HACKING.md

Hacking on Bashcov

Nix flake usage

This project supplies a flake.nix file defining a Nix flake¹ that makes it possible to build, test, run, and hack on Bashcov using the Nix package manager

This Nix flake defines three important important outputs:

1. A Nix package for Bashcov,
2. A Nix flake check (test) that runs Bashcov's unit and feature tests,
3. A Nix application,² and
4. A Nix development shell,³.

In order to work on the Bashcov project's Nix features, you'll need to install the Nix package manager and ensure that the flakes and nix-command experimental features are enabled.

Building the Bashcov package

To build the Bashcov package exposed by this flake, run the following command:⁴

$ nix build -L '.#'

Or:

$ nix build -L '.#bashcov'

These two forms are functionally equivalent because the Bashcov package is the default package.

In addition to building the package, nix build will place a symbolic link to its output path at ./result (ls -lAR ./result/, tree ./result/, or similar to see what the package contains).

Nix flake checks

This project includes a test of Bashcov's functionality and features, exposed as a Nix flake check. In essence, this runs the Bashcov test suite, but inside the Nix build environment⁵ (which may be sandboxed⁶).

This project also includes a test that Nix source files are properly formatted.⁷

Running Nix flake checks

To run Nix flake checks, execute the following command:⁴

$ nix flake check -L

If a check fails, nix will print a diagnostic message and exit with nonzero status.

Running a check for a specific system

Running nix flake check will execute Nix flake checks for all supported systems.⁸ To run a check for a particular system, instead use the nix build command. For instance, to execute the Bashcov unit and feature tests with Nix on the x86_64-linux system, run:⁴

$ nix build -L '.#checks.x86_64-linux.bashcov'

Running the Nix application

To run Bashcov itself:

$ nix run '.#' -- <args>

To run commands from the Nix development shell but without entering the shell:

$ nix run '.#devshell' -- <command> <args>

For instance, to run the update-deps shell command:

$ nix run '.#devshell' -- update-deps

Entering the Nix development shell

To enter the Nix development shell, run the following command:

$ nix develop

You will be presented with a menu of commands available within the development shell.

Summary of available commands

• fmt: format all Nix code in this project using alejandra.
• bundix: tool for managing Nix <=> Ruby integration assets (Bundix lives here).
• update-deps: update the Nix-specific lockfile and Nix gemset.
• update-deps-conservative: update the Nix-specific lockfile and Nix gemset if (and only if) nix build fails without updates to those assets and nix build succeeds with updates to them.

Maintenance of Nix assets

The Bashcov Nix package depends on nixpkgs's Ruby integration; specifically, it uses the bundlerEnv function to create an environment with all of Bashcov's Ruby gem dependencies present. bundlerEnv requires a Bundler lockfile (here, Gemfile.nix.lock) and a Nix-specific gemset.nix that acts as a sort of translation layer between Bundler and Nix.

Both of these files must be updated from time to time in order to reflect changes in bashcov.gemspec, including certain changes to Bashcov itself (e.g. version bumps).

Note If bashcov.gemspec is updated without updating the Bundler lockfile and gemset.nix, the Bashcov Nix package will fail to build.

The Nix development shell includes two convenience commands for managing these assets:

• update-deps unconditionally updates Gemfile.nix.lock with bundle lock, then updates gemset.nix to reflect any changes to the Bundler lockfile.
• update-deps-conservative does the same, but if (and only if) doing so fixes failures running nix build. That is, it updates the assets if it looks like problems with those assets have broken the Bashcov Nix package.

Footnotes

1. See the NixOS wiki and the nix flake page in the Nix package manager reference manual for background on Nix flakes. ↩

2. Runnable with nix run. ↩

3. Based on the numtide/devshell project. ↩

4. Note that the -L flag can be omitted for terser output. ↩ ↩² ↩³

5. The Nix build environment is described here. ↩

6. The Nix sandbox is described here. ↩

7. Defined by treefmt-nix. ↩

8. Run nix flake show to view flake outputs namespaced by all supported systems. ↩