#
#==================================================================================
-# Copyright (c) 2019 Nokia
-# Copyright (c) 2018-2019 AT&T Intellectual Property.
+# Copyright (c) 2020 Nokia
+# Copyright (c) 2018-2020 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.
#==================================================================================
#
+RIC Message Router -- RMR
-Source for the RIC Messaging Library -- RMR.
+RMR is a message router library which an application can use to send messages
+to other RMR based applications. The destination of each message is governed
+by the message type and subscription ID, or just the message type. RMR is
+responsible for establishing and managing each connection freeing the application
+from any network connectivity management.
-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:
+This repo contains the source and documentation for the core RMR library.
+RMR python bindings are available as a submodule in the xapp-frame-py PyPI package at
+https://pypi.org/project/ricxappframe/ and documented at https://docs.o-ran-sc.org/projects/o-ran-sc-ric-plt-xapp-frame-py/en/latest/.
- <name>.c -- C code which builds separately and generates an object
- that is ultimately added to the archive.
+The directories at the root level are as follows, each contains its own readme
+file where additional details are necessary.
- <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
+ci This directory contains the continuous integration scripts needed
+ to build and verify RMR when changes are made and committed to the repo.
- <name>_inline.h Header files containing inline static functions that the
- user application is expected to include.
+doc RMR documentation is written in a document language and thus is
+ source code. This directory contains the source for all generated
+ documentation.
- <name>_private.h Header file meant only to be included by the package.
+docs This is a 'canned' directory which is intended to be scraped. Direct
+ editing of documentation files in this directory is dangerous as
+ most of the files, even though checked into the repo per mandate,
+ are artifacts and will be overlaid if hand edited.
-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).
-
+examples This directory contains example programmes which illustrate the use
+ of RMR.
-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.
+ext RMR makes use of NNG (next generation Nanomsg). The ext directory is
+ the git reference allowing the NNG code to be pulled and built as
+ a reference.
-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.
+src This directory is the top level source directory containing the
+ core RMR code.
+test All unit and application level tests for the core library are kept
+ within this directory. Tests for bindings are managed within the
+ binding's directory under the source directory.
+Top level pollution
+There are several "configuration" files which sit at the top level of the
+repo that are required for some sort of CI/CD/Documentation automation. Most,
+if not all of the CI/CD goo is in the ci directory where it's out of the way
+and thus not confusing. However, there is some pollution that can generally
+be ignored:
-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.
+ tox.ini -- this seems to drive the scraper which pulls from docs and
+ writes to some external documentation repo/host.
-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.
+ .readthedocs.yaml -- this seems to be some configuration for the docs
+ scraping process(es).
Code Review / ric-plt / lib / rmr.git / blobdiff