Cellular Network Infrastructure

{{>toc}}

h1. Build from Source

bq. *Before you consider building from source, be aware that there are [[Binary Packages]]

available for Debian + Ubuntu platforms. These are recommended for normal users.*

Osmocom projects use autoconf/automake.

The general pattern for building is:

<pre>

cd source-tree

autoreconf -fi

export PKG_CONFIG_PATH="$PKG_CONFIG_PATH:/usr/local/lib/pkgconfig"

./configure

make

make check

sudo make install

sudo ldconfig

</pre>

The @./configure@ step may need further configuration options, and

@./configure@ will tell you which dependencies are still missing, if any.

See below for project specific details and troubleshooting.

The @make@ step may be sped up by using multiple CPU cores:

<pre>

make -j 8

</pre>

We take care to make our builds parallelizable with @-j@, but in case

@make -j@ fails, issuing a simple @make@ could fix the problem.

h1. Dependencies

Which libraries are needed by various Osmocom programs is best resolved during

the @./configure@ step described below. This script checks for any missing

dependencies and issues corresponding error messages.

Here is a (probably incomplete) overview of dependencies between Osmocom

projects:

| _To build ..._ | _... you also need ..._ |

| osmo-bts | libosmocore, libosmo-abis, openbsc (source tree only), L1 headers depending on BTS model |

| osmo-pcu | libosmocore, L1 headers depending on BTS model |

| osmo-hlr | libosmocore, libosmo-abis |

| osmo-mgw | libosmocore, libosmo-abis, libosmo-netif |

| osmo-msc | libosmocore, libosmo-abis, libosmo-netif, libosmo-sccp, osmo-mgw (for libosmo-mgcp-client), libsmpp34 (for --enable-smpp); for 3G, use --enable-iu and add: osmo-iuh, libasn1c |

| osmo-bsc | libosmocore, libosmo-abis, libosmo-netif, libosmo-sccp, osmo-mgw (for libosmo-mgcp-client) |

| osmo-sgsn | libosmocore, osmo-ggsn; for 3G, use --enable-iu and add: osmo-iuh, libasn1c |

| osmo-ggsn | libosmocore |

| osmo-sip-connector | libosmocore |

h1. External dependencies

If you want to build on specific Linux distros, you might need to install additional dependencies before the build will succeed

-- this is a collection of various dependencies used by various osmocom projects:

| _To build on ..._ | _...you might need to install these packages:_ |

|Ubuntu 16.10 | libpcsclite-dev libtalloc-dev libortp-dev libsctp-dev libmnl-dev libdbi-dev libdbd-sqlite3 libsqlite3-dev sqlite3 libc-ares-dev libgnutls-dev |

|Debian 8 and 9| build-essential gcc g++ make automake autoconf libtool pkg-config libtalloc-dev libpcsclite-dev libortp-dev libsctp-dev libssl-dev libdbi-dev libdbd-sqlite3 libsqlite3-dev libpcap-dev libc-ares-dev libgnutls28-dev libsctp-dev sqlite3 libsofia-sip-ua-glib-dev|

|FreeBSD 11|automake autoconf libtool git pkgconf talloc pcsc-lite python gmake ortp|

|Fedora 28|@development-tools autoconf automake gnutls-devel libtool libtalloc-devel pcsc-lite-devel ortp-devel openssl-devel lksctp-tools-devel libmnl-devel libdbi-devel libdbi-dbd-sqlite libpcap-devel sqlite-devel gcc-g++ uhd-devel libusb-devel fftw-devel boost-devel|

h1. Download Sources

The latest Osmocom sources are available from git at https://git.osmocom.org,

where each project's overview page displays the actual git URL.

The projects' repository URLs generally are of the pattern:

<pre>git://git.osmocom.org/project-name</pre>

(To contribute, see [[Coding Standards#Submitting-Patches|Submitting Patches]])

For example, to verify libosmocore's git repository URL, browse to

https://git.osmocom.org/libosmocore/ and observe the URL shown at the

bottom of the page under _Clone_: @git://git.osmocom.org/libosmocore@

Then download this URL using the @git@ client:

<pre>

git clone git://git.osmocom.org/libosmocore

</pre>

It is also possible to download specific releases' tarballs for each git ref

that is defined. For example, browse to https://git.osmocom.org/libosmocore/,

click on _refs_ on the top and select any branch or tag, e.g. "0.9.0":https://git.osmocom.org/libosmocore/tag/?h=0.9.0

All of these download instructions hold true for any of the git repositories,

not limited to libosmocore.

h1. Build debian packages

Most Osmocom projects are setup and ready for building debian packages.

See the @debian/@ subdir in each source tree.

For example, to build a libosmocore debian package:

<pre>

cd libosmocore/

dpkg-buildpackage -tc -uc -us

# then, you can install the package on your system with

sudo dpkg -i ../libosmocore*.deb

</pre>

These steps are identical for all other Osmocom projects that are ready for debian packaging.

Advantages of debian packages:

* they allow you to easily install the same binaries on several machines,

* you don't need to keep the source tree around,

* they guarantee a clean de-installation later.

Note: when not using debian packages, i.e. after a '@make install@' directly from the source tree,

you can also achieve a clean de-installation with '@make uninstall@'.

h1. Details and Troubleshooting

Here is a list of the most common configuration items or pitfalls to be

aware of when building specific Osmocom projects.

h2. Non-GNU Systems

On systems like FreeBSD, you need to run @gmake@ instead of @make@.

h2. Cross-Compiling for a BTS Platform

To build new software for the sysmoBTS and Litecell 1.5, you will typically

cross-compile using an SDK matching the BTS. You should find specific instructions

in, for example, the sysmoBTS manual.

h2. General ./configure options

To provide the installation location, which is /usr/local by default:

<pre>

./configure --prefix=$HOME/my_osmocom_inst

</pre>

If you choose a non-standard location, later builds may fail to find it.

For example, if you built libosmocore with a custom prefix, a subsequent

build of libosmo-abis, which needs libosmocore installed, may fail.

You can tell a build process where to look for libraries to compile against

using the @PKG_CONFIG_PATH@ environment variable.

Furthermore, when you want to run binaries compiled against libraries

installed in a non-standard location, you will have to use the

@LD_LIBRARY_PATH@ environment variable to successfully load the binary.

Particularly, the @make check@ step typically runs such binaries,

as well as when you would like to run the installed binaries yourself.

For example:

<pre>

mkdir -p $HOME/osmo/src

cd $HOME/osmo/src

git clone git://git.osmocom.org/libosmocore

cd libosmocore

autoreconf -fi

./configure --prefix=$HOME/osmo/inst --disable-pcsc

make -j5

make check

make install

sudo ldconfig

cd ..

git clone git://git.osmocom.org/libosmo-abis

cd libosmo-abis

autoreconf -fi

export PKG_CONFIG_PATH=$HOME/osmo/inst/lib/pkgconfig

./configure --prefix=$HOME/osmo/inst

make -j5

export LD_LIBRARY_PATH=$HOME/osmo/inst/lib

make check

make install

sudo ldconfig

</pre>

Note that PKG_CONFIG_PATH points at the prefix's lib/pkgconfig and is needed

during the configure step of a library;

And that LD_LIBRARY_PATH is needed when running binaries that need libraries

installed in the non-standard location, here via @make check@.

Furthermore, when installing to an SDK's sysroot location, you would usually

set @DESTDIR@ to the sysroot with @--prefix=/usr@, resulting in an install

location of @$DESTDIR/usr@.

h2. libosmocore

When @libpcsclite@ is not easily available, e.g. when building for a BTS target platform:

<pre>

./configure --disable-pcsc

</pre>

h2. openbsc

@openbsc@ is so far the only source tree where the build commands must be run

a level deeper than the source tree's root. Enter the second @openbsc@ dir:

<pre>

git clone git://git.osmocom.org/openbsc

cd openbsc/openbsc

autoreconf -fi

[...]

</pre>

h2. osmo-msc and osmo-sgsn for 3G

Be sure to pass the @--enable-iu@ configure option to enable Iu interface support.

<pre>

cd osmo-msc

./configure --enable-iu

</pre>

h1. Example: completely build osmo-bsc, osmo-msc, osmo-sgsn and osmo-ggsn

This is an example of a complete build process for 2G+3G core network,

including SMPP and the "nat" binaries, to the @/usr/local@ prefix; it is assumed

that your system by default scans @/usr/local@ for installed libraries:

If you don't require 3G, you can omit build of osmo-iuh and remove configure flag "--enable-iu" in osmo-msc and osmo-sgsn.

<pre>

osmo_src=$HOME/osmo/src

mkdir -p $osmo_src

cd $osmo_src

git clone git://git.osmocom.org/libosmocore

cd libosmocore

autoreconf -fi

./configure

make -j5

make check

make install

sudo ldconfig

cd $osmo_src

git clone git://git.osmocom.org/libosmo-abis

cd libosmo-abis

autoreconf -fi

./configure

make -j5

make check

make install

sudo ldconfig

cd $osmo_src

git clone git://git.osmocom.org/libosmo-netif

cd libosmo-netif

autoreconf -fi

./configure

make -j5

make check

make install

sudo ldconfig

cd $osmo_src

git clone git://git.osmocom.org/libosmo-sccp

cd libosmo-sccp

autoreconf -fi

./configure

make -j5

make check

make install

sudo ldconfig

cd $osmo_src

git clone git://git.osmocom.org/libsmpp34

cd libsmpp34

autoreconf -fi

./configure

make

make check

make install

sudo ldconfig

cd $osmo_src

git clone git://git.osmocom.org/osmo-mgw

cd osmo-mgw

autoreconf -fi

./configure

make -j5

make check

make install

sudo ldconfig

cd $osmo_src

git clone git://git.osmocom.org/libasn1c

cd libasn1c

autoreconf -fi

./configure

make

make check

make install

sudo ldconfig

cd $osmo_src

git clone git://git.osmocom.org/osmo-iuh

cd osmo-iuh

autoreconf -fi

./configure

make -j5

make check

make install

sudo ldconfig

cd $osmo_src

git clone git://git.osmocom.org/osmo-msc

cd osmo-msc

autoreconf -fi

./configure --enable-iu

make -j5

make check

make install

sudo ldconfig

cd $osmo_src

git clone git://git.osmocom.org/osmo-ggsn

cd osmo-ggsn

autoreconf -fi

./configure

make -j5

make check

make install

sudo ldconfig

cd $osmo_src

git clone git://git.osmocom.org/osmo-sgsn

cd osmo-sgsn

autoreconf -fi

./configure --enable-iu

make -j5

make check

make install

sudo ldconfig

export LD_LIBRARY_PATH="/usr/local/lib"

export PATH="$PATH:/usr/local/bin"

which osmo-msc

osmo-msc --version

</pre>

h1. Example: build script

This is a shell script that builds openbsc and osmo-ggsn,

expecting the git clones to be ready in the current directory:

attachment:build_2G.sh

h1. Example: top-level Makefile

I (neels) use a top-level makefile to manage various configurations and build all source trees in sequence.

See https://git.osmocom.org/osmo-dev and look at the readme file.

h1. Example: script for cloning and building a single project

<pre>

#!/bin/sh -e

# Location where the git repositories will be stored (must exist)

DIR=~/code

# Check usage

if [ -z "$1" ]; then

	echo "usage: $(basename $0) PROJECT"

	exit 1

fi

# Clone

cd $DIR

if ! [ -d "$1" ]; then

	git clone "git://git.osmocom.org/$1"

fi

# Build

export PKG_CONFIG_PATH="$PKG_CONFIG_PATH:/usr/local/lib/pkgconfig/"

cd $1

autoreconf -fi

./configure

make -j3

make check

sudo make install

sudo ldconfig

</pre>