src/bindings/rmr-python/docs/source/index.rst

   1 rmr-python
   2 ==========
   3
   4 Summary, Limitations
   5 ====================
   6
   7 This is a CTYPES wrapper around the C rmr library. It requires you have
   8 rmr installed.
   9
  10 That is, it is not a native re-implementation of the rmr library. This
  11 seems to come with pros and cons. On the positive side, wrapping the
  12 library was much less work; we only need to wrap the function
  13 signatures. Keeping up with the rmr spec is thus also less work, as when
  14 new functions are added into the C lib, we only need to again wrap the
  15 function signatures.
  16
  17 The downside is this seems to be Linux only currently. This wrapper
  18 immediately SIGABRT’s on Mac, and no one yet seems to know why. The
  19 other downside is that there are currently some functionality that needs
  20 to be “exported” from the C library for this to be fully operational.
  21 For example, CTYPES does not have access to C header files, and
  22 important constants are defined in the C header files.
  23
  24 Possibly evaluate whether we could natively reimplement the API with the nano nng python
  25 bindings: https://pypi.org/project/pynng/
  26
  27 Not Yet Implemented
  28 -------------------
  29
  30 At the time of this writing (Aug 13 2019) The following C functions
  31 are not yet implemented in this library (do we need them?):
  32
  33 ::
  34
  35    1. `extern void rmr_free_msg`
  36    2. `extern rmr_mbuf_t* rmr_mtosend_msg`
  37    3. `extern rmr_mbuf_t* rmr_call` (this has some problems AFAIU from Scott)
  38    4. `extern rmr_mbuf_t* rmr_rcv_specific`
  39    5. `extern int rmr_get_rcvfd`
  40
  41 Unit Testing
  42 ============
  43
  44 ::
  45
  46    tox
  47    open htmlcov/index.html
  48
  49 Installation
  50 ============
  51
  52 Prequisites
  53 -----------
  54
  55 If rmr is *not* compiled on your system, see the below instructions for
  56 downloading and compiling rmr. This library expects that the rmr .so
  57 files are compiled and available.
  58
  59 From PyPi
  60 ---------
  61
  62 ::
  63
  64    pip install rmr==X.Y.Z
  65
  66 From Source
  67 -----------
  68
  69 ::
  70
  71    git clone "https://gerrit.o-ran-sc.org/r/ric-plt/lib/rmr"
  72    cd rmr/src/bindings/rmr-python/
  73    pip install .
  74
  75 Examples
  76 ========
  77
  78 See the ``examples`` directory.
  79
  80 Compiling rmr (if not already done on your system)
  81 ==================================================
  82
  83 (Note, you may or may not need sudo in your final command, depending on
  84 permissions to ``/usr/local``. The pack externals option to CMake is
  85 needed only if the NNG libary is not already installed on the system,
  86 and you do not wish to manually install it.)
  87
  88 ::
  89
  90    git clone https://gerrit.oran-osc.org/r/ric-plt/lib/rmr
  91    cd rmr
  92    mkdir .build; cd .build; cmake .. -DPACK_EXTERNALS=1; sudo make install