CI: Add silent cmake SonarCloud scan

[ric-plt/lib/rmr.git] / BUILD

diff --git a/BUILD b/BUILD
index 24e604f..b2febef 100644 (file)
--- a/BUILD
+++ b/BUILD
@@ -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
 
 
  gcc git make vim cmake g++ ksh bash
 


@@ -41,12 +39,12 @@ To build RMR, the usual CMake steps are followed:
        make package
 
 
        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
 
   -DBUILD_DOC=1         Man pages generated
   -DDEV_PKG=1                  Development package configuration


@@ -59,26 +57,26 @@ the configuration:
 
 
 Packages
 
 
 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
 
 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.
+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:
 
 
 The following is a sample YAML file generated during this process:
 


@@ -93,55 +91,57 @@ The following is a sample YAML file generated during this process:
 
 
 Alternatives
 
 
 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
 
   -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 User Applications

+

 Should the Rmr and NNG/Nano libraries be installed in a directory
 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 options  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
 
 
        -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
 
        -L $HOME/usr -lrmr_nng -lnng -lpthread
 
 
 Libraries

-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.
+
+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
 
 NNG version with a commit ID of 906d5ea1b3d67bece941d8a4e0a049e5f6c65051
 is required to build RMR.  That version (as yet untagged) adds a


@@ -153,24 +153,45 @@ 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.
 
 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).
-
+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
 
 Manual Pages

+

 By default the deb created does not include the manual pages. To
 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
 
        -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.