doc/src/rtd/developer-guide.xfm

   1 .** vim: ts=4 noet sw=4:
   2 .if false
   3 ==================================================================================
   4         Copyright (c) 2019 Nokia
   5         Copyright (c) 2018-2019 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 .im setup.im
  30
  31 &h1(RMR Developer Guide)
  32
  33 The RIC Message Router (RMR) is a library which applications use to send and receive
  34 messages where the message routing, endpoint selection, is based on the message type
  35 rather than on traditional DNS names or IP addresses.
  36 This document contains information that potential developers might need to know
  37 in order to contribute to the project
  38
  39 &h2(Language)
  40 RMR is written in C, and thus a contributing developer to the core library should
  41 have an excellent working knowledge of C.
  42 There currently is one set of cross languages bindings supporting Python, and a
  43 developer wishing to contribute to the bindings source should be familiar with
  44 Python (version 3.7+) and with the Python &ital(ctypes) library.
  45
  46 &h2(Code Structure)
  47 RMR is designed to provide an insulation layer between user applications and
  48 the actual transport mechanism.
  49 Initially RMR was built on top of Nanosmg, and shortly after was ported to NNG
  50 (Nanomsg Next Generation).
  51 Because RMR presents the same API to the user application regardless of the underlying
  52 transport library, the resulting output when compiling RMR is a transport specific
  53 library.
  54 As an example, &cw(librmr_nng.a) is the library generated for use with the NNG
  55 transport.
  56 &space
  57
  58 As such the library source is organised into multiple components:
  59
  60 &beg_dlist(.75i : ^&bold_font )
  61
  62 &di(common) Source in the common directory is agnostic to the underlying transport
  63         mechanism (Nanomsg or NNG), and thus can be used when generating either library.
  64
  65 &di(nano) Source which is tightly coupled with the underlying Nanomsg library.
  66         (Nanomsg has been deprecated, but the RMR source remains as an example.)
  67
  68 &di(nng) Source which is tightly coupled with the underlying NNG library.
  69
  70 &end_dlist
  71
  72 &space
  73 &h3(Internal Function Exposure)
  74 The decision to limit as much as practical the exposure of truely internal RMR functions
  75 was made, and as a result most of the RMR functions carry a &cw(static) label.
  76 In order to modularise the code as much as possible, this means that the primary
  77 module (e.g. rmr_nng.c) will directly include other RMR modules, rather than
  78 depending on referencing the internal functions during linking.
  79 While this is an infrequently used approach, it does mean that there are very
  80 few functions visible for the user application to reference, all of them having
  81 the prefix &cw(rmr_,) while allowing internal functions to have shorter names
  82 while still being meaningful.
  83
  84 &h2(Coding Style)
  85 There is a list of coding style guidelines in the top level directory, and as such
  86 they are not expanded upon here.
  87 The general practice is to follow the style when editing an existing module, respect
  88 the author's choice where style alternatives are not frowned upon.
  89 When creating new modules, select a style that fits the guidelines and is easy
  90 for you to work with.
  91 There are a few things that are insisted on by the maintainers of RMR, but for the
  92 most part style is up to the creator of a module.
  93
  94 &h2(Building)
  95 RMR is constructed using CMake.
  96 While CMake's project description can be more cumbersome than most typical Makefiles,
  97 the tool provides convenience especially when it comes to creating packages.