123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899 |
- [/
- Boost.Config
- Copyright (c) 2001 Beman Dawes
- Copyright (c) 2001 Vesa Karvonen
- Copyright (c) 2001 John Maddock
- 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_config Build Time Configuration]
- There are times when you want to control whether a build target gets built or not, based
- on what features the compiler supports. For example, suppose you have a test file
- "test_constexpr_128.cpp" which requires three key features in order to build:
- * The `constexpr` keyword as detected by BOOST_NO_CXX11_CONSTEXPR.
- * User defined literals, as detected by BOOST_NO_CXX11_USER_DEFINED_LITERALS.
- * The `__int128` data type, as detected by BOOST_HAS_INT128.
- Clearly we know that if these features are not supported by the compiler, then
- there's simply no point in even trying to build the test program. The main advantages being:
- * Faster compile times - build configuration uses lightweight tests the results of which are also cached.
- * Less noise in build output - there's no reason to be faced with pages of template
- instantiation backtrace if we know the file can never compile anyway.
- * Less noise in the online test results - the test will show up as blank, rather than as a fail
- in the online test matrix.
- * A better experience for end users building all of Boost, if those libraries which can not be built
- for the current target compiler are simply skipped, rather than generating pages of error output.
- Returning to our example, the test case is probably executed in it's Jamfile via the "run" rule:
- run test_constexpr_128.cpp ;
- We now need to make this target conditional on the necessary features.
- We can do that by first importing the necessary rule at the start of the Jamfile:
- import path-to-config-lib/checks/config : requires ;
- Assuming that the test case is in the usual directory:
- libs/yourlib/test
- then the import rule will actually be:
- import ../../config/checks/config : requires ;
- Then add a "requires" rule invocation to the requirements section of the target:
- run test_constexpr_128.cpp
- : : : #requirements:
- [ requires cxx11_constexpr cxx11_user_defined_literals int128 ] ;
- Notice that multiple arguments can be added to the requires rule, and that these are
- always the same as the Boost.Config macro name, but in lower case and with the ['boost_no_]
- or ['boost_has_] prefix removed. You can also use any C++ standard feature-macro name
- with the leading underscores removed (see more below).
- When building the above example, you will see at the start of the build process the results
- of the configuration, for example GCC in C++11 mode gives:
- - Boost.Config Feature Check: int128 : yes
- - Boost.Config Feature Check: cxx11_constexpr : yes
- - Boost.Config Feature Check: cxx11_user_defined_literals : yes
- If you wish to make a build conditional on a C++ standard feature macro then you can specify
- these too, just remove the leading underscores from the name. For example:
- [ requires cpp_constexpr ]
- To require C++11 style const-expressions. If you want to specify a macro from a particular
- standard, then you append an underscore followed by the (2 digit) year of the standard, for example:
- [ requires cpp_constexpr_17 ]
- For C++17 constepxr. If you don't specify a standard then you get the first version that
- introduced the macro. In addition there are only standard-specific rules for each version
- bump of the macro, so:
- [ requires cpp_if_constexpr_17 ]
- Is fine since the macro was introduced in C++17 and is the same as the un-versioned name, but:
- [ requires cpp_if_constexpr_20 ]
- Will result in a build error since there is no C++20 version bump for `__cpp_if_constexpr`.
- That's all there is to this handy feature, should at any time you be unsure of the feature-test
- names you can pass to the "requires" rule, then search for the Boost.Config macro of interest in
- libs/config/checks/Jamfiles.v2, and the name of the feature check will follow it.
- And finally, this feature is built around the Boost.Build built in rule ['check-target-builds]
- which can be used to perform more generalized build-time feature testing. The checks in this
- library are provided as a convenient shorthand without the need for you to write the test cases yourself.
- [endsect]
|