4d9851b9e139f1567007b60c99b6fd374a1ae217
[ric-plt/sdl.git] / docs / developer-guide.rst
1 ..
2 ..  Copyright (c) 2019 AT&T Intellectual Property.
3 ..  Copyright (c) 2019 Nokia.
4 ..
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
8 ..
9 ..    https://creativecommons.org/licenses/by/4.0/
10 ..
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.
14 ..
15 ..  See the License for the specific language governing permissions and
16 ..  limitations under the License.
17 ..
18
19
20 ###############
21 Developer Guide
22 ###############
23
24 .. raw:: pdf
25
26    PageBreak
27
28 .. contents::
29    :depth: 3
30    :local:
31
32 .. raw:: pdf
33
34    PageBreak
35
36 Introduction
37 ************
38
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).
42
43 Without commit hook::
44
45     git clone "https://gerrit.o-ran-sc.org/r/ric-plt/sdl"
46
47 With commit hook::
48
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)
50
51
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.
55
56 If not otherwise mentioned, commands in this document are executed in the
57 directory where the SDL repository has been cloned into.
58
59 .. raw:: pdf
60
61    PageBreak
62
63 Compilation
64 ***********
65
66 **Dependencies**
67
68 C++ compiler supporting C++14 is required for compiling SDL.
69
70 Currently, the following library is required while building:
71
72 * boost
73 * hiredis
74 * doxygen (optional)
75
76 Commands to install dependent packages in Fedora::
77
78     sudo dnf install boost-devel
79     sudo dnf install hiredis-devel
80     sudo dnf install doxygen
81
82 Commands to install dependent packages in Debian/Ubuntu::
83
84     sudo apt install libboost-all-dev
85     sudo apt install libhiredis-dev
86     sudo apt install doxygen
87
88 **Compilation in the Source Directory**::
89
90     ./autogen.sh
91     ./configure
92     make all
93     make test
94
95 **Compilation in a Separate Build Directory**
96
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::
100
101     ./autogen.sh
102     mkdir build
103     cd build
104     ../configure
105     make all
106     make test
107
108 Note that if you compile SDL this way, all coming *configure* and *make*
109 commands are executed in the build directory like above.
110
111 .. raw:: pdf
112
113    PageBreak
114
115 Installation
116 ************
117
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::
121
122     ./configure --prefix=$HOME
123
124 Note that *configure* command allows plethora of additional options. For more
125 info::
126
127     ./configure --help
128
129 After configuration has been done, run::
130
131     make install
132
133 .. raw:: pdf
134
135    PageBreak
136
137 .. _building_sdl_api_doc:
138
139 Building SDL API Document
140 *************************
141
142 SDL API Documentation is a Doxygen document generated from SDL public header
143 files.
144
145 One can generate Doxygen documentation locally by running commands::
146
147     ./autogen.sh
148     ./configure
149     make doxygen-doc
150
151 in the directory where the SDL repository has been cloned to.
152
153
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):
158
159 * doxygen-doc/html/index.html
160 * doxygen-doc/shareddatalayer.pdf
161 * doxygen-doc/shareddatalayer.ps
162
163
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::
167
168     ./configure --disable-doxygen-pdf --disable-doxygen-ps
169     make doxygen-doc
170
171 .. raw:: pdf
172
173    PageBreak
174
175 Running Tests
176 *************
177
178 Unit Tests
179 ==========
180
181 Unit tests are compiled and executed by simply running::
182
183     make test
184
185 By default all unit tests are executed. If *valgrind* is installed, then by
186 default unit test execution is analyzed with *valgrind*.
187
188 Running specific test cases can be achieved by using *GTEST_FILTER* environment
189 variable. For example::
190
191     make test GTEST_FILTER=AsyncStorageTest*
192
193 If *valgrind* is not desired (even if installed), then it can be disabled with
194 *USE_VALGRIND* environment variable::
195
196     make test USE_VALGRIND=false
197
198 Additional *valgrind* arguments can be specified with *VALGRIND_EXTRA_ARGS*
199 environment variable. For example::
200
201     make test VALGRIND_EXTRA_ARGS='--track-fds=yes --log-file=mylog.txt'
202
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::
206
207     make testrunner
208     ./testrunner --help
209     ./testrunner
210     ./testrunner --gtest_filter=AsyncStorageTest*
211
212 To get unit test code coverage analysis enable unit test gcov code coverage
213 analysis by configuring gcov reporting directory::
214
215     configure --with-gcov-report-dir=DIR
216
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.
219
220 Build and run unit tests with code coverage analysis::
221
222     make test_gcov
223
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.
226
227 In addition, graphical gcov front-ends such as lcov can be used for coverage
228 analysis::
229
230     lcov --directory tst/ --directory src --capture --output-file coverage.info
231     genhtml coverage.info --output-directory out
232
233 Open the out/index.html using any web browser.
234
235
236 Docker Tests
237 ============
238
239 It's also possible to test SDL compilation, run unit tests and test building of
240 rpm and Debian packages in a Docker::
241
242     docker build  --no-cache -f docker_test/Dockerfile-Test -t sdltest:latest .
243
244 If needed, ready rpm and Debian packages can be copied from Docker to host. In
245 below example packages are copied to host's /tmp/sdltest-packages directory::
246
247     docker run -v /tmp/sdltest-packages:/export sdltest:latest /export
248
249 Functional Tests
250 ================
251
252 Functional tests are not yet available.
253
254 .. raw:: pdf
255
256    PageBreak
257
258 Debugging SDL Binaries
259 **********************
260
261 The testrunner and other binaries created by make into the working
262 directory are not real binaries but shell scripts (generated by automake)
263 used for running the real binaries. The real binaries are in .libs directory.
264 Normally this is not important, but when using gdb or other debugger/analyzer
265 tools it is important to use the real binary instead of the generated shell
266 script.
267
268 Examples below demonstrate how one can run testrunner binary (unit tests) in
269 gdb debugger::
270
271     LD_LIBRARY_PATH=.libs gdb --args .libs/testrunner
272     LD_LIBRARY_PATH=.libs gdb --args .libs/testrunner --gtest_filter=AsyncStorageTest*
273
274 .. raw:: pdf
275
276    PageBreak
277
278 Redis
279 *****
280
281 When Redis type backend data storage is used, SDL requires Redis v4.0 or
282 greater. Older versions do not support extension modules.
283
284 Redis Modules
285 =============
286
287 When Redis type backend data storage is used, SDL requires that the following
288 Redis extension commands have been installed to runtime environment:
289
290 * MSETPUB
291 * SETIE
292 * SETIEPUB
293 * SETNXPUB
294 * DELPUB
295 * DELIE
296 * DELIEPUB
297
298 Implementation for these commands is produced by RIC DBaaS. In official RIC
299 deployments these commands are installed by DBaaS service to Redis
300 container(s). In development environment you may want install commands
301 manually to pod/container which is running Redis.
302
303 **Manual Redis module installing**
304
305 Redis module implementation downloading (execute command in such directory
306 where you want to download redis module implementation)::
307
308     git clone "https://gerrit.o-ran-sc.org/r/ric-plt/dbaas"
309
310 Installation to default system directory::
311
312     cd redismodule
313     ./autogen.sh
314     ./configure
315     make install
316
317 Following line should be added to *redis.conf* file::
318
319     loadmodule <path>/libredismodule.so
320
321 <path> should be replaced to match library installation directory path.
322
323 *redis-server* must be restarted after configuration file update.
324
325 Notice that *redis-server* takes path to configuration file as an argument.
326 If not given, *redis-server* will start with default parameter values and above
327 made *loadmodule* option is not effective. Refer to::
328
329     redis-server --help
330
331 SDL API will check in connection setup phase that all required Redis extension
332 commands are available, if not then execution is aborted and error log is
333 written to identify which commands are missing.
334
335 .. raw:: pdf
336
337    PageBreak