docs/developer-guide.rst

   1
   2 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   3 .. SPDX-License-Identifier: CC-BY-4.0
   4 .. CAUTION: this document is generated from source in doc/src/rtd.
   5 .. To make changes edit the source and recompile the document.
   6 .. Do NOT make changes directly to .rst or .md files.
   7
   8
   9 RMR Developer Guide
  10 ============================================================================================
  11
  12 The RIC Message Router (RMR) is a library which applications
  13 use to send and receive messages where the message routing,
  14 endpoint selection, is based on the message type rather than
  15 on traditional DNS names or IP addresses. This document
  16 contains information that potential developers might need to
  17 know in order to contribute to the project
  18
  19 Language
  20 --------------------------------------------------------------------------------------------
  21
  22 RMR is written in C, and thus a contributing developer to the
  23 core library should have an excellent working knowledge of C.
  24 There currently is one set of cross languages bindings
  25 supporting Python, and a developer wishing to contribute to
  26 the bindings source should be familiar with Python (version
  27 3.7+) and with the Python *ctypes* library.
  28
  29 Code Structure
  30 --------------------------------------------------------------------------------------------
  31
  32 RMR is designed to provide an insulation layer between user
  33 applications and the actual transport mechanism. Initially
  34 RMR was built on top of Nanosmg, and shortly after was ported
  35 to NNG (Nanomsg Next Generation). Because RMR presents the
  36 same API to the user application regardless of the underlying
  37 transport library, the resulting output when compiling RMR is
  38 a transport specific library. As an example, librmr_nng.a is
  39 the library generated for use with the NNG transport.
  40
  41 As such the library source is organised into multiple
  42 components:
  43
  44
  45 common
  46
  47   Source in the common directory is agnostic to the
  48   underlying transport mechanism (Nanomsg or NNG), and thus
  49   can be used when generating either library.
  50
  51 nano
  52
  53   Source which is tightly coupled with the underlying
  54   Nanomsg library. (Nanomsg has been deprecated, but the RMR
  55   source remains as an example.)
  56
  57 nng
  58
  59   Source which is tightly coupled with the underlying NNG
  60   library.
  61
  62
  63
  64 Internal Function Exposure
  65 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  66
  67 The decision to limit as much as practical the exposure of
  68 truely internal RMR functions was made, and as a result most
  69 of the RMR functions carry a static label. In order to
  70 modularise the code as much as possible, this means that the
  71 primary module (e.g. rmr_nng.c) will directly include other
  72 RMR modules, rather than depending on referencing the
  73 internal functions during linking. While this is an
  74 infrequently used approach, it does mean that there are very
  75 few functions visible for the user application to reference,
  76 all of them having the prefix rmr\_, while allowing internal
  77 functions to have shorter names while still being meaningful.
  78
  79 Coding Style
  80 --------------------------------------------------------------------------------------------
  81
  82 There is a list of coding style guidelines in the top level
  83 directory, and as such they are not expanded upon here. The
  84 general practice is to follow the style when editing an
  85 existing module, respect the author's choice where style
  86 alternatives are not frowned upon. When creating new modules,
  87 select a style that fits the guidelines and is easy for you
  88 to work with. There are a few things that are insisted on by
  89 the maintainers of RMR, but for the most part style is up to
  90 the creator of a module.
  91
  92 Building
  93 --------------------------------------------------------------------------------------------
  94
  95 RMR is constructed using CMake. While CMake's project
  96 description can be more cumbersome than most typical
  97 Makefiles, the tool provides convenience especially when it
  98 comes to creating packages.