mirror of
https://github.com/apache/nuttx.git
synced 2025-12-07 01:44:23 +08:00
c36d067603
Some checks failed
Build Documentation / build-html (push) Has been cancelled
This commit moves the flake.lock and flake.nix files from root and Documentation/ to the tools/ directory, according to @anchao's suggestion in PR #16763. Updates documentation to reflect this change. Signed-off-by: Côme VINCENT <44554692+comejv@users.noreply.github.com>
158 lines
3.9 KiB
ReStructuredText
158 lines
3.9 KiB
ReStructuredText
======================================
|
|
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.
|
|
|
|
Prerequisites
|
|
-------------
|
|
|
|
* `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 build** development shell, navigate to the root of
|
|
the NuttX directory and run:
|
|
|
|
.. code-block:: bash
|
|
|
|
nix develop ./tools/nix
|
|
|
|
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.
|
|
|
|
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 ./tools/nix#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 (has to but run in Documentation/ directory)
|
|
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.
|
|
* **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 two `devShells`:
|
|
|
|
* ``devShells.default`` - NuttX build environment:
|
|
|
|
.. code-block:: nix
|
|
|
|
buildInputs = [
|
|
# Build tools
|
|
pkgs.cmake
|
|
pkgs.ninja
|
|
pkgs.gnumake
|
|
pkgs.clang-tools
|
|
|
|
# ARM toolchain
|
|
pkgs.gcc-arm-embedded
|
|
|
|
# NuttX dependencies
|
|
pkgs.automake
|
|
pkgs.bison
|
|
pkgs.flex
|
|
pkgs.genromfs
|
|
pkgs.gettext
|
|
pkgs.gperf
|
|
pkgs.kconfig-frontends
|
|
pkgs.libelf
|
|
pkgs.expat.dev
|
|
pkgs.gmp.dev
|
|
pkgs.isl
|
|
pkgs.libmpc
|
|
pkgs.mpfr.dev
|
|
pkgs.ncurses.dev
|
|
pkgs.zlib
|
|
pkgs.python313Packages.kconfiglib
|
|
];
|
|
|
|
shellHook = ''
|
|
export CMAKE_EXPORT_COMPILE_COMMANDS=ON
|
|
echo "Welcome to NuttX devShell"
|
|
'';
|
|
|
|
* ``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.
|