r6.1.1:Building Guide (test)

Introduction

The test and benchmark program is a command line application with release or debug builds.

A platform is a combination of hardware, operating system and toolchain. The library has out-of-the-box support for certain broad platforms, where broad indicates particular components but where the versions vary, but it is problematic to exactly define which versions are supported due to the very large number of versions combined with lack of hardware, software and information.

Directory Layout

The source archive contains the following directory tree;

/test/bin/                            - the test and benchmark program binary ends up in here
/test/obj/                            - directory for object files for the test and benchmark program
/test/src/                            - test and benchmark program sources

In short; /test/bin contains the test binary, /liblfds611/obj is the temporary directory for object files and /liblfds611/src contains the source files.

The root contains a considerable number of files required for building on various platforms.

Supported Platforms

Out-of-the-box ports are provided for;

Hardware	Operating System	Toolchain Choices
x64	Windows 64-bit	1. Microsoft Visual Studio 2. Microsoft Windows SDK and GNUmake
x64 x86	Windows 32-bit	1. Microsoft Visual Studio 2. Visual C++ Express Edition 3. Microsoft Windows SDK and GNUmake
x64	Linux 64-bit	1. GCC and GNUmake
x64 x86 ARM	Linux 32-bit	1. GCC and GNUmake

The test programme is much simpler than the library and requires only to know the number of CPUs in the system and the ability to start threads and wait on threads to complete. As such, there are no meaningful versioning requirements.

Tested Platforms

The release variant of test programme, with both the static and the dynamic release builds of liblfds, has been built and run for five iterations, on the following platforms;

Hardware	NN/PC/LC¹	Operating System	Toolchain	Targets
Intel Core i5	1/2/4	Windows 7 build 7600 64-bit	Microsoft SDK for Windows 7 v7.1 and GNUmake 3.8.1	x64 (native) x86
VirtuaBox VM	1/2/2	Windows 7 build 7600 64-bit	Visual C++ 2008 Trial Edition	x64 (native) x86
EC2 VM m1.xlarge	?/?/4	Linux 3.2.34-55.46.amzn1.x86_64	GCC 4.6.2 20111027 and GNUmake 3.8.1	x64 (native)
EC2 VM c1.medium	?/?/2	Linux 3.2.34-55.46.amzn1.i686	GCC 4.6.2 20111027 and GNUmake 3.8.1	x86 (OS native, but 64-bit CPUs)
Cortex A15	1/1/2	Linux 3.4.0 armv71	GCC 4.6.3 and GNUmake 3.8.1	ARM (native)

1. Numa Nodes / Physical Cores / Logical Cores

Toolchain Notes

Microsoft Visual Studio is Microsoft's commerical, fully fledged development GUI. It is expensive and supports all Windows platforms (32 and 64-bit Windows and 32 and 64-bit CPUs).

Visual C++ Express Edition is Microsoft's free development GUI. It only supports x86 but in theory installation of the Microsoft Windows SDK makes the x64 compilers available.

Microsoft Windows SDK is Microsoft's free command line based development environment. It has no GUI, but supports all Windows platforms (32 and 64-bit Windows and 32 and 64-bit CPUs).

Building for Linux User-Mode

There is a GNUmake makefile, /test/makefile.linux, which has the following targets;

rel (release build)
dbg (debug build)

The makefile detects your CPU type by calling uname -m and so correctly produces 32 or 64 bit builds. On 32 bit Linux on 64 bit CPUs, what seems to happen is the OS lies about the CPU type and so fools the makefile into thinking it really is on a 32 bit platform.

The default build is debug.

The makefile does not build liblfds. The library must be build manually beforehand. The library can be built as a static library or shared object; the test and benchmark program will compile properly in both cases.

The test and benchmark makefile knows where it is in the liblfds directory structure and directly reads the /bin and /inc directories and as such the test and benchmark program will compile properly against both the static and shared object builds of liblfds.

The static build will then be runnable. The dynamic build will not, since the operating system will not be able to find the liblfds shared object. To resolve this issue, the shared object either must be installed on your system (e.g. copied into one of the usual shared object directories such as /usr/local/lib/ or /usr/lib/) or the environment variable LD_LIBRARY_PATH must have been set to include a path to the shared object.

Building for Windows User-Mode

Microsoft Visual Studio / Visual C++ Express Edition

There is a Visual Studio 2008 project file, /test/test.sln, which has the following platforms;

Win32 (for 32 bit CPUs)
x64 (for 64 bit CPUs)

and the following configurations;

Debug
Release

The default build is x64 debug.

With Visual C++ Express Edition, the x64 platform will not be available but in theory installation of the Microsoft Windows SDK makes the x64 compilers available.

As is customary with Visual Studio, each build has it's own object file and output binary directory (/test/obj/$(Platform)/$(Configuration) and /test/bin/$(Platform)/$(Configuration), respectively), so it is not necessary to clean between switching configuration or platform types.

This project file will (unlike the makefiles) automatically build the liblfds library and builds it as a static library, automatically correctly selecting debug or release. The project file does not detect the platform and so the x86 or x64 build type must be selected.

Microsoft Windows SDK=

There is a GNUmake makefile, /test/makefile.windows, which has the following targets;

rel (release build)
dbg (debug build)

The default build is debug.

To use this makefile, open a command shell and run vcvars*.bat as appropriate for your target platform. The particular vcvars batch file you run will select the target platform and the SDK ships with cross compilers, so it is possible on all platforms to build for all platforms.

The makefile does not build liblfds. The library must be build manually, as a static library, beforehand. The test and benchmark makefile knows where it is in the directory structure and directly reads the /liblfds611/bin and /liblfds611/inc directories, so it is not necessary to install liblfds on your system to build and run the test and benchmark program.

Usage

The test and benchmark program is run from the command line.

For usage documentation, see the testing and benchmarking guide.