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 This will create a .deb (provided the system supports this) in
  44 the build directory.  It's that simple.
  45
  46 Continuous integration build
  47 Use the Dockerfile in the ci/ subdirectory. This installs all
  48 the required tools and creates an image in the local registry.
  49
  50 To support the distribution of package(s) created during the
  51 build by the CI process, the fully qualified path of each generated
  52 package will be placed into a well known YAML file:
  53 /tmp/build_output.yml.   This file is created during CMake
  54 configuration and lists the package name(s) for packages which
  55 can be generated given the current environment. Currently
  56 Debian (.deb), and RPM packages are supported (the Ubuntu
  57 alien package must be installed in order to generate RPMs).
  58
  59
  60 Alternatives
  61 To build in a non-Linux environment, or to build with an
  62 alternate install path (or both) read on.
  63
  64 Instead of using 'make package' as listed above, using
  65 'make install'  will build and install on the local system.
  66 By default, the target install is into /usr/local which may
  67 not be desired.  To install into an alternate path add
  68 these two options when the 'cmake ..' command is given:
  69
  70   -DCMAKE_INSTALL_PREFIX=/path/to/dir
  71   -DMAN_PREFIX=/path/to/dir
  72
  73
  74 The first will cause the make process to install into the named
  75 directory, which can be in your home directory. The second
  76 defines where manual pages are placed (if not defined
  77 /usr/share/man is the target).   Manual pages are generally
  78 NOT built as the required tool has yet to be incorporated into
  79 the build process and generally is not available on most systems.
  80
  81
  82 Compiling and Linking User Applications
  83 Should the Rmr and NNG/Nano libraries be installed in a directory
  84 outside of the normal system spots (e.g. not in /usr/local)
  85 it might be necessary to define the specific directory for
  86 libraries (.e.g -L) on the command line, or via environment
  87 variables (e.g.. C_INCLUDE_PATH, LD_LIBRARY_PATH, LIBRARY_PATH).
  88 It may also be necessary to have the library directory defined
  89 in the environment at run time.  It is difficult to know what
  90 each system needs, but the following linker ooptions  work when
  91 libraries are installed in the system spots:
  92
  93         -lrmr_nng -lnng -lpthread
  94
  95 Adding -L is one way to compensate when libraries are installed
  96 a different spot (e.g. in $HOME/usr):
  97
  98         -L $HOME/usr -lrmr_nng -lnng -lpthread
  99
 100
 101 Libraries
 102 RMr supports both NNG and Nanomsg as underlying transport. They
 103 are separate beasts, and while an NNG based programme can
 104 communicate with a Nanomsg based programme, their APIs are NOT
 105 compatible.  For this reason, and others, RMr generates two
 106 libraries and requires that the underlying transport be selected
 107 at link time rather than run time.  The RMr API for both underlying
 108 mechanisms is the same, so generating a NNG and Nanomsg version
 109 of a programme should require no extra work; other than adding
 110 a second link statement and giving it a different name.
 111
 112 Nanomsg is on its way out with respect to community support. RMr
 113 will continue to support Nanomsg for a short period of time, but
 114 new programmes should NOT use Nanomsg.
 115
 116
 117 Manual Pages
 118 By default the deb created does not include the manual pages. To
 119 enable their creation, and subsequent inclusion in the deb, add
 120 the following option to the cmake command:
 121
 122         -DBUILD_DOC=1
 123
 124 This will cause the {X}fm text formatting package to be fetched
 125 (github) and built at cmake time (must exist before building)
 126 and will trigger the generation of the man pages in both postscript
 127 and troff format.  The troff pages are placed into the deb and
 128 the postscript pages are left in the build directory for the
 129 developer to convert to PDF, or otherwise use.
 130
 131