View source for 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 <tt>/usr/local</tt>.
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 <tt>~/install</tt>. 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 <tt>sudo</tt> when doing the traditional <tt>sudo make install</tt> (simply <tt>make install</tt> 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 <tt>~/src/<module name></tt> and you wish to place the built module under <tt>~/build/<module name></tt>

 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 [http://svn.spench.net/main/gr-baz/apps/subenv subenv] script in [[gr-baz]] that can be invoked to do this. Simply copy the script into your <tt>~/bin</tt> directory, add execute permissions to it (i.e. <tt>chmod +x subenv</tt>) and then invoke as follows:

 subenv <module name>

This will prepend the appropriate module subdirectories to your <tt>LD_LIBRARY_PATH</tt>, <tt>PYTHONPATH</tt> and <tt>PATH</tt> 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 <tt>~/.bashrc</tt> or equivalent:

<syntaxhighlight lang="bash">
if [ -n "$SUBENV" ]; then
    PS1="\e[1;31m$SUBENV\e[m $PS1"
fi
</syntaxhighlight>

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 [http://docs.python.org/2/library/site.html sitecustomize] feature to inject the alternate module into the GNU Radio (<tt>gnuradio</tt>) namespace, which in effect hides the normal existing installation of the module.

This is done by the <tt>sitecustomize.py</tt>, 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 [http://svn.spench.net/main/gr-baz/patch/op25/sitecustomize.py specific example] for [[OP25]]):

<syntaxhighlight lang="python">
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
</syntaxhighlight>

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

<syntaxhighlight lang="python">
 from gnuradio import op25
</syntaxhighlight>

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

<!--
Could also:

<syntaxhighlight lang="python">
from gnuradio import op25 as op25_original
...
gnuradio.op25_original = op25_original
</syntaxhighlight>
-->

{{RF}}