1# Contributing to rustc_codegen_gcc23Welcome to the `rustc_codegen_gcc` project! This guide will help you get started as a contributor. The project aims to provide a GCC codegen backend for rustc, allowing Rust compilation on platforms unsupported by LLVM and potentially improving runtime performance through GCC's optimizations.45## Getting Started67### Setting Up Your Development Environment89For detailed setup instructions including dependencies, build steps, and initial testing, please refer to our [README](Readme.md). The README contains the most up-to-date information on:1011- Required dependencies and system packages12- Repository setup and configuration13- Build process14- Basic test verification1516Once you've completed the setup process outlined in the README, you can proceed with the contributor-specific information below.1718## Communication Channels1920- Matrix: Join our [Matrix channel](https://matrix.to/#/#rustc_codegen_gcc:matrix.org)21- IRC: Join us on [IRC](https://web.libera.chat/#rustc_codegen_gcc)22- [GitHub Issues](https://github.com/rust-lang/rustc_codegen_gcc/issues): For bug reports and feature discussions2324We encourage new contributors to join our communication channels and introduce themselves. Feel free to ask questions about where to start or discuss potential contributions.2526## Understanding Core Concepts2728### Sysroot & compilation flags2930#### What *is* the sysroot?31The **sysroot** is the directory that stores the compiled standard32library (`core`, `alloc`, `std`, `test`, …) and compiler built-ins.33Rustup ships these libraries **pre-compiled with LLVM**.3435**rustc_codegen_gcc** replaces LLVM with the GCC backend.3637The freshly compiled sysroot ends up in38`build/build_sysroot/...`.3940A rebuild of sysroot is needed when4142* the backend changes in a way that affects code generation, or43* the user switches toolchains / updates submodules.4445Both backend and sysroot can be built using different [profiles](https://doc.rust-lang.org/cargo/reference/profiles.html#default-profiles).46That is exactly what the `--sysroot`, `--release-sysroot` and `--release` flag supported by the build system script `y.sh` take care of.474849#### Typical flag combinations5051| Command                                   | Backend Profile               | Sysroot Profile                  | Usage Scenario                                              |52|--------------------------------------------|-------------------------------|----------------------------------|------------------------------------------------------------|53| `./y.sh build`                            | &nbsp;dev*                          | &nbsp;n/a                                | &nbsp;Build backend in dev mode with optimized dependencies without rebuilding sysroot                |54| `./y.sh build --release`                  | &nbsp;release (optimized)           | &nbsp;n/a                                | &nbsp;Build backend in release mode with optimized dependencies without rebuilding sysroot                 |55| `./y.sh build --release --sysroot`        | &nbsp;release (optimized)           | &nbsp;dev                          | &nbsp;Build backend in release mode with optimized dependencies and sysroot in dev mode (unoptimized)              |56| `./y.sh build --sysroot`                  | &nbsp;dev*                          | &nbsp;dev                          | &nbsp;Build backend in dev mode with optimized dependencies and sysroot in dev mode (unoptimized)              |57| `./y.sh build --release-sysroot --sysroot`| &nbsp;dev*                          | &nbsp;release (optimized)              | &nbsp;Build backend in dev mode and sysroot in release mode, both with optimized dependencies             |5859\* In `dev` mode, dependencies are compiled with optimizations, while the code of the backend itself is not.606162Note: `--release-sysroot` must be used together with `--sysroot`.636465### Common Development Tasks6667#### Running Specific Tests6869To run specific tests, use appropriate flags such as:7071- `./y.sh test --test-libcore`72- `./y.sh test --std-tests`73- `./y.sh test --cargo-tests -- <name of test>`7475Additionally, you can run the tests of `libgccjit`:7677```bash78# libgccjit tests79cd gcc-build/gcc80make check-jit81# For a specific test:82make check-jit RUNTESTFLAGS="-v -v -v jit.exp=jit.dg/test-asm.cc"83```8485#### Debugging Tools8687The project provides several environment variables for debugging:8889- `CG_GCCJIT_DUMP_GIMPLE`: Dumps the GIMPLE IR90- `CG_RUSTFLAGS`: Additional Rust flags91- `CG_GCCJIT_DUMP_MODULE`: Dumps a specific module92- `CG_GCCJIT_DUMP_TO_FILE`: Creates C-like representation9394Full list of debugging options can be found in the [README](Readme.md#env-vars).9596## Making Contributions9798### Finding Issues to Work On991001. Look for issues labeled with [`good first issue`](https://github.com/rust-lang/rustc_codegen_gcc/issues?q=is%3Aissue%20state%3Aopen%20label%3A"good%20first%20issue") or [`help wanted`](https://github.com/rust-lang/rustc_codegen_gcc/issues?q=is%3Aissue%20state%3Aopen%20label%3A"help%20wanted")1012. Check the [progress report](https://blog.antoyo.xyz/rustc_codegen_gcc-progress-report-34#state_of_rustc_codegen_gcc) for larger initiatives1023. Consider improving documentation or investigating [failing tests](https://github.com/rust-lang/rustc_codegen_gcc/tree/master/tests) (except `failing-ui-tests12.txt`)103104### Pull Request Process1051061. Fork the repository and create a new branch1072. Make your changes with clear commit messages1083. Add tests for new functionality1094. Update documentation as needed1105. Submit a PR with a description of your changes111112### Code Style Guidelines113114- Follow Rust standard coding conventions115- Ensure your code passes `rustfmt` and `clippy`116- Add comments explaining complex logic, especially in GCC interface code117118## Additional Resources119120- [Rustc Dev Guide](https://rustc-dev-guide.rust-lang.org/)121- [GCC Internals Documentation](https://gcc.gnu.org/onlinedocs/gccint/)122- Project-specific documentation in the `doc/` directory:123  - [Common errors](doc/errors.md)124  - [Debugging](doc/debugging.md)125  - [Debugging libgccjit](doc/debugging-libgccjit.md)126  - [Git subtree sync](doc/subtree.md)127  - [List of useful commands](doc/tips.md)128  - [Send a patch to GCC](doc/sending-gcc-patch.md)129130## Getting Help131132If you're stuck or unsure about anything:1331. Check the existing documentation in the `doc/` directory1342. Ask in the IRC or Matrix channels1353. Open a GitHub issue for technical problems1364. Comment on the issue you're working on if you need guidance137138Remember that all contributions, including documentation improvements, bug reports, and feature requests, are valuable to the project.