X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=README;h=247db4d1f0164e428bd01a5825ef28842e4222f7;hb=HEAD;hp=86217ce1c443a611023f3a1899a7af609f9efc18;hpb=fd9cc7a5b3355146388ebdf4d558cb284c66c5f1;p=ric-plt%2Flib%2Frmr.git diff --git a/README b/README index 86217ce..247db4d 100644 --- a/README +++ b/README @@ -1,7 +1,7 @@ # #================================================================================== -# 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. @@ -17,77 +17,58 @@ #================================================================================== # +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/. - .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. - _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. - .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. - _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. - _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/utest.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. + .readthedocs.yaml -- this seems to be some configuration for the docs + scraping process(es).