ceph/src/boost/libs/test/doc/adv_scenarios/obsolete_init_func.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:obsolete_init_func The obsolete initialization function]
   9
  10 For backwards compatibility, the __UTF__ also allows the customization of an initialization function of a different type.
  11 This is called the ['obsolete initialization function]. Its signature is:
  12
  13 ```
  14 boost::unit_test::test_suite* init_unit_test_suite(int argc, char* argv[]);
  15 ```
  16
  17 The original design of the __UTF__ required of the programmer to implement it. It was intended to initialize and return
  18 the __master_test_suite__. No [link ref_BOOST_AUTO_TEST_CASE automatic test case registration] was available at that
  19 time. The null-pointer value was considered an initialization error.
  20
  21 In the single-header usage variant, you fall back to the obsolete initialization function signature by omitting the
  22 definition of macro __BOOST_TEST_ALTERNATIVE_INIT_API__ in test module code.
  23
  24 [bt_example custom_obsolete_init..using obsolete initialization function..run-fail]
  25
  26 In the static-library usage variant, you need to omit the definition of macro __BOOST_TEST_ALTERNATIVE_INIT_API__ in test
  27 module and compile the __UTF__ static library without the compilation flag __BOOST_TEST_ALTERNATIVE_INIT_API__ (this is
  28 the default).
  29
  30 In the shared-library usage variant, it is not possible to use the obsolete initialization function.
  31
  32 Even if you decide to us the obsolete initialization function, it is recommended that:
  33
  34 # You always return a null-pointer value and install the master test suite via
  35   [memberref boost::unit_test::test_suite::add `test_suite::add`] as illustrated
  36   [link ref_BOOST_TEST_CASE here]. The current framework does no longer treat the
  37   null-pointer value as failure.
  38 # You signal the failure by throwing [classref boost::unit_test::framework::setup_error] exception.
  39 # You access the command-line arguments through the interface of the __master_test_suite__,
  40   and ignore the function's arguments `argc` and `argv`.
  41
  42 [caution The obsolete initialization function is deprecated. It is recommended, to move from the old initialization
  43 function API, and rely on the automated test unit registration and [link boost_test.tests_organization.fixtures
  44 fixtures] (including [link boost_test.tests_organization.fixtures.global global fixtures]) for other set-up. ]
  45
  46 [endsect] [/section:obsolete_init_func]