README

#
#==================================================================================
#       Copyright (c) 2019 Nokia 
#       Copyright (c) 2018-2019 AT&T Intellectual Property.
#
#   Licensed under the Apache License, Version 2.0 (the "License");
#   you may not use this file except in compliance with the License.
#   You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#   Unless required by applicable law or agreed to in writing, software
#   distributed under the License is distributed on an "AS IS" BASIS,
#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#   See the License for the specific language governing permissions and
#   limitations under the License.
#==================================================================================
#


Source for the RIC Messaging Library -- RMR.

C does not provide the concept of package names,  yet we have
a desire not to maintain all of the static code in a single large 
file, we use the following convention:

	<name>.c --		C code which builds separately and generates an object
					that is ultimately added to the archive.

	<name>_static.c - File containing nothing but static functions (a.k.a package
					only functions). These files should be included by other *.c 
					files and should not generate object.

	<name>.h		Header file that user applications are expected to include
					in order to make use of the library

	<name>_inline.h Header files containing inline static functions that the
					user application is expected to include.

	<name>_private.h Header file meant only to be included by the package.

Further, as this code is used to generate both a Nanomsg and NNG based version, 
there are some modules which are specific to the underlying transport being
used.  The original code was based on Nanomsg, thus any changes resulting from 
the port to NNG, are in files with the same name plus _nng (e.g. rtable_static.c
is the original module, and rrable_nng_static.c is the NNG version).
					

External Names
All externally facing function names and constants will start with rmr_ or
RMR_ repsectively (RIC Message Router).    For the time being, there is a 
set of mappings from the old uta_* names to rmr_* names. The user code must
define UTA_COMPAT to have these ensbled.

Internal Names
Internal (static) functions have no mandiated convention. There are some 
names which are prefixed with uta_.  These are left over from the original
prototype libray which had the name Uta.  The uta_ prefixes were mostly on 
functions which were iniitally external, but were pulled back for this release.



Requirements
To build the RMR libraries, both Nanomsg and NNG must be installed, and if not
installed in the standard places (e.g. /usr/local/include and /usr/local/lib),
then the proper references must be made in C_INCLUDE_PATH, and LD_LIBRARY_PATH.

To install see the instructions on their html sites:
	https://github.com/nanomsg/nng
	https://nanomsg.org/download.html


Unit Testing
The script ../test/unit_test.ksh should be used for running unit tests. With no 
parameters it will attempt to build any file in this directory which has the 
name *_test.c.  Build is attempted with either mk or make and enables the 
necessary compiler flags to support coverage output (gcov).  Once built, the
test programme is executed and if the return code is success (0), the 
coverage data is interpreted.

The test programmes may make use of ../test/tools.c which provide simple 
validation check functions.  These programmes shouild also directly include
the module(s) under test.  This ensures that they are not linked, and are 
compiled with the proper coverage flags. In addition, it allows modules that
are not under test to be linked from the archive and (most importantly) not
reported on from a coverage perspective. In cases where two modules depend on
each other, and are static functions, they will need to be tested from a single
unit test programme (see the rt_tool test programme).

It might be necessary to write a higher level test driver as some of the modules
(e.g. route table) have threaded daemons which might not be easy to drive 
completely or at all, and thus the code coverage for a passing test might need
to be lower for this type of module.

Containerized Build
The Dockerfile defines an environment to build and test this library.  It uses
a base image with the C toolchain.  The Dockerfile is NOT intended to create a
distributable image.