Cortexlab users do not have direct access to the cortexlab radio nodes. They have to package their experiment in a minus scenario and launch it from the frontend (airlock).

This is simple as long as the scenario is made, for example, from simple python scripts or static binaries, using the right version of libraries and/or gnuradio than installed on the nodes. But things get more complex as soon as users want to make use of:

1. gnuradio version different from the version on the nodes
2. executable binaries relying on shared libraries which are not installed on the cortexlab nodes (uncommon libraries or custom libraries)
3. executables binaries relying on versions of shared libraries which are not present on on the cortexlab nodes (perhaps because the binaries where compiled on a different operating system, or a different version of the same operating system.
4. gnuradio “Out Of Tree” (OOT) modules, that is, custom gnuradio components (blocks, and possibly associated gnuradio-companion block metadata) which are not install on the cortexlab nodes. These OOT modules may rely themselves on other gnuradio version, custom binaries or libraries not installed on the nodes, or with the wrong version, such as in (1), (2), (3).

There are a few ways to tackle these problems.

There is basically no way to avoid this issue: users need to target the same gnuradio version than the one on the cortexlab nodes.

Actually this is not only about gnuradio, but about the whole package of software used to run the radio on the nodes. We refer to this package as the cortexlab toolchain. It is made of:

• 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.

There is currently three possibilities for working with the same version of toolchain than the one on the cortexlab nodes:

• use the cortexlab toolchain which is installed on the airlock frontend. It is the exact same toolchain as on the nodes, the only difference is that there is no hardware (usrp, picosdr, jtag) connected to the frontend.
• build a cortexlab toolchain on a user's workstation. We provide the cxlb-build-toolchain tool, which is the tool that we use to build the toolchain on the nodes. This tool is limited to 64 bit linux and is tested only under debian. For each toolchain built with this tool, a bundle file is written in the toolchain directory, which tracks all exact versions of all packages included in the toolchain. The bundle file for the current cortexlab toolchain can be found on airlock in /cortexlab/toolchains/current/share/cxlb-build-toolchain/build.bundle. This file can be used as input to cxlb-build-toolchain to be sure to build the exact same toolchain. cxlb-build-toolchain also provides options to select which parts of the toolchain to build. For example, a user willing to experiment only on usrp won't need to include the picosdr specific stuff.
• build the same version of gnuradio than on airlock, without using our cxlb-build-toolchain script. In this case, users are on their own. In the majority of situation this should cause no issue but there may be some slight incompatibilities with the toolchain on the nodes.

Besides, the main advantage of the cxlb-build-toolchain is that it takes care to install everything in a given directory, as regular user. It then generates and installs two scripts, one that has to be run by 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.
• thus,you are sure that it does not conflict with anything in the regular directory tree structure of your system. In particular, it cannot conflit with the debian package system.
• everything from the toolchain is kept isolated in the toolchain install directory, instead of being scattered everywhere.
• it is possible to have more than one toolchain 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).

Ususally, one compiles an executable binary or library on the same system it will run on, and installs it in its final location. The difficulty when packaging such binaries in a minus task scenario is that it's not longer the case:

• one may compile on its own workstation (we assume a 64 bits linux workstation, preferably with the same toolchain as the cortexlab toolchain, see previous section). In this case, there may be some difference between the library versions of the compilation environment (the workstation) and the execution environment (the cortexlab radio node). It may sometimes work, sometimes not. Chances are better if the workstation runs the same operation system as the cortexlab nodes. Cortexlab nodes run debian stable (currently debian jessie)
• one may compile on airlock. airlock runs the same operating system with the same libraries as the the radio nodes, so we are sure that it should work on the nodes.

The last issue is that we need to configure the compilation of the binaries such that the install location of the binaries is the final location where they will be executed, on the radio nodes, but we will need to install them first into a staging area where we will assemble our task file. This is the concept of a staged install which tools such as automake or cmake support. Unfortunately, some other build systems (especially adhoc makefiles) will perhaps not directly support that functionnality and will need a bit of hacking to be able to do that.

The location on the cortexlab nodes where the task will be unpacked and executed is /home/cxlbuser/tasks/task

Thus, the compilation / stage installation of a custom binary in a minus task scenario has the following scheme, assuming that the task is assembled in directory /cortexlab/homes/<userlogin>/tasks/mytask and that the temporary staging directory for compiled binaries is /cortexlab/homes/<userlogin>/tasks/mytask/tmp

(in the following, we assume that we compile directly on airlock)

$ ./configure --prefix=/home/cxlbuser/tasks/task
$ make
$ make DESTDIR=/cortexlab/homes/<userlogin>/tasks/mytask/tmp install

$ cmake -DCMAKE_INSTALL_PREFIX=/home/cxlbuser/tasks/task
$ make
$ make DESTDIR=/cortexlab/homes/<userlogin>/tasks/mytask/tmp install

Then, in both cases, we will find in /cortexlab/homes/<userlogin>/tasks/mytask/tmp the complete directory hierarchy /cortexlab/homes/<userlogin>/tasks/mytask/tmp/home/cxlbuser/tasks/task and directories such as usr, share, include, etc. below. Now we simply have to move this up to the toplevel of the task:

$ mv /cortexlab/homes/<userlogin>/tasks/mytask/tmp/home/cxlbuser/tasks/task/* /cortexlab/homes/<userlogin>/tasks/mytask/
$ rm -rf /cortexlab/homes/<userlogin>/tasks/mytask/tmp

Then we can assemble our task:

$ minus task create /cortexlab/homes/<userlogin>/tasks/mytask

If we compile on a workstation instead of airlock, the steps are identical except that the task directory has be be transfered to airlock before running minus task create on airlock

A gnuradio OOT module is just a special case of custom binary, as described in the previous section.

The gnuradio build system is designed to allow building OOT gnuradio modules easily. For this, users need to use gr_modtool to create their module.

gr_modtool will generate a cmake project which will automatically detect gnuradio, if running cmake from airlock (using the cortexlab toolchain instance on airlock), or from a user's workstation, with a gnuradio built with cxlb-build-toolchain and a properly configured environment.

Then, as described in the previous section, run cmake and install this way:

$ cmake -DCMAKE_INSTALL_PREFIX=/home/cxlbuser/tasks/task
$ make
$ make DESTDIR=/cortexlab/homes/<userlogin>/tasks/mytask/tmp install
$ mv /cortexlab/homes/<userlogin>/tasks/mytask/tmp/home/cxlbuser/tasks/task/* /cortexlab/homes/<userlogin>/tasks/mytask/
$ rm -rf /cortexlab/homes/<userlogin>/tasks/mytask/tmp

The most complex situation is when you need to embed into a minus task a binary (be it a gnuradio OOT module, an executable or a library) which depends itself from other binaries (libraries, most of the time) which need to be also embedded in the minus task. These dependency chains may be longer (eg. OOT module A depends on library B, which depends on library C and D, and library C depends on D also, as well as on library E).

In this situation, you need to compile everything in reverse order starting from the end of the chain (the libraries which have no custom dependencies. In the previous example, the order would be E, D, C, B, A). The challenge is to be able to tell following libraries (in the order of compilation) where to find previous ones includes (for compilation) and libs (for linking)

explain how to, when compiling D, telling it where to find E