diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9db99e0469..c2be717ab4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -43,7 +43,7 @@ jobs: with: enable_pr_coverage: false # Disabled: Too many issues with lcov enable_cygwin: false - depinst_args: --include doc/examples + depinst_args: --include doc/modules enable_mingw: false enable_multiarch: false timeout: 360 @@ -62,3 +62,62 @@ jobs: # CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} Disabled: Too many issues with lcov COVERITY_SCAN_NOTIFICATION_EMAIL: ${{ secrets.COVERITY_SCAN_NOTIFICATION_EMAIL }} COVERITY_SCAN_TOKEN: ${{ secrets.COVERITY_SCAN_TOKEN }} + + antora: + name: Antora docs + runs-on: ubuntu-latest + defaults: + run: + shell: bash + steps: + - name: Install packages + uses: alandefreitas/cpp-actions/package-install@v1.8.8 + with: + apt-get: git cmake + + - name: Clone Boost.Test + uses: actions/checkout@v4 + + # MrDocs compiles an umbrella translation unit against the rest of Boost, + # so the dependencies have to be on disk. `scan-modules-ignore: test` + # keeps the clone from bringing in a second copy of this library. + - name: Clone Boost + uses: alandefreitas/cpp-actions/boost-clone@v1.8.8 + id: boost-clone + with: + branch: ${{ (github.ref_name == 'master' && github.ref_name) || 'develop' }} + boost-dir: ../boost-source + scan-modules-dir: . + scan-modules-ignore: test + + - uses: actions/setup-node@v4 + with: + node-version: 18 + + - name: Build Antora docs + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + git config --global --add safe.directory "$(pwd)" + + cd .. + BOOST_SRC_DIR="$(pwd)/boost-source" + export BOOST_SRC_DIR + + cd test/doc + bash ./build_antora.sh + + # Antora returns zero even when it fails, so check the site exists. + # build_antora.sh additionally passes --log-failure-level=warn when + # CI is set, which makes an unresolved xref or include fatal. + if [ ! -d "html" ] + then + echo "Antora build failed" + exit 1 + fi + + - name: Create Antora docs artifact + uses: actions/upload-artifact@v4 + with: + name: antora-docs + path: doc/html diff --git a/README.md b/README.md index fd191d35b0..b4acfac6a8 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -![boosttest logo](doc/html/images/boost.test.logo.png) +![boosttest logo](doc/modules/ROOT/images/boost.test.logo.png) # What is Boost.Test? Boost.Test is a C++11/14/17 unit testing library, available on a wide range of platforms and compilers. diff --git a/build/CMakeLists.txt b/build/CMakeLists.txt index 4b441836ec..4ecaa8c9ce 100644 --- a/build/CMakeLists.txt +++ b/build/CMakeLists.txt @@ -121,11 +121,12 @@ set_target_properties(boost_test_framework_shared PROPERTIES FOLDER "UTF") # Documentation files (files only, no target) file(GLOB_RECURSE BOOST_UTF_DOC_FILES - ${BOOST_TEST_ROOT_DIR}/doc/*.qbk) + ${BOOST_TEST_ROOT_DIR}/doc/modules/ROOT/pages/*.adoc + ${BOOST_TEST_ROOT_DIR}/doc/modules/ROOT/nav.adoc) add_custom_target( - quickbook + documentation SOURCES ${BOOST_UTF_DOC_FILES}) -set_property(TARGET quickbook PROPERTY FOLDER "Documentation/") +set_property(TARGET documentation PROPERTY FOLDER "Documentation/") # Unit tests add_subdirectory(${BOOST_TEST_ROOT_DIR}/test tmp_folders_tests) diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000000..e675fe9019 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,7 @@ +html/ +node_modules/ +build/ +reference-output/ +antora.log +.superproject-playbook.yml +mrdocs.yml.bak diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt new file mode 100644 index 0000000000..5a1f930fbf --- /dev/null +++ b/doc/CMakeLists.txt @@ -0,0 +1,52 @@ +# +# 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) +# +# Standalone project whose only purpose is to give MrDocs a compilation +# database for mrdocs.cpp, the umbrella translation unit that includes the +# public headers. Nothing is built: MrDocs only configures this project and +# reads compile_commands.json. +# +# The library's own CMakeLists.txt cannot serve this purpose because it is a +# modular-Boost library that has to be added from the superproject. So this +# project adds the superproject instead, restricted to Boost.Test and its +# dependencies, and picks up the include paths from the Boost::unit_test_framework +# target's interface. + +cmake_minimum_required(VERSION 3.8...3.22) + +project(boost_test_mrdocs LANGUAGES CXX) + +# MrDocs forces CMAKE_EXPORT_COMPILE_COMMANDS=ON, which would dump every target +# of the superproject into the compilation database. Turn it off globally and +# switch it on for our target alone. +set(CMAKE_EXPORT_COMPILE_COMMANDS OFF) + +if(NOT DEFINED ENV{BOOST_SRC_DIR}) + message(FATAL_ERROR + "BOOST_SRC_DIR is not set. It normally comes from the cpp-reference " + "extension's `dependencies` block in the Antora playbook; build_antora.sh " + "also derives it from a surrounding Boost superproject checkout.") +endif() + +# Configure only what Boost.Test needs; the superproject resolves the +# dependencies listed in ../CMakeLists.txt for us. +set(BOOST_INCLUDE_LIBRARIES test) +add_subdirectory($ENV{BOOST_SRC_DIR} deps/boost EXCLUDE_FROM_ALL) + +# An object library, not an executable: unit_test.hpp brings in a main() +# that wants init_unit_test_suite(), and there is nothing here to link. +add_library(mrdocs OBJECT mrdocs.cpp) + +# This worktree's headers must win over whatever the Boost checkout carries, +# which matters when BOOST_SRC_DIR is a clone rather than the superproject this +# library sits in. +get_filename_component(BOOST_TEST_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../include" ABSOLUTE) +target_include_directories(mrdocs BEFORE PRIVATE ${BOOST_TEST_INCLUDE_DIR}) +target_link_libraries(mrdocs PRIVATE Boost::unit_test_framework) +set_target_properties(mrdocs PROPERTIES + CXX_STANDARD 17 + CXX_STANDARD_REQUIRED ON + EXPORT_COMPILE_COMMANDS ON) diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 index 43690e8b5d..d26de8c60f 100644 --- a/doc/Jamfile.v2 +++ b/doc/Jamfile.v2 @@ -5,152 +5,64 @@ # file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) # -using quickbook ; -using doxygen ; -using boostbook ; - -######################################################################## -# Standalone HTML documentation - -import doxygen ; - -path-constant TEST_ROOT : .. ; - -doxygen doxygen_reference_generated_doc - : - $(TEST_ROOT)/include/boost/test/debug_config.hpp - $(TEST_ROOT)/include/boost/test/detail/global_typedef.hpp - $(TEST_ROOT)/include/boost/test/debug.hpp - $(TEST_ROOT)/include/boost/test/execution_monitor.hpp - $(TEST_ROOT)/include/boost/test/framework.hpp - $(TEST_ROOT)/include/boost/test/tools/assertion_result.hpp - $(TEST_ROOT)/include/boost/test/unit_test.hpp - $(TEST_ROOT)/include/boost/test/tree/observer.hpp - - # logs and formatters - $(TEST_ROOT)/include/boost/test/unit_test_log.hpp - $(TEST_ROOT)/include/boost/test/output/xml_log_formatter.hpp - $(TEST_ROOT)/include/boost/test/output/plain_report_formatter.hpp - $(TEST_ROOT)/include/boost/test/output/compiler_log_formatter.hpp - - # reports - $(TEST_ROOT)/include/boost/test/output/xml_report_formatter.hpp - $(TEST_ROOT)/include/boost/test/unit_test_log_formatter.hpp - $(TEST_ROOT)/include/boost/test/results_reporter.hpp - $(TEST_ROOT)/include/boost/test/results_collector.hpp - - # progress monitor - $(TEST_ROOT)/include/boost/test/progress_monitor.hpp - - # test cases and suites - $(TEST_ROOT)/include/boost/test/tree/test_unit.hpp - $(TEST_ROOT)/include/boost/test/parameterized_test.hpp - - # execution monitor source files - $(TEST_ROOT)/include/boost/test/execution_monitor.hpp - - # output test stream - $(TEST_ROOT)/include/boost/test/tools/output_test_stream.hpp - - # datasets - $(TEST_ROOT)/include/boost/test/data/monomorphic/fwd.hpp - $(TEST_ROOT)/include/boost/test/data/test_case.hpp - $(TEST_ROOT)/include/boost/test/data/for_each_sample.hpp - $(TEST_ROOT)/include/boost/test/data/size.hpp - $(TEST_ROOT)/include/boost/test/data/monomorphic/delayed.hpp - $(TEST_ROOT)/include/boost/test/data/monomorphic/initializer_list.hpp - $(TEST_ROOT)/include/boost/test/data/monomorphic/array.hpp - $(TEST_ROOT)/include/boost/test/data/monomorphic/collection.hpp - $(TEST_ROOT)/include/boost/test/data/monomorphic/generate.hpp - - - $(TEST_ROOT)/include/boost/test/data/monomorphic/grid.hpp - $(TEST_ROOT)/include/boost/test/data/monomorphic/join.hpp - $(TEST_ROOT)/include/boost/test/data/monomorphic/singleton.hpp - $(TEST_ROOT)/include/boost/test/data/monomorphic/zip.hpp - - # datasets generators - $(TEST_ROOT)/include/boost/test/data/config.hpp - $(TEST_ROOT)/include/boost/test/data/monomorphic/generators.hpp - $(TEST_ROOT)/include/boost/test/data/monomorphic/generators/keywords.hpp - $(TEST_ROOT)/include/boost/test/data/monomorphic/generators/random.hpp - $(TEST_ROOT)/include/boost/test/data/monomorphic/generators/xrange.hpp - - # utils - $(TEST_ROOT)/include/boost/test/utils/algorithm.hpp - $(TEST_ROOT)/include/boost/test/utils/named_params.hpp - $(TEST_ROOT)/include/boost/test/tools/floating_point_comparison.hpp - $(TEST_ROOT)/include/boost/test/utils/is_forward_iterable.hpp - - # BOOST_TEST related functions - $(TEST_ROOT)/include/boost/test/tools/detail/bitwise_manip.hpp - $(TEST_ROOT)/include/boost/test/tools/detail/lexicographic_manip.hpp - $(TEST_ROOT)/include/boost/test/tools/detail/per_element_manip.hpp - $(TEST_ROOT)/include/boost/test/tools/detail/tolerance_manip.hpp - - # others - $(TEST_ROOT)/include/boost/test/unit_test_parameters.hpp - : - EXTRACT_ALL=YES - "PREDEFINED=\"BOOST_TEST_DECL=\" \\ - \"BOOST_TEST_DOXYGEN_DOC__=1\" - " - HIDE_UNDOC_MEMBERS=NO - AUTOLINK_SUPPORT=YES - HIDE_UNDOC_CLASSES=NO - INLINE_INHERITED_MEMB=YES - EXTRACT_PRIVATE=NO - ENABLE_PREPROCESSING=YES - MACRO_EXPANSION=YES - EXPAND_ONLY_PREDEF=YES - SEARCH_INCLUDES=YES - INCLUDE_PATH=$(TEST_ROOT)/include - EXAMPLE_PATH=$(TEST_ROOT)/doc/examples - BRIEF_MEMBER_DESC=YES - REPEAT_BRIEF=YES - ALWAYS_DETAILED_SEC=YES - MULTILINE_CPP_IS_BRIEF=YES - CASE_SENSE_NAMES=YES - INTERNAL_DOCS=NO - SUBGROUPING=YES - SHORT_NAMES=YES - ; - - - -######################################################################## -# HTML documentation for $(BOOST_ROOT)/doc/html - -xml test_doc - : - test.qbk - ; - -explicit test_doc ; - -path-constant images_location : html ; - -boostbook standalone - : - test_doc - : - boost.root=../../../.. - html.stylesheet=boostbook.css - chapter.autolabel=0 - toc.max.depth=3 - toc.section.depth=10 - chunk.section.depth=4 - chunk.first.sections=1 - generate.section.toc.level=3 - pdf:img.src.path=$(images_location)/ - pdf:boost.url.prefix=http://www.boost.org/doc/libs/release/libs/test/doc/html - doxygen_reference_generated_doc +# The documentation is built by Antora, driven by build_antora.sh. The API +# reference inside it is generated by MrDocs. Neither Quickbook, Doxygen nor +# BoostBook is involved any more. + +import generate ; +import path ; +import property-set ; +import virtual-target ; + +path-constant HERE : . ; + +make html/index.html : build_antora.sh : @run-script ; +generate files-to-install : html/index.html : @delayed-glob ; +install install + : files-to-install + : html + html/test ; - -explicit test ; +explicit html/index.html files-to-install ; + +# this runs the antora script +actions run-script +{ + bash $(>) +} + +# this globs after its sources are created +rule delayed-glob ( project name : property-set : sources * ) +{ + for local src in $(sources) + { + # the next line causes the source to be generated immediately + # and not later (which it normally would) + UPDATE_NOW [ $(src).actualize ] ; + } + + # we need to construct the path to the globbed directory; + # this path would be /html + local root = [ path.root html [ $(project).location ] ] ; + local files ; + + # actual globbing happens here + for local file in [ path.glob-tree $(root) : * ] + { + # we have to skip directories, because our match expression accepts anything + if [ CHECK_IF_FILE $(file) ] + { + # we construct a list of targets to copy + files += [ virtual-target.from-file $(file:D=) : $(file:D) : $(project) ] ; + } + } + + # we prepend empty usage requirements to the result + return [ property-set.empty ] $(files) ; +} ############################################################################### alias boostdoc ; explicit boostdoc ; -alias boostrelease : standalone ; +alias boostrelease : install ; explicit boostrelease ; diff --git a/doc/README.md b/doc/README.md index 4d8ad89c88..5b6e678ac3 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,64 +1,100 @@ This folder contains the documentation for the Boost.Test library. Any contribution or submission to the library should be accompanied by the corresponding documentation. -The format of the documentation uses [Quickbook](http://www.boost.org/tools/quickbook/index.html). +The narrative chapters are written in [AsciiDoc](https://docs.asciidoctor.org/asciidoc/latest/) +and assembled by [Antora](https://antora.org). The API reference is generated from the +headers by [MrDocs](https://www.mrdocs.com). -How to build the documentation -============================== - -In order to generate the documentation, the following is needed: - -* Docbook -* Doxygen -* xsltproc - -Doxygen -------- -Part of the documentation needs [Doxygen](http://www.doxygen.org). `doxygen` should be accessible from the `PATH`. +Layout +====== -Docbook -------- -Quickbook needs Docbook (XSL and XML) to be installed. Download and untar the docbook archives: - -* Docbook XSL that can be found here: http://sourceforge.net/projects/docbook/files/docbook-xsl/ -* Docbook DTD that can be found here: http://www.docbook.org/schemas/ - -The directories `$docbook_xsl_directory` and `$docbook_dtd_directory`, respectively, will refer to the location -of the deflated archive. +``` +doc/ +├── antora.yml component descriptor; also defines the +│ attributes the pages use for reference links +├── local-playbook.yml site playbook, used for local builds and CI +├── build_antora.sh the entry point: npm ci, then Antora +├── mrdocs.yml what MrDocs extracts, and how +├── mrdocs.cpp umbrella translation unit: the public headers +├── CMakeLists.txt gives MrDocs a compilation database for it +├── mrdocs-addons/ template overrides, each explaining itself +└── modules/ROOT/ + ├── nav.adoc the navigation tree + ├── pages/ the chapters + ├── partials/bt_example.adoc renders an example's code beside its output + ├── images/, attachments/ + └── examples/ example programs, compiled and run by the + └── snippets/ test suite; included into the pages by tag +``` -Download xsltproc ------------------ -This program is needed by Docbook, in order to be able to transform XMLs into HTMLs. -`xsltproc` should be accessible from the `PATH`. +How to build the documentation +============================== -**note**: `xsltproc` seems to be distributed with macOS. +You need [Node.js](https://nodejs.org) 18 or later, CMake and a C++ compiler. +MrDocs itself is downloaded automatically. -Construct b2 ------------- +``` +> cd $boost_root/libs/test/doc +> npm ci +> ./build_antora.sh +``` -Simply by typing in a console at the root of the Boost repository: +The site lands in `doc/html`; open `doc/html/test/index.html`. To serve it +rather than opening the files directly: ``` -> ./bootstrap.[sh|bat] +> python3 -m http.server -d html 8080 ``` -Build the documentation ------------------------ +The build needs the rest of Boost, because MrDocs compiles `mrdocs.cpp` against +it. `build_antora.sh` finds a surrounding superproject checkout by itself; +otherwise set `BOOST_SRC_DIR`, or let the playbook clone Boost for you. -Running the following commands will construct the documentation with `b2` and -all the needed dependencies: +Antora exits successfully even when a cross-reference or an include fails to +resolve. `build_antora.sh` passes `--log-failure-level=warn` when `CI` is set, +which makes those fatal. To get the same locally: ``` -> cd $boost_root/libs/test/doc -> ../../../b2 -sDOCBOOK_XSL_DIR=$docbook_xsl_directory -sDOCBOOK_DTD_DIR=$docbook_dtd_directory +> CI=1 ./build_antora.sh ``` -It is possible to run directly +Working on the prose alone +-------------------------- + +Regenerating the reference dominates the build time. Comment out the +`cpp-reference` stanza in `antora.yml` and run Antora directly: + ``` -> ../../../b2 +> npx antora --clean local-playbook.yml ``` -but this results in a download from the Internet of the Docbook XLS and DTD, which is much slower. +Nothing else changes; only the reference module disappears. + +If the cached MrDocs nightly goes stale, `./refresh_mrdocs_cache.sh` clears it +so that the next build downloads a current one. + +Writing documentation +===================== + +- Cross-references into the reference chapter go through the attributes defined + in `antora.yml`, for example ``xref:{boost_test}[`BOOST_TEST`]``. The + attribute holds only the target, so a reference page can be renamed in one + place; the label stays at the call site, because Asciidoctor does not apply + formatting to text that arrives from an attribute. +- References to a C++ entity use the `cpp:` macro, which resolves against what + MrDocs generated: `cpp:boost::test_tools::assertion_result[assertion_result]`. +- Examples live in `modules/ROOT/examples` as complete programs named + `.run.cpp` or `.run-fail.cpp`, with their expected output in + `.output`. The test suite compiles and runs every one of them, so an + example that stops working breaks the build rather than just the docs. Show + one with: + + ``` + :bt-name: example22 + :bt-rule: run-fail + :bt-descr: BOOST_TEST_CHECKPOINT usage + include::partial$bt_example.adoc[] + ``` Recommendations =============== @@ -66,6 +102,6 @@ Recommendations - Documentation is part of the "definition of done". A feature does not exist until it is implemented, tested, documented and reviewed. - It is highly recommended that each of your pull request comes with an updated documentation. Not doing so put this work on the shoulders of the maintainers and as a result, it would be likely that the pull request is not addressed in a timely manner. -- Please also update the changelog in the file [`change_log.qbk`](closing_chapters/change_log.qbk) +- Please also update the changelog in [`modules/ROOT/pages/change_log.adoc`](modules/ROOT/pages/change_log.adoc) indicating your contribution - Every file should come with a copyright notice at their very beginning diff --git a/doc/adv_scenarios.qbk b/doc/adv_scenarios.qbk deleted file mode 100644 index f8c388200f..0000000000 --- a/doc/adv_scenarios.qbk +++ /dev/null @@ -1,52 +0,0 @@ -[/ - / 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:adv_scenarios Advanced Usage Scenarios] - -If you are reading this chapter, this means that the wide range of tools and interfaces covered -in the previous sections are not sufficient for the testing scenario -you have in mind. You are here to bend the __UTF__ to your will and ... we are not going to -stop you. Instead we'll try to guide you so that some dark corners do not look scary. - -In most cases the __UTF__ is going to be supplied for you either as part of your system libraries -or set of libraries used by your companies. Yet if you are facing the necessity to build your -own static or dynamic library of the __UTF__ or need to customize the build for any reason, section -[link boost_test.adv_scenarios.build_utf Building the __UTF__] covers all the necessary steps. - -To streamline the experience of setting up your test module, the __UTF__ provides some default -initialization logic for them. Usually the default test module initialization will work just fine, -but if you want to implement some custom initialization or change how default initialization -behaves you need to first look in [*Test module initialization] section. Here you'll learn -about various options the __UTF__ provides for you to customize this behavior. - -The part of the framework which loads, initializes and executed your test module is called the -[*Test Runner]. Each usage variant comes with default test runner. If, instead, you prefer to -implement your own entry point into the test module (for example if you need to implement the -`main` function yourself and not use the one provided by the __UTF__, you need to learn about -__UTF__ interfaces involved in test runners operations. These are covered in the [*Test runners] -section. Let me reiterate that you only need to this section if regular regular options for -customization of initialization logic like -[link boost_test.tests_organization.fixtures fixtures] or [link boost_test.tests_organization.decorators decorators] -are not sufficient for your purposes. - -[/ build and link with boost.test] -[include adv_scenarios/building_utf.qbk] -[include adv_scenarios/entry_point_overview.qbk] -[include adv_scenarios/test_module_init_overview.qbk] -[include adv_scenarios/test_module_runner_overview.qbk] -[include adv_scenarios/single_header_customizations.qbk] -[include adv_scenarios/static_lib_customizations.qbk] -[include adv_scenarios/shared_lib_customizations.qbk] -[include adv_scenarios/external_test_runner.qbk] -[include adv_scenarios/obsolete_init_func.qbk] - -[/=============================================================================] - -[endsect] [/Advanced usage scenarios] - -[/ EOF] diff --git a/doc/adv_scenarios/building_utf.qbk b/doc/adv_scenarios/building_utf.qbk deleted file mode 100644 index cc359782c3..0000000000 --- a/doc/adv_scenarios/building_utf.qbk +++ /dev/null @@ -1,65 +0,0 @@ -[/ - / 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:build_utf Building the __UTF__] -In case you would like to use the [link boost_test.usage_variants.shared_lib shared library variant] or the [link boost_test.usage_variants.static_lib static library variant] of the __UTF__, the library needs to be built. -Building the __UTF__ is in fact quite easy. - -In the sequel, we define - -* $`boost_path` refers to the location where the boost archive was deflated -* $`boost_installation_prefix` refers to the location where you want to install the __UTF__ - -[/ not true - [note By default, the static and dynamic variant will be built for your operating system] -] - -More documentation about *Boost's build system* can be found [@http://www.boost.org/more/getting_started/index.html here]. - -[h3 Windows] - -You need to have a compilation toolchain. /Visual Studio Express/ is such one, freely available from the -Microsoft website. Once installed, open a /Visual Studio Command Line tools/ prompt and build the Boost build program `b2` -(see the link above). You will then be able to compile the __UTF__ with different variants. - -[h4 Static variant] -For building 32bits libraries, open a console window and enter the following commands: -``` -> cd ``$``boost_path -> bootstrap.bat -> b2 address-model=32 architecture=x86 --with-test link=static \ -> --prefix=``$``boost_installation_prefix install -``` - -For building 64bits libraries, the commands become: -``` -> cd ``$``boost_path -> bootstrap.bat -> b2 address-model=64 architecture=x86 --with-test link=static \ -> --prefix=``$``boost_installation_prefix install -``` - -[h4 Shared library variant] -In order to build the shared library variant, the directive `link=static` should be replaced by `link=shared` on the above command lines. -For instance, for 64bits builds, the commands become: - -``` -> cd ``$``boost_path -> bootstrap.bat -> b2 address-model=64 architecture=x86 --with-test link=shared --prefix=``$``boost_installation_prefix install -``` - -[h3 Linux/OSX] -For Unix/Linux/OSX operating system, the build of the __UTF__ is very similar to the one on Windows: -``` -> cd ``$``boost_path -> ./bootstrap.sh -> ./b2 --with-test --prefix=``$``boost_installation_prefix install -``` - -[endsect] [/build_utf] diff --git a/doc/adv_scenarios/entry_point_overview.qbk b/doc/adv_scenarios/entry_point_overview.qbk deleted file mode 100644 index a8cb6814a3..0000000000 --- a/doc/adv_scenarios/entry_point_overview.qbk +++ /dev/null @@ -1,39 +0,0 @@ -[/ - / 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_tree.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 header-only 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] diff --git a/doc/adv_scenarios/external_test_runner.qbk b/doc/adv_scenarios/external_test_runner.qbk deleted file mode 100644 index a3ba79e622..0000000000 --- a/doc/adv_scenarios/external_test_runner.qbk +++ /dev/null @@ -1,23 +0,0 @@ -[/ - / 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:external_test_runner The external test runner usage variant] - -This usage variant does not provide any [link boost_test.adv_scenarios.test_module_runner_overview test runner]. -You employ it when you only want to define a [link ref_test_tree test tree] and possibly an -[link boost_test.adv_scenarios.test_module_init_overview initialization function], -and expect another (external) program to evaluate these tests. This external program will come with its own test runner. - -If you plan to use an external test runner with your test module, you need to build it as a dynamic library. -You need to define macro flag __BOOST_TEST_DYN_LINK__ either in a makefile or before the header -`boost/test/unit_test.hpp` inclusion. An external test runner utility is required to link with dynamic library. - -The __UTF__ comes with an example external test runner `console_test_runner`: -Given a name of the test module (implemented as a shared library), and a name of the initialization function defined therein, -the program can run all the tests from the module's test tree. - -[endsect] [/section:external_test_runner] diff --git a/doc/adv_scenarios/link_reference.qbk b/doc/adv_scenarios/link_reference.qbk deleted file mode 100644 index 0d9a8449d3..0000000000 --- a/doc/adv_scenarios/link_reference.qbk +++ /dev/null @@ -1,134 +0,0 @@ -[/ - / 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:link_references Build scenarios and behaviors] - -[/-----------------------------------------------------------------] -[section:link_boost_test_main_macro `BOOST_TEST_MAIN`] - -When defined, this macro creates a stub for the test module initialization (the main entry part). This -macro also expands properly into a `main` function in case the shared library variant of the __UTF__ is used. - - -[caution This macro should - -# be defined before any inclusion directive to __UTF__ headers -# be defined exactly for one compilation unit of your test module - -] - -[tip The macro __BOOST_TEST_MODULE__ should be preferred] - -[endsect] - -[/-----------------------------------------------------------------] -[section:link_boost_test_module_macro `BOOST_TEST_MODULE`] -Serves the same purpose as the macro __BOOST_TEST_MAIN__ but, in addition, defines the name of the master test suite. - -[caution As __BOOST_TEST_MAIN__, this macro should - -# be defined before any inclusion directive to __UTF__ headers -# be defined exactly for one compilation unit of your test module - -] - -An example may be found [link ref_BOOST_TEST_MODULE here]. - -[endsect] - -[/-----------------------------------------------------------------] -[section:link_boost_test_alternative_init_macro `BOOST_TEST_ALTERNATIVE_INIT_API`] - -[warning This macro should be defined before any include directive to the __UTF__ headers and is -mutually exclusive with the __BOOST_TEST_MODULE__ macro.] - -In case of custom initialization of the test module entry point, this macro indicates the __UTF__ to -use the new API. The differences between the new and old APIs are described in [link -boost_test.adv_scenarios.obsolete_init_func this section]. - -The way to customize the entry point of the test-module depends on the variant of the __UTF__ in use. -Several sections in the documentation are devoted to this: - -* [link boost_test.adv_scenarios.single_header_customizations.entry_point this section] for single header variant, -* [link boost_test.adv_scenarios.static_lib_customizations.init_func this section] for static link variant, -* [link boost_test.adv_scenarios.shared_lib_customizations.init_func this section] for shared link variant - -[endsect] - -[/-----------------------------------------------------------------] -[section:link_boost_test_no_lib `BOOST_TEST_NO_LIB`] -Define this flag to prevent auto-linking. -[note The same flag is used for the __UTF__ and the __PEM__ components.] -[endsect] - -[/-----------------------------------------------------------------] -[section:link_boost_test_dyn_link `BOOST_TEST_DYN_LINK`] -Define this flag to link against the __UTF__ shared library. -[note The same flag is used for the __UTF__ and the __PEM__ components.] -[endsect] - -[/-----------------------------------------------------------------] -[section:link_boost_test_no_main `BOOST_TEST_NO_MAIN`] -Prevents the auto generation of the test module initialization functions. This macro is particularly relevant for -manually registered tests in conjunction with dynamic variant of the __UTF__. When defined, a `main` function -registering all the tests should be implemented. - -An example of a module initialization would be -`` -#define __BOOST_TEST_NO_MAIN__ -#include - -// a function in another compilation unit registering tests under the master test suite. -void register_some_tests_manually(test_suite* test); - -bool registering_all_tests() -{ - test_suite* test_master_suite = &boost::unit_test::framework::master_test_suite(); - register_some_tests_manually(test_master_suite); - - // register any other tests function or test suite to the master test suite - // ... - return true; -} - -int main(int argc, char* argv[]) -{ - return ::boost::unit_test::unit_test_main(®istering_all_tests, argc, argv); -} -`` -[endsect] - -[/-----------------------------------------------------------------] -[section:link_boost_test_global_configuration `BOOST_TEST_GLOBAL_CONFIGURATION`] -Declares a class that will be constructed during the initialization of the test framework, and destructed afterwards. -The framework will not call any other member function than the constructor and destructor. -In particular the constructor and destructor will be called prior and after to the [link boost_test.tests_organization.fixtures.global global fixtures] -setup and teardown. - -This facility is provided to perform additional configuration, in particular programmatic configuration -of the loggers and reporters. See [link boost_test.test_output.logging_api this section] for more details. - -[warning No logging or any other call to the framework assertion is allowed in the constructor and destructor, as its purpose is - to set-up the loggers/reporters, and the assertions are calling the logging/reporting facility. - Any such assertion during the execution of the will result in the abortion of the test module .] - -[endsect] - -[/-----------------------------------------------------------------] -[section:config_disable_alt_stack `BOOST_TEST_DISABLE_ALT_STACK`] -Disables the support of the alternative stack. - -Define this macro before the inclusion of any __UTF__ header to disable the support -of the [@http://www.gnu.org/software/libc/manual/html_node/Signal-Stack.html alternative stack], -in case your compiler does not support it and the __UTF__ cannot automatically guess the lack of support. - -See [link boost_test.utf_reference.rt_param_reference.use_alt_stack `use_alt_stack`] -and [macroref BOOST_TEST_DISABLE_ALT_STACK `BOOST_TEST_DISABLE_ALT_STACK`] for more details. -[endsect] - -[endsect] diff --git a/doc/adv_scenarios/obsolete_init_func.qbk b/doc/adv_scenarios/obsolete_init_func.qbk deleted file mode 100644 index d8bed08cf1..0000000000 --- a/doc/adv_scenarios/obsolete_init_func.qbk +++ /dev/null @@ -1,46 +0,0 @@ -[/ - / 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:obsolete_init_func The obsolete initialization function] - -For backwards compatibility, the __UTF__ also allows the customization of an initialization function of a different type. -This is called the ['obsolete initialization function]. Its signature is: - -``` -boost::unit_test::test_suite* init_unit_test_suite(int argc, char* argv[]); -``` - -The original design of the __UTF__ required of the programmer to implement it. It was intended to initialize and return -the __master_test_suite__. No [link ref_BOOST_AUTO_TEST_CASE automatic test case registration] was available at that -time. The null-pointer value was considered an initialization error. - -In the header-only usage variant, you fall back to the obsolete initialization function signature by omitting the -definition of macro __BOOST_TEST_ALTERNATIVE_INIT_API__ in test module code. - -[bt_example custom_obsolete_init..using obsolete initialization function..run-fail] - -In the static-library usage variant, you need to omit the definition of macro __BOOST_TEST_ALTERNATIVE_INIT_API__ in test -module and compile the __UTF__ static library without the compilation flag __BOOST_TEST_ALTERNATIVE_INIT_API__ (this is -the default). - -In the shared-library usage variant, it is not possible to use the obsolete initialization function. - -Even if you decide to us the obsolete initialization function, it is recommended that: - -# You always return a null-pointer value and install the master test suite via - [memberref boost::unit_test::test_suite::add `test_suite::add`] as illustrated - [link ref_BOOST_TEST_CASE here]. The current framework does no longer treat the - null-pointer value as failure. -# You signal the failure by throwing [classref boost::unit_test::framework::setup_error] exception. -# You access the command-line arguments through the interface of the __master_test_suite__, - and ignore the function's arguments `argc` and `argv`. - -[caution The obsolete initialization function is deprecated as its name indicates. It is recommended to migrate - to the new API, and rely on the automated test unit registration and [link boost_test.tests_organization.fixtures -fixtures] (including [link boost_test.tests_organization.fixtures.global global fixtures]) for other set-up. ] - -[endsect] [/section:obsolete_init_func] diff --git a/doc/adv_scenarios/shared_lib_customizations.qbk b/doc/adv_scenarios/shared_lib_customizations.qbk deleted file mode 100644 index f4ddae14a4..0000000000 --- a/doc/adv_scenarios/shared_lib_customizations.qbk +++ /dev/null @@ -1,104 +0,0 @@ -[/ - / 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:shared_lib_customizations Shared-library variant customizations] - -[caution Macro __BOOST_TEST_DYN_LINK__ (which instructs the compiler/linker to dynamically link against a shared -library variant) may be implicitly defined when macro `BOOST_ALL_DYN_LINK` is defined.] - -[caution In order to be able to run a test built with the dynamic variant, the operating system should be able - to find the dynamic library of the __UTF__. This means, for example on Linux and MacOSX respectively, setting the environment - variable `LD_LIBRARY_PATH` or `DYLD_LIBRARY_PATH` properly prior to the execution of the test module.] - -[section:entry_point Customizing the module's entry point] - -In this variant, in one of the source files, you now 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. -You need to define __BOOST_TEST_NO_MAIN__ (its value is irrelevant) in the main file: - -[table -[[In *exactly one* file][In all other files]] -[[```#define BOOST_TEST_MODULE test module name -#define BOOST_TEST_DYN_LINK -#define BOOST_TEST_NO_MAIN -#include - -// entry point: -int main(int argc, char* argv[], char* envp[]) -{ - return boost::unit_test::unit_test_main( &init_unit_test, argc, argv ); -} -```] -[```#define BOOST_TEST_DYN_LINK -#include - -// -// test cases -// - -// -// test cases -// -```]] -] - -[endsect] [/section:entry_point] - -[section:init_func Customizing the module's initialization function] - -In the shared-library variant, it is impossible to customize the initialization function without -[link boost_test.adv_scenarios.shared_lib_customizations.entry_point customizing the entry point]. We have -to customize both. In one of the source files, you now have to define your custom entry point and -[link boost_test.adv_scenarios.test_module_init_overview initialization function] `init_unit_test`; next invoke -the default [link boost_test.adv_scenarios.test_module_runner_overview test runner] `unit_test_main` manually -with `init_unit_test` as argument. You ['do not] define __BOOST_TEST_MODULE__ in the main file: - -[table -[[In *exactly one* file][In all other files]] -[[```#define BOOST_TEST_DYN_LINK -#include - -// initialization function: -bool init_unit_test() -{ - return true; -} - -// entry point: -int main(int argc, char* argv[]) -{ - return boost::unit_test::unit_test_main( &init_unit_test, argc, argv ); -} -```] -[```#define BOOST_TEST_DYN_LINK -#include - -// -// test cases -// - -// -// test cases -// - -// -// test cases -// -```]] -] - -For reporting errors that may occur during the initialization, - -* either you return `false` (valid only for the new API only, see __BOOST_TEST_ALTERNATIVE_INIT_API__) -* or you raise an exception such as `std::runtime_error` or [classref boost::unit_test::framework::setup_error] - -An error reported in this function aborts the execution of the test module. - -[endsect] [/section:init_func] - -[endsect] [/section:shared_lib_customizations] diff --git a/doc/adv_scenarios/single_header_customizations.qbk b/doc/adv_scenarios/single_header_customizations.qbk deleted file mode 100644 index f6f5c79cd8..0000000000 --- a/doc/adv_scenarios/single_header_customizations.qbk +++ /dev/null @@ -1,93 +0,0 @@ -[/ - / 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 Header-only variant customizations] - -[section:multiple_translation_units Header-only with multiple translation units] -It is possible to use the header-only variant of the __UTF__ even if the test module has multiple translation -units: - -* one translation unit should define __BOOST_TEST_MODULE__ and include `` -* all the other translation units should include `` - -An example might be the following: - -* Translation unit 1, defines __BOOST_TEST_MODULE__ - ``` - #define BOOST_TEST_MODULE header-only multiunit test - #include - - BOOST_AUTO_TEST_CASE( test1 ) - { - int i = 1; - BOOST_CHECK( i*i == 1 ); - } - ``` - -* Translation unit 2, includes `` instead of ``: - ``` - #include - - BOOST_AUTO_TEST_CASE( test2 ) - { - int i = 1; - BOOST_CHECK( i*i == 1 ); - } - ``` - -[endsect] [/section:multiple_translation_units] - -[section:entry_point Customizing the module's entry point] - -In this usage variant and in the translation unit containing the definition of __BOOST_TEST_MODULE__, -you need to define the 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 name specified by __BOOST_TEST_MODULE__ -is assigned to the [link boost_test.tests_organization.test_tree.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_tree.master_test_suite master test suite]. Therefore the default name ("Master Test -Suite") is used.] - -For reporting errors that may occur during the initialization, - -* either you return `false` (valid only for the new API only, see __BOOST_TEST_ALTERNATIVE_INIT_API__) -* or you raise an exception such as `std::runtime_error` or [classref boost::unit_test::framework::setup_error] - -An error reported in this function aborts the execution of the test module. - -[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] diff --git a/doc/adv_scenarios/static_lib_customizations.qbk b/doc/adv_scenarios/static_lib_customizations.qbk deleted file mode 100644 index 46c7e89f4b..0000000000 --- a/doc/adv_scenarios/static_lib_customizations.qbk +++ /dev/null @@ -1,123 +0,0 @@ -[/ - / 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:static_lib_customizations Static-library variant customizations] - -[section:entry_point Customizing the module's entry point] - -In the static library variant, customizing the main entry point is quite troublesome, because the definition -of function `main` is already compiled into the static library. This requires you to rebuild the __UTF__ -static library with the defined symbol __BOOST_TEST_NO_MAIN__. In the Boost root directory you need to -invoke command - -``` -> b2 --with-test link=static define=__BOOST_TEST_NO_MAIN__ define=__BOOST_TEST_ALTERNATIVE_INIT_API__ install -``` - -[warning This removal of entry point definition from the static library will affect everybody else who is -linking against the library. It may be less intrusive to switch to the -[link boost_test.adv_scenarios.shared_lib_customizations shared library usage variant] instead.] - -In one of the source files, you now 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 the first argument. There is no need to define __BOOST_TEST_NO_MAIN__ in your source code, but you need -to define __BOOST_TEST_ALTERNATIVE_INIT_API__ in the main file: - -[table -[[In *exactly one* file][In all other files]] -[[```#define BOOST_TEST_MODULE test module name -#define BOOST_TEST_ALTERNATIVE_INIT_API -#include - -// entry point: -int main(int argc, char* argv[], char* envp[]) -{ - return utf::unit_test_main(init_unit_test, argc, argv); -} -```] -[```#include - -// -// test cases -// - -// -// test cases -// -```]] -] - -[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 the static library variant, customizing the main entry point is quite troublesome, because the default test -runner compiled into the static library uses the obsolete initialization function signature. This requires you -to rebuild the __UTF__ static library with the defined symbol __BOOST_TEST_ALTERNATIVE_INIT_API__. In the Boost -root directory you need to invoke command - -``` -> b2 --with-test link=static define=__BOOST_TEST_ALTERNATIVE_INIT_API__ install -``` - -[warning This alteration of the static library will affect everybody else who is linking against the -library. Consider using the [link boost_test.adv_scenarios.obsolete_init_func obsolete test initialization function], -which requires no rebuilding. Alternatively, it may be less intrusive to switch to the -[link boost_test.adv_scenarios.shared_lib_customizations shared library usage variant] instead.] - -In one of the source files, you now have to define your custom initialization function with signature: - -``` -bool init_unit_test(); -``` - -The default [link boost_test.adv_scenarios.test_module_runner_overview test runner] will use it to initialize -the test module. In your source code, you no longer define macro __BOOST_TEST_MODULE__; instead, you need to -define __BOOST_TEST_ALTERNATIVE_INIT_API__ in the main file: - -[table -[[In *exactly one* file][In all other files]] -[[```#define BOOST_TEST_ALTERNATIVE_INIT_API -#include - -// init func: -bool init_unit_test() -{ - return true; -} -```] -[```#include - -// -// test cases -// - -// test cases -// -```]] -] - -For reporting errors that may occur during the initialization, - -* either you return `false` (valid only for the new API only, see __BOOST_TEST_ALTERNATIVE_INIT_API__) -* or you raise an exception such as `std::runtime_error` or [classref boost::unit_test::framework::setup_error] - -An error reported in this function aborts the execution of the test module. - - -[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:static_lib_customizations] diff --git a/doc/adv_scenarios/test_module_init_overview.qbk b/doc/adv_scenarios/test_module_init_overview.qbk deleted file mode 100644 index a9f04a78c7..0000000000 --- a/doc/adv_scenarios/test_module_init_overview.qbk +++ /dev/null @@ -1,51 +0,0 @@ -[/ - / 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:test_module_init_overview Test module's initialization] - -In order for a unit test module to successfully link and execute, it has to have access to the ['test module's initialization -function]. the module's initialization function is called only once during the execution of the program, just before the -[link boost_test.adv_scenarios.test_module_runner_overview ['test module runner]] is run. By default, the __UTF__ provides -a default definition of initialization function. The only thing you have to do is to instruct the framework in which translation -unit (`cpp` file) it needs to provide the definition. You do it by defining macro __BOOST_TEST_MODULE__ in the designated file. -The default implementation assigns the name to the [link ref_test_module test module] as well as the -[link boost_test.tests_organization.test_tree.master_test_suite master test suite]. The name to be assigned is specified by -the value of the macro __BOOST_TEST_MODULE__. - -[important -For a test module consisting of multiple source files you have to define __BOOST_TEST_MODULE__ in a single test file only. -Otherwise you end up with multiple instances of the initialization function. -] - -There is practically no need to ever alter the default behavior of the test module's initialization function. The __UTF__ provides -superior tools for performing customization tasks: - -* for automatic registration of test cases and test suites in the test tree, see section [link boost_test.tests_organization Tests organization]; -* in order to assign the custom name to the master test suite define macro __BOOST_TEST_MODULE__ to desired value; -* in order to access the command-line parameters (except the ones consumed by the __UTF__), use the interface of the - [link boost_test.tests_organization.test_tree.master_test_suite master test suite]; -* in order to perform a global initialization of the state required by the test cases, [link boost_test.tests_organization.fixtures.global global fixtures] - offer a superior alternative: you can specify global set-up and tear-down in one place, allow access to the global data from every test case, and guarantee - that clean-up and tear-down is repeated each time the tests are re-run during the execution of the program; -* if the need for custom module initialization is only driven by legacy code (written against old versions of the __UTF__), it is recommended - to update your program's code. - -The default initialization function provided by the framework is defined with the following signature in the global namespace: - -``` -bool init_unit_test(); -``` - -Return value `true` indicates a successful initialization. Value `false` indicates initialization failure. - -For overriding the default definition: - -* [link boost_test.adv_scenarios.single_header_customizations.init_func see here], for header-only usage variant, -* [link boost_test.adv_scenarios.static_lib_customizations.init_func see here], for static library usage variant, -* [link boost_test.adv_scenarios.shared_lib_customizations.init_func see here], for shared library usage variant. - -[endsect] [/section:test_module_init_overview] diff --git a/doc/adv_scenarios/test_module_runner_overview.qbk b/doc/adv_scenarios/test_module_runner_overview.qbk deleted file mode 100644 index 37cb99269f..0000000000 --- a/doc/adv_scenarios/test_module_runner_overview.qbk +++ /dev/null @@ -1,50 +0,0 @@ -[/ - / 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:test_module_runner_overview Test module runner] - -A ['test module runner] is an ['orchestrator] or a ['driver] that, given the test tree, ensures the test tree is initialized, -tests are executed and necessary reports generated. It performs the following operations: - -* initialize the test module using the supplied [link boost_test.adv_scenarios.test_module_init_overview ['initialization function]]; -* select output media for the test log and the test results report; -* execute test cases as specified by run-time parameters; -* produce the test results report; -* generate the appropriate return code. - -The __UTF__ comes with the default test runner. There is no need to call it explicitly. The default generated test module's -[link boost_test.adv_scenarios.entry_point_overview entry point] invokes the default test runner. The default test runner is -declared with the following signature: - -``` -namespace boost { namespace unit_test { - - typedef bool (*init_unit_test_func)(); - - int unit_test_main( init_unit_test_func init_func, int argc, char* argv[] ); - -} } -``` - -The test runner may return one of the following values: - -[table -[[Value][Meaning]] -[[`boost::exit_success`][ -* No errors occurred during testing, or -* the success result was forced with command-line argument `--[link boost_test.utf_reference.rt_param_reference.result_code `result_code`]=no`.]] -[[`boost::exit_test_failure`][ -* Non-fatal errors detected and no uncaught exceptions were thrown during testing, or -* the initialization of the __UTF__ failed. ]] -[[`boost::exit_exception_failure`][ -* Fatal errors were detected, or -* uncaught exceptions thrown during testing. ]] -] - -An advanced test runner may provide additional features, including interactive GUI interfaces, test coverage and profiling support. - -[endsect] [/section:test_module_runner_overview] diff --git a/doc/antora.yml b/doc/antora.yml new file mode 100644 index 0000000000..8824473624 --- /dev/null +++ b/doc/antora.yml @@ -0,0 +1,130 @@ +# +# 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) +# +# Official repository: https://github.com/boostorg/test +# + +name: test +title: Boost.Test +version: ~ +start_page: index.adoc + +asciidoc: + attributes: + source-language: cpp@ + table-caption: false + # Base of the links to header sources. build_antora.sh overrides this with + # the exact commit when it can determine one; this is the fallback for + # builds that cannot, such as a local preview. + base-url: https://github.com/boostorg/test/blob/master + # Issue trackers referenced from the change log. + trac-url: https://svn.boost.org/trac/boost/ticket + pr-url: https://github.com/boostorg/test/pull + issue-url: https://github.com/boostorg/test/issues + # Targets for the cross-references into the reference chapter, so that a + # reference page can be renamed in one place instead of at ~2000 call + # sites. Only the target lives here; the label stays at the call site, as + # in xref:{boost_test}[`BOOST_TEST`]. It has to: Asciidoctor substitutes + # quotes before attributes, and a value coming from an API attribute -- + # which is what this file sets -- is inserted without further + # substitution, so formatting inside a value would never be processed. + part_faq: 'section_faq.adoc' + floating_points_testing_tools: 'testing_tools/floating_point.adoc#floating_points_comparison_theory' + master_test_suite: 'tests_organization/master_test_suite.adoc' + runtime_configuration: 'runtime_config/index.adoc' + output_test_stream_tool: 'testing_tools/output_stream_testing.adoc' + auto_linking: 'program_execution_monitor.adoc#ref_pem_auto_link' + boost_test_alternative_init_api: 'utf_reference/link_references.adoc#link_boost_test_alternative_init_macro' + boost_test_main: 'utf_reference/link_references.adoc#link_boost_test_main_macro' + boost_test_dyn_link: 'utf_reference/link_references.adoc#link_boost_test_dyn_link' + boost_test_no_lib: 'utf_reference/link_references.adoc#link_boost_test_no_lib' + boost_test_no_main: 'utf_reference/link_references.adoc#link_boost_test_no_main' + boost_test_module: 'utf_reference/link_references.adoc#link_boost_test_module_macro' + boost_test_global_configuration: 'utf_reference/link_references.adoc#link_boost_test_global_configuration' + boost_test_checkpoint: 'utf_reference/testout_reference.adoc#test_output_macro_checkpoint' + boost_test_passpoint: 'utf_reference/testout_reference.adoc#test_output_macro_passpoint' + boost_test_message: 'utf_reference/testout_reference.adoc#test_output_macro_message' + boost_test_info: 'utf_reference/testout_reference.adoc#test_output_macro_info' + boost_test_context: 'utf_reference/testout_reference.adoc#test_output_macro_context' + boost_test_info_scope: 'utf_reference/testout_reference.adoc#test_output_macro_context_sticky' + boost_test_dont_print_log_value: 'utf_reference/testout_reference.adoc#test_output_macro_disable_type' + boost_test: 'utf_reference/testing_tool_ref.adoc#assertion_boost_test_universal_macro' + boost_test_level: 'utf_reference/testing_tool_ref.adoc#assertion_boost_test_universal_macro' + boost_test_require: 'utf_reference/testing_tool_ref.adoc#assertion_boost_test_universal_macro' + boost_level: 'utf_reference/testing_tool_ref.adoc#assertion_boost_level' + boost_level_message: 'utf_reference/testing_tool_ref.adoc#assertion_boost_level_message' + boost_level_equal: 'utf_reference/testing_tool_ref.adoc#assertion_boost_level_eq' + boost_level_predicate: 'utf_reference/testing_tool_ref.adoc#assertion_boost_level_predicate' + boost_level_equal_collections: 'utf_reference/testing_tool_ref.adoc#assertion_boost_level_eq_collections' + boost_level_ne: 'utf_reference/testing_tool_ref.adoc#assertion_boost_level_ne' + boost_level_ge: 'utf_reference/testing_tool_ref.adoc#assertion_boost_level_ge' + boost_level_gt: 'utf_reference/testing_tool_ref.adoc#assertion_boost_level_gt' + boost_level_le: 'utf_reference/testing_tool_ref.adoc#assertion_boost_level_le' + boost_level_lt: 'utf_reference/testing_tool_ref.adoc#assertion_boost_level_lt' + boost_level_no_throw: 'utf_reference/testing_tool_ref.adoc#assertion_boost_level_no_throw' + boost_level_throw: 'utf_reference/testing_tool_ref.adoc#assertion_boost_level_throw' + boost_level_exception: 'utf_reference/testing_tool_ref.adoc#assertion_boost_level_exception' + boost_level_bitwise_equal: 'utf_reference/testing_tool_ref.adoc#assertion_boost_level_bitwise_eq' + boost_error: 'utf_reference/testing_tool_ref.adoc#assertion_boost_error' + boost_fail: 'utf_reference/testing_tool_ref.adoc#assertion_boost_fail' + boost_is_defined: 'utf_reference/testing_tool_ref.adoc#assertion_boost_is_defined' + boost_auto_test_case_expected_failures: 'utf_reference/testing_tool_ref.adoc#test_org_boost_test_case_expected_failure' + boost_level_small: 'utf_reference/testing_tool_ref.adoc#assertion_boost_level_small' + boost_check_small: 'utf_reference/testing_tool_ref.adoc#assertion_boost_level_small' + boost_level_close: 'utf_reference/testing_tool_ref.adoc#assertion_boost_level_close' + boost_check_close: 'utf_reference/testing_tool_ref.adoc#assertion_boost_level_close' + boost_level_close_fraction: 'utf_reference/testing_tool_ref.adoc#assertion_boost_level_close_fraction' + boost_test_tools_under_debugger: 'utf_reference/testing_tool_ref.adoc#assertion_control_under_debugger' + boost_test_tools_debuggable: 'utf_reference/testing_tool_ref.adoc#assertion_control_under_debuggable' + boost_auto_test_case: 'utf_reference/test_org_reference.adoc#test_org_boost_auto_test_case' + boost_test_case: 'utf_reference/test_org_reference.adoc#test_org_boost_test_case' + boost_test_case_name: 'utf_reference/test_org_reference.adoc#test_org_boost_test_case' + boost_auto_test_case_template: 'utf_reference/test_org_reference.adoc#test_org_boost_test_case_auto_template' + boost_test_case_template: 'utf_reference/test_org_reference.adoc#test_org_boost_test_case_template' + boost_test_case_template_function: 'utf_reference/test_org_reference.adoc#test_org_boost_test_case_template_function' + boost_param_test_case: 'utf_reference/test_org_reference.adoc#test_org_boost_test_case_parameter' + boost_data_test_case: 'utf_reference/test_org_reference.adoc#test_org_boost_test_dataset' + boost_data_test_case_f: 'utf_reference/test_org_reference.adoc#test_org_boost_test_dataset_fixture' + boost_test_dataset_max_arity: 'utf_reference/test_org_reference.adoc#test_org_boost_test_dataset' + boost_auto_test_suite: 'utf_reference/test_org_reference.adoc#test_org_boost_auto_test_suite' + boost_auto_test_suite_end: 'utf_reference/test_org_reference.adoc#test_org_boost_auto_test_suite_end' + boost_test_suite: 'utf_reference/test_org_reference.adoc#test_org_boost_test_suite' + boost_test_decorator: 'utf_reference/test_org_reference.adoc#test_org_boost_test_decorator' + boost_fixture_test_case: 'utf_reference/test_org_reference.adoc#test_org_boost_test_case_fixture' + boost_fixture_test_suite: 'utf_reference/test_org_reference.adoc#test_org_boost_test_suite_fixture' + boost_global_fixture: 'utf_reference/test_org_reference.adoc#test_org_boost_global_fixture' + boost_test_global_fixture: 'utf_reference/test_org_reference.adoc#test_org_boost_test_global_fixture' + boost_test_log_level: 'utf_reference/rt_param_reference.adoc#log_level' + default_run_status: 'runtime_config/test_unit_filtering.adoc#ref_default_run_status' + param_run_test: 'utf_reference/rt_param_reference.adoc#run_test' + decorator_label: 'utf_reference/test_org_reference.adoc#decorator_label' + decorator_enabled: 'utf_reference/test_org_reference.adoc#decorator_enabled' + decorator_disabled: 'utf_reference/test_org_reference.adoc#decorator_enabled' + decorator_enable_if: 'utf_reference/test_org_reference.adoc#decorator_enable_if' + decorator_depends_on: 'utf_reference/test_org_reference.adoc#decorator_depends_on' + decorator_precondition: 'utf_reference/test_org_reference.adoc#decorator_precondition' + decorator_fixture: 'utf_reference/test_org_reference.adoc#decorator_fixture' + decorator_description: 'utf_reference/test_org_reference.adoc#decorator_description' + decorator_expected_failures: 'utf_reference/testing_tool_ref.adoc#decorator_expected_failures' + decorator_timeout: 'utf_reference/testing_tool_ref.adoc#decorator_timeout' + decorator_tolerance: 'utf_reference/testing_tool_ref.adoc#decorator_tolerance' + +nav: + - modules/ROOT/nav.adoc + +ext: + # Commenting this stanza out is the fast inner loop when editing prose: it + # skips MrDocs, and with it the reference module, entirely. + cpp-reference: + config: doc/mrdocs.yml + cpp-tagfiles: + using-namespaces: + - boost::unit_test + - boost::unit_test::data + - boost::unit_test::data::monomorphic + - boost::unit_test::framework + - boost::test_tools + - boost::debug diff --git a/doc/build_antora.sh b/doc/build_antora.sh new file mode 100755 index 0000000000..f550f0b1b4 --- /dev/null +++ b/doc/build_antora.sh @@ -0,0 +1,137 @@ +#!/bin/bash + +# +# 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) +# +# Official repository: https://github.com/boostorg/test +# + +set -ex + +if [ $# -eq 0 ] + then + echo "No playbook supplied, using default playbook" + PLAYBOOK="local-playbook.yml" + else + PLAYBOOK=$1 +fi + +SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd ) +cd "$SCRIPT_DIR" + +if [ -z "${BOOST_SRC_DIR:-}" ]; then + CANDIDATE=$( cd "$SCRIPT_DIR/../../.." 2>/dev/null && pwd ) + if [ -n "$CANDIDATE" ]; then + BOOST_SRC_DIR_IS_VALID=ON + for F in "CMakeLists.txt" "Jamroot" "boost-build.jam" "bootstrap.sh" "libs"; do + if [ ! -e "$CANDIDATE/$F" ]; then + BOOST_SRC_DIR_IS_VALID=OFF + break + fi + done + if [ "$BOOST_SRC_DIR_IS_VALID" = "ON" ]; then + export BOOST_SRC_DIR="$CANDIDATE" + echo "Using BOOST_SRC_DIR=$BOOST_SRC_DIR" + fi + fi +fi + +BRANCH=master + +if [ -n "${BOOST_SRC_DIR:-}" ]; then + if [ -n "${CIRCLE_REPOSITORY_URL:-}" ]; then + if [[ "$CIRCLE_REPOSITORY_URL" =~ boostorg/boost(\.git)?$ ]]; then + LIB="$(basename "$(dirname "$SCRIPT_DIR")")" + REPOSITORY="boostorg/${LIB}" + BRANCH=$(git -C "$BOOST_SRC_DIR" rev-parse --abbrev-ref HEAD) + else + ACCOUNT="${CIRCLE_REPOSITORY_URL#*:}" + ACCOUNT="${ACCOUNT%%/*}" + LIB=$(basename "$(git rev-parse --show-toplevel)") + REPOSITORY="${ACCOUNT}/${LIB}" + fi + SHA=$(git -C "$BOOST_SRC_DIR/libs" ls-tree HEAD | grep -w test | awk '{print $3}') + elif [ -n "${GITHUB_REPOSITORY:-}" ]; then + REPOSITORY="${GITHUB_REPOSITORY}" + SHA="${GITHUB_SHA}" + fi +fi + +cd "$SCRIPT_DIR" + +if [ -n "${REPOSITORY}" ] && [ -n "${SHA}" ]; then + BASE_URL="https://github.com/${REPOSITORY}/blob/${SHA}" + echo "Setting base-url to $BASE_URL" + if [ -f mrdocs.yml ]; then + cp mrdocs.yml mrdocs.yml.bak + perl -i -pe 's{^\s*base-url:.*$}{base-url: '"$BASE_URL/"'}' mrdocs.yml + fi +else + echo "REPOSITORY or SHA not set; skipping base-url modification" +fi + +# Antora's git backend requires /.git to be a directory. Inside +# a Boost superproject checkout libs/test is a submodule, so its .git is a file +# and Antora refuses the source. Derive an equivalent playbook rooted at the +# superproject in that case. A standalone clone (which is what CI checks out) +# takes neither branch and uses the playbook as written. +if [ -f "$SCRIPT_DIR/../.git" ]; then + if [ -n "${BOOST_SRC_DIR:-}" ] && [ -d "$BOOST_SRC_DIR/.git" ]; then + DERIVED_PLAYBOOK=".superproject-playbook.yml" + REL_START_PATH="${SCRIPT_DIR#"$BOOST_SRC_DIR"/}" + echo "libs/test is a submodule; deriving $DERIVED_PLAYBOOK rooted at $BOOST_SRC_DIR" + perl -pe "s{^(\s*)- url: \.\.\s*\$}{\$1- url: $BOOST_SRC_DIR\n}; + s{^(\s*)start_path: doc\s*\$}{\$1start_path: $REL_START_PATH\n}" \ + "$PLAYBOOK" > "$DERIVED_PLAYBOOK" + PLAYBOOK="$DERIVED_PLAYBOOK" + else + echo "WARNING: libs/test/.git is a file (submodule) and no usable BOOST_SRC_DIR" >&2 + echo " was found; Antora will reject the content source." >&2 + fi +fi + +echo "Building documentation with Antora..." +echo "Installing npm dependencies..." +npm ci + +echo "Building docs in custom dir..." +PATH="$(pwd)/node_modules/.bin:${PATH}" +export PATH + +# The reference pages link each header to its source with `link:{base-url}/...`. +# Point that at the exact commit when we know it; otherwise antora.yml's +# fallback applies. A command-line attribute outranks the one in antora.yml. +ANTORA_ARGS=() +if [ -n "${BASE_URL:-}" ]; then + ANTORA_ARGS+=(--attribute "base-url=$BASE_URL") +fi + +# Antora exits 0 even when xrefs and includes fail to resolve. Make that fatal +# in CI, but keep local previews usable while pages are being worked on. +if [ -n "${CI:-}" ]; then + ANTORA_ARGS+=(--log-failure-level=warn) +fi + +npx antora --clean --fetch "$PLAYBOOK" "${ANTORA_ARGS[@]}" --stacktrace # --log-level all + +echo "Fixing links to non-mrdocs URIs..." +echo "BRANCH='${BRANCH:-}'" +echo "BASE_URL='${BASE_URL:-}'" + +for f in $(find html -name '*.html'); do + perl -i -pe "s{Boost.Test}{Boost.Test}g" "$f" +done + +if [ -n "${BASE_URL:-}" ]; then + if [ -f mrdocs.yml.bak ]; then + mv -f mrdocs.yml.bak mrdocs.yml + echo "Restored original mrdocs.yml" + else + echo "mrdocs.yml.bak not found; skipping restore" + fi +fi + +echo "Done" diff --git a/doc/closing_chapters/change_log.qbk b/doc/closing_chapters/change_log.qbk deleted file mode 100644 index 90c4fc4d30..0000000000 --- a/doc/closing_chapters/change_log.qbk +++ /dev/null @@ -1,611 +0,0 @@ -[/ - / Copyright (c) 2013 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 Change log] - -Boost.Test releases: - -* [link ref_CHANGE_LOG_3_15 Boost.Test v3.15 / boost 1.79] -* [link ref_CHANGE_LOG_3_14 Boost.Test v3.14 / boost 1.74] -* [link ref_CHANGE_LOG_3_13 Boost.Test v3.13 / boost 1.73] -* [link ref_CHANGE_LOG_3_12 Boost.Test v3.12 / boost 1.72] -* [link ref_CHANGE_LOG_3_11 Boost.Test v3.11 / boost 1.71] -* [link ref_CHANGE_LOG_3_10 Boost.Test v3.10 / boost 1.70] -* [link ref_CHANGE_LOG_3_9 Boost.Test v3.9 / boost 1.69] -* [link ref_CHANGE_LOG_3_8 Boost.Test v3.8 / boost 1.68] -* [link ref_CHANGE_LOG_3_7 Boost.Test v3.7 / boost 1.67] -* [link ref_CHANGE_LOG_3_6 Boost.Test v3.6 / boost 1.65] -* [link ref_CHANGE_LOG_3_5 Boost.Test v3.5 / boost 1.64] -* [link ref_CHANGE_LOG_3_4 Boost.Test v3.4 / boost 1.63] -* [link ref_CHANGE_LOG_3_3 Boost.Test v3.3 / boost 1.62] -* [link ref_CHANGE_LOG_3_2 Boost.Test v3.2 / boost 1.61] -* [link ref_CHANGE_LOG_3_1 Boost.Test v3.1 / boost 1.60] -* [link ref_CHANGE_LOG_3_0 Boost.Test v3 / boost 1.59] - -[#ref_CHANGE_LOG_3_15][h4 Boost.Test v3.15 / boost 1.79] - -[h5 New features] - -[h5 Bugfixes and feature requests] - -# [github_issue 268] Clang warning generated by dataset grid operation in C++20 mode -# [github_issue 272] Uninitialized memory in `framework_init_observer_t` -# [github_issue 284] Undefined behavior in `basic_cstring::trim_right` -# [github_issue 297] `BOOST_TEST_GLOBAL_FIXTURE` documentation misleading -# [github_issue 305] boost test documentation tells users to file bugs with decommissioned Trac. - -# [pull_request 286] fix uninitilized variable in `framework_init_observer_t` -# [pull_request 301] UB comparing unrelated pointers in `priority_order` -# [pull_request 275] Replace anonymous `enum` arity with `static constexpr` -# [pull_request 278] Use `boost_test_print_type` customization point in `lazy_ostream` -# [pull_request 281] Export `execution_aborted` exception to allow catching it from outside the DLL - -[#ref_CHANGE_LOG_3_14][h4 Boost.Test v3.14 / boost 1.74] - -[h5 New features] - -* Now able to detect when running under a debugger on macOS/iOS. When running under a debugger, Boost.Test does not - try to catch system errors and the behaviour is the same as if the command line [link boost_test.utf_reference.rt_param_reference.catch_system `catch_system_error`] - option was set to `no`. Thanks to [@https://github.com/thughes Tom Hughes] for this feature. -* Adding support for Embarcadero C++ clang-based compilers, thanks to [@https://github.com/eldiener Edward Diener] - -[h5 Bugfixes and feature requests] - -# [github_issue 264] GCC suggest-override warnings -# [github_issue 269] Deprecated bind placeholders in tests - -# [pull_request 142] Make `under_debugger` work on apple (iOS/macOS) -# [pull_request 266] Changes for Embarcadero C++ clang-based compilers -# [pull_request 267] Use macOS API only on macOS - - -[#ref_CHANGE_LOG_3_13][h4 Boost.Test v3.13 / boost 1.73] - -[h5 New features] - -* It is now possible to combine tolerance indication, user message and collection comparison modifier in a single `BOOST_TEST` expression - - `` - std::vector v1 = f(); - std::vector v2{1.1, 1.19}; - BOOST_TEST(v1 == v2, boost::test_tools::tolerance( 1e-3 ) << "comparison to ground truth failed" << boost::test_tools::per_element()); - `` - -[h5 Bugfixes and feature requests] - -# [github_issue 173] Compare collections of floating point values with tolerance -# [github_issue 179] `test_tools-test` failed on some archs -# [github_issue 220] Support for cuda `nvcc` -# [github_issue 221] Coverity security issue (minor) (`umask`) -# [github_issue 235] Ugly GCC `-Wattributes` warnings that cannot be suppressed using /included/ variant -# [github_issue 237] Clang-cl's `-Wdelete-non-abstract-non-virtual-dtor` triggered by `test_case_gen` -# [github_issue 241] warning: comparing floating point with == or != is unsafe `[-Wfloat-equal]` -# [github_issue 245] code coverity test defect -# [github_issue 246] Incorrect usage of `BOOST_HEADER_DEPRECATED` -# [github_issue 251] Context message are always printed if both HRF and Junit loggers are enabled -# [github_issue 253] Invalid XML log is generated by `BOOST_AUTO_TEST_CASE_TEMPLATE` when tests are skipped -# [github_issue 254] Console colors are not restored on Windows -# [github_issue 263] Windows: Header-only mode with multiple translation units requires `BOOST_TEST_NO_LIB` - -# [pull_request 41] Fix: activate virtual destructors for all `msvc` versions -# [pull_request 114] Silence unreachable code warning in MSVC (`/W4`) -# [pull_request 187] enable `BOOST_TEST` with tolerance and user-message (through [github_issue 173]) -# [pull_request 239] Fix unused variable warning in `unit_test_main.ipp` -# [pull_request 247] Use `__linux__` instead of `__linux` -# [pull_request 252] Fix compilation issue due to deleted `std::basic_ostream::operator<<` from `wchar_t` -# [pull_request 259] Avoid deprecated bind placeholders in global namespace -# [pull_request 265] Suppress the unused parameter warning for `root_test_unit_id` - -# [ticket 11107] A lot of warnings on MSVC due to protected destructor being non-virtual -# [ticket 12072] Lots of `C4265` warnings in test when using Visual Studio 2015 (duplicates [ticket 11107]) - -[#ref_CHANGE_LOG_3_12][h4 Boost.Test v3.12 / boost 1.72] - -[h5 New features] - -* Support for C++17 `std::string_view` has been added. -* Better diagnostic on `boost::exception` and no rtti mode (thanks to Mikhail Pilin / [pull_request 234]) - -[h5 Bugfixes and feature requests] - -# [github_issue 206] compile-time disabled test not correctly handled by junit log -# [github_issue 217] Data test cases fail with `bool` initializer list -# [github_issue 223] Unable to filter test by name (`-t`, `--run_test`) if template type contains multiple parameters -# [github_issue 229] Random shuffle deprecated - -# [pull_request 227] Add `printf` format checking attribute to `report_error` -# [pull_request 231] OpenBSD is missing `SI_ASYNCIO` and `SI_MESGQ` -# [pull_request 232] fix timeout in windows -# [pull_request 234] `boost::diagnostic_information()` works in no `rtti` mode - -[#ref_CHANGE_LOG_3_11][h4 Boost.Test v3.11 / boost 1.71] - -[h5 New features] -* Now `BOOST_TEST` can be used to compare abstract types - -[h5 Breaking changes] - -* Marking more headers as deprecated: this might break some compilations - depending on the warning policies. - -[h5 Bugfixes and feature requests] - -# Fixing a small bug on named timers (Windows only). The bug is visible when - several test modules are executed in parallel on the same machine. - -# [github_issue 209] `BOOST_TEST_CHECK` can't compare abstract classes using gcc -# [github_issue 218] Default file name (for logger output files) - -# [pull_request 219] Commented out unused argument name (`stack_decorator::apply`) -# [pull_request 224] Add `BOOST_HEADER_DEPRECATED` to deprecated headers - -[#ref_CHANGE_LOG_3_10][h4 Boost.Test v3.10 / boost 1.70] - -[h5 New features] -* New documentation section about [link boost_test.runtime_config.custom_command_line_arguments custom command line] - arguments -* [link boost_test.tests_organization.test_cases.test_case_generation.datasets.dataset_interface Custom datasets] - are not required to declare a inner type `sample` anymore -* Boost.Test does not depend on Boost.Timer any more (which was pulling also Boost.Chrono - and Boost.System as transitive dependencies). -* Now Boost.Test raises an exception when the test case times-out on Windows. Prior to this release, - times-out on Windows were not failing the test cases. Note that signaling is not available on Windows, - and it is not possible to interrupt a test even in case of time out. -* Time-out now applies to test-suites as well: a test-suite is marked as timed-out if it exceeds the allocated - time. The test units that were not executed at the time-point of the time-out are skipped. -* It is now possible to pass several values for the same context via the tool - __BOOST_TEST_CONTEXT__. -* A new macro __BOOST_TEST_INFO_SCOPE__ let define a context for the current scope in a sticky way. -* It is now possible to use [link boost_test.testing_tools.extended_comparison.floating_point floating point] - comparison without being required to cast both operands to floating point types. Now Boost.Test uses floating - point comparisons for expressions such as - - `` - BOOST_TEST(3.0001 == 3); - `` - - See [link boost_test.testing_tools.extended_comparison.floating_point.type_promotion_of_the_operands this section] - for more information. - -[h5 Breaking changes] -* Boost.Test `minimal.hpp` is now showing a deprecation warning. `minimal.hpp` has been - deprecated for a long time already, and will be removed in the near future. Please - switch to eg. the header only variable of Boost.Test. Tests using `minimal.hpp` can - readily be converted to the header variant. For instance, the following code: - - `` - #include - int test_main( int, char *[] ) - { - ... - } - `` - - may be rewritten as: - - `` - #include - BOOST_AUTO_TEST_CASE(test_main) - { - ... - } - `` -* The floating point comparison behavior change may use this type of comparison while previously - using straight relational operator comparison. In particular this may causes ['new warnings]. - -* the member function [memberref boost::unit_test::unit_test_log_formatter::log_build_info] has slightly changed - to accept an additional boolean argument. If you have a custom logger, you will need to update its signature. - -[h5 Bugfixes and feature requests] - -# [github_issue 133] Timeout effect on Windows -# [github_issue 138] expected_failures doesn't work for `BOOST_DATA_TEST_CASE` -# [github_issue 141] Support for Boost.MP11 and Boost.Hana type lists -# [github_issue 157] Test name should handle `const`-`volatile` specifiers -# [github_issue 160] suppress `-Wformat-overflow` when optimization is enabled on GCC 8.2.0 -# [github_issue 174] `UBSAN` identified a problem at exit time by `gcc-8` only -# [github_issue 176] `[snippet_dataset1_3]` seems to be broken -# [github_issue 177] `boost_check_equal-str-test` failed on `llvm` -# [github_issue 180] Unreachable code warning on MSVC builds in test matrix -# [github_issue 181] `doc_example22` (and `23`) are expected to fail, but do not on clang with release variant builds -# [github_issue 194] `master_test_suite` declared twice -# [github_issue 196] junit report: test error is also reported as failure -# [github_issue 198] Support `BOOST_UNIT_TEST_FRAMEWORK_DYN_LINK` et al -# [github_issue 199] Runtime `type_mismatch` after upgrade to `1.69` -# [github_issue 202] `boost/timer.hpp` is deprecated -# [github_issue 203] Test cases with datasets and fixtures don't support flexible fixture interface -# [github_issue 204] Feature Request: Allow specifying timeouts for test cases with datasests. -# [github_issue 208] Incorrect handling of timed-tests on Windows -# [github_issue 211] `windows.h` should be lower case -# [github_issue 212] Comment `ar` parameter of `assertion_result` to avoid warning -# [github_issue 213] `BOOST_SYMBOL_VISIBLE` cannot be used for `enums` with Sun Studio - -# [pull_request 171] Correct library name in test runner help screen -# [pull_request 172] Check for non-used variables when `NDEBUG` is defined -# [pull_request 182] fix use of `bind1st` in `example 12` -# [pull_request 183] remove superfluous semicolon in `example 04` -# [pull_request 184] fix example to use the correct variable and avoid unused variable warning -# [pull_request 185] Added CI framework -# [pull_request 190] fix warning on gcc-7.3 in cygwin claiming `master_test_suite` is declared differently -# [pull_request 195] Fix MinGW compilation problems -# [pull_request 197] Feature Request: `BOOST_TEST_CONTEXT` that doesn't require introducing a new scope with braces -# [pull_request 205] Fix MinGW `vsnprintf` compile errors and warnings -# [pull_request 214] Fixes an issue with sun_cc lacking the __global attribute for enums - -# [ticket 7397] Boost.Test, since boost `1.48` is using the deprecated `Boost.Timer` class (solved via [github_issue 202]) -# [ticket 9434] error: `namespace boost::timer {}` re-declared as different kind of symbol (solved via [github_issue 202]) -# [ticket 13106] `libs/test/tools/console_test_runner` does not compile -# [ticket 13418] Request: allow general typelist types in `BOOST_AUTO_TEST_CASE_TEMPLATE()` - - -[#ref_CHANGE_LOG_3_9][h4 Boost.Test v3.9 / boost 1.69] - -[h5 New features] -* Official support of header-only variant of Boost.Test with multiple translation units. This feature - was available but needed to be properly documented ([link boost_test.adv_scenarios.single_header_customizations.multiple_translation_units here] - and [link boost_test.usage_variants here]). -* It is now possible to manually add a test case by specifying its name, with __BOOST_TEST_CASE_NAME__ -* Better logging of messages in `boost::exception` - -[h5 Bugfixes and feature requests] - -# [github_issue 149] Setting color_output=no does not disable the output of color format codes -# [github_issue 150] Some headers fail to compile independently -# [github_issue 156] `close_at_tolerance` always returns `false` for comparisons of infinity -# [github_issue 158] Detecting `boost_test_print_type` does not work when testing a type with an explicit conversion to `bool` -# [github_issue 163] Significant start slowdown on MSVC x64/Debug after upgrade to `v1.68.0` - -# [pull_request 147] Catch block for `boost::exception` appears after `std::exception` in `execution_monitor::execute()` -# [pull_request 148] Colored output contradiction -# [pull_request 151] Fix warning: `BOOST_CLANG` is not defined, evaluates to `0` -# [pull_request 154] When specifying `--color_output=no`, don't output color codes -# [pull_request 161] add a self-containment test - -# [ticket 13380] data-driven tests' join operator `+` corrupts first column (duplicates [ticket 12216]) -# [ticket 13625] Boost.test fail to compile with `-Werror=missing-declarations` on some architectures -# [ticket 13637] Fix for Bug [ticket 12597] causes a problem with `BOOST_TEST_CASE` - - -[#ref_CHANGE_LOG_3_8][h4 Boost.Test v3.8 / boost 1.68] - -[h5 New features] -* The tests generated from a dataset are now instantiated during the framework setup. This - let the dataset generator access the `argc` and `argv` of the master test suite. For indicating - a dataset that should be instantiated in a delayed manner, a new `data::make_delayed` helper has - been introduced. -* It is now possible to create a dataset with `data::make`, with variable number of arguments. - As the datasets are monomorphic, it should be possible to cast all elements to the first element type. - -[h5 Breaking changes] -* the [link boost_test.tests_organization.test_tree.master_test_suite `master_test_suite_t`] is not copyable anymore. -* As datasets can now be delayed, it might be that additional copies of the dataset arguments are performed. - This is especially the case for datasets created out of an `std::initializer_list`. - -[h5 Bugfixes and feature requests] -# [pull_request 143] Fix exception_api.run-fail.cpp doc example -# [pull_request 145] Fix build of library on recent Cygwin editions -# [ticket 12095] disabling test with precondition leads to error -# [ticket 12953] access to `master_test_suite().{argc, argv}` -# [ticket 13504] `[Boost::Test]` short form of `catch_system_errors` not working -# [ticket 13525] Boost Test 1.67.0: Compilation error with GCC 4.6.3 -# [ticket 13528] Boost Test 1.67 crashes when the `--report_sink` command-line parameter is used - - -[#ref_CHANGE_LOG_3_7][h4 Boost.Test v3.7 / boost 1.67] - -[h5 Breaking changes] - -* Now colour is on by default for the output streams that are either `std::cout` or `std::cerr`. This can be - disabled by passing [link boost_test.utf_reference.rt_param_reference.color_output `--no_color_ouput`] (or just `--no_color`) - to the command line. -* Adding test cases with the same name to the same test suite is reported as an error. This impacts - [link boost_test.tests_organization.test_cases.test_organization_templates template] and - [link boost_test.tests_organization.test_cases.param_test parametrized] test cases, as well as manually - registered tests. Make sure you have no duplicate names. - -[h5 New features] -* Colour output on Windows -* Improved and clearer command line help -* `BOOST_AUTO_TEST_CASE_TEMPLATE` now accepts a sequence of types in an `std::tuple` - -[h5 Bugfixes and feature requests] -# [pull_request 112] Deliberate-failure tests shouldn't be optimized -# [pull_request 118] Update VxWorks support -# [pull_request 118] `[clang]` Fix `[-Wc++11-narrowing]` error -# [pull_request 121] fix compiler warning -# [pull_request 122] Fix some fallthrough warnings with `gcc >= 7` -# [pull_request 125] Prevent 2 unused parameter warnings -# [pull_request 127] Silence 'unused variable' warning -# [pull_request 134] Fix `stdcerr` file creation on shutdown -# [pull_request 136] Change `Windows.h` include to all-lowercase (MinGW) -# [ticket 12092] Request: allow `std::tuple` typelists in `BOOST_AUTO_TEST_CASE_TEMPLATE` -# [ticket 12596] Sanitize metacharacters in test names -# [ticket 12597] Report tests with clashing names -# [ticket 12969] Problem linking `print_helper_t` under Clang -# [ticket 13058] `errors.hpp` in Boost Test requires warning `C4946` to be `off` -# [ticket 13149] Dependency decorators on parent suites -# [ticket 13170] `BOOST_AUTO_TEST_CASE_TEMPLATE` don't want `typedef` for list -# [ticket 13181] Boost test can't compare classes which have `begin` and `end` but not `const_iterator` -# [ticket 13371] Use-after-free with `--log_sink=file` -# [ticket 13387] Test header fails to compile -# [ticket 13398] Log format JUNIT generates invalid XML files -# [ticket 13407] Boost.Test appears to crash under Cygwin -# [ticket 13435] `BOOST_TEST_GLOBAL_CONFIGURATION` (result report shutdown time) -# [ticket 13443] Boost.Test data driven test fails to compile when number of samples greater than 9 - -[#ref_CHANGE_LOG_3_6][h4 Boost.Test v3.6 / boost 1.65] - -[h5 Breaking changes] -* __BOOST_GLOBAL_FIXTURE__ is flagged as deprecated and will be removed in a later version -* Using test assertions and macros is not allowed when used inside __BOOST_GLOBAL_FIXTURE__. Please use __BOOST_TEST_GLOBAL_FIXTURE__ - instead (see below). -* the interface for loggers has slightly changed to take into account the current log level. This is for addressing [ticket 12631]. - -[h5 New features] -* VS2017 / C++17 compatibility (thanks to Daniela Engert) -* Deprecating __BOOST_GLOBAL_FIXTURE__ in favor of __BOOST_TEST_GLOBAL_FIXTURE__ and __BOOST_TEST_GLOBAL_CONFIGURATION__. This - helps separating the logic of the fixtures associated to the master test suite, from the one used for setting up the logging - and reporting facility, and results in a general cleaner design. -* It is possible to use now the __BOOST_TEST__ check to comparing a collection with respect to regular arrays. See - [link ref_boost_test_coll_c_arrays this section] for more details. - -[h5 Bugfixes and feature requests] -# [pull_request 106] replace deprecated binders and adapters, and `random_shuffle` by more modern equivalents -# [ticket 5282] Test fixtures do not support virtual inheritance -# [ticket 5563] using a test macro in a global fixture crashes Boost.Test -# [ticket 11471] array is a sequence -# [ticket 11962] `BOOST_TEST_MESSAGE` in fixture constructor - invalid XML -# [ticket 12228] Some test headers fail to compile independently -# [ticket 12631] `BOOST_TEST_MESSAGE` generates incorrect output when used in `BOOST_DATA_TEST_CASE` -# [ticket 13011] `BOOST_TEST` broken with floating point relational operators - -[#ref_CHANGE_LOG_3_5][h4 Boost.Test v3.5 / boost 1.64] - -[h5 New features] -* Now Boost.Test provides [link ref_log_output_custom_customization_point customization points] for logging user defined types: - this solution is less intrusive than forcing the definition of `operator<<` for a specific type. -* [link boost_test.test_output.log_formats.log_junit_format JUnit output format] can now have a - [link boost_test.test_output.log_formats.test_log_output log-level] set between `success` and - `non-fatal error`, and defaults to `general information`. -* [link boost_test.test_output.log_formats.log_junit_format JUnit output format] is now more - efficient in case a lot of checks are done in a test module. - -[h5 Bugfixes and feature requests] -# [pull_request 107] `BOOST_NO_EXCEPTIONS` typo making `throw_exception` unusable under some circumstances -# [pull_request 108] Change capital variable names to lowercase -# [ticket 11756] boost.Test: non standards compliant use of `FE_*` macros (unable to compile boost test library on FPU-less arches) (reopened) -# [ticket 12540] Provide customization point for printing types in tests -# [ticket 12712] `BOOST_AUTO_TEST_SUITE`: Generate unique names by using `__COUNTER__` -# [ticket 12748] Boost.Test defines a variable called `VERSION` -# [ticket 12778] Boost.Test is broken against left shift operator in certain cases (`nullptr` issue) - -[#ref_CHANGE_LOG_3_4][h4 Boost.Test v3.4 / boost 1.63] - -[h5 Breaking changes] -# Now colons that appear in test case names are replaced with underscores. This affect mainly the - [link boost_test.tests_organization.test_cases.test_organization_templates template/typed test cases]. - The change is needed since the colon '`:`' is interpreted as a filter separators since 1.62, and it is - otherwise not possible to execute the tests reported by `--list_content`. See [ticket 12531] for more details. - -[h5 New features] -* Now [link boost_test_coll_perelement `per_element`] and [link boost_test_coll_default_lex `lexicographic`] modifiers of __BOOST_TEST__ - can also be applied to string comparison. See - [link boost_test.testing_tools.extended_comparison.strings string comparison] for more details. - -[h5 Bugfixes and feature requests] -# [pull_request 103] Syntactic change silences latest gcc warnings -# [pull_request 105] Fix unused parameter warnings/errors with gcc 6 -# [ticket 11756] boost.Test: non standards compliant use of `FE_*` macros (unable to compile boost test library on FPU-less arches) -# [ticket 11907] Why does `BOOST_TEST()` treat `std::string` as a collection? -# [ticket 12339] Propose users given way to disable blink in colour output -# [ticket 12506] typo in Boost.test `report_sink` description -# [ticket 12507] Boost.test `--report_sink` parameter broken -# [ticket 12530] No way to find out Boost.Test version without running any tests -# [ticket 12531] `--run_test` in Boost 1.62 does not accept test names which contain ':' - -[#ref_CHANGE_LOG_3_3][h4 Boost.Test v3.3 / boost 1.62] - -[h5 New features] -* Boost.Test now treats each sample of a dataset test case as being a uniquely named test case under the same test suite, - which enables the (re)run of one particular sample from the command line interface. See - [link boost_test.tests_organization.test_cases.test_case_generation.datasets_auto_registration.samples_and_test_tree here] - for more details, -* Boost.Test learned to interpret ':' as a separator for the test filters: the string passed to - [link boost_test.utf_reference.rt_param_reference.run_test `--run_test`] - generates tokens as if `--run_test` has been repeated, which enables the set up of several test filters - through the associated environment variable `BOOST_TEST_RUN_FILTERS` -* the __UTF__ learned to log the messages in the xUnit/JUNIT log format. - See [link boost_test.test_output.log_formats.log_junit_format here] for more details. -* the __UTF__ learned to have several loggers at the same time, each of which with their own log level and log sink. - See the associated command line switch [link boost_test.utf_reference.rt_param_reference.logger `--logger`] and - corresponding environment variable `BOOST_TEST_LOGGER` for more details. -* loggers are now able to indicate their default output stream and log level. - -[h5 Bugfixes and feature requests] -# [pull_request 81] Possibility to remove the support of the alternative stack at compilation time. See - [link boost_test.utf_reference.link_references.config_disable_alt_stack `BOOST_TEST_DISABLE_ALT_STACK`] for more details. -# [ticket 8707] Provide Standard xUnit XML Output from Boost Test -# [ticket 8834] Boost Test should be able to generate report in both XML and HRF together -# [ticket 11128] `[bb10/qnx failures]` Build error -# [ticket 11845] Ability to generate the unique and stable test name for every data set in `BOOST_DATA_TEST_CASE` -# [ticket 11859] Wrong handling of "," in Run-Parameters -# [ticket 12024] boost test depends on nonexisting `abi::__cxa_demangle` on android -# [ticket 12093] Boost 1.60.0: Build fails (gcc 4.6) -# [ticket 12103] Fix for gcc bug 58952 (`getchar()` is defined as a macro in `uClibc`) -# [ticket 12224] Crash on MSVC with RTTI disabled -# [ticket 12241] Data-driven testing over a range of `std::tuple` has broken -# [ticket 12257] Incorrect line numbers in `test_units` generated from `test_case_gen` -# [ticket 12378] Compilation errors with clang 3.8 - -[#ref_CHANGE_LOG_3_2][h4 Boost.Test v3.2 / boost 1.61] - -[h5 New features] -* now datasets support any [link boost_test.tests_organization.test_cases.test_case_generation.datasets arity], using the - variadic template support of the compiler. -* now datasets support fixtures through `BOOST_DATA_TEST_CASE_F`, see - [link boost_test.tests_organization.test_cases.test_case_generation.datasets here] for more details -* now datasets honors move semantics of the types used for samples - -[h5 Bugfixes and feature requests] -# [ticket 6767] Use of namespace qualifier with floating point exception functions breaks if they are macros -# [ticket 8905] `boost/test/impl/debug.ipp`: Ignores return value from `WaitForSingleObject` -# [ticket 9443] Runtime parameter Random seed for random order of test cases not respected correctly -# [ticket 11854] Add fixture support in `BOOST_DATA_TEST_CASE` -# [ticket 11887] `BOOST_TEST(3u == (std::max)(0u, 3u))` fails -# [ticket 11889] `BOOST_DATA_TEST_CASE` fails to compile for 4D and higher dimensional grids -# [ticket 11983] Boost Test XML Report contains unescaped XML characters - -[#ref_CHANGE_LOG_3_1][h4 Boost.Test v3.1 / boost 1.60] - -[h5 New major features] -* improved API for datasets - * it is now possible to use initializer lists - * the use of `make` as top left dataset is not necessary anymore -* improved command line interface - * clearer help commands - * now proposes closest matching command in case of ambiguity - * reports invalid or ambiguous parameters: this might break existing calls when user defined commands are - provided to the test module. The following calling convention should be adopted: - * if the test module uses user supplied commands, those should be passed after an empty token `--` - * all boost.test related commands should be passed before `--`, if any - - Example: - the call - `` - test_module --user-arg1=xy --log_level=test_suite - `` - should be rewritten to - `` - test_module --log_level=test_suite -- --user-arg1=xy - `` - -[h5 Bugfixes and feature requests] -# [ticket 3384] Double-quoted arguments including spaces are divided by Boost.Test. -# [ticket 3897] Test framework does not include `` before testing `__FreeBSD_version` (fixed in 1.59) -# [ticket 6032] Program options within `init_unit_test_suite` are incorrect when using path and whitespaces -# [ticket 6859] Boost.Test eats away last empty command line parameter -# [ticket 7257] Boost.Test alters and does not restore `ostream` precision after any Test macro (fixed in 1.59) -# [ticket 9228] Patch to make Boost.Test work with RTTI disabled (fixed in 1.59) -# [ticket 10317] boost::test corrupts contents of `argv` if a paramter contains whitespace -# [ticket 11279] invalid parameters should be reported -# [ticket 11478] Boost Test Exception Assert Failure has poor message -# [ticket 11571] Can't compile `BOOST_TEST( ..., per_element() )` comparison of `vector` -# [ticket 11623] Clang rejects some simple `BOOST_TEST()` statements -# [ticket 11624] `BOOST_TEST( 0.0 == 0.0 )` fails under C++11 (GCC and Clang) -# [ticket 11625] `BOOST_TEST( ..., per_element() )` erroneously requires collections are comparable - - -[#ref_CHANGE_LOG_3_0][h4 Boost.Test v3 / boost 1.59] - -[h5 New major features] - -* __BOOST_TEST__ generic assertion -* [link boost_test.tests_organization.test_cases.test_case_generation data driven test cases]: supersedes the parametric test case (unary test cases) -* test units [link boost_test.tests_organization.decorators attributes], that allow finer control over test units property and behavior -* logical grouping of the test units using [link boost_test.tests_organization.tests_grouping labels] -* support for declaring [link boost_test.tests_organization.tests_dependencies dependencies] over test cases -* attributes for [link boost_test.tests_organization.enabling enabling or disabling] test execution based on static, compile-time or runtime rules -* extended [link boost_test.runtime_config.test_unit_filtering unit test filtering] from the command line (negation, labels, ...) -* color output with [link boost_test.utf_reference.rt_param_reference.color_output `color_output`] -* test bed listing with [link boost_test.utf_reference.rt_param_reference.list_content `list_content`] -* rewritten documentation using quickbook - -[/* now having a more accurate timing (see [ticket 7397]) for the tests. Old format is still available through the command line option __param_deprecated_timer_format__ - in case you experience problems with the new output. ] - -[h5 Bugfixes and feature requests] -[/ pending -# [ticket 1136] Let BOOST_CHECK_EQUAL support `std::wstring` -# [ticket 4222] `feenablexcept` does not exist on mac -# [ticket 7397] Boost.Test, since boost 1.48 is using the deprecated Boost.Timer class - it should be updated to use the new class -] -# [ticket 2018] Error in the documentation chapter "Runtime parameters reference" -# [ticket 2450] equations in Floating-point comparison algorithms html are not rendered properly -# [ticket 2600] Unit Test Framework - missed documentation -# [ticket 2717] `BOOST__EQUAL_COLLECTION` docs typo -# [ticket 2759] Typos in test new-year-resolution.html -# [ticket 3182] `_CrtSetReportFile` can be used to redirect memory leaks report -# [ticket 3316] Access violation when trying to log from `init_tests_func` -# [ticket 3392] Boost::Test: Wrong contents for documentation of the `BOOST_TEST_PASSPOINT` macro -# [ticket 3402] Invalid define name in documentation (duplicates #[ticket 2717]) -# [ticket 3445] incorrect link in the docs -# [ticket 3463] `GT` is GREAT! -# [ticket 3542] Bug in documentation of detect_memory_leak parameter (duplicates #[ticket 2018]) -# [ticket 3481] Boost Testing doesn't work under Sun Solaris Containers (duplicates #[ticket 3592]) -# [ticket 3495] Boost::Test enters endless loop when running in `vserver` environment (duplicates #[ticket 3592]) -# [ticket 3592] under_debugger() goes into infinite loop -# [ticket 3595] Typo (duplicates #[ticket 2759]) -# [ticket 3623] Boost Test Typo (duplicates #[ticket 2759]) -# [ticket 3664] `SIGCHLD` always considered fatal error -# [ticket 3784] Documentation errors in Execution Monitor Compilation -# [ticket 3785] Documentation errors in Program Execution Monitor implementation -# [ticket 3811] global namespace pollution -# [ticket 3834] doc: probably incorrect HTML rendering (duplicates #[ticket 2450]) -# [ticket 3896] erroneous documentation in boost test command line parameter description -# [ticket 3932] Error in `BOOST__GT` description (duplicates #[ticket 3463]) -# [ticket 3938] doc: incorrect macro name (duplicates #[ticket 2759]) -# [ticket 3964] Documentation for `BOOST__CLOSE_FRACTION` is incorrect -# [ticket 3978] Failed to completely redirect TestLog to file, bugfix appended -# [ticket 3979] `` requires additional includes -# [ticket 4161] spelling mistakes... -# [ticket 4275] Documentation error Boost.Test (duplicates #[ticket 2717]) -# [ticket 4389] Enable boost_test to run specific tests with any required dependent tests. -# [ticket 4434] `BOOST_AUTO_EST_CASE` typos in docs -# [ticket 4587] Broken link in website -# [ticket 4806] Invalid link (examples not showing up in documentation) -# [ticket 4911] ENH: boost.test output the exception real type name. -# [ticket 4923] Missing semicolon in documentation example -# [ticket 4924] Minor typo in Boost::Test docs -# [ticket 4982] Boost.Test has misspelled Gennadiy Rozental e-mail address -# [ticket 5008] Boost.Test does not do check-pointing of entry/exit of test cases -# [ticket 5036] Boost.Test VC memory leak report should direct to `stderr` -# [ticket 5262] Run tests by name utility doesn't support negation -# [ticket 5374] Errors from Boost.Test are no more shown in the Error list in VS2010 -# [ticket 5412] XML formatter in test library processes strings with subsequences `]]>` incorrectly -# [ticket 5563] using a test macro in a global fixture crashes Boost.Test -# [ticket 5582] There is a memory leak in the `BOOST_AUTO_TEST_CASE_TEMPLATE` -# [ticket 5599] boost::test documentation gives poor instruction -# [ticket 5718] broken link to unit testing framework examples -# [ticket 5729] Missing static_cast in fpt_limits -# [ticket 5870] The warning stack is not maintained -# [ticket 5972] Support program option to only dump the test-tree in text to output stream -# [ticket 6002] Failed to completely redirect TestLog to file (duplicates) -# [ticket 6071] Boost Test (Boost 1.46.0) GCC 4.6.1 error: ambiguous overload for ‘operator[]’ -# [ticket 6074] warnings-as-errors not usable with Boost.test in release mode -# [ticket 6161] SunOS: bad `putenv` declaration (duplicates [ticket 6766]) -# [ticket 6766] incorrect declaration for `putenv` in `config.hpp` -# [ticket 6712] Eliminate warnings with GCC -# [ticket 6748] Link in the documentation points to wrong page -# [ticket 7046] Output full error message, not just 512 chars -# [ticket 7136] Correct documentation for `BOOST__CLOSE_FRACTION` is not reflected into released documents -# [ticket 7410] Test Units (Cases and Suites) in Boost.Test do not capture `__FILE__` and `__LINE__` at declaration point making it impossible to provide source file linking using external test management tools -# [ticket 7894] Boost.Test documentation contains no linking instructions -# [ticket 8201] Broken link in document -# [ticket 8272] `BOOST_REQUIRE_CLOSE` fails to compile with `boost::multiprecision::cpp_dec_float_100` (duplicates #[ticket 11054]) -# [ticket 8467] Incorrect link in document (duplicates #[ticket 6748]) -# [ticket 8679] Boost.Test pollutes boost namespace with it's own `enable_if/disable_if` templates -# [ticket 8862] Boost.Test typo in documentation -# [ticket 8895] English error in test collection comparison -# [ticket 9179] Documentation: broken link (unable to find =const_string.hpp/const_string_test.cpp=) -# [ticket 9272] boost::test `BOOST__GT` documentation bug (duplicates #[ticket 3463]) -# [ticket 9390] Incomplete `BOOST_TEST_DONT_PRINT_LOG_VALUE` -# [ticket 9409] Some source code examples are missing -# [ticket 9537] const_string_test example fails -# [ticket 9539] Floating-point comparison algorithms aren't formatted correctly -# [ticket 9581] Squassabia reference link gives 404 not found -# [ticket 9960] Warnings on Clang -# [ticket 10256] [boost test] - issue: `sigaltstack` -# [ticket 10318] Minor documentation fix -# [ticket 10394] Broken links in Boost Test documentation -# [ticket 10888] Assertion failures don't show up in the errors pane in VS 2010, VS 2012 or VS 2013 (duplicates) -# [ticket 11054] Floating-point comparison of multiprecision values fails if expression template is on -# [ticket 11347] `DS` identifier causes test failures in `doc/examples/dataset_example*.cpp` -# [ticket 11358] Boost.Test v3 warning could helpfully be suppressed. -# [ticket 11359] `BOOST_CHECK_EQUAL_COLLECTIONS`: can't control output operator (duplicates #9390) -# [ticket 11425] use-of-uninitialized-value (obsolete) - -[endsect] diff --git a/doc/closing_chapters/glossary.qbk b/doc/closing_chapters/glossary.qbk deleted file mode 100644 index a520c70745..0000000000 --- a/doc/closing_chapters/glossary.qbk +++ /dev/null @@ -1,103 +0,0 @@ -[/ - / 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:section_glossary Glossary] - -Here is the list of terms used throughout this documentation. - -[#ref_test_module][h3 Test module] -This is a single binary that performs the test. Physically a test module consists of one or more test source files, -which can be built into an executable or a dynamic library. A test module that consists of a single test source -file is called ['single-file test module]. Otherwise -it's called ['multi-file test module]. Logically, each test module consists of four parts: - -# [link test_setup test setup] (or test initialization), -# [link test_body test body] -# [link test_cleanup test cleanup] -# [link test_runner test runner] - -The test runner part is optional. If a test module is built as -an executable, the test runner is built-in. If a test module is built as a dynamic library, it is run by an -[link boost_test.adv_scenarios.external_test_runner external test runner]. - -[warning The test module should have at least one test-case defined, otherwise it is considered as an error.] - -[#test_body][h3 Test body] -This is the part of a test module that actually performs the test. -Logically test body is a collection of [link test_assertion test assertions] wrapped in -[link test_case test cases], which are organized in a [link ref_test_tree test tree]. - -[#ref_test_tree][h3 Test tree] -This is a hierarchical structure of [link test_suite test suites] (non-leaf nodes) and -[link test_case test cases] (leaf nodes). More details can be found [link boost_test.tests_organization here]. - -[#ref_test_unit][h3 Test unit] -This is a collective name when referred to either a [link test_suite test suite] or -[link test_case test cases]. See [link boost_test.tests_organization this section] for more details. - -[#test_assertion][h3 Test assertion] -This is a single binary condition (binary in a sense that is has two outcomes: pass and fail) checked -by a test module. - -There are different schools of thought on how many test assertions a test case should consist of. Two polar -positions are the one advocated by TDD followers - one assertion per test case; and opposite of this - all test -assertions within single test case - advocated by those only interested in the first error in a -test module. The __UTF__ supports both approaches. - -[#test_case][h3 Test case] -This is an independently monitored function within a test module that -consists of one or more test assertions. The term ['independently monitored] in the definition above is -used to emphasize the fact, that all test cases are monitored independently. An uncaught exception or other normal -test case execution termination doesn't cause the testing to cease. Instead the error is caught by the test -case execution monitor, reported by the __UTF__ and testing proceeds to the next test case. Later on you are going -to see that this is on of the primary reasons to prefer multiple small test cases to a single big test function. - - -[#test_suite][h3 Test suite] -This is a container for one or more test cases. The test suite gives you an ability to group -test cases into a single referable entity. There are various reasons why you may opt to do so, including: - -* To group test cases per subsystems of the unit being tested. -* To share test case setup/cleanup code. -* To run selected group of test cases only. -* To see test report split by groups of test cases. -* To skip groups of test cases based on the result of another test unit in a test tree. - -A test suite can also contain other test suites, thus allowing a hierarchical test tree structure to be formed. -The __UTF__ requires the test tree to contain at least one test suite with at least one test case. The top level -test suite - root node of the test tree - is called the master test suite. - - - -[#test_setup][h3 Test setup] -This is the part of a test module that is responsible for the test -preparation. It includes the following operations that take place prior to a start of the test: - -* The __UTF__ initialization -* Test tree construction -* Global test module setup code -* ['Per test case] setup code, invoked for every test case it's assigned to, is also attributed to the - test initialization, even though it's executed as a part of the test case. - -[#test_cleanup][h3 Test cleanup] -This is the part of test module that is responsible for cleanup operations. - -[#test_fixture][h3 Test fixture] -Matching setup and cleanup operations are frequently united into a single entity called test fixture. - -[#test_runner][h3 Test runner] -This is an ['orchestrator] or a ['driver] that, given the test tree, ensures the test tree is initialized, tests are executed and necessary reports generated. For more information [link boost_test.adv_scenarios.test_module_runner_overview see here]. - -[#test_log][h3 Test log] -This is the record of all events that occur during the testing. - -[#test_report][h3 Test report] -This is the report produced by the __UTF__ after the testing is completed, that indicates which test cases/test -suites passed and which failed. - - -[endsect] [/ Glossary] diff --git a/doc/doxygen/Doxyfile b/doc/doxygen/Doxyfile deleted file mode 100644 index e837e07c0a..0000000000 --- a/doc/doxygen/Doxyfile +++ /dev/null @@ -1,2357 +0,0 @@ -# Doxyfile 1.8.8 - -# This file describes the settings to be used by the documentation system -# doxygen (www.doxygen.org) for a project. -# -# All text after a double hash (##) is considered a comment and is placed in -# front of the TAG it is preceding. -# -# All text after a single hash (#) is considered a comment and will be ignored. -# The format is: -# TAG = value [value, ...] -# For lists, items can also be appended using: -# TAG += value [value, ...] -# Values that contain spaces should be placed between quotes (\" \"). - -#--------------------------------------------------------------------------- -# Project related configuration options -#--------------------------------------------------------------------------- - -# This tag specifies the encoding used for all characters in the config file -# that follow. The default is UTF-8 which is also the encoding used for all text -# before the first occurrence of this tag. Doxygen uses libiconv (or the iconv -# built into libc) for the transcoding. See http://www.gnu.org/software/libiconv -# for the list of possible encodings. -# The default value is: UTF-8. - -DOXYFILE_ENCODING = UTF-8 - -# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by -# double-quotes, unless you are using Doxywizard) that should identify the -# project for which the documentation is generated. This name is used in the -# title of most generated pages and in a few other places. -# The default value is: My Project. - -PROJECT_NAME = "Boost.Test Reference" - -# The PROJECT_NUMBER tag can be used to enter a project or revision number. This -# could be handy for archiving the generated documentation or if some version -# control system is used. - -PROJECT_NUMBER = - -# Using the PROJECT_BRIEF tag one can provide an optional one line description -# for a project that appears at the top of each page and should give viewer a -# quick idea about the purpose of the project. Keep the description short. - -PROJECT_BRIEF = - -# With the PROJECT_LOGO tag one can specify an logo or icon that is included in -# the documentation. The maximum height of the logo should not exceed 55 pixels -# and the maximum width should not exceed 200 pixels. Doxygen will copy the logo -# to the output directory. - -PROJECT_LOGO = - -# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path -# into which the generated documentation will be written. If a relative path is -# entered, it will be relative to the location where doxygen was started. If -# left blank the current directory will be used. - -OUTPUT_DIRECTORY = - -# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 4096 sub- -# directories (in 2 levels) under the output directory of each output format and -# will distribute the generated files over these directories. Enabling this -# option can be useful when feeding doxygen a huge amount of source files, where -# putting all generated files in the same directory would otherwise causes -# performance problems for the file system. -# The default value is: NO. - -CREATE_SUBDIRS = NO - -# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII -# characters to appear in the names of generated files. If set to NO, non-ASCII -# characters will be escaped, for example _xE3_x81_x84 will be used for Unicode -# U+3044. -# The default value is: NO. - -ALLOW_UNICODE_NAMES = NO - -# The OUTPUT_LANGUAGE tag is used to specify the language in which all -# documentation generated by doxygen is written. Doxygen will use this -# information to generate all constant output in the proper language. -# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese, -# Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States), -# Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian, -# Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages), -# Korean, Korean-en (Korean with English messages), Latvian, Lithuanian, -# Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian, -# Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish, -# Ukrainian and Vietnamese. -# The default value is: English. - -OUTPUT_LANGUAGE = English - -# If the BRIEF_MEMBER_DESC tag is set to YES doxygen will include brief member -# descriptions after the members that are listed in the file and class -# documentation (similar to Javadoc). Set to NO to disable this. -# The default value is: YES. - -BRIEF_MEMBER_DESC = YES - -# If the REPEAT_BRIEF tag is set to YES doxygen will prepend the brief -# description of a member or function before the detailed description -# -# Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the -# brief descriptions will be completely suppressed. -# The default value is: YES. - -REPEAT_BRIEF = YES - -# This tag implements a quasi-intelligent brief description abbreviator that is -# used to form the text in various listings. Each string in this list, if found -# as the leading text of the brief description, will be stripped from the text -# and the result, after processing the whole list, is used as the annotated -# text. Otherwise, the brief description is used as-is. If left blank, the -# following values are used ($name is automatically replaced with the name of -# the entity):The $name class, The $name widget, The $name file, is, provides, -# specifies, contains, represents, a, an and the. - -ABBREVIATE_BRIEF = - -# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then -# doxygen will generate a detailed section even if there is only a brief -# description. -# The default value is: NO. - -ALWAYS_DETAILED_SEC = NO - -# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all -# inherited members of a class in the documentation of that class as if those -# members were ordinary class members. Constructors, destructors and assignment -# operators of the base classes will not be shown. -# The default value is: NO. - -INLINE_INHERITED_MEMB = NO - -# If the FULL_PATH_NAMES tag is set to YES doxygen will prepend the full path -# before files name in the file list and in the header files. If set to NO the -# shortest path that makes the file name unique will be used -# The default value is: YES. - -FULL_PATH_NAMES = YES - -# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. -# Stripping is only done if one of the specified strings matches the left-hand -# part of the path. The tag can be used to show relative paths in the file list. -# If left blank the directory from which doxygen is run is used as the path to -# strip. -# -# Note that you can specify absolute paths here, but also relative paths, which -# will be relative from the directory where doxygen is started. -# This tag requires that the tag FULL_PATH_NAMES is set to YES. - -STRIP_FROM_PATH = ../../include - -# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the -# path mentioned in the documentation of a class, which tells the reader which -# header file to include in order to use a class. If left blank only the name of -# the header file containing the class definition is used. Otherwise one should -# specify the list of include paths that are normally passed to the compiler -# using the -I flag. - -STRIP_FROM_INC_PATH = - -# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but -# less readable) file names. This can be useful is your file systems doesn't -# support long names like on DOS, Mac, or CD-ROM. -# The default value is: NO. - -SHORT_NAMES = NO - -# If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the -# first line (until the first dot) of a Javadoc-style comment as the brief -# description. If set to NO, the Javadoc-style will behave just like regular Qt- -# style comments (thus requiring an explicit @brief command for a brief -# description.) -# The default value is: NO. - -JAVADOC_AUTOBRIEF = NO - -# If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first -# line (until the first dot) of a Qt-style comment as the brief description. If -# set to NO, the Qt-style will behave just like regular Qt-style comments (thus -# requiring an explicit \brief command for a brief description.) -# The default value is: NO. - -QT_AUTOBRIEF = NO - -# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a -# multi-line C++ special comment block (i.e. a block of //! or /// comments) as -# a brief description. This used to be the default behavior. The new default is -# to treat a multi-line C++ comment block as a detailed description. Set this -# tag to YES if you prefer the old behavior instead. -# -# Note that setting this tag to YES also means that rational rose comments are -# not recognized any more. -# The default value is: NO. - -MULTILINE_CPP_IS_BRIEF = NO - -# If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the -# documentation from any documented member that it re-implements. -# The default value is: YES. - -INHERIT_DOCS = YES - -# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce a -# new page for each member. If set to NO, the documentation of a member will be -# part of the file/class/namespace that contains it. -# The default value is: NO. - -SEPARATE_MEMBER_PAGES = NO - -# The TAB_SIZE tag can be used to set the number of spaces in a tab. Doxygen -# uses this value to replace tabs by spaces in code fragments. -# Minimum value: 1, maximum value: 16, default value: 4. - -TAB_SIZE = 2 - -# This tag can be used to specify a number of aliases that act as commands in -# the documentation. An alias has the form: -# name=value -# For example adding -# "sideeffect=@par Side Effects:\n" -# will allow you to put the command \sideeffect (or @sideeffect) in the -# documentation, which will result in a user-defined paragraph with heading -# "Side Effects:". You can put \n's in the value part of an alias to insert -# newlines. - -ALIASES = - -# This tag can be used to specify a number of word-keyword mappings (TCL only). -# A mapping has the form "name=value". For example adding "class=itcl::class" -# will allow you to use the command class in the itcl::class meaning. - -TCL_SUBST = - -# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources -# only. Doxygen will then generate output that is more tailored for C. For -# instance, some of the names that are used will be different. The list of all -# members will be omitted, etc. -# The default value is: NO. - -OPTIMIZE_OUTPUT_FOR_C = NO - -# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or -# Python sources only. Doxygen will then generate output that is more tailored -# for that language. For instance, namespaces will be presented as packages, -# qualified scopes will look different, etc. -# The default value is: NO. - -OPTIMIZE_OUTPUT_JAVA = NO - -# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran -# sources. Doxygen will then generate output that is tailored for Fortran. -# The default value is: NO. - -OPTIMIZE_FOR_FORTRAN = NO - -# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL -# sources. Doxygen will then generate output that is tailored for VHDL. -# The default value is: NO. - -OPTIMIZE_OUTPUT_VHDL = NO - -# Doxygen selects the parser to use depending on the extension of the files it -# parses. With this tag you can assign which parser to use for a given -# extension. Doxygen has a built-in mapping, but you can override or extend it -# using this tag. The format is ext=language, where ext is a file extension, and -# language is one of the parsers supported by doxygen: IDL, Java, Javascript, -# C#, C, C++, D, PHP, Objective-C, Python, Fortran (fixed format Fortran: -# FortranFixed, free formatted Fortran: FortranFree, unknown formatted Fortran: -# Fortran. In the later case the parser tries to guess whether the code is fixed -# or free formatted code, this is the default for Fortran type files), VHDL. For -# instance to make doxygen treat .inc files as Fortran files (default is PHP), -# and .f files as C (default is Fortran), use: inc=Fortran f=C. -# -# Note For files without extension you can use no_extension as a placeholder. -# -# Note that for custom extensions you also need to set FILE_PATTERNS otherwise -# the files are not read by doxygen. - -EXTENSION_MAPPING = - -# If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments -# according to the Markdown format, which allows for more readable -# documentation. See http://daringfireball.net/projects/markdown/ for details. -# The output of markdown processing is further processed by doxygen, so you can -# mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in -# case of backward compatibilities issues. -# The default value is: YES. - -MARKDOWN_SUPPORT = YES - -# When enabled doxygen tries to link words that correspond to documented -# classes, or namespaces to their corresponding documentation. Such a link can -# be prevented in individual cases by by putting a % sign in front of the word -# or globally by setting AUTOLINK_SUPPORT to NO. -# The default value is: YES. - -AUTOLINK_SUPPORT = YES - -# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want -# to include (a tag file for) the STL sources as input, then you should set this -# tag to YES in order to let doxygen match functions declarations and -# definitions whose arguments contain STL classes (e.g. func(std::string); -# versus func(std::string) {}). This also make the inheritance and collaboration -# diagrams that involve STL classes more complete and accurate. -# The default value is: NO. - -BUILTIN_STL_SUPPORT = NO - -# If you use Microsoft's C++/CLI language, you should set this option to YES to -# enable parsing support. -# The default value is: NO. - -CPP_CLI_SUPPORT = NO - -# Set the SIP_SUPPORT tag to YES if your project consists of sip (see: -# http://www.riverbankcomputing.co.uk/software/sip/intro) sources only. Doxygen -# will parse them like normal C++ but will assume all classes use public instead -# of private inheritance when no explicit protection keyword is present. -# The default value is: NO. - -SIP_SUPPORT = NO - -# For Microsoft's IDL there are propget and propput attributes to indicate -# getter and setter methods for a property. Setting this option to YES will make -# doxygen to replace the get and set methods by a property in the documentation. -# This will only work if the methods are indeed getting or setting a simple -# type. If this is not the case, or you want to show the methods anyway, you -# should set this option to NO. -# The default value is: YES. - -IDL_PROPERTY_SUPPORT = YES - -# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC -# tag is set to YES, then doxygen will reuse the documentation of the first -# member in the group (if any) for the other members of the group. By default -# all members of a group must be documented explicitly. -# The default value is: NO. - -DISTRIBUTE_GROUP_DOC = NO - -# Set the SUBGROUPING tag to YES to allow class member groups of the same type -# (for instance a group of public functions) to be put as a subgroup of that -# type (e.g. under the Public Functions section). Set it to NO to prevent -# subgrouping. Alternatively, this can be done per class using the -# \nosubgrouping command. -# The default value is: YES. - -SUBGROUPING = YES - -# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and unions -# are shown inside the group in which they are included (e.g. using \ingroup) -# instead of on a separate page (for HTML and Man pages) or section (for LaTeX -# and RTF). -# -# Note that this feature does not work in combination with -# SEPARATE_MEMBER_PAGES. -# The default value is: NO. - -INLINE_GROUPED_CLASSES = NO - -# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions -# with only public data fields or simple typedef fields will be shown inline in -# the documentation of the scope in which they are defined (i.e. file, -# namespace, or group documentation), provided this scope is documented. If set -# to NO, structs, classes, and unions are shown on a separate page (for HTML and -# Man pages) or section (for LaTeX and RTF). -# The default value is: NO. - -INLINE_SIMPLE_STRUCTS = NO - -# When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or -# enum is documented as struct, union, or enum with the name of the typedef. So -# typedef struct TypeS {} TypeT, will appear in the documentation as a struct -# with name TypeT. When disabled the typedef will appear as a member of a file, -# namespace, or class. And the struct will be named TypeS. This can typically be -# useful for C code in case the coding convention dictates that all compound -# types are typedef'ed and only the typedef is referenced, never the tag name. -# The default value is: NO. - -TYPEDEF_HIDES_STRUCT = NO - -# The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This -# cache is used to resolve symbols given their name and scope. Since this can be -# an expensive process and often the same symbol appears multiple times in the -# code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small -# doxygen will become slower. If the cache is too large, memory is wasted. The -# cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range -# is 0..9, the default is 0, corresponding to a cache size of 2^16=65536 -# symbols. At the end of a run doxygen will report the cache usage and suggest -# the optimal cache size from a speed point of view. -# Minimum value: 0, maximum value: 9, default value: 0. - -LOOKUP_CACHE_SIZE = 0 - -#--------------------------------------------------------------------------- -# Build related configuration options -#--------------------------------------------------------------------------- - -# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in -# documentation are documented, even if no documentation was available. Private -# class members and static file members will be hidden unless the -# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES. -# Note: This will also disable the warnings about undocumented members that are -# normally produced when WARNINGS is set to YES. -# The default value is: NO. - -EXTRACT_ALL = NO - -# If the EXTRACT_PRIVATE tag is set to YES all private members of a class will -# be included in the documentation. -# The default value is: NO. - -EXTRACT_PRIVATE = NO - -# If the EXTRACT_PACKAGE tag is set to YES all members with package or internal -# scope will be included in the documentation. -# The default value is: NO. - -EXTRACT_PACKAGE = NO - -# If the EXTRACT_STATIC tag is set to YES all static members of a file will be -# included in the documentation. -# The default value is: NO. - -EXTRACT_STATIC = NO - -# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) defined -# locally in source files will be included in the documentation. If set to NO -# only classes defined in header files are included. Does not have any effect -# for Java sources. -# The default value is: YES. - -EXTRACT_LOCAL_CLASSES = NO - -# This flag is only useful for Objective-C code. When set to YES local methods, -# which are defined in the implementation section but not in the interface are -# included in the documentation. If set to NO only methods in the interface are -# included. -# The default value is: NO. - -EXTRACT_LOCAL_METHODS = NO - -# If this flag is set to YES, the members of anonymous namespaces will be -# extracted and appear in the documentation as a namespace called -# 'anonymous_namespace{file}', where file will be replaced with the base name of -# the file that contains the anonymous namespace. By default anonymous namespace -# are hidden. -# The default value is: NO. - -EXTRACT_ANON_NSPACES = NO - -# If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all -# undocumented members inside documented classes or files. If set to NO these -# members will be included in the various overviews, but no documentation -# section is generated. This option has no effect if EXTRACT_ALL is enabled. -# The default value is: NO. - -HIDE_UNDOC_MEMBERS = YES - -# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all -# undocumented classes that are normally visible in the class hierarchy. If set -# to NO these classes will be included in the various overviews. This option has -# no effect if EXTRACT_ALL is enabled. -# The default value is: NO. - -HIDE_UNDOC_CLASSES = YES - -# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend -# (class|struct|union) declarations. If set to NO these declarations will be -# included in the documentation. -# The default value is: NO. - -HIDE_FRIEND_COMPOUNDS = NO - -# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any -# documentation blocks found inside the body of a function. If set to NO these -# blocks will be appended to the function's detailed documentation block. -# The default value is: NO. - -HIDE_IN_BODY_DOCS = YES - -# The INTERNAL_DOCS tag determines if documentation that is typed after a -# \internal command is included. If the tag is set to NO then the documentation -# will be excluded. Set it to YES to include the internal documentation. -# The default value is: NO. - -INTERNAL_DOCS = NO - -# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file -# names in lower-case letters. If set to YES upper-case letters are also -# allowed. This is useful if you have classes or files whose names only differ -# in case and if your file system supports case sensitive file names. Windows -# and Mac users are advised to set this option to NO. -# The default value is: system dependent. - -CASE_SENSE_NAMES = NO - -# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with -# their full class and namespace scopes in the documentation. If set to YES the -# scope will be hidden. -# The default value is: NO. - -HIDE_SCOPE_NAMES = NO - -# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of -# the files that are included by a file in the documentation of that file. -# The default value is: YES. - -SHOW_INCLUDE_FILES = NO - -# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each -# grouped member an include statement to the documentation, telling the reader -# which file to include in order to use the member. -# The default value is: NO. - -SHOW_GROUPED_MEMB_INC = NO - -# If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include -# files with double quotes in the documentation rather than with sharp brackets. -# The default value is: NO. - -FORCE_LOCAL_INCLUDES = NO - -# If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the -# documentation for inline members. -# The default value is: YES. - -INLINE_INFO = YES - -# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the -# (detailed) documentation of file and class members alphabetically by member -# name. If set to NO the members will appear in declaration order. -# The default value is: YES. - -SORT_MEMBER_DOCS = NO - -# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief -# descriptions of file, namespace and class members alphabetically by member -# name. If set to NO the members will appear in declaration order. Note that -# this will also influence the order of the classes in the class list. -# The default value is: NO. - -SORT_BRIEF_DOCS = NO - -# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the -# (brief and detailed) documentation of class members so that constructors and -# destructors are listed first. If set to NO the constructors will appear in the -# respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS. -# Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief -# member documentation. -# Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting -# detailed member documentation. -# The default value is: NO. - -SORT_MEMBERS_CTORS_1ST = NO - -# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy -# of group names into alphabetical order. If set to NO the group names will -# appear in their defined order. -# The default value is: NO. - -SORT_GROUP_NAMES = NO - -# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by -# fully-qualified names, including namespaces. If set to NO, the class list will -# be sorted only by class name, not including the namespace part. -# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. -# Note: This option applies only to the class list, not to the alphabetical -# list. -# The default value is: NO. - -SORT_BY_SCOPE_NAME = NO - -# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper -# type resolution of all parameters of a function it will reject a match between -# the prototype and the implementation of a member function even if there is -# only one candidate or it is obvious which candidate to choose by doing a -# simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still -# accept a match between prototype and implementation in such cases. -# The default value is: NO. - -STRICT_PROTO_MATCHING = YES - -# The GENERATE_TODOLIST tag can be used to enable ( YES) or disable ( NO) the -# todo list. This list is created by putting \todo commands in the -# documentation. -# The default value is: YES. - -GENERATE_TODOLIST = YES - -# The GENERATE_TESTLIST tag can be used to enable ( YES) or disable ( NO) the -# test list. This list is created by putting \test commands in the -# documentation. -# The default value is: YES. - -GENERATE_TESTLIST = YES - -# The GENERATE_BUGLIST tag can be used to enable ( YES) or disable ( NO) the bug -# list. This list is created by putting \bug commands in the documentation. -# The default value is: YES. - -GENERATE_BUGLIST = YES - -# The GENERATE_DEPRECATEDLIST tag can be used to enable ( YES) or disable ( NO) -# the deprecated list. This list is created by putting \deprecated commands in -# the documentation. -# The default value is: YES. - -GENERATE_DEPRECATEDLIST= YES - -# The ENABLED_SECTIONS tag can be used to enable conditional documentation -# sections, marked by \if ... \endif and \cond -# ... \endcond blocks. - -ENABLED_SECTIONS = - -# The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the -# initial value of a variable or macro / define can have for it to appear in the -# documentation. If the initializer consists of more lines than specified here -# it will be hidden. Use a value of 0 to hide initializers completely. The -# appearance of the value of individual variables and macros / defines can be -# controlled using \showinitializer or \hideinitializer command in the -# documentation regardless of this setting. -# Minimum value: 0, maximum value: 10000, default value: 30. - -MAX_INITIALIZER_LINES = 30 - -# Set the SHOW_USED_FILES tag to NO to disable the list of files generated at -# the bottom of the documentation of classes and structs. If set to YES the list -# will mention the files that were used to generate the documentation. -# The default value is: YES. - -SHOW_USED_FILES = YES - -# Set the SHOW_FILES tag to NO to disable the generation of the Files page. This -# will remove the Files entry from the Quick Index and from the Folder Tree View -# (if specified). -# The default value is: YES. - -SHOW_FILES = YES - -# Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces -# page. This will remove the Namespaces entry from the Quick Index and from the -# Folder Tree View (if specified). -# The default value is: YES. - -SHOW_NAMESPACES = YES - -# The FILE_VERSION_FILTER tag can be used to specify a program or script that -# doxygen should invoke to get the current version for each file (typically from -# the version control system). Doxygen will invoke the program by executing (via -# popen()) the command command input-file, where command is the value of the -# FILE_VERSION_FILTER tag, and input-file is the name of an input file provided -# by doxygen. Whatever the program writes to standard output is used as the file -# version. For an example see the documentation. - -FILE_VERSION_FILTER = - -# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed -# by doxygen. The layout file controls the global structure of the generated -# output files in an output format independent way. To create the layout file -# that represents doxygen's defaults, run doxygen with the -l option. You can -# optionally specify a file name after the option, if omitted DoxygenLayout.xml -# will be used as the name of the layout file. -# -# Note that if you run doxygen from a directory containing a file called -# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE -# tag is left empty. - -LAYOUT_FILE = - -# The CITE_BIB_FILES tag can be used to specify one or more bib files containing -# the reference definitions. This must be a list of .bib files. The .bib -# extension is automatically appended if omitted. This requires the bibtex tool -# to be installed. See also http://en.wikipedia.org/wiki/BibTeX for more info. -# For LaTeX the style of the bibliography can be controlled using -# LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the -# search path. See also \cite for info how to create references. - -CITE_BIB_FILES = - -#--------------------------------------------------------------------------- -# Configuration options related to warning and progress messages -#--------------------------------------------------------------------------- - -# The QUIET tag can be used to turn on/off the messages that are generated to -# standard output by doxygen. If QUIET is set to YES this implies that the -# messages are off. -# The default value is: NO. - -QUIET = NO - -# The WARNINGS tag can be used to turn on/off the warning messages that are -# generated to standard error ( stderr) by doxygen. If WARNINGS is set to YES -# this implies that the warnings are on. -# -# Tip: Turn warnings on while writing the documentation. -# The default value is: YES. - -WARNINGS = YES - -# If the WARN_IF_UNDOCUMENTED tag is set to YES, then doxygen will generate -# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag -# will automatically be disabled. -# The default value is: YES. - -WARN_IF_UNDOCUMENTED = YES - -# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for -# potential errors in the documentation, such as not documenting some parameters -# in a documented function, or documenting parameters that don't exist or using -# markup commands wrongly. -# The default value is: YES. - -WARN_IF_DOC_ERROR = YES - -# This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that -# are documented, but have no documentation for their parameters or return -# value. If set to NO doxygen will only warn about wrong or incomplete parameter -# documentation, but not about the absence of documentation. -# The default value is: NO. - -WARN_NO_PARAMDOC = YES - -# The WARN_FORMAT tag determines the format of the warning messages that doxygen -# can produce. The string should contain the $file, $line, and $text tags, which -# will be replaced by the file and line number from which the warning originated -# and the warning text. Optionally the format may contain $version, which will -# be replaced by the version of the file (if it could be obtained via -# FILE_VERSION_FILTER) -# The default value is: $file:$line: $text. - -WARN_FORMAT = "$file:$line: $text" - -# The WARN_LOGFILE tag can be used to specify a file to which warning and error -# messages should be written. If left blank the output is written to standard -# error (stderr). - -WARN_LOGFILE = warnings.log - -#--------------------------------------------------------------------------- -# Configuration options related to the input files -#--------------------------------------------------------------------------- - -# The INPUT tag is used to specify the files and/or directories that contain -# documented source files. You may enter file names like myfile.cpp or -# directories like /usr/src/myproject. Separate the files or directories with -# spaces. -# Note: If this tag is empty the current directory is searched. - -INPUT = ../../include/boost/test \ - ../../include/boost/test/tree \ - ../../include/boost/test/tools \ - ../../include/boost/test/included \ - ../../include/boost/test/data \ - ../../include/boost/test/data/monomorphic \ - ../../include/boost/test/data/monomorphic/generators - -# This tag can be used to specify the character encoding of the source files -# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses -# libiconv (or the iconv built into libc) for the transcoding. See the libiconv -# documentation (see: http://www.gnu.org/software/libiconv) for the list of -# possible encodings. -# The default value is: UTF-8. - -INPUT_ENCODING = UTF-8 - -# If the value of the INPUT tag contains directories, you can use the -# FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and -# *.h) to filter out the source-files in the directories. If left blank the -# following patterns are tested:*.c, *.cc, *.cxx, *.cpp, *.c++, *.java, *.ii, -# *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, *.hh, *.hxx, *.hpp, -# *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, *.m, *.markdown, -# *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf, -# *.qsf, *.as and *.js. - -FILE_PATTERNS = - -# The RECURSIVE tag can be used to specify whether or not subdirectories should -# be searched for input files as well. -# The default value is: NO. - -RECURSIVE = NO - -# The EXCLUDE tag can be used to specify files and/or directories that should be -# excluded from the INPUT source files. This way you can easily exclude a -# subdirectory from a directory tree whose root is specified with the INPUT tag. -# -# Note that relative paths are relative to the directory from which doxygen is -# run. - -EXCLUDE = - -# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or -# directories that are symbolic links (a Unix file system feature) are excluded -# from the input. -# The default value is: NO. - -EXCLUDE_SYMLINKS = NO - -# If the value of the INPUT tag contains directories, you can use the -# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude -# certain files from those directories. -# -# Note that the wildcards are matched against the file with absolute path, so to -# exclude all test directories for example use the pattern */test/* - -EXCLUDE_PATTERNS = - -# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names -# (namespaces, classes, functions, etc.) that should be excluded from the -# output. The symbol name can be a fully qualified name, a word, or if the -# wildcard * is used, a substring. Examples: ANamespace, AClass, -# AClass::ANamespace, ANamespace::*Test -# -# Note that the wildcards are matched against the file with absolute path, so to -# exclude all test directories use the pattern */test/* - -EXCLUDE_SYMBOLS = - -# The EXAMPLE_PATH tag can be used to specify one or more files or directories -# that contain example code fragments that are included (see the \include -# command). - -EXAMPLE_PATH = - -# If the value of the EXAMPLE_PATH tag contains directories, you can use the -# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and -# *.h) to filter out the source-files in the directories. If left blank all -# files are included. - -EXAMPLE_PATTERNS = - -# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be -# searched for input files to be used with the \include or \dontinclude commands -# irrespective of the value of the RECURSIVE tag. -# The default value is: NO. - -EXAMPLE_RECURSIVE = NO - -# The IMAGE_PATH tag can be used to specify one or more files or directories -# that contain images that are to be included in the documentation (see the -# \image command). - -IMAGE_PATH = - -# The INPUT_FILTER tag can be used to specify a program that doxygen should -# invoke to filter for each input file. Doxygen will invoke the filter program -# by executing (via popen()) the command: -# -# -# -# where is the value of the INPUT_FILTER tag, and is the -# name of an input file. Doxygen will then use the output that the filter -# program writes to standard output. If FILTER_PATTERNS is specified, this tag -# will be ignored. -# -# Note that the filter must not add or remove lines; it is applied before the -# code is scanned, but not when the output code is generated. If lines are added -# or removed, the anchors will not be placed correctly. - -INPUT_FILTER = - -# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern -# basis. Doxygen will compare the file name with each pattern and apply the -# filter if there is a match. The filters are a list of the form: pattern=filter -# (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how -# filters are used. If the FILTER_PATTERNS tag is empty or if none of the -# patterns match the file name, INPUT_FILTER is applied. - -FILTER_PATTERNS = - -# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using -# INPUT_FILTER ) will also be used to filter the input files that are used for -# producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES). -# The default value is: NO. - -FILTER_SOURCE_FILES = NO - -# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file -# pattern. A pattern will override the setting for FILTER_PATTERN (if any) and -# it is also possible to disable source filtering for a specific pattern using -# *.ext= (so without naming a filter). -# This tag requires that the tag FILTER_SOURCE_FILES is set to YES. - -FILTER_SOURCE_PATTERNS = - -# If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that -# is part of the input, its contents will be placed on the main page -# (index.html). This can be useful if you have a project on for instance GitHub -# and want to reuse the introduction page also for the doxygen output. - -USE_MDFILE_AS_MAINPAGE = - -#--------------------------------------------------------------------------- -# Configuration options related to source browsing -#--------------------------------------------------------------------------- - -# If the SOURCE_BROWSER tag is set to YES then a list of source files will be -# generated. Documented entities will be cross-referenced with these sources. -# -# Note: To get rid of all source code in the generated output, make sure that -# also VERBATIM_HEADERS is set to NO. -# The default value is: NO. - -SOURCE_BROWSER = NO - -# Setting the INLINE_SOURCES tag to YES will include the body of functions, -# classes and enums directly into the documentation. -# The default value is: NO. - -INLINE_SOURCES = NO - -# Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any -# special comment blocks from generated source code fragments. Normal C, C++ and -# Fortran comments will always remain visible. -# The default value is: YES. - -STRIP_CODE_COMMENTS = YES - -# If the REFERENCED_BY_RELATION tag is set to YES then for each documented -# function all documented functions referencing it will be listed. -# The default value is: NO. - -REFERENCED_BY_RELATION = NO - -# If the REFERENCES_RELATION tag is set to YES then for each documented function -# all documented entities called/used by that function will be listed. -# The default value is: NO. - -REFERENCES_RELATION = NO - -# If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set -# to YES, then the hyperlinks from functions in REFERENCES_RELATION and -# REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will -# link to the documentation. -# The default value is: YES. - -REFERENCES_LINK_SOURCE = YES - -# If SOURCE_TOOLTIPS is enabled (the default) then hovering a hyperlink in the -# source code will show a tooltip with additional information such as prototype, -# brief description and links to the definition and documentation. Since this -# will make the HTML file larger and loading of large files a bit slower, you -# can opt to disable this feature. -# The default value is: YES. -# This tag requires that the tag SOURCE_BROWSER is set to YES. - -SOURCE_TOOLTIPS = YES - -# If the USE_HTAGS tag is set to YES then the references to source code will -# point to the HTML generated by the htags(1) tool instead of doxygen built-in -# source browser. The htags tool is part of GNU's global source tagging system -# (see http://www.gnu.org/software/global/global.html). You will need version -# 4.8.6 or higher. -# -# To use it do the following: -# - Install the latest version of global -# - Enable SOURCE_BROWSER and USE_HTAGS in the config file -# - Make sure the INPUT points to the root of the source tree -# - Run doxygen as normal -# -# Doxygen will invoke htags (and that will in turn invoke gtags), so these -# tools must be available from the command line (i.e. in the search path). -# -# The result: instead of the source browser generated by doxygen, the links to -# source code will now point to the output of htags. -# The default value is: NO. -# This tag requires that the tag SOURCE_BROWSER is set to YES. - -USE_HTAGS = NO - -# If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a -# verbatim copy of the header file for each class for which an include is -# specified. Set to NO to disable this. -# See also: Section \class. -# The default value is: YES. - -VERBATIM_HEADERS = YES - -# If the CLANG_ASSISTED_PARSING tag is set to YES, then doxygen will use the -# clang parser (see: http://clang.llvm.org/) for more accurate parsing at the -# cost of reduced performance. This can be particularly helpful with template -# rich C++ code for which doxygen's built-in parser lacks the necessary type -# information. -# Note: The availability of this option depends on whether or not doxygen was -# compiled with the --with-libclang option. -# The default value is: NO. - -CLANG_ASSISTED_PARSING = NO - -# If clang assisted parsing is enabled you can provide the compiler with command -# line options that you would normally use when invoking the compiler. Note that -# the include paths will already be set by doxygen for the files and directories -# specified with INPUT and INCLUDE_PATH. -# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. - -CLANG_OPTIONS = - -#--------------------------------------------------------------------------- -# Configuration options related to the alphabetical class index -#--------------------------------------------------------------------------- - -# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index of all -# compounds will be generated. Enable this if the project contains a lot of -# classes, structs, unions or interfaces. -# The default value is: YES. - -ALPHABETICAL_INDEX = YES - -# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in -# which the alphabetical index list will be split. -# Minimum value: 1, maximum value: 20, default value: 5. -# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. - -COLS_IN_ALPHA_INDEX = 5 - -# In case all classes in a project start with a common prefix, all classes will -# be put under the same header in the alphabetical index. The IGNORE_PREFIX tag -# can be used to specify a prefix (or a list of prefixes) that should be ignored -# while generating the index headers. -# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. - -IGNORE_PREFIX = - -#--------------------------------------------------------------------------- -# Configuration options related to the HTML output -#--------------------------------------------------------------------------- - -# If the GENERATE_HTML tag is set to YES doxygen will generate HTML output -# The default value is: YES. - -GENERATE_HTML = YES - -# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a -# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of -# it. -# The default directory is: html. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_OUTPUT = html - -# The HTML_FILE_EXTENSION tag can be used to specify the file extension for each -# generated HTML page (for example: .htm, .php, .asp). -# The default value is: .html. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_FILE_EXTENSION = .html - -# The HTML_HEADER tag can be used to specify a user-defined HTML header file for -# each generated HTML page. If the tag is left blank doxygen will generate a -# standard header. -# -# To get valid HTML the header file that includes any scripts and style sheets -# that doxygen needs, which is dependent on the configuration options used (e.g. -# the setting GENERATE_TREEVIEW). It is highly recommended to start with a -# default header using -# doxygen -w html new_header.html new_footer.html new_stylesheet.css -# YourConfigFile -# and then modify the file new_header.html. See also section "Doxygen usage" -# for information on how to generate the default header that doxygen normally -# uses. -# Note: The header is subject to change so you typically have to regenerate the -# default header when upgrading to a newer version of doxygen. For a description -# of the possible markers and block names see the documentation. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_HEADER = - -# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each -# generated HTML page. If the tag is left blank doxygen will generate a standard -# footer. See HTML_HEADER for more information on how to generate a default -# footer and what special commands can be used inside the footer. See also -# section "Doxygen usage" for information on how to generate the default footer -# that doxygen normally uses. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_FOOTER = - -# The HTML_STYLESHEET tag can be used to specify a user-defined cascading style -# sheet that is used by each HTML page. It can be used to fine-tune the look of -# the HTML output. If left blank doxygen will generate a default style sheet. -# See also section "Doxygen usage" for information on how to generate the style -# sheet that doxygen normally uses. -# Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as -# it is more robust and this tag (HTML_STYLESHEET) will in the future become -# obsolete. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_STYLESHEET = - -# The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined -# cascading style sheets that are included after the standard style sheets -# created by doxygen. Using this option one can overrule certain style aspects. -# This is preferred over using HTML_STYLESHEET since it does not replace the -# standard style sheet and is therefor more robust against future updates. -# Doxygen will copy the style sheet files to the output directory. -# Note: The order of the extra stylesheet files is of importance (e.g. the last -# stylesheet in the list overrules the setting of the previous ones in the -# list). For an example see the documentation. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_EXTRA_STYLESHEET = - -# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or -# other source files which should be copied to the HTML output directory. Note -# that these files will be copied to the base HTML output directory. Use the -# $relpath^ marker in the HTML_HEADER and/or HTML_FOOTER files to load these -# files. In the HTML_STYLESHEET file, use the file name only. Also note that the -# files will be copied as-is; there are no commands or markers available. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_EXTRA_FILES = - -# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen -# will adjust the colors in the stylesheet and background images according to -# this color. Hue is specified as an angle on a colorwheel, see -# http://en.wikipedia.org/wiki/Hue for more information. For instance the value -# 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 -# purple, and 360 is red again. -# Minimum value: 0, maximum value: 359, default value: 220. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_COLORSTYLE_HUE = 159 - -# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors -# in the HTML output. For a value of 0 the output will use grayscales only. A -# value of 255 will produce the most vivid colors. -# Minimum value: 0, maximum value: 255, default value: 100. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_COLORSTYLE_SAT = 100 - -# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the -# luminance component of the colors in the HTML output. Values below 100 -# gradually make the output lighter, whereas values above 100 make the output -# darker. The value divided by 100 is the actual gamma applied, so 80 represents -# a gamma of 0.8, The value 220 represents a gamma of 2.2, and 100 does not -# change the gamma. -# Minimum value: 40, maximum value: 240, default value: 80. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_COLORSTYLE_GAMMA = 140 - -# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML -# page will contain the date and time when the page was generated. Setting this -# to NO can help when comparing the output of multiple runs. -# The default value is: YES. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_TIMESTAMP = YES - -# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML -# documentation will contain sections that can be hidden and shown after the -# page has loaded. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_DYNAMIC_SECTIONS = NO - -# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries -# shown in the various tree structured indices initially; the user can expand -# and collapse entries dynamically later on. Doxygen will expand the tree to -# such a level that at most the specified number of entries are visible (unless -# a fully collapsed tree already exceeds this amount). So setting the number of -# entries 1 will produce a full collapsed tree by default. 0 is a special value -# representing an infinite number of entries and will result in a full expanded -# tree by default. -# Minimum value: 0, maximum value: 9999, default value: 100. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_INDEX_NUM_ENTRIES = 100 - -# If the GENERATE_DOCSET tag is set to YES, additional index files will be -# generated that can be used as input for Apple's Xcode 3 integrated development -# environment (see: http://developer.apple.com/tools/xcode/), introduced with -# OSX 10.5 (Leopard). To create a documentation set, doxygen will generate a -# Makefile in the HTML output directory. Running make will produce the docset in -# that directory and running make install will install the docset in -# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at -# startup. See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html -# for more information. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -GENERATE_DOCSET = NO - -# This tag determines the name of the docset feed. A documentation feed provides -# an umbrella under which multiple documentation sets from a single provider -# (such as a company or product suite) can be grouped. -# The default value is: Doxygen generated docs. -# This tag requires that the tag GENERATE_DOCSET is set to YES. - -DOCSET_FEEDNAME = "Doxygen generated docs" - -# This tag specifies a string that should uniquely identify the documentation -# set bundle. This should be a reverse domain-name style string, e.g. -# com.mycompany.MyDocSet. Doxygen will append .docset to the name. -# The default value is: org.doxygen.Project. -# This tag requires that the tag GENERATE_DOCSET is set to YES. - -DOCSET_BUNDLE_ID = org.doxygen.Project - -# The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify -# the documentation publisher. This should be a reverse domain-name style -# string, e.g. com.mycompany.MyDocSet.documentation. -# The default value is: org.doxygen.Publisher. -# This tag requires that the tag GENERATE_DOCSET is set to YES. - -DOCSET_PUBLISHER_ID = org.doxygen.Publisher - -# The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher. -# The default value is: Publisher. -# This tag requires that the tag GENERATE_DOCSET is set to YES. - -DOCSET_PUBLISHER_NAME = Publisher - -# If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three -# additional HTML index files: index.hhp, index.hhc, and index.hhk. The -# index.hhp is a project file that can be read by Microsoft's HTML Help Workshop -# (see: http://www.microsoft.com/en-us/download/details.aspx?id=21138) on -# Windows. -# -# The HTML Help Workshop contains a compiler that can convert all HTML output -# generated by doxygen into a single compiled HTML file (.chm). Compiled HTML -# files are now used as the Windows 98 help format, and will replace the old -# Windows help format (.hlp) on all Windows platforms in the future. Compressed -# HTML files also contain an index, a table of contents, and you can search for -# words in the documentation. The HTML workshop also contains a viewer for -# compressed HTML files. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -GENERATE_HTMLHELP = NO - -# The CHM_FILE tag can be used to specify the file name of the resulting .chm -# file. You can add a path in front of the file if the result should not be -# written to the html output directory. -# This tag requires that the tag GENERATE_HTMLHELP is set to YES. - -CHM_FILE = - -# The HHC_LOCATION tag can be used to specify the location (absolute path -# including file name) of the HTML help compiler ( hhc.exe). If non-empty -# doxygen will try to run the HTML help compiler on the generated index.hhp. -# The file has to be specified with full path. -# This tag requires that the tag GENERATE_HTMLHELP is set to YES. - -HHC_LOCATION = - -# The GENERATE_CHI flag controls if a separate .chi index file is generated ( -# YES) or that it should be included in the master .chm file ( NO). -# The default value is: NO. -# This tag requires that the tag GENERATE_HTMLHELP is set to YES. - -GENERATE_CHI = NO - -# The CHM_INDEX_ENCODING is used to encode HtmlHelp index ( hhk), content ( hhc) -# and project file content. -# This tag requires that the tag GENERATE_HTMLHELP is set to YES. - -CHM_INDEX_ENCODING = - -# The BINARY_TOC flag controls whether a binary table of contents is generated ( -# YES) or a normal table of contents ( NO) in the .chm file. Furthermore it -# enables the Previous and Next buttons. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTMLHELP is set to YES. - -BINARY_TOC = NO - -# The TOC_EXPAND flag can be set to YES to add extra items for group members to -# the table of contents of the HTML help documentation and to the tree view. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTMLHELP is set to YES. - -TOC_EXPAND = NO - -# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and -# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that -# can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help -# (.qch) of the generated HTML documentation. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -GENERATE_QHP = NO - -# If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify -# the file name of the resulting .qch file. The path specified is relative to -# the HTML output folder. -# This tag requires that the tag GENERATE_QHP is set to YES. - -QCH_FILE = - -# The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help -# Project output. For more information please see Qt Help Project / Namespace -# (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace). -# The default value is: org.doxygen.Project. -# This tag requires that the tag GENERATE_QHP is set to YES. - -QHP_NAMESPACE = org.doxygen.Project - -# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt -# Help Project output. For more information please see Qt Help Project / Virtual -# Folders (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#virtual- -# folders). -# The default value is: doc. -# This tag requires that the tag GENERATE_QHP is set to YES. - -QHP_VIRTUAL_FOLDER = doc - -# If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom -# filter to add. For more information please see Qt Help Project / Custom -# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- -# filters). -# This tag requires that the tag GENERATE_QHP is set to YES. - -QHP_CUST_FILTER_NAME = - -# The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the -# custom filter to add. For more information please see Qt Help Project / Custom -# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- -# filters). -# This tag requires that the tag GENERATE_QHP is set to YES. - -QHP_CUST_FILTER_ATTRS = - -# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this -# project's filter section matches. Qt Help Project / Filter Attributes (see: -# http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes). -# This tag requires that the tag GENERATE_QHP is set to YES. - -QHP_SECT_FILTER_ATTRS = - -# The QHG_LOCATION tag can be used to specify the location of Qt's -# qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the -# generated .qhp file. -# This tag requires that the tag GENERATE_QHP is set to YES. - -QHG_LOCATION = - -# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be -# generated, together with the HTML files, they form an Eclipse help plugin. To -# install this plugin and make it available under the help contents menu in -# Eclipse, the contents of the directory containing the HTML and XML files needs -# to be copied into the plugins directory of eclipse. The name of the directory -# within the plugins directory should be the same as the ECLIPSE_DOC_ID value. -# After copying Eclipse needs to be restarted before the help appears. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -GENERATE_ECLIPSEHELP = NO - -# A unique identifier for the Eclipse help plugin. When installing the plugin -# the directory name containing the HTML and XML files should also have this -# name. Each documentation set should have its own identifier. -# The default value is: org.doxygen.Project. -# This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES. - -ECLIPSE_DOC_ID = org.doxygen.Project - -# If you want full control over the layout of the generated HTML pages it might -# be necessary to disable the index and replace it with your own. The -# DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) at top -# of each HTML page. A value of NO enables the index and the value YES disables -# it. Since the tabs in the index contain the same information as the navigation -# tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -DISABLE_INDEX = NO - -# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index -# structure should be generated to display hierarchical information. If the tag -# value is set to YES, a side panel will be generated containing a tree-like -# index structure (just like the one that is generated for HTML Help). For this -# to work a browser that supports JavaScript, DHTML, CSS and frames is required -# (i.e. any modern browser). Windows users are probably better off using the -# HTML help feature. Via custom stylesheets (see HTML_EXTRA_STYLESHEET) one can -# further fine-tune the look of the index. As an example, the default style -# sheet generated by doxygen has an example that shows how to put an image at -# the root of the tree instead of the PROJECT_NAME. Since the tree basically has -# the same information as the tab index, you could consider setting -# DISABLE_INDEX to YES when enabling this option. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -GENERATE_TREEVIEW = NO - -# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that -# doxygen will group on one line in the generated HTML documentation. -# -# Note that a value of 0 will completely suppress the enum values from appearing -# in the overview section. -# Minimum value: 0, maximum value: 20, default value: 4. -# This tag requires that the tag GENERATE_HTML is set to YES. - -ENUM_VALUES_PER_LINE = 4 - -# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used -# to set the initial width (in pixels) of the frame in which the tree is shown. -# Minimum value: 0, maximum value: 1500, default value: 250. -# This tag requires that the tag GENERATE_HTML is set to YES. - -TREEVIEW_WIDTH = 250 - -# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open links to -# external symbols imported via tag files in a separate window. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -EXT_LINKS_IN_WINDOW = NO - -# Use this tag to change the font size of LaTeX formulas included as images in -# the HTML documentation. When you change the font size after a successful -# doxygen run you need to manually remove any form_*.png images from the HTML -# output directory to force them to be regenerated. -# Minimum value: 8, maximum value: 50, default value: 10. -# This tag requires that the tag GENERATE_HTML is set to YES. - -FORMULA_FONTSIZE = 10 - -# Use the FORMULA_TRANPARENT tag to determine whether or not the images -# generated for formulas are transparent PNGs. Transparent PNGs are not -# supported properly for IE 6.0, but are supported on all modern browsers. -# -# Note that when changing this option you need to delete any form_*.png files in -# the HTML output directory before the changes have effect. -# The default value is: YES. -# This tag requires that the tag GENERATE_HTML is set to YES. - -FORMULA_TRANSPARENT = YES - -# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see -# http://www.mathjax.org) which uses client side Javascript for the rendering -# instead of using prerendered bitmaps. Use this if you do not have LaTeX -# installed or if you want to formulas look prettier in the HTML output. When -# enabled you may also need to install MathJax separately and configure the path -# to it using the MATHJAX_RELPATH option. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -USE_MATHJAX = NO - -# When MathJax is enabled you can set the default output format to be used for -# the MathJax output. See the MathJax site (see: -# http://docs.mathjax.org/en/latest/output.html) for more details. -# Possible values are: HTML-CSS (which is slower, but has the best -# compatibility), NativeMML (i.e. MathML) and SVG. -# The default value is: HTML-CSS. -# This tag requires that the tag USE_MATHJAX is set to YES. - -MATHJAX_FORMAT = HTML-CSS - -# When MathJax is enabled you need to specify the location relative to the HTML -# output directory using the MATHJAX_RELPATH option. The destination directory -# should contain the MathJax.js script. For instance, if the mathjax directory -# is located at the same level as the HTML output directory, then -# MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax -# Content Delivery Network so you can quickly see the result without installing -# MathJax. However, it is strongly recommended to install a local copy of -# MathJax from http://www.mathjax.org before deployment. -# The default value is: http://cdn.mathjax.org/mathjax/latest. -# This tag requires that the tag USE_MATHJAX is set to YES. - -MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest - -# The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax -# extension names that should be enabled during MathJax rendering. For example -# MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols -# This tag requires that the tag USE_MATHJAX is set to YES. - -MATHJAX_EXTENSIONS = - -# The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces -# of code that will be used on startup of the MathJax code. See the MathJax site -# (see: http://docs.mathjax.org/en/latest/output.html) for more details. For an -# example see the documentation. -# This tag requires that the tag USE_MATHJAX is set to YES. - -MATHJAX_CODEFILE = - -# When the SEARCHENGINE tag is enabled doxygen will generate a search box for -# the HTML output. The underlying search engine uses javascript and DHTML and -# should work on any modern browser. Note that when using HTML help -# (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET) -# there is already a search function so this one should typically be disabled. -# For large projects the javascript based search engine can be slow, then -# enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to -# search using the keyboard; to jump to the search box use + S -# (what the is depends on the OS and browser, but it is typically -# , /