Skip to content

Commit d47e751

Browse files
Copilotavik-pal
Copilot
and
avik-pal
authored
Add GitHub Copilot instructions (#1939)
* Initial plan * Add GitHub Copilot instructions for the repository Co-authored-by: avik-pal <30564094+avik-pal@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: avik-pal <30564094+avik-pal@users.noreply.github.com>
1 parent 6610cb2 commit d47e751

File tree

1 file changed

+216
-0
lines changed

1 file changed

+216
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
# GitHub Copilot Instructions for Reactant.jl
2+
3+
## Project Overview
4+
5+
Reactant.jl is a Julia package that compiles Julia functions into MLIR (Multi-Level Intermediate Representation) and runs advanced optimizations, including automatic differentiation with EnzymeMLIR, to create executables for CPU/GPU/TPU via XLA. It operates as a tracing system for high-performance computing.
6+
7+
## Language and Code Style
8+
9+
### Julia Code
10+
- **Language**: Julia 1.10+
11+
- **Code Style**: Use [Blue style](https://github.com/JuliaDiff/BlueStyle) as enforced by JuliaFormatter
12+
- **Formatter Config**: See `.JuliaFormatter.toml` with `style = "blue"` and `always_use_return = true`
13+
- **Type Stability**: Maintain type stability for performance-critical code
14+
- **Broadcasting**: Prefer Julia's dot notation for array operations (e.g., `sin.(x) .+ y`)
15+
- **Naming Conventions**: Use descriptive names; types are CamelCase, functions and variables are snake_case
16+
17+
### C++ Code
18+
- **Style**: LLVM style as specified in `.clang-format`
19+
- **Location**: C++ code lives in `deps/ReactantExtra/`
20+
- **Build System**: Bazel is used for building C++ components
21+
22+
## Project Structure
23+
24+
```
25+
├── src/ # Main Julia source code
26+
│ ├── Reactant.jl # Main module file
27+
│ ├── TracedRArray.jl, ConcreteRArray.jl # Core array types
28+
│ ├── Compiler.jl # Compilation infrastructure
29+
│ ├── Enzyme.jl # Automatic differentiation integration
30+
│ ├── mlir/ # MLIR bindings and utilities
31+
│ └── xla/ # XLA integration
32+
├── ext/ # Package extensions (conditional loading)
33+
├── lib/ # Sub-packages
34+
│ └── ReactantCore/ # Core functionality
35+
├── deps/ # Build dependencies and C++ code
36+
│ └── ReactantExtra/ # C++ API and Bazel build files
37+
├── test/ # Test suite
38+
│ ├── runtests.jl # Main test runner
39+
│ ├── integration/ # Integration tests
40+
│ └── nn/ # Neural network tests
41+
└── docs/ # Documentation
42+
```
43+
44+
## Core Concepts
45+
46+
### Array Types
47+
- **ConcreteRArray**: Underlying buffer for device data (CPU/GPU/TPU)
48+
- **TracedRArray**: Traced version used during compilation (no access to actual values)
49+
- Conversion: Use `Reactant.to_rarray()` to convert Julia arrays to RArrays
50+
51+
### Compilation
52+
- Use `@compile` macro to compile functions
53+
- Compiled functions capture control flow at compile time
54+
- Only ConcreteRArray updates are captured in compiled code
55+
56+
### Backends
57+
- Default backend can be set with `Reactant.set_default_backend("cpu"/"gpu"/"tpu")`
58+
- Supports CPU, GPU (CUDA), and TPU via XLA
59+
60+
## Testing
61+
62+
### Test Structure
63+
- **Framework**: Uses `SafeTestsets` and Julia's built-in `Test`
64+
- **Test Groups**: Tests are organized into three groups:
65+
- `core`: Basic functionality, tracing, compilation, autodiff
66+
- `neural_networks`: NNlib, Flux, LuxLib, Lux integration
67+
- `integration`: CUDA, KernelAbstractions, FFT, MPI, etc.
68+
- **Backend Testing**: Tests can run with different backends (CPU/GPU)
69+
- **Runtime Testing**: Tests run with both "pjrt" and "ifrt" runtimes
70+
71+
### Running Tests
72+
```bash
73+
# Run all tests
74+
julia --project=. test/runtests.jl
75+
76+
# Run specific test group
77+
REACTANT_TEST_GROUP=core julia --project=. test/runtests.jl
78+
79+
# Run with GPU backend
80+
REACTANT_BACKEND_GROUP=gpu julia --project=. test/runtests.jl
81+
```
82+
83+
### Writing Tests
84+
- Use `@safetestset` for isolated test environments
85+
- Follow existing patterns in test files
86+
- Test both forward and reverse-mode automatic differentiation where applicable
87+
- Include edge cases and type stability checks
88+
89+
## CI/CD
90+
91+
### Workflows
92+
- **CI**: Main test suite runs on Julia 1.10, 1.11 on multiple platforms (Ubuntu, macOS, Windows, ARM, TPU)
93+
- **Format Check**: Enforces Julia code style via JuliaFormatter
94+
- **Format Check (C++)**: Enforces LLVM style for C++ code via clang-format
95+
- **Format Check (Bazel)**: Enforces Bazel file formatting with buildifier
96+
- **Documentation**: Builds with Documenter.jl and DocumenterVitepress
97+
- **Benchmarks**: Performance tracking on push to main
98+
99+
### Continuous Integration
100+
- Tests run on push to `main` and `release-*` branches
101+
- PRs trigger CI on relevant file changes
102+
- Concurrency controls prevent redundant builds
103+
104+
## Dependencies and Extensions
105+
106+
### Core Dependencies
107+
- **EnzymeCore/Enzyme**: Automatic differentiation
108+
- **LLVM.jl**: LLVM integration
109+
- **Functors.jl**: Recursive structure traversal
110+
- **Adapt.jl**: Array type adaptation
111+
112+
### Package Extensions
113+
Reactant uses Julia's package extensions for optional integrations:
114+
- CUDA, KernelAbstractions for GPU computing
115+
- NNlib for neural network primitives
116+
- Zygote for alternative AD (Julia < 1.12)
117+
- MPI for distributed computing
118+
- AbstractFFTs, SpecialFunctions, etc.
119+
120+
### Adding Dependencies
121+
- Update `Project.toml` [deps] for required dependencies
122+
- Add to [weakdeps] and create extension in `ext/` for optional dependencies
123+
- Specify version bounds in [compat] section
124+
125+
## Development Workflow
126+
127+
### Setting Up Development Environment
128+
```bash
129+
# Clone the repository
130+
git clone https://github.com/EnzymeAD/Reactant.jl.git
131+
cd Reactant.jl
132+
133+
# Install dependencies
134+
julia --project=. -e 'using Pkg; Pkg.instantiate()'
135+
136+
# Build (if needed)
137+
julia --project=. deps/build_local.jl
138+
```
139+
140+
### Code Formatting
141+
```bash
142+
# Format Julia code
143+
julia --project=. -e 'using JuliaFormatter; format(".")'
144+
145+
# Format C++ code (requires clang-format)
146+
find deps/ReactantExtra -name "*.cpp" -o -name "*.h" | xargs clang-format -i
147+
148+
# Format Bazel files (requires buildifier)
149+
buildifier -r deps/ReactantExtra/
150+
```
151+
152+
### Documentation
153+
- Documentation is built with Documenter.jl and DocumenterVitepress
154+
- Docstrings should follow Julia conventions
155+
- Run `julia --project=docs docs/make.jl` to build locally
156+
157+
## Best Practices
158+
159+
### Performance
160+
- Minimize allocations in hot loops
161+
- Use `@inbounds` carefully when bounds are guaranteed
162+
- Prefer type-stable code; avoid type unions and `Any`
163+
- Use `@compile` to generate optimized executables for production code
164+
165+
### Automatic Differentiation
166+
- Test both forward and reverse mode when adding new operations
167+
- Ensure proper handling of mutation and aliasing
168+
- Use EnzymeCore for defining custom derivatives when needed
169+
170+
### MLIR/XLA Integration
171+
- MLIR operations are in `src/mlir/` and follow Dialect conventions
172+
- XLA integration code is in `src/xla/`
173+
- C++ API changes require updating Bazel build files and Julia bindings
174+
175+
### Error Handling
176+
- Provide informative error messages
177+
- Use Julia's exception system appropriately
178+
- Document expected failure modes in docstrings
179+
180+
### Compatibility
181+
- Maintain compatibility with Julia 1.10+
182+
- Follow [ColPrac](https://github.com/SciML/ColPrac) guidelines
183+
- Keep dependencies up-to-date via Dependabot
184+
185+
## Common Tasks
186+
187+
### Adding a New Operation
188+
1. Implement the Julia function in appropriate file in `src/`
189+
2. Add tracing support if needed in `src/Tracing.jl`
190+
3. Add tests in `test/ops.jl` or appropriate test file
191+
4. Add documentation if it's a public API
192+
5. Format code with JuliaFormatter
193+
194+
### Adding a New Test
195+
1. Create test file in `test/` (or appropriate subdirectory)
196+
2. Add to `test/runtests.jl` with `@safetestset`
197+
3. Group appropriately (core/integration/neural_networks)
198+
4. Run tests locally before submitting PR
199+
200+
### Updating MLIR Bindings
201+
1. Modify `deps/ReactantExtra/API.cpp` if needed
202+
2. Update Bazel BUILD files
203+
3. Run regeneration workflow or script
204+
4. Test thoroughly with existing test suite
205+
206+
## Resources
207+
208+
- [Documentation](https://enzymead.github.io/Reactant.jl/dev)
209+
- [Issue Tracker](https://github.com/EnzymeAD/Reactant.jl/issues)
210+
- [Contributing Guide](https://github.com/SciML/ColPrac)
211+
- [Enzyme Documentation](https://enzyme.mit.edu/)
212+
- [XLA Documentation](https://www.tensorflow.org/xla)
213+
214+
## Questions?
215+
216+
For questions or clarifications, open an issue or discussion on GitHub. The maintainers actively monitor the repository and are happy to help!

0 commit comments

Comments
 (0)