docs/developer-guide.rst

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