This page is valid on tags starting from **`2019.w09`**.
# Soft Modem Build Script
# Overview
The OAI EPC is developed in a distinct project with it's own [documentation](https://github.com/OPENAIRINTERFACE/openair-epc-fed/wiki) , it is not described here.
The [OAI EPC](https://github.com/OPENAIRINTERFACE/openair-epc-fed/blob/master/docs/DEPLOY_HOME_MAGMA_MME.md) and [OAI 5GC](https://gitlab.eurecom.fr/oai/cn5g/oai-cn5g-fed/-/blob/master/docs/DEPLOY_HOME.md) are developed in distinct projects with their own documentation and are not further described here.
OAI softmodem sources, which aim to implement 3GPP compliant UEs, eNodeB and gNodeB can be downloaded from the Eurecom [gitlab repository](./GET_SOURCES.md).
Sources come with a build script [build_oai](../cmake_targets/build_oai) located at the root of the `openairinterface5g/cmake_targets` directory. This script is developed to build the oai binaries (executables,shared libraries) for different hardware platforms, and use cases.
Sources come with a build script [build_oai](../cmake_targets/build_oai) located at the root of the `openairinterface5g/cmake_targets` directory. This script is developed to build the oai binaries (executables,shared libraries) for different hardware platforms, and use cases.
The main oai binaries, which are tested by the Continuous Integration process are:
...
...
@@ -28,36 +28,57 @@ The main oai binaries, which are tested by the Continuous Integration process ar
- The 5G UE: `nr-uesoftmodem`
- The LTE eNodeB: `lte-softmodem`
- The 5G gNodeB: `nr-softmodem`
- The 5G CU-UP: `nr-cuup`
- The LTE PHY simulators: `dlsim` and `ulsim`
- The 5G PHY simulators: `nr_dlschsim``nr_dlsim``nr_pbchsim``nr_pucchsim``nr_ulschsim``nr_ulsim``polartest``smallblocktest`
Running the [build_oai](../cmake_targets/build_oai) script also generates some utilities required to build and/or run the oai softmodem binaries:
-`conf2uedata`: a binary used to build the UE data from a configuration file. The created file emulates the sim card of a 3GPP compliant phone.
-`nvram`: a binary used to build UE (IMEI...) and EMM (IMSI, registered PLMN) non volatile data.
-`rb_tool`: radio bearer utility
-`genids` T Tracer utility, used at build time to generate T_IDs.h include file. This binary is located in the [T Tracer source file directory](../common/utils/T) .
-`conf2uedata`: a binary used to build the (4G) UE data from a configuration file. The created file emulates the sim card of a 3GPP compliant phone.
-`nvram`: a binary used to build (4G) UE (IMEI...) and EMM (IMSI, registered PLMN) non volatile data.
-`rb_tool`: radio bearer utility for (4G) UE
-`genids` T Tracer utility, used at build time to generate `T_IDs.h` include file. This binary is located in the [T Tracer source file directory](../common/utils/T) .
The build system for OAI uses [cmake](https://cmake.org/) which is a tool to generate makefiles. The `build_oai` script is a wrapper using cmake, make and standard linux shell commands to ease the oai build and use . The file describing how to build the executables from source files is the [CMakeLists.txt](../CMakeLists.txt), it is used as input by cmake to generate the makefiles.
The build system for OAI uses [cmake](https://cmake.org/) which is a tool to generate makefiles. The `build_oai` script is a wrapper using `cmake` and `make`/`ninja` to ease the oai build and use. It logs the `cmake` and `ninja`/`make` commands it executes. The file describing how to build the executables from source files is the [CMakeLists.txt](../CMakeLists.txt), it is used as input by cmake to generate the makefiles.
The oai softmodem supports many use cases, and new ones are regularly added. Most of them are accessible using the configuration file or the command line options and continuous effort is done to avoid introducing build options as it makes tests and usage more complicated than run-time options. The following functionalities, originally requiring a specific build are now accessible by configuration or command line options:
- s1, noS1
- all simulators as the rfsimulator, the L2 simulator, with exception of PHY simulators, which are distinct executables.
# Running `build_oai`
Calling the `build_oai` script with the -h option gives the list of all available options, but a process to simplify and check the requirements of all these options is on-going. Check the [table](BUILD.md"# `build_oai` options") At the end of this page to know the status of `buid_oai` options which are not described hereafter.
## List of options
# Building PHY Simulators
Calling the `build_oai` script with the `-h` option gives the list of all available options. A number of important ones:
The PHY layer simulators (LTE and NR) can be built as follows:
- The `-I` option is to install pre-requisites, you only need it the first time you build the softmodem or when some oai dependencies have changed.
- The `-w` option is to select the radio head support you want to include in your build. Radio head support is provided via a shared library, which is called the "oai device" The build script creates a soft link from `liboai_device.so` to the true device which will be used at run-time (here the USRP one, `liboai_usrpdevif.so`). The RF simulator[RF simulator](../radio/rfsimulator/README.md) is implemented as a specific device replacing RF hardware, it can be specifically built using `-w SIMU` option, but is also built during any softmodem build.
-`--eNB` is to build the `lte-softmodem` executable and all required shared libraries
-`--gNB` is to build the `nr-softmodem` and `nr-cuup` executables and all required shared libraries
-`--UE` is to build the `lte-uesoftmodem` executable and all required shared libraries
-`--nrUE` is to build the `nr-uesoftmodem` executable and all required shared libraries
-`--ninja` is to use the `ninja` build tool, which speeds up compilation.
-`-c` is to clean the workspace and force a complete rebuild.
## Installing dependencies
Install all dependencies by issuing the `-I` option. To install furthermore libraries for optional libraries, use the `--install-optional-packages` option. The `-I` option will also install dependencies for an SDR when paired with `-w`. For instance, in order to install all dependencies and the ones for USRP, run:
```bash
cd openairinterface5g/cmake_targets/
./build_oai -I--install-optional-packages-w USRP
```
cd <your oai installation directory>/openairinterface5g/
source oaienv
cd cmake_targets/
./build_oai -I --phy_simulators
Note the section on installing UHD further down for more information.
## Building PHY Simulators
The PHY layer simulators (LTE and NR) can be built as follows:
```bash
cd openairinterface5g/cmake_targets/
./build_oai --phy_simulators
```
After completing the build, the binaries are available in the `cmake_targets/ran_build/build` directory.
...
...
@@ -68,20 +89,11 @@ Detailed information about these simulators can be found [in this dedicated page
After downloading the source files, a single build command can be used to get the binaries supporting all the oai softmodem use cases (UE and [eg]NodeB):
```
cd <your oai installation directory>/openairinterface5g/
source oaienv
cd cmake_targets/
./build_oai -I -w USRP --eNB --UE --nrUE --gNB
```bash
cd openairinterface5g/cmake_targets/
./build_oai -w USRP --eNB--UE--nrUE--gNB
```
- The `-I` option is to install pre-requisites, you only need it the first time you build the softmodem or when some oai dependencies have changed.
- The `-w` option is to select the radio head support you want to include in your build. Radio head support is provided via a shared library, which is called the "oai device" The build script creates a soft link from `liboai_device.so` to the true device which will be used at run-time (here the USRP one,`liboai_usrpdevif.so` . USRP is the only hardware tested today in the Continuous Integration process. The RF simulator[RF simulator](../radio/rfsimulator/README.md) is implemented as a specific device replacing RF hardware, it can be specifically built using `-w SIMU` option, but is also built during any softmodem build.
-`--eNB` is to build the `lte-softmodem` executable and all required shared libraries
-`--gNB` is to build the `nr-softmodem` executable and all required shared libraries
-`--UE` is to build the `lte-uesoftmodem` executable and all required shared libraries
-`--nrUE` is to build the `nr-uesoftmodem` executable and all required shared libraries
You can build any oai softmodem executable separately, you may not need all of them depending on your oai usage.
After completing the build, the binaries are available in the `cmake_targets/ran_build/build` directory.
...
...
@@ -118,35 +130,56 @@ See:
*`cmake_targets/tools/uhd-4.x-tdd-patch.diff`
*`cmake_targets/tools/build_helper` --> function `install_usrp_uhd_driver_from_source`
# Building Optional Binaries
## Telnet Server
The telnet server can be built with the `--build-lib telnetsrv` option, after building the softmodem or while building it.
Using the help option of the build script you can get the list of available optional libraries. Those which haven't been mentioned above are known to need more tests and documentation.
The following libraries are build in CI and should always work: `telnet`,
`enbscope`, `uescope`, `nrscope`, `nrqtscope`.
`./build_oai --build-lib all` will build all available optional libraries.
Some libraries have further dependencies and might not build on every system:
-`enbscope`, `uescope`, `nrscope`: libforms/X
-`nrqtscope`: Qt5
-`ldpc_cuda`: CUDA
-`ldpc_t1`: DPDK and VVDN T1
-`websrv`: npm and others
# `build_oai` options
# Running `cmake` directly
Please run `./build_oai -h` to get a list of available options.
`build_oai` is a wrapper on top of `cmake`. It is therefore possible to run `cmake` directly. An example using `ninja`: to build all "main targets" for 5G, excluding additional libraries:
Please send email to [contact@openairinterface.org](mailto:contact@openairinterface.org) to be added to the repository
as a developer (only important for users who want to commit code to the repository). If
you do not have account on gitlab.eurecom.fr, please register yourself to gitlab.eurecom.fr and provide the identifiant in the email.
you do not have account on gitlab.eurecom.fr, please register yourself to gitlab.eurecom.fr and provide the login name in the email.
# Which branch to checkout?
On the RAN side:
***master**: This branch is targeted for the user community. Since January 2019, it is also subject to a Continuous Integration process. The update frequency is about once every 2-3 months. We are also performing bug fixes on this branch.
***develop**: This branch contains recent commits that are tested on our CI test bench. The update frequency is about once a week.
More information can be found in [a separate page](../CONTRIBUTING.md).
`develop`: contains recent commits that are tested on our CI test bench. The update frequency is about once a week. 5G is only in this branch. It is the recommended and default branch.
`master`: contains a stable version of 4G, and will be updated in the future with 5G.
you can find the latest stable tag release here:
Please see the work flow and policies page: https://gitlab.eurecom.fr/oai/openairinterface5g/wikis/oai-policies-home
