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   -DMAN_PREFIX=<path>   Supply a path where man pages are installed (default: /usr/share/man)
  54   -DPACK_EXTERNALS=1    Include external libraries used to build in the run-time package
  55   -DPRESERVE_PTYPE=1    Do not change the processor type when naming deb packages
  56   -DSKIP_EXTERNALS=1    Do not use Nano/NNG submodules when building; uee installed packages
  57
  58
  59 Packages
  60 The build can be configured to generate either a run-time or
  61 development package. The run-time generation is the default and
  62 the -DDEV_PKG=1 option must be given to generate the development
  63 package.  The run-time package contains only the shared library
  64 files (*.so), and the development package contains the headers,
  65 man pages (if the man option is set) and archive (.a) files.
  66 Resulting package names are illustrated in the CI section below.
  67
  68
  69 Continuous Integration Build
  70 Use the Dockerfile in the ci/ subdirectory. This installs all
  71 the required tools, then builds RMr and executes the unit and
  72 programm tests. If tests pass, then  an image is created in the
  73 local registry with both run-time and development packages.
  74
  75 To support the distribution of package(s) created during the
  76 build by the CI process,  a YAML file is left in the /tmp
  77 directory (build_packages.yml) which contains a list of the
  78 packages available from the image.  Currently, both .deb and
  79 .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 To build in a non-Linux environment, or to build with an
  95 alternate install path (or both) read on.
  96
  97 Instead of using 'make package' as listed above, using
  98 'make install'  will build and install on the local system.
  99 By default, the target install is into /usr/local which may
 100 not be desired.  To install into an alternate path add
 101 these two options when the 'cmake ..' command is given:
 102
 103   -DCMAKE_INSTALL_PREFIX=/path/to/dir
 104   -DMAN_PREFIX=/path/to/dir
 105
 106
 107 The first will cause the make process to install into the named
 108 directory, which can be in your home directory. The second
 109 defines where manual pages are placed (if not defined
 110 /usr/share/man is the target).   Manual pages are generally
 111 NOT built as the required tool has yet to be incorporated into
 112 the build process and generally is not available on most systems.
 113
 114
 115 Compiling and Linking User Applications
 116 Should the Rmr and NNG/Nano libraries be installed in a directory
 117 outside of the normal system spots (e.g. not in /usr/local)
 118 it might be necessary to define the specific directory for
 119 libraries (.e.g -L) on the command line, or via environment
 120 variables (e.g.. C_INCLUDE_PATH, LD_LIBRARY_PATH, LIBRARY_PATH).
 121 It may also be necessary to have the library directory defined
 122 in the environment at run time.  It is difficult to know what
 123 each system needs, but the following linker ooptions  work when
 124 libraries are installed in the system spots:
 125
 126         -lrmr_nng -lnng -lpthread
 127
 128 Adding -L is one way to compensate when libraries are installed
 129 a different spot (e.g. in $HOME/usr):
 130
 131         -L $HOME/usr -lrmr_nng -lnng -lpthread
 132
 133
 134 Libraries
 135 RMr supports both NNG and Nanomsg as underlying transport. They
 136 are separate beasts, and while an NNG based program can
 137 communicate with a Nanomsg based programme, their APIs are NOT
 138 compatible.  For this reason, and others, RMr generates two
 139 libraries and requires that the underlying transport be selected
 140 at link time rather than run time.  The RMr API for both underlying
 141 mechanisms is the same, so generating a NNG and Nanomsg version
 142 of a programme should require no extra work; other than adding
 143 a second link statement and giving it a different name.
 144
 145 Nanomsg is on its way out with respect to community support. RMr
 146 will continue to support Nanomsg for a short period of time, but
 147 new programmes should NOT use Nanomsg.
 148
 149
 150 Manual Pages
 151 By default the deb created does not include the manual pages. To
 152 enable their creation, and subsequent inclusion in the deb, add
 153 the following option to the cmake command:
 154
 155         -DBUILD_DOC=1
 156
 157 This will cause the {X}fm text formatting package to be fetched
 158 (github) and built at cmake time (must exist before building)
 159 and will trigger the generation of the man pages in both postscript
 160 and troff format.  The troff pages are placed into the deb and
 161 the postscript pages are left in the build directory for the
 162 developer to convert to PDF, or otherwise use.
 163
 164