diff --git a/doc/src/abstract-target.adoc b/doc/src/abstract-target.adoc index af99bd45cd..0ef0ffb978 100644 --- a/doc/src/abstract-target.adoc +++ b/doc/src/abstract-target.adoc @@ -1,4 +1,4 @@ -[[bbv2.reference.class.abstract-target]] +[[b2.reference.class.abstract-target]] = Class abstract-target Base class for all abstract targets. @@ -16,7 +16,7 @@ class abstract-target { ---- Classes derived from -link:#bbv2.reference.class.abstract-target[abstract-target]: +link:#b2.reference.class.abstract-target[abstract-target]: * project-target * main-target @@ -28,7 +28,7 @@ link:#bbv2.reference.class.abstract-target[abstract-target]: `name`:: The name of the target in the Jamfile. `project`:: - The link:#bbv2.reference.class.project-target[project] to which this + The link:#b2.reference.class.project-target[project] to which this target belongs. 2. `rule name ( )` @@ -37,7 +37,7 @@ Returns the name of this target. 3. `rule project ( )` + -Returns the link:#bbv2.reference.class.project-target[project] for this +Returns the link:#b2.reference.class.project-target[project] for this target. 4. `rule location ( )` @@ -48,7 +48,7 @@ Returns the location where the target was declared. + Returns a user-readable name for this target. -6. [[bbv2.reference.class.abstract-target.generate]] `rule generate ( property-set )` +6. [[b2.reference.class.abstract-target.generate]] `rule generate ( property-set )` + Generates virtual targets for this abstract target using the specified properties, unless a different value of some feature is required by the diff --git a/doc/src/architecture.adoc b/doc/src/architecture.adoc index 5fb9ddef9d..b84dc614d1 100644 --- a/doc/src/architecture.adoc +++ b/doc/src/architecture.adoc @@ -1,10 +1,10 @@ -[[bbv2.arch]] +[[b2.arch]] B2 v2 architecture --------------------------- This document is work-in progress. Do not expect much from it yet. -[[bbv2.arch.overview]] +[[b2.arch.overview]] Overview -------- @@ -18,7 +18,7 @@ functionality. It mostly allows declaring specific kinds of main targets, as well as registering available tools, which are then used when creating the dependency graph. -[[bbv2.arch.build]] +[[b2.arch.build]] The build layer --------------- @@ -55,7 +55,7 @@ instance, the `actualize` method is called to setup nodes and updating actions in the dependency graph kept inside B2 engine. This dependency graph is then updated, which runs necessary commands. -[[bbv2.arch.build.metatargets]] +[[b2.arch.build.metatargets]] Metatargets ~~~~~~~~~~~ @@ -106,7 +106,7 @@ to eliminate all such subclasses at the moment. Note that the `build/targets.jam` file contains an UML diagram which might help. -[[bbv2.arch.build.virtual]] +[[b2.arch.build.virtual]] Virtual targets ~~~~~~~~~~~~~~~ @@ -141,7 +141,7 @@ functionality is part of the "toolset" module. Note that the `build/virtual-targets.jam` file contains an UML diagram which might help. -[[bbv2.arch.build.properties]] +[[b2.arch.build.properties]] Properties ~~~~~~~~~~ @@ -154,13 +154,13 @@ caching for all operations, so most work is avoided. The `property-set.create` is the factory function used to create instances of the `property-set` class. -[[bbv2.arch.tools]] +[[b2.arch.tools]] The tools layer --------------- Write me! -[[bbv2.arch.targets]] +[[b2.arch.targets]] Targets ------- @@ -179,14 +179,14 @@ constructed from file targets. User has no way to create file targets but can specify rules for detecting source file types, as well as rules for transforming between file targets of different types. That information is used in constructing the final dependency graph, as -described in the link:#bbv2.arch.depends[next section]. **Note:**File +described in the link:#b2.arch.depends[next section]. **Note:**File targets are not the same entities as Jam targets; the latter are created from file targets at the latest possible moment. *Note:*"File target" is an originally proposed name for what we now call virtual targets. It is more understandable by users, but has one problem: virtual targets can potentially be "phony", and not correspond to any file. -[[bbv2.arch.depends]] +[[b2.arch.depends]] Dependency scanning ------------------- @@ -194,18 +194,18 @@ Dependency scanning is the process of finding implicit dependencies, like "#include" statements in {CPP}. The requirements for correct dependency scanning mechanism are: -* link:#bbv2.arch.depends.different-scanning-algorithms[Support for +* link:#b2.arch.depends.different-scanning-algorithms[Support for different scanning algorithms]. {CPP} and XML have quite different syntax for includes and rules for looking up the included files. -* link:#bbv2.arch.depends.same-file-different-scanners[Ability to scan +* link:#b2.arch.depends.same-file-different-scanners[Ability to scan the same file several times]. For example, a single {CPP} file may be compiled using different include paths. -* link:#bbv2.arch.depends.dependencies-on-generated-files[Proper +* link:#b2.arch.depends.dependencies-on-generated-files[Proper detection of dependencies on generated files.] -* link:#bbv2.arch.depends.dependencies-from-generated-files[Proper +* link:#b2.arch.depends.dependencies-from-generated-files[Proper detection of dependencies from a generated file.] -[[bbv2.arch.depends.different-scanning-algorithms]] +[[b2.arch.depends.different-scanning-algorithms]] Support for different scanning algorithms ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -213,7 +213,7 @@ Different scanning algorithm are encapsulated by objects called "scanners". Please see the "scanner" module documentation for more details. -[[bbv2.arch.depends.same-file-different-scanners]] +[[b2.arch.depends.same-file-different-scanners]] Ability to scan the same file several times ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -243,7 +243,7 @@ a.cpp (installed copy) <--(copy) ----------------------- a.cpp (no scanner) a.verbose --------------------------------+ .... -[[bbv2.arch.depends.dependencies-on-generated-files]] +[[b2.arch.depends.dependencies-on-generated-files]] Proper detection of dependencies on generated files. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -347,7 +347,7 @@ seem to be causing any problems in practice. For target types other than {CPP}, adding of include paths must be implemented anew. -[[bbv2.arch.depends.dependencies-from-generated-files]] +[[b2.arch.depends.dependencies-from-generated-files]] Proper detection of dependencies from generated files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -441,7 +441,7 @@ Types A file target can be given a type, which determines what transformations can be applied to the file. The `type.register` rule declares new types. File type can also be assigned a scanner, which is then used to find -implicit dependencies. See "link:#bbv2.arch.depends[dependency +implicit dependencies. See "link:#b2.arch.depends[dependency scanning]". Target paths diff --git a/doc/src/basic-target.adoc b/doc/src/basic-target.adoc index e5ffac54b3..7789ff2283 100644 --- a/doc/src/basic-target.adoc +++ b/doc/src/basic-target.adoc @@ -1,10 +1,10 @@ -[[bbv2.reference.class.basic-target]] +[[b2.reference.class.basic-target]] = Class basic-target [source] ---- class basic-target : abstract-target { - rule __init__ ( name : project : sources * : requirements * : default-build * : usage-requirements * ) + rule __init__ ( name : project : sources * : requirements * : default-build * : usage-requirements * ) rule generate ( property-set ) rule construct ( name : source-targets * : property-set ) @@ -26,15 +26,15 @@ and handles generation of those dependency targets. `name`:: The name of the target `project`:: - The link:#bbv2.reference.class.project-target[project] in which the + The link:#b2.reference.class.project-target[project] in which the target is declared. -2. [[bbv2.reference.class.basic-target.generate]] `rule generate ( property-set )` +2. [[b2.reference.class.basic-target.generate]] `rule generate ( property-set )` + Overrides -link:#bbv2.reference.class.abstract-target.generate[abstract-target.generate]. +link:#b2.reference.class.abstract-target.generate[abstract-target.generate]. Determines final build properties, generates sources, and calls -link:#bbv2.reference.class.basic-target.construct[construct]. This +link:#b2.reference.class.basic-target.construct[construct]. This method should not be overridden. + On success, returns: @@ -42,7 +42,7 @@ On success, returns: * a property-set with the usage requirements to be applied to dependents * a list of produced virtual targets, which may be empty. -3. [[bbv2.reference.class.basic-target.construct]] `rule construct ( name : source-targets * : property-set )` +3. [[b2.reference.class.basic-target.construct]] `rule construct ( name : source-targets * : property-set )` + Constructs virtual targets for this abstract target. Returns a usage-requirements property-set and a list of virtual targets. Should be diff --git a/doc/src/bjam.adoc b/doc/src/bjam.adoc index 451302a18c..3ff4a96abf 100644 --- a/doc/src/bjam.adoc +++ b/doc/src/bjam.adoc @@ -1,4 +1,4 @@ -[[bbv2.jam]] +[[b2.jam]] = Boost.Jam Documentation ____ diff --git a/doc/src/debug.adoc b/doc/src/debug.adoc index d2d46e2dc8..5b8fd32fd3 100644 --- a/doc/src/debug.adoc +++ b/doc/src/debug.adoc @@ -1,10 +1,10 @@ -[[bbv2.util]] +[[b2.util]] = Utilities -[[bbv2.util.debugger]] +[[b2.util.debugger]] == Debugger -[[bbv2.util.debugger.overview]] +[[b2.util.debugger.overview]] === Overview B2 comes with a debugger for Jamfiles. To run the debugger, @@ -21,7 +21,7 @@ Breakpoint 1, gcc.init ( ) at /usr/share/b2/tools/gcc.jam:74 (b2db) quit .... -[[bbv2.util.debugger.running]] +[[b2.util.debugger.running]] === Running the Program The `run` command is used to start a new `b2` subprocess for debugging. @@ -37,7 +37,7 @@ until the current function returns. The `kill` command terminates the current child immediately. -[[bbv2.util.debugger.break]] +[[b2.util.debugger.break]] === Breakpoints Breakpoints are set using the `break` command. The location of the @@ -73,7 +73,7 @@ Deleted breakpoint 1 (b2db) delete 2 .... -[[bbv2.util.debugger.stack]] +[[b2.util.debugger.stack]] === Examining the Stack The `backtrace` command will print a summary of every frame on the @@ -88,7 +88,7 @@ The `print` command can be used to show the value of an expression. Jamfile.jam .... -[[bbv2.util.debugger.misc]] +[[b2.util.debugger.misc]] === Miscellaneous Commands `quit` exits the debugger. `help` describes the available commands. diff --git a/doc/src/extending.adoc b/doc/src/extending.adoc index 3afea995c6..563d50bf76 100644 --- a/doc/src/extending.adoc +++ b/doc/src/extending.adoc @@ -1,13 +1,13 @@ -[[bbv2.extender]] +[[b2.extender]] = Extender Manual -[[bbv2.extender.intro]] +[[b2.extender.intro]] == Introduction This section explains how to extend B2 to accommodate your local requirements -- primarily to add support for non-standard tools you have. Before we start, be sure you have read and understood the concept -of metatarget, <>, which is critical to +of metatarget, <>, which is critical to understanding the remaining material. The current version of B2 has three levels of targets, listed @@ -31,24 +31,24 @@ WARNING: All of the Boost.Jam target-related builtin functions, like `DEPENDS` or `ALWAYS` operate on jam targets. Applying them to metatargets or concrete targets has no effect. -[[bbv2.extender.overview.metatargets]] +[[b2.extender.overview.metatargets]] === Metatargets Metatarget is an object that records information specified in Jamfile, such as metatarget kind, name, sources and properties, and can be called with specific properties to generate concrete targets. At the code level it is represented by an instance of class derived from -link:#bbv2.reference.class.abstract-target[abstract-target]. +link:#b2.reference.class.abstract-target[abstract-target]. footnote:[This name is historic, and will be eventually changed to `metatarget`] -The link:#bbv2.reference.class.abstract-target.generate[generate] method +The link:#b2.reference.class.abstract-target.generate[generate] method takes the build properties (as an instance of the -link:#bbv2.reference.class.property-set[property-set] class) and returns +link:#b2.reference.class.property-set[property-set] class) and returns a list containing: * As front element -- Usage-requirements from this invocation (an -instance of link:#bbv2.reference.class.property-set[property-set]) +instance of link:#b2.reference.class.property-set[property-set]) * As subsequent elements -- created concrete targets ( instances of the `virtual-target` class.) @@ -58,55 +58,55 @@ It's possible to lookup a metatarget by target-id using the `targets.generate-from-reference` function can both lookup and generate a metatarget. -The link:#bbv2.reference.class.abstract-target[abstract-target] class +The link:#b2.reference.class.abstract-target[abstract-target] class has three immediate derived classes: -* link:#bbv2.reference.class.project-target[project-target] that +* link:#b2.reference.class.project-target[project-target] that corresponds to a project and is not intended for further subclassing. -The link:#bbv2.reference.class.project-target.generate[generate] method +The link:#b2.reference.class.project-target.generate[generate] method of this class builds all targets in the project that are not marked as explicit. -* link:#bbv2.reference.class.main-target[main-target] corresponds to a +* link:#b2.reference.class.main-target[main-target] corresponds to a target in a project and contains one or more target alternatives. This class also should not be subclassed. The -link:#bbv2.reference.class.main-target.generate[generate] method of this +link:#b2.reference.class.main-target.generate[generate] method of this class selects an alternative to build, and calls the -link:#bbv2.reference.class.basic-target.generate[generate] method of +link:#b2.reference.class.basic-target.generate[generate] method of that alternative. -* link:#bbv2.reference.class.basic-target[basic-target] corresponds to a +* link:#b2.reference.class.basic-target[basic-target] corresponds to a specific target alternative. This is base class, with a number of derived classes. The -link:#bbv2.reference.class.basic-target.generate[generate] method +link:#b2.reference.class.basic-target.generate[generate] method processes the target requirements and requested build properties to determine final properties for the target, builds all sources, and finally calls the abstract -link:#bbv2.reference.class.basic-target.construct[construct] method with +link:#b2.reference.class.basic-target.construct[construct] method with the list of source virtual targets, and the final properties. The instances of the -link:#bbv2.reference.class.project-target[project-target] and -link:#bbv2.reference.class.main-target[main-target] classes are created +link:#b2.reference.class.project-target[project-target] and +link:#b2.reference.class.main-target[main-target] classes are created implicitly -- when loading a new Jamfiles, or when a new target alternative with as-yet unknown name is created. The instances of the classes derived from -link:#bbv2.reference.class.basic-target[basic-target] are typically +link:#b2.reference.class.basic-target[basic-target] are typically created when Jamfile calls a metatarget rule, such as such as `exe`. It it permissible to create a custom class derived from -link:#bbv2.reference.class.basic-target[basic-target] and create new +link:#b2.reference.class.basic-target[basic-target] and create new metatarget rule that creates instance of such target. However, in the majority of cases, a specific subclass of -link:#bbv2.reference.class.basic-target[basic-target] -- -link:#bbv2.reference.class.typed-target[typed-target] is used. That +link:#b2.reference.class.basic-target[basic-target] -- +link:#b2.reference.class.typed-target[typed-target] is used. That class is associated with a type and relays to generators to construct concrete targets of that type. This process will be explained below. When a new type is declared, a new metatarget rule is automatically defined. That rule creates new instance of type-target, associated with that type. -[[bbv2.extender.overview.targets]] +[[b2.extender.overview.targets]] === Concrete targets Concrete targets are represented by instance of classes derived from @@ -114,7 +114,7 @@ Concrete targets are represented by instance of classes derived from file target is associated with an action that creates it -- an instance of the `action` class. The action, in turn, hold a list of source targets. It also holds the -link:#bbv2.reference.class.property-set[property-set] instance with the +link:#b2.reference.class.property-set[property-set] instance with the build properties that should be used for the action. Here's an example of creating a target from another target, `source` @@ -127,7 +127,7 @@ local t = [ new file-target $(name) : CPP : $(project) : $(a) ] ; The first line creates an instance of the `action` class. The first parameter is the list of sources. The second parameter is the name a -jam-level link:#bbv2.overview.jam_language.actions[action]. The third +jam-level link:#b2.overview.jam_language.actions[action]. The third parameter is the property-set applying to this action. The second line creates a target. We specify a name, a type and a project. We also pass the action object created earlier. If the action creates several @@ -150,7 +150,7 @@ return [ virtual-target.register $(t) ] ; return [ sequence.transform virtual-target.register : $(targets) ] ; ---- -[[bbv2.extender.overview.generators]] +[[b2.extender.overview.generators]] === Generators In theory, every kind of metatarget in B2 (like `exe`, `lib` or @@ -164,12 +164,12 @@ In practice, most files have specific types, and most tools consume and produce files of specific type. To take advantage of this fact, B2 defines concept of target type and generators generators, and has special metatarget class -link:#bbv2.reference.class.typed-target[typed-target]. Target type is +link:#b2.reference.class.typed-target[typed-target]. Target type is merely an identifier. It is associated with a set of file extensions that correspond to that type. Generator is an abstraction of a tool. It advertises the types it produces and, if called with a set of input target, tries to construct output targets of the advertised types. -Finally, link:#bbv2.reference.class.typed-target[typed-target] is +Finally, link:#b2.reference.class.typed-target[typed-target] is associated with specific target type, and relays the generator (or generators) for that type. @@ -177,7 +177,7 @@ A generator is an instance of a class derived from `generator`. The `generator` class itself is suitable for common cases. You can define derived classes for custom scenarios. -[[bbv2.extender.example]] +[[b2.extender.example]] == Example: 1-to-1 generator Say you're writing an application that generates {CPP} code. If you ever @@ -209,7 +209,7 @@ type.register VERBATIM : verbatim ; ---- The first parameter to -link:#bbv2.reference.modules.type.register[type.register] gives the name +link:#b2.reference.modules.type.register[type.register] gives the name of the declared type. By convention, it's uppercase. The second parameter is the suffix for files of this type. So, if B2 sees `code.verbatim` in a list of sources, it knows that it's of type @@ -254,10 +254,10 @@ In subsequent sections, we will extend this example, and review all the mechanisms in detail. The complete code is available in the `example/customization` directory. -[[bbv2.extending.targets]] +[[b2.extending.targets]] == Target types -The first thing we did in the link:#bbv2.extender.intro[introduction] +The first thing we did in the link:#b2.extender.intro[introduction] was declaring a new target type: [source,jam] @@ -307,9 +307,9 @@ plugins to an application. A type can be defined as "main", in which case B2 will automatically declare a main target rule for building targets of that type. More details can be found -link:#bbv2.extending.rules.main-type[later]. +link:#b2.extending.rules.main-type[later]. -[[bbv2.extending.scanners]] +[[b2.extending.scanners]] == Scanners Sometimes, a file can refer to other files via some include system. To @@ -359,7 +359,7 @@ type.set-scanner VERBATIM : verbatim-scanner ; That's enough for scanning include dependencies. -[[bbv2.extending.tools]] +[[b2.extending.tools]] == Tools and generators This section will describe how B2 can be extended to support @@ -379,7 +379,7 @@ Each generator should be an instance of a class derived from the `generator` class. In the simplest case, you don't need to create a derived class, but simply create an instance of the `generator` class. Let's review the example we've seen in the -link:#bbv2.extender.intro[introduction]. +link:#b2.extender.intro[introduction]. [source,jam] ---- @@ -555,7 +555,7 @@ calling `generators.construct` and passing the {CPP} source and the libraries. At this point, we also change the extension's name, if necessary. -[[bbv2.extending.features]] +[[b2.extending.features]] == Features Often, we need to control the options passed the invoked tools. This is @@ -601,7 +601,7 @@ allow the user to pass any value to the command line parameters for a particular tool, if so desired. For example, the `` feature allows you to pass any command line options to a {CPP} compiler. The `` feature allows you to pass any string preceded by `-I` and -the interpretation is tool-specific. (See <> +the interpretation is tool-specific. (See <> for an example of very smart usage of that feature). Of course one should always strive to use portable features, but these are still be provided as a backdoor just to make sure B2 does not take away @@ -625,7 +625,7 @@ Adding a feature requires three steps: 1. Declaring a feature. For that, the "feature.feature" rule is used. You have to decide on the set of -link:#bbv2.reference.features.attributes[feature attributes]: +link:#b2.reference.features.attributes[feature attributes]: * if you want a feature value set for one target to automatically propagate to its dependent targets then make it “propagated”. * if a feature does not have a fixed list of values, it must be “free.” @@ -735,15 +735,15 @@ feature.compose fake : /mpi//fake/none ; This will allow you to specify the value of feature `parallelism`, which will expand to link to the necessary library. -[[bbv2.extending.rules]] +[[b2.extending.rules]] == Main target rules -A main target rule (e.g “link:#bbv2.tasks.programs[exe]” Or -“link:#bbv2.tasks.libraries[lib]”) creates a top-level target. It's +A main target rule (e.g “link:#b2.tasks.programs[exe]” Or +“link:#b2.tasks.libraries[lib]”) creates a top-level target. It's quite likely that you'll want to declare your own and there are two ways to do that. -[[bbv2.extending.rules.main-type]]The first way applies when your target rule +[[b2.extending.rules.main-type]]The first way applies when your target rule should just produce a target of specific type. In that case, a rule is already defined for you! When you define a new type, B2 automatically defines a corresponding @@ -797,7 +797,7 @@ type, the logic of building can be rather complicated. For example, the generator for that type. You can use that as example if your main target rule is non-trivial. -[[bbv2.extending.toolset_modules]] +[[b2.extending.toolset_modules]] == Toolset modules If your extensions will be used only on one project, they can be placed diff --git a/doc/src/faq.adoc b/doc/src/faq.adoc index 50a765fb6f..a687d8c285 100644 --- a/doc/src/faq.adoc +++ b/doc/src/faq.adoc @@ -1,7 +1,7 @@ -[[bbv2.faq]] +[[b2.faq]] = Frequently Asked Questions -[[bbv2.faq.featurevalue]] +[[b2.faq.featurevalue]] == How do I get the current value of feature in Jamfile? This is not possible, since Jamfile does not have "current" value of any @@ -17,12 +17,12 @@ A feature has a specific value only when building a target, and there are two ways you can use that value: * Use conditional requirements or indirect conditional requirements. See -link:#bbv2.overview.targets.requirements.conditional[the section called “Requirements”]. +link:#b2.overview.targets.requirements.conditional[the section called “Requirements”]. * Define a custom generator and a custom main target type. The custom generator can do arbitrary processing or properties. See the -link:#bbv2.extender[extender manual] +link:#b2.extender[extender manual] -[[bbv2.faq.duplicate]] +[[b2.faq.duplicate]] == I am getting a "Duplicate name of actual target" error. What does that mean? The most likely case is that you are trying to compile the same file @@ -108,13 +108,13 @@ in half of the cases, while in the other half it would be silently doing the wrong thing. It is simpler and safer to ask the user to clarify his intention in such cases. -[[bbv2.faq.envar]] +[[b2.faq.envar]] == Accessing environment variables Many users would like to use environment variables in Jamfiles, for example, to control the location of external libraries. In many cases it is better to declare those external libraries in the site-config.jam -file, as documented in the link:#bbv2.recipes.site-config[recipes +file, as documented in the link:#b2.recipes.site-config[recipes section]. However, if the users already have the environment variables set up, it may not be convenient for them to set up their site-config.jam files as well and using the environment variables might @@ -140,7 +140,7 @@ local SOME_LIBRARY_PATH = [ os.environ SOME_LIBRARY_PATH ] ; exe a : a.cpp : $(SOME_LIBRARY_PATH) ; ---- -[[bbv2.faq.proporder]] +[[b2.faq.proporder]] == How to control properties order? For internal reasons, B2 sorts all the properties @@ -167,7 +167,7 @@ should be preserved. You are advised to use this feature only when the order of properties really matters and not as a convenient shortcut. Using it everywhere might negatively affect performance. -[[bbv2.faq.liborder]] +[[b2.faq.liborder]] == How to control the library linking order on Unix? On Unix-like operating systems, the order in which static libraries are @@ -200,7 +200,7 @@ lib png : : z ; exe viewer : viewer png z ; ---- -[[bbv2.faq.external]] +[[b2.faq.external]] == Can I get capture external program output using a Boost.Jam variable? The `SHELL` builtin rule may be used for this purpose: @@ -210,7 +210,7 @@ The `SHELL` builtin rule may be used for this purpose: local gtk_includes = [ SHELL "gtk-config --cflags" ] ; ---- -[[bbv2.faq.projectroot]] +[[b2.faq.projectroot]] == How to get the project root (a.k.a. Jamroot) location? You might want to use your project's root location in your Jamfiles. To @@ -223,7 +223,7 @@ path-constant TOP : . ; After that, the `TOP` variable can be used in every Jamfile. -[[bbv2.faq.flags]] +[[b2.faq.flags]] == How to change compilation flags for one file? If one file must be compiled with special options, you need to @@ -245,7 +245,7 @@ exe a : a.cpp b ; obj b : b.cpp : -g ; ---- -You can also use link:#bbv2.tutorial.conditions[conditional properties] +You can also use link:#b2.tutorial.conditions[conditional properties] for finer control: [source,jam] @@ -254,8 +254,8 @@ exe a : a.cpp b ; obj b : b.cpp : release:off ; ---- -[[bbv2.faq.dll-path]] -== Why are the link:#bbv2.builtin.features.dll-path[`dll-path`] and link:#bbv2.builtin.features.hardcode-dll-paths[`hardcode-dll-paths`] properties useful? +[[b2.faq.dll-path]] +== Why are the link:#b2.builtin.features.dll-path[`dll-path`] and link:#b2.builtin.features.hardcode-dll-paths[`hardcode-dll-paths`] properties useful? NOTE: This entry is specific to Unix systems. @@ -275,8 +275,8 @@ system location. This can be inconvenient when developing, since the libraries are not yet ready to be installed, and cluttering system paths may be undesirable. Luckily, on Unix there is another way. -Using the link:#bbv2.builtin.features.hardcode-dll-paths[`hardcode-dll-paths`] -and link:#bbv2.builtin.features.dll-path[`dll-path`] features, +Using the link:#b2.builtin.features.hardcode-dll-paths[`hardcode-dll-paths`] +and link:#b2.builtin.features.dll-path[`dll-path`] features, a target can be linked with an additional list of library directory paths that will be searched before the system paths -- these are called "_runtime library search paths_" or "_run paths_", or @@ -287,21 +287,21 @@ https://en.wikipedia.org/wiki/Rpath[Wikipedia] for more. NOTE: We'll just use _rpath list_ for conciseness below. === `hardcode-dll-paths` -The link:#bbv2.builtin.features.hardcode-dll-paths[`hardcode-dll-paths`] -feature for link:#bbv2.reference.rules.exe[`exe`] targets, is especially +The link:#b2.builtin.features.hardcode-dll-paths[`hardcode-dll-paths`] +feature for link:#b2.reference.rules.exe[`exe`] targets, is especially helpful for development; As the build system already knows the paths to all the used shared libraries, it will by default automatically add them to the executable _rpath list_. When the executable is installed however, the story is different; Obviously, installed executables should not contain hardcoded paths to -your development tree. The link:#bbv2.reference.rules.install[`install`] +your development tree. The link:#b2.reference.rules.install[`install`] rule therefore implicitly (i.e. by default) negates the -link:#bbv2.builtin.features.hardcode-dll-paths[`hardcode-dll-paths`] +link:#b2.builtin.features.hardcode-dll-paths[`hardcode-dll-paths`] feature, by re-linking an executable _without_ the automatic paths if necessary. - - For the link:#bbv2.reference.rules.exe[`exe`] rule: + - For the link:#b2.reference.rules.exe[`exe`] rule: * With `true` (default), the paths to all directories with used shared libraries are _automatically_ added to the target's _rpath list_. @@ -310,11 +310,11 @@ if necessary. _disable_ the automatic adding of directory paths to the shared libraries. - - For the link:#bbv2.reference.rules.install[`install`] rule: + - For the link:#b2.reference.rules.install[`install`] rule: * If so desired, an explicit `true` is needed to propagate the _rpath list_, added to the source targets, through to the `install` targets. (This include explicit - link:#bbv2.builtin.features.dll-path[`dll-path`] entries added + link:#b2.builtin.features.dll-path[`dll-path`] entries added to the source targets.) * By default, the implicit `false` property, @@ -322,11 +322,11 @@ if necessary. propagated through to the `install` targets. - The `` feature is ignored for the - link:#bbv2.reference.rules.lib[`lib`] rule. + link:#b2.reference.rules.lib[`lib`] rule. === `dll-path` As an alternative -- or in addition -- you can use the -link:#bbv2.builtin.features.dll-path[`dll-path`] feature to add explicit +link:#b2.builtin.features.dll-path[`dll-path`] feature to add explicit directory paths manually to the _rpath list_. + For example: @@ -376,7 +376,7 @@ that they should always be used. |`hardcode-dll-paths` |`true` |Propagate _rpath list_ from the sources (`exe` & `lib` targets) to the installed binary. (This include explicit - link:#bbv2.builtin.features.dll-path[`dll-path`] + link:#b2.builtin.features.dll-path[`dll-path`] entries added to the source targets.) |`install` @@ -403,7 +403,7 @@ that they should always be used. command line invocation, thus severely limited in practical use. |=== -[[bbv2.recipes.site-config]] +[[b2.recipes.site-config]] == Targets in site-config.jam It is desirable to declare standard libraries available on a given @@ -430,7 +430,7 @@ exe hello : hello.cpp /site-config//zlib ; in any Jamfile. -[[bbv2.faq.header-only-libraries]] +[[b2.faq.header-only-libraries]] == Header-only libraries In modern {CPP}, libraries often consist of just header files, without any @@ -470,7 +470,7 @@ project my : usage-requirements whatever ; alias mylib ; ---- -[[bbv2.faq.names]] +[[b2.faq.names]] == What is the difference between B2, `b2`, `bjam` and Perforce Jam? B2 is the name of the complete build system. The executable diff --git a/doc/src/history.adoc b/doc/src/history.adoc index aa34895ed1..25632a8c55 100644 --- a/doc/src/history.adoc +++ b/doc/src/history.adoc @@ -8,6 +8,18 @@ * Fix asciidoctor ignoring relevant features when building which caused invalid reuse of the target. -- _René Ferdinand Rivera Morell_ +* Add documentation for clang and emscripten toolsets. + -- _Nikita Kniazev_ +* Fix doxygen tool to properly handle paths relative to the wording dir or + absolute paths. + -- _Dmitry Arkhipov_ +* Fix staging path calculation when using install prefix's. + -- _Dmitry Arkhipov_ +* Make `toolset.using` preserve current project to allow for calling it in more + contexts with minimal effort. + -- _Dmitry Arkhipov_ +* Updated cxxstd=latest for gcc and clang to account for {CPP} 26. + -- _Andrey Semashev_ == Version 5.2.1 diff --git a/doc/src/howto.adoc b/doc/src/howto.adoc index 88918187c0..2b578e9757 100644 --- a/doc/src/howto.adoc +++ b/doc/src/howto.adoc @@ -1,13 +1,13 @@ Want to learn about B2 features? Start with the -link:#bbv2.tutorial[tutorial] and continue with the link:#bbv2.overview[overview]. +link:#b2.tutorial[tutorial] and continue with the link:#b2.overview[overview]. When you're ready to try B2 in practice, go to the -link:#bbv2.installation[installation]. +link:#b2.installation[installation]. -Building a project with B2? See the link:#bbv2.installation[installation] -and then read the link:#bbv2.overview.invocation[overview]. +Building a project with B2? See the link:#b2.installation[installation] +and then read the link:#b2.overview.invocation[overview]. Setting up B2 on your project? Take a look at the -link:#bbv2.overview[overview] and link:#bbv2.extender[extender manual]. +link:#b2.overview[overview] and link:#b2.extender[extender manual]. If there's anything you find unclear in this documentation, report the problem directly in the https://github.com/bfgroup/b2/issues[issue diff --git a/doc/src/install.adoc b/doc/src/install.adoc index 28955597da..b97a4cc348 100644 --- a/doc/src/install.adoc +++ b/doc/src/install.adoc @@ -1,4 +1,4 @@ -[[bbv2.installation]] +[[b2.installation]] = Installation To install B2 from an official release, as available on diff --git a/doc/src/main-target.adoc b/doc/src/main-target.adoc index 7d0e63818d..f5004fa8f7 100644 --- a/doc/src/main-target.adoc +++ b/doc/src/main-target.adoc @@ -1,4 +1,4 @@ -[[bbv2.reference.class.main-target]] +[[b2.reference.class.main-target]] = Class main-target [source,jam] @@ -14,18 +14,18 @@ class main-target : abstract-target { } ---- -A link:#bbv2.reference.class.main-target[main-target] represents a named +A link:#b2.reference.class.main-target[main-target] represents a named top-level target in a Jamfile. -- -1. [[bbv2.reference.class.main-target.generate]] `rule generate ( property-set )` +1. [[b2.reference.class.main-target.generate]] `rule generate ( property-set )` + Overrides -link:#bbv2.reference.class.abstract-target.generate[abstract-target.generate]. +link:#b2.reference.class.abstract-target.generate[abstract-target.generate]. Select an alternative for this main target, by finding all alternatives whose requirements are satisfied by `property-set` and picking the one with the longest requirements set. Returns the result of calling -link:#bbv2.reference.class.basic-target.generate[generate] on that +link:#b2.reference.class.basic-target.generate[generate] on that alternative. + On success, returns: diff --git a/doc/src/overview.adoc b/doc/src/overview.adoc index cee21409c4..86026d81b4 100644 --- a/doc/src/overview.adoc +++ b/doc/src/overview.adoc @@ -1,11 +1,11 @@ -[[bbv2.overview]] +[[b2.overview]] = Overview This section will provide the information necessary to create your own projects using B2. The information provided here is relatively -high-level, and the link:#bbv2.reference[Reference] as well as the on-line +high-level, and the link:#b2.reference[Reference] as well as the on-line help system must be used to obtain low-level documentation (see -link:#bbv2.overview.invocation.options.help[`--help`]). +link:#b2.overview.invocation.options.help[`--help`]). B2 has two parts — a build engine with its own interpreted language, and B2 itself, implemented in that language. The @@ -13,7 +13,7 @@ chain of events when you type `b2` on the command line is as follows: 1. The B2 executable tries to find B2 modules and loads the top-level module. The exact process is described in -link:#bbv2.reference.init[the section called “Initialization”] +link:#b2.reference.init[the section called “Initialization”] 2. The top-level module loads user-defined configuration files, `user-config.jam` and `site-config.jam`, which define available toolsets. @@ -28,13 +28,13 @@ running the scheduled build action commands. So, to be able to successfully use B2, you need to know only four things: -* link:#bbv2.overview.configuration[How to configure B2] -* link:#bbv2.overview.targets[How to declare targets in Jamfiles] -* link:#bbv2.overview.build_process[How the build process works] +* link:#b2.overview.configuration[How to configure B2] +* link:#b2.overview.targets[How to declare targets in Jamfiles] +* link:#b2.overview.build_process[How the build process works] * Some Basics about the Boost.Jam language. See -link:#bbv2.overview.jam_language[the section called “Boost.Jam Language”]. +link:#b2.overview.jam_language[the section called “Boost.Jam Language”]. -[[bbv2.overview.concepts]] +[[b2.overview.concepts]] == Concepts B2 has a few unique concepts that are introduced in this @@ -115,7 +115,7 @@ same properties. Instead, the "top-level" metatargets are called with the properties specified on the command line. Each metatarget can elect to augment or override some properties (in particular, using the requirements mechanism, see -link:#bbv2.overview.targets.requirements[the section called “Requirements”]). +link:#b2.overview.targets.requirements[the section called “Requirements”]). Then, the dependency metatargets are called with the modified properties and produce concrete targets that are then used in the build process. Of course, dependency metatargets maybe in turn modify build properties and @@ -125,23 +125,23 @@ For a more in-depth treatment of the requirements and concepts, you may refer to http://syrcose.ispras.ru/2009/files/04_paper.pdf[SYRCoSE 2009 B2 article]. -[[bbv2.overview.jam_language]] +[[b2.overview.jam_language]] == Boost.Jam Language This section will describe the basics of the Boost.Jam language—just enough for writing Jamfiles. For more information, please see the -link:#bbv2.jam[Boost.Jam] documentation. +link:#b2.jam[Boost.Jam] documentation. -link:#bbv2.jam[Boost.Jam] has an interpreted, procedural language. On -the lowest level, a link:#bbv2.jam[Boost.Jam] program consists of +link:#b2.jam[Boost.Jam] has an interpreted, procedural language. On +the lowest level, a link:#b2.jam[Boost.Jam] program consists of variables and _rules_ (the Jam term for functions). They are grouped into modules—there is one global module and a number of named modules. -Besides that, a link:#bbv2.jam[Boost.Jam] program contains classes and +Besides that, a link:#b2.jam[Boost.Jam] program contains classes and class instances. -Syntactically, a link:#bbv2.jam[Boost.Jam] program consists of two kinds +Syntactically, a link:#b2.jam[Boost.Jam] program consists of two kinds of elements—keywords (which have a special meaning to -link:#bbv2.jam[Boost.Jam]) and literals. Consider this code: +link:#b2.jam[Boost.Jam]) and literals. Consider this code: [source] ---- @@ -163,7 +163,7 @@ value can be quoted: a = "=" ; ---- -All variables in link:#bbv2.jam[Boost.Jam] have the same type—list of +All variables in link:#b2.jam[Boost.Jam] have the same type—list of strings. To define a variable one assigns a value to it, like in the previous example. An undefined variable is the same as a variable with an empty value. Variables can be accessed using the `$(variable)` @@ -196,7 +196,7 @@ have exactly one value. The list passed as the second argument can either have one value of be empty. The two remaining arguments can be arbitrarily long, but the third argument may not be empty. -The overview of link:#bbv2.jam[Boost.Jam] language statements is given +The overview of link:#b2.jam[Boost.Jam] language statements is given below: [source] @@ -257,7 +257,7 @@ are made available using the qualified name: `module.rule`. The second form imports the specified rules only, and they can be called using unqualified names. -[[bbv2.overview.jam_language.actions]] +[[b2.overview.jam_language.actions]] Sometimes, you need to specify the actual command lines to be used when creating targets. In the jam language, you use named actions to do this. For example: @@ -304,7 +304,7 @@ actions would be impossible. More details can be found in the Jam reference, link:#jam.language.rules[the section called “Rules”]. -[[bbv2.overview.configuration]] +[[b2.overview.configuration]] == Configuration On startup, B2 searches and reads three configuration files: @@ -367,13 +367,13 @@ searched. |=== Any of these files may also be overridden -link:#bbv2.reference.init.options.config[on the command line]. +link:#b2.reference.init.options.config[on the command line]. TIP: You can use the `--debug-configuration` option to find which configuration files are actually loaded. Usually, `user-config.jam` just defines the available compilers and -other tools (see link:#bbv2.recipes.site-config[the section called “Targets +other tools (see link:#b2.recipes.site-config[the section called “Targets in site-config.jam”] for more advanced usage). A tool is configured using the following syntax: @@ -399,7 +399,7 @@ The general principle is that descriptions in Jamfile should be maintained as portable while configuration files are system specific. All the supported tools are documented in -link:#bbv2.reference.tools[the section called “Builtin tools”], including the +link:#b2.reference.tools[the section called “Builtin tools”], including the specific options they take. Some general notes that apply to most {CPP} compilers are below. @@ -511,7 +511,7 @@ to syntax used to specify requirements in Jamfiles, the toolset options are not the same as features. Don't try to specify a feature value in toolset initialization. -[[bbv2.overview.invocation]] +[[b2.overview.invocation]] == Invocation To invoke B2, type `b2` on the command line. Three kinds of @@ -530,7 +530,7 @@ target:: targets to build. The available targets entirely depend on the project you are building. -[[bbv2.overview.invocation.examples]] +[[b2.overview.invocation.examples]] === Examples To build all targets defined in the Jamfile in the current directory @@ -556,12 +556,12 @@ command line: b2 toolset=gcc variant=debug optimization=space ---- -[[bbv2.overview.invocation.options]] +[[b2.overview.invocation.options]] === Options B2 recognizes the following command line options. -[[bbv2.overview.invocation.options.help]]`--help`:: +[[b2.overview.invocation.options.help]]`--help`:: Invokes the online help system. This prints general information on how to use the help system with additional --help* options. `--clean`:: @@ -584,14 +584,14 @@ B2 recognizes the following command line options. `--abbreviate-paths`:: Compresses target paths by abbreviating each component. This option is useful to keep paths from becoming longer than the filesystem - supports. See also link:#bbv2.reference.buildprocess.targetpath[the + supports. See also link:#b2.reference.buildprocess.targetpath[the section called “Target Paths”]. `--hash`:: Compresses target paths using an MD5 hash. This option is useful to keep paths from becoming longer than the filesystem supports. This option produces shorter paths than `--abbreviate-paths` does, but at the cost of making them less understandable. See also - link:#bbv2.reference.buildprocess.targetpath[the section called “Target + link:#b2.reference.buildprocess.targetpath[the section called “Target Paths”]. `--version`:: Prints information on the B2 and Boost.Jam versions. @@ -607,14 +607,14 @@ B2 recognizes the following command line options. of detected available CPU threads. Note: There are circumstances when that default can be larger than the allocated cpu resources, for instance in some virtualized container installs. -`--config=filename`[[bbv2.reference.init.options.config]]:: - Override all link:#bbv2.overview.configuration[configuration files] +`--config=filename`[[b2.reference.init.options.config]]:: + Override all link:#b2.overview.configuration[configuration files] `--site-config=filename`:: - Override the default link:#bbv2.overview.configuration[site-config.jam] + Override the default link:#b2.overview.configuration[site-config.jam] `--user-config=filename`:: - Override the default link:#bbv2.overview.configuration[user-config.jam] + Override the default link:#b2.overview.configuration[user-config.jam] `--project-config=filename`:: - Override the default link:#bbv2.overview.configuration[project-config.jam] + Override the default link:#b2.overview.configuration[project-config.jam] `--debug-configuration`:: Produces debug information about the loading of B2 and toolset files. @@ -658,13 +658,13 @@ B2 recognizes the following command line options. `--command-database-out=_file_`:: Specify the _file_ path to output the commands database to. -[[bbv2.overview.invocation.properties]] +[[b2.overview.invocation.properties]] === Properties In the simplest case, the build is performed with a single set of properties, that you specify on the command line with elements in the form `feature=value`. The complete list of features can be found in -link:#bbv2.overview.builtins.features[the section called “Builtin features”]. +link:#b2.overview.builtins.features[the section called “Builtin features”]. The most common features are summarized below. [cols=",,a",options="header"] @@ -688,15 +688,13 @@ in the source code itself. |32,64 |Explicitly request either 32-bit or 64-bit code generation. This typically requires that your compiler is appropriately -configured. Please refer to -link:#bbv2.reference.tools.compilers[the section called “C++ Compilers”] -and your compiler documentation in case of problems. +configured. Please refer to <> and your +compiler documentation in case of problems. |toolset |(Depends on configuration) -|The {CPP} compiler to use. See -link:#bbv2.reference.tools.compilers[the section called “C++ Compilers”] -for a detailed list. +|The {CPP} compiler to use. See <> for a +detailed list. |include |(Arbitrary string) @@ -767,26 +765,26 @@ b2 gcc/link=shared msvc/link=static,shared This will build 3 different variants, altogether. -[[bbv2.overview.invocation.targets]] +[[b2.overview.invocation.targets]] === Targets All command line elements that are neither options nor properties are -the names of the targets to build. See link:#bbv2.reference.ids[the section +the names of the targets to build. See link:#b2.reference.ids[the section called “Target identifiers and references”]. If no target is specified, the project in the current directory is built. -[[bbv2.overview.targets]] +[[b2.overview.targets]] == Declaring Targets -[[bbv2.overview.targets.main]] +[[b2.overview.targets.main]] A Main target is a user-defined named entity that can be built, for example an executable file. Declaring a main target is usually done using one of the main target rules described in -link:#bbv2.reference.rules[the section called “Builtin rules”]. The user can +link:#b2.reference.rules[the section called “Builtin rules”]. The user can also declare custom main target rules as shown in -link:#bbv2.extending.rules[the section called “Main target rules”]. +link:#b2.extending.rules[the section called “Main target rules”]. -anchor:bbv2.main-target-rule-syntax[] +anchor:b2.main-target-rule-syntax[] Most main target rules in B2 have the same common signature: [source] @@ -820,7 +818,7 @@ The actual requirements for a target are obtained by refining the requirements of the project where the target is declared with the explicitly specified requirements. The same is true for usage-requirements. More details can be found in -link:#bbv2.reference.variants.proprefine[the section called “Property refinement”]. +link:#b2.reference.variants.proprefine[the section called “Property refinement”]. === Name @@ -850,7 +848,7 @@ The list of sources specifies what should be processed to get the resulting targets. Most of the time, it's just a list of files. Sometimes, you'll want to automatically construct the list of source files rather than having to spell it out manually, in which case you can -use the link:#bbv2.reference.rules.glob[glob] rule. Here are two +use the link:#b2.reference.rules.glob[glob] rule. Here are two examples: [source] @@ -864,7 +862,7 @@ exe b : [ glob *.cpp ] ; <2> Unless you specify a file with an absolute path, the name is considered relative to the source directory — which is typically the directory where the Jamfile is located, but can be changed as described in -link:#bbv2.overview.projects.attributes.projectrule[the section called “Projects”]. +link:#b2.overview.projects.attributes.projectrule[the section called “Projects”]. The list of sources can also refer to other main targets. Targets in the same project can be referred to by name, while targets in other projects @@ -888,10 +886,10 @@ one uses some target (most likely a library) defined by a Jamfile one level higher. Finally, the third target uses a http://boost.org[{CPP} Boost] library, referring to it using its absolute symbolic name. More information about target references can be found in -link:#bbv2.tutorial.libs[the section called “Dependent Targets”] and -link:#bbv2.reference.ids[the section called “Target identifiers and references”]. +link:#b2.tutorial.libs[the section called “Dependent Targets”] and +link:#b2.reference.ids[the section called “Target identifiers and references”]. -[[bbv2.overview.targets.requirements]] +[[b2.overview.targets.requirements]] === Requirements Requirements are the properties that should always be present when @@ -903,7 +901,7 @@ exe hello : hello.cpp : /opt/boost MY_DEBUG ; ---- There are a number of other features, listed in -link:#bbv2.overview.builtins.features[the section called “Builtin features”]. +link:#b2.overview.builtins.features[the section called “Builtin features”]. For example if a library can only be built statically, or a file can't be compiled with optimization due to a compiler bug, one can use. @@ -913,7 +911,7 @@ lib util : util.cpp : static ; obj main : main.cpp : off ; ---- -[[bbv2.overview.targets.requirements.conditional]]Sometimes, particular +[[b2.overview.targets.requirements.conditional]]Sometimes, particular relationships need to be maintained among a target's build properties. This can be achieved with _conditional requirements_. For example, you might want to set specific @@ -1047,14 +1045,14 @@ to build only helpers, one should run `b2 hello..helpers`. When no target is requested on the command line, all targets in the current project will be built. If a target should be built only by explicit request, this can be expressed by the -link:#bbv2.reference.rules.explicit[explicit] rule: +link:#b2.reference.rules.explicit[explicit] rule: [source] ---- explicit install_programs ; ---- -[[bbv2.overview.projects]] +[[b2.overview.projects]] == Projects As mentioned before, targets are grouped into projects, and each Jamfile @@ -1088,7 +1086,7 @@ The possible attributes are listed below. _Project id_ is a short way to denote a project, as opposed to the Jamfile's pathname. It is a hierarchical path, unrelated to filesystem, -such as "boost/thread". link:#bbv2.reference.ids[Target references] make +such as "boost/thread". link:#b2.reference.ids[Target references] make use of project ids to specify a target. _Source location_ specifies the directory where sources for the project @@ -1100,7 +1098,7 @@ the projects as well as all sub-projects. _Default build_ is the build request that should be used when no build request is specified explicitly. -[[bbv2.overview.projects.attributes.projectrule]] +[[b2.overview.projects.attributes.projectrule]] The default values for those attributes are given in the table below. [cols=",,,",options="header",] @@ -1128,7 +1126,7 @@ passed value, interpreted as relative to the project's location. Besides defining projects and main targets, Jamfiles often invoke various utility rules. For the full list of rules that can be directly used in Jamfile see -link:#bbv2.reference.rules[the section called “Builtin rules”]. +link:#b2.reference.rules[the section called “Builtin rules”]. Each subproject inherits attributes, constants and rules from its parent project, which is defined by the nearest Jamfile in an ancestor @@ -1150,7 +1148,7 @@ NOTE: Giving the root project the special name “`Jamroot`” ensures that B2 won't misinterpret a directory above it as the project root just because the directory contains a Jamfile. -[[bbv2.overview.build_process]] +[[b2.overview.build_process]] == The Build Process When you've described your targets, you want B2 to run the @@ -1171,7 +1169,7 @@ TIP: This means that for B2, you cannot directly obtain a build variant from a Jamfile. There could be several variants requested by the user, and each target can be built with different properties. -[[bbv2.overview.build_request]] +[[b2.overview.build_request]] === Build Request The command line specifies which targets to build and with which @@ -1184,7 +1182,7 @@ b2 app1 lib1//lib1 toolset=gcc variant=debug optimization=full would build two targets, "app1" and "lib1//lib1" with the specified properties. You can refer to any targets, using -link:#bbv2.reference.ids[target id] and specify arbitrary properties. +link:#b2.reference.ids[target id] and specify arbitrary properties. Some of the properties are very common, and for them the name of the property can be omitted. For example, the above can be written as: @@ -1194,14 +1192,14 @@ b2 app1 lib1//lib1 gcc debug optimization=full ---- The complete syntax, which has some additional shortcuts, is described -in link:#bbv2.overview.invocation[the section called “Invocation”]. +in link:#b2.overview.invocation[the section called “Invocation”]. === Building a main target When you request, directly or indirectly, a build of a main target with specific requirements, the following steps are done. Some brief explanation is provided, and more details are given in -link:#bbv2.reference.buildprocess[the section called “Build process”]. +link:#b2.reference.buildprocess[the section called “Build process”]. 1. Applying default build. If the default-build property of a target specifies a value of a feature that is not present in the build request, @@ -1211,14 +1209,14 @@ we look how many properties are present both in alternative's requirements, and in build request. The alternative with largest number of matching properties is selected. 3. Determining "common" properties. The build request is -link:#bbv2.reference.variants.proprefine[refined] with target's +link:#b2.reference.variants.proprefine[refined] with target's requirements. The conditional properties in requirements are handled as well. Finally, default values of features are added. 4. Building targets referred by the sources list and dependency properties. The list of sources and the properties can refer to other -target using link:#bbv2.reference.ids[target references]. For each +target using link:#b2.reference.ids[target references]. For each reference, we take all -link:#bbv2.reference.features.attributes.propagated[propagated] +link:#b2.reference.features.attributes.propagated[propagated] properties, refine them by explicit properties specified in the target reference, and pass the resulting properties as build request to the other target. diff --git a/doc/src/path.adoc b/doc/src/path.adoc index e6b4c214d5..7b776553ed 100644 --- a/doc/src/path.adoc +++ b/doc/src/path.adoc @@ -1,4 +1,4 @@ -[[bbv2.reference.modules.path]] +[[b2.reference.modules.path]] = path Performs various path manipulations. Paths are always in a 'normalized' @@ -11,52 +11,52 @@ In plain english, a path can be rooted, `'..'` elements are allowed only at the beginning, and it never ends in slash, except for the path consisting of slash only. -1. [[bbv2.reference.modules.path.make]] `rule make ( native )` +1. [[b2.reference.modules.path.make]] `rule make ( native )` + Converts the native path into normalized form. -2. [[bbv2.reference.modules.path.native]] `rule native ( path )` +2. [[b2.reference.modules.path.native]] `rule native ( path )` + Builds the native representation of the path. -3. [[bbv2.reference.modules.path.is-rooted]] `rule is-rooted ( path )` +3. [[b2.reference.modules.path.is-rooted]] `rule is-rooted ( path )` + Tests if a path is rooted. -4. [[bbv2.reference.modules.path.has-parent]] `rule has-parent ( path )` +4. [[b2.reference.modules.path.has-parent]] `rule has-parent ( path )` + Tests if a path has a parent. -5. [[bbv2.reference.modules.path.basename]] `rule basename ( path )` +5. [[b2.reference.modules.path.basename]] `rule basename ( path )` + Returns the path without any directory components. -6. [[bbv2.reference.modules.path.parent]] `rule parent ( path )` +6. [[b2.reference.modules.path.parent]] `rule parent ( path )` + Returns the parent directory of the path. If no parent exists, an error is issued. -7. [[bbv2.reference.modules.path.reverse]] `rule reverse ( path )` +7. [[b2.reference.modules.path.reverse]] `rule reverse ( path )` + Returns `path2` such that `[ join path path2 ] = "."`. The path may not contain `".."` element or be rooted. -8. [[bbv2.reference.modules.path.join]] `rule join ( elements + )` +8. [[b2.reference.modules.path.join]] `rule join ( elements + )` + Concatenates the passed path elements. Generates an error if any element other than the first one is rooted. Skips any empty or undefined path elements. -9. [[bbv2.reference.modules.path.root]] `rule root ( path root )` +9. [[b2.reference.modules.path.root]] `rule root ( path root )` + If `path` is relative, it is rooted at `root`. Otherwise, it is unchanged. -10. [[bbv2.reference.modules.path.pwd]] `rule pwd ( )` +10. [[b2.reference.modules.path.pwd]] `rule pwd ( )` + Returns the current working directory. -11. [[bbv2.reference.modules.path.glob]] `rule glob ( dirs * : patterns + : exclude-patterns * )` +11. [[b2.reference.modules.path.glob]] `rule glob ( dirs * : patterns + : exclude-patterns * )` + Returns the list of files matching the given pattern in the specified directory. Both directories and patterns are supplied as portable paths. @@ -77,47 +77,47 @@ example: [ glob . : */build/Jamfile ] ---- -12. [[bbv2.reference.modules.path.glob-tree]] `rule glob-tree ( roots * : patterns + : exclude-patterns * )` +12. [[b2.reference.modules.path.glob-tree]] `rule glob-tree ( roots * : patterns + : exclude-patterns * )` + -Recursive version of link:#bbv2.reference.modules.path.glob[glob]. +Recursive version of link:#b2.reference.modules.path.glob[glob]. Builds the glob of files while also searching in the subdirectories of the given roots. An optional set of exclusion patterns will filter out the matching entries from the result. The exclusions also apply to the subdirectory scanning, such that directories that match the exclusion patterns will not be searched. -13. [[bbv2.reference.modules.path.exists]] `rule exists ( file )` +13. [[b2.reference.modules.path.exists]] `rule exists ( file )` + Returns true if the specified file exists. -14. [[bbv2.reference.modules.path.all-parents]] `rule all-parents ( path : upper_limit ? : cwd ? )` +14. [[b2.reference.modules.path.all-parents]] `rule all-parents ( path : upper_limit ? : cwd ? )` + Find out the absolute name of path and return the list of all the parents, starting with the immediate one. Parents are returned as relative names. If `upper_limit` is specified, directories above it will be pruned. -15. [[bbv2.reference.modules.path.glob-in-parents]] `rule glob-in-parents ( dir : patterns + : upper-limit ? )` +15. [[b2.reference.modules.path.glob-in-parents]] `rule glob-in-parents ( dir : patterns + : upper-limit ? )` + Search for `patterns` in parent directories of `dir`, up to and including `upper_limit`, if it is specified, or till the filesystem root otherwise. -16. [[bbv2.reference.modules.path.relative]] `rule relative ( child parent : no-error ? )` +16. [[b2.reference.modules.path.relative]] `rule relative ( child parent : no-error ? )` + Assuming `child` is a subdirectory of `parent`, return the relative path from `parent` to `child`. -17. [[bbv2.reference.modules.path.relative-to]] `rule relative-to ( path1 path2 )` +17. [[b2.reference.modules.path.relative-to]] `rule relative-to ( path1 path2 )` + Returns the minimal path to path2 that is relative path1. -18. [[bbv2.reference.modules.path.programs-path]] `rule programs-path ( )` +18. [[b2.reference.modules.path.programs-path]] `rule programs-path ( )` + Returns the list of paths which are used by the operating system for looking up programs. -19. [[bbv2.reference.modules.path.makedirs]] `rule makedirs ( path )` +19. [[b2.reference.modules.path.makedirs]] `rule makedirs ( path )` + Creates a directory and all parent directories that do not already exist. diff --git a/doc/src/project-target.adoc b/doc/src/project-target.adoc index f4697d726c..e313008823 100644 --- a/doc/src/project-target.adoc +++ b/doc/src/project-target.adoc @@ -1,4 +1,4 @@ -[[bbv2.reference.class.project-target]] +[[b2.reference.class.project-target]] = Class project-target [source,jam] @@ -23,10 +23,10 @@ This class has the following responsibilities: * Maintaining a list of main targets in this project and building them. -- -1. [[bbv2.reference.class.project-target.generate]] `rule generate ( property-set )` +1. [[b2.reference.class.project-target.generate]] `rule generate ( property-set )` + Overrides -link:#bbv2.reference.class.abstract-target.generate[abstract-target.generate]. +link:#b2.reference.class.abstract-target.generate[abstract-target.generate]. Generates virtual targets for all the targets contained in this project. + On success, returns: @@ -40,13 +40,13 @@ Returns the root build directory of the project. 3. `rule main-target ( name )` + -Returns a link:#bbv2.reference.class.main-target[main-target] class +Returns a link:#b2.reference.class.main-target[main-target] class instance corresponding to `name`. Can only be called after the project has been fully loaded. 4. `rule has-main-target ( name )` + -Returns whether a link:#bbv2.reference.class.main-target[main-target] +Returns whether a link:#b2.reference.class.main-target[main-target] with the specified name exists. Can only be called after the project has been fully loaded. diff --git a/doc/src/property-set.adoc b/doc/src/property-set.adoc index 507132a632..28226dc1be 100644 --- a/doc/src/property-set.adoc +++ b/doc/src/property-set.adoc @@ -1,4 +1,4 @@ -[[bbv2.reference.class.property-set]] +[[b2.reference.class.property-set]] = Class property-set Class for storing a set of properties. @@ -32,33 +32,33 @@ Returns the string representation of the stored properties. 3. `rule propagated ( )` + -Returns a link:#bbv2.reference.class.property-set[property-set] +Returns a link:#b2.reference.class.property-set[property-set] containing all the -link:#bbv2.reference.features.attributes.propagated[propagated] +link:#b2.reference.features.attributes.propagated[propagated] properties in this -link:#bbv2.reference.class.property-set[property-set]. +link:#b2.reference.class.property-set[property-set]. -4. [[bbv2.reference.class.property-set.add]] `rule add ( ps )` +4. [[b2.reference.class.property-set.add]] `rule add ( ps )` + -Returns a new link:#bbv2.reference.class.property-set[property-set] +Returns a new link:#b2.reference.class.property-set[property-set] containing the union of the properties in this -link:#bbv2.reference.class.property-set[property-set] and in `ps`. +link:#b2.reference.class.property-set[property-set] and in `ps`. + NOTE: If `ps` contains non-free properties that should override the values in -this object, use link:#bbv2.reference.class.property-set.refine[refine] +this object, use link:#b2.reference.class.property-set.refine[refine] instead. 5. `rule add-raw ( properties * )` + -Link link:#bbv2.reference.class.property-set.add[add], except that it +Link link:#b2.reference.class.property-set.add[add], except that it takes a list of properties instead of a -link:#bbv2.reference.class.property-set[property-set]. +link:#b2.reference.class.property-set[property-set]. -6. [[bbv2.reference.class.property-set.refine]] `rule refine ( ps )` +6. [[b2.reference.class.property-set.refine]] `rule refine ( ps )` + Refines properties by overriding any non-free and non-conditional properties for which a different value is specified in `ps`. Returns the -resulting link:#bbv2.reference.class.property-set[property-set]. +resulting link:#b2.reference.class.property-set[property-set]. 7. `rule get ( feature )` + diff --git a/doc/src/recipes.adoc b/doc/src/recipes.adoc index 3d136d6edc..fd923397e7 100644 --- a/doc/src/recipes.adoc +++ b/doc/src/recipes.adoc @@ -1,3 +1,3 @@ -[[bbv2.recipes]] +[[b2.recipes]] B2 System V2 recipes ----------------------------- diff --git a/doc/src/reference.adoc b/doc/src/reference.adoc index b58544fb36..071d9fbfb3 100644 --- a/doc/src/reference.adoc +++ b/doc/src/reference.adoc @@ -1,10 +1,10 @@ -[[bbv2.reference]] +[[b2.reference]] = Reference -[[bbv2.reference.general]] +[[b2.reference.general]] == General information -[[bbv2.reference.init]] +[[b2.reference.init]] === Initialization Immediately upon starting, the B2 engine (*`b2`*) loads the Jam @@ -22,37 +22,37 @@ invocation directory, then in its parent and so forth up to the filesystem root, and finally in the directories specified by the environment variable BOOST_BUILD_PATH. On Unix BOOST_BUILD_PATH defaults to `/usr/share/b2`. -[[bbv2.reference.rules]] +[[b2.reference.rules]] == Builtin rules This section contains the list of all rules that can be used in Jamfile — both rules that define new targets and auxiliary rules. -[[bbv2.reference.rules.exe]]`exe`:: +[[b2.reference.rules.exe]]`exe`:: Creates an executable file. See -link:#bbv2.tasks.programs[the section called “Programs”]. +link:#b2.tasks.programs[the section called “Programs”]. -[[bbv2.reference.rules.lib]]`lib`:: +[[b2.reference.rules.lib]]`lib`:: Creates an library file. See -link:#bbv2.tasks.libraries[the section called “Libraries”]. +link:#b2.tasks.libraries[the section called “Libraries”]. -[[bbv2.reference.rules.install]]`install`:: +[[b2.reference.rules.install]]`install`:: Installs built targets and other files. See -link:#bbv2.tasks.installing[the section called “Installing”]. +link:#b2.tasks.installing[the section called “Installing”]. -[[bbv2.reference.rules.alias]]`alias`:: +[[b2.reference.rules.alias]]`alias`:: Creates an alias for other targets. See -link:#bbv2.tasks.alias[the section called “Alias”]. +link:#b2.tasks.alias[the section called “Alias”]. -[[bbv2.reference.rules.unit-test]]`unit-test`:: +[[b2.reference.rules.unit-test]]`unit-test`:: Creates an executable that will be automatically run. See -link:#bbv2.builtins.testing[the section called “Testing”]. +link:#b2.builtins.testing[the section called “Testing”]. -[[bbv2.reference.rules.test]]`compile`; `compile-fail`; `link`; `link-fail`; `run`; `run-fail`:: +[[b2.reference.rules.test]]`compile`; `compile-fail`; `link`; `link-fail`; `run`; `run-fail`:: Specialized rules for testing. See -link:#bbv2.builtins.testing[the section called “Testing”]. +link:#b2.builtins.testing[the section called “Testing”]. -[[bbv2.reference.rules.check-target-builds]]`check-target-builds`:: +[[b2.reference.rules.check-target-builds]]`check-target-builds`:: The `check-target-builds` allows you to conditionally use different properties depending on whether some metatarget builds, or not. This is similar to functionality of configure script in `autotools` projects. @@ -78,15 +78,15 @@ like so: alias foobar : : : : [ check-target-builds has_foo "System has foo" : foo : bar ] ; ---- -[[bbv2.reference.rules.obj]]`obj`:: +[[b2.reference.rules.obj]]`obj`:: Creates an object file. Useful when a single source file must be compiled with special properties. -[[bbv2.reference.rules.preprocessed]]`preprocessed`:: +[[b2.reference.rules.preprocessed]]`preprocessed`:: Creates an preprocessed source file. The arguments follow the -link:#bbv2.main-target-rule-syntax[common syntax]. +link:#b2.main-target-rule-syntax[common syntax]. -[[bbv2.reference.rules.glob]]`glob`:: +[[b2.reference.rules.glob]]`glob`:: The `glob` rule takes a list shell pattern and returns the list of files in the project's source directory that match the pattern. For example: @@ -104,7 +104,7 @@ example: lib tools : [ glob *.cpp : file_to_exclude.cpp bad*.cpp ] ; ---- -[[bbv2.reference.glob-tree]]`glob-tree`:: +[[b2.reference.glob-tree]]`glob-tree`:: The `glob-tree` is similar to the `glob` except that it operates recursively from the directory of the containing Jamfile. For example: + @@ -116,22 +116,22 @@ will print the names of all {CPP} files in your project. The `.svn` exclude pattern prevents the `glob-tree` rule from entering administrative directories of the Subversion version control system. -[[bbv2.reference.rules.project]]`project`:: +[[b2.reference.rules.project]]`project`:: Declares project id and attributes, including project requirements. -See link:#bbv2.overview.projects[the section called “Projects”]. +See link:#b2.overview.projects[the section called “Projects”]. -[[bbv2.reference.rules.use-project]]`use-project`:: +[[b2.reference.rules.use-project]]`use-project`:: Assigns a symbolic project ID to a project at a given path. This rule must be better documented! -[[bbv2.reference.rules.explicit]]`explicit`:: +[[b2.reference.rules.explicit]]`explicit`:: The `explicit` rule takes a single parameter--a list of target names. The named targets will be marked explicit, and will be built only if they are explicitly requested on the command line, or if their dependents are built. Compare this to ordinary targets, that are built implicitly when their containing project is built. -[[bbv2.reference.rules.always]]`always`:: +[[b2.reference.rules.always]]`always`:: The `always` function takes a single parameter—a list of metatarget names. The targets produced by the named metatargets will be always considered out of date. Consider this example: @@ -146,7 +146,7 @@ If a build of `hello` is requested, then it will always be recompiled. Note that if a build of `hello` is not requested, for example you specify just `bye` on the command line, `hello` will not be recompiled. -[[bbv2.reference.rules.constant]]`constant`:: +[[b2.reference.rules.constant]]`constant`:: Sets project-wide constant. Takes two parameters: variable name and a value and makes the specified variable name accessible in this Jamfile and any child Jamfiles. For example: @@ -155,7 +155,7 @@ and any child Jamfiles. For example: constant VERSION : 1.34.0 ; ---- -[[bbv2.reference.rules.path-constant]]`path-constant`:: +[[b2.reference.rules.path-constant]]`path-constant`:: Same as `constant` except that the value is treated as path relative to Jamfile location. For example, if `b2` is invoked in the current directory, and Jamfile in `helper` subdirectory has: @@ -168,7 +168,7 @@ then the variable `DATA` will be set to `helper/data/a.txt`, and if *`b2`* is invoked from the `helper` directory, then the variable `DATA` will be set to `data/a.txt`. -[[bbv2.reference.rules.build-project]]`build-project`:: +[[b2.reference.rules.build-project]]`build-project`:: Cause some other project to be built. This rule takes a single parameter—a directory name relative to the containing Jamfile. When the containing Jamfile is built, the project located at that directory @@ -176,10 +176,10 @@ will be built as well. At the moment, the parameter to this rule should be a directory name. Project ID or general target references are not allowed. -[[bbv2.reference.rules.test-suite]]`test-suite`:: +[[b2.reference.rules.test-suite]]`test-suite`:: This rule is deprecated and equivalent to `alias`. -[[bbv2.reference.rules.import-search]]`import-search`:: +[[b2.reference.rules.import-search]]`import-search`:: + ==== [horizontal] @@ -204,7 +204,7 @@ include::../../src/engine/mod_jam_builtin.h[tag=reference] :leveloffset: -1 -[[bbv2.overview.builtins.features]] +[[b2.overview.builtins.features]] == Builtin features This section documents the features that are built-in into B2. @@ -287,7 +287,7 @@ include::../../src/tools/features/translate-path-feature.jam[tag=doc] include::../../src/tools/features/lto-feature.jam[tag=doc] include::../../src/tools/features/response-file-feature.jam[tag=doc] -[[bbv2.reference.tools]] +[[b2.reference.tools]] == Builtin tools B2 comes with support for a large number of {CPP} compilers, and @@ -314,7 +314,7 @@ using gcc : 4.0 : g++-4.0 ; The options that can be passed to each tool are documented in the subsequent sections. -[[bbv2.reference.tools.compilers]] +[[b2.reference.tools.compilers]] === {CPP} Compilers This section lists all B2 modules that support {CPP} compilers @@ -345,7 +345,7 @@ include::../../src/tools/vacpp.jam[tag=doc] B2 provides special support for some third-party {CPP} libraries, documented below. -[[bbv2.reference.tools.libraries.stlport]] +[[b2.reference.tools.libraries.stlport]] ==== STLport library The http://stlport.org[STLport] library is an alternative implementation @@ -371,7 +371,7 @@ its own `iostream` implementation, so the library path is required. When STLport is configured, you can build with STLport by requesting `stdlib=stlport` on the command line. -[[bbv2.reference.tools.libraries.zlib]] +[[b2.reference.tools.libraries.zlib]] ==== zlib Provides support for the http://www.zlib.net[zlib] library. zlib can be @@ -403,7 +403,7 @@ Options for building zlib from source: The zlib source directory. Defaults to the environmental variable ZLIB_SOURCE. `tag`:: - Sets the link:#bbv2.builtin.features.tag[tag] property to adjust the + Sets the link:#b2.builtin.features.tag[tag] property to adjust the file name of the library. Ignored when using precompiled binaries. `build-name`:: The base name to use for the compiled library. Ignored when using @@ -425,7 +425,7 @@ using zlib : 1.2.7 : C:/Devel/src/zlib-1.2.7 : msvc ; using zlib : 1.2.7 : : gcc ; ---- -[[bbv2.reference.tools.libraries.bzip2]] +[[b2.reference.tools.libraries.bzip2]] ==== bzip2 Provides support for the http://www.bzip.org[bzip2] library. bzip2 can @@ -457,7 +457,7 @@ Options for building bzip2 from source: The bzip2 source directory. Defaults to the environmental variable BZIP2_SOURCE. `tag`:: - Sets the link:#bbv2.builtin.features.tag[tag] property to adjust the + Sets the link:#b2.builtin.features.tag[tag] property to adjust the file name of the library. Ignored when using precompiled binaries. `build-name`:: The base name to use for the compiled library. Ignored when using @@ -479,7 +479,7 @@ using bzip2 : 1.0.6 : C:/Devel/src/bzip2-1.0.6 : msvc ; using bzip2 : 1.0.6 : : gcc ; ---- -[[bbv2.reference.tools.libraries.python]] +[[b2.reference.tools.libraries.python]] ==== Python Provides support for the http://www.python.org[python] language @@ -576,7 +576,7 @@ using python B2 support for the Boost documentation tools is documented below. -[[bbv2.reference.tools.doc.xsltproc]] +[[b2.reference.tools.doc.xsltproc]] ==== xsltproc To use xsltproc, you first need to configure it using the following @@ -623,7 +623,7 @@ Runs xsltproc to create multiple outputs in a directory. `dirname` is unused, but exists for historical reasons. The output directory is determined from the target. -[[bbv2.reference.tools.doc.boostbook]] +[[b2.reference.tools.doc.boostbook]] ==== boostbook To use boostbook, you first need to configure it using the following @@ -670,7 +670,7 @@ rule boostbook ( target-name : sources * : requirements * : default-build * ) + Creates a boostbook target. -[[bbv2.reference.tools.doc.doxygen]] +[[b2.reference.tools.doc.doxygen]] ==== doxygen To use doxygen, you first need to configure it using the following @@ -726,7 +726,7 @@ Creates a doxygen target. If the target name ends with .html, then this will generate an html directory. Otherwise it will generate BoostBook XML. -[[bbv2.reference.tools.doc.quickbook]] +[[b2.reference.tools.doc.quickbook]] ==== quickbook The quickbook module provides a generator to convert from Quickbook to @@ -744,7 +744,7 @@ using quickbook : command ; will compile it from source. If it is unable to find the source it will search for a quickbook executable in PATH. -[[bbv2.reference.tools.doc.fop]] +[[b2.reference.tools.doc.fop]] ==== fop The fop module provides generators to convert from XSL formatting @@ -762,7 +762,7 @@ B2 will search for it in PATH and FOP_HOME. Either `java-home` or `java` can be used to specify where to find java. -[[bbv2.reference.modules]] +[[b2.reference.modules]] == Builtin modules This section describes the modules that are provided by B2. The @@ -790,7 +790,7 @@ include::type.adoc[] :leveloffset: -2 -[[bbv2.reference.class]] +[[b2.reference.class]] == Builtin classes :leveloffset: +2 @@ -809,11 +809,11 @@ include::property-set.adoc[] :leveloffset: -2 -[[bbv2.reference.buildprocess]] +[[b2.reference.buildprocess]] == Build process The general overview of the build process was given in the -link:#bbv2.overview.build_process[user documentation]. This section +link:#b2.overview.build_process[user documentation]. This section provides additional details, and some specific rules. To recap, building a target with specific properties includes the @@ -829,15 +829,15 @@ the "common" properties, 6. building the target using generators, 7. computing the usage requirements to be returned. -[[bbv2.reference.buildprocess.alternatives]] +[[b2.reference.buildprocess.alternatives]] === Alternative selection When a target has several alternatives, one of them must be selected. The process is as follows: 1. For each alternative, its _condition_ is defined as the set of -link:#bbv2.reference.features.attributes.base[base properties] in its -requirements. link:#bbv2.reference.variants.propcond[Conditional +link:#b2.reference.features.attributes.base[base properties] in its +requirements. link:#b2.reference.variants.propcond[Conditional properties] are excluded. 2. An alternative is viable only if all properties in its condition are @@ -850,7 +850,7 @@ a strict subset of the set of properties of a's condition. If one viable alternative is better than all the others, it's selected. Otherwise, an error is reported. -[[bbv2.reference.buildprocess.common]] +[[b2.reference.buildprocess.common]] === Determining common properties "Common" properties is a somewhat artificial term. This is the @@ -876,7 +876,7 @@ adding all the expanded properties to the build request or the requirements respectively. 5. If the requirements include a -link:#bbv2.reference.variants.propcond[conditional property], and the +link:#b2.reference.variants.propcond[conditional property], and the condition of this property is true in the context of common properties, then the conditional property should be in common properties as well. @@ -897,7 +897,7 @@ exe a : a.cpp release:FOO ; ---- -[[bbv2.reference.buildprocess.targetpath]] +[[b2.reference.buildprocess.targetpath]] === Target Paths Several factors determine the location of a concrete file target. All @@ -938,10 +938,10 @@ exe a : a.cpp : subdir ; will create the files for `a` in `bin/subdir/gcc-4.6.1/debug` -[[bbv2.reference.definitions]] +[[b2.reference.definitions]] == Definitions -[[bbv2.reference.features]] +[[b2.reference.features]] === Features and properties A _feature_ is a normalized (toolset-independent) aspect of a build @@ -979,10 +979,10 @@ the previous example would be `gcc/static`. A _build specification_ is a property set that fully describes the set of features used to build a target. -[[bbv2.reference.features.validity]] +[[b2.reference.features.validity]] === Property Validity -For link:#bbv2.reference.features.attributes.free[free] features, all +For link:#b2.reference.features.attributes.free[free] features, all values are valid. For all other features, the valid values are explicitly specified, and the build system will report an error for the use of an invalid feature-value. Subproperty validity may be restricted @@ -991,7 +991,7 @@ subproperties. For example, it is possible to specify that the `mingw` property is only valid in the presence of `2.95.2`. -[[bbv2.reference.features.attributes]] +[[b2.reference.features.attributes]] === Feature Attributes Each feature has a collection of zero or more of the following @@ -1001,7 +1001,7 @@ build request. We also refer to the attributes of properties, so that an _incidental_ property, for example, is one whose feature has the _incidental_ attribute. -* [[bbv2.reference.features.attributes.incidental]] _incidental_ +* [[b2.reference.features.attributes.incidental]] _incidental_ + Incidental features are assumed not to affect build products at all. As a consequence, the build system may use the same file for targets whose @@ -1012,19 +1012,19 @@ incidental feature. Non-incidental features are assumed to affect build products, so the files for targets whose build specification differs in non-incidental features are placed in different directories as described in -<>. +<>. -* [[bbv2.reference.features.attributes.propagated]] _propagated_ +* [[b2.reference.features.attributes.propagated]] _propagated_ + Features of this kind are propagated to dependencies. That is, if a -link:#bbv2.overview.targets.main[main target] is built using a +link:#b2.overview.targets.main[main target] is built using a propagated property, the build systems attempts to use the same property when building any of its dependencies as part of that main target. For instance, when an optimized executable is requested, one usually wants it to be linked with optimized libraries. Thus, the `` feature is propagated. -* [[bbv2.reference.features.attributes.free]] _free_ +* [[b2.reference.features.attributes.free]] _free_ + Most features have a finite set of allowed values, and can only take on a single value from that set in a given build specification. Free @@ -1036,7 +1036,7 @@ several preprocessor symbols defined simultaneously: NDEBUG=1 HAS_CONFIG_H=1 ---- -* [[bbv2.reference.features.attributes.optional]] _optional_ +* [[b2.reference.features.attributes.optional]] _optional_ + An optional feature is a feature that is not required to appear in a build specification. Every non-optional non-free feature has a default @@ -1045,21 +1045,21 @@ specified, either in a target's requirements or in the user's build request. [A feature's default value is given by the first value listed in the feature's declaration. -- move this elsewhere - dwa] -* [[bbv2.reference.features.attributes.symmetric]] _symmetric_ +* [[b2.reference.features.attributes.symmetric]] _symmetric_ + Normally a feature only generates a sub-variant directory when its value differs from its default value, leading to an asymmetric sub-variant directory structure for certain values of the feature. A symmetric feature always generates a corresponding sub-variant directory. -* [[bbv2.reference.features.attributes.path]] _path_ +* [[b2.reference.features.attributes.path]] _path_ + The value of a path feature specifies a path. The path is treated as relative to the directory of Jamfile where path feature is used and is translated appropriately by the build system when the build is invoked from a different directory -* [[bbv2.reference.features.attributes.implicit]] _implicit_ +* [[b2.reference.features.attributes.implicit]] _implicit_ + Values of implicit features alone identify the feature. For example, a user is not required to write "gcc", but can simply write @@ -1068,7 +1068,7 @@ although the values do. Thus: bin/gcc/... as opposed to bin/toolset-gcc/.... There should typically be only a few such features, to avoid possible name clashes. -* [[bbv2.reference.features.attributes.composite]] _composite_ +* [[b2.reference.features.attributes.composite]] _composite_ + Composite features actually correspond to groups of properties. For example, a build variant is a composite feature. When generating targets @@ -1077,7 +1077,7 @@ expanded and _added_ to the build property set, so rules can find them if necessary. Non-composite non-free features override components of composite features in a build property set. -* [[bbv2.reference.features.attributes.dependency]] _dependency_ +* [[b2.reference.features.attributes.dependency]] _dependency_ + The value of a dependency feature is a target reference. When used for building of a main target, the value of dependency feature is treated as @@ -1088,11 +1088,11 @@ on library B. As the result, whenever an application will link to A, it will also link to B. Specifying B as dependency of A is different from adding B to the sources of A. -[[bbv2.reference.features.attributes.base]] +[[b2.reference.features.attributes.base]] Features that are neither free nor incidental are called _base_ features. -[[bbv2.reference.features.declaration]] +[[b2.reference.features.declaration]] === Feature Declaration The low-level feature declaration interface is the `feature` rule from @@ -1106,7 +1106,7 @@ rule feature ( name : allowed-values * : attributes * ) A feature's allowed-values may be extended with the `feature.extend` rule. -[[bbv2.reference.variants.proprefine]] +[[b2.reference.variants.proprefine]] === Property refinement When a target with certain properties is requested, and that target @@ -1120,7 +1120,7 @@ set 2. If the original property set includes property with a different value of non free feature, that property is removed. -[[bbv2.reference.variants.propcond]] +[[b2.reference.variants.propcond]] === Conditional properties Sometime it's desirable to apply certain requirements only for a @@ -1148,7 +1148,7 @@ The syntax also allows several properties in the condition, for example: exe hello : hello.cpp : NT,gcc:static ; ---- -[[bbv2.reference.ids]] +[[b2.reference.ids]] === Target identifiers and references _Target identifier_ is used to denote a target. The syntax is: @@ -1189,7 +1189,7 @@ just slash), because: * It emphasis that projects and targets are different things. * It allows to have main target names with slashes. -[[bbv2.reference.targets.references]] +[[b2.reference.targets.references]] _Target reference_ is used to specify a source target, and may additionally specify desired properties for that target. It has this syntax: diff --git a/doc/src/sequence.adoc b/doc/src/sequence.adoc index dcedeee6c7..a5c36395cb 100644 --- a/doc/src/sequence.adoc +++ b/doc/src/sequence.adoc @@ -1,4 +1,4 @@ -[[bbv2.reference.modules.sequence]] +[[b2.reference.modules.sequence]] = sequence Various useful list functions. Note that algorithms in this module diff --git a/doc/src/standalone.adoc b/doc/src/standalone.adoc index df07f53afe..37d2ceb261 100644 --- a/doc/src/standalone.adoc +++ b/doc/src/standalone.adoc @@ -1,5 +1,5 @@ = B2 User Manual -:copyright: Copyright 2018-2021 René Ferdinand Rivera Morell; Copyright 2006, 2014 Vladimir Prus +:copyright: Copyright 2018-2025 René Ferdinand Rivera Morell; Copyright 2006, 2014 Vladimir Prus :author: René Ferdinand Rivera Morell, Vladimir Prus, Steven Watanabe :toc: left :toclevels: 2 @@ -7,16 +7,12 @@ :sectnums: :nofooter: :stylesheet: amber.css -// :source-highlighter: rouge -// :rouge-style: native :source-language: jam -:highlightjsdir: hljs :caution-caption: ⚑ :important-caption: ‼ :note-caption: ℹ :tip-caption: ☀ :warning-caption: ⚠ -:CPP: C++ == Introduction @@ -30,8 +26,7 @@ endif::[] include::howto.adoc[] **** -Copyright 2018-2021 René Ferdinand Rivera Morell; -Copyright 2006, 2014 Vladimir Prus. +{copyright} Distributed under the Boost Software License, Version 1.0. (See accompanying file `LICENSE.txt` or copy at https://www.bfgroup.xyz/b2/LICENSE.txt) **** diff --git a/doc/src/tasks.adoc b/doc/src/tasks.adoc index 51cfce786f..f081c46675 100644 --- a/doc/src/tasks.adoc +++ b/doc/src/tasks.adoc @@ -1,16 +1,16 @@ -[[bbv2.tasks]] +[[b2.tasks]] = Common tasks This section describes main targets types that B2 supports out-of-the-box. Unless otherwise noted, all mentioned main target rules have the common signature, described in -link:#bbv2.overview.targets[the section called “Declaring Targets”]. +link:#b2.overview.targets[the section called “Declaring Targets”]. -[[bbv2.tasks.programs]] +[[b2.tasks.programs]] == Programs Programs are created using the `exe` rule, which follows the -link:#bbv2.main-target-rule-syntax[common syntax]. For example: +link:#b2.main-target-rule-syntax[common syntax]. For example: [source] ---- @@ -32,13 +32,13 @@ possible to immediately run the application, because the `PATH` environment variable should include the path to the libraries. It means you have to either add the paths manually, or have the build place the application and the libraries into the same directory. See -link:#bbv2.tasks.installing[the section called “Installing”]. +link:#b2.tasks.installing[the section called “Installing”]. -[[bbv2.tasks.libraries]] +[[b2.tasks.libraries]] == Libraries Library targets are created using the `lib` rule, which follows the -link:#bbv2.main-target-rule-syntax[common syntax]. For example: +link:#b2.main-target-rule-syntax[common syntax]. For example: [source] ---- @@ -48,7 +48,7 @@ lib helpers : helpers.cpp ; This will define a library target named `helpers` built from the `helpers.cpp` source file. It can be either a static library or a shared library, depending on the value of the -link:#bbv2.builtin.features.link[``] feature. +link:#b2.builtin.features.link[``] feature. Library targets can represent: @@ -152,7 +152,7 @@ executables that link to `a` to link to `b` also. In this case, even for shared linking, the `a` library will not refer to `b`. ==== -link:#bbv2.overview.targets[Usage requirements] are often very useful +link:#b2.overview.targets[Usage requirements] are often very useful for defining library targets. For example, imagine that you want you build a `helpers` library and its interface is described in its `helpers.hpp` header file located in the same directory as the @@ -169,7 +169,7 @@ defined (and where the library's header file is located) to the compiler's include path for all targets using the `helpers` library. This feature greatly simplifies Jamfiles. -[[bbv2.tasks.alias]] +[[b2.tasks.alias]] == Alias The `alias` rule gives an alternative name to a group of targets. For @@ -218,7 +218,7 @@ exe main : main.cpp static_libraries ; will compile `main.cpp` with additional includes required for using the specified static libraries. -[[bbv2.tasks.installing]] +[[b2.tasks.installing]] == Installing This section describes various ways to install built targets and @@ -227,7 +227,7 @@ arbitrary files. === Basic install For installing a built target you should use the `install` rule, which -follows the link:#bbv2.main-target-rule-syntax[common syntax]. For +follows the link:#b2.main-target-rule-syntax[common syntax]. For example: [source] @@ -259,8 +259,8 @@ install dist : hello helpers : install dist2 : hello helpers : $(DIST) ; ---- -See also link:#bbv2.reference.variants.propcond[conditional properties] -and link:#bbv2.faq.envar[environment variables] +See also link:#b2.reference.variants.propcond[conditional properties] +and link:#b2.faq.envar[environment variables] === Installing with all dependencies @@ -280,7 +280,7 @@ will find all targets that `hello` depends on, and install all of those which are either executables or libraries. More specifically, for each target, other targets that were specified as sources or as dependency properties, will be recursively found. One exception is that targets -referred with the link:#bbv2.builtin.features.use[`use`] feature are not +referred with the link:#b2.builtin.features.use[`use`] feature are not considered, as that feature is typically used to refer to header-only libraries. If the set of target types is specified, only targets of that type will be installed, otherwise, all found target will be installed. @@ -304,13 +304,13 @@ install headers the a file named `/tmp/b/c.h` will be created. -The link:#bbv2.reference.glob-tree[`glob-tree`] rule can be used to find +The link:#b2.reference.glob-tree[`glob-tree`] rule can be used to find all files below a given directory, making it easy to install an entire directory tree. === Installing into Several Directories -The link:#bbv2.tasks.alias[`alias`] rule can be used when targets need +The link:#b2.tasks.alias[`alias`] rule can be used when targets need to be installed into several directories: [source] @@ -322,11 +322,11 @@ install install-lib : helper : /usr/lib ; Because the `install` rule just copies targets, most free features footnote:[see the definition of "free" in -link:#bbv2.reference.features.attributes[the section called “Feature Attributes”].] +link:#b2.reference.features.attributes[the section called “Feature Attributes”].] have no effect when used in requirements of the `install` rule. The only two that matter are -link:#bbv2.builtin.features.dependency[`dependency`] and, on Unix, -link:#bbv2.builtin.features.dll-path[`dll-path`]. +link:#b2.builtin.features.dependency[`dependency`] and, on Unix, +link:#b2.builtin.features.dll-path[`dll-path`]. NOTE: (Unix specific) On Unix, executables built using B2 typically contain the list of paths to all used shared libraries. For installing, @@ -334,19 +334,19 @@ this is not desired, so B2 relinks the executable with an empty list of paths. You can also specify additional paths for installed executables using the `dll-path` feature. -[[bbv2.builtins.testing]] +[[b2.builtins.testing]] == Testing B2 has convenient support for running unit tests. The simplest way is the `unit-test` rule, which follows the -link:#bbv2.main-target-rule-syntax[common syntax]. For example: +link:#b2.main-target-rule-syntax[common syntax]. For example: [source] ---- unit-test helpers_test : helpers_test.cpp helpers ; ---- -The `unit-test` rule behaves like the link:#bbv2.tasks.programs[exe] +The `unit-test` rule behaves like the link:#b2.tasks.programs[exe] rule, but after the executable is created it is also run. If the executable returns an error code, the build system will also return an error and will try running the executable on the next invocation until @@ -463,13 +463,13 @@ valgrind bin/$toolset/debug/helpers_test A description of the test. This is displayed as part of the `--dump-tests` command-line option. -[[bbv2.builtins.raw]] +[[b2.builtins.raw]] == Custom commands For most main target rules, B2 automatically figures out the commands to run. When you want to use new file types or support new tools, one approach is to extend B2 to support them smoothly, -as documented in link:#bbv2.extender[Extender Manual]. However, if the new +as documented in link:#b2.extender[Extender Manual]. However, if the new tool is only used in a single place, it might be easier just to specify the commands to run explicitly. @@ -501,7 +501,7 @@ actions in2out If you run `b2` and `file.out` does not exist, B2 will run the `in2out` command to create that file. For more details on specifying actions, see -link:#bbv2.overview.jam_language.actions[the section called “Boost.Jam Language”]. +link:#b2.overview.jam_language.actions[the section called “Boost.Jam Language”]. It could be that you just want to run some command unconditionally, and that command does not create any specific files. For that you can use @@ -542,7 +542,7 @@ list of `virtual-target` instances. The interface of the B2 distribution illustrates how the `generate` rule can be used. -[[bbv2.reference.precompiled_headers]] +[[b2.reference.precompiled_headers]] == Precompiled Headers Precompiled headers is a mechanism to speed up compilation by creating a @@ -592,7 +592,7 @@ details. was required to include the header at the top of every source file the precompiled header will be used with. -[[bbv2.reference.generated_headers]] +[[b2.reference.generated_headers]] == Generated headers Usually, B2 handles implicit dependencies completely @@ -623,14 +623,14 @@ The above example tells the build system that when scanning all sources of "app" for implicit-dependencies, it should consider targets from "parser" as potential dependencies. -[[bbv2.tasks.crosscompile]] +[[b2.tasks.crosscompile]] == Cross-compilation B2 supports cross compilation with the gcc and msvc toolsets. When using gcc, you first need to specify your cross compiler in `user-config.jam` (see -link:#bbv2.overview.configuration[the section called “Configuration”]), for +link:#b2.overview.configuration[the section called “Configuration”]), for example: [source] @@ -659,15 +659,15 @@ b2 toolset=gcc-mingw target-os=windows ---- For the complete list of allowed operating system names, please see the -documentation for link:#bbv2.builtin.features.target-os[target-os +documentation for link:#b2.builtin.features.target-os[target-os feature]. When using the msvc compiler, it's only possible to cross-compile to a 64-bit system on a 32-bit host. Please see -link:#bbv2.reference.tools.compiler.msvc.64[the section called “64-bit support”] +link:#b2.reference.tools.compiler.msvc.64[the section called “64-bit support”] for details. -[[bbv2.tasks.packagemanagers]] +[[b2.tasks.packagemanagers]] == Package Managers B2 supports automatic, or manual, loading of generated build files @@ -727,7 +727,7 @@ managers. Currently the supported ones are: * Conan (`conan`): currently supports the link:https://docs.conan.io/en/latest/reference/generators/b2.html[`b2 generator`]. -[[bbv2.tasks.projectsearch]] +[[b2.tasks.projectsearch]] == Searching For Projects B2 supports automatic searching for referenced global projects. For example, @@ -736,7 +736,7 @@ can find the B2 project for it and automatically resolve the reference. The searching supports two modes: finding regular B2 project directories, and package/config style loading of single jam files. -[[bbv2.tasks.projectsearch.path]] +[[b2.tasks.projectsearch.path]] === Search Path To control which and where projects are found one can use different methods: @@ -763,7 +763,7 @@ The _project-id_ in the search path specification maps that project root to the indicated _path_. Which B2 will use to search for any projects and sub-projects with that _project-id_ root. -[[bbv2.tasks.projectsearch.process]] +[[b2.tasks.projectsearch.process]] === Search Process Regardless of how the search path is specified, how the search happens is the @@ -806,7 +806,7 @@ And given the `/boost/core` _project-id_ to resolve, we search for: The first project jamfile will be assigned to the _project-id_. Or the first `*.jam` file found will be loaded. -[[bbv2.tasks.projectsearch.loading]] +[[b2.tasks.projectsearch.loading]] === Loading Process Depending on whether a project jamfile or `*.jam` file determines how the diff --git a/doc/src/tutorial.adoc b/doc/src/tutorial.adoc index 4d725dbc43..d86cc9179b 100644 --- a/doc/src/tutorial.adoc +++ b/doc/src/tutorial.adoc @@ -1,11 +1,11 @@ -[[bbv2.tutorial]] +[[b2.tutorial]] = Tutorial This section will guide you through the most basic features of B2. We will start with the “Hello, world” example, learn how to use libraries, and finish with testing and installing features. -[[bbv2.tutorial.hello]] +[[b2.tutorial.hello]] == Hello, world The simplest project that B2 can construct is stored in @@ -66,7 +66,7 @@ b2 hello2 b2 --clean hello2 ---- -[[bbv2.tutorial.properties]] +[[b2.tutorial.properties]] == Properties To represent aspects of target configuration such as debug and release @@ -108,9 +108,9 @@ an _implicit_ feature—B2 will deduce its identity just from the name of one of its values. A complete description of features can be found in -link:#bbv2.reference.features[the section called “Features and properties”]. +link:#b2.reference.features[the section called “Features and properties”]. -[[bbv2.tutorial.properties.requirements]] +[[b2.tutorial.properties.requirements]] === Build Requests and Target Requirements The set of properties specified on the command line constitutes a _build @@ -120,7 +120,7 @@ project in the current directory). The _actual_ properties used for building targets are typically a combination of the build request and properties derived from the project's `Jamfile` (and its other Jamfiles, as described in -link:#bbv2.tutorial.hierarchy[the section called “Project Hierarchies”]). +link:#b2.tutorial.hierarchy[the section called “Project Hierarchies”]). For example, the locations of `#include`d header files are normally not specified on the command-line, but described in Jamfiles as _target requirements_ and automatically combined with the build request for those @@ -141,13 +141,13 @@ be present. If the build request given on the `b2` command-line explicitly contradicts a target's requirements, the target requirements usually override (or, in the case of “free” features like ``, footnote:[See -link:#bbv2.reference.features.attributes[the section called “Feature Attributes”]] +link:#b2.reference.features.attributes[the section called “Feature Attributes”]] augment) the build request. TIP: The value of the `` feature is relative to the location of `Jamfile` where it is used. -[[bbv2.tutorial.properties.project_attributes]] +[[b2.tutorial.properties.project_attributes]] === Project Attributes If we want the same requirements for our other target, `hello2`, we @@ -169,7 +169,7 @@ exe hello2 : hello.cpp ; The effect would be as if we specified the same requirement for both `hello` and `hello2`. -[[bbv2.tutorial.hierarchy]] +[[b2.tutorial.hierarchy]] == Project Hierarchies So far we have only considered examples with one project, with one @@ -219,8 +219,8 @@ in its requirements, then all of its sub-projects will have it in their requirements, too. Of course, any project can add include paths to those specified by its parents. footnote:[Many features will be overridden, rather than added-to, in sub-projects See -link:#bbv2.reference.features.attributes[the section called “Feature Attributes”] for more information] More -details can be found in link:#bbv2.overview.projects[the section called “Projects”]. +link:#b2.reference.features.attributes[the section called “Feature Attributes”] for more information] More +details can be found in link:#b2.overview.projects[the section called “Projects”]. Invoking `b2` without explicitly specifying any targets on the command line builds the project rooted in the current directory. Building a @@ -237,7 +237,7 @@ which would cause the project in `top/app/` to be built whenever the project in `top/` is built. However, targets in `top/util/foo/` will be built only if they are needed by targets in `top/` or `top/app/`. -[[bbv2.tutorial.libs]] +[[b2.tutorial.libs]] == Dependent Targets When building a target `X` that depends on first building another target @@ -346,7 +346,7 @@ project ==== -[[bbv2.tutorial.linkage]] +[[b2.tutorial.linkage]] == Static and shared libraries Libraries can be either _static_, which means they are included in @@ -374,7 +374,7 @@ lib l : l.cpp : static ; We can also use the `` property to express linking requirements on a per-target basis. For example, if a particular executable can be correctly built only with the static version of a library, we can -qualify the executable's link:#bbv2.reference.targets.references[target +qualify the executable's link:#b2.reference.targets.references[target reference] to the library as follows: [source] @@ -408,7 +408,7 @@ exe e1 : e1.cpp foo ; exe e10 : e10.cpp foo ; ---- -The link:#bbv2.tasks.alias[alias] rule is specifically used to rename a +The link:#b2.tasks.alias[alias] rule is specifically used to rename a reference to a target and possibly change the properties. [TIP] @@ -438,7 +438,7 @@ This restriction is lifted when you use B2 testing facilities—the `PATH` variable will be automatically adjusted before running the executable. -[[bbv2.tutorial.conditions]] +[[b2.tutorial.conditions]] == Conditions and alternatives Sometimes, particular relationships need to be maintained among a @@ -480,7 +480,7 @@ selected, and when building with `msvc` alternative *(3)* will be selected. In all other cases, the most generic alternative *(1)* will be built. -[[bbv2.tutorial.prebuilt]] +[[b2.tutorial.prebuilt]] == Prebuilt targets To link to libraries whose build instructions aren't given in a Jamfile, @@ -549,5 +549,5 @@ lib pythonlib : : python22_d debug ; ---- A more advanced use of prebuilt targets is described in -link:#bbv2.recipes.site-config[the section called “Targets in +link:#b2.recipes.site-config[the section called “Targets in site-config.jam”]. diff --git a/doc/src/type.adoc b/doc/src/type.adoc index 10cf93c8b8..5dc51e6bdd 100644 --- a/doc/src/type.adoc +++ b/doc/src/type.adoc @@ -1,61 +1,61 @@ -[[bbv2.reference.modules.type]] +[[b2.reference.modules.type]] = type Deals with target type declaration and defines target class which supports typed targets. -1. [[bbv2.reference.modules.type.register]] `rule register ( type : suffixes * : base-type ? )` +1. [[b2.reference.modules.type.register]] `rule register ( type : suffixes * : base-type ? )` + Registers a target type, possible derived from a `base-type`. Providing a list of suffixes here is a shortcut for separately calling the -link:#bbv2.reference.modules.type.register-suffixes[register-suffixes] +link:#b2.reference.modules.type.register-suffixes[register-suffixes] rule with the given suffixes and the -link:#bbv2.reference.modules.type.set-generated-target-suffix[set-generated-target-suffix] +link:#b2.reference.modules.type.set-generated-target-suffix[set-generated-target-suffix] rule with the first given suffix. -2. [[bbv2.reference.modules.type.register-suffixes]] `rule register-suffixes ( suffixes + : type )` +2. [[b2.reference.modules.type.register-suffixes]] `rule register-suffixes ( suffixes + : type )` + Specifies that files with suffix from `suffixes` be recognized as targets of type `type`. Issues an error if a different type is already specified for any of the suffixes. -3. [[bbv2.reference.modules.type.registered]] `rule registered ( type )` +3. [[b2.reference.modules.type.registered]] `rule registered ( type )` + Returns true iff type has been registered. -4. [[bbv2.reference.modules.type.validate]] `rule validate ( type )` +4. [[b2.reference.modules.type.validate]] `rule validate ( type )` + Issues an error if `type` is unknown. -5. [[bbv2.reference.modules.type.set-scanner]] `rule set-scanner ( type : scanner )` +5. [[b2.reference.modules.type.set-scanner]] `rule set-scanner ( type : scanner )` + Sets a scanner class that will be used for this type. -6. [[bbv2.reference.modules.type.get-scanner]] `rule get-scanner ( type : property-set )` +6. [[b2.reference.modules.type.get-scanner]] `rule get-scanner ( type : property-set )` + Returns a scanner instance appropriate to `type` and `property-set`. -7. [[bbv2.reference.modules.type.base]] `rule base ( type )` +7. [[b2.reference.modules.type.base]] `rule base ( type )` + Returns a base type for the given type or nothing in case the given type is not derived. -8. [[bbv2.reference.modules.type.all-bases]] `rule all-bases ( type )` +8. [[b2.reference.modules.type.all-bases]] `rule all-bases ( type )` + Returns the given type and all of its base types in order of their distance from type. -9. [[bbv2.reference.modules.type.all-derived]] `rule all-derived ( type )` +9. [[b2.reference.modules.type.all-derived]] `rule all-derived ( type )` + Returns the given type and all of its derived types in order of their distance from type. -10. [[bbv2.reference.modules.type.is-derived]] `rule is-derived ( type base )` +10. [[b2.reference.modules.type.is-derived]] `rule is-derived ( type base )` + Returns true if `type` is equal to `base` or has `base` as its direct or indirect base. -11. [[bbv2.reference.modules.type.set-generated-target-suffix]] `rule set-generated-target-suffix ( type : properties * : suffix )` +11. [[b2.reference.modules.type.set-generated-target-suffix]] `rule set-generated-target-suffix ( type : properties * : suffix )` + Sets a file suffix to be used when generating a target of `type` with the specified properties. Can be called with no properties if no suffix @@ -67,20 +67,20 @@ recognized as being of `type`. Two different types can use the same suffix for their generated files but only one type can be auto-detected for a file with that suffix. User should explicitly specify which one using the -link:#bbv2.reference.modules.type.register-suffixes[register-suffixes] +link:#b2.reference.modules.type.register-suffixes[register-suffixes] rule. -12. [[bbv2.reference.modules.type.change-generated-target-suffix]] `rule change-generated-target-suffix ( type : properties * : suffix )` +12. [[b2.reference.modules.type.change-generated-target-suffix]] `rule change-generated-target-suffix ( type : properties * : suffix )` + Change the suffix previously registered for this type/properties combination. If suffix is not yet specified, sets it. -13. [[bbv2.reference.modules.type.generated-target-suffix]] `rule generated-target-suffix ( type : property-set )` +13. [[b2.reference.modules.type.generated-target-suffix]] `rule generated-target-suffix ( type : property-set )` + Returns the suffix used when generating a file of `type` with the given properties. -14. [[bbv2.reference.modules.type.set-generated-target-prefix]] `rule set-generated-target-prefix ( type : properties * : prefix )` +14. [[b2.reference.modules.type.set-generated-target-prefix]] `rule set-generated-target-prefix ( type : properties * : prefix )` + Sets a target prefix that should be used when generating targets of `type` with the specified properties. Can be called with empty @@ -91,17 +91,17 @@ prefix should be used. + Usage example: library names use the `"lib"` prefix on unix. -15. [[bbv2.reference.modules.type.change-generated-target-prefix]] `rule change-generated-target-prefix ( type : properties * : prefix )` +15. [[b2.reference.modules.type.change-generated-target-prefix]] `rule change-generated-target-prefix ( type : properties * : prefix )` + Change the prefix previously registered for this type/properties combination. If prefix is not yet specified, sets it. -16. [[bbv2.reference.modules.type.generated-target-prefix]] `rule generated-target-prefix ( type : property-set )` +16. [[b2.reference.modules.type.generated-target-prefix]] `rule generated-target-prefix ( type : property-set )` + Returns the prefix used when generating a file of `type` with the given properties. -17. [[bbv2.reference.modules.type.type]] `rule type ( filename )` +17. [[b2.reference.modules.type.type]] `rule type ( filename )` + Returns file type given its name. If there are several dots in filename, tries each suffix. E.g. for name of "file.so.1.2" suffixes "2", "1", and diff --git a/doc/src/typed-target.adoc b/doc/src/typed-target.adoc index 20c16da533..d62b2199f4 100644 --- a/doc/src/typed-target.adoc +++ b/doc/src/typed-target.adoc @@ -1,10 +1,10 @@ -[[bbv2.reference.class.typed-target]] +[[b2.reference.class.typed-target]] = Class typed-target [source,jam] ---- class typed-target : basic-target { - rule __init__ ( name : project : type : sources * : requirements * : default-build * : usage-requirements * ) + rule __init__ ( name : project : type : sources * : requirements * : default-build * : usage-requirements * ) rule type ( ) rule construct ( name : source-targets * : property-set ) @@ -13,13 +13,13 @@ class typed-target : basic-target { rule project ( ) rule location ( ) rule full-name ( ) - + # Methods inherited from basic-target rule generate ( property-set ) } ---- -link:#bbv2.reference.class.typed-target[typed-target] is the most common +link:#b2.reference.class.typed-target[typed-target] is the most common kind of target alternative. Rules for creating typed targets are defined automatically for each type. @@ -29,26 +29,26 @@ automatically for each type. `name`:: The name of the target `project`:: - The link:#bbv2.reference.class.project-target[project] in which the + The link:#b2.reference.class.project-target[project] in which the target is declared. `type`:: - The link:#bbv2.reference.modules.type[type] of the target. + The link:#b2.reference.modules.type[type] of the target. 2. `rule type ( )` + -Returns the link:#bbv2.reference.modules.type[type] of the target. +Returns the link:#b2.reference.modules.type[type] of the target. 3. `rule construct ( name : source-targets * : property-set )` + Implements -link:#bbv2.reference.class.basic-target.construct[basic-target.construct]. +link:#b2.reference.class.basic-target.construct[basic-target.construct]. Attempts to create a target of the correct type using generators appropriate for the given -link:#bbv2.reference.class.property-set[property-set]. Returns a -link:#bbv2.reference.class.property-set[property-set] containing the +link:#b2.reference.class.property-set[property-set]. Returns a +link:#b2.reference.class.property-set[property-set] containing the usage requirements and a list of virtual targets. + NOTE: This function is invoked automatically by -link:#bbv2.reference.class.basic-target.generate[basic-target.generate] +link:#b2.reference.class.basic-target.generate[basic-target.generate] and should not be called directly by users. -- diff --git a/example/user-config.jam b/example/user-config.jam index 05d823da0f..ee7f2e7e27 100644 --- a/example/user-config.jam +++ b/example/user-config.jam @@ -8,7 +8,7 @@ # this file in place, or you can place it in a permanent location so that it # does not get overwritten should you get a new version of B2. See: # -# https://www.bfgroup.xyz/b2/manual/release/index.html#bbv2.overview.configuration +# https://www.bfgroup.xyz/b2/manual/release/index.html#b2.overview.configuration # # for documentation about possible permanent locations. @@ -17,7 +17,7 @@ # example lines and adjust them to taste. The complete list of supported tools, # and configuration instructions can be found at: # -# https://www.bfgroup.xyz/b2/manual/release/index.html#bbv2.reference.tools +# https://www.bfgroup.xyz/b2/manual/release/index.html#b2.reference.tools # # This file uses Jam language syntax to describe available tools. Mostly, diff --git a/src/build-system.jam b/src/build-system.jam index 1f6c72b1e4..7e23acbfc8 100644 --- a/src/build-system.jam +++ b/src/build-system.jam @@ -653,7 +653,7 @@ local rule should-clean-project ( project ) ECHO "warning: If the default is wrong, your build may not work correctly." ; ECHO "warning: Use the \"toolset=xxxxx\" option to override our guess." ; ECHO "warning: For more configuration options, please consult" ; - ECHO "warning: https://www.bfgroup.xyz/b2/manual/release/index.html#bbv2.overview.configuration" ; + ECHO "warning: https://www.bfgroup.xyz/b2/manual/release/index.html#b2.overview.configuration" ; toolset.using $(default-toolset) : $(default-toolset-version) ; } diff --git a/src/build/targets.jam b/src/build/targets.jam index e451b25c67..51cc8c3d2d 100644 --- a/src/build/targets.jam +++ b/src/build/targets.jam @@ -1675,7 +1675,7 @@ class typed-target : basic-target ECHO "error: no generators were found for type '$(self.type)'" ; ECHO "error: and the requested properties" ; ECHO "error: make sure you've configured the needed tools" ; - ECHO "See https://www.bfgroup.xyz/b2/manual/release/index.html#bbv2.overview.configuration" ; + ECHO "See https://www.bfgroup.xyz/b2/manual/release/index.html#b2.overview.configuration" ; EXIT "To debug this problem, try the --debug-generators option." ; } diff --git a/src/tools/acc.jam b/src/tools/acc.jam index 67b44fc6c5..2b703ddf09 100644 --- a/src/tools/acc.jam +++ b/src/tools/acc.jam @@ -7,7 +7,7 @@ #| tag::doc[] -[[bbv2.reference.tools.compiler.acc]] +[[b2.reference.tools.compiler.acc]] = HP aC++ compiler The `acc` module supports the diff --git a/src/tools/borland.jam b/src/tools/borland.jam index 7003da3434..161c1bb324 100644 --- a/src/tools/borland.jam +++ b/src/tools/borland.jam @@ -7,7 +7,7 @@ #| tag::doc[] -[[bbv2.reference.tools.compiler.borland]] +[[b2.reference.tools.compiler.borland]] = Borland C++ Compiler The `borland` module supports the 32-bit command line C++ compilers diff --git a/src/tools/clang-linux.jam b/src/tools/clang-linux.jam index 77bbdd6c5f..41d03e9da6 100644 --- a/src/tools/clang-linux.jam +++ b/src/tools/clang-linux.jam @@ -9,11 +9,11 @@ #| tag::doc[] -[[bbv2.reference.tools.compiler.clang-linux]] +[[b2.reference.tools.compiler.clang-linux]] = Clang (GCC frontend) The `clang-linux` module supports Clang with GCC frontend and has the same -options as link:#bbv2.reference.tools.compiler.gcc[`gcc`] toolset. +options as link:#b2.reference.tools.compiler.gcc[`gcc`] toolset. |# # end::doc[] diff --git a/src/tools/clang-win.jam b/src/tools/clang-win.jam index 4d352315d9..708aa1d4e9 100644 --- a/src/tools/clang-win.jam +++ b/src/tools/clang-win.jam @@ -7,11 +7,11 @@ #| tag::doc[] -[[bbv2.reference.tools.compiler.clang-win]] +[[b2.reference.tools.compiler.clang-win]] = Clang (MSVC frontend) The `clang-win` module supports Clang with MSVC frontend and has the same -options as link:#bbv2.reference.tools.compiler.msvc[`msvc`] toolset. +options as link:#b2.reference.tools.compiler.msvc[`msvc`] toolset. |# # end::doc[] diff --git a/src/tools/como.jam b/src/tools/como.jam index 3dd5bb4e44..d3a1f1c108 100644 --- a/src/tools/como.jam +++ b/src/tools/como.jam @@ -5,7 +5,7 @@ #| tag::doc[] -[[bbv2.reference.tools.compiler.como]] +[[b2.reference.tools.compiler.como]] = Comeau C/C++ Compiler The `como-linux` and the `como-win` modules supports the diff --git a/src/tools/cray.jam b/src/tools/cray.jam index b8f1447e3b..ba95e9d039 100644 --- a/src/tools/cray.jam +++ b/src/tools/cray.jam @@ -204,7 +204,7 @@ rule check-prgenv-module ( toolset ) : toolset initialization failed : please load the PrgEnv-$(default-compiler) module next time ; # Do not abort, as suggested by: - # https://www.bfgroup.xyz/b2/manual/release/index.html#bbv2.extending.toolset_modules. + # https://www.bfgroup.xyz/b2/manual/release/index.html#b2.extending.toolset_modules. } } diff --git a/src/tools/cw.jam b/src/tools/cw.jam index 9078c7307c..dc80fbb8bb 100644 --- a/src/tools/cw.jam +++ b/src/tools/cw.jam @@ -5,7 +5,7 @@ #| tag::doc[] -[[bbv2.reference.tools.compiler.cw]] +[[b2.reference.tools.compiler.cw]] = Code Warrior The `cw` module support CodeWarrior compiler, originally produced by diff --git a/src/tools/dmc.jam b/src/tools/dmc.jam index bf308824a9..f7d99f8096 100644 --- a/src/tools/dmc.jam +++ b/src/tools/dmc.jam @@ -10,7 +10,7 @@ #| tag::doc[] -[[bbv2.reference.tools.compiler.dmc]] +[[b2.reference.tools.compiler.dmc]] = Digital Mars C/C++ Compiler The `dmc` module supports the http://www.digitalmars.com/[Digital Mars diff --git a/src/tools/embarcadero.jam b/src/tools/embarcadero.jam index a28b329303..57aad059a6 100644 --- a/src/tools/embarcadero.jam +++ b/src/tools/embarcadero.jam @@ -6,7 +6,7 @@ #| tag::doc[] -[[bbv2.reference.tools.compiler.embarcadero]] +[[b2.reference.tools.compiler.embarcadero]] = Embarcadero C++ Compiler The `embarcadero` module supports the 32-bit command line C++ compiler diff --git a/src/tools/emscripten.jam b/src/tools/emscripten.jam index 75f72e9f21..fa758e2c86 100644 --- a/src/tools/emscripten.jam +++ b/src/tools/emscripten.jam @@ -6,11 +6,11 @@ #| tag::doc[] -[[bbv2.reference.tools.compiler.emscripten]] +[[b2.reference.tools.compiler.emscripten]] = Emscripten The `emscripten` module supports https://emscripten.org[Emscripten toolchain] -and has the same options as link:#bbv2.reference.tools.compiler.clang-linux[`clang-linux`] +and has the same options as link:#b2.reference.tools.compiler.clang-linux[`clang-linux`] toolset. WARNING: Emscripten toolset defaults to static linkage because it is what @@ -18,7 +18,7 @@ generally expected and limitations of the toolchain itself (`wasm-ld` does not support `rpath`; js launcher does not respect `LD_LIBRARY_PATH`/`PATH` when looking for shared objects). -Additional link:#bbv2.overview.invocation.properties[features] +Additional link:#b2.overview.invocation.properties[features] supported by Emscripten toolset exclusively: `debug-symbols-source-map`:: diff --git a/src/tools/features/address-model-feature.jam b/src/tools/features/address-model-feature.jam index e6b416a297..8144823e0a 100644 --- a/src/tools/features/address-model-feature.jam +++ b/src/tools/features/address-model-feature.jam @@ -7,13 +7,13 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.address-model]]`address-model`:: +[[b2.builtin.features.address-model]]`address-model`:: *Allowed values:* `32`, `64`. + Specifies if 32-bit or 64-bit code should be generated by the compiler. Whether this feature works depends on the used compiler, its version, how the compiler is configured, and the values of the `architecture` `instruction-set` features. -Please see the section <> for details. +Please see the section <> for details. |# # end::doc[] diff --git a/src/tools/features/allow-feature.jam b/src/tools/features/allow-feature.jam index 913251dbfd..20dc245cfe 100644 --- a/src/tools/features/allow-feature.jam +++ b/src/tools/features/allow-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.allow]]`allow`:: +[[b2.builtin.features.allow]]`allow`:: This feature is used to allow specific generators to run. For example, Qt tools can only be invoked when Qt library is used. In that case, `qt` will be in usage requirement of the library. diff --git a/src/tools/features/architecture-feature.jam b/src/tools/features/architecture-feature.jam index a47c4bfdc3..3499328879 100644 --- a/src/tools/features/architecture-feature.jam +++ b/src/tools/features/architecture-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.architecture]]`architecture`:: +[[b2.builtin.features.architecture]]`architecture`:: *Allowed values:* `x86`, `ia64`, `sparc`, `power`, `mips`, `mips1`, `mips2`, `mips3`, `mips4`, `mips32`, `mips32r2`, `mips64`, `parisc`, `arm`, `s390x`, `loongarch`. diff --git a/src/tools/features/archiveflags-feature.jam b/src/tools/features/archiveflags-feature.jam index 017153631f..2f1c768d2a 100644 --- a/src/tools/features/archiveflags-feature.jam +++ b/src/tools/features/archiveflags-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.archiveflags]]`archiveflags`:: +[[b2.builtin.features.archiveflags]]`archiveflags`:: The value of this feature is passed without modification to the archiver tool when creating static libraries. diff --git a/src/tools/features/asmflags-feature.jam b/src/tools/features/asmflags-feature.jam index 39c203de82..a9bbd0e6f0 100644 --- a/src/tools/features/asmflags-feature.jam +++ b/src/tools/features/asmflags-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.asmflags]]`asmflags`:: +[[b2.builtin.features.asmflags]]`asmflags`:: The value of this feature is passed without modification to the assembler. |# # end::doc[] diff --git a/src/tools/features/build-feature.jam b/src/tools/features/build-feature.jam index 90e3b26922..b3938d4067 100644 --- a/src/tools/features/build-feature.jam +++ b/src/tools/features/build-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.build]]`build`:: +[[b2.builtin.features.build]]`build`:: *Allowed values:* `no` + Used to conditionally disable build of a target. If `no` is in diff --git a/src/tools/features/cflags-feature.jam b/src/tools/features/cflags-feature.jam index 2f0b9a53fc..178411dbb3 100644 --- a/src/tools/features/cflags-feature.jam +++ b/src/tools/features/cflags-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.cflags]]`cflags`; `cxxflags`; `linkflags`:: +[[b2.builtin.features.cflags]]`cflags`; `cxxflags`; `linkflags`:: The value of these features is passed without modification to the corresponding tools. For `cflags` that is both the C and {CPP} compilers, for `cxxflags` that is the {CPP} compiler, and for `linkflags` that is the linker. The features are diff --git a/src/tools/features/compileflags-feature.jam b/src/tools/features/compileflags-feature.jam index 9448542c2b..cda37bef0b 100644 --- a/src/tools/features/compileflags-feature.jam +++ b/src/tools/features/compileflags-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.compileflags]]`compileflags`:: +[[b2.builtin.features.compileflags]]`compileflags`:: The value of this feature is passed without modification to the corresponding tools. The values from the `compileflags` is applied to all compilation of any language for the tools. diff --git a/src/tools/features/conditional-feature.jam b/src/tools/features/conditional-feature.jam index 5eca038997..e508aee209 100644 --- a/src/tools/features/conditional-feature.jam +++ b/src/tools/features/conditional-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.conditional]]`conditional`:: +[[b2.builtin.features.conditional]]`conditional`:: Used to introduce indirect conditional requirements. The value should have the form: + diff --git a/src/tools/features/coverage-feature.jam b/src/tools/features/coverage-feature.jam index 6283f582bf..f1e5738104 100644 --- a/src/tools/features/coverage-feature.jam +++ b/src/tools/features/coverage-feature.jam @@ -8,7 +8,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.coverage]]`coverage`:: +[[b2.builtin.features.coverage]]`coverage`:: *Allowed values:* `off`, `on`. + Enables code instrumentation to generate coverage data during execution. diff --git a/src/tools/features/cxx-template-depth-feature.jam b/src/tools/features/cxx-template-depth-feature.jam index a0feea64aa..ec8d08589a 100644 --- a/src/tools/features/cxx-template-depth-feature.jam +++ b/src/tools/features/cxx-template-depth-feature.jam @@ -8,7 +8,7 @@ import numbers ; #| tag::doc[] -[[bbv2.builtin.features.cpp-template-depth]]`c++-template-depth`:: +[[b2.builtin.features.cpp-template-depth]]`c++-template-depth`:: *Allowed values:* Any positive integer. + Allows configuring a {CPP} compiler with the maximal template instantiation diff --git a/src/tools/features/cxxabi-feature.jam b/src/tools/features/cxxabi-feature.jam index 9ca0f2b055..0fae799450 100644 --- a/src/tools/features/cxxabi-feature.jam +++ b/src/tools/features/cxxabi-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.cxxabi]]`c++abi`:: +[[b2.builtin.features.cxxabi]]`c++abi`:: Selects a specific variant of C++ ABI if the compiler supports several. diff --git a/src/tools/features/cxxflags-feature.jam b/src/tools/features/cxxflags-feature.jam index fe4d972084..07f76cc2e0 100644 --- a/src/tools/features/cxxflags-feature.jam +++ b/src/tools/features/cxxflags-feature.jam @@ -7,8 +7,8 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.cxxflags]]`cxxflags`:: -See <`>>. +[[b2.builtin.features.cxxflags]]`cxxflags`:: +See <`>>. |# # end::doc[] diff --git a/src/tools/features/cxxstd-feature.jam b/src/tools/features/cxxstd-feature.jam index fb1d0dc947..2ab5314592 100644 --- a/src/tools/features/cxxstd-feature.jam +++ b/src/tools/features/cxxstd-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.cxxstd]]`cxxstd`:: +[[b2.builtin.features.cxxstd]]`cxxstd`:: *Allowed values*: `98`, `03`, `0x`, `11`, `1y`, `14`, `1z`, `17`, `2a`, `20`, `2b`, `23`, `2c`, `26`, `latest`. + @@ -33,7 +33,7 @@ feature.feature cxxstd #| tag::doc[] -[[bbv2.builtin.features.cxxstd-dialect]]`cxxstd-dialect`:: +[[b2.builtin.features.cxxstd-dialect]]`cxxstd-dialect`:: *Subfeature of* `cxxstd` + *Allowed values*: `iso`, `gnu`, `ms`. diff --git a/src/tools/features/debug-feature.jam b/src/tools/features/debug-feature.jam index 197ef74003..f7171b45fc 100644 --- a/src/tools/features/debug-feature.jam +++ b/src/tools/features/debug-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.debug-symbols]]`debug-symbols`:: +[[b2.builtin.features.debug-symbols]]`debug-symbols`:: *Allowed values:* `on`, `off`. + Specifies if produced object files, executables, and libraries should include @@ -23,7 +23,7 @@ feature.feature debug-symbols #| tag::prof-doc[] -[[bbv2.builtin.features.profiling]]`profiling`:: +[[b2.builtin.features.profiling]]`profiling`:: *Allowed values:* `off`, `on`. + Enables generation of extra code to write profile information. diff --git a/src/tools/features/define-feature.jam b/src/tools/features/define-feature.jam index 497bc829f1..69134d42de 100644 --- a/src/tools/features/define-feature.jam +++ b/src/tools/features/define-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.define]]`define`:: +[[b2.builtin.features.define]]`define`:: Specifies a preprocessor symbol that should be defined on the command line. You may either specify just the symbol, which will be defined without any value, or both the symbol and the value, separated by equal sign. @@ -20,7 +20,7 @@ feature.feature define #| tag::undef-doc[] -[[bbv2.builtin.features.undef]]`undef`:: +[[b2.builtin.features.undef]]`undef`:: Specifies a preprocessor symbol to undefine. |# # end::undef-doc[] diff --git a/src/tools/features/dependency-feature.jam b/src/tools/features/dependency-feature.jam index 61a075fc4e..96f15b636b 100644 --- a/src/tools/features/dependency-feature.jam +++ b/src/tools/features/dependency-feature.jam @@ -21,7 +21,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.dependency]]`dependency`:: +[[b2.builtin.features.dependency]]`dependency`:: Introduces a dependency on the target named by the value of this feature (so it will be brought up-to-date whenever the target being declared is). The dependency is not used in any other way. @@ -34,7 +34,7 @@ feature.feature dependency #| tag::impl-doc[] -[[bbv2.builtin.features.implicit-dependency]]`implicit-dependency`:: +[[b2.builtin.features.implicit-dependency]]`implicit-dependency`:: Indicates that the target named by the value of this feature may produce files that are included by the sources of the target being declared. See the section <> for more information. @@ -47,7 +47,7 @@ feature.feature implicit-dependency #| tag::use-doc[] -[[bbv2.builtin.features.use]]`use`:: +[[b2.builtin.features.use]]`use`:: Introduces a dependency on the target named by the value of this feature (so it will be brought up-to-date whenever the target being declared is), and adds its usage requirements to the build properties of the target being declared. The diff --git a/src/tools/features/dll-feature.jam b/src/tools/features/dll-feature.jam index 00ee96fdd9..521a32823a 100644 --- a/src/tools/features/dll-feature.jam +++ b/src/tools/features/dll-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.dll-path]]`dll-path` (_Unix_ only):: +[[b2.builtin.features.dll-path]]`dll-path` (_Unix_ only):: *Allowed values:* A directory path to shared libraries. + Specifies an additional directory where the system should look for shared @@ -17,9 +17,9 @@ WARNING: Note that a relative path will be prepended with the directory of the r `jam` file - as supplied on the `b2` command line - thus _severely_ limiting its practical use!. + -Please see the link:#bbv2.faq.dll-path[FAQ entry on the +Please see the link:#b2.faq.dll-path[FAQ entry on the `dll-path` and `hardcode-dll-paths`] for details, and the -link:#bbv2.builtin.features.hardcode-dll-paths[`hardcode-dll-paths`] feature +link:#b2.builtin.features.hardcode-dll-paths[`hardcode-dll-paths`] feature to automatically add paths for development. |# # end::doc[] @@ -30,11 +30,11 @@ feature.feature dll-path #| tag::hardcode-doc[] -[[bbv2.builtin.features.hardcode-dll-paths]]`hardcode-dll-paths` (_Unix_ only):: +[[b2.builtin.features.hardcode-dll-paths]]`hardcode-dll-paths` (_Unix_ only):: *Allowed values:* `true`, `false`. + -*Defaults to:* `true`(link:#bbv2.reference.rules.exe[`exe`]), - `false`(link:#bbv2.reference.rules.install[`install`]) + -*Ignored for:* link:#bbv2.reference.rules.lib[`lib`] +*Defaults to:* `true`(link:#b2.reference.rules.exe[`exe`]), + `false`(link:#b2.reference.rules.install[`install`]) + +*Ignored for:* link:#b2.reference.rules.lib[`lib`] + When an ``exe``cutable is built with `true` (default), @@ -42,14 +42,14 @@ the target binary will be linked with an _rpath list_ that contains all the paths to the directories of used shared libraries. + When a target is ``install``ed with `true`, those same -paths, and any added with link:bbv2.builtin.features.dll-path[``], +paths, and any added with link:b2.builtin.features.dll-path[``], are propagated through to the resulting binary. + The purpose of this feature is to aid development; the resulting executable (`exe` - but not `install` target) can by default be run, without changing system paths to shared libraries or installing the libraries to system paths. + -Please see the <> for details. +Please see the <> for details. |# # end::hardcode-doc[] @@ -67,7 +67,7 @@ feature.feature xdll-path #| tag::def-doc[] -[[bbv2.builtin.features.def-file]]`def-file`:: +[[b2.builtin.features.def-file]]`def-file`:: Provides a means to specify def-file for windows DLLs. |# # end::def-doc[] @@ -78,7 +78,7 @@ feature.feature def-file #| tag::suppress-doc[] -[[bbv2.builtin.features.suppress-import-lib]]`suppress-import-lib`:: +[[b2.builtin.features.suppress-import-lib]]`suppress-import-lib`:: Suppresses creation of import library by the linker. |# # end::suppress-doc[] diff --git a/src/tools/features/exception-feature.jam b/src/tools/features/exception-feature.jam index c24c10a81d..23e7576ed7 100644 --- a/src/tools/features/exception-feature.jam +++ b/src/tools/features/exception-feature.jam @@ -9,7 +9,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.exception-handling]]`exception-handling`:: +[[b2.builtin.features.exception-handling]]`exception-handling`:: *Allowed values:* `on`, `off`. + Disables exceptions. @@ -22,7 +22,7 @@ feature.feature exception-handling #| tag::asynch-doc[] -[[bbv2.builtin.features.asynch-exceptions]]`asynch-exceptions`:: +[[b2.builtin.features.asynch-exceptions]]`asynch-exceptions`:: *Allowed values:* `off`, `on`. + Selects whether there is support for asynchronous EH (e.g. catching SEGVs). @@ -35,7 +35,7 @@ feature.feature asynch-exceptions #| tag::doc[] -[[bbv2.builtin.features.extern-c-nothrow]]`extern-c-nothrow`:: +[[b2.builtin.features.extern-c-nothrow]]`extern-c-nothrow`:: *Allowed values:* `off`, `on`. + Selects whether all `extern "C"` functions are considered `nothrow` by default. diff --git a/src/tools/features/fflags-feature.jam b/src/tools/features/fflags-feature.jam index 3c58f21074..ee9be0a037 100644 --- a/src/tools/features/fflags-feature.jam +++ b/src/tools/features/fflags-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.fflags]]`fflags`:: +[[b2.builtin.features.fflags]]`fflags`:: The value of this feature is passed without modification to the tool when compiling Fortran sources. diff --git a/src/tools/features/file-feature.jam b/src/tools/features/file-feature.jam index 2a00b6e902..1578ccacb5 100644 --- a/src/tools/features/file-feature.jam +++ b/src/tools/features/file-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.file]]`file`:: +[[b2.builtin.features.file]]`file`:: When used in requirements of a prebuilt library target this feature specifies the path to the library file. See <> for examples. diff --git a/src/tools/features/find-lib-feature.jam b/src/tools/features/find-lib-feature.jam index 84e07e5819..bd1ed923e9 100644 --- a/src/tools/features/find-lib-feature.jam +++ b/src/tools/features/find-lib-feature.jam @@ -7,8 +7,8 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.find-shared-library]]`find-shared-library`:: -Adds a shared library to link to. Usually link:#bbv2.tasks.libraries[`lib`] +[[b2.builtin.features.find-shared-library]]`find-shared-library`:: +Adds a shared library to link to. Usually link:#b2.tasks.libraries[`lib`] targets should be preferred over using this feature. |# # end::doc[] @@ -19,8 +19,8 @@ feature.feature find-shared-library #| tag::doc[] -[[bbv2.builtin.features.find-static-library]]`find-static-library`:: -Adds a static library to link to. Usually link:#bbv2.tasks.libraries[`lib`] +[[b2.builtin.features.find-static-library]]`find-static-library`:: +Adds a static library to link to. Usually link:#b2.tasks.libraries[`lib`] targets should be preferred over using this feature. |# # end::doc[] @@ -31,7 +31,7 @@ feature.feature find-static-library #| tag::path-doc[] -[[bbv2.builtin.features.library-path]]`library-path`:: +[[b2.builtin.features.library-path]]`library-path`:: Adds to the list of directories which will be used by the linker to search for libraries. diff --git a/src/tools/features/flags-feature.jam b/src/tools/features/flags-feature.jam index 56dec0cc8c..f317f73d72 100644 --- a/src/tools/features/flags-feature.jam +++ b/src/tools/features/flags-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.flags]]`flags`:: +[[b2.builtin.features.flags]]`flags`:: This feature is used for generic, i.e. non-language specific, flags for tools. The value of this feature is passed without modification to the tool that will build the target. diff --git a/src/tools/features/force-include-feature.jam b/src/tools/features/force-include-feature.jam index 8d98374a30..e25c34a772 100644 --- a/src/tools/features/force-include-feature.jam +++ b/src/tools/features/force-include-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.force-include]]`force-include`:: +[[b2.builtin.features.force-include]]`force-include`:: Specifies an include path that has to be included in a way like if `#include "file"` appeared as the first line of every target's source file. diff --git a/src/tools/features/include-feature.jam b/src/tools/features/include-feature.jam index 254dcbfe98..1de436bfb8 100644 --- a/src/tools/features/include-feature.jam +++ b/src/tools/features/include-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.include]]`include`:: +[[b2.builtin.features.include]]`include`:: Specifies an additional include path that is to be passed to C and {CPP} compilers. diff --git a/src/tools/features/instruction-set-feature.jam b/src/tools/features/instruction-set-feature.jam index ad3aadb832..3563e420f9 100644 --- a/src/tools/features/instruction-set-feature.jam +++ b/src/tools/features/instruction-set-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.instruction-set]]`instruction-set`:: +[[b2.builtin.features.instruction-set]]`instruction-set`:: *Allowed values:* depends on the used toolset. + Specifies for which specific instruction set the code should be generated. The @@ -16,7 +16,7 @@ sets. + While B2 allows a large set of possible values for this features, whether a given value works depends on which compiler you use. Please see -the section <> for details. +the section <> for details. |# # end::doc[] diff --git a/src/tools/features/library-feature.jam b/src/tools/features/library-feature.jam index 0db67fe362..75459cdd64 100644 --- a/src/tools/features/library-feature.jam +++ b/src/tools/features/library-feature.jam @@ -7,9 +7,9 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.library]]`library`:: +[[b2.builtin.features.library]]`library`:: This feature is almost equivalent to the -<`>> feature, except that it takes +<`>> feature, except that it takes effect only for linking. When you want to link all targets in a Jamfile to certain library, the `` feature is preferred over `X` -- the latter will add the library to all targets, even those that have nothing to do diff --git a/src/tools/features/linemarkers-feature.jam b/src/tools/features/linemarkers-feature.jam index 0808d53897..0bbc034628 100644 --- a/src/tools/features/linemarkers-feature.jam +++ b/src/tools/features/linemarkers-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.linemarkers]]`linemarkers`:: +[[b2.builtin.features.linemarkers]]`linemarkers`:: *Allowed values:* `off`. + On preprocessing targets changes behavior to emit/omit line directives diff --git a/src/tools/features/link-feature.jam b/src/tools/features/link-feature.jam index 86cb86d094..a8742110e9 100644 --- a/src/tools/features/link-feature.jam +++ b/src/tools/features/link-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.link]]`link`:: +[[b2.builtin.features.link]]`link`:: *Allowed values:* `shared`, `static` + Controls how libraries are built. diff --git a/src/tools/features/linkflags-feature.jam b/src/tools/features/linkflags-feature.jam index 266aed50d2..3d3942d6f8 100644 --- a/src/tools/features/linkflags-feature.jam +++ b/src/tools/features/linkflags-feature.jam @@ -7,8 +7,8 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.linkflags]]`linkflags`:: -See <`>>. +[[b2.builtin.features.linkflags]]`linkflags`:: +See <`>>. |# # end::doc[] diff --git a/src/tools/features/local-visibility-feature.jam b/src/tools/features/local-visibility-feature.jam index 373a2c2346..c2dd99c1c2 100644 --- a/src/tools/features/local-visibility-feature.jam +++ b/src/tools/features/local-visibility-feature.jam @@ -7,11 +7,11 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.local-visibility]]`local-visibility`:: +[[b2.builtin.features.local-visibility]]`local-visibility`:: *Allowed values:* `global`, `protected`, `hidden`. + This feature has the same effect as the -<> feature but is intended +<> feature but is intended to be used by targets that require a particular symbol visibility. Unlike the `visibility` feature, `local-visibility` is not inherited by the target dependencies and only affects the target to which it is applied. diff --git a/src/tools/features/location-feature.jam b/src/tools/features/location-feature.jam index 2730199a18..f5f5b82dc3 100644 --- a/src/tools/features/location-feature.jam +++ b/src/tools/features/location-feature.jam @@ -7,9 +7,9 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.location]]`location`:: +[[b2.builtin.features.location]]`location`:: Specifies the build directory for a target. The feature is used primarily with -<`>> rule. +<`>> rule. |# # end::doc[] diff --git a/src/tools/features/location-prefix-feature.jam b/src/tools/features/location-prefix-feature.jam index b60d07215e..e644113466 100644 --- a/src/tools/features/location-prefix-feature.jam +++ b/src/tools/features/location-prefix-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.location-prefix]]`location-prefix`:: +[[b2.builtin.features.location-prefix]]`location-prefix`:: Sets the build directory for a target as the project’s build directory prefixed with the value of this feature. See section <> for an example. diff --git a/src/tools/features/lto-feature.jam b/src/tools/features/lto-feature.jam index 359c2f99b0..3d82380145 100644 --- a/src/tools/features/lto-feature.jam +++ b/src/tools/features/lto-feature.jam @@ -7,12 +7,12 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.lto]]`lto`:: +[[b2.builtin.features.lto]]`lto`:: *Allowed values:* `on`. + Enables link time optimizations (also known as interprocedural optimizations or -whole-program optimizations). Currently supported toolsets are <>, -clang and <>. The feature is optional. +whole-program optimizations). Currently supported toolsets are >, +clang and <>. The feature is optional. |# # end::doc[] @@ -22,7 +22,7 @@ feature.feature lto #| tag::doc[] -[[bbv2.builtin.features.lto-mode]]`lto-mode`:: +[[b2.builtin.features.lto-mode]]`lto-mode`:: *Subfeature of* `lto` + *Allowed values:* `full`, `thin`, `fat`. diff --git a/src/tools/features/name-feature.jam b/src/tools/features/name-feature.jam index 97998ad286..dc88904a0c 100644 --- a/src/tools/features/name-feature.jam +++ b/src/tools/features/name-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.name]]`name`:: +[[b2.builtin.features.name]]`name`:: When used in requirements of a prebuilt library target this feature specifies the name of the library (the name of the library file without any platform-specific suffixes or prefixes). See <> for examples. diff --git a/src/tools/features/objcflags-feature.jam b/src/tools/features/objcflags-feature.jam index b94e6f1e01..0c9df31ec4 100644 --- a/src/tools/features/objcflags-feature.jam +++ b/src/tools/features/objcflags-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.mflags]]`mflags`:: +[[b2.builtin.features.mflags]]`mflags`:: The value of this feature is passed without modification to the tool when compiling Objective C sources. @@ -20,7 +20,7 @@ feature.feature mflags #| tag::doc[] -[[bbv2.builtin.features.mmflags]]`mmflags`:: +[[b2.builtin.features.mmflags]]`mmflags`:: The value of this feature is passed without modification to the tool when compiling Objective {CPP} sources. diff --git a/src/tools/features/optimization-feature.jam b/src/tools/features/optimization-feature.jam index ad1b817a05..f14f04667e 100644 --- a/src/tools/features/optimization-feature.jam +++ b/src/tools/features/optimization-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.optimization]]`optimization`:: +[[b2.builtin.features.optimization]]`optimization`:: *Allowed values:* `off`, `speed`, `space`, 'minimal', 'debug'. + Enables optimization. `speed` optimizes for faster code, `space` optimizes for @@ -21,7 +21,7 @@ feature.feature optimization #| tag::inline-doc[] -[[bbv2.builtin.features.inlining]]`inlining`:: +[[b2.builtin.features.inlining]]`inlining`:: *Allowed values:* `off`, `on`, `full`. + Enables inlining. @@ -34,7 +34,7 @@ feature.feature inlining #| tag::vector-doc[] -[[bbv2.builtin.features.vectorize]]`vectorize`:: +[[b2.builtin.features.vectorize]]`vectorize`:: *Allowed values:* `off`, `on`, `full`. + Enables vectorization. diff --git a/src/tools/features/os-feature.jam b/src/tools/features/os-feature.jam index a2df7be31a..ca8661a4fd 100644 --- a/src/tools/features/os-feature.jam +++ b/src/tools/features/os-feature.jam @@ -76,7 +76,7 @@ feature.set-default host-os : [ default-host-os ] ; #| tag::doc[] -[[bbv2.builtin.features.target-os]]`target-os`:: +[[b2.builtin.features.target-os]]`target-os`:: *Allowed values:* `aix`, `android`, `appletv`, `bsd`, `cygwin`, `darwin`, `freebsd`, `haiku`, `hpux`, `iphone`, `linux`, `netbsd`, `openbsd`, `osf`, `qnx`, `qnxnto`, `sgi`, `solaris`, `unix`, `unixware`, `windows`, `vms`, diff --git a/src/tools/features/relevant-feature.jam b/src/tools/features/relevant-feature.jam index 417feee8cd..8a3c6093d3 100644 --- a/src/tools/features/relevant-feature.jam +++ b/src/tools/features/relevant-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.relevant]]`relevant`:: +[[b2.builtin.features.relevant]]`relevant`:: *Allowed values:* the name of any feature. + Indicates which other features are relevant for a given target. It is usually diff --git a/src/tools/features/response-file-feature.jam b/src/tools/features/response-file-feature.jam index 2aaca0e77b..e2e2dd907f 100644 --- a/src/tools/features/response-file-feature.jam +++ b/src/tools/features/response-file-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.response-file]]`response-file`:: +[[b2.builtin.features.response-file]]`response-file`:: *Allowed values:* `auto`, `file`, `contents`. + Controls whether a response file is used, or not, during the build of the diff --git a/src/tools/features/rtti-feature.jam b/src/tools/features/rtti-feature.jam index f767831c62..73aef105ae 100644 --- a/src/tools/features/rtti-feature.jam +++ b/src/tools/features/rtti-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.rtti]]`rtti`:: +[[b2.builtin.features.rtti]]`rtti`:: *Allowed values:* `on`, `off`. + Disables run-time type information. diff --git a/src/tools/features/runtime-feature.jam b/src/tools/features/runtime-feature.jam index b27faff7f3..f5a9300c97 100644 --- a/src/tools/features/runtime-feature.jam +++ b/src/tools/features/runtime-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.runtime-debugging]]`runtime-debugging`:: +[[b2.builtin.features.runtime-debugging]]`runtime-debugging`:: *Allowed values:* `on`, `off`. + Specifies whether produced object files, executables, and libraries should @@ -24,7 +24,7 @@ feature.feature runtime-debugging #| tag::doc[] -[[bbv2.builtin.features.runtime-link]]`runtime-link`:: +[[b2.builtin.features.runtime-link]]`runtime-link`:: *Allowed values:* `shared`, `static` + Controls if a static or shared C/{CPP} runtime should be used. There are some diff --git a/src/tools/features/sanitizers-feature.jam b/src/tools/features/sanitizers-feature.jam index e7bf8097c0..8f8c54dbb2 100644 --- a/src/tools/features/sanitizers-feature.jam +++ b/src/tools/features/sanitizers-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::addr-doc[] -[[bbv2.builtin.features.address-sanitizer]]`address-sanitizer`:: +[[b2.builtin.features.address-sanitizer]]`address-sanitizer`:: *Allowed values:* `on`, `norecover`. + Enables address sanitizer. Value `norecover` disables recovery for the @@ -21,7 +21,7 @@ feature.feature address-sanitizer #| tag::leak-doc[] -[[bbv2.builtin.features.leak-sanitizer]]`leak-sanitizer`:: +[[b2.builtin.features.leak-sanitizer]]`leak-sanitizer`:: *Allowed values:* `on`, `norecover`. + Enables leak sanitizer. Value `norecover` disables recovery for the @@ -35,7 +35,7 @@ feature.feature leak-sanitizer #| tag::thread-doc[] -[[bbv2.builtin.features.thread-sanitizer]]`thread-sanitizer`:: +[[b2.builtin.features.thread-sanitizer]]`thread-sanitizer`:: *Allowed values:* `on`, `norecover`. + Enables thread sanitizer. Value `norecover` disables recovery for the @@ -49,7 +49,7 @@ feature.feature thread-sanitizer #| tag::undef-doc[] -[[bbv2.builtin.features.undefined-sanitizer]]`undefined-sanitizer`:: +[[b2.builtin.features.undefined-sanitizer]]`undefined-sanitizer`:: *Allowed values:* `on`, `norecover`. + Enables undefined behavior sanitizer. Value `norecover` disables recovery for diff --git a/src/tools/features/search-feature.jam b/src/tools/features/search-feature.jam index cee5622f71..3eece064d6 100644 --- a/src/tools/features/search-feature.jam +++ b/src/tools/features/search-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.search]]`search`:: +[[b2.builtin.features.search]]`search`:: When used in requirements of a prebuilt library target this feature adds to the list of directories to search for the library file. See <> for examples. diff --git a/src/tools/features/source-feature.jam b/src/tools/features/source-feature.jam index 3725cfd53d..44298dde4a 100644 --- a/src/tools/features/source-feature.jam +++ b/src/tools/features/source-feature.jam @@ -7,13 +7,13 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.source]]`source`:: +[[b2.builtin.features.source]]`source`:: The `X` property has the same effect on building a target as putting X in the list of sources. It is useful when you want to add the same source to all targets in the project (you can put `` in requirements) or to conditionally include a source (using conditional requirements, see the section <>. See also the -<`>> feature. +<`>> feature. |# # end::doc[] diff --git a/src/tools/features/stdlib-feature.jam b/src/tools/features/stdlib-feature.jam index 4b83021d56..c97e917982 100644 --- a/src/tools/features/stdlib-feature.jam +++ b/src/tools/features/stdlib-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.stdlib]]`stdlib`:: +[[b2.builtin.features.stdlib]]`stdlib`:: *Allowed values*: `native`, `gnu`, `gnu11`, `libc++`, `sun-stlport`, `apache`. + Specifies C++ standard library to link to and in some cases the library ABI to diff --git a/src/tools/features/strip-feature.jam b/src/tools/features/strip-feature.jam index 60f4c1a35d..1266ba1667 100644 --- a/src/tools/features/strip-feature.jam +++ b/src/tools/features/strip-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.strip]]`strip`:: +[[b2.builtin.features.strip]]`strip`:: *Allowed values:* `off`, `on`. + Controls whether the binary should be stripped -- that is have everything not diff --git a/src/tools/features/tag-feature.jam b/src/tools/features/tag-feature.jam index e11a3bd58f..329d94536a 100644 --- a/src/tools/features/tag-feature.jam +++ b/src/tools/features/tag-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.tag]]`tag`:: +[[b2.builtin.features.tag]]`tag`:: Used to customize the name of the generated files. The value should have the form: + diff --git a/src/tools/features/threadapi-feature.jam b/src/tools/features/threadapi-feature.jam index 2eec99da9e..db1ef06c83 100644 --- a/src/tools/features/threadapi-feature.jam +++ b/src/tools/features/threadapi-feature.jam @@ -10,7 +10,7 @@ import features/os-feature ; #| tag::doc[] -[[bbv2.builtin.features.threadapi]]`threadapi`:: +[[b2.builtin.features.threadapi]]`threadapi`:: *Allowed values:* `pthread`, `win32`. + Selects threading implementation. The default is `win32` if `` is diff --git a/src/tools/features/threading-feature.jam b/src/tools/features/threading-feature.jam index c199057d0a..3ceb25ece9 100644 --- a/src/tools/features/threading-feature.jam +++ b/src/tools/features/threading-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.threading]]`threading`:: +[[b2.builtin.features.threading]]`threading`:: *Allowed values:* `single`, `multi` + Controls if the project should be built in multi-threaded mode. This feature diff --git a/src/tools/features/toolset-feature.jam b/src/tools/features/toolset-feature.jam index 7e9c6c2385..a57c05f9d0 100644 --- a/src/tools/features/toolset-feature.jam +++ b/src/tools/features/toolset-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.toolset]]`toolset`:: +[[b2.builtin.features.toolset]]`toolset`:: *Allowed values:* any of the toolset modules. + Selects the toolset that will be used to build binary targets. The full list of diff --git a/src/tools/features/translate-path-feature.jam b/src/tools/features/translate-path-feature.jam index c99f4655d3..484ad88678 100644 --- a/src/tools/features/translate-path-feature.jam +++ b/src/tools/features/translate-path-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.translate-path]]`translate-path`:: +[[b2.builtin.features.translate-path]]`translate-path`:: Used to introduce custom path feature translation. The value should have the form: + diff --git a/src/tools/features/user-interface-feature.jam b/src/tools/features/user-interface-feature.jam index 40f6ecd9b5..0e51686ba5 100644 --- a/src/tools/features/user-interface-feature.jam +++ b/src/tools/features/user-interface-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.user-interface]]`user-interface`:: +[[b2.builtin.features.user-interface]]`user-interface`:: *Allowed values:* `console`, `gui`, `wince`, `native`, `auto`. + Specifies the environment for the executable which affects the entry point diff --git a/src/tools/features/variant-feature.jam b/src/tools/features/variant-feature.jam index 13f73da974..e1b868644e 100644 --- a/src/tools/features/variant-feature.jam +++ b/src/tools/features/variant-feature.jam @@ -9,7 +9,7 @@ import property ; #| tag::doc[] -[[bbv2.builtin.features.variant]]`variant`:: +[[b2.builtin.features.variant]]`variant`:: *Allowed values:* `debug`, `release`, `profile`. + A feature combining several low-level features, making it easy to diff --git a/src/tools/features/version-feature.jam b/src/tools/features/version-feature.jam index e4c6acb0ac..0a4e97f2ce 100644 --- a/src/tools/features/version-feature.jam +++ b/src/tools/features/version-feature.jam @@ -7,9 +7,9 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.version]]`version`:: +[[b2.builtin.features.version]]`version`:: This feature isn't used by any of the builtin tools, but can be used, for -example, to adjust target's name via <`>> +example, to adjust target's name via <`>> feature. |# # end::doc[] diff --git a/src/tools/features/visibility-feature.jam b/src/tools/features/visibility-feature.jam index dadbc67436..08efa86275 100644 --- a/src/tools/features/visibility-feature.jam +++ b/src/tools/features/visibility-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.visibility]]`visibility`:: +[[b2.builtin.features.visibility]]`visibility`:: *Allowed values:* `global`, `protected`, `hidden`. + Specifies the default symbol visibility in compiled binaries. Not all values diff --git a/src/tools/features/warnings-feature.jam b/src/tools/features/warnings-feature.jam index a2eac78074..479c440833 100644 --- a/src/tools/features/warnings-feature.jam +++ b/src/tools/features/warnings-feature.jam @@ -7,7 +7,7 @@ import feature ; #| tag::doc[] -[[bbv2.builtin.features.warnings]]`warnings`:: +[[b2.builtin.features.warnings]]`warnings`:: *Allowed values:* `on`, `all`, `extra`, `pedantic`, `off`. + Controls the warning level of compilers. @@ -28,7 +28,7 @@ feature.feature warnings #| tag::doc[] -[[bbv2.builtin.features.warnings-as-errors]]`warnings-as-errors`:: +[[b2.builtin.features.warnings-as-errors]]`warnings-as-errors`:: *Allowed values:* `off`, `on`. + Makes it possible to treat warnings as errors and abort compilation on a diff --git a/src/tools/gcc.jam b/src/tools/gcc.jam index 9b6a4d0692..e8b1fb5133 100644 --- a/src/tools/gcc.jam +++ b/src/tools/gcc.jam @@ -13,7 +13,7 @@ #| tag::doc[] -[[bbv2.reference.tools.compiler.gcc]] +[[b2.reference.tools.compiler.gcc]] = GCC - GNU Compiler Collection The `gcc` module supports the http://gcc.gnu.org[GNU C++ compiler] on diff --git a/src/tools/hp_cxx.jam b/src/tools/hp_cxx.jam index f0ad537f8d..82d08d225e 100644 --- a/src/tools/hp_cxx.jam +++ b/src/tools/hp_cxx.jam @@ -5,7 +5,7 @@ #| tag::doc[] -[[bbv2.reference.tools.compiler.hp_cxx]] +[[b2.reference.tools.compiler.hp_cxx]] = HP C++ Compiler for Tru64 Unix The `hp_cxx` modules supports the diff --git a/src/tools/intel.jam b/src/tools/intel.jam index 6b1e1d6bf4..f7e5baa0fe 100644 --- a/src/tools/intel.jam +++ b/src/tools/intel.jam @@ -5,7 +5,7 @@ #| tag::doc[] -[[bbv2.reference.tools.compiler.intel]] +[[b2.reference.tools.compiler.intel]] = Intel C++ The `intel-*` modules support the Intel C++ command-line compiler. diff --git a/src/tools/msvc.jam b/src/tools/msvc.jam index c210b93b30..2f6b91594b 100644 --- a/src/tools/msvc.jam +++ b/src/tools/msvc.jam @@ -15,7 +15,7 @@ #| tag::doc[] -[[bbv2.reference.tools.compiler.msvc]] +[[b2.reference.tools.compiler.msvc]] = Microsoft Visual C++ The `msvc` module supports the @@ -129,7 +129,7 @@ The filename of the target platform specific environment setup script to run before invoking any of the tools defined in this toolset. If not specified the global environment setup script is used. -[[bbv2.reference.tools.compiler.msvc.64]] +[[b2.reference.tools.compiler.msvc.64]] == 64-bit support Starting with version 8.0, Microsoft Visual Studio can generate binaries @@ -174,7 +174,7 @@ of those options depending on the value of the`instruction-set` feature. Starting with version 14.0, Microsoft Visual Studio can generate binaries using native arm64 tools to compile for x86, x86_64, and arm64. -[[bbv2.reference.tools.compiler.msvc.winrt]] +[[b2.reference.tools.compiler.msvc.winrt]] == Windows Runtime support Starting with version 11.0, Microsoft Visual Studio can produce binaries @@ -243,10 +243,10 @@ type.register MANIFEST : manifest ; #| tag::embed-doc[] -[[bbv2.builtin.features.embed-manifest]]`embed-manifest`:: +[[b2.builtin.features.embed-manifest]]`embed-manifest`:: *Allowed values:* `on`, `off`. + -This feature is specific to the `msvc` toolset (see <>), +This feature is specific to the `msvc` toolset (see <>), and controls whether the manifest files should be embedded inside executables and shared libraries, or placed alongside them. This feature corresponds to the IDE option found in the project settings dialog, under Configuration Properties @@ -258,8 +258,8 @@ feature.feature embed-manifest : on off : incidental propagated ; #| tag::embed-doc[] -[[bbv2.builtin.features.embed-manifest-file]]`embed-manifest-file`:: -This feature is specific to the `msvc` toolset (see <>), +[[b2.builtin.features.embed-manifest-file]]`embed-manifest-file`:: +This feature is specific to the `msvc` toolset (see <>), and controls which manifest files should be embedded inside executables and shared libraries. This feature corresponds to the IDE option found in the project settings dialog, under Configuration Properties -> Manifest Tool -> @@ -271,8 +271,8 @@ feature.feature embed-manifest-file : : free dependency ; #| tag::embed-doc[] -[[bbv2.builtin.features.embed-manifest-via]]`embed-manifest-via`:: -This feature is specific to the `msvc` toolset (see <>), +[[b2.builtin.features.embed-manifest-via]]`embed-manifest-via`:: +This feature is specific to the `msvc` toolset (see <>), and controls whether a manifest should be embedded via linker or manifest tool. |# # end::embed-doc[] diff --git a/src/tools/stage.jam b/src/tools/stage.jam index 17bb13219e..fea9df064f 100644 --- a/src/tools/stage.jam +++ b/src/tools/stage.jam @@ -8,7 +8,7 @@ #| tag::doc[] -[[bbv2.reference.modules.stage]] +[[b2.reference.modules.stage]] = stage This module defines the `install` rule, used to copy a set of targets to a single location. @@ -41,7 +41,7 @@ feature.feature : on : optional incidental ; #| tag::features-install-package-doc[] -[[bbv2.builtin.features.install-package]]`install-package`:: +[[b2.builtin.features.install-package]]`install-package`:: Specifies the name of the package to which installed files belong. This is used for default installation prefix on certain platforms. @@ -52,13 +52,13 @@ feature.feature install-package : : free ; #| tag::doc[] -[[bbv2.reference.modules.stage.add-install-dir]] +[[b2.reference.modules.stage.add-install-dir]] . `rule add-install-dir ( name : suffix ? : parent ? : options * )` + Defines a named installation directory. + For example, `add-install-dir foo : bar : baz ;` creates feature -<`>> and adds support for +<`>> and adds support for named directory `(foo)` to `install` rule. The rule will try to use the value of `` property if present, otherwise will fallback to `(baz)/bar`. + @@ -114,8 +114,8 @@ rule install-dir-names ( ) #| tag::features-install-prefix-doc[] -[[bbv2.builtin.features.install-prefix]]`install-`:: -Specifies installation prefix for <> targets. +[[b2.builtin.features.install-prefix]]`install-`:: +Specifies installation prefix for <> targets. These named installation prefixes are registered by default: + * `prefix`: `C:\` if `windows` is in the property set, @@ -144,7 +144,7 @@ These named installation prefixes are registered by default: * `mandir`: `(datarootdir)/man` If more are necessary, they could be added with -<>. +<>. |# # end::features-install-prefix-doc[] @@ -175,8 +175,8 @@ add-install-dir mandir : man : datarootdir ; #| tag::features-staging-prefix-doc[] -[[bbv2.builtin.features.staging-prefix]]`staging-prefix`:: -Specifies staging prefix for <> targets. +[[b2.builtin.features.staging-prefix]]`staging-prefix`:: +Specifies staging prefix for <> targets. If present, it will be used instead of the path to named directory `prefix`. Example: + @@ -724,7 +724,7 @@ that were registered with `package-suffix` option and also to construct + Available `flags`: + -* `staged`: take <> into +* `staged`: take <> into account. * `relative`: return the path to `name` relative to its base directory. @@ -856,7 +856,7 @@ local rule get-install-prefix ( property-set : package-name : flags * ) + Returns the package name that will be used for `install` targets when constructing installation location. The rule uses the value of -<`>> property if it's +<`>> property if it's present in `property-set`. Otherwise it deduces the package name using ``project-module``'s attributes. It traverses the project hierarchy up to the root searching for the first project with an id. If none is found, the base diff --git a/src/tools/sun.jam b/src/tools/sun.jam index d00b66814c..e284e041f2 100644 --- a/src/tools/sun.jam +++ b/src/tools/sun.jam @@ -6,7 +6,7 @@ #| tag::doc[] -[[bbv2.reference.tools.compiler.sun]] +[[b2.reference.tools.compiler.sun]] = Sun Studio The `sun` module supports the diff --git a/src/tools/vacpp.jam b/src/tools/vacpp.jam index b6930447b9..a12a4abb9f 100644 --- a/src/tools/vacpp.jam +++ b/src/tools/vacpp.jam @@ -6,7 +6,7 @@ #| tag::doc[] -[[bbv2.reference.tools.compiler.vacpp]] +[[b2.reference.tools.compiler.vacpp]] = IBM Visual Age The `vacpp` module supports the http://www.ibm.com/software/ad/vacpp[IBM