[ceph.git] / ceph / src / boost / libs / test / doc / adv_scenarios / entry_point_overview.qbk

[/
 / Copyright (c) 2003 Boost.Test contributors 
 /
 / Distributed under the Boost Software License, Version 1.0. (See accompanying
 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 /]

[section:entry_point_overview Test module's entry point]

Typically, every C++ program contains exactly one definition of function `main`: the program's /entry point/.
When using the __UTF__ you do not have to define one. Function `main` will be generated for you by the framework.
The only thing you are required to do in case your program consists of more than one translation unit (`cpp` file)
is to indicate to the framework in which of the files it is supposed to generate function `main`.
You do it by defining macro __BOOST_TEST_MODULE__ before the inclusion of any of the framework files.
The value of this macro is used as a name of the [link ref_test_module test module] as well as the
[link boost_test.tests_organization.test_suite.master_test_suite master test suite]. 

The reason for defining function `main` for you is twofold:

# This allows the __UTF__ to perform some custom [link boost_test.adv_scenarios.test_module_init_overview ['test module initialization]].
# 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).

By default, the test module's entry point is defined with signature:

```
int main(int argc, char* argv[]);
```

It calls [link boost_test.adv_scenarios.test_module_init_overview ['test module initialization]] function, then calls the
[link boost_test.adv_scenarios.test_module_runner_overview ['test module runner]] and forwards its return value to environment.

The default entry point is sufficient in most of the cases. Occasionally, a need may arise to declare an entry point with a
different name or signature. For overriding the definition of the default test module's entry point:

* [link boost_test.adv_scenarios.single_header_customizations.entry_point see here], for single header usage variant,
* [link boost_test.adv_scenarios.static_lib_customizations.entry_point see here], for static library usage variant,
* [link boost_test.adv_scenarios.shared_lib_customizations.entry_point see here], for shared library usage variant.

[endsect] [/section:entry_point_overview]
Commit	Line	Data
7c673cae FG	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]