The toolchain is the set of tools used to prototype or run a Cortexlab experiment.

Actually, there is theorically almost no constraint at all on the toolchain that experimenters could use, since the workflow of execution of an experiment on each node is basically the following:

• unpack the task file on the node
• execute the entry point of the task

Thus, users, may pack whatever they want in their task file.

That said, the cortexlab team provides a standard toolchain, which we call the CorteXlab toolchain, which is maintained, supported, configured, includes all necessary drivers, and is well adapted to our platform. This toolchain is made of the following components:

• gnuradio
• some gnuradio additional modules / blocks, such as blocks which interface with the radio hardware (uhd for usrp and similar blocks to interface with picosdr nodes)
• some gnuradio additional modules adding convenient tools, which we decided to incude, such as gr-iqbal.
• software for supporting the picosdr: xilinx ise, digilent hs2 (the jtag used on the cortexlab nodes) and adp from nutaq.
• custom CorteXlab software such as fft-web (fftweb).

This toolchain is installed on the CorteXlab nodes as well as on the CorteXlab frontend airlock. It is regularly updated and versionned (current version, at the date of this writing is v1.4).

The building of this toolchain is completely automated by the cxlb-build-toolchain script. Users can use this script to build a similar toolchain on their workstation.

The only limitation is that this script is only supported on recent (stable or testing) linux debian 64 bits. Running it in another environment may be possible with some limitations. For example, it's quite straightforward to run it under a recent ubuntu 64 bits, a few package names will need to be adapted. On the other hand, it won't work at all on a 32 bits system or under windows or macos.

The main advantage of the cxlb-build-toolchain is that it takes care of installing everything in a given directory, as a regular user. It then generates and installs two scripts, one that has to be run as root, to configure the dynamic loader and udev to use the toolchain, the other that has to be sourced by the user which will use the toolchain, to configure the environment. Thus:

• as it runs as a regular user, there is zero risk to damage anything in the system, you are sure that anything it does is restricted to the rights of the user running the script. The only thing that has to be run as root is a single script generated at the end, which is easy to review and audit.
• you are then sure that it does not conflict with anything in the regular directory tree structure of your system. In particular, it cannot conflict with the package manager of your distribution.
• everything from the toolchain is kept isolated in the toolchain install directory, instead of being scattered everywhere.
• it is possible to have several toolchains installed in parallel. You only need to re-run the root script to switch to a different toolchain, and reboot (or possibly only restart udev? that needs to be checked), and re-source the environment configuration script.

When building a toolchain on a user's workstation, the user is not forced to build everything. For example, a user willing to experiment only with usrp can avoid installing all picosdr stuff (xilinx ise, digilent hs2 jtag, adp).

This script has an integrated help. Try running:

$ cxlb-build-toolchain --help

Basically, building a toolchain consists of the following steps:

• choosing what to compile/install. By default the script only install gnuradio components but not the fpga tools (for the pico nodes).
• install all prerequisites (debian package names of prerequisistes are documented in the script integrated help)
• decide a build directory, where the script will checkout/unpack all needed sources.
• optionnaly put in the build directory some packages which you have to retrieve manually and which we cannot provide due to licensing issues. These are the packages for the fpga tools (digilent, xilinx, nutaq). Currently you need to look in the source code of cxlb-build-toolchain to get the list of these packages, where to put them, which versions to use, and where to get them.
• decide an install directory, where everything will be installed.
• run cxlb-build-toolchain and be patient. On a recent fast computer, compilation and installation takes more than 30 minutes.

Once finished, two scripts are generated in install/bin/: cxlb-toolchain-system-conf which needs to be run once as root, to configure the dynamic loader and udev rules, and cxlb-toolchain-user-conf which needs to be sourced to configure the environment in each session where you want to use the toolchain. If you want to always have the toolchain available and configured, you can add sourcing of cxlb-toolchain-user-conf in your ~/.profile.

Also, once finished, two files are generated in install/share/cxlb-build-toolchain:

• build.log contains the full log of the build
• build.bundle lists the exact versions of all which was compiled and installed in the toolchain.

You can build the exact same toolchain as the one in CorteXlab using the bundle file.

The bundle file of the current CorteXlab toolchain can be found on airlock in /cortexlab/toolchains/current/share/cxlb-build-toolchain/build.bundle. It can be used as input of cxlb-build-toolchain to build on your workstation a toolchain with the exact same versions of everyhting.