CorteXlab's Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Embedding OOT modules or custom libraries/binaries in a minus scenario ======

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:

  -gnuradio version different from the version on the nodes
  -executable binaries relying on shared libraries which are not installed on the cortexlab nodes (uncommon libraries or custom libraries)
  -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.
  -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.

===== gnuradio version / toolchain version =====

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**. See [[Building a toolchain]]

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 [[https://github.com/CorteXlab/cxlb-build-toolchain|cxlb-build-toolchain]] tool, which is the tool that we use to build the toolchain on the nodes. See [[Building a toolchain]].
* 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.

===== Packaging executable binaries or libraries in a minus task scenario =====

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 [[https://www.debian.org|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 [[https://www.gnu.org/prep/standards/html_node/DESTDIR.html#DESTDIR|staged install]] which tools such as [[https://www.gnu.org/software/automake/manual/html_node/DESTDIR.html|automake]] or [[https://cmake.org/cmake/help/v3.0/variable/CMAKE_INSTALL_PREFIX.html|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'')

== For autotools project ==

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

== For cmake project ==

  $ 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''
==== gnuradio Out Of Tree (OOT) modules ====

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 [[https://gnuradio.org/redmine/projects/gnuradio/wiki/OutOfTreeModules|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 [[https://github.com/CorteXlab/cxlb-build-toolchain|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

==== multiple chained dependencies ====

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)

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