Documentation changes needed to support RTD

[ric-plt/lib/rmr.git] / doc / src / rtd / developer-guide.xfm

diff --git a/doc/src/rtd/developer-guide.xfm b/doc/src/rtd/developer-guide.xfm
new file mode 100644 (file)
index 0000000..3cf3bb8
--- /dev/null
+++ b/doc/src/rtd/developer-guide.xfm
@@ -0,0 +1,97 @@
+.** vim: ts=4 noet sw=4:
+.if false
+==================================================================================
+       Copyright (c) 2019 Nokia
+       Copyright (c) 2018-2019 AT&T Intellectual Property.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+==================================================================================
+.fi
+
+
+.if false
+       Mnemonic:       config-deploy.xfm
+       Abstract:       Source to generate a configuration deployment guide.
+       Date:           6 November 2019
+       Author:         E. Scott Daniels
+.fi
+
+.im setup.im
+
+&h1(RMR Developer Guide)
+
+The RIC Message Router (RMR) is a library which applications use to send and receive
+messages where the message routing, endpoint selection, is based on the message type 
+rather than on traditional DNS names or IP addresses. 
+This document contains information that potential developers might need to know 
+in order to contribute to the project
+
+&h2(Language)
+RMR is written in C, and thus a contributing developer to the core library should 
+have an excellent working knowledge of C.
+There currently is one set of cross languages bindings supporting Python, and a
+developer wishing to contribute to the bindings source should be familiar with 
+Python (version 3.7+) and with the Python &ital(ctypes) library.
+
+&h2(Code Structure)
+RMR is designed to provide an insulation layer between user applications and 
+the actual transport mechanism.  
+Initially RMR was built on top of Nanosmg, and shortly after was ported to NNG
+(Nanomsg Next Generation).  
+Because RMR presents the same API to the user application regardless of the underlying
+transport library, the resulting output when compiling RMR is a transport specific
+library. 
+As an example, &cw(librmr_nng.a) is the library generated for use with the NNG
+transport.
+&space
+
+As such the library source is organised into multiple components:
+
+&beg_dlist(.75i : ^&bold_font )
+
+&di(common) Source in the common directory is agnostic to the underlying transport
+       mechanism (Nanomsg or NNG), and thus can be used when generating either library.
+
+&di(nano) Source which is tightly coupled with the underlying Nanomsg library.
+       (Nanomsg has been deprecated, but the RMR source remains as an example.)
+
+&di(nng) Source which is tightly coupled with the underlying NNG library.
+
+&end_dlist
+
+&space
+&h3(Internal Function Exposure)
+The decision to limit as much as practical the exposure of truely internal RMR functions
+was made, and as a result most of the RMR functions carry a &cw(static) label.
+In order to modularise the code as much as possible, this means that the primary
+module (e.g. rmr_nng.c) will directly include other RMR modules, rather than 
+depending on referencing the internal functions during linking.
+While this is an infrequently used approach, it does mean that there are very 
+few functions visible for the user application to reference, all of them having 
+the prefix &cw(rmr_,) while allowing internal functions to have shorter names
+while still being meaningful.
+
+&h2(Coding Style)
+There is a list of coding style guidelines in the top level directory, and as such
+they are not expanded upon here. 
+The general practice is to follow the style when editing an existing module, respect
+the author's choice where style alternatives are not frowned upon.
+When creating new modules, select a style that fits the guidelines and is easy
+for you to work with.
+There are a few things that are insisted on by the maintainers of RMR, but for the
+most part style is up to the creator of a module.
+
+&h2(Building)
+RMR is constructed using CMake.
+While CMake's project description can be more cumbersome than most typical Makefiles, 
+the tool provides convenience especially when it comes to creating packages.