Side-by-side GNU Radio Modules

Motivation

You may encounter the situation where you wish to have multiple versions of the same GNU Radio module installed. By default, they usually are installed under /usr/local. When you configure your build system, you have the option of altering the install prefix and therefore have the module installed to an alternate location. The problem with setting up an alternate location is that you then need to make your execution environment aware of the additional places it needs to search for the module's various parts (e.g. the shared object, Python wrappers, etc).

One common place to install modules to is ~/install. This keeps the modules within your home directory and doesn't pollute the general filesystem.

Note: if you choose a location under your home directory, you do not need to use sudo when doing the traditional sudo make install (simply make install will suffice).

Build System

You can change the default install prefix as follows:

Automake

./configure --prefix=/home/<your username>/install/<module name>

CMake

It is good practice to use a separate build directory. For example: assume the module's source is in ~/src/<module name> and you wish to place the built module under ~/build/<module name>

cd ~/build/<module name>
cmake ~/src/<module name> -DCMAKE_INSTALL_PREFIX=/home/<your username>/install<module name>

Alternate environment

Once you have compiled and installed your module to its alternate location, you still need to set up the environment so that the module's components will be found.

The subenv script in gr-baz that can be invoked to do this. Simply copy the script into your ~/bin directory, add execute permissions to it (i.e. chmod +x subenv) and then invoke as follows:

subenv <module name>

This will prepend the appropriate module subdirectories to your LD_LIBRARY_PATH, PYTHONPATH and PATH environment variables.

Note: there are some internal variables that need to be set inside the script if your environment differs from the common one. Notably:

PYTHON_VER=2.7
BASE_PATH="$HOME/install/$MODULE"

It is also handy to display at the prompt that you are inside an active sub-environment. To do this, modify you ~/.bashrc or equivalent:

if [ -n "$SUBENV" ]; then
    PS1="\e[1;31m$SUBENV\e[m $PS1"
fi

This will cause the current module name to be prepended to the shell prompt in red when it is active.

Python sitecustomize

The final step (specific to GNU Radio) is important if you already have an existing installation of the module in the default location (i.e. it is installed alongside the normal GNU Radio installation).

Therefore it is necessary to tell Python where the alternate module can be found (outside the normal GNU Radio installation) by using Python's sitecustomize feature to inject the alternate module into the GNU Radio (gnuradio) namespace, which in effect hides the normal existing installation of the module.

This is done by the sitecustomize.py, which is automatically interpreted during Python start-up. The file should be placed (depending on your Python version) at:

<module installation path>/lib/python2.7/site-packages/sitecustomize.py

It should contain something like (here is a specific example for OP25):

import os

_sc_path = os.path.abspath( __file__ )
try:
	print "Customising for:", _sc_path.split(os.sep)[-5]
except:
	print "[!] Customising for:", _sc_path

_gr_base_path = None
try:
	_gr_base_path = os.path.dirname(_sc_path)
	sys.path = [os.path.join(_gr_base_path, 'gnuradio')] + sys.path   # Add 'gnuradio' sub-directory to module search path if your module is installed there
except:
	print "Failed to add gnuradio in sitecustomize:", _gr_base_path

import <module name>                     # This must come first!
import gnuradio
gnuradio.<module name> = <module name>   # This injects the alternate module into the GR namespace, thereby hiding the existing one

It is necessary to do this as existing code that does the following:

 from gnuradio import op25

will now have access to the module in the alternate location. Without sitecustomize.py it would still import the existing normal installation inside GNU Radio.