OpenCSD - CoreSight Trace Decode Library  1.1.1
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:
10  - Linux and Windows, x86 or x64 hosts.
11  - ARM linux - AArch32 and AArch64
12  - ARM aarch32 and aarch64 libs, x-compiled on x86/64 hosts.
13 
14 In addition to building the library from the project, the library may be installed into the standard
15 `/usr/lib/` area in Linux, and will soon be available as a package from Linux Distros.
16 
17 Building the Library
18 --------------------
19 
20 The library and test programs are built from the library `./build/<platform>` directory, where
21 <platform> is either 'linux' or 'win-vs2015'
22 
23 See [`./docs/test_progs.md`](@ref test_progs) for further information on use of the test
24 programs.
25 
26 ### Linux x86/x64/ARM ###
27 
28 Libraries are built into a <tgt_dir>. This is used as the final output directory for the
29 libraries in `decoder/lib/<tgt_dir>`, and also as a sub-directory of the build process for
30 intermediate files - `decoder/build/linux/ref_trace_decode_lib/<tgt_dir>`.
31 
32 For a standard build, go to the `./build/linux/` and run `make` in that directory.
33 
34 This will set <tgt_dir> to `builddir` for all build variants of the library. Using this only one variant of the library can be built at any one time.
35 
36 For development, alternatively use `make -f makefile.dev`
37 
38 This will set <tgt_dir> to `linux<bit-variant>/<dbg|rel>` and therefore build libraries into the
39 `decoder/lib/linux<bit-variant>/<dbg|rel>` directories, allowing multiple variants of the library
40 to be present during development.
41 
42 e.g.
43 
44 `./lib/linux64/rel` will contain the linux 64 bit release libraries.
45 
46 `./lib/linux-arm64/dbg` will contain the linux aarch 64 debug libraries for ARM.
47 
48 Options to pass to both makefiles are:-
49 - `DEBUG=1` : build the debug version of the library.
50 
51 Options to pass to makefile.dev are:-
52 - ARCH=<arch> : sets the bit variant in the delivery directories. Set if cross compilation for ARCH
53  other than host. Otherwise ARCH is auto-detected.
54  <arch> can be x86, x86_64, arm, arm64, aarch64, aarch32
55 
56 For cross compilation, set the environment variable `CROSS_COMPILE` to the name path/prefix for the
57 compiler to use. The following would set the environment to cross-compile for ARM
58 
59  export PATH=$PATH:~/work/gcc-x-aarch64-6.2/bin
60  export ARCH=arm64
61  export CROSS_COMPILE=aarch64-linux-gnu-
62 
63 The makefile will scan the `ocsd_if_version.h` to get the library version numbers and use these
64 in the form Major.minor.patch when naming the output .so files.
65 
66 Main C++ library names:
67 - `libcstraced.so.M.m.p` : shared library containing the main C++ based decoder library
68 - `libcstrace.so.M` : symbolic link name to library - major version only.
69 - `libcstrace.so` : symbolic link name to library - no version.
70 
71 C API wrapper library names:
72 - `libcstraced_c_api.so.M.m.p` : shared library containing the C-API wrapper library. Dependent on `libcstraced.so.M`
73 - `libcstraced_c_api.so.M` : symbolic link name to library - major version only.
74 - `libcstraced_c_api.so` : symbolic link name to library - no version.
75 
76 Static versions of the libraries:
77 - `libcstraced.a` : static library containing the main C++ based decoder library.
78 - `libcstraced_c_api.a` : static library containing the C-API wrapper library.
79 
80 Test programs are delivered to the `./tests/bin/<tgt_dir>` directories.
81 
82 The test programs are built to used the .so versions of the libraries.
83 - `trc_pkt_lister` - dependent on `libcstraced.so`.
84 - `simple_pkt_print_c_api` - dependent on `libcstraced_c_api.so` & hence `libcstraced.so`.
85 
86 The test program build for `trc_pkt_lister` also builds an auxiliary library used by this program for test purposes only.
87 This is the `libsnapshot_parser.a` library, delivered to the `./tests/lib/<tgt_dir>` directories.
88 
89 __Installing on Linux__
90 
91 The libraries can be installed on linux using the `make install` command. This will usually require root privileges. Installation will be the version in the `./lib/<tgt_dir>` directory, according to options chosen.
92 
93 e.g. ` make -f makefile.dev DEBUG=1 install`
94 
95 will install from `./lib/linux64/dbg`
96 
97 The libraries `libopencsd` and `libopencsd_c_api` are installed to `/usr/lib`.
98 
99 Sufficient header files to build using the C-API library will be installed to `/usr/include/opencsd`.
100 
101 The installation can be removed using `make clean_install`. No additional options are necessary.
102 
103 
104 ### Windows (x86/x64) ###
105 
106 Use the `.\build\win\ref_trace_decode_lib\ref_trace_decode_lib.sln` file to load a solution
107 which contains all library and test build projects.
108 
109 Libraries are delivered to the `./lib/win<bitsize>/<dbg\rel>` directories.
110 e.g. `./lib/win64/rel` will contain the windows 64 bit release libraries.
111 
112 The solution contains four configurations:-
113 - *Debug* : builds debug versions of static C++ main library and C-API libraries, test programs linked to the static library.
114 - *Debug-dll* : builds debug versions of static main library and C-API DLL. C-API statically linked to the main library.
115 C-API test built as `simple_pkt_print_c_api-dl.exe` and linked against the DLL version of the C-API library.
116 - *Release* : builds release static library versions, test programs linked to static libraries.
117 - *Release-dll* : builds release C-API DLL, static main library.
118 
119 _Note_: Currently there is no Windows DLL version of the main C++ library. This may follow once
120 the project is nearer completion with further decode protocols, and the classes requiring export are established..
121 
122 Libraries built are:-
123 - `libcstraced.lib` : static main C++ decoder library.
124 - `cstraced_c_api.dll` : C-API DLL library. Statically linked against `libcstraced.lib` at .DLL build time.
125 - `libcstraced_c_api.lib` : C-API static library.
126 
127 There is also a project file to build an auxiliary library used `trc_pkt_lister` for test purposes only.
128 This is the `snapshot_parser_lib.lib` library, delivered to the `./tests/lib/win<bitsize>/<dgb\rel>` directories.
129 
130 
131 ### Additional Build Options ###
132 
133 __Library Virtual Address Size__
134 
135 The ocsd_if_types.h file includes a #define that controls the size of the virtual addresses
136 used within the library. By default this is a 64 bit `uint64_t` value.
137 
138 When building for ARM architectures that have only a 32 bit Virtual Address, and building on
139 32 bit ARM architectures it may be desirable to build a library that uses a v-addr size of
140 32 bits. Define `USE_32BIT_V_ADDR` to enable this option
141 
142 
143 Including the Library in an Application
144 ---------------------------------------
145 
146 The user source code includes a header according to the API to be used:-
147 
148 - Main C++ decoder library - include `opencsd.h`. Link to C++ library.
149 - C-API library - include `opencsd_c_api.h`. Link to C-API library.
150 
151 ### Linux build ###
152 
153 By default linux builds will link against the .so versions of the library. Using the C-API library will also
154 introduce a dependency on the main C++ decoder .so. Ensure that the library paths and link commands are part of the
155 application makefile.
156 
157 To use the static versions use appropriate linker options.
158 
159 ### Windows build ###
160 
161 To link against the C-API DLL, include the .DLL name as a dependency in the application project options.
162 
163 To link against the C-API static library, include the library name in the dependency list, and define the macro
164 `OCSD_USE_STATIC_C_API` in the preprocessor definitions. This ensures that the correct static bindings are declared in
165 the header file. Also link against the main C++ library.
166 
167 To link against the main C++ library include the library name in the dependency list.
168