doc/src/rtd/developer-guide.xfm

   1 .** vim: ts=4 noet sw=4:
   2 .if false
   3 ==================================================================================
   4         Copyright (c) 2019-2020 Nokia
   5         Copyright (c) 2018-2020 AT&T Intellectual Property.
   6
   7    Licensed under the Apache License, Version 2.0 (the "License");
   8    you may not use this file except in compliance with the License.
   9    You may obtain a copy of the License at
  10
  11        http://www.apache.org/licenses/LICENSE-2.0
  12
  13    Unless required by applicable law or agreed to in writing, software
  14    distributed under the License is distributed on an "AS IS" BASIS,
  15    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16    See the License for the specific language governing permissions and
  17    limitations under the License.
  18 ==================================================================================
  19 .fi
  20
  21
  22 .if false
  23         Mnemonic:       config-deploy.xfm
  24         Abstract:       Source to generate a configuration deployment guide.
  25         Date:           6 November 2019
  26         Author:         E. Scott Daniels
  27 .fi
  28
  29 .dv GEN_TITLE=1
  30 .dv doc_title Developer's Guide
  31
  32 .im setup.im
  33
  34 &h1(Overview)
  35
  36 The RIC Message Router (RMR) is a library for peer-to-peer
  37 communication.  Applications use the library to send and receive
  38 messages where the message routing and endpoint selection is based on
  39 the message type rather than DNS host name-IP port combinations.
  40 &space
  41 This document contains information that developers need to know to
  42 contribute to the RMR project.
  43
  44 &h2(Language)
  45 RMR is written in C, and thus a contributing developer to the core
  46 library should have an excellent working knowledge of C.  There
  47 currently is one set of cross-languages bindings supporting Python,
  48 and a developer wishing to contribute to the bindings source should be
  49 familiar with Python (version 3.7+) and with the Python &ital(ctypes)
  50 library.
  51
  52 &h2(Code Structure)
  53 RMR is designed to provide an insulation layer between user
  54 applications and the actual transport mechanism.  Initially RMR was
  55 built on top of the third-party library Nanosmg, shortly after was
  56 ported to the third-party library NNG (Nanomsg Next Generation), and
  57 then was ported to an internally developed socket library called SI95.
  58 RMR presents the same API to the user application regardless of the
  59 underlying transport library, but the resulting output when compiling
  60 RMR is always a transport-specific library.  As an example,
  61 &cw(librmr_nng.a) is the library generated for use with the NNG
  62 transport.  &space
  63
  64 As such the library source is organised into multiple components:
  65
  66 &beg_dlist(.75i : ^&bold_font )
  67
  68 &ditem(common) Source in the common directory is agnostic to the
  69         underlying transport mechanism (Nanomsg, NNG, SI95, ..), and
  70         thus can be used when generating either library.
  71
  72 &ditem(nano) Source which is tightly coupled with the underlying Nanomsg library.
  73         (Nanomsg has been deprecated, but the RMR source remains as an example.)
  74
  75 &ditem(nng) Source which is tightly coupled with the underlying NNG library.
  76         (NNG has been deprecated, but the RMR source remains as an example.)
  77
  78 &ditem(si) Source which is tightly coupled with the underlying SI95 library.
  79
  80 &end_dlist
  81
  82 &space
  83 &h3(Internal Function Exposure)
  84 The decision to limit as much as practical the exposure of truly
  85 internal RMR functions was made, and as a result most of the RMR
  86 functions carry a &cw(static) label.  In order to modularise the code
  87 as much as possible, this means that the primary module
  88 (e.g. rmr_nng.c) directly includes other RMR modules, rather than
  89 depending on referencing the internal functions during linking.  While
  90 this is an infrequently used approach, it does mean that there are
  91 very few functions visible for the user application to reference, all
  92 of them having the prefix &cw(rmr&{esc}_). This allows internal
  93 functions to have shorter names while still being meaningful.
  94
  95 &h2(Coding Style)
  96 There is a list of coding style guidelines in the top level directory,
  97 and as such they are not expanded upon here.  The general practice is
  98 to follow the style when editing an existing module, respect the
  99 author's choice where style alternatives are not frowned upon.  When
 100 creating new modules, select a style that fits the guidelines and is
 101 easy for you to work with.  There are a few things that the RMR
 102 maintainers insist on, but for the most part style is up to the
 103 creator of a module.
 104
 105 &h2(Building)
 106 RMR is constructed using CMake.  While CMake's project description can
 107 be more cumbersome than most typical Makefiles, the tool provides
 108 convenience especially when it comes to creating DEB/RPM packages.