Add Nix-based Development Environment and Documentation

README.md

@@ -87,6 +87,42 @@ Hello from Adder!
 [100%] Built target run_adder_iverilog
 ```
 
+## Dependency management
+
+Once you use more advanced SoCMake targets, e.g. simulation, etc., you will have dependency on some external tools. You are free to choose how you provide all the dependencies required for your project. However, to simplify this task, a Nix-based workflow is available using the provided `flake.nix` file.
+
+### Using Nix for a Reproducible Environment
+
+Nix allows you to create a fully reproducible development environment with all necessary tools and dependencies pre-installed.
+
+To use the Nix flow:
+
+1. **Install Nix**
+
+Follow the instructions at https://nixos.org/download.html to install the Nix package manager on your system.
+For more advanced Nix installation scenarios, check the guide at [Nix Installation Guide](https://nixos.wiki/wiki/Nix_Installation_Guide#Single-user_install).
+ You can also download a statically linked *nix* binary, useful e.g. in HPC environments: [Static Nix Binary](https://discourse.nixos.org/t/where-can-i-get-a-statically-built-nix/34253/15).
+
+2. **Enter the development environment**
+
+In the project directory (where `flake.nix` is located), run:
+
+```shell
+$ nix --experimental-features 'nix-command flakes' develop
+```
+
+As you can see, we use [Nix flakes](https://nixos.wiki/wiki/Flakes). Nix Flakes can be enabled permanently in the configuration file ([link](https://nixos.wiki/wiki/Flakes)), and then the command is simple:
+
+```shell
+$ nix develop
+```
+
+3. **Start working**
+
+You will be dropped into a shell with all required tools (such as `cmake`, `peakrdl`, `verible`, `verilator`, etc.) available and ready to use.
+
+This approach ensures that everyone working on the project uses the same versions of all dependencies, making builds and development more reliable and reproducible.
+
 Examples
 --------
 

flake.nix

@@ -0,0 +1,59 @@
+{
+  description = "SoCMake environment";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/02263f46911178e286242786fd6ea1d229583fbb";
+    nixpkgs_cmake_3_25.url = "github:NixOS/nixpkgs/nixos-23.05";
+    flake-utils.url = "github:numtide/flake-utils";
+
+    peakrdl-socgen.url = "github:HEP-SoC/PeakRDL-socgen?ref=refs/tags/v0.1.7";
+    peakrdl-socgen.inputs.nixpkgs.follows = "nixpkgs";
+  };
+
+  outputs = { self, nixpkgs, nixpkgs_cmake_3_25, flake-utils, peakrdl-socgen } :
+    flake-utils.lib.eachDefaultSystem (system:
+      let
+        overlays = [
+          (self: super: {
+            sv-lang = super.sv-lang.overrideAttrs (old: {
+              version = "10.0";
+              src = super.fetchFromGitHub {
+                owner = "MikePopoloski";
+                repo = "slang";
+                tag = "v10.0";
+                hash = "sha256-rw+DztENuY+DiAhQR2oNN/dQJzrcP5neF3LoWnqri+c=";
+              };
+            });
+          })
+        ];
+
+        pkgs = import nixpkgs { inherit system overlays; };
+        pkgs_cmake_3_25 = nixpkgs_cmake_3_25.legacyPackages.${system};
+        python = pkgs.python3;
+
+        pythonDeps = ps: [
+          peakrdl-socgen.packages.${system}.default
+          ps.peakrdl-regblock
+        ];
+
+        deps = with pkgs; [
+          pkgs_cmake_3_25.cmake
+          gnumake
+          sv-lang
+          verible
+          verilator
+        ];
+
+      in {
+        inherit pythonDeps deps;
+
+        devShells.default = pkgs.mkShell {
+          name = "socmake-shell";
+          packages = deps ++ [ (python.withPackages pythonDeps) ];
+          shellHook = ''
+            echo "❄️  SoCMake environment loaded (cmake, verible, verilator, peakrdl)"
+          '';
+        };
+      }
+    );
+}