forked from M-Labs/artiq
update installation instructions
This commit is contained in:
parent
280915d54f
commit
2ffc843790
@ -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 <http://nixos.org/nix/>`_.
|
||||
|
||||
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 <https://github.com/NixOS/nixpkgs/tree/release-19.03>`_. You can check the latest status through the `Hydra interface <https://nixbld.m-labs.hk>`_. 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 <https://github.com/NixOS/nix/issues/2709>`_. 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 <https://github.com/NixOS/nix/issues/2709>`_. 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 <nixpkgs> {};
|
||||
# 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 <m-labs> { 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 <sinara> { inherit pkgs; };
|
||||
artiq-full = import <artiq-full> { 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::
|
||||
|
||||
|
||||
@ -8,27 +8,23 @@ The following network device support packages are available for ARTIQ. This list
|
||||
+=================================+===================================+==================================+=====================================================================================================+
|
||||
| PDQ2 | Not available | Not available | `HTML <https://pdq.readthedocs.io>`_ |
|
||||
+---------------------------------+-----------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------+
|
||||
| Lab Brick Digital Attenuator | ``m-labs.lda`` | ``("main", "lda")`` | `HTML <https://nixbld.m-labs.hk/job/artiq/main/lda-manual-html/latest/download/1>`_ |
|
||||
| Lab Brick Digital Attenuator | ``lda`` | ``lda` | `HTML <https://nixbld.m-labs.hk/job/artiq/full/lda-manual-html/latest/download/1>`_ |
|
||||
+---------------------------------+-----------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------+
|
||||
| Novatech 409B | ``m-labs.novatech409b`` | ``("main", "novatech409b")`` | `HTML <https://nixbld.m-labs.hk/job/artiq/main/novatech409b-manual-html/latest/download/1>`_ |
|
||||
| Novatech 409B | ``novatech409b`` | ``novatech409b`` | `HTML <https://nixbld.m-labs.hk/job/artiq/full/novatech409b-manual-html/latest/download/1>`_ |
|
||||
+---------------------------------+-----------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------+
|
||||
| Thorlabs T-Cubes | ``m-labs.thorlabs_tcube`` | ``("main", "thorlabs_tcube")`` | `HTML <https://nixbld.m-labs.hk/job/artiq/main/thorlabs_tcube-manual-html/latest/download/1>`_ |
|
||||
| Thorlabs T-Cubes | ``thorlabs_tcube`` | ``"thorlabs_tcube`` | `HTML <https://nixbld.m-labs.hk/job/artiq/full/thorlabs_tcube-manual-html/latest/download/1>`_ |
|
||||
+---------------------------------+-----------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------+
|
||||
| Korad KA3005P | ``m-labs.korad_ka3005p`` | ``("main", "korad_ka3005p")`` | `HTML <https://nixbld.m-labs.hk/job/artiq/main/korad_ka3005p-manual-html/latest/download/1>`_ |
|
||||
| Korad KA3005P | ``korad_ka3005p`` | ``korad_ka3005p`` | `HTML <https://nixbld.m-labs.hk/job/artiq/full/korad_ka3005p-manual-html/latest/download/1>`_ |
|
||||
+---------------------------------+-----------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------+
|
||||
| Newfocus 8742 | ``m-labs.newfocus8742`` | ``("main", "newfocus8742")`` | `HTML <https://nixbld.m-labs.hk/job/artiq/main/newfocus8742-manual-html/latest/download/1>`_ |
|
||||
| Newfocus 8742 | ``newfocus8742`` | ``newfocus8742`` | `HTML <https://nixbld.m-labs.hk/job/artiq/full/newfocus8742-manual-html/latest/download/1>`_ |
|
||||
+---------------------------------+-----------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------+
|
||||
| Princeton Instruments PICam | Not available | Not available | Not available |
|
||||
+---------------------------------+-----------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------+
|
||||
| Anel HUT2 power distribution | ``m-labs.hut2`` | ``("main", "hut2")`` | `HTML <https://nixbld.m-labs.hk/job/artiq/main/hut2-manual-html/latest/download/1>`_ |
|
||||
| Anel HUT2 power distribution | ``hut2`` | ``hut2`` | `HTML <https://nixbld.m-labs.hk/job/artiq/full/hut2-manual-html/latest/download/1>`_ |
|
||||
+---------------------------------+-----------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------+
|
||||
| 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 <https://nixbld.m-labs.hk/job/artiq/main/highfinesse-net-manual-html/latest/download/1>`_ |
|
||||
| HighFinesse wavemeters | ``highfinesse-net`` | ``highfinesse-net`` | `HTML <https://nixbld.m-labs.hk/job/artiq/full/highfinesse-net-manual-html/latest/download/1>`_ |
|
||||
+---------------------------------+-----------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------+
|
||||
|
||||
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.
|
||||
|
||||
@ -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))
|
||||
|
||||
Loading…
Reference in New Issue
Block a user