#
-Building RMr
+Building RMR
-The RIC Message Router (RMr) is built with CMake, and requires
+The RIC Message Router (RMR) is built with CMake, and requires
a modern gcc compiler and make to be installed on the build
system. Typically, installing the following list of packages
in a container (Ubuntu) is all that is needed to craft a
Build process
-To build RMr, the usual CMake steps are followed:
+To build RMR, the usual CMake steps are followed:
mkdir build
cd build
cmake .. [options]
-DBUILD_DOC=1 Man pages generated
-DDEV_PKG=1 Development package configuration
+ -DIGNORE_LIBDIR Ignore the system preferred library directory and install in /usr/local/lib
-DMAN_PREFIX=<path> Supply a path where man pages are installed (default: /usr/share/man)
-DPACK_EXTERNALS=1 Include external libraries used to build in the run-time package
-DPRESERVE_PTYPE=1 Do not change the processor type when naming deb packages
Continuous Integration Build
Use the Dockerfile in the ci/ subdirectory. This installs all
-the required tools, then builds RMr and executes the unit and
+the required tools, then builds RMR and executes the unit and
programm tests. If tests pass, then an image is created in the
local registry with both run-time and development packages.
Libraries
-RMr supports both NNG and Nanomsg as underlying transport. They
-are separate beasts, and while an NNG based program can
-communicate with a Nanomsg based programme, their APIs are NOT
-compatible. For this reason, and others, RMr generates two
-libraries and requires that the underlying transport be selected
-at link time rather than run time. The RMr API for both underlying
-mechanisms is the same, so generating a NNG and Nanomsg version
-of a programme should require no extra work; other than adding
-a second link statement and giving it a different name.
-
-Nanomsg is on its way out with respect to community support. RMr
-will continue to support Nanomsg for a short period of time, but
-new programmes should NOT use Nanomsg.
+RMR supports only NNG as the underlying transport. Nanomsg
+support was dropped in starting with version 1.0.45 as Nanomsg
+has reached end of life. The package generation and install
+will produce a single RMR library: librmr_nng. RMR is designed
+to support different underlying transport mechanisms, which
+might require separate libraries, and thus the library name is
+given a suffix of _nng to reflect the transport mechanism
+in use.
+
+Regardless of transport mechanism supported by an RMR library,
+the RMR API will be identical, thus it is possible for an appliction
+to shift mechanisms simply by referencing a differnt library (should
+multiple RMR libraries become available).
Manual Pages
-API change summaries and fixes to the code. Doc correctsions
+API and build change and fixe summaries. Doc correctsions
and/or changes are not mentioned here; see the commit messages.
-2019 August 6; version 1.0.44
+2019 August 6; version 1.0.45 (build changes)
+ Support for the Nanomsg transport library has been dropped.
+ The library librmr.* will no longer be included in packages.
+
+ Packages will install RMR libraries into the system preferred
+ target directory. On some systems this is /usr/local/lib
+ and on others it is /usr/local/lib64. The diretory is
+ determined by the sytem on which the package is built and
+ NOT by the system installing the package, so it's possible
+ that the RMR libraries end up in a strange location if the
+ .deb or .rpm file was generated on a Linux flavour that
+ has a different preference than the one where the package
+ is installed.
+
+2019 August 6; version 1.0.44 (API change)
Added a new message type constant.
-2019 July 15; Version 1.0.39
+2019 July 15; Version 1.0.39 (bug fix)
Prevent unnecessary usleep in retry loop.
-2019 July 12; Version 1.0.38
+2019 July 12; Version 1.0.38 (API change)
Added new message types to RIC_message_types.h.
2019 July 11; Version 1.0.37
- librmr and librmr_nng
+ librmr and librmr_nng
- Add message buffer API function rmr_trace_ref()
(see rmr_trace_ref.3 manual page in dev package).
#
# -DDEV_PKG=1 Development package configuration
# -DBUILD_DOC=1 Man pages generated
+# -DIGNORE_LIBDIR=1 Installation of rmr libries is into /usr/local/lib and ignores
+# value in CMAKE_INSTALL_LIBDIR.
+# system preferred (typically /usr/local/lib64).
# -DPRESERVE_PTYPE=1 Do not change the processor type when naming deb packages
# -DPACK_EXTERNALS=1 Include external libraries used to build in the run-time package
# (This makes some stand-alone unit testing of bindings possible, it
# is not meant to be used for production package generation.)
-# -DSKIP_EXTERNALS=1 Do not use Nano/NNG submodules when building; uee installed packages
+# -DSKIP_EXTERNALS=1 Do not use NNG submodule when building; uee installed packages
# -DMAN_PREFIX=<path> Supply a path where man pages are installed (default: /usr/share/man)
project( rmr LANGUAGES C )
set( major_version "1" ) # should be automatically populated from git tag later, but until CI process sets a tag we use this
set( minor_version "0" )
-set( patch_level "44" )
+set( patch_level "45" )
set( install_root "${CMAKE_INSTALL_PREFIX}" )
-set( install_lib "lib" )
set( install_inc "include/rmr" )
if( MAN_PREFIX )
set( install_man ${MAN_PREFIX} ) # is there a cmake var for this -- can't find one
# locations on all platforms.
include( GNUInstallDirs )
-# nano/nng install using LIBDIR as established by the gnu include; it varies from system
-# to system, and we don't trust that it is always set, so we default to lib.
+# nng installs using LIBDIR as established by the gnu include; it varies from system
+# to system, and we don't trust that it is always set, so we default to lib if it is missing.
#
if( NOT CMAKE_INSTALL_LIBDIR )
set( CMAKE_INSTALL_LIBDIR "lib" )
endif()
+if( IGNORE_LIBDIR ) # if set, then force to lib otherwise use "system preference"
+ set( install_lib "lib" )
+else()
+ set( install_lib "${CMAKE_INSTALL_LIBDIR}" )
+endif()
+unset(IGNORE_LIBDIR CACHE ) # we don't want this to persist
+message( "+++ RMR library install target directory: ${install_lib}" )
+
# ---------------- extract some things from git ------------------------------
# commit id for the version string
OUTPUT_VARIABLE mmp_version_str
ERROR_QUIET OUTPUT_STRIP_TRAILING_WHITESPACE
)
+message( "+++ mmp version from tag: '${mmp_version_str}'" )
# extra indicator to show that the build was based on modified file(s) and not the true commit
# (no hope of reproducing the exact library for debugging). Used only for the internal version
# ---------------- suss out pkg gen tools so we don't fail generating packages that the system cannot support --------------
# deb packages use underbars, and package manager(s) seem to flip the *_64 processor type
-# to the old (non-standard) amd64 string, so we do it here for consistency. Set -DPRESERVE_PTYPE=1
+# to the old (non-standard) amd64 string, so we do it here for consistency. Set -DPRESERVE_PTYPE=1
# to prevent the flip. RPM packages will always be given the system generated processor type string.
#
if( ${CMAKE_SYSTEM_PROCESSOR} MATCHES "x86_64" )
set( rpm_pkg_label "${rpm_pkg_name}${spoiled_str}-${major_version}.${minor_version}.${patch_level}-${rpm_sys_name}" )
set( deb_pkg_label "${deb_pkg_name}${spoiled_str}_${major_version}.${minor_version}.${patch_level}_${deb_sys_name}" )
message( "+++ pkg name: ${deb_pkg_label}.deb" )
-message( "+++ pkg name: ${rpm_pkg_label}.rpm" )
-set( out_yml /tmp/build_output.yml ) # we will record package names (we record only untainted names)
+#set( out_yml /tmp/build_output.yml ) # we will record package names (we record only untainted names)
find_program( rpm NAMES rpmbuild ) # rpm package gen requires this to be installed
set( gen_rpm 0 )
set( pkg_list "DEB" )
message( "### make package will generate only deb package; cannot find support to generate rpm packages" )
else()
+ message( "+++ pkg name: ${rpm_pkg_label}.rpm" ) # debugging if we think we can gen rpm too
set( pkg_list "DEB;RPM" )
set( gen_rpm 1 )
message( "+++ make package will generate both deb and rpm packages" )
endif()
-execute_process(
- COMMAND bash -c "printf '# RMr build generated list of package paths\n---\n' >${out_yml}"
-)
-
-execute_process(
- COMMAND bash -c " echo deb: ${CMAKE_CURRENT_BINARY_DIR}/${deb_pkg_label}.deb >>${out_yml}"
-)
-
-if( gen_rpm )
- execute_process(
- COMMAND bash -c " echo rpm: ${CMAKE_CURRENT_BINARY_DIR}/${rpm_pkg_label}.rpm >>${out_yml}"
- )
-endif()
-
-execute_process(
- COMMAND bash -c "printf '...\n' >>${out_yml}"
-)
-
# ---------------- setup nano/nng things ---------------------------------------
if( NOT SKIP_EXTERNALS )
set( need_ext 1 ) # we force dependences on these for right build order
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
)
- execute_process( COMMAND git submodule update --init -- ext/nanomsg
- WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
- )
if( NOT EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/ext/nng/CMakeLists.txt )
message( FATAL_ERROR "cannot find nng in our git source as a submodule: Giving up" ) # this will abort which seems wrong, but tdam.
endif()
TEST_COMMAND ""
STEP_TARGETS build
)
- ExternalProject_Add(
- nanomsg
- SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/ext/nanomsg"
- BUILD_COMMAND "make"
- UPDATE_COMMAND ""
- CMAKE_ARGS "-DCMAKE_INSTALL_PREFIX=${CMAKE_CURRENT_BINARY_DIR}"
- TEST_COMMAND ""
- STEP_TARGETS build
- )
# it seems impossible to install everything that lands in {bin}/lib, so we need to
# hard code (shudder) some things. Even worse, we have to make exceptions for
# builds on apple (osx) since their naming convention wandered off the path.
set( nng_major 1 )
set( nng_minor 1.0 )
- set( nano_major 5 )
- set( nano_minor 1.0 )
set( so ${CMAKE_SHARED_LIBRARY_SUFFIX} ) # cmake variables are impossibly long :(
if( NOT APPLE ) # probably breaks in windows, but idc
set( nng_so_suffix ${so} )
set( nng_so_suffix_m ${so}.${nng_major} )
set( nng_so_suffix_mm ${so}.${nng_major}.${nng_minor} )
-
- set( nano_so_suffix ${so} )
- set( nano_so_suffix_m ${so}.${nano_major} )
- set( nano_so_suffix_mm ${so}.${nano_major}.${nano_minor} )
else()
# of course apple puts versions before the suffix :(
set( nng_so_suffix ${so} ) # so has a lead dot, so NOT needed
set( nng_so_suffix_m ".${nng_major}${so}" ) # these need leading dots
set( nng_so_suffix_mm ".${nng_major}.${nng_minor}${so}" )
-
- set( nano_so_suffix ${so} )
- set( nano_so_suffix_m ".${nano_major}${so}" )
- set( nano_so_suffix_mm ".${nano_major}.${nano_minor}${so}" )
endif()
- message( "+++ installing nano/nng with: ${nano_major}.${nano_minor} | ${nng_major}.${nng_minor}" )
+ message( "+++ building with nng: ${nng_major}.${nng_minor}" )
else()
if( PACK_EXTERNALS )
# This makes some stand-alone unit testing possible for bindings and transport layer testing;
# Include modules
add_subdirectory( src/rmr/common )
-add_subdirectory( src/rmr/nanomsg )
add_subdirectory( src/rmr/nng )
add_subdirectory( doc ) # this will auto skip if {X}fm is not available
# shared and static libraries are built from the same object files.
-# Nanomsg based library (librmr ) while nng based is librmr_nng.
-# library is built by pulling object files from either the nano or nng and common subdirs
+# librmr_nng is a combination of common and nng specific rmr functions.
#
-add_library( rmr_shared SHARED "$<TARGET_OBJECTS:nano_objects>;$<TARGET_OBJECTS:common_objects>" )
-
-set_target_properties( rmr_shared
- PROPERTIES
- OUTPUT_NAME "rmr"
- SOVERSION ${major_version}
- VERSION ${major_version}.${minor_version}.${patch_level} )
add_library( rmr_nng_shared SHARED "$<TARGET_OBJECTS:nng_objects>;$<TARGET_OBJECTS:common_objects>" )
set_target_properties( rmr_nng_shared
OUTPUT_NAME "rmr_nng"
SOVERSION ${major_version}
VERSION ${major_version}.${minor_version}.${patch_level} )
-
- add_library( rmr_static STATIC "$<TARGET_OBJECTS:nano_objects>;$<TARGET_OBJECTS:common_objects>" )
-
- set_target_properties( rmr_static
- PROPERTIES
- OUTPUT_NAME "rmr"
- SOVERSION ${major_version}
- VERSION ${major_version}.${minor_version}.${patch_level} )
endif()
# if externals need to be built, then we must force them to be built first by depending on them
if( need_ext )
if( DEV_PKG )
- add_dependencies( rmr_static;rmr_shared nanomsg )
add_dependencies( rmr_nng_shared;rmr_nng_static ext_nng )
else()
- add_dependencies( rmr_shared nanomsg )
add_dependencies( rmr_nng_shared ext_nng )
endif()
endif()
#
if( APPLE )
message( "### apple hack: forcing hard coded library paths for nng/nano dynamic libraries" )
- target_link_libraries( rmr_shared ${CMAKE_CURRENT_BINARY_DIR}/lib/libnanomsg${nano_so_suffix} )
target_link_libraries( rmr_nng_shared ${CMAKE_CURRENT_BINARY_DIR}/lib/libnng${nng_so_suffix} )
endif()
# the library (.so) files and nothing more.
#
if( DEV_PKG )
- set( target_list "rmr_nng_static;rmr_static" )
+ set( target_list "rmr_nng_static" )
else()
- set( target_list "rmr_nng_shared;rmr_shared" )
+ set( target_list "rmr_nng_shared" )
endif()
install( TARGETS ${target_list} EXPORT LibraryConfig
)
-unset( DEV_PKG CACHE ) # prevent from being a hiddent setting if user redoes things
+unset( DEV_PKG CACHE ) # prevent from being a hidden setting if user redoes things
# install any nano/nng libraries in to the deb as well, but ONLY if asked for on the 'cmake ..' command
# (sure would be nice if FILEs allowed for globbing; sadlyy it does not.)
if( PACK_EXTERNALS )
message( "+++ including nano and nng libraries in the deb" )
install( FILES
- ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR}/libnanomsg${nano_so_suffix}
- ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR}/libnanomsg${nano_so_suffix_m}
- ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR}/libnanomsg${nano_so_suffix_mm}
${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR}/libnng${nng_so_suffix}
${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR}/libnng${nng_so_suffix_m}
${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR}/libnng${nng_so_suffix_mm}
set( CPACK_DEBIAN_FILE_NAME "${deb_pkg_label}.deb" )
set( CPACK_RPM_FILE_NAME "${rpm_pkg_label}.rpm" )
- # we build and ship the libraries, so there is NO dependency
+ # there is not an NNG package, so we cannot define a dependency
set( CPACK_DEBIAN_PACKAGE_PRIORITY "optional" )
set( CPACK_DEBIAN_PACKAGE_SECTION "ric" )
#
#==================================================================================
-# Copyright (c) 2019 Nokia
+# Copyright (c) 2019 Nokia
# Copyright (c) 2018-2019 AT&T Intellectual Property.
#
# Licensed under the Apache License, Version 2.0 (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
+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
+ 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
<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).
-
+Further, as this code is used to generate libraries which make use of different
+transport mechanisms, there are some modules which are specific to the
+underlying transport being used. The original code supported both Nanomsg and
+NNG, however Nanomsg has been phased out (starting with 1.0.45). File naming
+convention for modules which are transport specific originally included a
+suffix (e.g. _nng), however as the directory structure was reorganised, and
+transport specific directories, plus a common directory, have been created,
+the need for the suffix has been eliminated (existing files were not changed).
+
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
+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
+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
+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 build the RMR libraries, NNG must be installed, or the external references
+in the source tree must be used to pull and build the NNG library. It might
+be necessary to alter the values of C_INCLUDE_PATH, LD_LIBRARY_PATH, or
+LIBRARY_PATH to reflect the instalation location when the installed version
+ot NNG is being used.
To install see the instructions on their html sites:
https://github.com/nanomsg/nng
- https://nanomsg.org/download.html
+The default CMake build will not require NNG to be installed, and this is the
+easiest way to build.
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
+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
+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
+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
+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
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
+(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.
.PHONY: all
-all: sender receiver sender_nano receiver_nano caller mt_receiver
+all: sender receiver caller mt_receiver
receiver_nano: receiver.c
gcc -I $${C_INCLUDE_PATH:-.} $< -g -o $@ -lrmr -lnanomsg -lpthread -lm
quiet=0
gen_xml=0
replace_flags=1 # replace ##### in gcov for discounted lines
+run_nano_tests=0
while [[ $1 == "-"* ]]
do
-C) builder="$2"; shift;; # custom build command
-G) builder="gmake %s";;
-M) builder="mk -a %s";; # use plan-9 mk (better, but sadly not widly used)
+ -N) run_nano_tests=1;;
-c) module_cov_target=$2; shift;;
-f) force_discounting=1;
do
if [[ $tfile != *"static_test.c" ]]
then
+ if(( ! run_nano_tests )) && [[ $tfile == *"nano"* ]]
+ then
+ continue
+ fi
+
flist="${flist}$tfile "
fi
done
add_ignored_func test_nng_em.c # the nng/nano emulated things
for f in *_static_test.c # all static modules here
do
+ if(( ! run_nano_tests )) && [[ $f == *"nano"* ]]
+ then
+ continue
+ fi
+
add_ignored_func $f
done
Code Review / ric-plt / lib / rmr.git / commitdiff