Add Nix-based Development Environment and Documentation

[adrianf0]

As we agree, SoCMake should not take care of installing any software dependencies and should fetch only the project's IPs.

The user is completely free to choose how he/she provides all the dependencies required for the project. However, to simplify this task, this pull request introduces a reproducible development environment for SoCMake using flake.nix, and updates the README.md with detailed instructions for dependency management.

Summary of changes

• Added a flake.nix file that defines a Nix development shell with all required tools and dependencies (e.g. cmake, verible, verilator, peakrdl, etc.).
• Updated the README.md to include a new section on dependency management, describing how to use the provided flake.nix for a consistent and reproducible development environment.

Additional notes

• The Nix-based workflow is optional and does not interfere with other ways of managing dependencies.
• The documentation provides step-by-step instructions and useful links for installing and using Nix.
• This approach ensures that all contributors can easily set up a consistent development environment, improving reliability and reproducibility.

[benoitdenkinger]

Which versions of these dependencies are installed?

[adrianf0]

The Nix flake pins all dependencies to a specific nixpkgs commit defined by this line:

  nixpkgs.url = "github:NixOS/nixpkgs/02263f46911178e286242786fd6ea1d229583fbb";

This means everyone using this flake will get the exact same versions of all packages, regardless of when or where they build.

Unlike traditional package managers, installing the same software on different operating systems (e.g., using apt, yum, brew, or pacman) does not guarantee identical results. OS package maintainers can apply different patches, build options, or even backport features and bugfixes, so the "same" package name and version might behave differently across distributions.
With Nix, the build recipes and sources are pinned and shared, so the environment is truly reproducible across all supported systems.

How to check the versions

1. With Nix installed

You can check the version of each dependency using this command pattern:

nix eval --inputs-from . nixpkgs#<package>.version

For your specific dependencies question, run:

nix eval --inputs-from . nixpkgs#cmake.version
nix eval --inputs-from . nixpkgs#gnumake.version
nix eval --inputs-from . nixpkgs#verible.version
nix eval --inputs-from . nixpkgs#verilator.version

Alternatively, you can enter the development shell and check versions interactively:

nix develop

Then, inside the shell:

cmake --version
make --version
verible-verilog-lint --version
verilator --version

2. Without Nix installed

If you do not have Nix installed, you can still check the versions by looking them up in the Nixpkgs repository at the pinned commit:

1. Go to the Nixpkgs GitHub repository at the specific commit:

   https://github.com/NixOS/nixpkgs/tree/02263f46911178e286242786fd6ea1d229583fbb
   

2. Use the GitHub search bar to search for each package (e.g., cmake).
3. Open the relevant package.nix file for the package.
4. Look for the version field.

What are the actual versions?

As of the pinned commit, these are the versions you will get:

• cmake: 4.1.2
• gnumake: 4.4.1
• verible: 0.0.4023
• verilator: 5.044

[Risto97]

I tried it an it works for me.

But I am a bit unsure how should this be used within SoCMake context.
I could see it if it viable if it only included the mandatory dependencies (cmake, make/ninja, jq), not that many dependencies though.

But when it comes to simulators, and other tools, it feels more like its a project specific thing.
Could a user in an easy way use the flake from SoCMake, and add their additional tools in their nix environment?
I don't feel like its a good idea to force verible, peakrdl-socgen, verilator if they are not mandatory.

On the other hand.
Sometimes the open source projects like OpenROAD distribute a docker image with all the tools preinstalled.
This to me seems like an alternative approach to that.

[mtravaillard]

I share Risto opinion. I also think it that it can be useful in projects to have Nix from what I saw, but maybe it should be in a project repository and not in SoCMake repository directly ? As most of the dependencies are related to the tools used in a project.

Otherwise, I think it should be merged to develop and not master, we synchronized the 2 branches with the goal of keeping master clean for now, until we merge from develop to it, especially for a stable release soon.

[adrianf0]

I tried it an it works for me.

@Risto97 Thank you for your feedback and for testing the flake.nix!

Context

The flake.nix is optional and intended as a convenience for contributors and users who want a reproducible development environment.

It is not mandatory and does not interfere with other ways of managing dependencies.

The Nix-based workflow is similar to distributing a Docker image, but offers more flexibility and composability.

Scope of included tools

Currently, flake.nix includes only open-source tools that are directly supported and referenced by SoCMake sources, such as verible, peakrdl, verilator, and vhier.

While the only mandatory dependencies for SoCMake are cmake and gnumake (or ninja), the flake also includes tools that are used internally by SoCMake depending on the target.
The selection is guided by SoCMake's source code and official examples, not by external or proprietary dependencies.

Customization and extensibility

Nix flakes are composable and extensible.

Users can easily extend the SoCMake flake in their own project to add or remove tools as needed.

Example: Extending SoCMake's flake to add project-specific tools

{
  inputs.socmake.url = "github:HEP-SoC/SoCMake";
  outputs = { self, socmake, nixpkgs}:
    let
      system = "x86_64-linux";
      pkgs = import nixpkgs { inherit system; };
    in {
      devShells.default = pkgs.mkShell {
        packages = socmake.outputs.deps.${system} ++ [
          pkgs.myExtraTool
        ];
      };
    };
}

This allows users to reuse the base environment and customize it for their specific needs.

[adrianf0]

Otherwise, I think it should be merged to develop and not master, we synchronized the 2 branches with the goal of keeping master clean for now, until we merge from develop to it, especially for a stable release soon.

As far as I know, the develop branch addresses different aspects of the project.

The flake.nix and flake.lock files are, to my knowledge, completely unrelated to the ongoing development in develop.

It should be very easy for developers working on the develop branch to merge these two files, as they are isolated and do not interfere with other parts of the codebase.

This should help keep the workflow smooth and avoid unnecessary merge conflicts.

[benoitdenkinger]

I'm also not so sure which tools and versions we should set up by default. I'm not familiar with Nix environment setup yet, so I don't fully understand how complex it is to change the version of certain tools. According to @adrianf0's comment, it seems to be simple once you are familiar with Nix. I would merge this into master and see how it goes over time, we can always change it later.

My only real concern is the CMake version. The minimum version is set to 3.25 on master (3.27 on develop), while here we install 4.1.2. If we start using Nix and develop SoCMake with 4.1.2, we might lose backward compatibility with version 3.25/27. For now, I would set the cmake version to 3.25.

[adrianf0]

For now, I would set the cmake version to 3.25.

@benoitdenkinger : The nix development environment now uses cmake version 3.25.3, following your request.

[benoitdenkinger]

I realize now also some python packages are installed. I was already not convinced about installing some other dependencies, like the simulators, for the reasons mentioned by @Risto97, these are project specific. The same for these python plugins, I don't see the point of setting them here instead of inside a specific project.

Let's keep it simple:
cmake
gnumake
jq
python310

Or any other core/basic dependency if I missed any, but nothing else. Then, everything else goes into each specific project.

[adrianf0]

@benoitdenkinger: Thanks for the feedback.

Why SoCMake's flake.nix should include its own tool dependencies

The tools included in flake.nix (e.g. peakrdl-socgen, verible, verilator, etc.) are not arbitrary project-specific choices, but are directly invoked by SoCMake's own CMake functions and modules (see: socgen, verilator, etc.)
If a user or CI wants to run SoCMake's own tests, examples, or use all its features, these tools must be present.
Providing a flake.nix that includes all tools required by SoCMake itself ensures:

• Out-of-the-box reproducibility for contributors and CI.
• All features and examples work without extra manual setup.
• The environment is composable: downstream projects can extend or override as needed.

Use of Nix is always optional

• Using Nix is entirely optional for SoCMake users.
• The flake.nix is provided as a convenience for those who want a reproducible, ready-to-use environment.
• Users who prefer other workflows or dependency management approaches are not forced to use Nix at all.

User experience: lowering the barrier to entry

With the current flake.nix, people who want to try SoCMake and run, for example, a simulation of the SoC using open-source tools, do not need to know anything about Nix itself.
They simply run nix develop and get an environment with all the required tools.
It would not make sense to require new users to extend flake.nix and add packages themselves (which would mean searching for the right package names in the Nixpkgs archive, etc.) just to get a working SoCMake environment.

Summary

• SoCMake's flake.nix should provide all open-source tools it uses internally.
• This is not about forcing tools on users, but about ensuring SoCMake is reproducible and works out-of-the-box.
• Downstream projects remain free to customize their own environments as needed.
• Use of Nix is always optional and does not affect users who prefer other workflows.
• This approach is standard, maximizes usability, and avoids confusion for new contributors and CI.

[benoitdenkinger]

My point of view about Nix for SoCMake is that it can indeed become a very valuable tool to provide reproducible environments. However, we are still in an exploratory phase, and our current infrastructure does not rely on it. Because of that, I would strongly favor keeping things minimal at this stage to avoid prematurely committing to a workflow we may still revise.

The tools included in flake.nix (e.g. peakrdl-socgen, verible, verilator, etc.) are not arbitrary project-specific choices, but are directly invoked by SoCMake's own CMake functions and modules (see: socgen, verilator, etc.)The tools included in flake.nix (e.g. peakrdl-socgen, verible, verilator, etc.) are not arbitrary project-specific choices, but are directly invoked by SoCMake's own CMake functions and modules (see: socgen, verilator, etc.)

The tools themselves are indeed not arbitrary, but their exact versions should remain flexible (at least at the major version level).

Regarding tests and examples: I agree that Nix could be very useful to provide ready-to-use environments. That said, these are distinct use cases from the core goal of SoCMake (i.e. being used within a user’s project), and also distinct from each other. It would make more sense to handle them in dedicated, clearly scoped files rather than in a single, general-purpose one.

In short: I see the value, but I would keep the current integration minimal, avoid encoding too many assumptions, and revisit this once the Nix approach has proven stable and aligned with our workflow.

I'll now let others comment so we can make a final decision and move forward.

[mksoc]

Speaking from a project point of view, the deal breaker for me at the moment is that dependencies need to be defined twice, potentially with different versions. For instance, in a project using Nix one would have a certain version of SoCMake in the Nix flake (e.g. on the nix branch we have now) and possibly a different one in the CMake dependencies (installed with CPM). This is confusing and hard to maintain.

Moreover, yesterday @adrianf0 showed me how to update socgen for instance, and it's honestly a pain for tools that I consider under development (basically our whole PeakRDL toolchain). First of all you can't see the repository of the tool directly (it is in the Nix store), so if you need to work on a fix you need to clone locally and point your PYTHONPATH to use that. Then once you have the fix you need to update the Nix flakes (easy, but not documented here at the moment), potentially of multiple repositories depending where the specific tool is added. Compare this to having these packages installed in editable mode in a Python virtual environment, where it would require a one line change in requirements.txt.

While I see the convenience of having "system" dependencies defined in a single point, I think this should not be done on SoCMake. As we said some time ago, SoCMake should not provide dependencies. In my opinion, Nix should be one of several ways to provide dependencies, which should be at project top level. This is especially the case for SoCMake because in the end it's a collection of many different functions calling many different tools and I don't see the point in enforcing the end user to have all these tools installed, when maybe they will never need them. The tool dependency should go with the CMake function: if you don't need the function, you don't need the tool.

We could think of providing an example project repository, where there we use Nix to install a set of dependencies we define.

[Risto97]

I agree with the previous comments, I think Nix can be very useful but we are not using it for the right packages here.
The whole idea was to replace the build scripts, that were compiling systemc, systemc-uvm, scv, crave, sail, riscv-gcc, arm-gcc...
These things can be long and complicated to build from source, and it would be valuable to have a way to fetch the binaries for without relying on package manager of the os.

I see that some already exist, and compilers of course:
https://search.nixos.org/packages?channel=25.11&query=systemc&show=systemc
https://search.nixos.org/packages?channel=25.11&query=sail&show=sail-riscv

But someone needs to maintain these packages, its not add and forget.

When it comes to python packages, I really don't see myself using this over uv or pip.
As it is this simple to do it:

uv venv
uv pip install git+git@github.com:HEP-SoC/PeakRDL-socgen.git@<tag>
# Or development
uv pip install -e /path-to-repo