docs/developer-guide.rst

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