[ceph.git] / ceph / src / boost / libs / test / doc / adv_scenarios / single_header_customizations.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:single_header_customizations Single-header variant customizations] 

[section:entry_point Customizing the module's entry point]

In this usage variant, in your single translation unit, you need to define macros __BOOST_TEST_NO_MAIN__ and
__BOOST_TEST_ALTERNATIVE_INIT_API__ (their values are irrelevant) prior to including any of the framework's headers.
Next, you have to define your custom entry point, and invoke the default [link
boost_test.adv_scenarios.test_module_runner_overview test runner] `unit_test_main` manually with the default [link
boost_test.adv_scenarios.test_module_init_overview initialization function] `init_unit_test` as argument.


[bt_example custom_main..using custom entry point..run-fail]

In the above example, a custom entry point was selected because the test module, in addition to command line arguments
needs to obtain also the information about environment variables.

[note The above example also illustrates that it makes sense to define both __BOOST_TEST_MODULE__ and
__BOOST_TEST_NO_MAIN__. This way, no `main` is generated by the framework, but the specified name is assigned to the
[link boost_test.tests_organization.test_suite.master_test_suite Master Test Suite].]

[note The reason for defining __BOOST_TEST_ALTERNATIVE_INIT_API__ is described [link
boost_test.adv_scenarios.obsolete_init_func here].]


[endsect] [/section:entry_point]

[section:init_func Customizing the module's initialization function]

In this usage variant, you do not define macro __BOOST_TEST_MODULE__ and instead provide the definition of function
`init_unit_test`. This is going to be the custom initialization function. The default [link
boost_test.adv_scenarios.test_module_runner_overview test runner] will use it to initialize the test module.


[bt_example custom_init..using custom initialization function..run-fail]

[note Because we overwrote the default initialization function, it does no longer assign any name to the [link
boost_test.tests_organization.test_suite.master_test_suite master test suite]. Therefore the default name ("Master Test
Suite") is used.]

[note The reason for defining __BOOST_TEST_ALTERNATIVE_INIT_API__ is described [link
boost_test.adv_scenarios.obsolete_init_func here].]


[endsect] [/section:init_func]

[endsect] [/section:single_header_customizations]
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:single_header_customizations Single-header variant customizations]
	9
	10	[section:entry_point Customizing the module's entry point]
	11
	12	In this usage variant, in your single translation unit, you need to define macros __BOOST_TEST_NO_MAIN__ and
	13	__BOOST_TEST_ALTERNATIVE_INIT_API__ (their values are irrelevant) prior to including any of the framework's headers.
	14	Next, you have to define your custom entry point, and invoke the default [link
	15	boost_test.adv_scenarios.test_module_runner_overview test runner] `unit_test_main` manually with the default [link
	16	boost_test.adv_scenarios.test_module_init_overview initialization function] `init_unit_test` as argument.
	17
	18
	19	[bt_example custom_main..using custom entry point..run-fail]
	20
	21	In the above example, a custom entry point was selected because the test module, in addition to command line arguments
	22	needs to obtain also the information about environment variables.
	23
	24	[note The above example also illustrates that it makes sense to define both __BOOST_TEST_MODULE__ and
	25	__BOOST_TEST_NO_MAIN__. This way, no `main` is generated by the framework, but the specified name is assigned to the
	26	[link boost_test.tests_organization.test_suite.master_test_suite Master Test Suite].]
	27
	28	[note The reason for defining __BOOST_TEST_ALTERNATIVE_INIT_API__ is described [link
	29	boost_test.adv_scenarios.obsolete_init_func here].]
	30
	31
	32	[endsect] [/section:entry_point]
	33
	34	[section:init_func Customizing the module's initialization function]
	35
	36	In this usage variant, you do not define macro __BOOST_TEST_MODULE__ and instead provide the definition of function
	37	`init_unit_test`. This is going to be the custom initialization function. The default [link
	38	boost_test.adv_scenarios.test_module_runner_overview test runner] will use it to initialize the test module.
	39
	40
	41	[bt_example custom_init..using custom initialization function..run-fail]
	42
	43	[note Because we overwrote the default initialization function, it does no longer assign any name to the [link
	44	boost_test.tests_organization.test_suite.master_test_suite master test suite]. Therefore the default name ("Master Test
	45	Suite") is used.]
	46
	47	[note The reason for defining __BOOST_TEST_ALTERNATIVE_INIT_API__ is described [link
	48	boost_test.adv_scenarios.obsolete_init_func here].]
	49
	50
	51
	52	[endsect] [/section:init_func]
	53
	54	[endsect] [/section:single_header_customizations]