Skip to content

Latest commit

 

History

History
121 lines (80 loc) · 4.52 KB

b2.md

File metadata and controls

121 lines (80 loc) · 4.52 KB

XModule Reference: External Boost.Build

Build external Boost.Build sources with b2

Main target rules

  • xbuild
    When given a Jamfile source, b2 will build external sources. The target that this rule names is the directory and repository in which this build occurs.

  • xdist
    When given an XBUILD repository source generated from a Jamfile, Processes xpatch and xaction properties in the xdist repository directory. The target that this rule names is the directory and repository in which files are 'installed'.

    Aside from xpatch and xaction properties, this target is a placeholder for the directory. All building is done in the b2 XBUILD target actions.

Features

XBUILD

Control b2 build actions of the XBUILD derived type XB2_BUILD with properties based on these features:

  • <xbuild-arg> ARG
    ARG is passed to b2 plainly. When not set, b2 receives no argument, building default target(s).

  • <xbuild-jobs> N
    Passed to b2 with the -j flag.
    Defaults to a value proportional to invoked Boost.Build executable's -j value.

  • <xb2-build-dir-arg> prefix
    Combined with the absolute-path to the XBUILD repository location as a prefix and passed to b2.

  • <xb2-dist-arg> prefix
    Combined with the absolute-path to the XDIST repository location as a prefix and passed to b2.

  • <xb2-bootstrap> script
    Script to execute to bootstrap xb2-build process.

  • <xb2-bootstrap-build-dir-arg> prefix
    Combined with the absolute-path to the XBUILD repository location as a prefix and passed to the xb2-bootstrap script.

  • <xb2-bootstrap-dist-arg> prefix
    Combined with the absolute-path to the XDIST repository location as a prefix and passed to the xb2-bootstrap script.

  • <xb2-toolset-options> options
    Additional options in <feature>value property form for external Boost.Build toolset, in addition to those configured via xtoolset features.

XDIST

All processing is done for b2 XBUILD stage.

This target exists for access to, and processing on, installation or staging files.

  • <xdist-arg> arg
    Ignored. Use xbuild-arg.

  • <xdist-jobs> N
    Ignored. Use xbuild-jobs.

  • <xdist-location>
    Control location of 'xdist' directory. TODO: Document & Test

  • <xpatch> patch-file
    Patch files

  • <xaction> @action-or-rule Execute actions

XModule

  • <xworkspace>, and related features
    Control workspace of external build

XToolset

  • <xtoolset-subfeatures>
    Control the toolset used by external Boost.Build system.

    In this case of b2 based builds, the relevant xtoolset subfeatures are used to create a toolset-config.jam file:

    using $(TOOLSET) : $(TOOLSET_VERSION:E=) 
  : $(XTOOLSET_CXX:J= )
  : <archiver>"$(XTOOLSET_AR)" 
    <ranlib>"$(XTOOLSET_RANLIB)"
    <cflags>"$(XTOOLSET_CFLAGS)"
    <cxxflags>"$(XTOOLSET_CXXFLAGS)"
    <linkflags>"$(XTOOLSET_LINKFLAGS)"
    $(XB2_TOOLSET_OPTIONS)
  ;

    Upper-case variables are sourced from properties with matching feature names.

    toolset-config.jam is loaded via --user-config= argument to b2.

    By default, all configured toolset properties are inherited from the Boost.Build toolset associated with the target. If you are trying to set one or more of these properties instead of adding additional values, use the xtoolset-forfeit feature to prevent inheritance.

    If the toolset subfeature is not inherited, toolset-config.jam is not created, and default toolset will be used.

Notes

Workspace files

  • workspace/b2/toolset-config.jam
  • workspace/log/b2-bootstrap.log
  • workspace/log/b2-build.log

Serialization

XBUILD and XDIST actions execute in serial by using a JAM_SEMAPHORE. This mitigates CPU, memory and other resource utilization.

Boost.Build Type Reference

Type Base Type Infer from source file Generate from Notes
XJAMFILE *.jam
XJAMROOT Jamroot, Jamroot.jam
XUSER_JAMFILE Jamfile, Jamfile.jam
XB2_BUILD XBUILD XJAMROOT | XUSER_JAMFILE build and install/stage
XB2_DIST XDIST XB2_BUILD xpatch and xaction processing on xdist repository