X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=docs%2Fdeveloper-guide.rst;fp=docs%2Fdeveloper-guide.rst;h=b8dc8e1d22af99b773c73b791d11d00ba6ad6243;hb=02cf8dfcafb7380cda35beaa2aad783ffea87fa3;hp=0000000000000000000000000000000000000000;hpb=2f5d035eb3d2392a565713a4b2fc1c6f3e978e8e;p=ric-plt%2Fsdl.git diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst new file mode 100644 index 0000000..b8dc8e1 --- /dev/null +++ b/docs/developer-guide.rst @@ -0,0 +1,300 @@ +.. +.. Copyright (c) 2019 AT&T Intellectual Property. +.. Copyright (c) 2019 Nokia. +.. +.. Licensed under the Creative Commons Attribution 4.0 International +.. Public License (the "License"); you may not use this file except +.. in compliance with the License. You may obtain a copy of the License at +.. +.. https://creativecommons.org/licenses/by/4.0/ +.. +.. Unless required by applicable law or agreed to in writing, documentation +.. 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. +.. + + +############### +Developer Guide +############### + +.. raw:: pdf + + PageBreak + +.. contents:: + :depth: 3 + :local: + +.. raw:: pdf + + PageBreak + +Introduction +************ + +This is the developer guide of O-RAN SC SDL C++ library. +SDL implementation downloading (execute command in such directory where you want +to download SDL repository). + +Without commit hook:: + + git clone "https://gerrit.o-ran-sc.org/r/ric-plt/sdl" + +With commit hook:: + + git clone "https://gerrit.o-ran-sc.org/r/ric-plt/sdl" && (cd "sdl" && mkdir -p .git/hooks && curl -Lo `git rev-parse --git-dir`/hooks/commit-msg https://gerrit.o-ran-sc.org/r/tools/hooks/commit-msg; chmod +x `git rev-parse --git-dir`/hooks/commit-msg) + + +SDL has only few dependencies to other components and therefore SDL should be +quite simple to build and install to almost any modern Linux environment by +following instructions below. + +If not otherwise mentioned, commands in this document are executed in the +directory where the SDL repository has been cloned into. + +.. raw:: pdf + + PageBreak + +Compilation +*********** + +**Dependencies** + +C++ compiler supporting C++14 is required for compiling SDL. + +Currently, the following library is required while building: + +* boost +* hiredis +* doxygen (optional) + +Commands to install dependent packages in Fedora:: + + sudo dnf install boost-devel + sudo dnf install hiredis-devel + sudo dnf install doxygen + +Commands to install dependent packages in Debian/Ubuntu:: + + sudo apt install libboost-all-dev + sudo apt install libhiredis-dev + sudo apt install doxygen + +**Compilation in the Source Directory**:: + + ./autogen.sh + ./configure + make all + make test + +**Compilation in a Separate Build Directory** + +Both *configure* and *make* can be executed in a separate directory +(or directories) for keeping the source directory clean or for testing +different configuration options in parallel. For example:: + + ./autogen.sh + mkdir build + cd build + ../configure + make all + make test + +Note that if you compile SDL this way, all coming *configure* and *make* +commands are executed in the build directory like above. + +.. raw:: pdf + + PageBreak + +Installation +************ + +By default the shared library is installed to */usr/local/lib* and headers into +to */usr/local/include*. If this is not desired, then provide different path +when running *configure*, for example:: + + ./configure --prefix=$HOME + +Note that *configure* command allows plethora of additional options. For more +info:: + + ./configure --help + +After configuration has been done, run:: + + make install + +.. raw:: pdf + + PageBreak + +.. _building_sdl_api_doc: + +Building SDL API Document +************************* + +SDL API Documentation is a Doxygen document generated from SDL public header +files. + +One can generate Doxygen documentation locally by running commands:: + + ./autogen.sh + ./configure + make doxygen-doc + +in the directory where the SDL repository has been cloned to. + + +By default make doxygen-doc creates HTML, PDF and PS documents (if the needed +tools are available, check the output of *./configure* command to get the names +of missing tools). The documents are created to (paths are relative to the +directory where the SDL repository has been cloned to): + +* doxygen-doc/html/index.html +* doxygen-doc/shareddatalayer.pdf +* doxygen-doc/shareddatalayer.ps + + +Creation of different document formats can be controlled with various +--enable-doxygen-* and --disable-doxygen-* configuration options. For example +if only HTML document is needed, then run:: + + ./configure --disable-doxygen-pdf --disable-doxygen-ps + make doxygen-doc + +.. raw:: pdf + + PageBreak + +Running Tests +************* + +Unit Tests +========== + +Unit tests are compiled and executed by simply running:: + + make test + +By default all unit tests are executed. If *valgrind* is installed, then by +default unit test execution is analyzed with *valgrind*. + +Running specific test cases can be achieved by using *GTEST_FILTER* environment +variable. For example:: + + make test GTEST_FILTER=AsyncStorageTest* + +If *valgrind* is not desired (even if installed), then it can be disabled with +*USE_VALGRIND* environment variable:: + + make test USE_VALGRIND=false + +Additional *valgrind* arguments can be specified with *VALGRIND_EXTRA_ARGS* +environment variable. For example:: + + make test VALGRIND_EXTRA_ARGS='--track-fds=yes --log-file=mylog.txt' + +It is also possible to use the *testrunner* binary directly (after it has been +compiled). The *testrunner* binary supports all the command line options gtest +supports, for example:: + + make testrunner + ./testrunner --help + ./testrunner + ./testrunner --gtest_filter=AsyncStorageTest* + +Functional Tests +================ + +Functional tests are not yet available. + +.. raw:: pdf + + PageBreak + +Debugging SDL Binaries +********************** + +The testrunner and other binaries created by make into the working +directory are not real binaries but shell scripts (generated by automake) +used for running the real binaries. The real binaries are in .libs directory. +Normally this is not important, but when using gdb or other debugger/analyzer +tools it is important to use the real binary instead of the generated shell +script. + +Examples below demonstrate how one can run testrunner binary (unit tests) in +gdb debugger:: + + LD_LIBRARY_PATH=.libs gdb --args .libs/testrunner + LD_LIBRARY_PATH=.libs gdb --args .libs/testrunner --gtest_filter=AsyncStorageTest* + +.. raw:: pdf + + PageBreak + +Redis +***** + +When Redis type backend data storage is used, SDL requires Redis v4.0 or +greater. Older versions do not support extension modules. + +Redis Modules +============= + +When Redis type backend data storage is used, SDL requires that the following +Redis extension commands have been installed to runtime environment: + +* MSETPUB +* SETIE +* SETIEPUB +* SETNXPUB +* DELPUB +* DELIE +* DELIEPUB + +Implementation for these commands is produced by RIC DBaaS. In official RIC +deployments these commands are installed by DBaaS service to Redis +container(s). In development environment you may want install commands +manually to pod/container which is running Redis. + +**Manual Redis module installing** + +Redis module implementation downloading (execute command in such directory +where you want to download redis module implementation):: + + git clone "https://gerrit.o-ran-sc.org/r/ric-plt/dbaas" + +Installation to default system directory:: + + cd redismodule + ./autogen.sh + ./configure + make install + +Following line should be added to *redis.conf* file:: + + loadmodule /libredismodule.so + + should be replaced to match library installation directory path. + +*redis-server* must be restarted after configuration file update. + +Notice that *redis-server* takes path to configuration file as an argument. +If not given, *redis-server* will start with default parameter values and above +made *loadmodule* option is not effective. Refer to:: + + redis-server --help + +SDL API will check in connection setup phase that all required Redis extension +commands are available, if not then execution is aborted and error log is +written to identify which commands are missing. + +.. raw:: pdf + + PageBreak