ceph/src/boost/libs/test/doc/closing_chapters/faq.qbk

   1 [/
   2  / Copyright (c) 2003 Boost.Test contributors
   3  /
   4  / Distributed under the Boost Software License, Version 1.0. (See accompanying
   5  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6  /]
   7
   8 [section:section_faq Frequently Asked Questions]
   9
  10 [h3 Where the latest version of the Boost Test Library is located?]
  11 The latest version of Boost Test Library is available online at [@http://www.boost.org/libs/test].
  12
  13 [h3 I found a bug. Where can I report it?]
  14 You can send a bug report to the boost users' mailing list and/or fill a ticket here [@https://svn.boost.org/trac/boost/].
  15
  16
  17 [h3 I have a request for a new feature. Where can I ask for it?]
  18 You can send a request to the boost developers' mailing list and/or and/or fill a ticket here [@https://svn.boost.org/trac/boost/].
  19
  20
  21 [h3 How to create test case using the Unit Test Framework?]
  22 To create a test case, use the macro
  23
  24   __BOOST_AUTO_TEST_CASE__( test_function );
  25
  26 For more details see the Unit Test Framework __BOOST_AUTO_TEST_CASE__ documentation.
  27
  28 [h3 How to create test suite using the Unit Test Framework?]
  29 To create a test suite use the macro
  30
  31   __BOOST_AUTO_TEST_SUITE__( suite_name );
  32
  33 For more details see the Unit Test Framework __BOOST_AUTO_TEST_SUITE__ documentation.
  34
  35
  36 [h3 Why did I get a linker error when compiling my test program?]
  37
  38 Boost Test Library components provide several usage variants: to create a test program you can
  39 link with the one of the precompiled library variants or use single-header variant. For example, to use Unit Test
  40 Framework you may either include
  41
  42 ``
  43   #include <boost/test/unit_test.hpp>
  44 ``
  45 and link with ``libunit_test_framework.lib`` or you can include
  46
  47 ``
  48  #include <boost/test/included/unit_test.hpp>
  49 ``
  50
  51 in which case you should not need to link with any precompiled component. Note also that
  52 you should strictly follow specification on initialization function in other case some compilers may produce linker
  53 error like this.
  54
  55 ``
  56   Unresolved external init_unit_test_suite(int, char**).
  57 ``
  58
  59
  60 The reason for this error is that in your implementation you should specify second argument of
  61 `init_unit_test_suite` exactly as in the specification, i.e.: `char* []`.
  62
  63 [h3 How can I redirect testing output?]
  64 Use ``unit_test_log::instance().set_log_output( std::ostream & )``
  65 For more details see the __UTF__ __output_test_stream_tool__ documentation.
  66
  67 [h3 I want different default log trace level]
  68 Use environment variable __BOOST_TEST_LOG_LEVEL__ to define desired log trace level. You still will be able to reset
  69 this value from the command line. For the list of acceptable values see the __UTF__
  70 __runtime_configuration__ documentation.
  71
  72 [h3 Is there DLL version of Boost.Test components available on Win32 platform?]
  73 Yes. Starting with Boost 1.34.0.
  74
  75
  76 [h3 How to set up a CMake project using __UTF__ (extended)]
  77
  78 Suppose, you are building a test module from one translation unit `test_file.cpp`. First, let's do it using the [link boost_test.usage_variants.single_header single-header usage variant] of the __UTF__.
  79
  80 Let's paste the following content in a `CMakeLists.txt`
  81 at the same location than our test file `test_file.cpp`:
  82
  83 [pre
  84 cmake_minimum_required(VERSION 2.8.7)
  85 project(my_first_test)
  86 enable_testing()
  87
  88 # indicates the location of the boost installation tree.
  89 # hard-coded for our simple example.
  90 set(BOOST_INCLUDE_DIRS $boost_installation_prefix/include)
  91
  92 # creates the executable
  93 add_executable(test_executable test_file.cpp)
  94 # indicates the include paths
  95 target_include_directories(test_executable PRIVATE ${BOOST_INCLUDE_DIRS})
  96
  97 # declares a test with our executable
  98 add_test(NAME test1 COMMAND test_executable)
  99 ]
 100
 101 We will now create the build directory for this project (separate directory),
 102 configure and build the project, as follow:
 103 ```
 104 > cd ``$``test_path
 105 > mkdir build     /*< we create a directory dedicated to the build, to avoid
 106                       any pollution of the sources with the temporary
 107                       build files >*/
 108 > cd build
 109 > cmake  ..       /*< configuration of the project >*/
 110 > cmake --build . /*< this command builds the project, cmake drives a native
 111                       tool that is configured on the previous command line >*/
 112 > ctest           /*< runs the tests declared in the project and prints a report >*/
 113 ```
 114
 115 In the case you are using the [link boost_test.usage_variants.shared_lib shared libraries] variant of __UTF__,
 116 some modifications should be done in your CMakeLists.txt.
 117
 118 [pre
 119 cmake_minimum_required(VERSION 2.8.11)
 120 project(my_first_test)
 121 enable_testing()
 122
 123 # replace XX with the version you have
 124 set(Boost_ADDITIONAL_VERSIONS "1.XX" "1.XX.0")
 125
 126 # finds boost, triggers an error otherwise
 127 find_package(Boost XX REQUIRED COMPONENTS unit_test_framework)
 128
 129 # creates the executable
 130 add_executable(test_executable test_file.cpp)
 131 # indicates the include paths
 132 target_include_directories(test_executable PRIVATE ${Boost_INCLUDE_DIRS})
 133 # indicates the shared library variant
 134 target_compile_definitions(test_executable PRIVATE "BOOST_TEST_DYN_LINK=1")
 135 # indicates the link paths
 136 target_link_libraries(test_executable ${Boost_UNIT_TEST_FRAMEWORK_LIBRARY})
 137
 138 # declares a test with our executable
 139 add_test(NAME test1 COMMAND test_executable)
 140
 141 ]
 142
 143 We will now create the build directory for this project (separate directory), configure and build the project,
 144 as follow:
 145 ```
 146 > cd ``$``test_path
 147 > mkdir build /*< we create a directory dedicated to the build, to avoid any pollution of the sources with the temporary
 148                   build files >*/
 149 > cd build
 150 > cmake -DBOOST_ROOT=``$``boost_installation_prefix .. /*< configuration of the project, the `BOOST_ROOT` configuration element indicates the
 151                                                            Boost module of `cmake` where to find our installation >*/
 152 > cmake --build . /*< this command builds the project, cmake drives a native tool that is configured on the
 153                       previous command line >*/
 154 > ctest           /*< runs the tests declared in the project and prints a report >*/
 155 ```
 156
 157
 158
 159 [endsect] [/faq]