This class of target refer to a directory which contains files and directories generated by an external process.
An xdist target is a prime example of this type. It represents the final install location for a software package. Typically refered to as the installation prefix. Another example of this target type is xrepo, which can be used to hold remote sources.
This class of target are used in tandem with Repository Targets. Specific files and directories contained within Repository Targets must be exported and named within the Boost.Build environment to be useful.
An xfile target is main example. It represents a file, and will attempt to expose the file's type through standard Boost.Build means. Another important example is xinclude. It represents a directory within a repository that is intended to be part of include path for dependent targets. xsystem-include is like xinclude but will set compiler's system include path instead, which is useful for suppression of warnings from thirdparty included sources.
Repository Targets are also 'Project' targets in the Boost.Build system. This means that you can refer to Exports of Repository targets using Boost.Build's project reference syntax: project//target.
Example reference that resolves as a c file:
myrepo//path/file.c
If the type of reference is not automatically known by Boost.Build's type system, the target will be treated as an XRSRC target type, which is a viable source for XMODULE repository export targets such as xinclude, xfile, and xpath.
xinclude myinclude : myrepo//package-name/include ;
xfile myfile : myreop//package-name/src/file.txt ;
You can explicitly specify the type of a given reference with type@path syntax.
myrepo//configure@path/configure-script
Type from the value of type string is the first valid match in search pattern described in the following table.
| type | example |
|---|---|
| Boost.Build TYPE | H C OBJ LIB XCONFIGURE |
| Boost.Build main target rule | exe obj lib xconfigure |
| filename | configure CMakeLists.txt |
| file suffix | h c o |
XModule targets are build entirely within a directory inside the Boost.Build's build dir refered to as a workspace.
The workspace directory contains:
- xmodule respository target directories and the export targets within.
- log files of external build tools.
- intermediate files necessary for XModule's build rules to achieve their end goals.
If necessary, you can set the name of the workspace directory with a property using the xworkspace feature. By default, the workspace directory is formed from the target's name.
By default, boost.build will generate unique targets for each unique non-free feature value present in its properties. Typically you will see this manifested as directory names such as /release/link-static/ inside your project's build directories.
Generating different targets for different combinations of these properties often doesn't make sense when downloading and bulding external sources. To address this problem, XModule provides two features: xvariant and xinvariant.
The property value for these two features is a regex pattern that will be matched against the feature name of properties of the given workspace target. For example, exact match strings such as link match <link>static and <link>shared properties. A regex patterns such as .* matches all features and thus all properties. The regex pattern link|variant will match any properties of respective link and variant features.
-
<xinvariant> feature-regex
Any property with feature matched by feature-regex is removed and ignored by the workspace and its targets. This is useful when the actual target that you are building does not vary on the given feature. -
<xvariant> feature-regex
Any property with feature matched by feature-regex is not removed by the workspace and its targets. This only makes sense when used to override another <xinvariant> property, or a target's default xinvariant patterns.
XModule tries to configure the external source builds with the same toolset associated with the boost.build target (via the toolset and related toolset-* features. We call this toolset inheritance. The external toolset inherits the boost.build toolset. This is done to ensure that the libraries built with external tools use the same compiler and linker and any other possibly critical settings. XModule gives you full control over this inheritance behavior with the xtoolset-forfeit and xtoolset_inherit features. In addition to control of toolset inheritance, you can additionally specify toolset paramaters for the external toolset with the xtoolset-{subfeature} set of features.
| feature | subfeature | description |
|---|---|---|
| xtoolset-forfeit | regex of subfeatures to forfeit inheritance of | |
| xtoolset-inherit | regex of subfeatures to inherit. Override forfeit | |
| xtoolset-cc | cc | c compiler executable |
| xtoolset-cxx | cxx | c++ compiler executable |
| xtoolset-ar | ar | archiver executable |
| xtoolset-nm | nm | nm utility executable |
| xtoolset-ld | ld | linker executable |
| xtoolset-ranlib | ranlib | ranlib utility executable |
| xtoolset-cflags | cflags | flags passed to c compiler for c sources |
| xtoolset-cxxflags | cxxflags | flags passed to c++ compiler for c++ sources |
| xtoolset-linkflags | linkflags | flags passed to linker |
| toolset | name of associated Boost.Build toolset, can only be inherited | |
| version | version of associated Boost.Build toolset, can only be inherited |
Control of toolset inheritance is done at the subfeature level. An inherited subfeature is passed on to the external toolset. Subfeatures which are not inherited are left up to the external tools default action. By default, all subfeatures are inherited. To prevent inheritance of one or more subfeatures use properties with the xtoolset-forfeit feature. If you wish to ensure an xtoolset-subfeature is inherited and cannot be forfeited, use the xtoolset-inherit feature.
-
<xtoolset-forfeit> xtoolset-subfeature-regex
Matching xtoolset subfeatures are not inherited from the boost.build toolset associated with the target.
Regex patterns can be:- an exact match, such as:
ccorcxxflags - patterns such as
.*,.*flags, orar|nm|ranlib|.*flags
- an exact match, such as:
-
<xtoolset-inherit> toolset-subfeature-regex
Matching xtoolset subfeatures are inherited from the boost.build toolset associated with the target. Since inheritance is the default, this is only useful to override a corresponding property that has used the xtoolset_forfeit feature.
In addition to inheritance, you can specify subfeatures of external toolset explictly with xtoolset-{subfeature} features.
Any subfeature value set explictly will be combined with inherited values. This can be desired for subfeatures such as cxxflags, and not desired for subfeatures such as cxx. In undesired cases use the xtoolset-forfiet feature to prevent inheritance. Then only the explicit values you specify will be used.
In the test/xmodule/ directory there are many tests.
These tests are not intended to be examples of the preferred method or correct way to use XModule. They are simply meant to test all of the features. You should use syntax that is minimal, and easy to understand. Many of these tests break that goal in an attempt to test all of the corner cases. That said, these tests could be worthwhile looking through, especially if the documentation hasn't helped.
./test/xmodule/Jamfile
./test/xmodule/build-tests.jam
./test/xmodule/curl-tests.jam
./test/xmodule/download-tests.jam
./test/xmodule/mixed-lib.jam
./test/xmodule/project-tests.jam
./test/xmodule/regular-lib.jam
./test/xmodule/tar-tests.jam
./test/xmodule/xrsrc-piecewise-tests.jam
./test/xmodule/xrsrc-project-tests.jam