BUILD

   1 #
   2 #==================================================================================
   3 #       Copyright (c) 2019 Nokia
   4 #       Copyright (c) 2018-2019 AT&T Intellectual Property.
   5 #
   6 #   Licensed under the Apache License, Version 2.0 (the "License");
   7 #   you may not use this file except in compliance with the License.
   8 #   You may obtain a copy of the License at
   9 #
  10 #       http://www.apache.org/licenses/LICENSE-2.0
  11 #
  12 #   Unless required by applicable law or agreed to in writing, software
  13 #   distributed under the License is distributed on an "AS IS" BASIS,
  14 #   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15 #   See the License for the specific language governing permissions and
  16 #   limitations under the License.
  17 #==================================================================================
  18 #
  19
  20
  21 Building RMR
  22
  23 The RIC Message Router (RMR) is built with CMake, and requires
  24 a modern gcc compiler and make to be installed on the build
  25 system. Typically, installing the following list of packages
  26 in a container (Ubuntu) is all that is needed to craft a
  27 development environment (containerised builds are also the
  28 recommended approach):
  29
  30  gcc git make vim cmake g++ ksh bash
  31
  32 Kshell and vi are needed only if you wish to use the container
  33 interactively. Bash is assumed necessary for CMake.
  34
  35
  36 Build process
  37 To build RMR, the usual CMake steps are followed:
  38         mkdir build
  39         cd build
  40         cmake .. [options]
  41         make package
  42
  43
  44 This will create a .deb (provided the system supports this) in
  45 the build directory.  It's that simple.
  46
  47 The following flags may be given on the 'cmake' command line
  48 (options) which are outside of "normal" CMake flags and affect
  49 the configuration:
  50
  51   -DBUILD_DOC=1         Man pages generated
  52   -DDEV_PKG=1                   Development package configuration
  53   -DIGNORE_LIBDIR               Ignore the system preferred library directory and install in /usr/local/lib
  54   -DMAN_PREFIX=<path>   Supply a path where man pages are installed (default: /usr/share/man)
  55   -DPACK_EXTERNALS=1    Include external libraries used to build in the run-time package
  56   -DPRESERVE_PTYPE=1    Do not change the processor type when naming deb packages
  57   -DSKIP_EXTERNALS=1    Do not use Nano/NNG submodules when building; use installed packages
  58                                                 (See caution in the 'Libraries' section below)
  59
  60
  61 Packages
  62 The build can be configured to generate either a run-time or
  63 development package. The run-time generation is the default and
  64 the -DDEV_PKG=1 option must be given to generate the development
  65 package.  The run-time package contains only the shared library
  66 files (*.so), and the development package contains the headers,
  67 man pages (if the man option is set) and archive (.a) files.
  68 Resulting package names are illustrated in the CI section below.
  69
  70
  71 Continuous Integration Build
  72 Use the Dockerfile in the ci/ subdirectory. This installs all
  73 the required tools, then builds RMR and executes the unit and
  74 program tests. If tests pass, then  an image is created in the
  75 local registry with both run-time and development packages.
  76
  77 To support the distribution of package(s) created during the
  78 build by the CI process,  a YAML file is left in the /tmp
  79 directory (build_packages.yml) which contains a list of the
  80 packages available from the image.  Currently, both .deb and
  81 .rpm packages are generated.
  82
  83 The following is a sample YAML file generated during this process:
  84
  85    ---
  86    files:
  87      - /tmp/rmr-dev_1.0.34_x86_64.deb
  88      - /tmp/rmr-dev-1.0.34-x86_64.rpm
  89      - /tmp/rmr_1.0.34_x86_64.deb
  90      - /tmp/rmr-1.0.34-x86_64.rpm
  91    ...
  92
  93
  94
  95 Alternatives
  96 To build in a non-Linux environment, or to build with an
  97 alternate install path (or both) read on.
  98
  99 Instead of using 'make package' as listed above, using
 100 'make install'  will build and install on the local system.
 101 By default, the target install is into /usr/local which may
 102 not be desired.  To install into an alternate path add
 103 these two options when the 'cmake ..' command is given:
 104
 105   -DCMAKE_INSTALL_PREFIX=/path/to/dir
 106   -DMAN_PREFIX=/path/to/dir
 107
 108
 109 The first will cause the make process to install into the named
 110 directory, which can be in your home directory. The second
 111 defines where manual pages are placed (if not defined
 112 /usr/share/man is the target).   Manual pages are generally
 113 NOT built as the required tool has yet to be incorporated into
 114 the build process and generally is not available on most systems.
 115
 116
 117 Compiling and Linking User Applications
 118 Should the Rmr and NNG/Nano libraries be installed in a directory
 119 outside of the normal system spots (e.g. not in /usr/local)
 120 it might be necessary to define the specific directory for
 121 libraries (.e.g -L) on the command line, or via environment
 122 variables (e.g.. C_INCLUDE_PATH, LD_LIBRARY_PATH, LIBRARY_PATH).
 123 It may also be necessary to have the library directory defined
 124 in the environment at run time.  It is difficult to know what
 125 each system needs, but the following linker options  work when
 126 libraries are installed in the system spots:
 127
 128         -lrmr_nng -lnng -lpthread
 129
 130 Adding -L is one way to compensate when libraries are installed
 131 a different spot (e.g. in $HOME/usr):
 132
 133         -L $HOME/usr -lrmr_nng -lnng -lpthread
 134
 135
 136 Libraries
 137 RMR supports only NNG as the underlying transport. Nanomsg
 138 support was dropped starting with version 1.0.45 as Nanomsg
 139 has reached end of life. The package generation and install
 140 will produce a single RMR library:  librmr_nng.  RMR is designed
 141 to support different underlying transport mechanisms, which
 142 might require separate libraries, and thus the library name is
 143 given a suffix of _nng to reflect the transport mechanism
 144 in use.
 145
 146 NNG version with a commit ID of 906d5ea1b3d67bece941d8a4e0a049e5f6c65051
 147 is required to build RMR.  That version (as yet untagged) adds a
 148 new error state which we must trap.  While application environments
 149 are encouraged to also build and install at least this version of
 150 NNG, RMR is still compatable back to the version tagged as 1.1.1.
 151 If you opt to build with the -DSKIP_EXTERNALS=1 flag set, you must
 152 ensure that this version of NNG is present in your build environment.
 153 If you do not set this flag, the proper NNG source will be used
 154 automatically.
 155
 156 Regardless of transport mechanism supported by an RMR library,
 157 the RMR API will be identical, thus it is possible for an application
 158 to shift mechanisms simply by referencing a different library (should
 159 multiple RMR libraries become available).
 160
 161
 162 Manual Pages
 163 By default the deb created does not include the manual pages. To
 164 enable their creation, and subsequent inclusion in the deb, add
 165 the following option to the cmake command:
 166
 167         -DBUILD_DOC=1
 168
 169 This will cause the {X}fm text formatting package to be fetched
 170 (github) and built at cmake time (must exist before building)
 171 and will trigger the generation of the man pages in both postscript
 172 and troff format.  The troff pages are placed into the deb and
 173 the postscript pages are left in the build directory for the
 174 developer to convert to PDF, or otherwise use.
 175
 176 Debug Mode
 177 Because RMR is designed to keep its overhead to an absolute minimum,
 178 messages written to standard error are by default very limited.
 179 The route table collection thread provides the means to enable
 180 debug messages on the fly, but only because that thread does not
 181 impact the sending and receiving of user messages.
 182
 183 If it becomes necessary, for development or problem soving, to have
 184 the RMR functions generate debugging messages the following
 185 CMake flag can be given when the CMake environment is created:
 186         -DDEBUG=n
 187
 188 The value for 'n' should be 1 or 2 to enable debugging.  The default
 189 when not given is the same as setting n to zero.
 190
 191 When running in debug mode, RMR will log messages received, sent,
 192 and other useful information.  Because debugging uses fprintf() there
 193 is a significant amount of overhead with logging this information and
 194 thus in debugging mode the user should not expect that usual message
 195 rates can be achieved, and in some cases may cause messages to drop
 196 if TCP queues become full.