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*
215 Functional tests are not yet available.
221 Debugging SDL Binaries
222 **********************
224 The testrunner and other binaries created by make into the working
225 directory are not real binaries but shell scripts (generated by automake)
226 used for running the real binaries. The real binaries are in .libs directory.
227 Normally this is not important, but when using gdb or other debugger/analyzer
228 tools it is important to use the real binary instead of the generated shell
231 Examples below demonstrate how one can run testrunner binary (unit tests) in
234 LD_LIBRARY_PATH=.libs gdb --args .libs/testrunner
235 LD_LIBRARY_PATH=.libs gdb --args .libs/testrunner --gtest_filter=AsyncStorageTest*
244 When Redis type backend data storage is used, SDL requires Redis v4.0 or
245 greater. Older versions do not support extension modules.
250 When Redis type backend data storage is used, SDL requires that the following
251 Redis extension commands have been installed to runtime environment:
261 Implementation for these commands is produced by RIC DBaaS. In official RIC
262 deployments these commands are installed by DBaaS service to Redis
263 container(s). In development environment you may want install commands
264 manually to pod/container which is running Redis.
266 **Manual Redis module installing**
268 Redis module implementation downloading (execute command in such directory
269 where you want to download redis module implementation)::
271 git clone "https://gerrit.o-ran-sc.org/r/ric-plt/dbaas"
273 Installation to default system directory::
280 Following line should be added to *redis.conf* file::
282 loadmodule <path>/libredismodule.so
284 <path> should be replaced to match library installation directory path.
286 *redis-server* must be restarted after configuration file update.
288 Notice that *redis-server* takes path to configuration file as an argument.
289 If not given, *redis-server* will start with default parameter values and above
290 made *loadmodule* option is not effective. Refer to::
294 SDL API will check in connection setup phase that all required Redis extension
295 commands are available, if not then execution is aborted and error log is
296 written to identify which commands are missing.