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 both a Nanomsg and NNG based version,
  43 there are some modules which are specific to the underlying transport being
  44 used.  The original code was based on Nanomsg, thus any changes resulting from
  45 the port to NNG, are in files with the same name plus _nng (e.g. rtable_static.c
  46 is the original module, and rrable_nng_static.c is the NNG version).
  47
  48
  49 External Names
  50 All externally facing function names and constants will start with rmr_ or
  51 RMR_ repsectively (RIC Message Router).    For the time being, there is a
  52 set of mappings from the old uta_* names to rmr_* names. The user code must
  53 define UTA_COMPAT to have these ensbled.
  54
  55 Internal Names
  56 Internal (static) functions have no mandiated convention. There are some
  57 names which are prefixed with uta_.  These are left over from the original
  58 prototype libray which had the name Uta.  The uta_ prefixes were mostly on
  59 functions which were iniitally external, but were pulled back for this release.
  60
  61
  62
  63 Requirements
  64 To build the RMR libraries, both Nanomsg and NNG must be installed, and if not
  65 installed in the standard places (e.g. /usr/local/include and /usr/local/lib),
  66 then the proper references must be made in C_INCLUDE_PATH, and LD_LIBRARY_PATH.
  67
  68 To install see the instructions on their html sites:
  69         https://github.com/nanomsg/nng
  70         https://nanomsg.org/download.html
  71
  72
  73 Unit Testing
  74 The script ../test/unit_test.ksh should be used for running unit tests. With no
  75 parameters it will attempt to build any file in this directory which has the
  76 name *_test.c.  Build is attempted with either mk or make and enables the
  77 necessary compiler flags to support coverage output (gcov).  Once built, the
  78 test programme is executed and if the return code is success (0), the
  79 coverage data is interpreted.
  80
  81 The test programmes may make use of ../test/tools.c which provide simple
  82 validation check functions.  These programmes shouild also directly include
  83 the module(s) under test.  This ensures that they are not linked, and are
  84 compiled with the proper coverage flags. In addition, it allows modules that
  85 are not under test to be linked from the archive and (most importantly) not
  86 reported on from a coverage perspective. In cases where two modules depend on
  87 each other, and are static functions, they will need to be tested from a single
  88 unit test programme (see the rt_tool test programme).
  89
  90 It might be necessary to write a higher level test driver as some of the modules
  91 (e.g. route table) have threaded daemons which might not be easy to drive
  92 completely or at all, and thus the code coverage for a passing test might need
  93 to be lower for this type of module.
  94
  95 Containerized Build
  96 The Dockerfile defines an environment to build and test this library.  It uses
  97 a base image with the C toolchain.  The Dockerfile is NOT intended to create a
  98 distributable image.