From 7669cfce3d4e260230579b88072dec05e7667b4f Mon Sep 17 00:00:00 2001 From: architeuthidae Date: Sun, 15 Dec 2024 01:30:56 +0100 Subject: [PATCH] doc: Clarify Nix installation --- doc/manual/building_developing.rst | 10 ++-- doc/manual/installing.rst | 80 ++++++++++++++++++------------ 2 files changed, 52 insertions(+), 38 deletions(-) diff --git a/doc/manual/building_developing.rst b/doc/manual/building_developing.rst index b14e5642e..2e15d99ff 100644 --- a/doc/manual/building_developing.rst +++ b/doc/manual/building_developing.rst @@ -86,9 +86,7 @@ Nix development environment - Enable flakes, for example by adding ``experimental-features = nix-command flakes`` to ``nix.conf``. See also the `NixOS Wiki on flakes `_. - Add ``/opt`` (or your Vivado location) as an Nix sandbox, for example by adding ``extra-sandbox-paths = /opt`` to ``nix.conf``. - - Create a file called ``trusted-settings.json`` in ``~/.local/share/nix/``, if it doesn't exist already. Make sure it contains the following: - - :: + - Make sure that you have accepted and marked as permanent the additional settings described in :ref:`installing-details`. You can check on this manually by ensuring the file ``trusted-settings.json`` in ``~/.local/share/nix/`` exists and contains the following: :: { "extra-sandbox-paths":{ @@ -102,7 +100,7 @@ Nix development environment } } - - If using NixOS, instead make the equivalent changes to your ``configuration.nix``. + - If using NixOS, make the equivalent changes to your ``configuration.nix`` instead. * Clone `the ARTIQ Git repository `_, or `the ARTIQ-Zynq repository `__ for :ref:`Zynq devices ` (Kasli-SoC, ZC706, or EBAZ4205). By default, you are working with the ``master`` branch, which represents the beta version and is not stable (see :doc:`releases`). Checkout the most recent release (``git checkout release-[number]``) for a stable version. * If your Vivado installation is not in its default location ``/opt``, open ``flake.nix`` and edit it accordingly (note that the edits must be made in the main ARTIQ flake, even if you are working with Zynq, see also tip below). @@ -120,7 +118,7 @@ Once you have run ``nix develop`` you are in the ARTIQ development environment. $ export PYTHONPATH=/absolute/path/to/your/artiq:$PYTHONPATH - Note that this only applies for incremental builds. If you want to use ``nix build``, or make changes to the dependencies, look into changing the inputs of the ``flake.nix`` instead. You can do this by replacing the URL of the GitHub ARTIQ repository with ``path:/absolute/path/to/your/artiq``; remember that Nix caches dependencies, so to incorporate new changes you will need to exit the development shell, update the Nix cache with ``nix flake update``, and re-run ``nix develop``. + Note that this only applies for incremental builds. If you want to use ``nix build``, or make changes to the dependencies, look into changing the inputs of the ``flake.nix`` instead. You can do this by replacing the URL of the GitHub ARTIQ repository with ``path:/absolute/path/to/your/artiq``; remember that Nix pins dependencies, so to incorporate new changes you will need to exit the development shell, update the environment with ``nix flake update``, and re-run ``nix develop``. Building only standard binaries ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -138,7 +136,7 @@ The parallel command does exist for ARTIQ-Zynq: :: $ nix develop git+https://git.m-labs.hk/m-labs/artiq-zynq\?ref=release-[number] -but if you are building ARTIQ-Zynq without intention to change the source, it is not actually necessary to enter the development environment at all; Nix is capable of accessing the official flake remotely for the build itself, eliminating the requirement for any particular environment. +but if you are building ARTIQ-Zynq without intention to change the source, it is not actually necessary to enter the development environment at all; Nix is capable of accessing the official flake directly to set up the build, eliminating the requirement for any particular environment. This is equally possible for original ARTIQ, but not as useful, as the development environment (specifically the ``#boards`` shell) is still the easiest way to access the necessary tools for flashing the board. On the other hand, Zynq boards can also be flashed by writing to the SD card directly, which requires no further special tools. As long as you have a functioning Nix/Vivado installation with flakes enabled, you can progress directly to the building instructions below. diff --git a/doc/manual/installing.rst b/doc/manual/installing.rst index e558ce3e5..ba205f2ba 100644 --- a/doc/manual/installing.rst +++ b/doc/manual/installing.rst @@ -1,31 +1,35 @@ Installing ARTIQ ================ -ARTIQ can be installed using the Nix (on Linux) or MSYS2 (on Windows) package managers. Using Conda is also possible on both platforms but not recommended. +M-Labs recommends installing ARTIQ through Nix (on Linux) or MSYS2 (on Windows). It is also possible to use Conda (on either platform), but this is not preferred, and likely to become unsupported in the near future. Installing via Nix (Linux) -------------------------- -First install the Nix package manager. Some distributions provide a package for it; otherwise, it can be installed via the script on the `Nix website `_. Make sure you get Nix version 2.4 or higher. Prefer a single-user installation for simplicity. +First, install the Nix package manager. Some distributions provide a package for it. Otherwise, use the official install script, as described on the `Nix website `_, e.g.: :: -Once Nix is installed, enable flakes, for example by running: :: + $ sh <(curl -L https://nixos.org/nix/install) --no-daemon + +Prefer the single-user installation for simplicity. Enable `Nix flakes `_, for example by running: :: $ mkdir -p ~/.config/nix $ echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf -See also the different options for enabling flakes on `the NixOS wiki `_. +User environment installation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The easiest way to obtain ARTIQ is to install it into the user environment with :: +There are few options for accessing ARTIQ through Nix. The easiest way is to install it into the user environment: :: $ nix profile install git+https://github.com/m-labs/artiq.git -Answer "Yes" to the questions about setting Nix configuration options (for more details see 'Troubleshooting' below.) You should now have a minimal installation of ARTIQ, where the usual front-end commands (:mod:`~artiq.frontend.artiq_run`, :mod:`~artiq.frontend.artiq_master`, :mod:`~artiq.frontend.artiq_dashboard`, etc.) are all available to you. +Answer "Yes" to the questions about setting Nix configuration options (for more details see :ref:`installing-details` below.) You should now have a minimal installation of ARTIQ, where the usual front-end commands (:mod:`~artiq.frontend.artiq_run`, :mod:`~artiq.frontend.artiq_master`, :mod:`~artiq.frontend.artiq_dashboard`, etc.) are all available to you. -This installation is however quite limited, as Nix creates a dedicated Python environment for the ARTIQ commands alone. This means that other useful Python packages, which ARTIQ is not dependent on but which you may want to use in your experiments (pandas, matplotlib...), are not available. +This installation is however relatively limited. Without further instructions, Nix takes its cues from the main ARTIQ flake (the ``flake.nix`` file at the root of the repository linked in the command) and creates a dedicated Python environment for the ARTIQ commands alone. This means that other useful Python packages, which are not necessary to run ARTIQ but which you might want to use in experiments (pandas, matplotlib...), are not available. -Installing multiple packages and making them visible to the ARTIQ commands requires using the Nix language. Create an empty directory with a file ``flake.nix`` with the following contents: +Flake custom environments +^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +Modifying the environment and making additional packages visible to the ARTIQ commands requires using the Nix language and writing your own flake. Create an empty directory with a file ``flake.nix`` containing the following: :: { inputs.extrapkg.url = "git+https://git.m-labs.hk/M-Labs/artiq-extrapkg.git"; @@ -34,13 +38,14 @@ Installing multiple packages and making them visible to the ARTIQ commands requi pkgs = extrapkg.pkgs; artiq = extrapkg.packages.x86_64-linux; in { - defaultPackage.x86_64-linux = pkgs.buildEnv { + # This section defines the new environment + packages.x86_64-linux.default = pkgs.buildEnv { name = "artiq-env"; paths = [ # ======================================== - # EDIT BELOW + # ADD PACKAGES BELOW # ======================================== - (pkgs.python3.withPackages(ps: [ + (pkgs.python3.withPackages(_: [ # List desired Python packages here. artiq.artiq #ps.paramiko # needed if and only if flashing boards remotely (artiq_flash -H) @@ -60,35 +65,42 @@ Installing multiple packages and making them visible to the ARTIQ commands requi #ps.qiskit # Note that NixOS also provides packages ps.numpy and ps.scipy, but it is # not necessary to explicitly add these, since they are dependencies of - # ARTIQ and available with an ARTIQ install anyway. + # ARTIQ and incorporated with an ARTIQ install anyway. ])) + # List desired non-Python packages here + # Additional NDSPs can be included: #artiq.korad_ka3005p #artiq.novatech409b - # List desired non-Python packages here # Other potentially interesting non-Python packages from the NixOS package collection: #pkgs.gtkwave #pkgs.spyder #pkgs.R #pkgs.julia # ======================================== - # EDIT ABOVE + # ADD PACKAGES ABOVE # ======================================== ]; }; }; + # This section configures additional settings to be able to use M-Labs binary caches nixConfig = { # work around https://github.com/NixOS/nix/issues/6771 extra-trusted-public-keys = "nixbld.m-labs.hk-1:5aSRVA5b320xbNvu30tqxVPXpld73bhtOeH6uAjRyHc="; extra-substituters = "https://nixbld.m-labs.hk"; }; } -You can now spawn a shell containing these packages by running ``$ nix shell`` in the directory containing the ``flake.nix``. This should make both the ARTIQ commands and all the additional packages available to you. You can exit the shell with Control+D or with the command ``exit``. A first execution of ``$ nix shell`` may take some time, but for any future repetitions Nix will use cached packages and startup should be much faster. +To spawn a shell in this environment, navigate to the directory containing the ``flake.nix`` and run: :: -You might be interested in creating multiple directories containing different ``flake.nix`` files which represent different sets of packages for different purposes. If you are familiar with Conda, using Nix in this way is similar to having multiple Conda environments. + $ nix shell + +The resulting shell will have access to ARTIQ as well as any additional packages you may have added. You can exit this shell at any time with CTRL+D or with the command ``exit``. Note that a first execution of ``nix shell`` on a given flake may take some time; repetitions of the same command will use stored versions of packages and run much more quickly. + +You might be interested in creating multiple directories containing separate ``flake.nix`` files to represent different sets of packages for different purposes. If you are familiar with Conda, using Nix in this way is similar to having multiple Conda environments. To find more packages you can browse the `Nix package search `_ website. If your favorite package is not available with Nix, contact M-Labs using the helpdesk@ email. .. note:: + If you find you prefer using flakes to your original ``nix profile`` installation, you can remove it from your system by running: :: $ nix profile list @@ -97,35 +109,39 @@ To find more packages you can browse the `Nix package search `_ in Nix, which may be the case for example when Nix is installed via ``pacman`` in Arch Linux. By default, users accessing Nix in multi-user mode are "unprivileged" and cannot use untrusted substituters. To change this, edit ``/etc/nix/nix.conf`` and add the following line (or append to the key if the key already exists): :: +and Nix tries to build some packages from source, this means that you are using `multi-user mode `_ in Nix, which may be the case for example when Nix is installed via ``pacman`` in Arch Linux. By default, users accessing Nix in multi-user mode are "unprivileged" and cannot use untrusted substituters. To change this, edit ``/etc/nix/nix.conf`` and add the following line (or append to the key if the key already exists): :: trusted-substituters = https://nixbld.m-labs.hk @@ -143,9 +159,9 @@ This will add the substituter as a trusted substituter for all users using Nix. Alternatively, add the following line: :: - trusted-users = # Replace with the user invoking `nix` + trusted-users = # Replace with your username -This will set your user as a trusted user, allowing the use of any untrusted substituters. +This will set your user as a trusted user, allowing you to specify untrusted substituters. .. warning:: @@ -216,9 +232,9 @@ Upgrading ARTIQ Upgrading with Nix ^^^^^^^^^^^^^^^^^^ -Run ``$ nix profile upgrade`` if you installed ARTIQ into your user profile. If you used a ``flake.nix`` shell environment, make a back-up copy of the ``flake.lock`` file to enable rollback, then run ``$ nix flake update`` and re-enter the environment with ``$ nix shell``. +Run ``$ nix profile upgrade`` if you installed ARTIQ into your user profile. If you use a ``flake.nix`` shell environment, make a back-up copy of the ``flake.lock`` file to enable rollback, then run ``$ nix flake update`` and re-enter the environment with ``$ nix shell``. If you use multiple flakes, each has its own ``flake.lock`` and can be updated or rolled back separately. -To rollback to the previous version, respectively use ``$ nix profile rollback`` or restore the backed-up version of the ``flake.lock`` file. +To rollback to the previous version, respectively use ``$ nix profile rollback`` or restore the backed-up versions of the ``flake.lock`` files. Upgrading with MSYS2 ^^^^^^^^^^^^^^^^^^^^