README.md

hdx

hdx packages Amaranth (+ -boards, -stdio) and Yosys on Nix. These are already available in nixpkgs, but hdx also lets you use on-disk checkouts for Amaranth and/or Yosys. This lets you test your own changes (or debug crashes) in the context of your own project on Nix.

It also ships with Rain, a small framework for building projects with Amaranth. A Rain project also has a devShell for using an on-disk Yosys checkout. (Planned: Amaranth also, depending on how much work it is to get two editable checkouts at once.)

Usage

• nix develop github:charlottia/hdx

  This is the default mode of operation. Yosys and Amaranth are built and added to PATH.

  Amaranth is configured to use the Yosys built by hdx, and not its built-in one.

• nix develop github:charlottia/hdx#amaranth

  An Amaranth checkout in ./ or ./amaranth/ is expected, and installed in editable mode. Yosys is still built, added to PATH, and used by your Amaranth checkout as usual.

• nix develop github:charlottia/hdx#amaranth-yosys

  An Amaranth checkout is expected at ./amaranth/, and a Yosys checkout is expected at ./yosys. Amaranth is installed in editable mode. Yosys is configured to be compiled and installed to ./yosys/hdx-out/, and PATH has the output directory's bin subdirectory prepended. You'll need to actually make install Yosys at least once for this mode to function, including any use of Amaranth that depends on Yosys.

• Your project's flake.nix

  {
    inputs.hdx.url = github:charlottia/hdx;
  
    outputs = {
      self,
      nixpkgs,
      flake-utils,
      hdx,
    }:
      flake-utils.lib.eachDefaultSystem (system: let
        pkgs = nixpkgs.legacyPackages.${system};
      in {
        devShells.default = pkgs.mkShell {
          nativeBuildInputs = [
            hdx.packages.${system}.default
          ];
        };
      });
  }

  • Want to specify a different version of a dependency? WE HAVE A TOOL FOR THAT:

    inputs = {
      hdx.url = github:charlottia/hdx;
      hdx.inputs.amaranth.url = git+https://codeberg.org/lilnyonker/amaranth?ref=my-feature-branch;
    };

Rain

To get started, you can use the included flake template:

mkdir nyonkomatic
cd nyonkomatic
nix flake init -t github:charlottia/hdx#rainhdx

Then you can enter a development environment with nix develop. Try python -m proj to see what the default CLI options are.

If you want to use your own on-disk checkout of Yosys with your Rain project, nix develop .#yosys will expect a Yosys checkout at ./yosys or ../yosys.

Background

hdx originally reproduced the entire setup described in Installing an HDL toolchain from source in Nix, and mostly served as a way for me to learn Nix. It's since been refined in its scope.