README

   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 Source for the RIC Messaging Library -- RMR.
  22
  23 C does not provide the concept of package names,  yet we have
  24 a desire not to maintain all of the static code in a single large
  25 file, we use the following convention:
  26
  27         <name>.c --             C code which builds separately and generates an object
  28                                         that is ultimately added to the archive.
  29
  30         <name>_static.c - File containing nothing but static functions (a.k.a package
  31                                         only functions). These files should be included by other *.c
  32                                         files and should not generate object.
  33
  34         <name>.h                Header file that user applications are expected to include
  35                                         in order to make use of the library
  36
  37         <name>_inline.h Header files containing inline static functions that the
  38                                         user application is expected to include.
  39
  40         <name>_private.h Header file meant only to be included by the package.
  41
  42 Further, as this code is used to generate libraries which make use of different
  43 transport mechanisms, there are some modules which are specific to the
  44 underlying transport being used.  The original code supported both Nanomsg and
  45 NNG, however Nanomsg has been phased out (starting with 1.0.45).  File naming
  46 convention for modules which are transport specific originally included a
  47 suffix (e.g. _nng), however as the directory structure was reorganised, and
  48 transport specific directories, plus a common directory, have been created,
  49 the need for the suffix has been eliminated (existing files were not changed).
  50
  51
  52 External Names
  53 All externally facing function names and constants will start with rmr_ or
  54 RMR_ repsectively (RIC Message Router).    For the time being, there is a
  55 set of mappings from the old uta_* names to rmr_* names. The user code must
  56 define UTA_COMPAT to have these ensbled.
  57
  58 Internal Names
  59 Internal (static) functions have no mandiated convention. There are some
  60 names which are prefixed with uta_.  These are left over from the original
  61 prototype libray which had the name Uta.  The uta_ prefixes were mostly on
  62 functions which were iniitally external, but were pulled back for this release.
  63
  64
  65
  66 Requirements
  67 To build the RMR libraries, NNG must be installed, or the external references
  68 in the source tree must be used to pull and build the NNG library. It might
  69 be necessary to alter the values of C_INCLUDE_PATH,  LD_LIBRARY_PATH, or
  70 LIBRARY_PATH to reflect the instalation location when the installed version
  71 ot NNG is being used.
  72
  73 To install see the instructions on their html sites:
  74         https://github.com/nanomsg/nng
  75
  76 The default CMake build will not require NNG to be installed, and this is the
  77 easiest way to build.
  78
  79 Unit Testing
  80 The script ../test/unit_test.ksh should be used for running unit tests. With no
  81 parameters it will attempt to build any file in this directory which has the
  82 name *_test.c.  Build is attempted with either mk or make and enables the
  83 necessary compiler flags to support coverage output (gcov).  Once built, the
  84 test programme is executed and if the return code is success (0), the
  85 coverage data is interpreted.
  86
  87 The test programmes may make use of ../test/tools.c which provide simple
  88 validation check functions.  These programmes shouild also directly include
  89 the module(s) under test.  This ensures that they are not linked, and are
  90 compiled with the proper coverage flags. In addition, it allows modules that
  91 are not under test to be linked from the archive and (most importantly) not
  92 reported on from a coverage perspective. In cases where two modules depend on
  93 each other, and are static functions, they will need to be tested from a single
  94 unit test programme (see the rt_tool test programme).
  95
  96 It might be necessary to write a higher level test driver as some of the modules
  97 (e.g. route table) have threaded daemons which might not be easy to drive
  98 completely or at all, and thus the code coverage for a passing test might need
  99 to be lower for this type of module.
 100
 101 Containerized Build
 102 The Dockerfile defines an environment to build and test this library.  It uses
 103 a base image with the C toolchain.  The Dockerfile is NOT intended to create a
 104 distributable image.