X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=BUILD;h=b2febefbf0c4c5b9d9e8588879fd15044c010cf1;hb=HEAD;hp=64bd052b4f560a4f4f0689fbfd52764b010f4575;hpb=fd9cc7a5b3355146388ebdf4d558cb284c66c5f1;p=ric-plt%2Flib%2Frmr.git diff --git a/BUILD b/BUILD index 64bd052..b2febef 100644 --- a/BUILD +++ b/BUILD @@ -1,6 +1,6 @@ # #================================================================================== -# Copyright (c) 2019 Nokia +# Copyright (c) 2019 Nokia # Copyright (c) 2018-2019 AT&T Intellectual Property. # # Licensed under the Apache License, Version 2.0 (the "License"); @@ -17,15 +17,13 @@ #================================================================================== # +Building RMR -Building RMr - -The RIC Message Router (RMr) is built with CMake, and requires -a modern gcc compiler and make to be installed on the build -system. Typically, installing the following list of packages -in a container (Ubuntu) is all that is needed to craft a -development environment (containerised builds are also the -recommended approach): +The RIC Message Router (RMR) is built with CMake, and requires cmake +version 3, make and a modern gcc compiler to be installed on the build +system. Typically, installing the following list of packages in a +container (Ubuntu) is all that is needed to craft a development +environment (containerised builds are also the recommended approach): gcc git make vim cmake g++ ksh bash @@ -34,70 +32,166 @@ interactively. Bash is assumed necessary for CMake. Build process -To build RMr, the usual CMake steps are followed: +To build RMR, the usual CMake steps are followed: mkdir build cd build cmake .. [options] make package -This will create a .deb (provided the system supports this) in -the build directory. It's that simple. + +On a Debian/Ubuntu system, this will create a .deb (provided the +system supports this) in the build directory. It's that simple. + +The following flags may be given on the 'cmake' command line (options) +which are outside of "normal" CMake flags and affect the +configuration: + + -DBUILD_DOC=1 Man pages generated + -DDEV_PKG=1 Development package configuration + -DIGNORE_LIBDIR Ignore the system preferred library directory and install in /usr/local/lib + -DMAN_PREFIX= Supply a path where man pages are installed (default: /usr/share/man) + -DPACK_EXTERNALS=1 Include external libraries used to build in the run-time package + -DPRESERVE_PTYPE=1 Do not change the processor type when naming deb packages + -DSKIP_EXTERNALS=1 Do not use Nano/NNG submodules when building; use installed packages + (See caution in the 'Libraries' section below) + + +Packages + +The build can be configured to generate either a run-time or +development package. The run-time generation is the default and the +-DDEV_PKG=1 option must be given to generate the development package. +The run-time package contains only the shared library files (*.so), +and the development package contains the headers, man pages (if the +man option is set) and archive (.a) files. Resulting package names +are illustrated in the CI section below. + +Continuous Integration Build + +Use the Dockerfile in the ci/ subdirectory. This installs all the +required tools, then builds RMR and executes the unit and program +tests. If tests pass, then an image is created in the local registry +with both run-time and development packages. + +To support the distribution of package(s) created during the build by +the CI process, a YAML file is left in the /tmp directory +(build_packages.yml) which contains a list of the packages available +from the image. Currently, both .deb and .rpm packages are generated. + +The following is a sample YAML file generated during this process: + + --- + files: + - /tmp/rmr-dev_1.0.34_x86_64.deb + - /tmp/rmr-dev-1.0.34-x86_64.rpm + - /tmp/rmr_1.0.34_x86_64.deb + - /tmp/rmr-1.0.34-x86_64.rpm + ... + Alternatives -To build in a non-Linux environment, or to build with an -alternate install path (or both) read on. -Instead of using 'make package' as listed above, using -'make install' will build and install on the local system. -By default, the target install is into /usr/local which may -not be desired. To install into an alternate path add -these two options when the 'cmake ..' command is given: +To build in a non-Linux environment, or to build with an alternate +install path (or both) read on. + +Instead of using 'make package' as listed above, using 'make install' +will build and install on the local system. By default, the target +install is into /usr/local which may not be desired. To install into +an alternate path add these two options when the 'cmake ..' command is +given: -DCMAKE_INSTALL_PREFIX=/path/to/dir -DMAN_PREFIX=/path/to/dir The first will cause the make process to install into the named -directory, which can be in your home directory. The second -defines where manual pages are placed (if not defined -/usr/share/man is the target). Manual pages are generally -NOT built as the required tool has yet to be incorporated into -the build process and generally is not available on most systems. +directory, which can be in your home directory. The second defines +where manual pages are placed (if not defined /usr/share/man is the +target). Manual pages are generally NOT built as the required tool +has yet to be incorporated into the build process and generally is not +available on most systems. + +Compiling and Linking User Applications -Compiling and Linking Should the Rmr and NNG/Nano libraries be installed in a directory -outside of the normal system spots (e.g. not in /usr/local) -it might be necessary to define the specific directory for -libraries (.e.g -L) on the command line, or via environment -variables (e.g.. C_INCLUDE_PATH, LD_LIBRARY_PATH, LIBRARY_PATH). -It may also be necessary to have the library directory defined -in the environment at run time. It is difficult to know what -each system needs, but the following linker ooptions work when -libraries are installed in the system spots: +outside of the normal system spots (e.g. not in /usr/local) it might +be necessary to define the specific directory for libraries (.e.g -L) +on the command line, or via environment variables +(e.g.. C_INCLUDE_PATH, LD_LIBRARY_PATH, LIBRARY_PATH). It may also be +necessary to have the library directory defined in the environment at +run time. It is difficult to know what each system needs, but the +following linker options work when libraries are installed in the +system spots: -lrmr_nng -lnng -lpthread -Adding -L is one way to compensate when libraries are installed -a different spot (e.g. in $HOME/usr): +Adding -L is one way to compensate when libraries are installed in a +different spot (e.g. in $HOME/usr): -L $HOME/usr -lrmr_nng -lnng -lpthread Libraries -RMr supports both NNG and Nanomsg as underlying transport. They -are separate beasts, and while an NNG based programme can -communicate with a Nanomsg based programme, their APIs are NOT -compatible. For this reason, and others, RMr generates two -libraries and requires that the underlying transport be selected -at link time rather than run time. The RMr API for both underlying -mechanisms is the same, so generating a NNG and Nanomsg version -of a programme should require no extra work; other than adding -a second link statement and giving it a different name. - -Nanomsg is on its way out with respect to community support. RMr -will continue to support Nanomsg for a short period of time, but -new programmes should NOT use Nanomsg. - +RMR is designed to support different underlying transport mechanisms, +which might require separate libraries, and thus the library name is +given a suffix that reflects the transport mechanism in use. RMR +supports NNG and SI95 as the underlying transports. Nanomsg support +was dropped starting with version 1.0.45 as Nanomsg has reached end of +life. The package generation and install will produce two RMR +libraries: librmr_nng and librmr_si. + +NNG version with a commit ID of 906d5ea1b3d67bece941d8a4e0a049e5f6c65051 +is required to build RMR. That version (as yet untagged) adds a +new error state which we must trap. While application environments +are encouraged to also build and install at least this version of +NNG, RMR is still compatable back to the version tagged as 1.1.1. +If you opt to build with the -DSKIP_EXTERNALS=1 flag set, you must +ensure that this version of NNG is present in your build environment. +If you do not set this flag, the proper NNG source will be used +automatically. + +Regardless of transport mechanism supported by an RMR library, the RMR +API will be identical, thus it is possible for an application to shift +mechanisms simply by referencing a different library (should multiple +RMR libraries become available). + +Manual Pages + +By default the deb created does not include the manual pages. To +enable their creation, and subsequent inclusion in the deb, add the +following option to the cmake command: + + -DBUILD_DOC=1 + +This will cause the {X}fm text formatting package to be fetched +(github) and built at cmake time (must exist before building) and will +trigger the generation of the man pages in both postscript and troff +format. The troff pages are placed into the deb and the postscript +pages are left in the build directory for the developer to convert to +PDF, or otherwise use. + +Debug Mode + +Because RMR is designed to keep its overhead to an absolute minimum, +messages written to standard error are by default very limited. The +route table collection thread provides the means to enable debug +messages on the fly, but only because that thread does not impact the +sending and receiving of user messages. + +If it becomes necessary, for development or problem soving, to have +the RMR functions generate debugging messages the following +CMake flag can be given when the CMake environment is created: + -DDEBUG=n + +The value for 'n' should be 1 or 2 to enable debugging. The default +when not given is the same as setting n to zero. + +When running in debug mode, RMR will log messages received, sent, and +other useful information. Because debugging uses fprintf() there is a +significant amount of overhead with logging this information and thus +in debugging mode the user should not expect that usual message rates +can be achieved, and in some cases may cause messages to drop if TCP +queues become full.