ceph/src/boost/libs/test/doc/adv_scenarios/entry_point_overview.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:entry_point_overview Test module's entry point]
   9
  10 Typically, every C++ program contains exactly one definition of function `main`: the program's /entry point/.
  11 When using the __UTF__ you do not have to define one. Function `main` will be generated for you by the framework.
  12 The only thing you are required to do in case your program consists of more than one translation unit (`cpp` file)
  13 is to indicate to the framework in which of the files it is supposed to generate function `main`.
  14 You do it by defining macro __BOOST_TEST_MODULE__ before the inclusion of any of the framework files.
  15 The value of this macro is used as a name of the [link ref_test_module test module] as well as the
  16 [link boost_test.tests_organization.test_suite.master_test_suite master test suite].
  17
  18 The reason for defining function `main` for you is twofold:
  19
  20 # This allows the __UTF__ to perform some custom [link boost_test.adv_scenarios.test_module_init_overview ['test module initialization]].
  21 # This prevents you defining `main`, and accidentally forgetting to run all the test (in which case running the program would incorrectly indicate a clean run).
  22
  23 By default, the test module's entry point is defined with signature:
  24
  25 ```
  26 int main(int argc, char* argv[]);
  27 ```
  28
  29 It calls [link boost_test.adv_scenarios.test_module_init_overview ['test module initialization]] function, then calls the
  30 [link boost_test.adv_scenarios.test_module_runner_overview ['test module runner]] and forwards its return value to environment.
  31
  32 The default entry point is sufficient in most of the cases. Occasionally, a need may arise to declare an entry point with a
  33 different name or signature. For overriding the definition of the default test module's entry point:
  34
  35 * [link boost_test.adv_scenarios.single_header_customizations.entry_point see here], for single header usage variant,
  36 * [link boost_test.adv_scenarios.static_lib_customizations.entry_point see here], for static library usage variant,
  37 * [link boost_test.adv_scenarios.shared_lib_customizations.entry_point see here], for shared library usage variant.
  38
  39 [endsect] [/section:entry_point_overview]