Building Guide (libbenchmark)
Introducton
The libbenchmark library is used by benchmark, and depends upon liblfds711, liblfds700 and libshared. It is not used by, or needed to build, liblfds711.
The libbenchmark library uses a porting abstraction layer to mask platform differences. Building libbenchmark requires build files (makefile, etc) for your toolchain (GCC, gnumake, etc) and a port of the abstraction layer to your platform.
A small number of popular toolchains are supported out-of-the-box, along with porting abstraction layers which cover Windows (user-mode and kernel-mode) and Linux (user-mode). A kernel-mode Linux port is not yet present as it is not yet clear how to obtain high resolution timers in the Linux kernel, but where even before this is solved, libshared has to modify its thread abstraction to deal with the lack of a wait-for-thread-to-complete function in Linux kernel.
Supported Toolchains
The supported toolchains are;
- GCC and gnumake
- GCC, gnumake and kbuild (Linux kernel toolchain)
- MSVC and and gnumake (Windows user-mode toolchain - and, yup, gnumake, not nmake)
- WDK 7.1 (Windows XP/Vista/7 kernel toolchain)
Note that in 7.1.1, Visual Studio solution files are not provided. This is because there are over liblfds and the benchmark and benchmark libraries and programmes (seven projects in all) in the end due to the multple build variants (debug, release, library, DLL, kernel library, kernel DLL, and repeated twice, once for VS2012 and once for VS2013) what comes to something like ten thousand settings, all of which have to be set using a mouse and a GUI, which is not only extraordinarily time-consuming and error-prone, but emotionally agonizing.
Mac support is not available due to lack of access to a Mac.
Directory Structure
└───test_and_benchmark
└───libbenchmark : libbenchmark library
├───bin : output directory - the library file ends up here
├───build : build configuration directory - contains one directory per platform
│ ├───gcc_gnumake : GCC and gnumake
│ ├───gcc_gnumake_kbuild : GCC, gnumake, and kbuild
│ ├───msvc_and_gnumake : Microsoft Visual C (command line compiler) and gnumake
│ └───wdk_7.1 : WDK 7.1
├───inc : the public header files
│ └───libbenchmark
├───obj : temporary directory for object files
└───src : the source files
├───libbenchmark_benchmarkinstance : API for running a single benchmark
├───libbenchmark_benchmarks_btree_au_readn_writen : btree_au benchmark
├───libbenchmark_benchmarkset : API for all benchmarks for a given data structure
├───libbenchmark_benchmarks_freelist_push1_then_pop1 : freelist benchmark
├───libbenchmark_benchmarks_queue_umm_enqueue1_then_dequeue1 : queue_umm benchmark
├───libbenchmark_benchmarksuite : convenience API to easily run all benchmarks
├───libbenchmark_datastructures_btree_au : locking btree_au data structures
├───libbenchmark_datastructures_freelist : locking freelist data structures
├───libbenchmark_datastructures_queue_umm : locking queue_au data structures
├───libbenchmark_misc : misc
├───libbenchmark_porting_abstraction_layer : porting abstraction layer
├───libbenchmark_results : benchmark results storage API
├───libbenchmark_threadset : convenience API for handling issuing threads
├───libbenchmark_topology : processor/memory topology API
└───libbenchmark_topology_node : processor/memory topology node API
Building
The library directory tree contains at its top level directory called build.
This directory contains one directory per supported toolchain, where each such directory contains the files necessary to build for that toolchain. Detailed descriptions of how to build for each toolchain are given below, with one heading per toolchain.
The various other components (test, benchmark, etc) in their build files know the location of the resultant library file, so it does not need to be installed.
On all platforms, you need to clean between changing build types (debug, release, static, dynamic, profiled, etc), as there is only one directory used to hold object files.
Per-Toolchain Build Instructions
GCC and gnumake
└───test_and_benchmark
└───libbenchmark
└───build
└───gcc_gnumake
Makefile
To build, install GCC and gnumake, enter the build directory and type;
make
The following targets are available;
ar_cov : archive (.a), coverage ar_dbg : archive (.a), debug ar_prof : archive (.a), profiling ar_rel : archive (.a), release ar_tsan : archive (.a), thread sanitizer ar_vanilla : archive (.a), no specific-build arguments so_cov : shared (.so), coverage so_dbg : shared (.so), debug so_prof : shared (.so), profiling so_rel : shared (.so), release so_tsan : shared (.so), thread sanitizer so_vanilla : shared (.so), no specific-build arguments clean : what you'd expect
When switching from one target to another, clean must be made.
If building *_ar_tsan, libtsan must be installed. This is not necessary if building *_so_tsan.
GCC, gnumake and kbuild
└───test_and_benchmark
└───libbenchmark
└───build
└───gcc_gnumake_kbuild
Kbuild
Makefile
This platform cannot currently build.
There are two reasons for this. Firstly, although the build files are present, the porting abstraction layer is not fully implemented. Secondly, this build is currently broken because of a bug in the 7.0.0 porting abstraction layer. This happens where the libbenchmark library includes earlier versions of liblfds, to benchmark them. This will be fixed by a the release of 7.0.1.
To build, install GCC, gnumake, kbuild (and the Linux kernel headers), enter the build directory and type;
make
The makefile is complimentory (mint-flavoured :-) and simply issues the necessary kbuild command.
There are three targets;
clean help modules
Note that modules is the default build (i.e. with no arguments).
I do not properly understand kbuild. I've read the documentation; I find for example examples which have switches in which are simply not present in the documentation, and in general I don't see how libraries are built to fit in with larger projects. The most I can say about this build is that it compiles without warnings or errors. I am pretty sure it's not something which can be used as it is in a kernel build or driver, but anyone who knows enough to be developing such a thing should be able to take what is here (since it compiles against the kernel) and easily fit it into their work.
Any feedback on making this build proper is greatly appreciated.
MSVC and gnumake
└───test_and_benchmark
└───libbenchmark
└───build
└───msvc_and_gnumake
libbenchmark.def
makefile
To build, install an MSVC command line compiler, enter the build directory and type;
make
The following targets are available;
libdbg : archive (.lib), debug librel : archive (.lib), release dlldbg : shared (.dll), debug dllrel : shared (.dll), release clean : what you'd expect
When switching from one target to another, clean must be made.
WDK 7.1
└───test_and_benchmark
└───libbenchmark
└───build
└───wdk_7.1
dirs
driver_entry_renamed_to_avoid_compiler_warning.c
libbenchmark.def
readme_before_win_kernel_build.txt
runme_before_win_kernel_dynamic_lib_build.bat
runme_before_win_kernel_static_lib_build.bat
sources.dynamic
sources.static
All processor types are supported (x86, IA64, x64).
The WDK 7.1 kernel build environment is primitive and has a number of severe limitations; in particular, all source files must be in one directory and it is not possible to choose the output binary type (static or dynamic library) from the build command line; rather, a string has to be modified in a text file used by the build (!)
To deal with these limitations, it is necessary for a Windows kernel build to run a batch file prior to building. There are two batch files, one for static library builds and the other for dynamic library builds. They are idempotent; you can run them as often as you like and switch between them as often as you want. It's all fine.
Both batch files copy all the sources file into a single directory, libbenchmark/build/wdk7.1/single_dir_for_windows_kernel/.
The static library batch file will then copy libbenchmark/sources.static into libbenchmark/build/wdk7.1/single_dir_for_windows_kernel/, which will cause a static library to be built.
The dynamic library batch file will then copy libbenchmark/sources.dynamic into libbenchmark/build/wdk7.1/single_dir_for_windows_kernel/, which will cause a dynamic library to be built. It will also copy driver_entry_renamed_to_avoid_compiler_warning.c to libbenchmark/build/wdk7.1/single_dir_for_windows_kernel/driver_entry.c (note the renaming), since the linker requires the DriverEntry function to exist, even though it's not used.
To build, start a build command line as usual, indicating through the command line you select whether you are making a debug or release build. Then run the appropriate liblfds batch file to select a static or dynamic library. Then, finally, run build.exe in the libbenchmark/build/wdk_7.1/ directory, with whatever arguments you prefer.
Note that due to limitations in the build environment, object files appear in a subdirectory in libbenchmark/build/wdk7.1/single_dir_for_windows_kernel/, rather than in the usual libbenchmark/obj/. The final binary output however still appears almost as usual, in libbenchmark/bin/[processor]/, where processor might be i386. (The usual is just libbenchmark/bin/, with no subdirectories).
Note that the sources file used to compile the library asserts the define KERNEL_MODE. This appears to be necessary, due to the lack of a compiler-provided macro to differentiate in the code between a user-mode or kernel-mode build.