DEPENDENCIES

Prerequisites for building the OpenDataPlane (ODP) API

1. Linux
   CentOS 7 (kernel v3.10) and Ubuntu 16.04 (kernel v4.4) are the oldest
   Linux distributions tested by the ODP CI. Earlier versions may or may not
   work.

2. autotools

   automake
   autoconf
   libtool
   pkg-config

   On Debian/Ubuntu systems:
   $ sudo apt-get install automake autoconf libtool pkg-config

   On CentOS/RedHat/Fedora systems:
   $ sudo yum install automake autoconf libtool pkgconfig

3. Required packages

   Libraries currently required to link: libconfig, openssl, libatomic

   On Debian/Ubuntu systems:
   $ sudo apt-get install libconfig-dev

   On CentOS/RedHat/Fedora systems:
   $ sudo yum install libconfig-devel

   It is possible to build ODP without OpenSSL by passing flag
   --without-openssl to configure script. However this will result in
   ODP-generic not supporting any cryptography algorithm (except NULL) and any
   strong random generation (only BASIC is supported and it is not
   cryptographically secure). Use at your own risk!

3.1 OpenSSL native compile

   For native compilation, simply load the necessary libraries using the appropriate
   tool set.

   On Debian/Ubuntu systems:
   $ sudo apt-get install libssl-dev

   On CentOS/RedHat/Fedora systems:
   $ sudo yum install openssl-devel

3.2 OpenSSL cross compilation

   Cross compilation requires cross compiling the individual libraries.  In order for
   a cross compiled executable to run on a target system, one must build the same
   version as that which is installed on the target rootfs.

   For example, to build openssl for both 32 and 64 bit compilation:

   # Clone openssl repository
   $ git clone git://git.openssl.org/openssl.git
   $ cd openssl

   # The command "git tag" will list all tags available in the repo.
   $ git tag

   # Checkout the specific tag to match openssl library in your target rootfs
   $ git checkout <tag name>

   # Build and install 32 bit version of openssl
   $ ./Configure linux-generic32 --cross-compile-prefix=arm-linux-gnueabihf- \
     --prefix=/home/${USER}/src/install-openssl shared
   $ make
   $ make install

   # Build and install 64 bit version of openssl
   $ ./Configure linux-generic64 --cross-compile-prefix=aarch64-linux-gnu- \
     --prefix=/home/${USER}/src/install-openssl-aarch64 shared
   $ make
   $ make install

   # You may now build either 32 or 64 bit ODP
   $ git clone https://github.com/OpenDataPlane/odp.git odp
   $ cd odp
   $ ./bootstrap

   # Build 32 bit version of ODP
   $ ./configure --host=arm-linux-gnueabihf \
     --with-openssl-path=/home/${USER}/src/install-openssl
   $ make

   # Or build 64 bit version of ODP
   $ ./configure --host=aarch64-linux-gnu \
     --with-openssl-path=/home/${USER}/src/install-openssl-aarch64
   $ make

3.3 Netmap packet I/O support (optional)

   Netmap accelerated ODP packet I/O.

3.3.1 Building netmap kernel modules

   ODP works at least with the latest release version of netmap, which is
   currently v13.0. However, if possible one should try to use the latest netmap
   master branch commit for the best performance and the latest bug fixes.

   # Checkout netmap code
   $ git clone https://github.com/luigirizzo/netmap.git
   $ cd netmap
   $ git checkout v13.0 (optional)

   This is enough to build ODP. If you don't want to build netmap kernel
   modules you can jump to section 3.3.2.

   Netmap consists of a core kernel module (netmap.ko), optional modified
   device drivers and user space API headers to access the netmap
   functionality. It is recommended to build both the core module and modified
   device drivers for optimal performance.

   Netmap builds as an out-of-tree kernel module, you need matching kernel
   sources to compile it. General build instructions can be found in the packet
   README: https://github.com/luigirizzo/netmap/blob/master/LINUX/README.

   If you are running Ubuntu/Debian with the stock kernel and you want to
   compile both netmap.ko and modified drivers, these steps will guide you
   through it.

   # Download kernel headers
   $ sudo apt-get install linux-headers-$(uname -r)

   # Download kernel source matching to the headers
   $ sudo apt-get install linux-source
   # or
   $ apt-get source linux-image-$(uname -r)

   The source archive will be placed in /usr/src/linux-source-<kernel-version>
   (or in the current directory if using apt-get source). You will need to
   locate it and extract it to a convenient place.

   # Compile netmap
   $ cd <netmap_dir>/LINUX
   $ ./configure --kernel-sources=<path_to_kernel_src>
   $ make

3.3.2 Building ODP

   $ cd <odp_dir>
   $ ./bootstrap
   $ ./configure --with-netmap-path=<netmap_dir>
   $ make

3.3.3 Inserting netmap kernel modules

   In order to use netmap I/O you need to insert at least the core netmap
   kernel module.

   $ cd <netmap_dir>/LINUX
   $ sudo insmod netmap.ko

   To insert the optional modified drivers you first need to remove the
   original drivers, if loaded (and if not linked into the kernel). For
   example, if using ixgbe:

   $ cd <netmap_path>/LINUX
   $ sudo rmmod ixgbe
   $ sudo insmod ixgbe/ixgbe.ko

   To restore the original drivers you should be able to use modprobe.

3.3.4 Running ODP with netmap I/O

   ODP applications will use netmap for packet I/O by default as long as the
   netmap kernel module is loaded. If socket I/O is desired instead, it can be
   activated by setting the environment variable ODP_PKTIO_DISABLE_NETMAP.

3.4 DPDK packet I/O support (optional)

   Use DPDK for ODP packet I/O. Currently supported DPDK versions are v19.11
   (recommended) and v18.11.

   Note: only packet I/O is accelerated with DPDK. See
        https://github.com/OpenDataPlane/odp-dpdk.git
   for a full DPDK based ODP implementation.

3.4.1 DPDK pktio requirements

   DPDK pktio adds a dependency to NUMA library.
   # Debian/Ubuntu
   $ sudo apt-get install libnuma-dev
   # CentOS/RedHat/Fedora
   $ sudo yum install numactl-devel

3.4.2 Native DPDK install
   # Debian/Ubuntu starting from 18.04
   $ sudo apt-get install dpdk-dev

3.4.2 Build DPDK from source
   $ git clone --branch=19.11 http://dpdk.org/git/dpdk-stable dpdk

   # Make and edit DPDK configuration
   $ export TARGET="x86_64-native-linuxapp-gcc"
   $ make config T=${TARGET} O=${TARGET}
   $ pushd ${TARGET}

   # Enable pcap PMD to use DPDK pktio without supported NICs:
   $ sed -ri 's,(CONFIG_RTE_LIBRTE_PMD_PCAP=).*,\1y,' .config
   $ popd

   # Build and install DPDK
   $ make install T=${TARGET} EXTRA_CFLAGS="-fPIC" DESTDIR=./install

   # Compile ODP
   $ ./configure --with-dpdk-path=<dpdk_install_dir>

3.4.3 Setup system

   # Load DPDK modules
   $ sudo modprobe uio
   $ cd <dpdk-dir>
   $ sudo insmod x86_64-native-linuxapp-gcc/kmod/igb_uio.ko

   Reserve and mount huge pages and bind supported interfaces to DPDK modules
   following the DPDK documentation. ODP DPDK packet I/O has been tested with
   512 x 2MB huge pages. All this can be done with the DPDK setup script
   (<dpdk-dir>/usertools/dpdk-setup.sh).

3.4.4 Running ODP with DPDK pktio

   ODP applications will try use DPDK for packet I/O by default. If some other
   I/O type is desired instead, DPDK I/O can be disabled by setting the
   environment variable ODP_PKTIO_DISABLE_DPDK.

   DPDK interfaces are accessed using indexes. For example, two first DPDK
   interfaces can be used with the odp_l2fwd example as follows:
   $ cd <odp_dir>
   $ sudo ./test/performance/odp_l2fwd -i 0,1 -c 2 -m 0

   Additionally, DPDK command line options can be passed to the application
   using ODP_PKTIO_DPDK_PARAMS environment variable. For example, allocate
   1024MB of memory:
   $ sudo ODP_PKTIO_DPDK_PARAMS="-m 1024" ./test/performance/odp_l2fwd -i 0 -c 1

4.0 Packages needed to build API tests

   CUnit test framework version 2.1-3 is required
   CUnit provides a framework to run the API test suite that proves conformance to the
   ODP API. The home page http://cunit.sourceforge.net/doc/introduction.html

4.1 Native CUnit install

   # Debian/Ubuntu
   $ apt-get install libcunit1-dev

4.2 Built from src

   export CUNIT_VERSION=2.1-3
   curl -sSOL http://sourceforge.net/projects/cunit/files/CUnit/${CUNIT_VERSION}/CUnit-${CUNIT_VERSION}.tar.bz2
   tar -jxf *.bz2
   cd CUnit*
   ./bootstrap

   # Install CUnit into the default location (/usr/local). This is needed for
   # 'make distcheck'.
   ./configure
   make
   sudo make install

   # On RedHat you also have to add path /usr/local/lib to /etc/ld.so.conf

   # ... OR ... Install CUnit into user defined location. The same path is
   # used in step 4.4: PKG_CONFIG_PATH=/home/<my_cunit_path>/lib/pkgconfig
   ./configure --prefix=/home/<my_cunit_path>
   make
   make install

   # Also (in Ubuntu/RedHat at least) run ldconfig to update shared lib
   # cache or reboot, before trying to run e.g. 'make distcheck'.
   sudo ldconfig

4.3 Cross compile of CUnit

   $ git svn clone http://svn.code.sf.net/p/cunit/code/trunk cunit-code
   $ cd cunit-code
   $ ./bootstrap

   # Build and install 32 bit version of cunit
   $ ./configure --host=arm-linux-gnueabihf --prefix=/home/${USER}/src/install-cunit
   $ make
   $ make install

   # Build and install 64 bit version of cunit
   $ ./configure --host=aarch64-linux-gnu --prefix=/home/${USER}/src/install-cunit
   $ make
   $ make install

4.4 Using CUnit with ODP

   Configure will automatically look for CUnit if validation testsuite is
   enabled. By default it uses pkg-config to locate CUnit. Usually no
   additional configuration will be required. Few corner cases:

   # User directory installation
   ./configure PKG_CONFIG_PATH=/home/<my_cunit_path>/lib/pkgconfig

   # ... OR directly specifying flags
   ./configure CUNIT_CFLAGS="-I/home/<my_cunit_path>/include" CUNIT_LIBS="/home/<my_cunit_path>/lib -lcunit"

5.0 Cross Compilation for arm64

   To cross compile binaries for arm64 on an x86_64 Debian based system, install
   the following packages: crossbuild-essential-arm64, libconfig-dev:arm64
   (optionally libssl-dev:arm64).

5.1 Pre-installation setup (optional)

   # Debian/Ubuntu
   $ sudo dpkg --add-architecture arm64

   Modify /etc/apt/sources.list to add remote repositories for fetching arm64
   software packages for your Ubuntu version. Once this is complete, run:
   $ sudo apt-get update

5.2 Install packages

   # Debian/Ubuntu
   $ sudo apt-get install crossbuild-essential-arm64
   $ sudo apt-get install libconfig-dev:arm64

   Installing OpenSSL is optional. Refer to section 3 for more details.
   $ sudo apt-get install libssl-dev:arm64

5.3 Building ODP

   $ ./bootstrap
   $ ./configure --host=aarch64-linux-gnu
   $ make

   To build ODP with cross-compiled cunit for arm64, refer to sections 4.3
   and 4.4.

6.0 Documentation Images & Doxygen

   Images are stored as svg files. No conversions for these are needed.

   Message sequence diagrams are stored as msc files and the svg versions are generated
   when the docs are built.
   # Debian/Ubuntu
   $ apt-get install mscgen

6.1 API Guide
   See https://www.doxygen.nl/manual/install.html

   The tested version of doxygen is 1.8.8

6.1.1 HTML
   # Debian/Ubuntu
   $ apt-get install doxygen graphviz

6.2 User guides

6.2.1 HTML
   # Debian/Ubuntu
   $ apt-get install asciidoctor source-highlight librsvg2-bin

7.0 Submitting patches

   When submitting patches they should be checked with ./scripts/checkpatch.pl
   To have this tool also check spelling you need codespell.
   # Debian/Ubuntu
   $ sudo apt-get install codespell