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