Fix message marker for src reset on send/rts
[ric-plt/lib/rmr.git] / 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.