From 2ffc8437906b0166cb49cb67832e580f9d89bdb1 Mon Sep 17 00:00:00 2001 From: Sebastien Bourdeauducq Date: Thu, 18 Jul 2019 00:51:47 +0800 Subject: [PATCH] update installation instructions --- doc/manual/installing.rst | 27 ++++++++----------- doc/manual/list_of_ndsps.rst | 20 ++++++--------- install-with-conda.py | 50 ++++++++++-------------------------- 3 files changed, 31 insertions(+), 66 deletions(-) diff --git a/doc/manual/installing.rst b/doc/manual/installing.rst index 1ce2e4e2a..c0581a200 100644 --- a/doc/manual/installing.rst +++ b/doc/manual/installing.rst @@ -19,10 +19,9 @@ Installing via Nix (Linux) First, install the Nix package manager. Some distributions provide a package for the Nix package manager, otherwise, it can be installed via the script on the `Nix website `_. -Once Nix is installed, add the M-Labs package channels with: :: +Once Nix is installed, add the M-Labs package channel with: :: - $ nix-channel --add https://nixbld.m-labs.hk/channel/custom/artiq/main/channel m-labs - $ nix-channel --add https://nixbld.m-labs.hk/channel/custom/artiq/sinara-systems/channel sinara + $ nix-channel --add https://nixbld.m-labs.hk/channel/custom/artiq/full/artiq-full Those channels track `nixpkgs 19.03 `_. You can check the latest status through the `Hydra interface `_. As the Nix package manager default installation uses the development version of nixpkgs, we need to tell it to switch to the release: :: @@ -40,10 +39,10 @@ Nix won't install packages without verifying their cryptographic signature. Add substituters = https://cache.nixos.org https://nixbld.m-labs.hk trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= nixbld.m-labs.hk-1:5aSRVA5b320xbNvu30tqxVPXpld73bhtOeH6uAjRyHc= -The easiest way to obtain ARTIQ is then to install it into the user environment with ``$ nix-env -iA m-labs.artiq-env``. This provides a minimal installation of ARTIQ where the usual commands (``artiq_master``, ``artiq_dashboard``, ``artiq_run``, etc.) are available. +The easiest way to obtain ARTIQ is then to install it into the user environment with ``$ nix-env -iA artiq-full.artiq-env``. This provides a minimal installation of ARTIQ where the usual commands (``artiq_master``, ``artiq_dashboard``, ``artiq_run``, etc.) are available. .. note:: - If you are getting the error message ``file 'm-labs' was not found in the Nix search path``, you are probably encountering `this Nix bug `_. As a workaround, enter the command ``$ export NIX_PATH=~/.nix-defexpr/channels:$NIX_PATH`` and try again. + If you are getting the error message ``file 'artiq-full' was not found in the Nix search path``, you are probably encountering `this Nix bug `_. As a workaround, enter the command ``$ export NIX_PATH=~/.nix-defexpr/channels:$NIX_PATH`` and try again. 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 that you may want (pandas, matplotlib, ...) are not available to them, and this restriction also applies to the M-Labs packages containing board binaries, which means that ``artiq_flash`` will not automatically find them. @@ -55,24 +54,18 @@ Installing multiple packages and making them visible to the ARTIQ commands requi # Contains the NixOS package collection. ARTIQ depends on some of them, and # you may also want certain packages from there. pkgs = import {}; - # Contains the main ARTIQ packages, their dependencies, and board packages - # for systems used in CI. - # List: https://nixbld.m-labs.hk/channel/custom/artiq/main/channel - m-labs = import { inherit pkgs; }; - # Contains the board packages for the majority of systems. - # List: https://nixbld.m-labs.hk/channel/custom/artiq/sinara-systems/channel - sinara = import { inherit pkgs; }; + artiq-full = import { inherit pkgs; }; in pkgs.mkShell { buildInputs = [ (pkgs.python3.withPackages(ps: [ # List desired Python packages here. - m-labs.artiq + artiq-full.artiq # The board packages are also "Python" packages. You only need a board # package if you intend to reflash that board (those packages contain # only board firmware). - m-labs.artiq-board-kc705-nist_clock - sinara.artiq-board-kasli-wipm + artiq-full.artiq-board-kc705-nist_clock + artiq-full.artiq-board-kasli-wipm # from the NixOS package collection: ps.paramiko # needed for flashing boards remotely (artiq_flash -H) ps.pandas @@ -83,7 +76,7 @@ Installing multiple packages and making them visible to the ARTIQ commands requi ps.bokeh ])) # List desired non-Python packages here - m-labs.openocd # needed for flashing boards, also provides proxy bitstreams + artiq-full.openocd # needed for flashing boards, also provides proxy bitstreams pkgs.spyder ]; } @@ -175,7 +168,7 @@ Installing OpenOCD OpenOCD can be used to write the binary images into the core device FPGA board's flash memory. -With Nix, add ``m-labs.openocd`` to the shell packages. Be careful not to add ``pkgs.openocd`` instead - this would install OpenOCD from the NixOS package collection, which does not support ARTIQ boards. +With Nix, add ``artiq-full.openocd`` to the shell packages. Be careful not to add ``pkgs.openocd`` instead - this would install OpenOCD from the NixOS package collection, which does not support ARTIQ boards. With Conda, the ``artiq`` package installs ``openocd`` automatically but it can also be installed explicitly on both Linux and Windows:: diff --git a/doc/manual/list_of_ndsps.rst b/doc/manual/list_of_ndsps.rst index 5f2b555b6..0e117f025 100644 --- a/doc/manual/list_of_ndsps.rst +++ b/doc/manual/list_of_ndsps.rst @@ -8,27 +8,23 @@ The following network device support packages are available for ARTIQ. This list +=================================+===================================+==================================+=====================================================================================================+ | PDQ2 | Not available | Not available | `HTML `_ | +---------------------------------+-----------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------+ -| Lab Brick Digital Attenuator | ``m-labs.lda`` | ``("main", "lda")`` | `HTML `_ | +| Lab Brick Digital Attenuator | ``lda`` | ``lda` | `HTML `_ | +---------------------------------+-----------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------+ -| Novatech 409B | ``m-labs.novatech409b`` | ``("main", "novatech409b")`` | `HTML `_ | +| Novatech 409B | ``novatech409b`` | ``novatech409b`` | `HTML `_ | +---------------------------------+-----------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------+ -| Thorlabs T-Cubes | ``m-labs.thorlabs_tcube`` | ``("main", "thorlabs_tcube")`` | `HTML `_ | +| Thorlabs T-Cubes | ``thorlabs_tcube`` | ``"thorlabs_tcube`` | `HTML `_ | +---------------------------------+-----------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------+ -| Korad KA3005P | ``m-labs.korad_ka3005p`` | ``("main", "korad_ka3005p")`` | `HTML `_ | +| Korad KA3005P | ``korad_ka3005p`` | ``korad_ka3005p`` | `HTML `_ | +---------------------------------+-----------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------+ -| Newfocus 8742 | ``m-labs.newfocus8742`` | ``("main", "newfocus8742")`` | `HTML `_ | +| Newfocus 8742 | ``newfocus8742`` | ``newfocus8742`` | `HTML `_ | +---------------------------------+-----------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------+ | Princeton Instruments PICam | Not available | Not available | Not available | +---------------------------------+-----------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------+ -| Anel HUT2 power distribution | ``m-labs.hut2`` | ``("main", "hut2")`` | `HTML `_ | +| Anel HUT2 power distribution | ``hut2`` | ``hut2`` | `HTML `_ | +---------------------------------+-----------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------+ -| TOPTICA lasers | ``m-labs.toptica-lasersdk-artiq`` | See anaconda.org | Not available | +| TOPTICA lasers | ``toptica-lasersdk-artiq`` | See anaconda.org | Not available | +---------------------------------+-----------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------+ -| HighFinesse wavemeters | ``m-labs.highfinesse-net`` | ``("main", "highfinessse-net")`` | `HTML `_ | +| HighFinesse wavemeters | ``highfinesse-net`` | ``highfinesse-net`` | `HTML `_ | +---------------------------------+-----------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------+ -In the "Nix package" column, ``m-labs`` refer to the Nix channel at https://nixbld.m-labs.hk/channel/custom/artiq/main/channel. - -The "Conda package" column gives the line to add into ``install-with-conda.py`` to install the corresponding package. Conda packages may also be downloaded from https://nixbld.m-labs.hk/project/artiq and installed manually. - For PDQ2 see https://github.com/m-labs/pdq. For PICam see https://github.com/quartiq/picam. diff --git a/install-with-conda.py b/install-with-conda.py index 7895c42da..a30d8852a 100644 --- a/install-with-conda.py +++ b/install-with-conda.py @@ -6,22 +6,17 @@ # EDIT THIS: # The name of the conda environment to create CONDA_ENV_NAME = "artiq" -# The conda packages to download from hydra and install. -# Each entry is ("hydra build name", "conda package name"). Hydra builds are: -# * main: core ARTIQ packages, including controllers for third-party devices -# * sinara-systems: firmware and gateware builds for generic Sinara systems +# The conda packages to download and install. CONDA_PACKAGES = [ - ("main", "artiq"), - ("main", "artiq-board-kc705-nist_clock"), - ("main", "artiq-board-kasli-tester"), - ("sinara-systems", "artiq-board-kasli-mitll") + "artiq", + "artiq-board-kc705-nist_clock", + "artiq-board-kasli-mitll" ] # Set to False if you have already set up conda channels ADD_CHANNELS = True # PROXY: If you are behind a web proxy, configure it in your .condarc (as per -# the conda manual) and add it to the "curl" command below (add "--proxy -# http://webproxy.your.com:8080" with your values filled in) +# the conda manual). # You should not need to modify the rest of the script below. @@ -35,32 +30,13 @@ def run(command): if ADD_CHANNELS: run("conda config --prepend channels m-labs") + run("conda config --prepend channels https://m-labs.hk/artiq/conda") run("conda config --append channels conda-forge") -run("conda install -y conda-build curl") -# A questionable conda decision is to ignore dependencies when installing .tar.bz2's directly. -# Work around it by creating a channel for our packages. -with tempfile.TemporaryDirectory() as channel_dir: - print("Creating conda channel in {channel_dir}...".format(channel_dir=channel_dir)) - previous_dir = os.getcwd() - os.chdir(channel_dir) - try: - os.mkdir("noarch") - # curl -OJL won't take the correct filename and it will save the output as "conda". - # wget --content-disposition is better-behaved but wget cannot be used on Windows. - # Amazingly, conda doesn't break when package files are renamed, so we can get away - # by generating our own names that don't contain the version number. - for hydra_build, package in CONDA_PACKAGES: - run("curl https://nixbld.m-labs.hk/job/artiq/{hydra_build}/conda-{package}/latest/download-by-type/file/conda -L -o noarch/{package}.tar.bz2" - .format(hydra_build=hydra_build, package=package)) - run("conda index") - - # Creating the environment first with python 3.5 hits fewer bugs in conda's broken dependency solver. - run("conda create -y -n {CONDA_ENV_NAME} python=3.5".format(CONDA_ENV_NAME=CONDA_ENV_NAME)) - for _, package in CONDA_PACKAGES: - # Do not activate the environment yet - otherwise "conda install" may not find the SSL module anymore on Windows. - # Installing into the environment from the outside works around this conda bug. - run("conda install -y -n {CONDA_ENV_NAME} -c {channel_dir} {package}" - .format(CONDA_ENV_NAME=CONDA_ENV_NAME, channel_dir=channel_dir, package=package)) - finally: - os.chdir(previous_dir) +# Creating the environment first with python 3.5 hits fewer bugs in conda's broken dependency solver. +run("conda create -y -n {CONDA_ENV_NAME} python=3.5".format(CONDA_ENV_NAME=CONDA_ENV_NAME)) +for package in CONDA_PACKAGES: + # Do not activate the environment yet - otherwise "conda install" may not find the SSL module anymore on Windows. + # Installing into the environment from the outside works around this conda bug. + run("conda install -y -n {CONDA_ENV_NAME} -c https://m-labs.hk/artiq/conda {package}" + .format(CONDA_ENV_NAME=CONDA_ENV_NAME, package=package))