doc: write section on developing with a conda env

This commit is contained in:
Robert Jördens 2017-02-02 19:53:12 +01:00
parent edab068ac9
commit 5a30536d59
6 changed files with 53 additions and 7 deletions

View File

@ -2,4 +2,4 @@ python:
version: 3
pip_install: false
conda:
file: conda/artiq-doc.yml
file: conda/artiq-doc.yaml

View File

@ -1,12 +1,44 @@
Developing ARTIQ
^^^^^^^^^^^^^^^^
We describe two different approaches to creating a development environment for ARTIQ.
The first method uses existing pre-compiled Anaconda packages for the development environment.
This is fast and convenient because it avoids compiling the entire toolchain but developing individual components within the toolchain requires extra care.
It is completely sufficient to develop and tweak the ARTIQ code and to build
bitstreams.
Some ARTIQ developers as well as the buildbot employs this method for continuous integration to build the ``artiq`` Anaconda packages and the bitstreams.
The second method builds most components in the toolchain from their sources.
This takes time and and care to reproduce precisely but it gives absolute control over the components and an immediate handle at developing them.
Some ARTIQ developers use this method.
It is only recommended for developers and advanced users.
.. _develop-from-conda:
ARTIQ Anaconda development environment
======================================
1. Install ``git`` as recommended for your operating system and distribution.
2. Obtain ARTIQ::
$ git clone --recursive https://github.com/m-labs/artiq ~/artiq-dev/artiq
$ cd ~/artiq-dev/artiq
3. :ref:`Install Anaconda or Miniconda <install-anaconda>`
4. Create and activate a conda environment named ``artiq-dev`` and install the ``artiq-dev`` package which pulls in all the packages required to develop ARTIQ::
$ conda env create -f conda/artiq-dev.yaml
$ source activate artiq-dev
5. Add the ARTIQ source tree to the environment's search path::
$ python setup.py develop
6. :ref:`Install Xilinx ISE or Vivado <install-xilinx>`
7. :ref:`Obtain and install the JTAG SPI flash proxy bitstream <install-bscan-spi>`
8. :ref:`Configure OpenOCD <setup-openocd>`
9. :ref:`Build target binaries <build-target-binaries>`
.. _install-from-source:
Installing ARTIQ from source
============================
.. note::
This method is only recommended for developers and advanced users. An easier way to install ARTIQ is via the Anaconda packages (see :ref:`Installing ARTIQ <install-from-conda>`).
Preparing the build environment for the core device
---------------------------------------------------
@ -88,6 +120,8 @@ Preparing the core device FPGA board
These steps are required to generate gateware bitstream (``.bit``) files, build the MiSoC BIOS and ARTIQ runtime, and flash FPGA boards. If the board is already flashed, you may skip those steps and go directly to `Installing the host-side software`.
.. _install-xilinx:
* Install the FPGA vendor tools (i.e. Xilinx ISE and/or Vivado):
* Get Xilinx tools from http://www.xilinx.com/support/download/index.htm. ISE can build gateware bitstreams both for boards using the Spartan-6 (Pipistrello) and 7-series devices (KC705), while Vivado supports only boards using 7-series devices.
@ -106,6 +140,8 @@ These steps are required to generate gateware bitstream (``.bit``) files, build
.. note::
The options ``develop`` and ``--user`` are for setup.py to install Migen in ``~/.local/lib/python3.5``.
.. _install-bscan-spi:
* Install the required flash proxy gateware bitstreams:
The purpose of the flash proxy gateware bitstream is to give programming software fast JTAG access to the flash connected to the FPGA.
@ -164,6 +200,7 @@ These steps are required to generate gateware bitstream (``.bit``) files, build
.. note:: Make sure that ``/usr/local/llvm-or1k/bin`` is first in your ``PATH``, so that the ``clang`` command you just built is found instead of the system one, if any.
.. _build-target-binaries:
* For Pipistrello::
$ python3 -m artiq.gateware.targets.pipistrello

View File

@ -8,7 +8,7 @@ Contents:
introduction
installing
installing_from_source
developing
release_notes
rtio
getting_started_core

View File

@ -16,6 +16,7 @@ The conda package contains pre-built binaries that you can directly flash to you
Conda packages are supported for Linux (64-bit) and Windows (32- and 64-bit).
Users of other operating systems (32-bit Linux, BSD, OSX ...) should and can :ref:`install from source <install-from-source>`.
.. _install-anaconda:
Installing Anaconda or Miniconda
--------------------------------
@ -104,10 +105,13 @@ They are all shipped in the conda packages, along with the required flash proxy
Installing OpenOCD
^^^^^^^^^^^^^^^^^^
OpenOCD can be used to write the binary images into the core device FPGA board's flash memory. It can be installed using conda on both Linux and Windows::
OpenOCD can be used to write the binary images into the core device FPGA board's flash memory.
The ``artiq`` or ``artiq-dev`` conda packages install ``openocd`` automatically but it can also be installed explicitly using conda on both Linux and Windows::
$ conda install openocd
.. _setup-openocd:
Some additional steps are necessary to ensure that OpenOCD can communicate with the FPGA board.
On Linux, first ensure that the current user belongs to the ``plugdev`` group. If it does not, run ``sudo adduser $USER plugdev`` and relogin. Afterwards::
@ -127,6 +131,11 @@ On Windows, a third-party tool, `Zadig <http://zadig.akeo.ie/>`_, is necessary.
You may need to repeat these steps every time you plug the FPGA board into a port where it has not been plugged into previously on the same system.
.. _flashing-core-device:
Flashing the core device
^^^^^^^^^^^^^^^^^^^^^^^^
Then, you can flash the board:
* For the Pipistrello board::