PyBOMBS

PyBOMBS is good at building GNU Radio, UHD, and various Out of Tree (OOT) modules from source and then installing into a specified user directory rather than in the system files. PyBOMBS detects the user's Operating System and loads all of the prerequisites in the first stage of the build.

For those looking to dive right in, the following commands should install PyBOMBS and GNU Radio version 3.10 (from source) into a directory called ~/prefix-3.10 and was verified to work under a fresh Ubuntu 20.04 and 22.04 install.

sudo apt-get install python3-pip
sudo pip3 install pybombs
pybombs auto-config
pybombs recipes add-defaults
pybombs prefix init ~/prefix-3.10 -R gnuradio-default
source ~/prefix-3.10/setup_env.sh
gnuradio-companion

Because it's installing GNU Radio from source, the 5th step might take some time, for a quicker install see https://wiki.gnuradio.org/index.php/InstallingGR#Ubuntu_PPA_Installation.

Installing PyBOMBS
Executing PyBOMBS
Prefixes
Installing packages
Recipes
Configuration Files
git cache (reference repository)
License

<a name="install"></a>Installing PyBOMBS

Open a terminal window.

The commands given below containing 'apt' are ones for Debian, Ubuntu, and derivatives. For other operating systems:

Fedora - use dnf
RHEL/CentOS - use yum
Archlinux - use pacman
Check with your OS documentation for specific syntax.

If you don't have 'git', run the following command:

sudo apt install git

Using pip

You don't have to clone the PyBOMBS repository if you don't plan to contribute to PyBOMBS yourself.

Using Python2.7

If you do not have Python2.7, run the following commands:

sudo apt install python
sudo apt install python-pip

If you have previously installed PyBOMBS with Python3, run the following command:

sudo pip3 uninstall pybombs

and then run:

sudo pip install --upgrade git+https://github.com/gnuradio/pybombs.git

Using Python3

If you have previously installed PyBOMBS with Python2, run the following command:

sudo pip uninstall pybombs

<b>Note:</b> If you are building UHD-3.14 or previous, run the following commands:

sudo apt install python
sudo apt install python-pip
sudo pip install mako requests numpy

If you don't already have python3, run the following commands:

sudo apt install python3
sudo apt install python3-pip

and then run:

sudo pip3 install --upgrade git+https://github.com/gnuradio/pybombs.git

From source using Python's setuptools

To clone the PyBOMBS source code, enter:

<pre> cd ~/ git clone https://github.com/gnuradio/pybombs.git cd ~/pybombs </pre>

then, to build in user's directory, run:

python setup.py build

or, to install in the system directory, run:

sudo python setup.py install

This will install PyBOMBS and all required dependencies. See

python setup.py build --help
python setup.py install --help

for additional settings.

<a name="executing"></a>Executing PyBOMBS

Recipes

There are several gnuradio recipes for use with the pybombs prefix command:

gnuradio38 builds GNU Radio 3.8 from the maint-3.8 branch
gnuradio39 builds GNU Radio 3.9 from the maint-3.9 branch
gnuradio310 builds GNU Radio 3.10 from the maint-3.10 branch
gnuradio-default builds the latest maintenance branch (currently maint-3.10)
gnuradio-main builds GNU Radio's main branch

In the following instructions, the notation {your_recipe} denotes your choice of recipe.

Folder/directory (prefix) definition

One of the main advantages of using PyBOMBS is the ability to specify a folder/directory within the user's account to contain all the files associated with the build. That allows the user to delete that one folder/directory and thereby remove everything associated with the build. No system files are affected.

In the following instructions, the notation {base_folder} denotes where to put the top level folder/directory. For example <code>~/gr38</code>. See more information in the Prefixes section below.

Platform-specific instructions

Platforms that require special attention are listed here:

To run PyBOMBS

Install PyBOMBS per the previous section.
Apply a default configuration:
```
 pybombs auto-config
```
Add a list of recipes, e.g., the default recipes:
```
 pybombs recipes add-defaults
```
Install GNU Radio into your selected directory (the alias parameter is optional):
```
 pybombs prefix init ~/{base_folder} -R {your_recipe}
```
<b>Wait</b>. The terminal will show the progress.
Run GNU Radio Companion from your new folder:
```
 source ~/{base_folder}/setup_env.sh
 gnuradio-companion
```
or execute it without changing the current environment:
```
 pybombs run gnuradio-companion
```

<a name="prefixes"></a>Prefixes

A prefix is a directory into which packages are installed.

The prefix may be ~/prefix. Typically, the prefix resides inside your home directory so you can modify or delete prefixes easily without admin access. This is the recommended way of running PyBOMBS. Any directory may be a prefix, but it is highly recommended to choose a dedicated directory for this purpose.

Many developers have multiple prefixes. Instead if installing to ~/prefix, a common way is to have multiple prefixes, e.g., ~/prefix/default_prefix, ~/prefix/dev_prefix, etc.

Prefixes require a configuration directory to function properly. Typically, it is called .pybombs/ and is a subdirectory of the prefix. So, if your prefix is ~/prefix, there will be a directory called ~/prefix/.pybombs/ containing special files. The two most important files are the inventory file (inventory.yml) and the prefix-local configuration file (config.yml), but it can also contain recipe files that are specific to this prefix.

There is no limit to the number of prefixes. Indeed, it may make sense to have many prefixes, e.g. one for system-wide installation, one for a user-specific installation, and one for cross-compiling to a different platform.

When running PyBOMBS, you select the desired prefix using the -p switch. You can set a default prefix with the following command:

pybombs config default_prefix {prefix_name}

The first time you run pybombs prefix init, it will set this value for you.

Prefix Selection

Prefixes are selected by the following rules, in this order:

Whatever is provided by the -p or --prefix command line switch
The current directory
The default prefix as defined by the default_prefix config switch

If no prefix can be found, most PyBOMBS operations will not be possible, but some will still work (for example, you can install all dependencies for a package from binary sources).

Initializing Prefixes

Any directory can function as a prefix, and PyBOMBS will make sure all the required files and directories are created. However, PyBOMBS provides a way to initialize a directory to be a full PyBOMBS prefix:

pybombs prefix init /path/to/prefix [-a alias]

This is similar to git init. The optional alias allows you to access the prefix with the alias instead of the full path. A typical value for the default prefix is ~/prefix/default, and then other prefixes also reside in ~/prefix alongside the default prefix.

After initializing a prefix, you can start to install to this prefix using the install command:

pybombs -p <alias> install <package>

PyBOMBS provides a way to not only initialize a raw prefix, but also configure it and install packages through a prefix recipe. These are selected using the -R switch on the command line:

pybombs prefix init /path/to/prefix [-a alias] [-R prefix-recipe]

Aliases

An alias is an optionally assigned name to provide a short substitute for a prefix path. It can be created in one of two ways:

in the pybombs prefix init command, adding -a {alias_name} will equate the ~/{base_folder} with {alias_name}.
by adding a [prefix_aliases] section in a configuration file. The format is alias=/path/to/prefix. Once an alias is defined, it can be used in a command such as pybombs -p {alias_name} install <package> in place of the prefix path.

Configuring a prefix environment (e.g. for cross-compiling)

Setting environment variables directly:

For a quick setup of environment variables, you can use the pybombs config command:

pybombs config --env CC clang
pybombs prefix env
# ...lots of output...
CC=clang
# ...lots of output...

This will, by default, set an environment variable for all prefixes. You might want to set it for a specific one, in that case, specify the prefix:

pybombs -p default config --env CC clang

You can also edit the config files directly. In any config file that is read, a env: section can be added. This will set environment variables for any command (configure, build, make...) that is run within PyBOMBS.

Note that this will still use the regular system environment as well, but it will overwrite existing variables. Variable expansion can be used, so this will keep the original setting:

env:
    LD_LIBRARY_PATH: ${LD_LIBRARY_PATH}:/path/to/more/libs

Note: Because this is a YAML file, remember to separate key/value pairs with colon (:), not an equals sign, as you would in a shell script.

In all cases, the environment variable PYBOMBS_PREFIX is set to the current prefix, and PYBOMBS_PREFIX_SRC is set to the source directory.

Use pybombs prefix env to show all environment variables as they would appear when commands are run inside the prefix.

Using an external script to set the environment

Inside the config section, a shell script can be defined that sets up an environment, which will the

Pybombs

Install / Use

README