1Building 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 6Platform Support 7---------------- 8 9The 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 14In 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 17Building the Library 18-------------------- 19 20The library and test programs are built from the library `./build/<platform>` directory, where 21<platform> is either 'linux' or 'win-vs2015' 22 23See [`./docs/test_progs.md`](@ref test_progs) for further information on use of the test 24programs. 25 26### Linux x86/x64/ARM ### 27 28Libraries are built into a <tgt_dir>. This is used as the final output directory for the 29libraries in `decoder/lib/<tgt_dir>`, and also as a sub-directory of the build process for 30intermediate files - `decoder/build/linux/ref_trace_decode_lib/<tgt_dir>`. 31 32For a standard build, go to the `./build/linux/` and run `make` in that directory. 33 34This 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 36For development, alternatively use `make -f makefile.dev` 37 38This 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 40to be present during development. 41 42e.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 48Options to pass to both makefiles are:- 49- `DEBUG=1` : build the debug version of the library. 50 51Options 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 56For cross compilation, set the environment variable `CROSS_COMPILE` to the name path/prefix for the 57compiler 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 63The makefile will scan the `ocsd_if_version.h` to get the library version numbers and use these 64in the form Major.minor.patch when naming the output .so files. 65 66Main 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 71C 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 76Static 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 80Test programs are delivered to the `./tests/bin/<tgt_dir>` directories. 81 82The 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 86The test program build for `trc_pkt_lister` also builds an auxiliary library used by this program for test purposes only. 87This is the `libsnapshot_parser.a` library, delivered to the `./tests/lib/<tgt_dir>` directories. 88 89__Installing on Linux__ 90 91The 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 93e.g. ` make -f makefile.dev DEBUG=1 install` 94 95will install from `./lib/linux64/dbg` 96 97The libraries `libopencsd` and `libopencsd_c_api` are installed to `/usr/lib`. 98 99Sufficient header files to build using the C-API library will be installed to `/usr/include/opencsd`. 100 101The installation can be removed using `make clean_install`. No additional options are necessary. 102 103 104### Windows (x86/x64) ### 105 106Use the `.\build\win\ref_trace_decode_lib\ref_trace_decode_lib.sln` file to load a solution 107which contains all library and test build projects. 108 109Libraries are delivered to the `./lib/win<bitsize>/<dbg\rel>` directories. 110e.g. `./lib/win64/rel` will contain the windows 64 bit release libraries. 111 112The 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. 115C-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 120the project is nearer completion with further decode protocols, and the classes requiring export are established.. 121 122Libraries 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 127There is also a project file to build an auxiliary library used `trc_pkt_lister` for test purposes only. 128This 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 135The ocsd_if_types.h file includes a #define that controls the size of the virtual addresses 136used within the library. By default this is a 64 bit `uint64_t` value. 137 138When building for ARM architectures that have only a 32 bit Virtual Address, and building on 13932 bit ARM architectures it may be desirable to build a library that uses a v-addr size of 14032 bits. Define `USE_32BIT_V_ADDR` to enable this option 141 142 143Including the Library in an Application 144--------------------------------------- 145 146The 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 153By default linux builds will link against the .so versions of the library. Using the C-API library will also 154introduce a dependency on the main C++ decoder .so. Ensure that the library paths and link commands are part of the 155application makefile. 156 157To use the static versions use appropriate linker options. 158 159### Windows build ### 160 161To link against the C-API DLL, include the .DLL name as a dependency in the application project options. 162 163To 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 165the header file. Also link against the main C++ library. 166 167To link against the main C++ library include the library name in the dependency list. 168 169