occheung
/
artiq
forked from M-Labs/artiq
1
0
Fork 0
Code Pull Requests Activity

manual: use $ for shell prompts consistently

This commit is contained in:
Sebastien Bourdeauducq 2019-03-04 11:06:20 +08:00
parent 26dd4e5160
commit 24a3b31f22
2 changed files with 23 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
doc/manual/developing.rst
View File

@ -7,18 +7,18 @@ Developing ARTIQ
The easiest way to obtain an ARTIQ development environment is via the Nix package manager on Linux. The Nix system is used on the `M-Labs Hydra server <https://nixbld.m-labs.hk/>`_ to build ARTIQ and its dependencies continuously; it ensures that all build instructions are up-to-date and allows binary packages to be used on developers' machines, in particular for large tools such as the Rust compiler. The easiest way to obtain an ARTIQ development environment is via the Nix package manager on Linux. The Nix system is used on the `M-Labs Hydra server <https://nixbld.m-labs.hk/>`_ to build ARTIQ and its dependencies continuously; it ensures that all build instructions are up-to-date and allows binary packages to be used on developers' machines, in particular for large tools such as the Rust compiler.
ARTIQ itself does not depend on Nix, and it is also possible to compile everything from source (look into the ``.nix`` files from the ``nix-scripts`` repository and run the commands manually) - but Nix makes the process a lot easier. ARTIQ itself does not depend on Nix, and it is also possible to compile everything from source (look into the ``.nix`` files from the ``nix-scripts`` repository and run the commands manually) - but Nix makes the process a lot easier.
* Install the `Nix package manager <http://nixos.org/nix/>`_ and Git (e.g. ``nix-shell -p git``). * Install the `Nix package manager <http://nixos.org/nix/>`_ and Git (e.g. ``$ nix-shell -p git``).
* Set up the M-Labs Hydra channels (:ref:`same procedure as the user section <installing-nix-users>`) to allow binaries to be downloaded. Otherwise, tools such as LLVM and the Rust compiler will be compiled on your machine, which uses a lot of CPU time, memory, and disk space. Simply setting up the channels is sufficient, Nix will automatically detect when a binary can be downloaded instead of being compiled locally. * Set up the M-Labs Hydra channels (:ref:`same procedure as the user section <installing-nix-users>`) to allow binaries to be downloaded. Otherwise, tools such as LLVM and the Rust compiler will be compiled on your machine, which uses a lot of CPU time, memory, and disk space. Simply setting up the channels is sufficient, Nix will automatically detect when a binary can be downloaded instead of being compiled locally.
* Clone the repositories https://github.com/m-labs/artiq and https://github.com/m-labs/nix-scripts. * Clone the repositories https://github.com/m-labs/artiq and https://github.com/m-labs/nix-scripts.
* Run ``nix-shell -I artiqSrc=path_to_artiq_sources shell-dev.nix`` to obtain an environment containing all the required development tools (e.g. Migen, MiSoC, Clang, Rust, OpenOCD...) in addition to the ARTIQ user environment. ``artiqSrc`` should point to the root of the cloned ``artiq`` repository, and ``shell-dev.nix`` can be found in the ``artiq`` folder of the ``nix-scripts`` repository. * Run ``$ nix-shell -I artiqSrc=path_to_artiq_sources shell-dev.nix`` to obtain an environment containing all the required development tools (e.g. Migen, MiSoC, Clang, Rust, OpenOCD...) in addition to the ARTIQ user environment. ``artiqSrc`` should point to the root of the cloned ``artiq`` repository, and ``shell-dev.nix`` can be found in the ``artiq`` folder of the ``nix-scripts`` repository.
* This enters a FHS chroot environment that simplifies the installation and patching of Xilinx Vivado. * This enters a FHS chroot environment that simplifies the installation and patching of Xilinx Vivado.
* Download Vivado from Xilinx and install it (by running the official installer in the FHS chroot environment). If you do not want to write to ``/opt``, you can install it in a folder of your home directory. The "appropriate" Vivado version to use for building the bitstream can vary. Some versions contain bugs that lead to hidden or visible failures, others work fine. Refer to the `M-Labs Hydra logs <https://nixbld.m-labs.hk/>`_ to determine which version is currently used when building the binary packages. * Download Vivado from Xilinx and install it (by running the official installer in the FHS chroot environment). If you do not want to write to ``/opt``, you can install it in a folder of your home directory. The "appropriate" Vivado version to use for building the bitstream can vary. Some versions contain bugs that lead to hidden or visible failures, others work fine. Refer to the `M-Labs Hydra logs <https://nixbld.m-labs.hk/>`_ to determine which version is currently used when building the binary packages.
* During the Vivado installation, uncheck ``Install cable drivers`` (they are not required as we use better and open source alternatives). * During the Vivado installation, uncheck ``Install cable drivers`` (they are not required as we use better and open source alternatives).
* You can then build the firmware and gateware with a command such as ``python -m artiq.gateware.targets.kasli``. * You can then build the firmware and gateware with a command such as ``$ python -m artiq.gateware.targets.kasli``.
* If you did not install Vivado in ``/opt``, add a command line option such as ``--gateware-toolchain-path ~/Xilinx/Vivado``. * If you did not install Vivado in ``/opt``, add a command line option such as ``--gateware-toolchain-path ~/Xilinx/Vivado``.
* Flash the binaries into the FPGA board with a command such as ``artiq_flash --srcbuild artiq_kasli -V <your_variant>``. You need to configure OpenOCD as explained :ref:`in the user section <configuring-openocd>`. OpenOCD is already part of the shell started by ``shell-dev.nix``. * Flash the binaries into the FPGA board with a command such as ``$ artiq_flash --srcbuild artiq_kasli -V <your_variant>``. You need to configure OpenOCD as explained :ref:`in the user section <configuring-openocd>`. OpenOCD is already part of the shell started by ``shell-dev.nix``.
* Check that the board boots and examine the UART messages by running a serial terminal program, e.g. ``flterm /dev/ttyUSB1`` (``flterm`` is part of MiSoC and installed by ``shell-dev.nix``). Leave the terminal running while you are flashing the board, so that you see the startup messages when the board boots immediately after flashing. You can also restart the board (without reflashing it) with ``artiq_flash start``. * Check that the board boots and examine the UART messages by running a serial terminal program, e.g. ``$ flterm /dev/ttyUSB1`` (``flterm`` is part of MiSoC and installed by ``shell-dev.nix``). Leave the terminal running while you are flashing the board, so that you see the startup messages when the board boots immediately after flashing. You can also restart the board (without reflashing it) with ``$ artiq_flash start``.
* The communication parameters are 115200 8-N-1. Ensure that your user has access to the serial device (``sudo adduser $USER dialout`` assuming standard setup). * The communication parameters are 115200 8-N-1. Ensure that your user has access to the serial device (``$ sudo adduser $USER dialout`` assuming standard setup).
* If you are modifying a dependency of ARTIQ, in addition to updating the relevant part of ``nix-scripts``, rebuild and upload the corresponding Conda packages manually, and update their version numbers in ``conda-artiq.nix``. For Conda, only the main ARTIQ package and the board packages are handled automatically on Hydra. * If you are modifying a dependency of ARTIQ, in addition to updating the relevant part of ``nix-scripts``, rebuild and upload the corresponding Conda packages manually, and update their version numbers in ``conda-artiq.nix``. For Conda, only the main ARTIQ package and the board packages are handled automatically on Hydra.
.. warning:: .. warning::

22
doc/manual/installing.rst
View File

@ -18,17 +18,17 @@ First, install the Nix package manager. Some distributions provide a package for
Once Nix is installed, add the M-Labs package channels with: :: Once Nix is installed, add the M-Labs package channels 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/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/sinara-systems/channel sinara
Those channels track `nixpkgs 18.09 <https://github.com/NixOS/nixpkgs/tree/release-18.09>`_. 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: :: Those channels track `nixpkgs 18.09 <https://github.com/NixOS/nixpkgs/tree/release-18.09>`_. 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: ::
nix-channel --remove nixpkgs $ nix-channel --remove nixpkgs
nix-channel --add https://nixos.org/channels/nixos-18.09 nixpkgs $ nix-channel --add https://nixos.org/channels/nixos-18.09 nixpkgs
Finally, make all the channel changes effective: :: Finally, make all the channel changes effective: ::
nix-channel --update $ nix-channel --update
Nix won't install packages without verifying their cryptographic signature. Add the M-Labs public key by creating the file ``~/.config/nix/nix.conf`` with the following contents: Nix won't install packages without verifying their cryptographic signature. Add the M-Labs public key by creating the file ``~/.config/nix/nix.conf`` with the following contents:
@ -37,7 +37,7 @@ Nix won't install packages without verifying their cryptographic signature. Add
substituters = https://cache.nixos.org https://nixbld.m-labs.hk substituters = https://cache.nixos.org https://nixbld.m-labs.hk
trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= nixbld.m-labs.hk-1:5aSRVA5b320xbNvu30tqxVPXpld73bhtOeH6uAjRyHc= 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 -i python3.6-artiq``. 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 -i python3.6-artiq``. This provides a minimal installation of ARTIQ where the usual commands (``artiq_master``, ``artiq_dashboard``, ``artiq_run``, etc.) are available.
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. 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.
@ -80,9 +80,9 @@ Installing multiple packages and making them visible to the ARTIQ commands requi
]; ];
} }
Then spawn a shell containing the packages with ``nix-shell my-artiq-env.nix``. The ARTIQ commands with all the additional packages should now be available. Then spawn a shell containing the packages with ``$ nix-shell my-artiq-env.nix``. The ARTIQ commands with all the additional packages should now be available.
You can exit the shell by typing Control-D. The next time ``nix-shell my-artiq-env.nix`` is invoked, Nix uses the cached packages so the shell startup is fast. You can exit the shell by typing Control-D. The next time ``$ nix-shell my-artiq-env.nix`` is invoked, Nix uses the cached packages so the shell startup is fast.
You can edit this file according to your needs, and also create multiple ``.nix`` files that correspond to different sets of packages. If you are familiar with Conda, using Nix in this way is similar to having multiple Conda environments. You can edit this file according to your needs, and also create multiple ``.nix`` files that correspond to different sets of packages. If you are familiar with Conda, using Nix in this way is similar to having multiple Conda environments.
@ -118,9 +118,9 @@ This activation has to be performed in every new shell you open to make the ARTI
Upgrading ARTIQ (with Nix) Upgrading ARTIQ (with Nix)
-------------------------- --------------------------
Run ``nix-channel --update`` to retrieve information about the latest versions, and then either reinstall ARTIQ into the user environment (``nix-env -i python3.6-artiq``) or re-run the ``nix-shell`` command. Run ``$ nix-channel --update`` to retrieve information about the latest versions, and then either reinstall ARTIQ into the user environment (``$ nix-env -i python3.6-artiq``) or re-run the ``nix-shell`` command.
To rollback to the previous version, use ``nix-channel --rollback`` and then re-do the second step. You can switch between versions by passing a parameter to ``--rollback`` (see the ``nix-channel`` documentation). To rollback to the previous version, use ``$ nix-channel --rollback`` and then re-do the second step. You can switch between versions by passing a parameter to ``--rollback`` (see the ``nix-channel`` documentation).
You may need to reflash the gateware and firmware of the core device to keep it synchronized with the software. You may need to reflash the gateware and firmware of the core device to keep it synchronized with the software.
@ -223,7 +223,7 @@ You can also insert other types of SFP transceivers into Kasli if you wish to us
If you purchased a device from M-Labs, it already comes with a valid MAC address and an IP address, usually ``192.168.1.75``. Once you can reach this IP, it can be changed with: :: If you purchased a device from M-Labs, it already comes with a valid MAC address and an IP address, usually ``192.168.1.75``. Once you can reach this IP, it can be changed with: ::
artiq_coremgmt -D 192.168.1.75 config write -s ip [new IP] $ artiq_coremgmt -D 192.168.1.75 config write -s ip [new IP]
and then reboot the device (with ``artiq_flash start`` or a power cycle). and then reboot the device (with ``artiq_flash start`` or a power cycle).