#
-Building RMr
+Building RMR
-The RIC Message Router (RMr) is built with CMake, and requires
+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
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.
-Continuous integration build
+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=<path> 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 and creates an image in the local registry.
+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, the fully qualified path of each generated
-package will be placed into a well known YAML file:
-/tmp/build_output.yml. This file is created during CMake
-configuration and lists the package name(s) for packages which
-can be generated given the current environment. Currently
-Debian (.deb), and RPM packages are supported (the Ubuntu
-alien package must be installed in order to generate RPMs).
+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
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
+each system needs, but the following linker options work when
libraries are installed in the system spots:
-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 supports only NNG as the underlying transport. Nanomsg
+support was dropped 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.
+
+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
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.
Code Review / ric-plt / lib / rmr.git / blobdiff