tools/nix: split flake into root and Documentation
Root flake now only contains dependencies needed for building the NuttX firmware. The Documentation flake contains the dependencies needed for running `make html`. Updated the documentation accordingly. Signed-off-by: Côme VINCENT <44554692+comejv@users.noreply.github.com>
This commit is contained in:
Côme VINCENT
Xiang Xiao
parent
61c8240458
commit
bd90132cd6
5 changed files with 233 additions and 35 deletions
27
Documentation/flake.lock
generated
Normal file
27
Documentation/flake.lock
generated
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
{
|
||||
"nodes": {
|
||||
"nixpkgs": {
|
||||
"locked": {
|
||||
"lastModified": 1754725699,
|
||||
"narHash": "sha256-iAcj9T/Y+3DBy2J0N+yF9XQQQ8IEb5swLFzs23CdP88=",
|
||||
"owner": "NixOS",
|
||||
"repo": "nixpkgs",
|
||||
"rev": "85dbfc7aaf52ecb755f87e577ddbe6dbbdbc1054",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "NixOS",
|
||||
"ref": "nixos-unstable",
|
||||
"repo": "nixpkgs",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"root": {
|
||||
"inputs": {
|
||||
"nixpkgs": "nixpkgs"
|
||||
}
|
||||
}
|
||||
},
|
||||
"root": "root",
|
||||
"version": 7
|
||||
}
|
||||
77
Documentation/flake.nix
Normal file
77
Documentation/flake.nix
Normal file
|
|
@ -0,0 +1,77 @@
|
|||
{
|
||||
description = "Sphinx documentation environment with sphinx-tags";
|
||||
|
||||
inputs = {
|
||||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
||||
};
|
||||
|
||||
outputs =
|
||||
{ self, nixpkgs }:
|
||||
let
|
||||
system = "x86_64-linux";
|
||||
pkgs = import nixpkgs { inherit system; };
|
||||
|
||||
python = pkgs.python313;
|
||||
|
||||
sphinx-tags = python.pkgs.buildPythonPackage rec {
|
||||
pname = "sphinx-tags";
|
||||
version = "0.4";
|
||||
|
||||
src = pkgs.fetchPypi {
|
||||
pname = "sphinx_tags";
|
||||
inherit version;
|
||||
sha256 = "MGUhm6z0dWfHBvIjfVZlsi86UWc2e0xFaLzaQ3GlNZ0=";
|
||||
};
|
||||
|
||||
pyproject = true;
|
||||
build-system = [ python.pkgs.flit-core ];
|
||||
|
||||
propagatedBuildInputs = with python.pkgs; [
|
||||
sphinx
|
||||
];
|
||||
|
||||
doCheck = false;
|
||||
};
|
||||
|
||||
sphinx-collapse = python.pkgs.buildPythonPackage rec {
|
||||
pname = "sphinx_collapse";
|
||||
version = "0.1.3";
|
||||
|
||||
src = pkgs.fetchPypi {
|
||||
inherit version pname;
|
||||
sha256 = "yuFB5vA+zVLtJGowWmnhsNXQXmzfP+gD1A1YOtatiVo=";
|
||||
};
|
||||
|
||||
pyproject = true;
|
||||
build-system = [ python.pkgs.flit-core ];
|
||||
|
||||
propagatedBuildInputs = with python.pkgs; [
|
||||
sphinx
|
||||
];
|
||||
|
||||
doCheck = false;
|
||||
};
|
||||
|
||||
nuttx-doc-py-env = python.withPackages (
|
||||
ps: with ps; [
|
||||
sphinx
|
||||
sphinx_rtd_theme
|
||||
myst-parser
|
||||
sphinx-tabs
|
||||
sphinx-autobuild
|
||||
sphinx-copybutton
|
||||
sphinx-togglebutton
|
||||
pytz
|
||||
importlib-metadata
|
||||
sphinx-design
|
||||
sphinx-tags
|
||||
sphinx-collapse
|
||||
]
|
||||
);
|
||||
in
|
||||
{
|
||||
devShells.${system}.default = pkgs.mkShell {
|
||||
buildInputs = [ nuttx-doc-py-env ];
|
||||
};
|
||||
};
|
||||
}
|
||||
|
|
@ -2,18 +2,23 @@
|
|||
Nix Flake for Reproducible Development
|
||||
======================================
|
||||
|
||||
This guide explains how to use the Nix flake to set up a reproducible development environment for NuttX. The Nix flake ensures that all required build tools and dependencies are consistently available, simplifying onboarding and reducing "works on my machine" issues.
|
||||
This guide explains how to use the Nix flake to set up a reproducible
|
||||
development environment for NuttX. The Nix flake ensures that all required
|
||||
build tools and dependencies are consistently available, simplifying
|
||||
onboarding and reducing "works on my machine" issues.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
* `Nix <https://nixos.org/download/>`_ installed on your system.
|
||||
* Nix flakes enabled (add ``experimental-features = nix-command flakes`` to your ``nix.conf``).
|
||||
* `Nix <https://nixos.org/download/>`_ installed on your system.
|
||||
* Nix flakes enabled (add ``experimental-features = nix-command flakes``
|
||||
to your ``nix.conf``).
|
||||
|
||||
Setting up the Development Environment
|
||||
--------------------------------------
|
||||
|
||||
To enter the NuttX development shell, navigate to the root of the NuttX directory and run:
|
||||
To enter the **NuttX build** development shell, navigate to the root of
|
||||
the NuttX directory and run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
|
@ -21,29 +26,77 @@ To enter the NuttX development shell, navigate to the root of the NuttX director
|
|||
|
||||
This command will:
|
||||
|
||||
* Download and set up all necessary build tools and dependencies, including:
|
||||
* CMake, Ninja, GNU Make
|
||||
* Clang tools
|
||||
* ARM toolchain (gcc-arm-embedded)
|
||||
* Automake, Bison, Flex, Genromfs, Gettext, Gperf
|
||||
* Kconfig-frontends, libelf, expat, gmp, isl, libmpc, mpfr, ncurses, zlib
|
||||
* Python with kconfiglib
|
||||
* Set the ``CMAKE_EXPORT_COMPILE_COMMANDS`` environment variable to ``ON``.
|
||||
* Display a welcome message.
|
||||
* Download and set up all necessary build tools and dependencies, including:
|
||||
|
||||
* CMake, Ninja, GNU Make
|
||||
* Clang tools
|
||||
* ARM toolchain (gcc-arm-embedded)
|
||||
* Automake, Bison, Flex, Genromfs, Gettext, Gperf
|
||||
* Kconfig-frontends, libelf, expat, gmp, isl, libmpc, mpfr, ncurses, zlib
|
||||
* Python with kconfiglib
|
||||
|
||||
* Set the ``CMAKE_EXPORT_COMPILE_COMMANDS`` environment variable to ``ON``.
|
||||
* Display a welcome message.
|
||||
|
||||
Once inside the development shell, you can proceed with building NuttX as usual.
|
||||
|
||||
Setting up the Documentation Environment
|
||||
-----------------------------------------
|
||||
|
||||
The flake also provides a **documentation** development shell that includes
|
||||
Sphinx and all required extensions for building the NuttX documentation.
|
||||
|
||||
To enter the documentation shell, run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
nix develop .#docs
|
||||
|
||||
This command will:
|
||||
|
||||
* Provide Python 3.13 with Sphinx and extensions, including:
|
||||
|
||||
* sphinx-rtd-theme
|
||||
* myst-parser
|
||||
* sphinx-tabs
|
||||
* sphinx-autobuild
|
||||
* sphinx-copybutton
|
||||
* sphinx-togglebutton
|
||||
* sphinx-design
|
||||
* sphinx-tags
|
||||
* sphinx-collapse
|
||||
* pytz, importlib-metadata
|
||||
|
||||
* Allow you to build and preview the documentation without installing
|
||||
anything globally.
|
||||
|
||||
Example usage:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Build HTML docs
|
||||
make html
|
||||
|
||||
See the :doc:`/contributing/documentation` guide for more details.
|
||||
|
||||
Benefits
|
||||
--------
|
||||
|
||||
* **Reproducibility:** Ensures a consistent build environment across all developers and machines.
|
||||
* **Simplified Onboarding:** New contributors can quickly set up their development environment with a single command.
|
||||
* **Dependency Management:** All dependencies are managed by Nix, avoiding conflicts with system-wide packages.
|
||||
* **Reproducibility:** Ensures a consistent build environment across all
|
||||
developers and machines.
|
||||
* **Simplified Onboarding:** New contributors can quickly set up their
|
||||
development environment with a single command.
|
||||
* **Dependency Management:** All dependencies are managed by Nix, avoiding
|
||||
conflicts with system-wide packages.
|
||||
* **Separate Environments:** Keep firmware build tools and documentation
|
||||
tools isolated, or combine them if needed.
|
||||
|
||||
Contents of the Nix Flake
|
||||
-------------------------
|
||||
|
||||
The `flake.nix` file defines a `devShell` that includes the following build inputs:
|
||||
The `flake.nix` file defines two `devShells`:
|
||||
|
||||
* ``devShells.default`` - NuttX build environment:
|
||||
|
||||
.. code-block:: nix
|
||||
|
||||
|
|
@ -76,13 +129,29 @@ The `flake.nix` file defines a `devShell` that includes the following build inpu
|
|||
pkgs.python313Packages.kconfiglib
|
||||
];
|
||||
|
||||
The `shellHook` sets up the `CMAKE_EXPORT_COMPILE_COMMANDS` and provides a welcome message:
|
||||
|
||||
.. code-block:: nix
|
||||
|
||||
shellHook = ''
|
||||
export CMAKE_EXPORT_COMPILE_COMMANDS=ON
|
||||
echo "Welcome to NuttX devShell"
|
||||
'';
|
||||
|
||||
This setup ensures that the development environment is fully configured for NuttX development.
|
||||
* ``devShells.docs`` - Documentation environment (from `Documentation/flake.nix`):
|
||||
|
||||
.. code-block:: nix
|
||||
|
||||
python.withPackages (ps: with ps; [
|
||||
sphinx
|
||||
sphinx_rtd_theme
|
||||
myst-parser
|
||||
sphinx-tabs
|
||||
sphinx-autobuild
|
||||
sphinx-copybutton
|
||||
sphinx-togglebutton
|
||||
sphinx-design
|
||||
sphinx-tags
|
||||
sphinx-collapse
|
||||
pytz
|
||||
importlib-metadata
|
||||
]);
|
||||
|
||||
This setup ensures that both firmware development and documentation building
|
||||
are fully reproducible and isolated.
|
||||
|
|
|
|||
33
flake.lock
generated
33
flake.lock
generated
|
|
@ -1,5 +1,19 @@
|
|||
{
|
||||
"nodes": {
|
||||
"documentation": {
|
||||
"inputs": {
|
||||
"nixpkgs": "nixpkgs"
|
||||
},
|
||||
"locked": {
|
||||
"path": "./Documentation",
|
||||
"type": "path"
|
||||
},
|
||||
"original": {
|
||||
"path": "./Documentation",
|
||||
"type": "path"
|
||||
},
|
||||
"parent": []
|
||||
},
|
||||
"flake-utils": {
|
||||
"inputs": {
|
||||
"systems": "systems"
|
||||
|
|
@ -19,6 +33,22 @@
|
|||
}
|
||||
},
|
||||
"nixpkgs": {
|
||||
"locked": {
|
||||
"lastModified": 1754725699,
|
||||
"narHash": "sha256-iAcj9T/Y+3DBy2J0N+yF9XQQQ8IEb5swLFzs23CdP88=",
|
||||
"owner": "NixOS",
|
||||
"repo": "nixpkgs",
|
||||
"rev": "85dbfc7aaf52ecb755f87e577ddbe6dbbdbc1054",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "NixOS",
|
||||
"ref": "nixos-unstable",
|
||||
"repo": "nixpkgs",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"nixpkgs_2": {
|
||||
"locked": {
|
||||
"lastModified": 1753250450,
|
||||
"narHash": "sha256-i+CQV2rPmP8wHxj0aq4siYyohHwVlsh40kV89f3nw1s=",
|
||||
|
|
@ -36,8 +66,9 @@
|
|||
},
|
||||
"root": {
|
||||
"inputs": {
|
||||
"documentation": "documentation",
|
||||
"flake-utils": "flake-utils",
|
||||
"nixpkgs": "nixpkgs"
|
||||
"nixpkgs": "nixpkgs_2"
|
||||
}
|
||||
},
|
||||
"systems": {
|
||||
|
|
|
|||
18
flake.nix
18
flake.nix
|
|
@ -4,6 +4,7 @@
|
|||
inputs = {
|
||||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
||||
flake-utils.url = "github:numtide/flake-utils";
|
||||
documentation.url = "path:./Documentation";
|
||||
};
|
||||
|
||||
outputs =
|
||||
|
|
@ -11,6 +12,7 @@
|
|||
self,
|
||||
nixpkgs,
|
||||
flake-utils,
|
||||
documentation,
|
||||
...
|
||||
}:
|
||||
flake-utils.lib.eachDefaultSystem (
|
||||
|
|
@ -19,6 +21,7 @@
|
|||
pkgs = import nixpkgs { inherit system; };
|
||||
in
|
||||
{
|
||||
# Default devShell
|
||||
devShells.default = pkgs.mkShell {
|
||||
buildInputs = [
|
||||
# Build tools
|
||||
|
|
@ -47,24 +50,15 @@
|
|||
pkgs.ncurses.dev
|
||||
pkgs.zlib
|
||||
pkgs.python313Packages.kconfiglib
|
||||
|
||||
# NuttX Documentation
|
||||
pkgs.sphinx
|
||||
pkgs.python313Packages.sphinx_rtd_theme
|
||||
pkgs.python313Packages.myst-parser
|
||||
pkgs.python313Packages.sphinx-tabs
|
||||
pkgs.python313Packages.sphinx-autobuild
|
||||
pkgs.python313Packages.sphinx-copybutton
|
||||
pkgs.python313Packages.sphinx-togglebutton
|
||||
pkgs.python313Packages.pytz
|
||||
pkgs.python313Packages.importlib-metadata
|
||||
pkgs.python313Packages.sphinx-design
|
||||
];
|
||||
shellHook = ''
|
||||
export CMAKE_EXPORT_COMPILE_COMMANDS=ON
|
||||
echo "Welcome to NuttX devShell"
|
||||
'';
|
||||
};
|
||||
|
||||
# Documentation devShell
|
||||
devShells.docs = documentation.devShells.${system}.default;
|
||||
}
|
||||
);
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue