diff --git a/.readthedocs.yml b/.readthedocs.yml index b7e160307..7bbd24a41 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -2,4 +2,4 @@ python: version: 3 pip_install: false conda: - file: conda/artiq-doc.yml + file: conda/artiq-doc.yaml diff --git a/conda/artiq-dev.yml b/conda/artiq-dev.yaml similarity index 100% rename from conda/artiq-dev.yml rename to conda/artiq-dev.yaml diff --git a/conda/artiq-doc.yml b/conda/artiq-doc.yaml similarity index 100% rename from conda/artiq-doc.yml rename to conda/artiq-doc.yaml diff --git a/doc/manual/installing_from_source.rst b/doc/manual/developing.rst similarity index 81% rename from doc/manual/installing_from_source.rst rename to doc/manual/developing.rst index 9fdcb1de6..f4d0ca58b 100644 --- a/doc/manual/installing_from_source.rst +++ b/doc/manual/developing.rst @@ -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 ` + 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 ` + 7. :ref:`Obtain and install the JTAG SPI flash proxy bitstream ` + 8. :ref:`Configure OpenOCD ` + 9. :ref:`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 `). - - 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 diff --git a/doc/manual/index.rst b/doc/manual/index.rst index 056122e4d..4b351bda5 100644 --- a/doc/manual/index.rst +++ b/doc/manual/index.rst @@ -8,7 +8,7 @@ Contents: introduction installing - installing_from_source + developing release_notes rtio getting_started_core diff --git a/doc/manual/installing.rst b/doc/manual/installing.rst index 5ac3018ed..a0aa97afa 100644 --- a/doc/manual/installing.rst +++ b/doc/manual/installing.rst @@ -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-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 `_, 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::