Skip to content

Commit 91235b0

Browse files
yesudeepyesudeep
committed
refactor(rules_dart): modularize
1 parent 1f5e89c commit 91235b0

File tree

8 files changed

+1384
-1
lines changed

8 files changed

+1384
-1
lines changed

‎bazel/rules_dart/CONTRIBUTING.md‎

Lines changed: 286 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,286 @@
1+
# Contributing to rules_dart
2+
3+
Thank you for your interest in contributing to `rules_dart`!
4+
5+
## Development Setup
6+
7+
1. Clone the repository:
8+
```bash
9+
git clone https://github.com/google/rules_dart.git
10+
cd rules_dart
11+
```
12+
13+
2. Run the tests:
14+
```bash
15+
# Unix (macOS/Linux)
16+
./scripts/test_examples.sh
17+
18+
# Windows
19+
scripts\test_examples.bat
20+
```
21+
22+
## Code Style
23+
24+
- Follow Starlark best practices
25+
- Use descriptive function and variable names
26+
- Add comprehensive docstrings to all public functions
27+
- Include ASCII diagrams for complex logic
28+
29+
## Package Organization
30+
31+
```
32+
rules_dart/
33+
├── defs.bzl # Public API - all user-facing rules
34+
├── extensions.bzl # Bzlmod extensions for SDK configuration
35+
├── repositories.bzl # SDK download and repository rules
36+
├── MODULE.bazel # Bzlmod module definition
37+
├── BUILD.bazel # Package definition
38+
│
39+
├── private/ # Internal implementation (NOT public API)
40+
│ ├── helpers.bzl # Common utilities (runfiles_path, is_windows, etc.)
41+
│ ├── windows.bzl # Windows .bat script generators
42+
│ └── unix.bzl # Unix .sh script generators
43+
│
44+
├── gazelle/ # Gazelle extension for BUILD file generation
45+
│ ├── dart_language.go # Language interface implementation
46+
│ ├── dart_generate.go # BUILD file generation logic
47+
│ └── dart_resolve.go # Dependency resolution
48+
│
49+
├── examples/ # Working examples for testing
50+
│ └── hello_world/ # Complete example project
51+
│
52+
└── scripts/ # CI and testing scripts
53+
├── test_examples.sh # Unix test runner
54+
└── test_examples.bat # Windows test runner
55+
```
56+
57+
### Key Files
58+
59+
| File | Purpose |
60+
|------|---------|
61+
| `defs.bzl` | Entry point for users - `load("@rules_dart//:defs.bzl", ...)` |
62+
| `repositories.bzl` | SDK version checksums and download logic |
63+
| `private/*.bzl` | Platform-specific script generation (internal) |
64+
65+
## Testing
66+
67+
### Local Testing
68+
69+
Run the full test suite locally:
70+
71+
```bash
72+
# Unix (macOS/Linux)
73+
./scripts/test_examples.sh
74+
75+
# Windows
76+
scripts\test_examples.bat
77+
```
78+
79+
The test scripts verify:
80+
1. ✅ All rules build successfully
81+
2. ✅ Compilation targets (native, js, wasm, aot) work
82+
3. ✅ Pub commands (get, publish) work
83+
4. ✅ Unit tests pass
84+
5. ✅ CI checks (format, analyze) pass
85+
6. ✅ Native binary executes correctly
86+
87+
### Testing in the hello_world Example
88+
89+
```bash
90+
cd examples/hello_world
91+
92+
# Build all targets
93+
bazel build //...
94+
95+
# Run tests
96+
bazel test //...
97+
98+
# Run specific targets
99+
bazel run //:hello_native
100+
bazel run //:hello_pub_get
101+
```
102+
103+
### CI Testing
104+
105+
CI runs tests on all platforms:
106+
107+
| Platform | Tested Architectures |
108+
|----------|---------------------|
109+
| Windows | x64 |
110+
| macOS | x64, arm64 |
111+
| Linux | x64, arm64 |
112+
113+
Make sure your changes pass on all platforms before submitting a PR.
114+
115+
116+
## Testing Requirements
117+
118+
All changes must:
119+
120+
1. **Pass on all platforms**: Windows, macOS, and Linux
121+
2. **Include tests**: Add test coverage for new rules
122+
3. **Update documentation**: Keep README.md and GEMINI.md current
123+
124+
### Test Scripts
125+
126+
Both Unix (.sh) and Windows (.bat) test scripts must exist and test the same functionality:
127+
128+
| Script | Platform |
129+
|--------|----------|
130+
| `scripts/test_examples.sh` | macOS, Linux |
131+
| `scripts/test_examples.bat` | Windows |
132+
133+
## Pull Request Process
134+
135+
1. Fork the repository
136+
2. Create a feature branch (`git checkout -b feat/my-feature`)
137+
3. Make your changes
138+
4. Run all tests on your platform
139+
5. Commit with a descriptive message following [Conventional Commits](https://www.conventionalcommits.org/):
140+
```
141+
feat(rules_dart): add dart_compile rule
142+
143+
Adds a new compilation rule for custom output formats.
144+
145+
- Supports all platforms
146+
- Includes comprehensive tests
147+
```
148+
6. Push to your fork and open a Pull Request
149+
150+
### PR Description Guidelines
151+
152+
Include in your PR description:
153+
154+
- **Summary**: What does this change do?
155+
- **Tables**: Feature support, test results
156+
- **Diagrams**: ASCII diagrams for architecture changes
157+
- **Test Results**: Platform-specific test outcomes
158+
159+
Example:
160+
161+
```markdown
162+
## Summary
163+
164+
Adds support for custom compilation targets.
165+
166+
## Changes
167+
168+
| Feature | Before | After |
169+
|---------|--------|-------|
170+
| dart_compile | ❌ | ✅ |
171+
172+
## Test Results
173+
174+
| Platform | Build | Tests |
175+
|----------|-------|-------|
176+
| macOS arm64 | ✅ | ✅ |
177+
| Linux x64 | ✅ | ✅ |
178+
| Windows x64 | ✅ | ✅ |
179+
```
180+
181+
## License
182+
183+
By contributing, you agree that your contributions will be licensed under the Apache 2.0 License.
184+
185+
## Adding a New Dart SDK Version
186+
187+
When a new Dart SDK is released, you can contribute support for it:
188+
189+
### 1. Get the Checksums
190+
191+
Download the SDK archives and compute SHA256 checksums:
192+
193+
```bash
194+
# For each platform (linux-x64, linux-arm64, macos-x64, macos-arm64, windows-x64)
195+
VERSION="3.8.0"
196+
197+
# Linux x64
198+
curl -L "https://storage.googleapis.com/dart-archive/channels/stable/release/${VERSION}/sdk/dartsdk-linux-x64-release.zip" -o dart-linux-x64.zip
199+
shasum -a 256 dart-linux-x64.zip
200+
201+
# Linux arm64
202+
curl -L "https://storage.googleapis.com/dart-archive/channels/stable/release/${VERSION}/sdk/dartsdk-linux-arm64-release.zip" -o dart-linux-arm64.zip
203+
shasum -a 256 dart-linux-arm64.zip
204+
205+
# macOS x64
206+
curl -L "https://storage.googleapis.com/dart-archive/channels/stable/release/${VERSION}/sdk/dartsdk-macos-x64-release.zip" -o dart-macos-x64.zip
207+
shasum -a 256 dart-macos-x64.zip
208+
209+
# macOS arm64
210+
curl -L "https://storage.googleapis.com/dart-archive/channels/stable/release/${VERSION}/sdk/dartsdk-macos-arm64-release.zip" -o dart-macos-arm64.zip
211+
shasum -a 256 dart-macos-arm64.zip
212+
213+
# Windows x64
214+
curl -L "https://storage.googleapis.com/dart-archive/channels/stable/release/${VERSION}/sdk/dartsdk-windows-x64-release.zip" -o dart-windows-x64.zip
215+
shasum -a 256 dart-windows-x64.zip
216+
```
217+
218+
Or use the official checksums from https://dart.dev/get-dart/archive.
219+
220+
### 2. Update repositories.bzl
221+
222+
Add the new version to `DART_SDK_VERSIONS`:
223+
224+
```python
225+
DART_SDK_VERSIONS = {
226+
# Existing versions...
227+
"3.7.0": { ... },
228+
229+
# Add new version
230+
"3.8.0": {
231+
"linux-x64": "sha256-CHECKSUM_HERE",
232+
"linux-arm64": "sha256-CHECKSUM_HERE",
233+
"macos-x64": "sha256-CHECKSUM_HERE",
234+
"macos-arm64": "sha256-CHECKSUM_HERE",
235+
"windows-x64": "sha256-CHECKSUM_HERE",
236+
},
237+
}
238+
```
239+
240+
### 3. Update Files
241+
242+
| File | Update |
243+
|------|--------|
244+
| `repositories.bzl` | Add checksums in `DART_SDK_VERSIONS` |
245+
| `extensions.bzl` | Update default version if this is the new stable |
246+
| `examples/*/MODULE.bazel` | Update example version references |
247+
| `README.md` | Update Quick Start version if needed |
248+
| `CHANGELOG.md` | Add entry for new SDK support |
249+
250+
### 4. Test
251+
252+
Run tests with the new SDK version:
253+
254+
```bash
255+
# Unix
256+
./scripts/test_examples.sh
257+
258+
# Windows
259+
scripts\test_examples.bat
260+
```
261+
262+
### 5. Submit PR
263+
264+
Use the commit format:
265+
266+
```
267+
feat(rules_dart): add Dart SDK 3.8.0 support
268+
269+
Adds checksums for Dart SDK 3.8.0 across all platforms.
270+
271+
- linux-x64
272+
- linux-arm64
273+
- macos-x64
274+
- macos-arm64
275+
- windows-x64
276+
```
277+
278+
## Getting Help
279+
280+
- Read [GEMINI.md](GEMINI.md) for development guidelines
281+
- File issues for bugs or feature requests
282+
- Ask questions in discussions
283+
284+
## Code of Conduct
285+
286+
This project follows Google's [Open Source Community Guidelines](https://opensource.google/conduct/).

‎bazel/rules_dart/GEMINI.md‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,11 @@ bazel/rules_dart/
9999
├── repositories.bzl # Repository rule for Dart SDK
100100
├── GEMINI.md # Development guidelines (this file)
101101
├── README.md # User documentation
102+
├── private/ # Internal implementation (not public API)
103+
│ ├── BUILD.bazel # Package definition
104+
│ ├── helpers.bzl # Common utility functions
105+
│ ├── windows.bzl # Windows script generators
106+
│ └── unix.bzl # Unix script generators
102107
├── gazelle/ # Gazelle extension for Dart
103108
│ ├── BUILD.bazel
104109
│ ├── go.mod
@@ -107,14 +112,41 @@ bazel/rules_dart/
107112
│ └── dart_resolve.go # Dependency resolution
108113
├── scripts/ # CI/testing scripts
109114
│ ├── test_examples.sh # Unix test script
110-
│ └── test_examples.bat # Windows test script
115+
│ └── test_examples.bat # Windows test script (REQUIRED)
111116
└── examples/ # Example projects
112117
└── hello_world/
113118
├── BUILD.bazel
114119
├── MODULE.bazel
115120
└── ...
116121
```
117122

123+
### Module Structure
124+
125+
```
126+
┌──────────────────────────────────────────────────────────────────────────┐
127+
│ Modular Architecture │
128+
├──────────────────────────────────────────────────────────────────────────┤
129+
│ │
130+
│ defs.bzl (Public API) │
131+
│ ├── Uses: private/helpers.bzl │
132+
│ │ private/windows.bzl │
133+
│ │ private/unix.bzl │
134+
│ │ │
135+
│ └── Exports: dart_library, dart_binary, dart_test, etc. │
136+
│ │
137+
│ private/helpers.bzl │
138+
│ └── runfiles_path(), is_windows(), relative_path(), to_windows_path() │
139+
│ │
140+
│ private/windows.bzl │
141+
│ └── generate_*_script() functions for .bat files │
142+
│ │
143+
│ private/unix.bzl │
144+
│ └── generate_*_script() functions for .sh files │
145+
│ │
146+
└──────────────────────────────────────────────────────────────────────────┘
147+
```
148+
149+
118150
## Development Principles
119151

120152
### 1. No Hardcoding

0 commit comments

Comments
 (0)