X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=BUILD;h=b2febefbf0c4c5b9d9e8588879fd15044c010cf1;hb=HEAD;hp=17ed7435224072c986bda76d7ca53c332266345c;hpb=b0ba22eb7deafbe43f7dac0e9d6abd8d4484c3bf;p=ric-plt%2Flib%2Frmr.git diff --git a/BUILD b/BUILD index 17ed743..b2febef 100644 --- a/BUILD +++ b/BUILD @@ -17,15 +17,13 @@ #================================================================================== # - 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 @@ -41,12 +39,12 @@ To build RMR, the usual CMake steps are followed: 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: +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 @@ -54,30 +52,31 @@ the configuration: -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; uee installed 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. +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 -programm 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. +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: @@ -92,74 +91,107 @@ The following is a sample YAML file generated during this process: 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 + 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 only NNG as the underlying transport. Nanomsg -support was dropped in starting with version 1.0.45 as Nanomsg -has reached end of life. The package generation and install -will produce a single RMR library: librmr_nng. RMR is designed -to support different underlying transport mechanisms, which -might require separate libraries, and thus the library name is -given a suffix of _nng to reflect the transport mechanism -in use. - -Regardless of transport mechanism supported by an RMR library, -the RMR API will be identical, thus it is possible for an appliction -to shift mechanisms simply by referencing a differnt library (should -multiple RMR libraries become available). +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: +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. - - +(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.