2 .. Copyright (c) 2019 AT&T Intellectual Property.
3 .. Copyright (c) 2019 Nokia.
5 .. Licensed under the Creative Commons Attribution 4.0 International
6 .. Public License (the "License"); you may not use this file except
7 .. in compliance with the License. You may obtain a copy of the License at
9 .. https://creativecommons.org/licenses/by/4.0/
11 .. Unless required by applicable law or agreed to in writing, documentation
12 .. distributed under the License is distributed on an "AS IS" BASIS,
13 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 .. See the License for the specific language governing permissions and
16 .. limitations under the License.
39 This is the developer guide of O-RAN SC SDL C++ library.
40 SDL implementation downloading (execute command in such directory where you want
41 to download SDL repository).
45 git clone "https://gerrit.o-ran-sc.org/r/ric-plt/sdl"
49 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)
52 SDL has only few dependencies to other components and therefore SDL should be
53 quite simple to build and install to almost any modern Linux environment by
54 following instructions below.
56 If not otherwise mentioned, commands in this document are executed in the
57 directory where the SDL repository has been cloned into.
68 C++ compiler supporting C++14 is required for compiling SDL.
70 Currently, the following library is required while building:
76 Commands to install dependent packages in Fedora::
78 sudo dnf install boost-devel
79 sudo dnf install hiredis-devel
80 sudo dnf install doxygen
82 Commands to install dependent packages in Debian/Ubuntu::
84 sudo apt install libboost-all-dev
85 sudo apt install libhiredis-dev
86 sudo apt install doxygen
88 **Compilation in the Source Directory**::
95 **Compilation in a Separate Build Directory**
97 Both *configure* and *make* can be executed in a separate directory
98 (or directories) for keeping the source directory clean or for testing
99 different configuration options in parallel. For example::
108 Note that if you compile SDL this way, all coming *configure* and *make*
109 commands are executed in the build directory like above.
118 By default the shared library is installed to */usr/local/lib* and headers into
119 to */usr/local/include*. If this is not desired, then provide different path
120 when running *configure*, for example::
122 ./configure --prefix=$HOME
124 Note that *configure* command allows plethora of additional options. For more
129 After configuration has been done, run::
137 .. _building_sdl_api_doc:
139 Building SDL API Document
140 *************************
142 SDL API Documentation is a Doxygen document generated from SDL public header
145 One can generate Doxygen documentation locally by running commands::
151 in the directory where the SDL repository has been cloned to.
154 By default make doxygen-doc creates HTML, PDF and PS documents (if the needed
155 tools are available, check the output of *./configure* command to get the names
156 of missing tools). The documents are created to (paths are relative to the
157 directory where the SDL repository has been cloned to):
159 * doxygen-doc/html/index.html
160 * doxygen-doc/shareddatalayer.pdf
161 * doxygen-doc/shareddatalayer.ps
164 Creation of different document formats can be controlled with various
165 --enable-doxygen-* and --disable-doxygen-* configuration options. For example
166 if only HTML document is needed, then run::
168 ./configure --disable-doxygen-pdf --disable-doxygen-ps
181 Unit tests are compiled and executed by simply running::
185 By default all unit tests are executed. If *valgrind* is installed, then by
186 default unit test execution is analyzed with *valgrind*.
188 Running specific test cases can be achieved by using *GTEST_FILTER* environment
189 variable. For example::
191 make test GTEST_FILTER=AsyncStorageTest*
193 If *valgrind* is not desired (even if installed), then it can be disabled with
194 *USE_VALGRIND* environment variable::
196 make test USE_VALGRIND=false
198 Additional *valgrind* arguments can be specified with *VALGRIND_EXTRA_ARGS*
199 environment variable. For example::
201 make test VALGRIND_EXTRA_ARGS='--track-fds=yes --log-file=mylog.txt'
203 It is also possible to use the *testrunner* binary directly (after it has been
204 compiled). The *testrunner* binary supports all the command line options gtest
205 supports, for example::
210 ./testrunner --gtest_filter=AsyncStorageTest*
212 To get unit test code coverage analysis enable unit test gcov code coverage
213 analysis by configuring gcov reporting directory:
215 configure --with-gcov-report-dir=DIR
217 Directory can be an absolute path or a relative path to an SDL source root.
218 Unit test build creates directory if it does not exist.
220 Build and run unit tests with code coverage analysis:
224 After successful unit test run code coverage (.gcov) result files are in
225 a directory, what was defined by '--with-gcov-report-dir' configure option.
227 In addition, graphical gcov front-ends such as lcov can be used for coverage
230 lcov --directory tst/ --directory src --capture --output-file coverage.info
231 genhtml coverage.info --output-directory out
233 Open the out/index.html using any web browser.
238 Functional tests are not yet available.
244 Debugging SDL Binaries
245 **********************
247 The testrunner and other binaries created by make into the working
248 directory are not real binaries but shell scripts (generated by automake)
249 used for running the real binaries. The real binaries are in .libs directory.
250 Normally this is not important, but when using gdb or other debugger/analyzer
251 tools it is important to use the real binary instead of the generated shell
254 Examples below demonstrate how one can run testrunner binary (unit tests) in
257 LD_LIBRARY_PATH=.libs gdb --args .libs/testrunner
258 LD_LIBRARY_PATH=.libs gdb --args .libs/testrunner --gtest_filter=AsyncStorageTest*
267 When Redis type backend data storage is used, SDL requires Redis v4.0 or
268 greater. Older versions do not support extension modules.
273 When Redis type backend data storage is used, SDL requires that the following
274 Redis extension commands have been installed to runtime environment:
284 Implementation for these commands is produced by RIC DBaaS. In official RIC
285 deployments these commands are installed by DBaaS service to Redis
286 container(s). In development environment you may want install commands
287 manually to pod/container which is running Redis.
289 **Manual Redis module installing**
291 Redis module implementation downloading (execute command in such directory
292 where you want to download redis module implementation)::
294 git clone "https://gerrit.o-ran-sc.org/r/ric-plt/dbaas"
296 Installation to default system directory::
303 Following line should be added to *redis.conf* file::
305 loadmodule <path>/libredismodule.so
307 <path> should be replaced to match library installation directory path.
309 *redis-server* must be restarted after configuration file update.
311 Notice that *redis-server* takes path to configuration file as an argument.
312 If not given, *redis-server* will start with default parameter values and above
313 made *loadmodule* option is not effective. Refer to::
317 SDL API will check in connection setup phase that all required Redis extension
318 commands are available, if not then execution is aborted and error log is
319 written to identify which commands are missing.