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; uee installed packages
  58
  59
  60 Packages
  61 The build can be configured to generate either a run-time or
  62 development package. The run-time generation is the default and
  63 the -DDEV_PKG=1 option must be given to generate the development
  64 package.  The run-time package contains only the shared library
  65 files (*.so), and the development package contains the headers,
  66 man pages (if the man option is set) and archive (.a) files.
  67 Resulting package names are illustrated in the CI section below.
  68
  69
  70 Continuous Integration Build
  71 Use the Dockerfile in the ci/ subdirectory. This installs all
  72 the required tools, then builds RMR and executes the unit and
  73 programm tests. If tests pass, then  an image is created in the
  74 local registry with both run-time and development packages.
  75
  76 To support the distribution of package(s) created during the
  77 build by the CI process,  a YAML file is left in the /tmp
  78 directory (build_packages.yml) which contains a list of the
  79 packages available from the image.  Currently, both .deb and
  80 .rpm packages are generated.
  81
  82 The following is a sample YAML file generated during this process:
  83
  84    ---
  85    files:
  86      - /tmp/rmr-dev_1.0.34_x86_64.deb
  87      - /tmp/rmr-dev-1.0.34-x86_64.rpm
  88      - /tmp/rmr_1.0.34_x86_64.deb
  89      - /tmp/rmr-1.0.34-x86_64.rpm
  90    ...
  91
  92
  93
  94 Alternatives
  95 To build in a non-Linux environment, or to build with an
  96 alternate install path (or both) read on.
  97
  98 Instead of using 'make package' as listed above, using
  99 'make install'  will build and install on the local system.
 100 By default, the target install is into /usr/local which may
 101 not be desired.  To install into an alternate path add
 102 these two options when the 'cmake ..' command is 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
 110 defines where manual pages are placed (if not defined
 111 /usr/share/man is the target).   Manual pages are generally
 112 NOT built as the required tool has yet to be incorporated into
 113 the build process and generally is not available on most systems.
 114
 115
 116 Compiling and Linking User Applications
 117 Should the Rmr and NNG/Nano libraries be installed in a directory
 118 outside of the normal system spots (e.g. not in /usr/local)
 119 it might be necessary to define the specific directory for
 120 libraries (.e.g -L) on the command line, or via environment
 121 variables (e.g.. C_INCLUDE_PATH, LD_LIBRARY_PATH, LIBRARY_PATH).
 122 It may also be necessary to have the library directory defined
 123 in the environment at run time.  It is difficult to know what
 124 each system needs, but the following linker ooptions  work when
 125 libraries are installed in the system spots:
 126
 127         -lrmr_nng -lnng -lpthread
 128
 129 Adding -L is one way to compensate when libraries are installed
 130 a different spot (e.g. in $HOME/usr):
 131
 132         -L $HOME/usr -lrmr_nng -lnng -lpthread
 133
 134
 135 Libraries
 136 RMR supports only NNG as the underlying transport. Nanomsg
 137 support was dropped in starting with version 1.0.45 as Nanomsg
 138 has reached end of life. The package generation and install
 139 will produce a single RMR library:  librmr_nng.  RMR is designed
 140 to support different underlying transport mechanisms, which
 141 might require separate libraries, and thus the library name is
 142 given a suffix of _nng to reflect the transport mechanism
 143 in use.
 144
 145 Regardless of transport mechanism supported by an RMR library,
 146 the RMR API will be identical, thus it is possible for an appliction
 147 to shift mechanisms simply by referencing a differnt library (should
 148 multiple RMR libraries become available).
 149
 150
 151 Manual Pages
 152 By default the deb created does not include the manual pages. To
 153 enable their creation, and subsequent inclusion in the deb, add
 154 the following option to the cmake command:
 155
 156         -DBUILD_DOC=1
 157
 158 This will cause the {X}fm text formatting package to be fetched
 159 (github) and built at cmake time (must exist before building)
 160 and will trigger the generation of the man pages in both postscript
 161 and troff format.  The troff pages are placed into the deb and
 162 the postscript pages are left in the build directory for the
 163 developer to convert to PDF, or otherwise use.
 164
 165