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