README - oransc/ric-plt/lib/rmr - Gitiles

 #
 #==================================================================================
 #       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.
	#
	#==================================================================================
	# 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.