OpenCSD - CoreSight Trace Decode Library  0.5
build_libs.md
Go to the documentation of this file.
1 Building and using the Library {#build_lib}
2 ==============================
3 
4 @brief How to build the library and test programs and include the library in an application
5 
6 Platform Support
7 ----------------
8 
9 The current makefiles and build projects support building the library on Linux and Windows,
10 x86 or x64 hosts.
11 
12 Support is expected for ARM linux and baremetal, AArch32 and AArch64 platforms.
13 
14 
15 Building the Library
16 --------------------
17 
18 The library and test programs are built from the library `./build/<platform>` directory.
19 
20 See [`./docs/test_progs.md`](@ref test_progs) for further information on use of the test
21 programs.
22 
23 ### Linux x86/x64 ###
24 
25 Go to the `./build/linux/` and run `make` in that directory.
26 
27 Options to pass to the makefile are:-
28 - `LINUX64=1` : build the 64 bit version of the library
29 - `DEBUG=1` : build the debug version of the library.
30 
31 Libraries are delivered to the `./lib/linux<bitsize>/<dbg\rel>` directories.
32 e.g. `./lib/linux64/rel` will contain the linux 64 bit release libraries.
33 
34 The following libraries are built:-
35 - `libcstraced.so` : shared library containing the main C++ based decoder library
36 - `libcstraced_c_api.so` : shared library containing the C-API wrapper library. Dependent on `libcstraced.so`
37 - `libcstraced.a` : static library containing the main C++ based decoder library.
38 - `libcstraced_c_api.a` : static library containing the C-API wrapper library.
39 
40 Test programs are delivered to the `./tests/bin/linux<bitsize>/<dgb\rel>` directories.
41 
42 The test programs are built to used the .so versions of the libraries.
43 - `trc_pkt_lister` - dependent on `libcstraced.so`.
44 - `simple_pkt_print_c_api` - dependent on `libcstraced_c_api.so` & hence `libcstraced.so`.
45 
46 The test program build for `trc_pkt_lister` also builds an auxiliary library used by this program for test purposes only.
47 This is the `libsnapshot_parser.a` library, delivered to the `./tests/lib/linux<bitsize>/<dgb\rel>` directories.
48 
49 ### Windows ###
50 
51 Use the `.\build\win\ref_trace_decode_lib\ref_trace_decode_lib.sln` file to load a solution
52 which contains all library and test build projects.
53 
54 Libraries are delivered to the `./lib/win<bitsize>/<dbg\rel>` directories.
55 e.g. `./lib/win64/rel` will contain the windows 64 bit release libraries.
56 
57 The solution contains four configurations:-
58 - *Debug* : builds debug versions of static C++ main library and C-API libraries, test programs linked to the static library.
59 - *Debug-dll* : builds debug versions of static main library and C-API DLL. C-API statically linked to the main library.
60 C-API test built as `simple_pkt_print_c_api-dl.exe` and linked against the DLL version of the C-API library.
61 - *Release* : builds release static library versions, test programs linked to static libraries.
62 - *Release-dll* : builds release C-API DLL, static main library.
63 
64 _Note_: Currently there is no Windows DLL version of the main C++ library. This may follow once
65 the project is nearer completion with further decode protocols, and the classes requiring export are established..
66 
67 Libraries built are:-
68 - `libcstraced.lib` : static main C++ decoder library.
69 - `cstraced_c_api.dll` : C-API DLL library. Statically linked against `libcstraced.lib` at .DLL build time.
70 - `libcstraced_c_api.lib` : C-API static library.
71 
72 There is also a project file to build an auxiliary library used `trc_pkt_lister` for test purposes only.
73 This is the `snapshot_parser_lib.lib` library, delivered to the `./tests/lib/win<bitsize>/<dgb\rel>` directories.
74 
75 
76 ### Additional Build Options ###
77 
78 __Library Virtual Address Size__
79 
80 The ocsd_if_types.h file includes a #define that controls the size of the virtual addresses
81 used within the library. By default this is a 64 bit `uint64_t` value.
82 
83 When building for ARM architectures that have only a 32 bit Virtual Address, and building on
84 32 bit ARM architectures it may be desirable to build a library that uses a v-addr size of
85 32 bits. Define `USE_32BIT_V_ADDR` to enable this option
86 
87 
88 Including the Library in an Application
89 ---------------------------------------
90 
91 The user source code includes a header according to the API to be used:-
92 
93 - Main C++ decoder library - include `opencsd.h`. Link to C++ library.
94 - C-API library - include `opencsd_c_api.h`. Link to C-API library.
95 
96 ### Linux build ###
97 
98 By default linux builds will link against the .so versions of the library. Using the C-API library will also
99 introduce a dependency on the main C++ decoder .so. Ensure that the library paths and link commands are part of the
100 application makefile.
101 
102 To use the static versions use appropriate linker options.
103 
104 ### Windows build ###
105 
106 To link against the C-API DLL, include the .DLL name as a dependency in the application project options.
107 
108 To link against the C-API static library, include the library name in the dependency list, and define the macro
109 `OCSD_USE_STATIC_C_API` in the preprocessor definitions. This ensures that the correct static bindings are declared in
110 the header file. Also link against the main C++ library.
111 
112 To link against the main C++ library include the library name in the dependency list.
113