The Unit Test Framework compilation

Boost.Test > Components > The Test Framework > Compilation

# The Unit Test Framework compilation instructions

Unlike most boost libraries the Unit Test Framework compilation may require you to go one extra mile. There are several alternative options that you could consider:

- Build standalone static library (with possibility to use auto linking feature)
- Build standalone dynamic library (with possibility to use auto linking feature)
- Single header that includes all the implementation files
- Include the framework sources directly into your test module project

Each option has it's advantages and drawbacks. By default it's recommended to use standalone static library.

#### Building standalone library

The Unit Test Framework is comparatively complicated library and implemented in close to hundred header and source files. While there exist an alternative option to include the whole implementation directly into your test module, for the long term usage the preferable solution is to build the framework once and reuse it by linking to prebuild library. Depending on your hardware this may save you significant time during compilation and doesn't really require that much effort.

If you decided to go with standalone library, you first need to build one. There are a varity of make systems that allow you to do that. To name a few: GNU make and similar, all kinds of integrated development environments. Boost preferred solution is Boost.Build system, that is built on top of bjam tool. All make systems require some kind of configuration file that list all files that constitute the library and all the build options. For example makefile that is used by make, Microsoft Visual Studio project file, Jamfile that is used by Boost.Build. For the sake of simplicity lets call this file the makefile. To build a stanalone library following files, that are located in the Boost Test Library source directory, needs to be listed as source files in your makefile:

compiler_log_formatter.cpp
exception_safety.cpp
execution_monitor.cpp
framework.cpp
interaction_based.cpp
logged_expectations.cpp
plain_report_formatter.cpp
progress_monitor.cpp
results_collector.cpp
results_reporter.cpp
unit_test_log.cpp
unit_test_main.cpp
unit_test_monitor.cpp
unit_test_parameters.cpp
unit_test_suite.cpp
xml_log_formatter.cpp
xml_report_formatter.cpp

The Jamfile for use with Boost.Build system is supplied in libs/test/build directory.

##### Building static library

There are no additional build defines or options required to build static library. Using Boost.build system you could build the static library with a following command from libs/test/build directory:

bjam -sTOOLS=<your-tool-name> "-sBUILD="boost_unit_test_framework

Also on windows you could use this Microsoft Visual Studio .NET project file.

##### Building dynamic library

To build dynamic library you need to add BOOST_TEST_DYN_LINK to the list of defines in makefile. Using Boost.Build system you could build the dynamic library with a following command from libs/test/build directory:

bjam -sTOOLS=<your-tool-name> "-sBUILD=" boost_unit_test_framework

Also on windows you could use this Microsoft Visual Studio .NET project file.

Note that the same flag BOOST_TEST_DYN_LINK needs to be defined during test module compilation for it to successfully link with dynamic library.

##### Using autolinking feature

For the Microsoft family of compilers Boost Test provides an ability to automatically select proper library name and add it to the list of objects to be linked with. By default this feature is on. To disable this feature you should define the flag BOOST_TEST_NO_LIB. More detailes on autolinking feature implementation and configuration you could see here.

#### Using "included" option

While building standalone library is preferred solution, some users prefer "quick and dirty" include one. The Unit Test Framework provides an ability to do that. The only change that is required for you to employ it is the path to the header file you include. So the usual include staments:

    #define BOOST_TEST_MAIN ...
    #include <boost/test/unit_test.hpp>

    ...

becomes:

    #define BOOST_TEST_MAIN ...
    #include <boost/test/included/unit_test.hpp>

    ...

This way you don't need to link with any prebuild library. The whole Unit Test Framework implementation in included directly into your file. The autolionking feature is disabled also.

#### Including sources directly into test module project

Finally you could include all the files listed in build standalone library section directly into you test module makefile. Obviosly there is no sence to employ an options for dynamic build since you you are linking with implementation statically.

28 February, 2006