Reproducible Environment with Nix

If you want to continue the work on the alloc crate, contribute to the project independently, or simply test the changes locally, setting up the GCCRS development environment can be tedious.

To eliminate this friction, I created a Nix flake that provides a fully reproducible and configured workspace. You can inspect the flake source in my fork here:

Quick Start

Clone the repository (Skip if you already have it):

git clone https://github.com/Rust-GCC/gccrs.git

Initialize the environment:

Option A (If you use direnv): Run the following command once. It configures gccrs, builds it, and triggers direnv so your environment is automatically loaded whenever you enter the directory.
```
echo 'use flake "github:nsvke/gccrs/gccrs-nix?dir=contrib/nix"' > .envrc
direnv allow
gccrs-setup
```

Option B (Manual approach): If you don’t use direnv, you must manually enter the Nix shell and run the setup script for your first time.
```
nix develop "github:nsvke/gccrs/gccrs-nix?dir=contrib/nix" -c gccrs-setup
```
Note: You will need to run the nix develop command every time you open a new terminal to load the environment. Thanks to Nix caching, subsequent loads are instantaneous.

Workspace Utilities

The Nix environment exposes several wrapper scripts designed to make compiler development smoother.

Note: These wrappers automatically resolve your project root and build directories. You can execute them from anywhere within your gccrs-workspace.

gccrs-setup: Configures the GCC build directory with well-thought-out defaults for gccrs development.

gccrs-build: Compiles the compiler. Pass –bear to automatically generate a compile_commands.json for your editor.

gccrs-test: Runs the Rust testsuite. Accepts DejaGnu arguments (e.g., gccrs-test compile.exp or gccrs-test execute.exp=my-test.rs).

gccrs-exec: Wraps the executables in build/gcc/ so you can call them directly (e.g., gccrs-exec crab1 my-test.rs).“

gccrs-git: A wrapper for git that resolves the repository root, allowing you to run git commands from outside the .git directory tree.

Changelog and Commit Tools

gccrs-mklog: Generates the GNU ChangeLog for your staged changes and prints it to stdout.

gccrs-commit-mklog: Generates the ChangeLog and directly injects it into your git commit template, ready for editing.

gccrs-verify: Validates your final commit message format against GCC’s strict commit guidelines before you open a PR.

Extra: You can use all commands with g prefix instead of the gccrs- prefix (e.g., gtest, gbuild).

If using direnv: Add --use-gprefix to your initial setup command (gccrs-setup --use-direnv --use-gprefix).
If using the manual approach: Append #gprefix to the flake target when entering the shell (nix develop "github:nsvke/gccrs/gccrs-nix?dir=contrib/nix#gprefix").

Note: In gprefix mode, the gccrs-exec command is named gx, not gexec.

Quick Reference

You can run gccrs-help (or ghelp) to see all available commands and their usages.

> gccrs-help
  gccrs-setup                   : Start from scratch (configures, builds).
  gccrs-setup --use-direnv      : Automatically setup direnv for your build folder.
  gccrs-setup --use-gprefix     : Use prefix as 'g' instead of 'gccrs-'.
  gccrs-build                   : Run incremental build (compiles only changes).
  gccrs-build --bear            : Incremental build and update compile_commands.json.
  gccrs-test <args...>          : Run gccrs testsuite.
  gccrs-test --build <args...>  : Build and run gccrs testsuite.
  gccrs-exec <binary> <args...> : Use built gccrs binaries.
  gccrs-git <args...>           : Use git within the gccrs source directory.

  gccrs-mklog                   : Generate ChangeLog template for STAGED files.
  gccrs-commit-mklog            : Generate ChangeLog and open Git commit editor.
  gccrs-verify                  : Verify your latest commit (HEAD) against GNU std.
  gccrs-verify <hash>           : Verify a specific commit in your history.
  gccrs-fix-changelog           : Attempt to fix minor format typos in HEAD.

  gccrs-style                   : Check GNU C++ style for modifications in HEAD.
  gccrs-style <hash>            : Check style for modifications in a specific commit.

Keyboard shortcuts