Home

Boost.Build V2 User Manual - LAR

1. EY Note rules called this way may accept at most 8 parameters Example rule filter f values local m CALLER_MODULE local result for v in values if modules call in m f v result v return result rule load module name filename search Load the indicated module if it is not already loaded module name Name of module to load filename partial path to file Defaults to module name jam search Directories in which to search for filename Defaults to BOOST_BUILD_PATH rule import module names rules opt rename opt Load the indicated module and import rule names into the current module Any members of rules opt will be available without qualification in the caller s module Any members of rename opt will be taken as the names of the rules in the caller s module in place of the names they have in the imported module If rules opt all rules from the indicated module are imported into the caller s module If rename opt is supplied it must have the same number of elements as rules opt EY Note The import rule is available without qualification in all modules Examples import path import path import path join import path native make native path make path rule clone rules source module target module 65 http www renderx com Reference Define exporte
2. It s possible to lookup a metataget by target id using the targets resolve reference function and the targets generate from reference function can both lookup and generate a metatarget The abstract target class has three immediate derived classes e project target that corresponds to a project and is not intended for further subclassing The generate method of this class builds all targets in the project that are not marked as explicit e main target corresponds to a target in a project and contains one or more target alternatives This class also should not be subclassed The generate method of this class selects an alternative to build and calls the generate method of that alternative e basic target corresponds to a specific target alternative This is base class with a number of derived classes The 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 construct method with the list of source virtual targets and the final properties The instances of the project target and 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 basic target are typically created when Jamfile calls a metatarget rule such as such as exe This name is historic and will be eventuall changed to metatarg
3. Issues an error if type is unknown rule set scanner type scanner Sets a scanner class that will be used for this type rule get scanner type property set Returns a scanner instance appropriate to type and property set rule base type Returns a base type for the given type or nothing in case the given type is not derived rule all bases type Returns the given type and all of its base types in order of their distance from type rule all derived type Returns the given type and all of its derived types in order of their distance from type rule is derived type base Returns true if type is equal to base or has base as its direct or indirect base 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 has already been specified for the type The suf fix parameter can be an empty string to indicate that no suffix should be used Note that this does not cause files with suffix to be automatically 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 register suffixes rule 12 rule change generated target suffix type properties suffix B 14 15 16
4. Try to work around at least one compiler bug with GCC and variable aliasing that causes crashes with hashing file cache entries Rene R Add We fno strict aliasing for QCC QNX to avoid the same aliasing crashes as in the general GCC 4 x series thanks to Niklas Angare for the fix Rene R On Windows let the child bjam commands inherit stdin as some commands assume it s available Rene R On Windows don t limit bjam output to ASCII as some tools output characters in extended character sets Rene R Isolate running of bjam tests to individual bjam instances to prevent possible spillover errors from one test affecting another test Separate the bjam used to run the tests vs the bjam being tested And add automatic re building of the bjam being tested Rene R Fix some possible overrun issues revealed by Fortify build Thanks to Steven Robbins for pointing out the issues Rene R Handle n and r escape sequences Vladimir P Minor edits to remove Wall warnings Rene R Dynamically adjust pwd buffer query size to allow for when PATH MAX is default defined instead of being provided by the system C library Rene R 3 2 fa 137 http www renderx com 3 2 fa Boost Jam Documentation Minor perf improvement for bjam by replacing hash function with faster version Only 1 diff for Boost tree Rene R Updated Boost Jam s error location reporting when parsing Jamfiles Now it reports the corr
5. exe test2 test2 cpp lt threading gt single exe test3 test3 cpp lt threading gt multi Here testi inherits the project requirements and will always be built in multi threaded mode The test2 target overrides the project s requirements and will always be built in single threaded mode In contrast the test 3 target removes a property from the project requirements and will be built either in single threaded or multi threaded mode depending on which variant is requested by the user Note that the removal of requirements is completely textual you need to specify exactly the same property to remove it Default Build The default build parameter is a set of properties to be used if the build request does not otherwise specify a value for features in the set For example exe hello hello cpp lt threading gt multi would build a multi threaded target unless the user explicitly requests a single threaded version The difference between the require ments and the default build is that the requirements cannot be overridden in any way 27 http www renderx com Overview Additional Information The ways a target is built can be so different that describing them using conditional requirements would be hard For example imagine that a library actually uses different source files depending on the toolset used to build it We can express this situation using target alternatives lib demangler dummy_demangler
6. A feature has a specific value only when building a target and there are two ways you can use that value e Use conditional requirements or indirect conditional requirements See the section called Requirements 26 e Define a custom generator and a custom main target type The custom generator can do arbitrary processing or properties See the Extender Manual 96 http www renderx com Frequently Asked Questions 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 twice with almost the same but differing properties For example exe a a cpp lt include gt usr local include exe b a cpp The above snippet requires two different compilations of a cpp which differ only in their include property Since the include feature is declared as free Boost Build does not create a separate build directory for each of its values and those two builds would both produce object files generated in the same build directory Ignoring this and compiling the file only once would be dangerous as different includes could potentially cause completely different code to be compiled To solve this issue you need to decide if the file should be compiled once or twice 1 To compile the file only once make sure that properties are the same for both target requests exe a a cpp lt include gt usr local include exe b a cpp lt i
7. INCLUDES foo c foo h foo o depends on foo c and foo h in this example Modifying Binding The six rules ALWAYS LEAVES NOCARE NOTFILE NOUPDATE and TEMPORARY modify the dependency graph so that bjam treats the targets differently during its target binding phase See Binding above Normally bjam updates a target if it is missing if its filesystem modification time is older than any of its dependencies recursively or if any of its dependencies are being updated This basic behavior can be changed by invoking the following rules ALWAYS rule ALWAYS targets Causes targets to be rebuilt regardless of whether they are up to date they must still be in the dependency graph This is used for the clean and uninstall targets as they have no dependencies and would otherwise appear never to need building It is best applied to targets that are also NOTFILE targets but it can also be used to force a real file to be updated as well LEAVES rule LEAVES targets Makes each of targets depend only on its leaf sources and not on any intermediate targets This makes it immune to its dependencies being updated as the leaf dependencies are those without their own dependencies and without updating actions This allows a target to be updated only if original source files change NOCARE rule NOCARE targets Causes bjam to ignore targets that neith
8. You can use several properties in the condition for example lib network network cpp lt toolset gt gcc lt optimization gt speed lt define gt USE_INLINE_ASSEMBLER 26 http www renderx com Overview A more powerful variant of conditional requirements is indirect conditional requirements You can provide a rule that will be called with the current build properties and can compute additional properties to be added For example lib network network cpp lt conditional gt my rule i rule my rule properties local result if lt toolset gt gcc lt optimization gt speed in properties result lt define gt USE_INLINE_ASSEMBLER return result This example is equivalent to the previous one but for complex cases indirect conditional requirements can be easier to write and understand Requirements explicitly specified for a target are usually combined with the requirements specified for the containing project You can cause a target to completely ignore a specific project requirement using the syntax by adding a minus sign before the property for example exe main main cpp lt define gt UNNECESSARY DEFINE This syntax is the only way to ignore free properties such as defines from a parent It can be also useful for ordinary properties Consider this example project test requirements lt threading gt multi exe testl testl cpp
9. linkflags Specifies additional command line options that will be passed to the linker 57 http www renderx com 3 2 fa Reference Borland C Compiler The borland module supports the command line C compiler included in C Builder 2006 product and earlier version of it running on Microsoft Windows The supported products are listed below The version reported by the command lines tools is also listed for reference e C Builder 2006 5 8 2 e CBuilderX 5 6 5 5 6 4 depending on release e CBuilder6 5 6 4 Free command line tools 5 5 1 The module is initialized using the following syntax using borland version ct compile command compiler options This statement may be repeated several times if you want to configure several versions of the compiler If the command is not specified Boost Build will search for a binary named bee32 in PATH The following options can be provided using lt opt ion name gt opt ion value syntax cflags Specifies additional compiler flags that will be used when compiling C sources cxxflags Specifies additional compiler flags that will be used when compiling C sources compileflags Specifies additional compiler flags that will be used when compiling both C and C sources linkflags Specifies additional command line options that will be passed to the linker Comeau C C Compiler The como linux and the como win modules supports the Comeau C C Compil
10. Change the suffix previously registered for this type properties combination If suffix is not yet specified sets it rule generated target suffix type property set Returns the suffix used when generating a file of type with the given properties 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 properties if no prefix for type has been specified yet The prefix parameter can be empty string to indicate that no prefix should be used Usage example library names use the lib prefix on unix 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 rule generated target prefix type property set 68 http www renderx com Reference Returns the prefix used when generating a file of type with the given properties 17 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 so will be tried 69 http www renderx com Reference Builtin classes Class abstract target Base class for all abstract targets class abstract target rule __init__ name project rule name
11. Determining common properties The common properties is a somewhat artificial term Those are the intermediate property set from which both the build request for dependencies and properties for building the target are derived Since default build and alternatives are already handled we have only two inputs build requests and requirements Here are the rules about common properties 1 2 6 Non free feature can have only one value A non conditional property in requirement in always present in common properties A property in build request is present in common properties unless 2 tells otherwise If either build request or requirements non conditional or conditional include an expandable property either composite or property with specified subfeature value the behaviour is equivalent to explicitly adding all expanded properties to build request or requirements If requirements include a conditional property and condiiton of this property is true in context of common properties then the conditional property should be in common properties as well If no value for a feature is given by other rules here it has default value in common properties Those rules are declarative they don t specify how to compute the common properties However they provide enough information for the user The important point is the handling of conditional requirements The condition can be satisfied either by property in 75
12. Updating rules treat arguments 1 and 2 as built targets and sources respectively while pure procedure rules can take arbitrary arguments When an updating rule is invoked its updating actions are added to those associated with its built targets 1 before the rule s procedure is run Later to build the targets in the updating phase commands are passed to the OS command shell with 1 and 2 replaced by bound versions of the target names See Binding above Rule invocation may be indirected through a variable S var fieldl field2 fieldN on target S var field1 field2 fieldN S var fieldl field2 fieldN on target var fieldl field2 fieldN The variable s value names the rule or rules to be invoked A rule is invoked for each element in the list of var s values The fields field1 field2 are passed as arguments for each invokation For the forms the return value is the concat enation of the return values for all of the invocations Action Modifiers The following action modifiers are understood actions bind vars vars will be replaced with bound values actions existing gt includes only source targets currently existing actions ignore The return status of the commands is ignored actions piecemeal commands are repeatedly invoked with a subset of gt small enough to fit in the command buffer on this OS 116 http www rend
13. W32_GETREG HKEY LOCAL MACHINE SOFTWARE Microsoft MicrosoftSDK Directories Install J Die j W32_GETREGNAMES rule W32_GETREGNAMES path result type Defined only for win32 platform It reads the registry of Windows path is the location of the information and result type is either subkeys or values For more information on path format and constraints please see W32_GETREG Depending on result type the rule returns one of the following subkeys Names of all direct subkeys of path values Names of values contained in registry key given by path The default value of the key appears in the returned list only if its value has been set in the registry 121 http www renderx com Boost Jam Documentation If result type is not recognized or requested data cannot be retrieved the rule returns an empty list Example local key HKEY_LOCAL_MACHINE SOFTWARE Microsoft Windows CurrentVersion App Paths local subkeys W32_GETREGNAMES S key subkeys for local subkey in subkeys local values W32_GETREGNAMES key subkey values for local value in values local data W32_GETREG S key subkey S value J ECHO Registry path S key S subkey S value S data SHELL rule SHELL command SHELL exec
14. unit test compile compile fail link link fail run run fail obj preprocessed glob glob tree project use project explicit always Creates an executable file See the section called Programs Creates an library file See the section called Libraries Installs built targets and other files See the section called Installing Creates an alias for other targets See the section called Alias Creates an executable that will be automatically run See the section called Testing Specialized rules for testing See the section called Testing Creates an object file Useful when a single source file must be compiled with special properties Creates an preprocessed source file The arguments follow the common syntax 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 lib tools I al glob cpp It is possible to also pass a second argument the list of exclude patterns The result will then include the list of files patching any of include patterns and not matching any of the exclude patterns For example lib tools all glob cpp file to exclude cpp bad cpp The glob t ree is similar to the glob except that it operates recursively from the directory of the containing Jamfile For example ECHO glob tree cpp evn 3 al will print the names of all C fil
15. Giving the root project the special name Jamroot ensures that Boost Build won t misinterpret a directory above it as the project root just because the directory contains a Jamfile 30 http www renderx com 3 2 fa Overview The Build Process When you ve described your targets you want Boost Build to run the right tools and create the needed targets This section will describe two things how you specify what to build and how the main targets are actually constructed The most important thing to note is that in Boost Build unlike other build tools the targets you declare do not correspond to specific files What you declare in a Jamfile is more like a metatarget Depending on the properties you specify on the command line each metatarget will produce a set of real targets corresponding to the requested properties It is quite possible that the same metatarget is built several times with different properties producing different files Tip This means that for Boost Build 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 Build Request The command line specifies which targets to build and with which properties For example b2 appl libl libl toolset gcc variant debug optimization full would build two targets app1 and lib1 lib1 with the specified properties You c
16. Returns the current working directory 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 Each pattern should be a non absolute path and can t contain or elements Each slash separated element of a pattern can contain the following special characters e matches any character 66 http www renderx com Reference e matches an arbitrary number of characters A file d e1 e2 e3 where d is in dirs matches the pattern p1 p2 p3 if and only if e1 matches p1 e2 matches p2 and so on For example glob cpp glob build Jamfile 12 rule glob tree roots patterns exclude patterns Recursive version of 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 B rule exists file Returns true if the specified file exists 14 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 wil
17. The primary use case is when you want the usage requirements such as include paths of some library to be applied but do not want to link to it Specify an additional directory where the system should look for shared libraries when the executable or shared library is run This feature only affects Unix compilers Plase see the section called Why are the dll path and hardcode dll paths properties useful in Frequently Asked Questions for details Controls automatic generation of dll path properties Allowed values t rue false This property is specific to Unix systems If an executable is built with lt hardcode d1l paths gt true the generated binary will contain the list of all the paths to the used shared libraries As the result the executable can be run without changing system paths to shared libraries or installing the libraries to system paths This is very conveni ent during development Plase see the FAQ entry for details Note that on Mac OSX the paths are unconditionally hardcoded by the linker and it is not possible to disable that behaviour The value of those features is passed without modification to the corresponding tools For cflags that is both the C and C compilers for cxxflags that is the C compiler and for Linkflags that is the linker The features are handy when you are trying to do something special that cannot be achieved by a higher level feature in Boost Build Specifies an additional include path t
18. Tutorial Conditions and alternatives Sometimes particular relationships need to be maintained among a target s build properties For example you might want to set specific define when a library is built as shared or when a target s release variant is built This can be achieved using condi tional requirements lib network network cpp lt link gt shared lt define gt NEWORK_LIB SHARED lt variant gt release lt define gt EXTRA_FAST In the example above whenever net work is built with lt link gt shared lt define gt NEWORK_LIB_SHARED will be in its properties too Also whenever its release variant is built lt define gt EXTRA_FAST will appear in its properties Sometimes the ways a target is built are so different that describing them using conditional requirements would be hard For example imagine that a library actually uses different source files depending on the toolset used to build it We can express this situation using target alternatives lib demangler dummy_demangler cpp alternative 1 lib demangler demangler_gcc cpp lt toolset gt gcc alternative 2 lib demangler demangler_msvc cpp lt toolset gt msvc alternative 3 When building demangler Boost Build will compare requirements for each alternative with build properties to find the best match For example when building with lt toolset gt gcc alternative 2 will be selected and when building with lt toolset gt msvc alternat
19. and they can be called using unqualified names 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 actions create file from another create file from another lt gt This specifies a named action called create file from another The text inside braces is the command to invoke The lt variable will be expanded to a list of generated files and the gt variable will be expanded to a list of source files To adjust the command line flexibly you can define a rule with the same name as the action and taking three parameters targets sources and properties For example rule create file from another targets sources properties if lt variant gt debug in properties OPTIONS on targets debug actions create file from another create file from another OPTIONS lt gt In this example the rule checks if a certain build property is specified If so it sets the variable OP IONS that is then used inside the action Note that the variables set on a target will be visible only inside actions building that target not globally Were they set globally using variable named OPTIONS in two unrelated actions would be impossible More details can be found in the Jam reference the section called Rules 18 http www renderx com Over
20. compiler to use See the section called C Compilers for a detailed list include Arbitrary string Additional include paths for C and C compilers define Arbitrary string Additional macro definitions for C and C compilers The string should be either SYMBOL or SYMBOL VALUE cxxflags Arbitrary string Custom options to pass to the C com piler cflags Arbitrary string Custom options to pass to the C compiler linkflags Arbitrary string Custom options to pass to the C linker runtime link shared static Determines if shared or static version of C and C runtimes should be used If you have more than one version of a given C toolset e g configured in user config jam or autodetected as happens with msvc you can request the specific version by passing toolset version as the value of the toolset feature for example toolset msvc 8 0 If a feature has a fixed set of values it can be specified more than once on the command line In which case everything will be built several times once for each specified value of a feature For example if you use b2 link static link shared threading single threading multi Then a total of 4 builds will be performed For convenience instead of specifying all requested values of a feature in separate command line elements you can separate the values with commas for example b2 link static shared threading single multi The comma has this special meaning only if t
21. lib a a cpp lt def file gt a def Actually this feature is already supported but anyway 1 Since the feature refers to a target it must be dependency feature def file free dependency 2 One of the toolsets that cares about DEF files is msvc The following line should be added to it flags msvce link DEF FILE lt def file gt 3 Since the DEF FILE variable is not used by the msvc link action we need to modify it to be actions link bind DEF_FILE LD DEF DEF FILE Note the bind DEF FILE part It tells bjam to translate the internal target name in DEF FILE to a corresponding filename in the link action Without it the expansion of DEF FILE would be a strange symbol that is not likely to make sense for the linker We are almost done but we should stop for a small workaround Add the following code to msvc jam rule link DEPENDS lt on S lt return DEF FILE This is needed to accomodate some bug in bjam which hopefully will be fixed one day Variants and composite features Sometimes you want to create a shortcut for some set of features For example release is a value of lt variant gt and is a shortcut for a set of features It is possible to define your own build variants For example 91 http www renderx com Extender Manual vari
22. noassert dist clean target Empty option when one wants to only specify a target The default builds the optimized executable Builds debugging versions of the executable When built they are placed in their own directory bin platform debug Normally the Jam language grammar parsing files are not regenerated This forces building of the grammar although it may not force the regeneration of the grammar parser If the parser is out of date it will be regenerated and subsequently built Enables Python integration given a path to the Python libraries Enables use of the Boehm Garbage Collector The build will look for the Boehm GC source in a poehm_gce subdirectory from the bjam sources Enables use of the DUMA Detect Uintended Memory Access debugging memory allocator The build expects to find the DUMA source files in a duma subdirectory from the bjam sources Indicates where the toolset used to build is located This option is passed in by the bootstrap build bat or build sh script For information prints out where it will put the built executable Disable debug assertions even if building the debug version of the executable Generate packages compressed archives as appropriate for distribution in the platform if possible Remove all the built executables and objects 114 http www renderx com 3 2 fa Boost Jam Documentation Language BJam has an interpreted procedural language Stat
23. orire irene Eere Enee E EEEa TEETE EEEE EEDE EELEE EEE ETENEE EESE E CEECEE EREE E E ane 45 E E E A A E E E E E 46 General Informatio eiia nenea bensndcocevaedeabiehid aoeedendenSbiend cch ESSEE ar KEES EE EEE EEES EEES 47 Builtin rules os sires are lian EA EEEE En EEEO EEEE EE EEEE ETE E E EAEE ERE E EEEREN EE EENES 48 B iltin KS YE IU 55505 oss Dots casteiabendeseh aiioviea babsed E EENDE EAE tcp EE EEE EEE EES EEEE STE TERESE AENA 50 Builtin tools riss veswgohssudtaahs snicabetoadasien onions oben Gegnas ss a e a EEEE A E E EEE a EEE EEREN a 54 Builtin modules 226 also benene sere nnie Erone ante EEEE TEIE EEEE ae EIEEE EEVEE dasa beneadedenese dines dlandarndevlss 64 Builtin classe S 5 roning eee gr en kE REE EEEE ARE EEEE ES ESEE EEEN EE EE EERE AE EE EEEE EEEE ER ETE 70 Build ProC SS iced sia shedion tise es eo rere res TEE EEEE EEE EEE LENEE EEEE RET EENEI uae undp LEVETTE EE TELT EEATT EKE RRE CETER EEEE PEE EUEN 75 DEMONS e a a nes e e E E S E E e E E cioatns Maen EEN ERE ENT 77 Extender Mantal i i cc satieciasedicgensentae dstsunencebiinsins rE EE vier oedwadnt incl EOE ESENE R EESE E EENE EEDE HEDERNE EA EES EEEE EEEn E VEn 81 Fat uge re ID Tr ke n UETA Ae E E E E E E austawen eaten cba EEE E EET ES ER ENE ERE Eee SEER 82 Example 1 40 1 generator us iesisniiaisecetebestonatuiadovepesamens rne sods EENE EEEE Aare ae hoe TETE EENS EEEE EEEE SE EEAS ETES 84 Target types era aor iskien Er e E E EE EEE EEE EE EEE E E E EE E EE EEE 85 LOOMS
24. www renderx com Common tasks Alias The alias rule gives an alternative name to a group of targets For example to give the name core to a group of three other targets with the following code alias core im reader writer Using core on the command line or in the source list of any other target is the same as explicitly using im reader and writer Another use of the alias rule is to change build properties For example if you want to use link statically to the Boost Threads library you can write the following alias threads boost thread boost_thread lt link gt static and use only the threads alias in your Jamfiles You can also specify usage requirements for the alias target If you write the following alias header only library lt include gt usr include header_only_library then using header_only_library in sources will only add an include path Also note that when an alias has sources their usage requirements are propagated as well For example lib libraryl libraryl cpp lt include gt library includel lib library2 library2 cpp lt include gt library include2 alias static_libraries libraryl library2 lt link gt static exe main main cpp static_libraries will compile main cpp with additional includes required for using the specified static libraries 37 http www renderx com Common tasks Installing This section describes various ways to
25. ANG SENELATOLS 5s sdssiewcessnd orir tesieni veninne EREE ENEE EE EEE EEEE EEEE EENES EVENE rer ea herrerne enker el EENE EEEE 87 Features ic ss orderne ERE NE een aeeubuitn acer EEEE EEE EEEE E EE OE OENE E EE REEE EE EEEE EE EESE 90 Maini target rules crer cost nere ek e reee enar EE ENEE EEEE TEE EREE EEE EKTE ETETE EEPE EREE EKUTNO CEEE NEE EENES 93 Toolset modules ispre serioa e a E e EE R S RE EERE E E a A EEE ES 94 Frequently Asked Questions soon generne gere e ETE EEKEREN EESE E E EE NEEESE EEE EEE VEEE EREE EEEE ERSEN 95 How do I get the current value of feature in Jamfile GW u u u ds sseeneeereeee ener ener ennen entreen ennen nerne rr ennen ennen ener 96 I am getting a Duplicate name of actual target error What does that mean W u u sssseseerereeerer renerne ener n ne 97 Accessing environment variables oser he EEN kE eE EEE EEE EE ere EE E E E TEE E Ea 99 How to contral properties Order sasicdshaveecessvescsngetenesads tensed poaules Seward ENK EEEE dh eee nere des kreere EEVEE RSS 100 How to control the library linking order On Unit 20 0 ceee cece cee ce ee ele NEDEN ELERS ENDE ERAT Eee 101 Can I get capture external program output using a Boost Jam variable 00 eee cece ce ee ce ee cence eee eeeeeeeeeeaeeeaes 102 How to get the project root a k a Jamroot location 2 0 0 cece cece ce ee ce ee cence eeeeeeeeeeeeeesaeeeaeeeeeeae eeu nerne 103 How to change compilation flags for one file eee
26. For example constant VERSION 1 34 0 al 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 path constant DATA data a txt al 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 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 will be built as well At the moment the parameter to this rule should be a directory name Project ID or general target ref erences are not allowed This rule is deprecated and equivalent to alias 49 http www renderx com Reference Builtin features This section documents the features that are built in into Boost Build For features with a fixed set of values that set is provided with the default value listed first variant link runtime link threading source A feature combining several low level features making it easy to request common build configurations Allowed values debug release profile The value debug expands to lt optimization gt off lt debug symbols gt on lt inlining gt off lt runtime debugH ging gt on The value release expands to lt optimization
27. Jam to solve such problems and that extension was integrated in Boost Jam Any target can be assigned a semaphore by setting a variable called SEMAPHORE on that target The value of the variable is the semaphore name It must be different from names of any declared target but is arbitrary otherwise The semantic of semaphores is that in a group of targets which have the same semaphore only one can be updated at the moment regardless of 4 option Platform Identifier A number of Jam built in variables can be used to identify runtime platform OS OS identifier string OSPLAT Underlying architecture when applicable MAC true on MAC platform NT true on NT platform OS2 true on OS2 platform UNIX true on Unix platforms VMS true on VMS platform Jam Version JAMDATE Time and date at bjam start up as an ISO 8601 UTC value JAMUNAME Ouput of uname 1 command Unix only JAMVERSION bjam version currently 3 1 19 JAM VERSION A predefined global variable with two elements indicates the version number of Boost Jam Boost Jam versions start at 03 00 Earlier versions of Jam do not automatically define JAM VERSION JAMSHELL When b jam executes a rule s action block it forks and execs a shell passing the action block as an argument to the shell The invoc ation of the shell can be controlled by JAMSHELL The default on Unix is for example JAMSHELL bin sh c The is replaced with
28. The actual properties used for building targets are typically a combination of the build request and properties derived from the project s Jamroot and its other Jamfiles as described in the section called Project Hierarchies For example the locations of included 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 targets Multithread enabled compilation is another example of a typical target requirement The Jamfile fragment below illustrates how these requirements might be specified exe hello hello cpp lt include gt boost lt threading gt multi When hello is built the two requirements specified above will always be present If the build request given on the b2 command line explictly contradicts a target s requirements the target requirements usually override or in the case of free features like lt include gt augments the build request 1 See the section called Feature Attributes http www renderx com Tutorial Tip The value of the lt include gt feature is relative to the location of Jamroot where it is used Project Attributes If we want the same requirements for our other target hel 102 we could simply duplicate them However as projects grow that approach leads to a great deal of repeated boilerplate in Jamfiles Fortunately there s a better way Each project
29. The current version of Boost Build has three levels of targets listed below metatarget Object that is created from declarations in Jamfiles May be called with a set of properties to produce concrete targets concrete target Object that corresponds to a file or an action jam target Low level concrete target that is specific to Boost Jam build engine Essentially a string most often a name of file In most cases you will only have to deal with concrete targets and the process that creates concrete targets from metatargets Extending metatarget level is rarely required The jam targets are typically only used inside the command line patterns 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 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 abstract target l The generate method takes the build properties as an instance of the property set class and returns a list containing e As front element Usage requirements from this invocation an instance of property set As subsequent elements created concrete targets instances of the virtual target class
30. The second one uses some target most likely a library defined by a Jamfile one level higher Finally the third target uses a C Boost library referring to it using its absolute symbolic name More information about target references can be found in the section called Dependent Targets and the section called Target identifiers and references Requirements Requirements are the properties that should always be present when building a target Typically they are includes and defines exe hello hello cpp lt include gt opt boost lt define gt MY_DEBUG There are a number of other features listed in 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 lib util util cpp lt link gt static obj main main cpp lt optimization gt off 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 defines when a library is built as shared or when a target s release variant is built in release mode lib network network cpp lt link gt shared lt define gt NEWORK_LIB SHARED lt variant gt release lt define gt EXTRA_FAST In the example above whenever network is built with lt link gt shared lt define gt NEWORK_LIB_SHARED will be in its properties too
31. a arameter If not specified a default script is chosen based on the used compiler binary e g vevars32 bat or vsvars32 bat setup amd64 setup The filename of the target platform specific environment setup script to run before invoking any of the i386 setup ia64 tools defined in this toolset If not specified the global environment setup script is used 64 bit support Starting with version 8 0 Microsoft Visual Studio can generate binaries for 64 bit processor both 64 bit flavours of x86 codenamed AMD64 EM64T and Itanium codenamed JA64 In addition compilers that are itself run in 64 bit mode for better performance are provided The complete list of compiler configurations are as follows we abbreviate AMD64 EM64T to just AMD64 e 32 bit x86 host 32 bit x86 target e 32 bit x86 host 64 bit AMD64 target e 32 bit x86 host 64 bit A64 target e 64 bit AMD64 host 64 bit AMD64 target e 64 bit IA64 host 64 bit A64 target The 32 bit host compilers can be always used even on 64 bit Windows On the contrary 64 bit host compilers require both 64 bit host processor and 64 bit Windows but can be faster By default only 32 bit host 32 bit target compiler is installed and additional compilers need to be installed explicitly To use 64 bit compilation you should 1 Configure you compiler as usual If you provide a path to the compiler explicitly provide the path to the 32 bit compiler If you try to specify the path to any of 64 bi
32. adding a feauture 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 feature attributes e if you want a feature value set for one target to automaticaly propagate to its dependant targets then make it propagated if a feature does not have a fixed list of values it must be free For example the include feature is a free feature if a feature is used to refer to a path relative to the Jamfile it must be a path feature Such features will also get their values automatically converted to Boost Build s internal path representation For example include is a path feature 90 http www renderx com Extender Manual e if feature is used to refer to some target it must be a dependency feature 2 Representing the feature value in a target specific variable Build actions are command templates modified by Boost Jam variable expansions The toolset flags rule sets a target specific variable to the value of a feature 3 Using the variable The variable set in step 2 can be used in a build action to form command parameters or files Another example Here s another example Let s see how we can make a feature that refers to a target For example when linking dynamic libraries on Windows one sometimes needs to specify a DEF file telling what functions should be exported It would be nice to use this file like this
33. all build tools have a similar mechanism Boost Build differs by requiring that all build properties are declared in advance and providing a large set of properties with portable semantics The final concept is property propagation Boost Build does not require that every metatarget is called with the 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 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 have dependencies of their own For a more in depth treatment of the requirements and concepts you may refer to SYRCoSE 2009 Boost Build article 15 http www renderx com Overview 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 Boost Jam documentation Boost Jam has an interpreted procedural language On the lowest level a 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 Boost Jam program contains classe
34. can put lt source gt in requirements or to conditionally include a source using conditional re quirements see the section called Conditions and alternatives See also the lt library gt feature 50 http www renderx com Reference library dependency implicit dependency use dll path hardcode dll paths cflags cxxflags linkflags include define warnings warnings as errors build This feature is almost equivalent to the lt source gt feature except that it takes effect only for linking When you want to link all targets in a Jamfile to certain library the lt library gt feature is preferred over lt source gt X the latter will add the library to all targets even those that have nothing to do with libraries 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 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 called Generated headers for more information 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 dependency is not used in any other way
35. cl will be used The command will be invoked after the setup script was executed and adjusted the PATH variable 55 http www renderx com 3 2 fa Reference compiler filter Command through which to pipe the output of running the compiler For example to pass the output to STLfilt idl compiler The command that compiles Microsoft COM interface definition files If not specified midl will be used The command will be invoked after the setup script was executed and adjusted the PATH variable linker The command that links executables and dynamic libraries If not specified link will be used The command will be invoked after the setup script was executed and adjusted the PATH variable mc compiler The command that compiles Microsoft message catalog files If not specified me will be used The command will be invoked after the setup script was executed and adjusted the PATH variable resource compiler The command that compiles resource files If not specified re will be used The command will be invoked after the setup script was executed and adjusted the PATH variable setup The filename of the global environment setup script to run before invoking any of the tools defined in this toolset Will not be used in case a target platform specific script has been explicitly specified for the current target platform Used setup script will be passed the target platform identifier x86 x86_amd64 x86_1a64 amd64 or ia64 as
36. eeceeeeeceeeceaeeeeeuececaeeeeaeeeeeeeeeaaeeeeeeeeceeeeeuaeeeeeeeaaeseegaes 104 Why are the dll path and hardcode dll paths properties useful 0 cee eeecnee cate ce eeca cena eeu eeneeenees 105 iii http www renderx com Targets in site config jam Header only libraries A Boost Jam Documentation Building BJam Language Miscellaneous History Boost Build V2 User Manual render gt http www renderx com List of Tables 1 Search paths for configuration eS ss0 cer duanas acta canes r naan Ea EEE NEE E REEE EE aaa 19 PAETE A E EE EEE eas ahieous deduatacyads E vac aahs taaaca A Seatessadn esate eenatied 23 E A esters A E A E A A Aceh capsiees E ERE A ERE EGE bapa bacaa ss 30 Al Supported TOOSCtS 005 sc arrene ker he hor rE EEEE EEEE EEEE TEE EEEE EEE EEEIEI EEE RE EENEN EEEE EEEIEE ETETE E E 110 render http www renderx com 3 2 fa How to use this document If you ve just found out about Boost Build V2 and want to know if it will work for you start with Tutorial You can continue with Overview When you re ready to try Boost Build in practice go to Installation If you are about to use Boost Build on your project or already using it and have a problem look at Overview If you re trying to build a project which uses Boost Build see Installation and then read about the section called Invocation If you have questions please post them to our mailing list http boost org more m
37. end user system And __ACTION_RULE__ is called as rule action rule args target command status start end user system output The arguments for both are args Any values following the rule name in the TIMING RULE or ACTION RULE are passed along here target The b jam target that was built command The text of the executed command in the action body status The integer result of the executed command start The starting timestamp of the executed command as a ISO 8601 UTC value end The completion timestamp of the executed command as a ISO 8601 UTC value user The number of user CPU seconds the executed command spent as a floating point value system The number of system CPU seconds the executed command spent as a floating point value output The output of the command as a single string The content of the output reflects the use of the pX option N Note If both variables are set for a target both are called first TIMING RULE then ACTION RULI T Gl 129 http www renderx com Boost Jam Documentation Modules Boost Jam introduces support for modules which provide some rudimentary namespace protection for rules and variables A new keyword module was also introduced The features described in this section are primitives meaning that they are meant to provide the operations needed to write Jam rules which provide a more elegant module interface Decl
38. expression of the form lt expr2 gt lt expr2 gt is then prepended e When Jam is invoked it imports all environment variable settings into corresponding Jam variables followed by all command line s variable settings Variables whose name ends in PATH Path or path are split into string lists on OS specific path list separator boundaries e g for UNIX and for Windows All other variables are split on space boundaries Boost Jam modifies that behavior by allowing variables to be quoted e A variable whose value is an empty list or which consists entirely of empty strings has a negative logical value Thus for example code like the following allows a sensible non empty default which can easily be overridden by the user MESSAGE starting jam if MESSAGE ECHO The message is MESSAGE If the user wants a specific message he invokes jam with sMESSAGE message text If he wants no message he invokes jam with sMESSAGE and nothing at all is printed The parsing of command line options in Jam can be rather unintuitive with regards to how other Unix programs accept options There are two variants accepted as valid for an option 1 xvalue and 2 x value 136 http www renderx com Boost Jam Documentation History 3 1 18 After years of bjam developments This is going to be the last unbundled release of the 3 1 x se
39. expressions 9 Show variable manipulation scanner tokens and memory usage 10 Show profile information for rules both timing and memory 11 Show parsing progress of Jamfiles 12 Show graph of target dependencies 13 Show change target status fate d N Enable debugging level N o file Write the updating actions to the specified file instead of running them s var value Set the variable var to value in the global scope of the jam language interpreter overriding variables imported from the environment 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 the section called Builtin features The most common features are summarized below 22 http www renderx com Overview Table 2 Feature Allowed values Notes variant debug release link shared static Determines if Boost Build creates shared or static libraries threading single multi Cause the produced binaries to be thread safe This requires proper support in the source code itself address model 32 64 Explicitly request either 32 bit or 64 bit code generation This typically requires that your compiler is appropriately con figured Please refer to the section called C Compilers and your compiler documentation in case of problems toolset Depends on configuration The C
40. http www renderx com Reference build request by non conditional requirements or even by another conditional property For example the following example works as expected exe a a cpp lt toolset gt gcc lt variant gt release lt variant gt release lt define gt FOO Target Paths Several factors determine the location of a concrete file target All files in a project are built under the directory bin unless this is overriden by the build dir project attribute Under bin is a path that depends on the properties used to build each target This path is uniquely determined by all non free non incidental properties For example given a property set containing lt toolset gt gcc lt toolset gcc version gt 4 6 1 lt variant gt debug lt warnings gt all lt define gt _DEBUG lt include gt usr local include lt link gt static the path will be gcc 4 6 1 debug link static lt warnings gt is an incidental feature and lt define gt and lt include gt are free features so they do not affect the path Sometimes the paths produced by Boost Build can become excessively long There are a couple of command line options that can help with this abbreviate paths reduces each element to no more than five characters For example link static becomes Ink sttc The hash option reduces the path to a single directory using an MDS hash There are two features that affect the build directory The lt location gt feature completely overrid
41. in PATH The following options can be provided using lt opt ion name gt opt ion value syntax cflags Specifies additional compiler flags that will be used when compiling C sources cxxflags Specifies additional compiler flags that will be used when compiling C sources compileflags Specifies additional compiler flags that will be used when compiling both C and C sources linkflags Specifies additional command line options that will be passed to the linker Sun Studio The sun module supports the Sun Studio C compilers for the Solaris OS The module is initialized using the following syntax using sun version ct compile command compiler options This statement may be repeated several times if you want to configure several versions of the compiler If the command is not specified Boost Build will search for a binary named CC in opt SUNWspro bin and in PATH When using this compiler on complex C code such as the Boost C library it is recommended to specify the following options when intializing the sun module library stlport4 features tmplif features tmplrefstatic a See the Sun C Frontend Tales for details The following options can be provided using lt option name gt option value syntax cflags Specifies additional compiler flags that will be used when compiling C sources cxxflags Specifies additional compiler flags that will be used when compiling C sources compileflags Specifies addition
42. install built target and arbitrary files Basic install For installing a built target you should use the install rule which follows the common syntax For example install dist hello helpers will cause the targets hello and helpers to be moved to the dist directory relative to the Jamfile s directory The directory can be changed using the Location property install dist hello helpers lt location gt usr bin While you can achieve the same effect by changing the target name to usr bin using the location property is better as it allows you to use a mnemonic target name The location property is especially handy when the location is not fixed but depends on the build variant or environment variables install dist hello helpers lt variant gt release lt location gt dist release lt variant gt debug lt location gt dist debug install dist2 hello helpers lt location gt DIST See also conditional properties and environment variables Installing with all dependencies Specifying the names of all libraries to install can be boring The install allows you to specify only the top level executable targets to install and automatically install all dependencies install dist hello lt install dependencies gt on lt install type gt EXE lt install type gt LIB will find all targets that hello depends on and install all of those which are either executables or libraries More specifically for
43. libraries can be found The version should always be provided and the library path should be provided if you re using STLport s implementation of iostreams Note that STLport 5 always uses its own iostream implement ation so the library path is required When STLport is configured you can build with STLport by requesting stdlib st1lport on the command line Documentation tools Boost Build support for the Boost documentation tools is documented below xsltproc To use xsltproc you first need to configure it using the following syntax using xsltproc xsltproc Where xs1tprocis the xsltproc executable If xs1tprocis not specified and the variable XSLTPROC is set the value of XSLTPROC will be used Otherwise xsltproc will be searched for in PATH The following options can be provided using lt opt ion name gt opt ion value syntax xsl param Values should have the form name value xsl path Sets an additional search path for xi include elements catalog A catalog file used to rewrite remote URL s to a local copy 61 http www renderx com Reference The xsltproc module provides the following rules Note that these operate on jam targets and are intended to be used by another toolset such as boostbook rather than directly by users xslt rule xslt target source stylesheet properties Runs xsltproc to create a single output file xslt dir rule xslt dir target source stylesheet properties dirna
44. lpython22 would appear in the command line other compilers may use different options We can also specify where the toolset should look for the library lib pythonlib lt name gt python22 lt search gt opt lib And of course target alternatives can be used in the usual way lib pythonlib lt name gt python22 lt variant gt release lib pythonlib lt name gt python22_d lt variant gt debug A more advanced use of prebuilt targets is described in the section called Targets in site config jam 13 http www renderx com 3 2 fa Overview This section will provide the information necessary to create your own projects using Boost Build The information provided here is relatively high level and Reference as well as the on line help system must be used to obtain low level documentation see help Boost Build actually consists of two parts Boost Jam a build engine with its own interpreted language and Boost Build itself im plemented in Boost Jam s language The chain of events when you type b2 on the command line is as follows 1 The Boost Build executable tries to find Boost Build modules and loads the top level module The exact process is described in the section called Initialization 2 The top level module loads user defined configuration files user config jamand site config jam which define available toolsets 3 The Jamfile in the current directory is read That in turn mig
45. matching against the pattern you can use this to do case insensitive matching using lowercase patterns The paths returned will still have mixed case if the OS supplies them On Windows NT and Cygwin filenames are always downcased before matching MATCH The MATCH rule does pattern matching rule MATCH regexps list Matches the egrep 1 style regular expressions regexps against the strings in list The result is the concatenation of matching subexpressions for each string in list and for each regular expression in regexps Only useful within the construct to change the result into a list BACKTRACE rule BACKTRACE Returns a list of quadruples filename line module rulename describing each shallower level of the call stack This rule can be used to generate useful diagnostic messages from Jam rules 120 http www renderx com Boost Jam Documentation UPDATE rule UPDATE targets Classic jam treats any non option element of command line as a name of target to be updated This prevented more sophisticated handling of command line This is now enabled again but with additional changes to the UPDATE rule to allow for the flexibility of changing the list of targets to update The UPDATE rule has two effects 1 It clears the list of targets to update and 2 Causes the specified targets to be updated If no target was specified with the UPDATE rule no targets will be updated To
46. name exists and then if main target of that name exists For example valid target ids might be 79 http www renderx com Reference a target in current project lib b cpp regular file boost thread project boost thread hnome ghost build lr_library parser target in specific project Rationale Target is separated from project by special separator not just slash because e It emphasises that projects and targets are different things It allows to have main target names with slashes Target reference is used to specify a source target and may additionally specify desired properties for that target It has this syntax target referenc gt target id requested properties requested properties gt property path For example exe compiler compiler cpp libs cmdline lt optimization gt space al would cause the version of cmdline library optimized for space to be linked in even if the compiler executable is build with optimization for speed 80 http www renderx com Extender Manual http www renderx com Extender Manual Introduction This section explains how to extend Boost Build to accomodate your local requirements primarily to add support for non standard tools you have Before we start be sure you have read and understoon the concept of metatarget the section called Concepts which is critical to understanding the remaining material
47. name gt png EY Note When a library has a shared library as a source or a static library has another static library as a source then any target linking to the first library with automatically link to its source library as well On the other hand when a shared library has a static library as a source then the first library will be built so that it completely includes the second one If you do not want a shared library to include all the libraries specified in its sources especially statically linked ones you would need to use the following lib b i a cpp lib a a cpp lt use gt b lt library gt b This specifies that library a uses library b and causes all 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 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 helpers cpp source file Then you could add the following to the Jamfile located in that same directory lib helpers helpers cpp lt include gt which would automatically add the directory where the target has been 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 36 http
48. names called with I 2 foo sorry Joe Dave Pete extra argument foo argument error rule report pronoun index state names called with I 2 sorry missing argument names If you omit the list of formal arguments all checking is bypassed as in classic Jam Argument lists drastically improve the reliab ility and readability of your rules however and are strongly recommended for any new Jam code you write Built in Rules BJam has a growing set of built in rules all of which are pure procedure rules without updating actions They are in three groups the first builds the dependency graph the second modifies it and the third are just utility rules 117 http www renderx com Boost Jam Documentation Dependency Building DEPENDS rule DEPENDS targetsl targets2 Builds a direct dependency makes each of targets depend on each of targets2 Generally targets will be rebuilt if targets2 are themselves rebuilt or are newer than targets INCLUDES rule INCLUDES targets1l targets2 Builds a sibling dependency makes any target that depends on any of targets also depend on each of targets2 This reflects the dependencies that arise when one source file includes another the object built from the source file depends both on the original and included source file but the two sources files don t depend on each other For example DEPENDS fo0o0 0 foo c
49. of F s subfeatures For example the properties lt toolset gt gcc lt toolset version gt 3 0 1 can be expressed more conscisely using a value string as lt toolset gt gcc 3 0 1 A property set is a set of properties i e a collection without duplicates for instance lt toolset gt gcc lt runtime link gt static A property path is a property set whose elements have been joined into a single string separated by slashes A property path repres entation of the previous example would be lt toolset gt gcc lt runtime link gt static A build specification is a property set that fully describes the set of features used to build a target Property Validity For 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 so that certain values are valid only in the presence of certain other subproperties For example it is possible to specify that the lt gcc target gt mingw property is only valid in the presence of lt gcc version gt 2 95 2 Feature Attributes Each feature has a collection of zero or more of the following attributes Feature attributes are low level descriptions of how the build system should interpret a feature s values when they appear in a build request We also refer to the attributes of properties so that an incidental property for example is one whose feature ha
50. of a target in a project with the explicit rule explicit hello_test would cause the hello test target to be built only if explicitly requested by the user or by some other target The Jamfile for a project can include a number of build project rule calls that specify additional projects to be built 32 http www renderx com Common tasks This section describes main targets types that Boost Build supports out of the box Unless otherwise noted all mentioned main target rules have the common signature described in the section called Declaring Targets 33 http www renderx com Common tasks Programs Programs are created using the exe rule which follows the common syntax For example exe hello hello cpp some_library lib some_project library lt threading gt multi This will create an executable file from the sources in this case one C file one library file present in the same directory and another library that is created by Boost Build Generally sources can include C and C files object files and libraries Boost Build will automatically try to convert targets of other types Tip On Windows if an application uses shared libraries and both the application and the libraries are built using Boost Build it is not 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
51. quoting The result of a token after variable expansion is the product of the components of the token where each component is a literal substring or a list substituting a variable reference For example X gt abc tS X gt ta tb ec X z gt az bz cz X X gt a a a b a c b a b b b c c a c b c c The variable name and modifiers can themselves contain a variable reference and this partakes of the product as well X gt abc Y gt 1 2 Z gt X Y Z gt a belz Because of this product expansion if any variable reference in a token is undefined the result of the expansion is an empty list If any variable element is a null string the result propagates the non null elements X gt am Y gt mr 1 Z gt X Y gt a al 1 X Z gt A variable element s string value can be parsed into grist and filename related components Modifiers to a variable are used to select elements select components and replace components The modifiers are n Select element number n starting at 1 If the variable contains fewer than n elements the result is a zero element list n can be negative in which case the element number n from the last leftward is returned 125 http www renderx com Boost Jam Documentation n m Select elements number n through m n and m can be negative in which case they refer to elements counting from the last leftward n
52. s Targets are out of date and will be updated can t find N target s Source files can t be found and there are no actions to create them can t make N target s Due to sources not being found other targets cannot be made warning X depends on itself A target depends on itself either directly or through its sources don t know how to make X A target is not present and no actions have been defined to create it X skipped for lack of Y A source failed to build and thus a target cannot be built warning using independent target X A target that is not a dependency of any other target is being referenced with lt or gt X removed BJam removed a partially built target after being interrupted Bugs Limitations For parallel building to be successful the dependencies among files must be properly spelled out as targets tend to get built in a quickest first ordering Also beware of un parallelizable commands that drop fixed named files into the current directory like yacc 1 does 134 http www renderx com Boost Jam Documentation A poorly set JAMSHELL is likely to result in silent failure Fundamentals This section is derived from the official Jam documentation and from experience using it and reading the Jambase rules We repeat the information here mostly because it is essential to understanding and using Jam but is not consolidated in a single place Some of it is missing from the official d
53. section called Cross compilation for details of crosscompilation The architecture features specifies the general processor familty to generate code for Allowed values depend on the used toolset The instruction set specifies for which specific instruction set the code should be gener ated The code in general might not run on processors with older different instruction sets While Boost Build 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 called C Compilers for details Allowed values 32 64 The address model 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 called C Compilers for details Allowed values Any positive integer 52 http www renderx com Reference embed manifest This feature allows configuring a C compiler with the maximal template instantiation depth parameter Specific toolsets may or may not provide support for this feature depending on whether their compilers provide a corresponding command line option Note Due to some internal details in the current Boost Build implementation it is not possible to have features whose valid values are all positive integer As a workaround a
54. support changing of the update list in more useful ways the rule also returns the targets previously in the update list This makes it possible to add targets as such local previous updates UPDATE UPDATE previous updates a new target W32_GETREG rule W32_GETREG path data Defined only for win32 platform It reads the registry of Windows path is the location of the information and data is the name of the value which we want to get If data is omitted the default value of path will be returned The path value must conform to MS key path format and must be prefixed with one of the predefined root keys As usual Fl e HKLM is equivalent to HKEY LOCAL MACHINE f e HKCU is equivalent to HKEY CURRENT USER e HKCR is equivalent to HKEY CLASSES ROOT Other predefined root keys are not supported Currently supported data types REG DWORD REG SZ REG EXPAND SZ REG MULTI SZ The data with REG_DWORD type will be turned into a string REG MULTI SZ into a list of strings and for those with REG EXPAND SZ type environment variables in it will be replaced with their defined values The data with REG_Sz type and other unsupported types will be put into a string without modification If it can t receive the value of the data it just return an empty list For example local PSDK location
55. the text of the action block BJam does not directly support building in parallel across multiple hosts since that is heavily dependent on the local environment To build in parallel across multiple hosts you need to write your own shell that provides access to the multiple hosts You then reset JAMSHELL to reference it 128 http www renderx com Boost Jam Documentation Just as bjam expands a to be the text of the rule s action block it expands a to be the multi process slot number The slot number varies between 1 and the number of concurrent jobs permitted by the j flag given on the command line Armed with this it is possible to write a multiple host shell For example bin sh This sample JAMSHELL uses the SunOS on 1 command to execute a command string with an identical environment on another host oe Set JAMSHELL jamshell where jamshell is the name of this shell file This version handles up to j6 after that they get executed locally case 1 in 114 on winken sh c 2 215 on blinken sh c 2 3 6 on nod sh c 2 eval S2 esac TIMING RULE and ACTION RULE The TIMING RULE and ACTION RULE can be set to the name of a rule for bjam to call after an action completes for a target They both give diagnostic information about the action that completed For TIMING RULE the rule is called as rule timing rule args target start
56. to link to However with Boost Build a header only library can be declared as Boost Build target and all dependents can use such library without having to remeber whether it is a header only library or not Header only libraries may be declared using the alias rule specifying their include path as a part of its usage requirements for example alias my lib no sources no build requirements no default build lt include gt whatever The includes specified in usage requirements of my 1ib are automatically added to all of its dependants build properties The de pendants need not care if my lib is a header only or not and it is possible to later make my 1ib into a regular compiled library without having to that its dependants declarations If you already have proper usage requirements declared for a project where a header only library is defined you do not need to du plicate them for the alias target project my usage requirements lt include gt whatever alias mylib 107 http www renderx com Appendix A Boost Jam Documentation 108 render gt http www renderx com Boost Jam Documentation Building BJam Installing BJam after building it is simply a matter of copying the generated executables someplace in your PATH For building the executables there are a set of build bootstrap scripts to accomodate particular environments The scripts take one optional argument the name of th
57. to load the Jam code that implements the build system To do this it searches for a file called boost build jam first in the 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 When found the file is interpreted and should specify the build system location by calling the boost build rule rule boost build location If location is a relative path it is treated as relative to the directory of boost build jam The directory specified by that location and the directories in BOOST BUILD PATH are then searched for a file called bootstrap jam which is expected to bootstrap the build system This arrangement allows the build system to work without any command line or environment variable settings For example if the build system files were located in a directory build system at your project root you might place a boost build jamat the project root containing boost build build system In this case running b2 anywhere in the project tree will automatically find the build system The default boot strap jam after loading some standard definitions loads two site config jamand user config jam 47 http www renderx com Reference 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 exe lib install alias
58. value of the same feature is already specified e g on the command line or by propagation from a dependent target e usage requirements is the list of properties that will be propagated to all main targets that use this one i e to all its dependents Some main target rules have a different list of parameters as explicitly stated in their documentation 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 the section called Property refinement Name The name of main target has two purposes First it s used to refer to this target from other targets and from command line Second it s used to compute the names of the generated files Typically filenames are obtained from main target name by appending system dependent suffixes and prefixes The name of a main target can contain alphanumeric characters dashes undescores and dots The entire name is significant when resolving references from other targets For determining filenames only the part before the first dot is taken For example obj test release test cpp lt variant gt release obj test debug test cpp lt variant gt debug will generate two files named test ob in two different directories not two files named test release obj and test de bug obj Sources The list of sour
59. which has the following syntax project id attributes Here attributes is a sequence of rule arguments each of which begins with an attribute name and is followed by any number of build properties The list of attribute names along with its handling is also shown in the table below For example it is possible to write project tennis requirements lt threading gt multi default build release 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 Target references make use of project ids to specify a target Source location specifies the directory where sources for the project are located Project requirements are requirements that apply to all the targets in the projects as well as all subprojects Default build is the build request that should be used when no build request is specified explicitly The default values for those attributes are given in the table below 29 http www renderx com Overview Table 3 Attribute Name Default value Handling by the project rule Project id none none Assigned from the first para Source location source location The location of jamfile for the project meter of the project rule It is assumed to denote absolute project id Sets to the passed value Requirements requirements The parent s requirements The parent s requi
60. Boost Build V2 User Manual render gt http www renderx com Boost Build V2 User Manual Copyright 2006 2009 Vladimir Prus ENS Distributed under the Boost Software License Version 1 0 See accompanying file LIC E 1 0 txt or copy at http www boost org LICENSE_1_0 txt http www renderx com 3 2 fa Table of Contents HOw to Use this dOCUMENE oo rss een EDEN Rees ar EEEE EE EEKE E EAER OEE EREE E 1 Installation Uee E E E E E E E E A E E E E E 2 NUTOTIAL EE E E E E E E E E E E 3 HENO WOME eee oc se Sates E AA EE A E E E E AE R E E 4 Properties riitese eneee E EE E E E EEE E EEE A e E E E E E EE EE E Ene ke 5 Project Hierarchies 0d senivnesesensendetasncueb eiisvnedyaeenaede EEEE E EKNE E in Eea DN EERE EREN A EEES EEE E EEEE rE E Ea EE 7 Dependent Targets socie nei eres ENS EEEE E EEE RE E SEEE EE E EAEE EEEIEE EEEO EERE EEEE EEDE RENS 8 St tic and Shared Dares onterven rener sas venneri Eeer EERE EErEE EEEE EE EEIE EESE PE EEVEE clei TES Jaabemasuand peosenebensenbed 10 Conditions and alternafiveS ssipeeiiiorersvois n iie aeto E EEEE EE EEE ER EEE EEE REA EEE EE EES E RE cubes 12 Prebuilt tal SES 250 serene nere erone te taadewapesuaensbanaes E EEE EEEE E ERIE EEEE EENET EESE EN EEEE REVENE EATE 13 OVERVIEW AE E E E E E E TT 14 COnNCEPIS oeri iere En E EEEE EEEE sells EEEE EEE EPEE EREE EE EEOSE EEEE EE SE REESE SES TEENE OE COTAT ENERE EESE EUNET EE EEEE ERE 15 Boost Jam Langage scri
61. C compiler toolsets that Boost Build supports out of the box the list of parameters to using is the same toolset name version invocation command and options If you have a single compiler and the compiler executable has its usual name and is in the PATH or was installed in a standard installation directory or can be found using a global system like the Windows registry 19 http www renderx com Overview it can be configured by simply using tool name If the compiler is installed in a custom directory you should provide the command that invokes the compiler for example using gcc gtt 3 2 using msvc Z Programs Microsoft Visual Studio vc98 bin cl Some Boost Build toolsets will use that path to take additional actions required before invoking the compiler such as calling vendor supplied scripts to set up its required environment variables When the compiler executables for C and C are different the path to the C compiler executable must be specified The command can be any command allowed by the operating system For example using msvc echo Compiling amp amp foo bar baz cl will work To configure several versions of a toolset simply invoke the using rule multiple times using gcc 343 using gcc 3 4 gtt 3 4 using gcc 3 2 g 3 2 Note that in the first call to using the compiler found in the PATH will be used and there is no need to exp
62. EARCH alter this e If LOCATE is set then the target is bound relative to the first directory in LOCATE Only the first element is used for binding If SEARCH is set then the target is bound to the first directory in SEARCH where the target file already exists Ifthe SEARCH search fails the target is bound relative to the current directory anyhow Both SEARCH and LOCATE should be set target specific and not globally If they were set globally b jam would use the same paths for all file binding which is not likely to produce sane results When writing your own rules especially ones not built upon those in Jambase you may need to set SEARCH or LOCATE directly Almost all of the rules defined in Jambase set SEARCH and LOCATE to sensible values for sources they are looking for and targets they create respectively HDRSCAN and HDRRULE These two variables control header file scanning HDRSCAN is an egrep 1 pattern with s surrounding the file name used to find file inclusion statements in source files Jambase uses HDRPATTERN as the pattern for HDRSCAN HDRRULE is the name of a rule to invoke with the results of the scan the scanned file is the target the found files are the sources This is the only place where b jam invokes a rule through a variable setting Both HDRSCAN and HDRRULE must be set for header file scanning to
63. 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 typed target is associated with specific target type and relays the generator or generators for that type 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 This create then register pattern is caused by limitations of the Boost Jam language Python port is likely to never create duplicate targets 83 http www renderx com Extender Manual Example 1 to 1 generator Say you re writing an application that generates C code If you ever did this you know that it s not nice Embedding large portions of C code in string literals is very awkward A much better solution is 1 Write the template of the code to be generated leaving placeholders at the points that will change 2 Access the template in your application and replace placeholders with appropriate text 3 Write the result It s quite easy to achieve You write special verbatim files that are just C except that the very first line of the file contains the name of a variable that should be generated A simple tool is created that takes a verbatim file and creates a cpp file with a single char variable whose name is taken from the first line of the verbatim file and whose value is the file s properly quo
64. Jamroot has lt include gt home ghost local in its requirements then all of its subprojects will have it in their requirements too Of course any project can add include paths to those specified by its parents 2 More details can be found in 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 project does not automatically cause its subprojects to be built unless the parent project s Jamfile explicitly requests it In our example top Jamroot might contain build project app 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 Many features will be overridden rather than added to in subprojects See the section called Feature Attributes for more information http www renderx com Tutorial Dependent Targets When building a target x that depends on first building another target Y such as a library that must be linked with X Y is called a dependency of X and x is termed a dependent of Y To get a feeling of target dependencies let s continue the above example and see how top app Jamfile can use libraries from top util foo If top util foo Jamfile contains lib bar bar cpp then to use this library in top app Jamfile we can write exe app a
65. Please also note that guidelines for different systems differ in this respect For example the Debian GNU guidelines prohibit any additional search paths while Sol aris guidelines suggest that they should always be used 105 http www renderx com Frequently Asked Questions Targets in site config jam It is desirable to declare standard libraries available on a given system Putting target declaration in a specific project s Jamfile is not really good since locations of the libraries can vary between different development machines and then such declarations would need to be duplicated in different projects The solution is to declare the targets in Boost Build s site config jam configuration file project site config lib zlib lt name gt z Recall that both site config jam and user config jam are projects and everything you can do in a Jamfile you can do in those files as well So you declare a project id and a target Now one can write exe hello hello cpp site config zlib in any Jamfile 106 http www renderx com Frequently Asked Questions Header only libraries In modern C libraries often consist of just header files without any source files to compile To use such libraries you need to add proper includes and possibly defines to your project But with a large number of external libraries it becomes problematic to remember which libraries are header only and which ones you have
66. RY rule TEMPORARY targets Marks targets as temporary allowing them to be removed after other targets that depend upon them have been updated If a TEMPORARY target is missing bjam uses the timestamp of the target s parent Jambase uses TEMPORARY to mark object files that are archived in a library after they are built so that they can be deleted after they are archived FAIL_EXPECTED rule FAIL_EXPECTED targets For handling targets whose build actions are expected to fail e g when testing that assertions or compile time type checking work properly Boost Jam supplies the FAIL_EXPECTED rule in the same style as NOCARE et al During target updating the return code of the build actions for arguments to FAIL_EXPECTED is inverted if it fails building of dependent targets continues as though it succeeded If it succeeds dependent targets are skipped RMOLD rule RMOLD targets BJam removes any target files that may exist on disk when the rule used to build those targets fails However targets whose depend encies fail to build are not removed by default The RMOLD rule causes its arguments to be removed if any of their dependencies fail to build ISFILE rule ISFILE targets ISFILE marks targets as required to be files This changes the way bjam searches for the target such that it ignores mathes for file system items that are not file like directorie
67. Select elements number n through the last n can be negative in which case it refers to the element counting from the last leftward B Select filename base S Select last filename suffix IM Select archive member name DD Select directory path P Select parent directory G Select grist U Replace lowercase characters with uppercase IL Replace uppercase characters with lowercase T Converts all back slashes V to forward slashes For example x C Program Files Borland ECHO x T prints C Program Files Borland W When invoking Windows based tools from Cygwin it can be important to pass them true windows style paths The W modifier under Cygwin only turns a cygwin path into a Win32 path using the cygwin_conv_to_win32_path function On other platforms the string is unchanged For example x cygdrive c Program Files Borland ECHO x W prints C Program Files Borland on Cygwin chars Select the components listed in chars G grist Replace grist with grist D path Replace directory with path B base Replace the base part of file name with base S suf Replace the suffix of file name with suf mem Replace the archive member name with mem R root Prepend root to the whole file name if not already rooted E value Assign value to the variable if it is unset J joinval Concatentate list elements into single element separated by joinval On VMS var P is the parent
68. a i string is greater than b i string where i is first mismatched element a gt b every a String is greater than or equal to its b counterpart ainb true if all elements of a can be found in b or if a has no elements cond condition not true cond amp amp cond conjunction cond cond disjunction cond precedence grouping include file Causes b jam to read the named file The file is bound like a regular target see Binding above but unlike a regular target the include file cannot be built 123 http www renderx com Boost Jam Documentation The include file is inserted into the input stream during the parsing phase The primary input file and all the included file s are treated as a single file that is jam infers no scope boundaries from included files local vars values Creates new vars inside to the enclosing block obscuring any previous values they might have The previous values for vars are restored when the current block ends Any rule called or file included will see the local and not the previous value this is sometimes called Dynamic Scoping The local statement may appear anywhere even outside of a block in which case the previous value is restored when the input ends The vars are initialized to values if present or left uninitialized otherwise return values Within a rule body the return statement sets the return value for an invocation of the rule It does not cause the ru
69. ailing_lists htm jamboost The mailing list is also mirrored to the newsgroup news news gmane org gmane comp lib boost build http www renderx com 3 2 fa Installation To install Boost Build from an official release or a nightly build as available on the official web site follow these steps 1 Unpack the release On the command line go to the root of the unpacked tree 2 Run either bootstrap bat on Windows or bootstrap sh on other operating systems 3 Run b2 install prefix PREFIX where PREFIX is a directory where you want Boost Build to be installed 4 Optionally add PREFIX bin to your PATH environment variable If you are not using a Boost Build package but rather the version bundled with the Boost C Libraries the above commands should be run in the tools build v2 directory Now that Boost Build is installed you can try some of the examples Copy PREFIX share boost build examples hello to a different directory then change to that directory and run PREFIX bin b2 A simple executable should be built http www renderx com 3 2 fa Tutorial This section will guide you though the most basic features of Boost Build V2 We will start with the Hello world example learn how to use libraries and finish with testing and installing features http www renderx com Tutorial Hello world The simplest project that Boost Build can construct is stored in ex
70. al 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 value that is used when a value for the feature is not otherwise 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 e symmetric Normally a feature only generates a subvariant directory when its value differs from its default value leading to an assymmetric subvariant directory structure for certain values of the feature A symmetric feature always generates a corresponding subvariant directory 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 e implicit Values of implicit features alone identify the feature For example a user is not required to write lt toolset gt gcc but can simply write gcc Implicit feature names also don t appear in variant paths 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 e composite Composite features actually correspond to groups of properties For example a build variant is a composite feature When gener ating t
71. al compiler flags that will be used when compiling both C and C sources linkflags Specifies additional command line options that will be passed to the linker Starting with Sun Studio 12 you can create 64 bit applications by using the address model 64 property 60 http www renderx com 3 2 fa Reference IBM Visual Age The vacpp module supports the IBM Visual Age C Compiler for the AIX operating system Versions 7 1 and 8 0 are known to work The module is initialized using the following syntax using vacpp The module does not accept any initialization options The compiler should be installed in the usr vacpp bin directory Later versions of Visual Age are known as XL C C They were not tested with the the vacpp module Third party libraries Boost Build provides special support for some third party C libraries documented below STLport library The STLport library is an alternative implementation of C runtime library Boost Build supports using that library on Windows platfrom Linux is hampered by different naming of libraries in each STLport version and is not officially supported Before using STI port you need to configure it in user config jam using the following syntax using stlport version header path library path Where version is the version of STLport for example 5 1 4 headers is the location where STLport headers can be found and libraries is the location where STLport
72. ample hello directory The project is described by a file called Jamroot that contains exe hello hello cpp Even with this simple setup you can do some interesting things First of all just invoking b2 will build the hello executable by compiling and linking hello cpp By default the debug variant is built Now to build the release variant of hello invoke b2 release Note that the debug and release variants are created in different directories so you can switch between variants or even build multiple variants at once without any unnecessary recompilation Let us extend the example by adding another line to our project s Jamroot exe hello2 hello cpp Now let us build both the debug and release variants of our project again b2 debug release Note that two variants of he11o02 are linked Since we have already built both variants of hello hello cpp will not be recompiled instead the existing object files will just be linked into the corresponding variants of hel 102 Now let us remove all the built products b2 clean debug releas It is also possible to build or clean specific targets The following two commands respectively build or clean only the debug version of hello2 b2 hello2 b2 clean hello2 http www renderx com Tutorial Properties To represent aspects of target configuration such as debug and release variants or single and multi threaded builds portably Boost Build uses features
73. an refer to any targets using 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 b2 appl libl libl gcc debug optimization full The complete syntax which has some additional shortcuts is described in 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 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 that value is added 2 Selecting the main target alternative to use For each alternative we look how many properties are present both in alternative s requirements and in build request The alternative with large number of matching properties is selected 3 Determining common properties The build request is 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 target references For each reference we take all propagated properties refine them by explici
74. ant crazy lt optimization gt speed lt inlining gt off lt debug symbols gt on lt profiling gt on will define a new variant with the specified set of properties You can also extend an existing variant variant super_release release lt define gt USE_ASM In this case super_release will expand to all properties specified by release and the additional one you ve specified You are not restricted to using the variant feature only Here s example that defines a brand new feature feature parallelism mpi fake none composite link incompatible feature compose lt parallelism gt mpi lt library gt mpi mpi lt parallelism gt none feature compose lt parallelism gt fake lt library gt mpi fake lt parallelism gt none This will allow you to specify the value of feature parallelism which will expand to link to the necessary library 92 http www renderx com Extender Manual Main target rules A main target rule e g exe Or 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 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 Boost Build automatically defines a corresponding rule The name of the rule is obtained from the name of the type by downcasing all letters and replacing underscores with dashes F
75. aration module expression Code within the executes within the module named by evaluating expression Rule definitions can be found in the module s own namespace and in the namespace of the global module as module name rule name so within a module other rules in that module may always be invoked without qualification module my_module rule salute x ECHO S x world rule greet salute hello greet my_module salute goodbye When an invoked rule is not found in the current module s namespace it is looked up in the namespace of the global module so qualified calls work across modules module your_module rule bedtime my_module salute goodnight Variable Scope Each module has its own set of dynamically nested variable scopes When execution passes from module A to module B all the variable bindings from A become unavailable and are replaced by the bindings that belong to B This applies equally to local and global variables 130 http www renderx com Boost Jam Documentation module A x 1 rule f local y 999 becomes visible again when B f calls A g But rule g ECHO S y prints 999 module B yrue rule f ECHO S y always prints 2 A g The only way to access another module s variables is by entering that module rule peek module name variables module module name
76. argets from a set of build properties composite features are recursively 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 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 additional dependency For example dependency features allow to state that library A depends 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 Features that are neither free nor incidental are called base features Feature Declaration The low level feature declaration interface is the feature rule from the feature module rule feature name allowed values attributes A feature s allowed values may be extended with the feature extend rule 78 http www renderx com Reference Property refinement When a target with certain properties is requested and that target requires some set of properties it is needed to find the set of properties to use for building This process is called property refinement and is performed by these rules 1 Each property in the required set is added to the original property set 2 If the original property set includes property with a different value of
77. aries can be either static which means they are included in executable files that use them or shared a k a dynamic which are only referred to from executables and must be available at run time Boost Build can create and use both kinds The kind of library produced from a 1 ib target is determined by the value of the link feature Default value is shared and to build a static library the value should be static You can request a static build either on the command line b2 link static or in the library s requirements lib 1 l cpp lt link gt static We can also use the lt link gt 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 target reference 80 to the library as follows exe important main cpp helpers lt link gt static No matter what arguments are specified on the b2 command line important will only be linked with the static version of helpers Specifying properties in target references is especially useful if you use a library defined in some other project one you can t change but you still want static or dynamic linking to that library in all cases If that library is used by many targets you could use target references everywhere exe el el cpp other_project bar lt link gt static exe e10 e10 cpp other_project bar lt link gt static but that s far f
78. caller return CALLER MODULE rule get caller s caller return CALLER MODULE 1 rule call Y return Y call X2 module Y rule call X return X get caller rule call X2 return X get caller s caller callers X get caller Y call X X call Y ECHO callers The DELETE MODULE Rule rule DELE H E MODULE module DELETE_MODULE removes all of the variable bindings and otherwise unreferenced rules from the given module or the global module if no module is supplied and returns their memory to the system N Note Though it won t affect rules that are currently executing until they complete DELETE_MODULE should be used with extreme care because it will wipe out any others and all variable including locals in that module immediately Because of the way dynamic binding works variables which are shadowed by locals will not be destroyed so the results can be really unpredictable 133 http www renderx com Boost Jam Documentation Miscellaneous Diagnostics In addition to generic error messages bjam may emit one of the following warning unknown rule X A rule was invoked that has not been defined with an actions or rule statement using N temp target s Targets marked as being temporary but nonetheless present have been found updating N target
79. can specify a set of attributes including requirements project requirements lt include gt home ghost Work boost lt threading gt multi exe hello hello cpp exe hello2 hello cpp The effect would be as if we specified the same requirement for both hello and hello2 http www renderx com Tutorial Project Hierarchies So far we have only considered examples with one project with one user written Boost Jam file Jamroot A typical large codebase would be composed of many projects organized into a tree The top of the tree is called the project root Every subproject is defined by a file called Jamfile in a descendant directory of the project root The parent project of a subproject is defined by the nearest Jamfile or Jamroot file in an ancestor directory For example in the following directory layout top Jamroot app Jamfile app cpp util foo Jamfile sa bar cpp the project root is top The projects in top app and top util foo are immediate children of the root project K we When we refer to a Jamfile set in normal type we mean a file called either Jamfile or Jamroot When we need to be more specific the filename will be set as Jamfile or Jamroot Projects inherit all attributes such as requirements from their parents Inherited requirements are combined with any requirements specified by the subproject For example if top
80. ce 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 introduction import generators generators register standard verbatim inline file VERBATIM CPP actions inline file inline file py lt gt We declare a standard generator specifying its id the source type and the target type When invoked the generator will create a target of type CPP with a source target of type VERBATIM as the only source But what command will be used to actually generate the file In bjam actions are specified using named actions blocks and the name of the action block should be specified when creating targets By convention generators use the same name of the action block as their own id So in above example the inline file actions block will be used to convert the source into the target There are two primary kinds of generators standard and composing which are registered with the generators register standard and the generators register composing rules respectively For example generators register standard verbatim inline file VERBATIM CPP generators register composing mex mex CPP LIB MEX The first standard generator takes a single source of type VERBATIM and produces a result The second composing generator takes any number of sources which ca
81. ces 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 glob rule Here are two examples 25 http www renderx com Overview exe a a cpp a cpp is the only source file exe b glob cpp all cpp files in this directory are sources Unless you specify a file with an absolute path the name is considered relative to the source directory which is typically the dir ectory where the Jamfile is located but can be changed as described in the section called Projects 29 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 must be qualified with a directory or a symbolic project name The directory project name is separated from the target name by a double forward slash There is no special syntax to distinguish the directory name from the project name the part before the double slash is first looked up as project name and then as directory name For example lib helper helper cpp exe a a cpp helper Since all project ids start with slash is a directory name exe b b cpp utils exe c c cpp boost program_options program_options The first exe uses the library defined in the same project
82. cpp alternative 1 lib demangler demangler_gcc cpp lt toolset gt gcc alternative 2 lib demangler demangler_msvc cpp lt toolset gt msvc alternative 3 In the example above when built with gcc or msvc demangler will use a source file specific to the toolset Otherwise it will use a generic source file dummy_demangler cpp It is possible to declare a target inline i e the sources parameter may include calls to other main rules For example exe hello hello cpp obj helpers helpers cpp lt optimization gt off Will cause helpers cpp to be always compiled without optimization When referring to an inline main target its declared name must be prefixed by its parent target s name and two dots In the example above 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 explicit rule explicit install programs 28 http www renderx com Overview Projects As mentioned before targets are grouped into projects and each Jamfile is a separate project Projects are useful because they allow us to group related targets together define properties common to all those targets and assign a symbolic name to the project that can be used in referring to its targets Projects are named using the project rule
83. d copies in target module of all rules exported from source module Also make them available in the global module with qualification so that it is just as though the rules were defined originally in target module path Performs various path manipulations Paths are always in a normalized representation In it a path may be either e or SOPI T token token 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 10 1 rule make native Converts the native path into normalized form rule native path Builds the native representation of the path rule is rooted path Tests if a path is rooted rule has parent path Tests if a path has a parent rule basename path Returns the path without any directory components rule parent path Returns the parent directory of the path If no parent exists an error is issued rule reverse path Returns path2 such that join path path2 The path may not contain element or be rooted 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 rule root path root If path is relative it is rooted at root Otherwise it is unchanged rule pwd
84. d in this section if executed successfully create a special manifest file to indicate that the test passed For the unit test rule the files is named target name passed and for the other rules it is called target name test The run rules also capture all output from the program and store it in a file named target name output 40 http www renderx com Common tasks If the preserve test targets feature has the value off then run and the run fail rules will remove the executable after running it This somewhat decreases disk space requirements for continuous testing environments The default value of preserve test targets feature is on It is possible to print the list of all test targets except for unit test declared in your project by passing the dump tests command line option The output will consist of lines of the form boost test test type path sources It is possible to process the list of tests Boost Build output and the presense absense of the test files created when test passes into human readable status table of tests Such processing utilities are not included in Boost Build 41 http www renderx com Common tasks Custom commands For most main target rules Boost Build automatically figures out the commands to run When you want to use new file types or support new tools one approach is to extend Boost Build to support them smoothly as documented in Extender Manual However if t
85. d supports precompiled headers with gcc and msvc toolsets To use precompiled headers follow the following steps 1 Create a header that includes headers used by your project that you want precompiled It is better to include only headers that are sufficiently stable like headers from the compiler and external libraries Please wrap the header in ifdef BOOST_BUILD_PCH_ENABLED so that the potentially expensive inclusion of headers is not done when PCH is not enabled Include the new header at the top of your source files 2 Declare a new Boost Build target for the precompiled header and add that precompiled header to the sources of the target whose compilation you want to speed up cpp pch pch i pech hpp exe main main cpp pch You can use the c pch rule if you want to use the precompiled header in C programs The pch example in Boost Build distribution can be used as reference Please note the following The inclusion of the precompiled header must be the first thing in a source file before any code or preprocessor directives The build properties used to compile the source files and the precompiled header must be the same Consider using project require ments to assure this Precompiled headers must be used purely as a way to improve compilation time not to save the number of include statements If a source file needs to include some header explicitly include it in the source file even if the same header is
86. dir specified in Jamroot or bin if none is specified The option is primarily useful when building from read only media when you can t modify Jamroot Prints information on the Boost Build and Boost Jam versions Causes all files to be rebuilt Do no execute the commands only print them 21 http www renderx com Overview q Stop at the first error as opposed to continuing to build targets that don t depend on the failed ones j N Run up to N commands in parallel debug configuration Produces debug information about the loading of Boost Build and toolset files debug building Prints what targets are being built and with what properties debug generators Produces debug output from the generator search process Useful for debugging custom generators ignore config Do not load site config jamor user config jam d0 Supress all informational messages d N Enable cummulative debugging levels from 1 to n Values are 1 Show the actions taken for building targets as they are executed the default 2 Show quiet actions and display all action text as they are executed 3 Show dependency analysis and target source timestamps paths 4 Show arguments and timming of shell invocations 5 Show rule invocations and variable expansions 6 Show directory header file archive scans and attempts at binding to targets 7 Show variable settings 8 Show variable fetches variable expansions and evaluation of if
87. directory of var D Local For Loop Variables Boost Jam allows you to declare a local for loop control variable right in the loop 126 http www renderx com 3 2 fa Boost Jam Documentation y 4 5 63 for local y in x ECHO y prints 1 2 or 3 ECHO S y prints 4 5 6 Generated File Expansion During expansion of expressions bjam also looks for subexpressions of the form filename E filecontents and replaces the expression with filename after creating the given file with the contents set to filecontents This is useful for creating compiler response files and other internal files The expansion works both during parsing and action execution Hence it is possible to create files during any of the three build phases Built in Variables This section discusses variables that have special meaning to b jam All of these must be defined or used in the global module using those variables inside a named module will not have the desired effect See Modules SEARCH and LOCATE These two variables control the binding of file target names to locations in the file system Generally SEARCH is used to find existing sources while LOCATE is used to fix the location for built targets Rooted absolute path file targets are bound as is Unrooted file target names are also normally bound as is and thus relative to the current directory but the settings of LOCATE and S
88. e following responsibilities e Maintaining a list of main targets in this project and building them l rule generate property set Overrides abstract target generate Generates virtual targets for all the targets contained in this project On success returns e a property set with the usage requirements to be applied to dependents alist of produced virtual targets which may be empty 2 rule build dir Returns the root build directory of the project 3 rule main target name Returns a 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 main target with the specified name exists Can only be called after the project has been fully loaded 5 rule find id no error Find and return the target with the specified id treated relative to self Id may specify either a target or a file name with the target taking priority May report an error or return nothing if the target is not found depending on the no error parameter Class main target class main target abstract target rule generate property set Methods inherited from abstract target rule name rule project rule location rule full name 71 http www renderx com Reference A main target represents a named top level target in a Jamfile l rule generate property set Overrides abstract target generate Sel
89. e generator class There are two methods of interest The run method is responsible for the overall process it takes a number of source targets converts them to the right types and creates the result The generated targets method is called when all sources are converted to the right types to actually create the result The generated targets method can be overridden when you want to add additional properties to the generated targets or use additional sources For a real life example suppose you have a program analysis tool that should be given a name of executable and the list of all sources Naturally you don t want to list all source files manually Here s how the generated targets method can find the list of sources automatically class itrace generator generator rule generated targets sources property set project name local leaves local temp virtual target traverse sources 1 include sources for local t in temp r if t action leaves t return generator generated targets sources leafs S property set project name generators register new itrace generator nm itrace EXE ITRACE The generated targets method will be called with a single source target of type EXE The call to virtual target travers will return all targets the executable depends on and we further find files that are not produced from a
90. e toolset to build with When the toolset is not given an attempt is made to detect an available toolset and use that The build scripts accept these arguments build toolset Running the scripts without arguments will give you the best chance of success On Windows platforms from a command console do cd jam source location build bat On Unix type platforms do cd jam source location sh build sh For the Boost Jam source included with the Boost distribution the jam source location is BOOST_ROOT tools jam src If the scripts fail to detect an appropriate toolset to build with your particular toolset may not be auto detectable In that case you can specify the toolset as the first argument this assumes that the toolset is readily available in the PATH EY Note The toolset used to build Boost Jam is independent of the toolsets used for Boost Build Only one version of Boost Jam is needed to use Boost Build The supported toolsets and whether they are auto detected are 109 http www renderx com Boost Jam Documentation Table A 1 Supported Toolsets Script build bat Platform Windows NT 2000 and XP Toolset borland Borland C Builder BCC 5 5 como Comeau Computing C C gcc GNU GCC gcc nocygwin GNU GCC intel win32 Intel C Compiler for Win dows metrowerks MetroWerks CodeWarrior C C 7 x 8 x 9 x mingw GNU GCC as the MinGW configuration mSvVCc Micros
91. e user does not have to adjust the values for a exact tool For example lt opt imization gt speed has the same meaning for all C compilers and the user does not have to worry about the exact options passed to the compiler s command line Besides such portable features there are special raw features that allow the user to pass any value to the command line parameters for a particular tool if so desired For example the lt cxxflags gt feature allows you to pass any command line options to a C compiler The lt include gt feature allows you to pass any string preceded by I and the interpretation is tool specific See the section called Can I get capture external program output using a Boost Jam variable 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 Boost Build does not take away any control from the user Using portable features is a good idea because e When a portable feature is given a fixed set of values you can build your project with two different settings of the feature and Boost Build will automatically use two different directories for generated files Boost Build does not try to separate targets built with different raw options e Unlike with raw features you don t need to use specific command line flags in your Jamfile and it will be more likely to work with other tools Steps for
92. 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 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 Preserving Directory Hierarchy By default the install rule will strip paths from its sources So if sources include a b c hpp the a b part will be ignored To make the install rule preserve the directory hierarchy you need to use the lt install source root gt feature to specify the root of the hierarchy you are installing Relative paths from that root will be preserved For example if you write 38 http www renderx com Common tasks install headers a b c h lt location gt tmp lt install source root gt a the a file named tmp b c h will be created The 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 alias rule can be used when targets need to be installed into several directories alias install install bin install lib install install bin applications usr bin install install lib helper usr lib Because the install rule just copies targets most free features l have no effect when used in requirements
93. ect 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 generate on that alternative On success returns e a property set with the usage requirements to be applied to dependents e alist of produced virtual targets which may be empty Class basic target class basic target abstract target rule __init__ name project sources requirements default build usage required ments rule generate property set rule construct name source targets property set Methods inherited from abstract target rule name rule project rule location rule full name Implements the most standard way of constructing main target alternative from sources Allows sources to be either files or other main targets and handles generation of those dependency targets l rule __init__ name project sources requirements default build usage requirements name The name of the target project The project in which the target is declared 2 rule generate property set Overrides abstract target generate Determines final build properties generates sources and calls construct This method should not be overridden On success returns e a property set with the usage requirements to be applied to dependents alist of produced virtual targets wh
94. ect error location inform ation when encountering an unexpected EOF It now also reports where an invalid lexical token being read started instead of finished which makes it much easier to find errors like unclosed quotes or curly braces Jurko G Removed the xarch generic architecture from build jam as this option is unknown so the Sun compilers on Linux Noel B Fixed a bug with T_FATE_ISTMP getting reported as T FATE_ISTMP amp T_FATE_NEEDTMP at the same time due to a missing break in a switch statement Jurko G Fixed a Boost Jam bug causing it to sometimes trigger actions depending on targets that have not been built yet Jurko G Added missing documentation for Boost Jam s T variable expansion modifier which converts all back slashes V to forward slashed Jurko G Added Boost Jam support for executing command lines longer than 2047 characters up to 8191 characters when running on Windows XP or later OS version Jurko G Fixed a Boost Jam bug on Windows causing its SHELL command not to work correctly with some commands containing quotes Jurko G Corrected a potential memory leak in Boost Jam s builtin_shell Q function that would appear should Boost Jam ever start to release its allocated string objects Jurko G Made all Boost Jam s ECHO commands automatically flush the standard output to make that output more promptly displayed to the user Jurko G Made Boost Jam tests quote their bjam ex
95. ecutable name when calling it allowing those executables to contain spaces in their name and or path Jurko G Change execunix c to always use fork instead of vfork on the Mac This works around known issues with bjam on PPC under Tiger and a problem reported by Rene with bjam on x86 under Leopard Noel B Corrected a bug in Boost Jam s base Jambase script causing it to trim the error message displayed when its boost build rule gets called multiple times Jurko G When importing from Python into an module with empty string as name import into root module Vladimir P Patch for the NORMALIZE_PATH builtin Boost Jam rule as well as an appropriate update for the path jam Boost Build module where that rule was being used to implement path join and related operations Jurko G Fixed a bug causing Boost Jam not to handle target file names specified as both short and long file names correctly Jurko G Relaxed test ignoring case of drive letter Roland S Implemented a patch contributed by Igor Nazarenko reimplementing the list_sort function to use a C qsort function instead of a hand crafted merge sort algorithm Makes some list sortings e g 1 2 1 2 1 2 1 2 extremely faster in turn significantly speeding up some project builds Jurko G Fixed a bug with bjam not handling the root Windows path correctly without its drive letter being specified Jurko G Solved the problem with child process returning
96. ed if you can t express everything you want that way you can return multiple regular expressions each of which contains a parenthesized group to be matched 85 http www renderx com Extender Manual After that we need to register our scanner class scanner register verbatim scanner include The value of the second parameter in this case include specifies the properties that contain the list of paths that should be searched for the included files Finally we assign the new scanner to the VERBATIM target type type set scanner VERBATIM verbatim scanner That s enough for scanning include dependencies 86 http www renderx com Extender Manual Tools and generators This section will describe how Boost Build can be extended to support new tools For each additional tool a Boost Build object called generator must be created That object has specific types of targets that it accepts and produces Using that information Boost Build is able to automatically invoke the generator For example if you declare a gen erator that takes a target of the type D and produces a target of the type OBJ when placing a file with extention d in a list of sources will cause Boost Build to invoke your generator and then to link the resulting object file into an application Of course this requires that you specify that the d extension corresponds to the D type Each generator should be an instan
97. ed automatically by basic target generate and should not be called directly by users Class property set Class for storing a set of properties class property set rule raw rule str rule propagated rule add ps rule add raw properties rule refine ps rule get feature 73 http www renderx com Reference There is 1 lt gt 1 correspondence between identity and value No two instances of the class are equal To maintain this property the property set create rule should be used to create new instances Instances are immutable l rule raw Returns a Jam list of the stored properties 2 rule str Returns the string repesentation of the stored properties 3 rule propagated Returns a property set containing all the propagated properties in this property set 4 rule add ps Returns a new property set containing the union of the properties in this property set and in ps N Note If ps contains non free properties that should override the values in this object use refine instead 5 rule add raw properties Link add except that it takes a list of properties instead of a property set 6 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 property set 7 rule get feature Returns all the values of feature 74 h
98. eing configured This setting makes sense only for Windows and only if you plan to use resource files By default windres will be used re type Specifies the type of resource compiler The value can be either windres for msve resource compiler or rc for borland s resource compiler 54 http www renderx com 3 2 fa Reference In order to compile 64 bit applications you have to specify address model 64 and the instruction set feature should refer to a 64 bit processor Currently those include nocona opteron athlon 4 and athlon fx Apple Darwin gcc The darwin module supports the version of gcc that is modified and provided by Apple The configuration is essentially identical to that of the gcc module The darwin toolset can generate so called fat binaries binaries that can run support more than one architecture or address mode To build a binary that can run both on Intel and PowerPC processors specify architecture combined To build a binary that can run both in 32 bit and 64 bit modes specify address mode1l 32_64 If you specify both of those properties a 4 way fat binary will be generated Microsoft Visual C The msvc module supports the Microsoft Visual C command line tools on Microsoft Windows The supported products and versions of command line tools are listed below e Visual Studio 2010 10 0 e Visual Studio 2008 9 0 e Visual Studio 2005 8 0 e Visual Studio NET 2003 7 1 e Visua
99. ements in bjam are rule procedure definitions rule invocations flow of control structures variable assignments and sundry language support Lexical Features BJan treats its input files as whitespace separated tokens with two exceptions double quotes can enclose whitespace to embed it into a token and everything between the matching curly braces in the definition of a rule action is treated as a single string A backslash can escape a double quote or any single whitespace character BJam requires whitespace blanks tabs or newlines to surround all tokens including the colon and semicolon tokens BJam keywords an mentioned in this document are reserved and generally must be quoted with double quotes to be used as ar bitrary tokens such as variable or target names Comments start with the character and extend until the end of line Targets The essential b jam data entity is a target Build targets are files to be updated Source targets are the files used in updating built targets Built targets and source targets are collectively referred to as file targets and frequently built targets are source targets for other built targets Pseudotargets are symbols which represent dependencies on other targets but which are not themselves associated with any real file A file target s identifier is generally the file s name which can be absolutely rooted relative to the directory of bjam s invocation or simp
100. er can be found nor have updating actions to build them Normally for such targets bjam issues a warning and then skips other targets that depend on these missing targets The HdrRule in Jambase uses NOCARE on the header file names found during header file scanning to let bjam know that the included files may not exist For example if an include is within an ifdef the included file may not actually be around 118 http www renderx com Boost Jam Documentation 1 Warning For targets with build actions if their build actions exit with a nonzero return code dependent targets will still be built NOTFILE rule NOTFILE targets Marks targets as pseudotargets and not real files No timestamp is checked and so the actions on such a target are only executed if the target s dependencies are updated or if the target is also marked with ALWAYS The default bj am target a11 is a pseudotarget In Jambase NOTFILE is used to define several addition convenient pseudotargets NOUPDATE rule NOUPDATE targets Causes the timestamps on targets to be ignored This has two effects first once the target has been created it will never be updated second manually updating target will not cause other targets to be updated In Jambase for example this rule is applied to direct ories by the MkDir rule because MkDir only cares that the target directory exists not when it has last been updated TEMPORA
101. er on Linux and Windows respectively The module is initialized using the following syntax using como linux version c compile command compiler options This statement may be repeated several times if you want to configure several versions of the compiler If the command is not specified Boost Build will search for a binary named como in PATH The following options can be provided using lt opt ion name gt opt ion value syntax cflags Specifies additional compiler flags that will be used when compiling C sources cxxflags Specifies additional compiler flags that will be used when compiling C sources compileflags Specifies additional compiler flags that will be used when compiling both C and C sources linkflags Specifies additional command line options that will be passed to the linker Before using the Windows version of the compiler you need to setup necessary environment variables per compiler s documentation In particular the COMO XXX INCLUDE variable should be set where xxx corresponds to the used backend C compiler 58 http www renderx com 3 2 fa Reference Code Warrior The cw module support CodeWarrior compiler originally produced by Metrowerks and presently developed by Freescale Boost Build supports only the versions of the compiler that target x86 processors All such versions were released by Metrowerks before aquisition and are not sold any longer The last version known to work i
102. erx com Boost Jam Documentation actions quietly The action is not echoed to the standard output actions together The gt from multiple invocations of the same action on the same built target are glommed together actions updated gt includes only source targets themselves marked for updating Argument lists You can describe the arguments accepted by a rule and refer to them by name within the rule For example the following prints I m sorry Dave to the console rule report pronoun index state names local he suffix she suffix it suffix s local I suffix m local they suffix you suffix re ECHO pronoun pronoun suffix state names index report I 2 sorry Joe Dave Pete wow Each name in a list of formal arguments separated by in the rule declaration is bound to a single element of the corresponding actual argument unless followed by one of these modifiers Symbol Semantics of preceding symbol optional Bind to zero or more unbound elements of the actual argument When appears where an argument name is expected any number of additional arguments are accepted This feature can be used to implement varargs rules Bind to one or more unbound elements of the actual argument The actual and formal arguments are checked for inconsistencies which cause Jam to exit with an error code argument error rule report pronoun index state
103. es libraries and C sources For each C source we create a separate Python extension by calling generators construct and passing the C source and the libraries At this point we also change the extension s name if necessary 89 http www renderx com Extender Manual Features Often we need to control the options passed the invoked tools This is done with features Consider an example Declare a new fr featur import feature feature feature verbatim options free Cause the value of the verbatim options feature to be available as OPTIONS variable inside verbatim inline file import toolset flags flags verbatim inline file OPTIONS lt verbatim options gt Use the OPTIONS variable actions inline file inline file py OPTIONS lt gt We first define a new feature Then the flags invocation says that whenever verbatin inline file action is run the value of the verbatim options feature will be added to the OPTIONS variable and can be used inside the action body You d need to consult online help help to find all the features of the toolset flags rule Although you can define any set of features and interpret their values in any way Boost Build suggests the following coding standard for designing features Most features should have a fixed set of values that is portable tool neutral across the class of tools they are designed to work with Th
104. es in your project The svn exclude pattern prevents the glob t ree rule from entering administrative directories of the Subversion version control system Declares project id and attributes including project requirements See the section called Projects Assigns a symbolic project ID to a project at a given path This rule must be better documented The explicit rule takes a single parameter a list of target names The named targets will be marked ex plicit 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 The always funciton takes a single parameter a list of metatarget names The top level targets produced by the named metatargets will be always considered out of date Consider this example 48 http www renderx com Reference constant path constant build project test suite exe hello hello cpp exe bye bye cpp always hello If a build of hello is requested then the binary will always be relinked The object files will not be recompiled though Note that if a build of hello is not requested for example you specify just bye on the command line hello will not be relinked 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
105. es the default build directory For example exe a a cpp lt location gt builds all the files produced by a in the directory of the Jamfile This is generally discouraged as it precludes variant builds The lt location prefix gt feature adds a prefix to the path under the project s build directory For example exe a a cpp lt location prefix gt subdir will create the files for a in bin subdir gcc 4 6 1 debug 76 http www renderx com Reference Definitions Features and properties A feature is a normalized toolset independent aspect of a build configuration such as whether inlining is enabled Feature names may not contain the gt character Each feature in a build configuration has one or more associated values Feature values for non free features may not contain the lt or characters Feature values for free features may not contain the lt character A property is a feature value pair expressed as lt feature gt value A subfeature is a feature that only exists in the presence of its parent feature and whose identity can be derived in the context of its parent from its value A subfeature s parent can never be another subfeature Thus features and their subfeatures form a two level hierarchy A value string for a feature F is a string of the form value subvaluel subvalue2 subvalueN where value is a legal value for F and subvaluel subvalueN are legal values of some
106. et 82 http www renderx com Extender Manual It it permissible to create a custom class derived from basic target and create new metatarget rule that creates instance of such target However in the majority of cases a specific subclass of basic 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 anew metatarget rule is automatically defined That rule creates new instance of type target associated with that type Concrete targets Concrete targets are represented by instance of classes derived from virtual target The most commonly used subclass is file target A file target is associated with an action that creates it an instance of the act ion class The action in turn hold a list of source targets It also holds the 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 local a new action source common copy property set local t new file target name CPP S project a The first line creates an instance of the act ion gt class The first parameter is the list of sources The second parameter is the name a jam level action 18 The third parameter is the property set applying to this action The second line creates a target We specifie a
107. exe app app cpp lt implicit dependency gt parser 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 44 http www renderx com Common tasks Cross compilation Boost Build 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 the section called Configuration for example using gcc arm arm none linux gnueabi gt After that if the host and target os are the same for example Linux you can just request that this compiler version to be used b2 toolset gcc arm If you want to target different operating system from the host you need to additionally specify the value for the target os feature for example On windows box b2 toolset gcc arm target os linux On Linux box b2 toolset gcc mingw target os windows For the complete list of allowed opeating system names please see the documentation for target os feature When using the msvc compiler it s only possible to cross compiler to a 64 bit system on a 32 bit host Please see the section called 64 bit support for details 45 http www renderx com 3 2 Reference 46 http www renderx com 3 2 fa Reference General information Initialization bjam s first job upon startup is
108. following syntax using doxygen name name is the doxygen command If it is not specified it will be found in the PATH The doxygen module depends on the boostbook module when generating BoostBook XML The following options can be provided using lt opt ion name gt opt ion value syntax 62 http www renderx com Reference doxygen param All the values of doxygen param are added to the doxyfile prefix Specifies the common prefix of all headers when generating BoostBook XML Everything before this will be stripped off reftitle Specifies the title of the library reference section when generating BoostBook XML doxygen xml imagedir When generating BoostBook XML specifies the directory in which to place the images generated from LaTex formulae Warning The path is interpreted relative to the current working directory not relative to the Jamfile This is necessary to match the behavior of BoostBook The doxygen module defines a rule for creating a target following the common syntax doxygen rule doxygen target sources requirements default build usage required ments Creates a doxygen target If the target name ends with html then this will generate an html directory Otherwise it will generate BoostBook XML quickbook The quickbook module provides a generator to convert from Quickbook to BoostBook XML To use quickbook you first need to configure it using the follo
109. form For example in Linux running on an Intel x86 compatible chip the executables are placed in bin linuxx86 The bjam exe executable can be used to invoke Boost Build The build scripts support additional invocation arguments for use by developers of Boost Jam and for additional setup of the toolset The extra arguments come after the toolset Arguments not in the form of an option before option arguments are used for extra setup to toolset configuration scripts e Arguments of the form option which are passed to the build jam build script e Arguments not in the form of an option after the options which are targets for the build jam script 113 http www renderx com Boost Jam Documentation build toolset setup option target The arguments immediately after the toolset are passed directly to the setup script of the toolset if available and if it needs to be in voked This allows one to configure the toolset ass needed to do non default builds of bjam For example to build a Win64 version with vc8 See the toolset descriptiona above for when particular toolsets support this The arguments starting with the option forms are passed to the build jam script and are used to further customize what gets built Options and targets supported by the build jam script release debug 9rammar with python path gc duma toolset root path show locat
110. gt speed lt debug symbols gt off lt inlining gt full lt runtime ded bugging gt off The value profile expands to the same as release plus lt profiling gt on lt debug symbols gt on Users can define their own build variants using the variant rule from the common module Note Runtime debugging is on in debug builds to suit the expectations of people used to various IDEs Allowed values shared static A feature controling how libraries are built Allowed values shared static Controls if a static or shared C C runtime should be used There are some restrictions how this feature can be used for example on some compilers an application using static runtime should not use shared libraries at all and on some compilers mixing static and shared runtime requires extreme care Check your compiler documentation for more details Allowed values single multi Controls if the project should be built in multi threaded mode This feature does not necessary change code generation in the compiler but it causes the compiler to link to additional or different runtime libraries and define additional preprocessor symbols for example _MT on Windows and _REENTRANT on Linux How those symbols affect the compiled code depends on the code itself The lt source gt x feature 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
111. hat is to be passed to C and C compilers Specifies an 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 The lt warnings gt feature controls the warning level of compilers It has the following values off disables all warnings on enables default warning level for the tool e all enables all warnings Default value is a11 The lt warnings as errors gt makes it possible to treat warnings as errors and abort compil ation on a warning The value on enables this behaviour The default value is off Allowed values no The build feature is used to conditionally disable build of a target If lt build gt no is in properties when building a target build of that target is skipped Combined with conditional 51 http www renderx com Reference tag debug symbols target os architecture instruction set address model c template depth requirements this allows you to skip building some target in configurations where the build is known to fail The tag feature is used to customize the name of the generated files The value should have the form rulename where rulename should be a name of a rule with the following signature rule tag name type property set The rule will be called for each target with the default name computed b
112. he Jam documentation should probably be titled Modifying Update Determination Grist is just a string prefix of the form lt characters gt It is used in Jam to create unique target names based on simpler names For example the file name test exe may be used by targets in separate subprojects or for the debug and release variants of the same abstract target Each distinct target bound to a file called test exe has its own unique grist prefix The Boost build system also takes full advantage of Jam s ability to divide strings on grist boundaries sometimes concatenating multiple gristed elements at the beginning of a string Grist is used instead of identifying targets with absolute paths for two reasons 1 The location of targets cannot always be derived solely from what the user puts in a Jamfile but sometimes depends also on the binding process Some mechanism to distinctly identify targets with the same name is still needed 2 Grist allows us to use a uniform abstract identifier for each built target regardless of target file location as allowed by setting ALL_LOCATE_TARGET 135 http www renderx com Boost Jam Documentation When grist is extracted from a name with var G the result includes the leading and trailing angle brackets When grist is added to a name with var G expr existing grist is first stripped Then if expr is non empty leading lt s and trailing gt s are added if necessary to form an
113. he feature has a fixed set of values so 23 http www renderx com Overview b2 include static shared is not treated specially Targets All command line elements that are neither options nor properties are the names of the targets to build See the section called Target identifiers and references If no target is specified the project in the current directory is built 24 http www renderx com Overview Declaring Targets 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 the section called Builtin rules The user can also declare custom main target rules as shown in the section called Main target rules Most main target rules in Boost Build have the same common signature rule rule name main target name sources requirements default build usage requirements e main target name is the name used to request the target on command line and to use it from other main targets A main target name may contain alphanumeric characters dashes and underscores _ e sources is the list of source files and other main targets that must be combined e requirements is the list of properties that must always be present when this main target is built e default buildis the list of properties that will be used unless some other
114. he file location The difference between using the file feature and using a combination of the name and search features is that file is more precise Warning The value of the search feature is just added to the linker search path When linking to multiple libraries the paths specified by search are combined without regard to which lib target each path came from Thus given lib a lt name gt a lt search gt pool release lib b lt name gt b lt search gt pool debug If pool release a so pool release b so pool debug a so and pool release b so all exist the linker will probably take both a and b from the same directory instead of finding a in pool release and b in pool debug If you need to distinguish between multiple libraries with the same name it s safer to use file For convenience the following syntax is allowed lib z lib gui db aux which has exactly the same effect as 35 render http www renderx com render r Common tasks lib z lt name gt z lib gui lt name gt gui lib db lt name gt db lib aux lt name gt aux When a library references another library you should put that other library in its list of sources This will do the right thing in all cases For portability you should specify library dependencies even for searched and prebuilt libraries othewise static linking on Unix will not work For example lib z lib png z lt
115. he new tool is only used in a single place it might be easier just to specify the commands to run explicitly Three main target rules can be used for that The make rule allows you to construct a single file from any number of source file by running a command you specify The notfile rule allows you to run an arbitrary command without creating any files And finaly the generate rule allows you to describe a transformation using Boost Build s virtual targets This is higher level than the file names that the make rule operates with and allows you to create more than one target create differently named targets depending on properties or use more than one tool The make rule is used when you want to create one file from a number of sources using some specific command The not file is used to unconditionally run a command Suppose you want to create the file file out from the file file in by running the command in2out Here is how you would do this in Boost Build make file out file in in2out actions in2out in2out lt gt If you run b2 and file out does not exist Boost Build will run the in2out command to create that file For more details on specifying actions see the section called Boost Jam Language 18 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 the not file rule For example notfile echo_something echo ac
116. hod 74 all bases 68 all derived 68 all parents 67 always building a metatarget base 68 basename 66 basic target 72 binding 64 boostbook module 62 rule build dir Project Target Method 71 C call in 65 catalog change generated target prefix 68 change generated target suffix 68 clone rules 65 common signature 25 construct Basic Target Method 72 Typed Target Method 73 cross compilation 45 D exists 67 F fat binaries 55 features builtin 50 find Project Target Method 71 fo fop 63 format full name Abstract Target 70 G generate Abstract Target 70 Basic Target Method 72 Main Target Method 72 Project Target 71 generated target prefix 68 generated target suffix 68 generators 83 get Property Set Method 74 get scanner 68 glob 66 glob in parents 67 glob tree 67 H hardcode dll paths has main target Project Target Method 71 has parent 66 html htmlhelp implicit dependency import 65 include install source root 38 instruction set is derived 68 define is rooted 66 dependency dll path J docbook Px doxygen 62 Jom 68 rule L doxygen param i doxygen xml imagedir library target 35 E link embed manifest 53 ead fa location exe 34 141 http www renderx com 3 2 fa Index Abstract Target 70 main target see metataget declaration syntax 25 main target 71 Project Target Method 71 make path 66 man manifes
117. hould be done with user config switch or similar Roland S Initial support for defining action body from Python Vladimir P Implement expansion during parse phase Rene R Define OSPLAT var unconditionally and more generically when possible Rene R Fix undeclared INT_MAX on some platforms i e Linux Rene R Modified execunix c to add support for terminating processes that consume too much cpu or that hang and fail to consume cpu at all This in support of the bjam 1x option Noel B Add internal dependencies for multi file generating actions to indicate that the targets all only appear when the first target appears This fixes the long standing problem Perforce Jam has with multi file actions and parallel execution JN Rene R Add test of 1 limit option now that it s implemented on windows and unix Rene R Add test for no op expansion Rene R Handle invalid formats of as doing a straight substitution instead of erroring out Rene R Various fixes to compile on SGI Irix Noel B Add output for when actions timeout with IN option Rene R Noel B Add needed include according to XOPEN for definition of WIFEXITED and WEXITSTATUS Markus S 3 2 fa 140 http www renderx com 3 2 fa Index Symbols 64 bit compilation gcc 55 Microsoft Visual Studio 56 Sun Studio 60 A abstract target 70 add Property Set Method 74 add raw Property Set Met
118. ht cause reading of further Jamfiles As a result a tree of projects is created with targets inside projects 4 Finally using the build request specified on the command line Boost Build decides which targets should be built and how That information is passed back to Boost Jam which takes care of actually running the scheduled build action commands So to be able to successfully use Boost Build you need to know only four things How to configure Boost Build How to declare targets in Jamfiles e How the build process works e Some Basics about the Boost Jam language See the section called Boost Jam Language http www renderx com Overview Concepts Boost Build has a few unique concepts that are introduced in this section The best way to explain the concepts is by comparison with more classical build tools When using any flavour of make you directly specify targets and commands that are used to create them from other target The below example creates a o from a c using a hardcoded compiler invocation command alor a c gtt o a o g a c This is a rather low level description mechanism and it s hard to adjust commands options and sets of created targets depending on the compiler and operating system used To improve portability most modern build system provide a set of higher level functions that can be used in build description files Consider this example add program a a c This is a func
119. ich may be empty 3 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 overriden in derived classes 72 http www renderx com Reference Class typed target class typed target basic target rule __init__ name project type sources requirements default build usage requirements rule type rule construct name source targets property set Methods inherited from abstract target rule name rule project rule location rule full name Methods inherited from basic target rule generate property set typed target is the most common kind of target alternative Rules for creating typed targets are defined automatically for each type l rule __init__ name project type sources requirements default build usage requirements name The name of the target project The project in which the target is declared type The type of the target 2 rule type Returns the type of the target 3 rule construct name source targets property set Implements basic target construct Attempts to create a target of the correct type using generators appropriate for the given property set Returns a property set containing the usage requirements and a list of virtual targets N Note This function is invok
120. included from the precompiled header This makes sure that your project will build even if precompiled headers are not supported On the gcc compiler the name of the header being precompiled must be equal to the name of the cpp pch target This is a gcc requirement Prior to version 4 2 the gcc compiler did not allow anonymous namespaces in precompiled headers which limits their utility See the bug report for details 43 http www renderx com 3 2 fa Common tasks Generated headers Usually Boost Build handles implicit dependendies completely automatically For example for C files all include statements are found and handled The only aspect where user help might be needed is implicit dependency on generated files By default Boost Build handles such dependencies within one main target For example assume that main target app has two sources app cpp and parser y The latter source is converted into parser c and parser h Then if app cpp includes parser h Boost Build will detect this dependency Moreover since parser h will be generated into a build directory the path to that directory will automatically added to include path Making this mechanism work across main target boundaries is possible but imposes certain overhead For that reason if there is implicit dependency on files from other main targets the lt implicit dependency gt feature must be used for example lib parser parser y
121. is the value of its last statement though only the following statements have values if value of the leg chosen switch value of the case chosen set value of the resulting variable and return value of its arguments Note that return doesn t actually cause a return i e is a no op unless it is the last statement of the last block executed within rule body The bjam statements for defining and invoking rules are as follows Define a rule s procedure replacing any previous definition 115 http www renderx com Boost Jam Documentation rule rulename statements Define a rule s updating actions replacing any previous definition actions modifiers rulename commands Invoke a rule rulename field1 field2 fieldN Invoke a rule under the influence of target s specific variables on target rulename fieldl field2 fieldN Used as an argument expands to the return value of the rule invoked rulename field1 field2 fieldN on target rulename field1 field2 fieldN A tule is invoked with values in field through fieldN They may be referenced in the procedure s statements as 1 through N 9 max and the first two only may be referenced in the action s commands as 1 and 2 lt and gt are synonymous with 1 and 2 Rules fall into two categories updating rules with actions and pure procedure rules without actions
122. ive 3 will be selected In all other cases the most generic alternative will be built 12 http www renderx com Tutorial Prebuilt targets To link to libraries whose build instructions aren t given in a Jamfile you need to create 1ib targets with an appropriate file property Target alternatives can be used to associate multiple library files with a single conceptual target For example t util lib2 Jamfile lib 1ib2 lt file gt lib2_release a lt variant gt release lib lib2 lt file gt lib2_debug a lt variant gt debug This example defines two alternatives for 1ib2 and for each one names a prebuilt file Naturally there are no sources Instead the lt file gt feature is used to specify the file name Once a prebuilt target has been declared it can be used just like any other target exe app app cpp util lib2 lib2 As with any target the alternative selected depends on the properties propagated from 1ib2 s dependants If we build the release and debug versions of app will be linked with 1ib2_release a and 1ib2_debug a respectively System libraries those that are automatically found by the toolset by searching through some set of predetermined paths should be declared almost like regular ones lib pythonlib lt name gt python22 We again don t specify any sources but give a name that should be passed to the compiler If the gcc toolset were used to link an executable target to pythonlib
123. knows the paths to all libraries and can include them in the executables That is done when the hardcode dll paths feature has the true value which is the default When the executables should be installed the story is different Obviously installed executable should not contain hardcoded paths to your development tree The install rule explicitly disables the hardcode dll paths feature for that reason However you can use the dll path feature to add explicit paths manually For example install installed application lt dll path gt usr lib snake lt location gt usr bin will allow the application to find libraries placed in the usr 1lib snake directory If you install libraries to a nonstandard location and add an explicit path you get more control over libraries which will be used A library of the same name in a system location will not be inadvertently used If you install libraries to a system location and do not add any paths the system administrator will have more control Each library can be individually upgraded and all applications will use the new library Which approach is best depends on your situation If the libraries are relatively standalone and can be used by third party applications they should be installed in the system location If you have lots of libraries which can be used only by your application it makes sense to install them to a nonstandard directory and add an explicit path like the example above shows
124. l Studio NET 7 0 e Visual Studio 6 0 Service Pack 5 6 5 The msvc module is initialized using the following syntax using msvc version ct compile command compiler options al This statement may be repeated several times if you want to configure several versions of the compiler If the version is not explicitly specified the most recent version found in the registry will be used instead If the special value a11 is passed as the version all versions found in the registry will be configured If a version is specified but the command is not the compiler binary will be searched in standard installation paths for that version followed by PATH The compiler command should be specified using forward slashes and quoted The following options can be provided using lt option name gt option value syntax cflags Specifies additional compiler flags that will be used when compiling C sources cxxflags Specifies additional compiler flags that will be used when compiling C sources compileflags Specifies additional compiler flags that will be used when compiling both C and C sources linkflags Specifies additional command line options that will be passed to the linker assembler The command that compiles assembler sources If not specified ml will be used The command will be invoked after the setup script was executed and adjusted the PATH variable compiler The command that compiles C and C sources If not specified
125. l be pruned 15 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 rule relative child parent no error Assuming child is a subdirectory of parent return the relative path from parent to child I7 rule relative to pathl path2 Returns the minimal path to path2 that is relative path1 18 rule programs path Returns the list of paths which are used by the operating system for looking up programs 19 rule makedirs path Creates a directory and all parent directories that do not already exist type Deals with target type declaration and defines target class which supports typed targets l 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 register suffixes rule with the given suffixes and the set generated target suffix rule with the first given suffix 2 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 rule registered type 67 http www renderx com Reference 10 11 Returns true iff type has been registered rule validate type
126. large set of allowed values has been defined for this feature and if a different one is needed user can easily add it by calling the feature extend rule Allowed values on off This feature is specific to the msvc toolset see the section called Microsoft Visual C 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 Manifest Tool gt Input and Output Embed manifest 53 http www renderx com Reference Builtin tools Boost Build comes with support for a large number of C compilers and other tools This section documents how to use those tools Before using any tool you must declare your intention and possibly specify additional information about the tool s configuration This is done by calling the using rule typically in your user config jam for example using gcc additional parameters can be passed just like for other rules for example using gcc 4 0 g 4 0 The options that can be passed to each tool are documented in the subsequent sections C Compilers This section lists all Boost Build modules that support C compilers and documents how each one can be initialized The name of support module for compiler is also the value for the toolset feature that can be used to explicitly request that c
127. lationship one can use the lt use gt feature For example both of the following lines will cause a to appear before b on the command line lib ai a cppb lib a a cpp lt use gt b The same approach works for searched libraries as well Lib 2 lib png lt use gt z xe viewer viewer png z 101 http www renderx com Frequently Asked Questions Can I get capture external program output using a Boost Jam variable The SHELL builtin rule may be used for this purpose local gtk_includes SHELL gtk config cflags 102 render X http www renderx com Frequently Asked Questions 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 access it just declare a path constant in your Jamroot jam file using path constant TOP After that the TOP variable can be used in every Jamfile 103 http www renderx com Frequently Asked Questions How to change compilation flags for one file If one file must be compiled with special options you need to explicitly declare an obj target for that file and then use that target in your exe or lib target exe ai a cpp b obj b b cpp lt optimization gt off Of course you can use other properties for example to specify specific C C compiler options exe a a cpp b obj b b cpp lt cflags gt g You can also use co
128. le to return a rule s value is actually the value of the last statement executed so a return should be the last statement executed before the rule naturally returns switch value case patternl statements case pattern2 statements The switch statement executes zero or one of the enclosed statements depending on which if any is the first case whose pattern matches value The pattern values are not variable expanded The pattern values may include the following wildcards match any single character match zero or more characters chars match any single character in chars chars match any single character not in chars x match x escapes the other wildcards while cond statements Repeatedly execute statements while cond remains true upon entry See the description of cond expression syntax under if above Variables BJam variables are lists of zero or more elements with each element being a string value An undefined variable is indistinguishable from a variable with an empty list however a defined variable may have one more elements which are null strings All variables are referenced as variable Variables are either global or target specific In the latter case the variable takes on the given value only during the updating of the specific target A variable is defined with 124 http www renderx com Boost Jam Documentation variable elements variable elements va
129. licitly specify the command Many of toolsets have an opt ions parameter to fine tune the configuration All of Boost Build s standard compiler toolsets accept four options cflags cxxflags compileflags and linkflags as options specifying flags that will be always passed to the corresponding tools Values of the cflags feature are passed directly to the C compiler values of the cxxflags feature are passed directly to the C compiler and values of the compileflags feature are passed to both For example to configure a gcc toolset so that it always generates 64 bit code you could write using gcc 3 4 lt compileflags gt m64 lt linkflags gt m64 amp Q Warning Although the syntax used to specify toolset options is very similar 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 20 http www renderx com 3 2 fa Overview Invocation To invoke Boost Build type b2 on the command line Three kinds of command line tokens are accepted in any order options Options start with either one or two dashes The standard options are listed below and each project may add addi tional options properties Properties specify details of what you want to build e g debug or release variant Syntactically all command line tokens with an equal sign in them are considered to specify properties In the simplest f
130. ll be used on many projects users will thank you for a finishing touch The using rule provides a standard mechanism for loading and configuring extensions To make it work your module should provide an init rule The rule will be called with the same parameters that were passed to the using rule The set of allowed parameters is determined by you For example you can allow the user to specify paths tool versions and other options Here are some guidelines that help to make Boost Build more consistent e The init rule should never fail Even if the user provided an incorrect path you should emit a warning and go on Configuration may be shared between different machines and wrong values on one machine can be OK on another e Prefer specifying the command to be executed to specifying the tool s installation path First of all this gives more control it s possible to specify usr bin gt snapshot time g as the command Second while some tools have a logical installation root it s better if the user doesn t have to remember whether a specific tool requires a full command or a path e Check for multiple initialization A user can try to initialize the module several times You need to check for this and decide what to do Typically unless you support several versions of a tool duplicate initialization is a user error If the tool s version can be specified during initialization make sure the version is either always specified or ne
131. lper 1 2 3 This code calls the named rule with the specified arguments When the result of the call must be used inside some expression you need to add brackets around the call like shown on the second line if cond statements else statements This is a regular if statement The condition is composed of Literals true if at least one string is not empty e Comparisons a operator b where operator is one of lt gt lt or gt The comparison is done pairwise between each string in the left and the right arguments e Logical operations a a amp amp b a b e Grouping cond for var in list statements Executes statements for each element in list setting the variable var to the element value while cond statements Repeatedly execute statements while cond remains true upon entry return values This statement should be used only inside a rule and assigns values to the return value of the rule amp Q Warning The return statement does not exit the rule For example rule test iE 1S 1 return reasonable return strange will return st range not reasonable import module import module rule 17 http www renderx com Overview The first form imports the specified module All rules from that module are made available using the qualified name module rule The second form imports the specified rules only
132. ly local no directory Most often it is the last case and the actual file path is bound using the SEARCH and LOCATE special variables See SEARCH and LOCATE Variables below A local filename is optionally qualified with grist a string value used to assure uniqueness A file target with an identifier of the form file member is a library member usually an ar 1 archive on Unix Binding Detection Whenever a target is bound to a location in the filesystem Boost Jam will look for a variable called BINDRULE first on the target being bound then in the global module If non empty BINDRULE 1 names a rule which is called with the name of the target and the path it is being bound to The signature of the rule named by BINDRULE 1 should match the following rule bind rule target path This facility is useful for correct header file scanning since many compilers will search for include files first in the directory containing the file doing the include directive BINDRULE can be used to make a record of that directory Rules The basic b jam language entity is called a rule A rule is defined in two parts the procedure and the actions The procedure is a body of jam statements to be run when the rule is invoked the actions are the OS shell commands to execute when updating the built targets of the rule Rules can return values which can be expanded into a list with rule args A rule s value
133. magic would only help 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 render gt 98 http www renderx com Frequently Asked Questions 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 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 be reasonable Boost Jam automatically imports all environment variables into its built in ENVIRON module so user can read them from there directly or by using the helper os environ rule For example import os local unga unga os environ UNGA_UNGA ECHO unga unga or a bit more realistic import os local SOME_LIBRARY_PATH os environ SOME_LIBRARY_PATH exe a a cpp lt include gt SOME LIBRARY PATH 99 http www renderx com Frequently Asked Questions How to control properties order For internal reasons Boost Build sorts all the properties alphabetically This means that if you write exe a a cpp lt include gt b lt include gt a then the command line with first men
134. manually or have the build place the ap plication and the libraries into the same directory See the section called Installing 34 http www renderx com Common tasks Libraries Library targets are created using the 1ib rule which follows the common syntax For example 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 lt link gt feature Library targets can represent e Libraries that should be built from source as in the example above Prebuilt libraries which already exist on the system Such libraries can be searched for by the tools using them typically with the linker s 1 option or their paths can be known in advance by the build system The syntax for prebuilt libraries is given below lib z lt name gt z lt search gt home ghost lib compress lt file gt opt libs compress a The name property specifies the name of the library without the standard prefixes and suffixes For example depending on the system z could refer to a file called z so libz a or z lib etc The search feature specifies paths in which to search for the library in addition to the default compiler paths search can be specified several times or it can be omitted in which case only the default compiler paths will be searched The file property specifies t
135. me 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 boostbook To use boostbook you first need to configure it using the following syntax using boostbook docbook xsl dir docbook dtd dir boostbook dir docbook xs1 diris the DocBook XSL stylesheet directory If not provided we use DOCBOOK_XSL_DIR from the environment if available or look in standard locations Otherwise we let the XML processor load the stylesheets remotely docbook dtd dir is the DocBook DTD directory If not provided we use DOCBOOK_DTD_DIR From the environment if available or look in standard locations Otherwise we let the XML processor load the DTD remotely boostbook dir is the BoostBook directory with the DTD and XSL subdirs The boostbook module depends on xsltproc For pdf or ps output it also depends on fop The following options can be provided using lt opt ion name gt opt ion value syntax format Allowed values html xhtml htmlhelp onehtml man pdf ps docbook fo tests The format feature determines the type of output produced by the boostbook rule The boostbook module defines a rule for creating a target following the common syntax boostbook rule boostbook target name sources requirements default build Creates a boostbook target doxygen To use doxygen you first need to configure it using the
136. n have either the CPP or the LIB type Composing generators are typically used for generating top level target type For example the first generator invoked when building an exe target is a composing generator corresponding to the proper linker You should also know about two specific functions for registering generators generators register c compiler and gener ators register linker The first sets up header dependecy scanning for C files and the seconds handles various complexities like searched libraries For that reason you should always use those functions when adding support for compilers and linkers Need a note about UNIX Custom generator classes The standard generators allows you to specify source and target types an action and a set of flags If you need anything more complex you need to create a new generator class with your own logic Then you have to create an instance of that class and register it Here s an example how you can create your own generator class 87 http www renderx com Extender Manual class custom generator generator tule init 3 generator __init__ 1 2 3 4 5 6 7 8 9 generators register new custom generator verbatim inline file VERBATIM CPP r This generator will work exactly like the verbatim inline file generator we ve defined above but it s possible to customize the behaviour by overriding methods of th
137. name a type and a project We also pass the action object created earlier If the action creates several targets we can repeat the second line several times In some cases code that creates concrete targets may be invoked more than once with the same properties Returning to different instance of file target that correspond to the same file clearly will result in problems Therefore whenever returning targets you should pass them via the virtual target register function that will replace targets with previously created identical ones as necessary Here are a couple of examples return virtual target register t return sequence transform virtual target register targets Generators In theory every kind of metatarget in Boost Build like exe 1ib or obj could be implemented by writing a new metatarget class that independently of the other code figures what files to produce and what commands to use However that would be rather inflexible For example adding support for a new compiler would require editing several metatargets In practice most files have specific types and most tools consume and produce files of specific type To take advantage of this fact Boost Build defines concept of target type and generators and has special metatarget class 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
138. nclude gt usr local include or alias a with include a cpp lt include gt usr local include xe a a with include xe b a with include or if you want the includes property not to affect how any other sources added for the built a and b executables would be compiled obj a obj a cpp lt include gt usr local include exe a a obj exe b a obj Note that in both of these cases the include property will be applied only for building these object files and not any other sources that might be added for targets a and b 2 To compile the file twice you can tell Boost Build to compile it to two separate object files like so obj a_obj a cpp lt include gt usr local include obj b_obj a cpp exe a a_obj exe b b_obj or you can make the object file targets local to the main target exe a obj a_obj a cpp lt include gt usr local include exe b i obj a_obj a cpp which will cause Boost Build to actually change the generated object file names a bit for you and thus avoid any conflicts 97 http www renderx com that might be added for targets a and b to clarify his intention in such cases Frequently Asked Questions Note that in both of these cases the include property will be applied only for building these object files and not any other sources A good question is why Boost Build can not use some of the above approaches automatically The problem is that such
139. nditional properties for finer control exe a a cpp b obj b b cpp lt variant gt release lt optimization gt off 104 http www renderx com 3 2 fa Frequently Asked Questions Why are the 411 724 and naracoae a11 patas properties useful EY Note This entry is specific to Unix systems Before answering the questions let us recall a few points about shared libraries Shared libraries can be used by several applications or other libraries without physically including the library in the application which can greatly decrease the total application size It is also possible to upgrade a shared library when the application is already installed However in order for application depending on shared libraries to be started the OS may need to find the shared library when the application is started The dynamic linker will search in a system defined list of paths load the library and resolve the symbols Which means that you should either change the system defined list given by the LD_LIBRARY_PATH environment variable or install the libraries to a 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 An executable can include a list of additional library paths which will be searched before system paths This is excellent for devel opment because the build system
140. non free feature that property is removed Conditional properties Sometime it s desirable to apply certain requirements only for a specific combination of other properties For example one of compilers that you use issues a pointless warning that you want to suppress by passing a command line option to it You would not want to pass that option to other compilers Conditional properties allow you to do just that Their syntax is property property property al For example the problem above would be solved by exe hello hello cpp lt toolset gt yfc lt cxxflags gt disable pointless warning The syntax also allows several properties in the condition for example exe hello hello cpp lt os gt NT lt toolset gt gcc lt link gt static Target identifiers and references Target identifier is used to denote a target The syntax is target id gt project id target name file name project id directory name target name project id gt path target name gt path file name gt path directory name gt path This grammar allows some elements to be recognized as either project id at this point all project ids start with slash name of target declared in current Jamfile note that target names may include slash e a regular file denoted by absolute name or name relative to project s sources location To determine the real meaning a check is made if project id by the specified
141. nything The found targets are added to the sources The run method can be overriden to completely customize the way the generator works In particular the conversion of sources to the desired types can be completely customized Here s another real example Tests for the Boost Python library usually consist of two parts a Python program and a C file The C file is compiled to Python extension that is loaded by the Python program But in the likely case that both files have the same name the created Python extension must be renamed Otherwise the Python program will import itself not the extension Here s how it can be done 88 http www renderx com Extender Manual rule run project name property set sources local python for local s in sources if s type PY python S s local libs for local s in sources if type is derived s type LIB libs s local new sources for local s in sources if type is derived s type CPP local name s name get the target s basename if name S python name name name ext rename the target new sources generators construct project name PYTHON EXTENSION property set s libs result construct result python new sources S project name property set First we separate all source into python fil
142. ocumentation altogether We hope it will be useful to anyone wishing to become familiar with Jam and the Boost build system Jam rules are actually simple procedural entities Think of them as functions Arguments are separated by colons A Jam target is an abstract entity identified by an arbitrary string The build in DEPENDS rule creates a link in the dependency graph between the named targets e Note that the original Jam documentation for the built in INCLUDES rule is incorrect INCLUDES targets1l targets2 causes everything that depends on a member of targets to depend on all members of targets2 It does this in an odd way by tacking targets2 onto a special tail section in the dependency list of everything in targets It seems to be OK to create circular dependencies this way in fact it appears to be the right thing to do when a single build action produces both targets and targets2 e When arule is invoked if there are act ions declared with the same name as the rule the actions are added to the updating actions for the target identified by the rule s first argument It is actually possible to invoke an undeclared rule if corresponding actions are declared the rule is treated as empty e Targets other than NOTFILE targets are associated with paths in the file system through a process called binding Binding is a process of searching for a file with the same name as the target sans grist based on the set
143. of the install rule The only two that matter are dependency and on Unix dll path EY Note Unix specific On Unix executables built using Boost Build typically contain the list of paths to all used shared libraries For installing this is not desired so Boost Build relinks the executable with an empty list of paths You can also specify additional paths for installed executables using the d1l path feature See the definition of free in the section called Feature Attributes 39 http www renderx com Common tasks Testing Boost Build has convenient support for running unit tests The simplest way is the unit test rule which follows the common syntax For example unit test helpers_test helpers_test cpp helpers The unit test rule behaves like the 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 it runs successfully This behaviour ensures that you can not miss a unit test failure By default the executable is run directly Sometimes it is desirable to run the executable using some helper command You should use the testing launcher property to specify the name of the helper command For example if you write unit test helpers_test helpers_test cpp helpers lt testing launcher gt valgrind The command used to run the exec
144. oft Visual C 6 x Detection and Notes e Common install location C Borland BCC55 BCC32 EXE in PATH ICL EXE in PATH x e CWFolder variable con figured MWCC EXE in PATH e Common install location C MinGw e VCVARS32 BAT already configured e SMSVCDir is present in environment e Common install locations SProgramFiles Mi crosoft Visual Stu dio SP rogram Files Microsoft Visual C e CL EXE in PATH 110 http www renderx com Boost Jam Documentation Script Platform Toolset Detection and Notes ve7 e VCVARS32 BAT or VS Microsoft Visual C 7 x VARS32 BAT already con figured e VS71COMNTOOLS is present in environment e SVCINSTALLDIRS is present in environment e Common install locations SProgramFiles Mi crosoft Visual Studio NET Program Files Microsoft Visual Studio NET 2003 e CL EXE in PATH 111 http www renderx com Boost Jam Documentation Script Platform Toolset Detection and Notes vc8 and vc9 Detection Microsoft Visual C 8 x and 9 x e VCVARSALL BAT already configured e VS90COMNTOOLS is present in environment e Common install location SProgramFiles Mi crosoft Visual Studio 9 SVS80COMNTOOLS is present in environment e Common install location SProgramFiles Mi crosoft Visual Studio g e CL EXE in PATH Note
145. ompiler GNU C The gcc module supports the GNU C compiler on Linux a number of Unix like system including SunOS and on Windows either Cygwin or MinGW On Mac OSX it is recommended to use system gcc see the section called Apple Darwin gcc The gcc module is initialized using the following syntax using gcc version ct compile command compiler options This statement may be repeated several times if you want to configure several versions of the compiler If the version is not explicitly specified it will be automatically detected by running the compiler with the v option If the command is not specified the g binary will be searched in PATH The following options can be provided using lt opt ion name gt option value syntax cflags Specifies additional compiler flags that will be used when compiling C sources cxxflags Specifies additional compiler flags that will be used when compiling C sources compileflags Specifies additional compiler flags that will be used when compiling both C and C sources linkflags Specifies additional command line options that will be passed to the linker root Specifies root directory of the compiler installation This option is necessary only if it is not possible to detect this information from the compiler command for example if the specified compiler command is a user script re Specifies the resource compiler command that will be used with the version of gcc that is b
146. on name gt opt ion value syntax cflags Specifies additional compiler flags that will be used when compiling C sources cxxflags Specifies additional compiler flags that will be used when compiling C sources compileflags Specifies additional compiler flags that will be used when compiling both C and C sources linkflags Specifies additional command line options that will be passed to the linker The Linux version supports the following additional options root Specifies root directory of the compiler installation This option is necessary only if it is not possible to detect this information from the compiler command for example if the specified compiler command is a user script HP aC compiler The acc module supports the HP aC compiler for the HP UX operating system The module is initialized using the following syntax using acc version ct compile command compiler options This statement may be repeated several times if you want to configure several versions of the compiler If the command is not specified the aCC binary will be searched in PATH The following options can be provided using lt opt ion name gt opt ion value syntax cflags Specifies additional compiler flags that will be used when compiling C sources cxxflags Specifies additional compiler flags that will be used when compiling C sources compileflags Specifies additional compiler flags that will be used when compiling both C and C sources
147. or example if you create a module obfus cate jam containing import type type register OBFUSCATED_CPP ocpp import generators generators register standard obfuscate file CPP OBFUSCATED_CPP and import that module you ll be able to use the rule obfuscated cpp in Jamfiles which will convert source to the OBFUS CATED_CPP type The second way is to write a wrapper rule that calls any of the existing rules For example suppose you have only one library per directory and want all cpp files in the directory to be compiled into that library You can achieve this effect using lib codegen glob cpp If you want to make it even simpler you could add the following definition to the Jamroot jam file rule glib name extra sources requirements lib name glob cpp S extra sources requirements allowing you to reduce the Jamfile to just glib codegen Note that because you can associate a custom generator with a target type the logic of building can be rather complicated For example the boostbook module declares a target type BOOSTBOOK_MAIN and a custom generator for that type You can use that as example if your main target rule is non trivial 93 http www renderx com Extender Manual Toolset modules If your extensions will be used only on one project they can be placed in a separate jam file and imported by your Jamroot jam If the extensions wi
148. orm a property looks like feature value target All tokens that are neither options nor properties specify what targets to build The available targets entirely depend on the project you are building Examples To build all targets defined in the Jamfile in the current directory with the default properties run b2 To build specific targets specify them on the command line b2 libl subproject lib2 To request a certain value for some property add property value to the command line b2 toolset gcc variant debug optimization space Options Boost Build recognizes the following command line options help clean clean all build dir version Invokes the online help system This prints general information on how to use the help system with additional help options Cleans all targets in the current directory and in any subprojects Note that unlike the clean target in make you can use clean together with target names to clean specific targets Cleans all targets no matter where they are defined In particular it will clean targets in parent Jamfiles and targets defined under other project roots Changes the build directories for all project roots being built When this option is specified all Jamroot files must declare a project name The build directory for the project root will be computed by concatanating the value of the build dir option the project name specified in Jamroot and the build
149. pecial kind of module which is managed by the build system Although they cannot be loaded directly by users the other features of modules are still useful for Jamfiles Every module has two special variables file contains the name of the file that the module was loaded from and __name__ contains the name of the module E l rule binding module name Note __file__ does not contain the full path to the file If you need this use modules binding Returns the filesystem binding of the given module For example a module can get its own location with me modules binding __name__ F rule poke module name variables value Sets the module local value of a variable For example to set a variable in the global module ZLIB_INCLUDE mS modules poke usr local include rule peek module name variables Returns the module local value of a variable For example to read a variable from the global module local ZLIB_INCLUDE ry ZLIB_INCLUDE ry modules peek 64 render http www renderx com Reference 4 5 7 rule call in module name rule name args Call the given rule locally in the given module Use this for rules accepting rule names as arguments so that the passed rule may be invoked in the context of the rule s caller for example if the rule accesses module globals or is a local rule
150. pecified mwld will be used The command will be invoked after the setup script was executed and adjusted the PATH variable Digital Mars C C Compiler The dmc module supports the Digital Mars C compiler The module is initialized using the following syntax using dmc version ct compile command compiler options This statement may be repeated several times if you want to configure several versions of the compiler If the command is not specified Boost Build will search for a binary named dmc in PATH The following options can be provided using lt opt ion name gt opt ion value syntax cflags Specifies additional compiler flags that will be used when compiling C sources cxxflags Specifies additional compiler flags that will be used when compiling C sources compileflags Specifies additional compiler flags that will be used when compiling both C and C sources linkflags Specifies additional command line options that will be passed to the linker 59 http www renderx com 3 2 fa Reference HP C Compiler for Tru64 Unix The hp_cxx modules supports the HP C Compiler for Tru64 Unix The module is initialized using the following syntax using hp_cxx version c compile command compiler options This statement may be repeated several times if you want to configure several versions of the compiler If the command is not specified Boost Build will search for a binary named hp cxx
151. pecifies which rules from the source_module to import target_rules specifies the names to give those rules in target_module If source_rules contains a name which doesn t correspond to a rule in source_module or if it contains a different number of items than target_rules an error is issued For example import ml rulel into m2 as local rule ml rulel IMPORT ml rulel m2 ml rulel import all non local rules from ml into m2 IMPORT ml RULENAMES ml m2 RULENAMES ml The export Rule EXPORT allows rule name aliasing across modules rule EXPORT module rules The EXPORT rule marks rules from the source_module as non local and thus exportable If an element of rules does not name a rule in module an error is issued For example module X local rule r ECHO X r IMPORT X r vj error r is local in X EXPORT X r IMPORT X r r OK The CALLER_MODULE Rule rule CALLER_MODULE levels CALLER_MODULE returns the name of the module scope enclosing the call to its caller if levels is supplied it is interpreted as an integer number of additional levels of call stack to traverse to locate the module If the scope belongs to the global module or if no such module exists returns the empty list For example the following prints Y X 132 http www renderx com Boost Jam Documentation module X rule get
152. port for building bjam with pgi and pathscale toolsets Noel B 3 2 fa 139 http www renderx com Boost Jam Documentation Implement running action commands through pipes p option to fix jumbled output when using parallel execution with j option This is implemented for Unix variants and Windows Win32 NT Rene R Noel B Add sun as alias to Sun Workshop compiler tools Rene R Set MAXLINE in jam h to 23k bytes for AIX The piecemeal archive action was broken with the default MAXLINE of 102400 Because the AIX shell uses some of the 24k default buffer size for its own use I reduced it to 23k Noel B Make use of output dir options of msvc to not polute src dir with compiled files Rene R A small fix so d 2 will always show the real commands being executed instead of casually the name of a temporary batch file Roland S Add test to check bjam n Rene R Add test to check bjam d2 Rene R Bring back missing output of n option The o option continues to be broken as it has been for a long time now because of the file feature Rene R Update GC support to work with Boehm GC 7 0 Rene R Revert the BOOST_BUILD_PATH change since the directory passed to boost build should be first in searched paths else project local build system will not be picked correctly The order had been changed to allow searching of alternate user config jam files from boost build This better s
153. pp cpp util foo bar While app cpp refers to a regular source file util foo bar is a reference to another target a library bar declared in the Jamfile at util foo Tip Some other build system have special syntax for listing dependent libraries for example LIBS variable In Boost Build you just add the library to the list of sources Suppose we build app with b2 app optimization full define USE_ASM al Which properties will be used to build foo The answer is that some features are propagated Boost Build attempts to use depend encies with the same value of propagated features The lt optimization gt feature is propagated so both app and foo will be compiled with full optimization But lt define gt is not propagated its value will be added as is to the compiler flags for a cpp but won t affect foo Let s improve this project further The library probably has some headers that must be used when compiling app cpp We could manually add the necessary include paths to app s requirements as values of the lt include gt feature but then this work will be repeated for all programs that use foo A better solution is to modify util foo Jamfile in this way project usage requirements lt include gt lib foo foo cpp Usage requirements are applied not to the target being declared but to its dependants In this case lt include gt will be applied to all targets that directly depend on foo Anothe
154. r improvement is using symbolic identifiers to refer to the library as opposed to Jamfile location In a large project a library can be used by many targets and if they all use Jamfile location a change in directory organization entails much work The solution is to use project ids symbolic names not tied to directory layout First we need to assign a project id by adding this code to Jamroot http www renderx com Tutorial use project library example foo util foo Second we modify app Jamfile to use the project id exe app app cpp library example foo bar The library example foo bar syntax is used to refer to the target bar in the project with id library example foo We ve achieved our goal if the library is moved to a different directory only Jamroot must be modified Note that project ids are global two Jamfiles are not allowed to assign the same project id to different directories Tip If you want all applications in some project to link to a certain library you can avoid having to specify it directly the sources of every target by using the lt 1library gt property For example if boost filesystem fs should be linked to all applications in your project you can add lt library gt boost filesystem fs to the project s requirements like this project requirements lt library gt boost filesystem fs http www renderx com Tutorial Static and shared libaries Libr
155. re ee EE EE EE EE E E e EEE A EOR E TTE EE EE EEE EOE R Raye 16 Conf duration ereere ai eroin evade ener Ene E CEET EEEE e e EEEE VEEE EET TES EEIE EEEE EEEE REN EEEN OEK EEEn OOE 19 INVOCAUON E A EN E E E E E E E E T 21 D cl ring TarTetS ois cick pees sie bide EEE EEE EEE EEEE EE EEEE EEEE E EOE EERE EI EEEE AEE EAE ENES ELSE MESSE SEERE 25 PEOJECIS srsieeninirinenansor ionene e EE EEE EEE EEEE E TE EEE E EEE EE EEEE E ERNE 29 The Build Process irisscci enenenneerere iseni erir eante Eneee r Erin de deatied nth EEEE IE EIEEE PRERE EEOSE AEE EEE EE CODEER EEEE ERSE EEEE ans hanke 31 Common t s e E areas ates E E E E E E ys sacetnvehebes 33 PROSTAMS i ic2scsisiie sok esonte en ere ru e E ands TEE EEEE EE EETA EERE CESET EREE E duatenalentecehsaDOvensetaseseluanetanstanbers danas 34 Librarie S enoni sutuianee atone us Ei E RE EE EEE E E EE EE R KERE E E e TREE EE EEEE EERS 35 Ta E sien E E E O E E E TE 37 Josta llint si enneren nee Era EEE E EE EEE ERE O Ea OE ONE ES TEE EEE E EEA EENES ERER 38 TESNO sorin ie eenen EErEE an EEEE EEEE EEE ERE EE EEE oul EE E EEE EERE eds EEEE EEEE EEEE EEE EE EREE SEEE 40 CUSTOM commands gessisse enni n nE E ae NEE RE EEE EEEL E EE EEEE EES TEO EOS E e ss 42 Precompiled Headers s cccsiscctwavcesadivncevacevineabsdengesd woes N TEENE EEIE E EEEE VETERE ESEE ESEE CETE EEEE EE 43 Generated Beaders ce ccicn vss ovatinnick apeosevsosbeivecioancegis eres erne sen guise SEEEN EEEE EE EE EEE EEEE EE ES E 44 Cross COmpllatlOD
156. rements are refined with the passed require ment and the result is used as the project requirements Default build default build none Sets to the passed value Build directory build dir Empty if the parent has no Sets to the passed value inter build directory set Otherwise the parent s build directory preted as relative to the pro ject s location with the relative path from parent to the current project appended to it 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 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 directory above the subproject The top level project is declared in a file called Jamroot rather than Jamfile When loading a project Boost Build looks for either Jamroot or Jamfile They are handled identically except that if the file is called Jamroot the search for a parent project is not performed Even when building in a subproject directory parent project files are always loaded before those of their subprojects so that every definition made in a parent project is always available to its children The loading order of any other projects is unspecified Even if one project refers to another via the use project or a target reference no specific order should be assumed K eg
157. return gt Note that because existing variable bindings change whenever a new module scope is entered argument bindings become unavailable That explains the use of gt in the peek rule above Local Rules local rule rulename The rule is declared locally to the current module It is not entered in the global module with qualification and its name will not appear in the result of RULENAMES module name The rutenaves Rule rule RULENAMES module Returns a list of the names of all non local rules in the given module If module is omitted the names of all non local rules in the global module are returned The varnaves Rule rule VARNAMES module 131 http www renderx com Boost Jam Documentation Returns a list of the names of all variable bindings in the given module If module is omitted the names of all variable bindings in the global module are returned EY Note This includes any local variables in rules from the call stack which have not returned at the time of the VARNAMES invocation BI The mrorr Rule IMPORT allows rule name aliasing across modules rule IMPORT source module source rules target_module target_rules The IMPORT rule copies rules from the source_module into the target_module as local rules If either source_module or target_module is not supplied it refers to the global module source_rules s
158. riable on targets elements variable on targets elements variable default elements variable elements The first two forms set variable globally The third and forth forms set a target specific variable The operator replaces any previous elements of variable with elements the operation adds elements to variable s list of elements The final two forms are synonymous they set variable globally but only if it was previously unset Variables referenced in updating commands will be replaced with their values target specific values take precedence over global values Variables passed as arguments 1 and 2 to actions are replaced with their bound values the bind modifier can be used on actions to cause other variables to be replaced with bound values See Action Modifiers above BJam variables are not re exported to the environment of the shell that executes the updating actions but the updating actions can reference b jam variables with variable Variable Expansion During parsing bjam performs variable expansion on each token that is not a keyword or rule name Such tokens with embedded variable references are replaced with zero or more tokens Variable references are of the form v or vm where vis the variable name and m are optional modifiers Variable expansion in a rule s actions is similar to variable expansion in statements except that the action string is tokenized at whitespace regardless of
159. ries From this point forward bjam will only be bundled as part of the larger Boost Build system And hence will likely change name at some point As a side effect of this move people will get more frequent release of bjam or whatever it ends up being called New built ins MD5 SPLIT_BY_CHARACTERS PRECIOUS PAD FILE_OPEN and UPDATE_NOW Viadimir P Ensure all file descriptors are closed when executing actions complete on nix Noel B Fix warnings patch from Mateusz Loskot Vladimir P Add KEEP GOING var to programatically override the q option Vladimir P Add more parameters up to 19 from 9 to rule invocations Patch from Jonathan Biggar Vladimir P Print failed command output even if the normally quite d0 option Vladimir P Build of bjam with vc10 aka Visual Studio 2010 Vladimir P More macros for detection of OSPLAT patch from John W Bito Vladimir P Add PARALLELISM var to programatically override the j option Vladimir P Tweak doc building to allow for PDF generation of docs John M 3 1 17 A year in the making this release has many stability improvements and various performance improvements And because of the efforts of Jurko the code is considerably more readable Reflect the results of calling bjam from Python Rene R For building on Windows Rework how arguments are parsed and tested to fix handling of quoted arguments options arguments and arguments with Rene R
160. rom SHARED LIB Initially the new type inherits all the properties of the base type in particular generators and suffix Typically you ll change the new type in some way For example using type set generated target suffix you can set the suffix for the new type Or you can write special a generator for the new type For example it can generate additional metainformation for the plugin In either way the PLUGIN type can be used whenever SHARED LIB can For example you can directly link plugins to an application A type can be defined as main in which case Boost Build will automatically declare a main target rule for building targets of that type More details can be found later 93 Scanners Sometimes a file can refer to other files via some include system To make Boost Build track dependencies between included files you need to provide a scanner The primary limitation is that only one scanner can be assigned to a target type First we need to declare a new class for the scanner class verbatim scanner common scanner rule pattern return include 4 All the complex logic is in the common scanner Class and you only need to override the method that returns the regular expression to be used for scanning The parentheses in the regular expression indicate which part of the string is the name of the included file Only the first parenthesized group in the regular expression will be recogniz
161. rom being convenient A better approach is to introduce a level of indirection Create a local alias target that refers to the static or dynamic version of foo alias foo other_project bar lt link gt static exe el el cpp foo exe e10 e10 cpp foo The alias rule is specifically used to rename a reference to a target and possibly change the properties Tip When one library uses another you put the second library in the source list of the first For example lib utils utils cpp boost filesystem fs lib core core cpp utils exe app app cpp core This works no matter what kind of linking is used When core is built as a shared library it is linked directly into utils Static libraries can t link to other libraries so when core is built as a static library its dependency on utils is passed along to core s dependents causing app to be linked with both core and utils 10 http www renderx com 3 2 Ly Tutorial Note Note for non UNIX system Typically shared libraries must be installed to a directory in the dynamic linker s search path Otherwise applications that use shared libraries can t be started On Windows the dynamic linker s search path is given by the PATH environment variable This restriction is lifted when you use Boost Build testing facilities the PATH variable will be automatically adjusted before running the executable http www renderx com
162. rule project rule location rule full name rule generate property set Classes derived from abstract target e project target e main target e basic target l rule __init__ name project name The name of the target in the Jamfile project The project to which this target belongs 2 rule name Returns the name of this target 3 rule project Returns the project for this target 4 rule location Returns the location where the target was declared 5 rule full name Returns a user readable name for this target 6 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 target This is an abstract method which must be overriden by derived classes On success returns e a property set with the usage requirements to be applied to dependents alist of produced virtual targets which may be empty If property set is empty performs the default build of this target in a way specific to the derived class 70 http www renderx com Reference Class project target class project target abstract target rule generate property set rule build dir rule main target name rule has main target name rule find id no error Methods inherited from abstract target rule name rule project rule location rule full name This class has th
163. s Rene R Check empty string invariants instead of assuming all strings are allocated And reset strings when they are freed Rene R Add OSPLAT PARISC for HP UX PA RISC Boris G Make quietly actions really quiet by not printing the command output The output for the quietly actions is still available through ACTION RULE Rene R Switch intel win32 to use static multi thread runtime since the single thread static runtime is no longer available Rene R When setting OSPLAT check __ia64 macro Boris G Get the unix timing working correctly Noel B Add fno strict aliasing to compilation with gcc Which works around GCC 4 2 crash problems Boris G Increased support for Python integration Vladimir P Daniel W Allow specifying options with quotes i e with pyt hon xyz to work around the CMD shell using as an argument separator Rene R Add values of variables specified with s to EVNRION module so that we can override environment on command line Vladimir P Make NORMALIZE_PATH convert to Vladimir P 3 1 15 This release sees a variety of fixes for long standing Perforce Jam problems Most of them relating to running actions in parallel with the jN option The end result of the changes is that running parallel actions is now reliably possible in Unix and Windows environments Many thanks to Noel for joining the effort to implement and fix the Unix side of stuff Add sup
164. s e If VCVARSALL BAT is called to set up the toolset it is passed all the extra argu ments see below for what those arguments are This can be used to build for ex ample a Win64 specific version of bjam Consult the VisualStudio document ation for what the possible argument values to the VCVARSALL BAT are build sh Unix Linux Cygwin etc acc e aCC in PATH HP UX aCC e uname is HP UX como e como in PATH Comeau Computing C C gec e gccin PATH GNU GCC 112 http www renderx com Boost Jam Documentation Platform MacOS X Windows NT 2000 and XP Toolset intel linux Intel C for Linux kee Intel KAT C kylax Borland C Builder mipspro SGI MIPSpro C sunpro Sun Workshop 6 C gcc QNX Neutrino true64cxx Compaq C Compiler for True64 UNIX vacpp IBM VisualAge C darwin Apple MacOS X GCC mingw GNU GCC as the MinGW configuration with the MSYS shell Detection and Notes icc in PATH Common install locations opt intel cc 9 0 opt intel cc 80 opt intel com piler70 opt in tel compiler60 opt intel com piler50 KCC in PATH bc in PATH uname iS IRIX or TRIX64 Standard install location opt SUNWspro uname is QNX and gcc in PATH uname is OSF1 xlc in PATH uname is Darwin Common install location m UL mingw The built executables are placed in a subdirectory specific to your plat
165. s This makes it possible to avoid include exception matching if one happens to have a directory named exception in the header search path 119 http www renderx com Boost Jam Documentation amp Q Warning This is currently not fully implemented Utility The two rules ECHO and EXIT are utility rules used only in bjam s parsing phase ECHO rule ECHO args Blurts out the message args to stdout EXIT rule EXIT message result value Blurts out the message to stdout and then exits with a failure status if no result value is given otherwise it exits with the given result value Ur mom moms Echo echo Exit and exit are accepted as aliases for ECHO and EXIT since it is hard to tell that these are built in rules and not part of the language like include GLOB The GLOB rule does filename globbing rule GLOB directories patterns downcase opt Using the same wildcards as for the patterns in the switch statement It is invoked by being used as an argument to a rule invocation inside of For example FILES GLOB dirl dir2 c h sets FILES to the list of C source and header files in dirl and dir2 The resulting filenames are the full pathnames including the directory but the pattern is applied only to the file name without the directory If downcase opt is supplied filenames are converted to all lowercase before
166. s 9 4 The module is initialized using the following syntax using cw version ct compile command compiler options This statement may be repeated several times if you want to configure several versions of the compiler If the command is not specified Boost Build will search for a binary named mwec in default installation paths and in PATH The following options can be provided using lt opt ion name gt opt ion value syntax cflags Specifies additional compiler flags that will be used when compiling C sources cxxflags Specifies additional compiler flags that will be used when compiling C sources compileflags Specifies additional compiler flags that will be used when compiling both C and C sources linkflags Specifies additional command line options that will be passed to the linker root Specifies root directory of the compiler installation This option is necessary only if it is not possible to detect this information from the compiler command for example if the specified compiler command is a user script setup The command that sets up environment variables prior to invoking the compiler If not specified cwenv bat alongside the compiler binary will be used compiler The command that compiles C and C sources If not specified mwec will be used The command will be in voked after the setup script was executed and adjusted the PATH variable linker The command that links executables and dynamic libraries If not s
167. s and class instances Syntantically a Boost Jam program consists of two kind of elements keywords which have a special meaning to Boost Jam and literals Consider this code which assigns the value b to the variable a Here and are keywords while a and b are literals Warning All syntax elements even keywords must be separated by spaces For example omitting the space character before will lead to a syntax error If you want to use a literal value that is the same as some keyword the value can be quoted All variables in 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 syntax For example a b c Rules are defined by specifying the rule name the parameter names and the allowed value list size for each parameter rule example parameterl parameter2 parameter3 parameter4d rule body al When this rule is called the list passed as the first argument must 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 Boost Jam language statements is given below 16 http www renderx com Overview helper 1 2 3 x he
168. s the incidental attribute 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 build specification differs only in incidental features A feature that controls a compiler s warning level is one example of a likely incidental feature Non incidental features are assumed to affect build products so the files for targets whose build specification differs in non incid ental features are placed in different directories as described in the section called Target Paths e propagated Features of this kind are propagated to dependencies That is if a main target 25 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 exectuable is requested one usually wants it to be linked with optimized libraries Thus the lt optimization gt feature is propagated e free 77 http www renderx com Reference 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 features on the other hand can have several values at a time and each value can be an arbitrary string For example it is possible to have several preprocessor symbols defined simultaneously lt define gt NDEBUG 1 lt define gt HAS_CONFIG_H 1 option
169. sult Otherwise returns string unmodified 122 http www renderx com Boost Jam Documentation FILE_OPEN rule FILE_OPEN filename mode The FILE_OPEN rule opens the specified file and returns a file descriptor The mode parameter can be either w or r Note that at present only the UPDATE NOW rule can use the resulting file descriptor number UPDATE_NOW rule UPDATE NOW targets log ignore minus n The UPDATE_NOW caused the specified targets to be updated immediately If update was successfull non empty string is returned The log parameter if present specifies a descriptor of a file where all output from building is redirected If the ignore minus n parameter is specified the targets are updated even if the n parameter is specified on the command line Flow of Control BJam has several simple flow of control statements for var in list statements Executes statements for each element in list setting the variable var to the element value if cond statements else statements Does the obvious the else clause is optional cond is built of a true if any a element is a non zero length string a b list a matches list b string for string a b list a does not match list b a lt b a i string is less than b i string where i is first mismatched element in lists a and b a lt b every a string is less than or equal to its b counterpart a gt b
170. t compilers configuration will not work 2 When compiling use address mode1 64 to generate AMD64 code 3 To generate IA64 code use architecture ia64 The AMD64 host AMD64 target compiler will be used automatically when you are generating AMD64 code and are running 64 bit Windows on AMD64 The A64 host A64 target compiler will never be used since nobody has an IA64 machine to test It is believed that AMD64 and EM64T targets are essentially compatible The compiler options favor AMD64 and favor EM64T which are accepted only by AMD64 targeting compilers cause the generated code to be tuned to a specific flavor of 64 bit x86 Boost Build will make use of those options depending on the value of theinstruction set feature 56 http www renderx com Reference Intel C The intel linux and intel win modules support the Intel C command line compiler the Linux and Windows versions respectively The module is initialized using the following syntax using intel linux version c compile command compiler options or using intel win version ct compile command compiler options respectively This statement may be repeated several times if you want to configure several versions of the compiler If compiler command is not specified then Boost Build will look in PATH for an executable icpe on Linux or icc exe on Windows The following options can be provided using lt opt i
171. t file embedding 53 metatarget definition 15 mkdirs 67 modules 64 N name Abstract Target 70 native 66 O onehtml P parent 66 path 66 pdf peek 64 poke 64 prefix preprocessed preserve test targets 41 programs path 67 project Abstract Target 70 project target 71 propagated Property Set Method 74 property definition 15 propagation 15 property set 73 Ps pwd 66 Q quickbook 63 R raw Property Set Method 74 refine Property Set Method 74 reftitle register type 67 register suffixes 67 registered 67 relative 67 relative to 67 requirements 26 reverse 66 root 66 rule 16 runtime linking S set generated target prefix 68 set generated target suffix 68 set scanner 68 source STLport 61 str Property Set Method 74 T tests threading type module 67 rule 69 Typed Target Method 73 typed target 73 U use V validate 68 variant X xhtml xsl param xsl path xslt xslt dir xsltproc 61 142 http www renderx com
172. t properties specified in the target reference and pass the resulting properties as build request to the other target 5 Adding the usage requirements produced when building dependencies to the common properties When dependencies are built in the previous step they return both the set of created real targets and usage requirements The usage requirements are added to the common properties and the resulting property set will be used for building the current target 6 Building the target using generators To convert the sources to the desired type Boost Build uses generators objects that correspond to tools like compilers and linkers Each generator declares what type of targets it can produce and what type of sources 31 http www renderx com Overview it requires Using this information Boost Build determines which generators must be run to produce a specific target from specific sources When generators are run they return the real targets 7 Computing the usage requirements to be returned The conditional properties in usage requirements are expanded and the result is returned Building a Project Often a user builds a complete project not just one main target In fact invoking b2 without arguments builds the project defined in the current directory When a project is built the build request is passed without modification to all main targets in that project It s is possible to prevent implicit building
173. take place and they should be set target specific and not globally If they were set globally all files including executables and libraries would be scanned for header file include statements The scanning for header file inclusions is not exact but it is at least dynamic so there is no need to run something like mak edepend GNU to create a static dependency file The scanning mechanism errs on the side of inclusion i e it is more likely to return filenames that are not actually used by the compiler than to miss include files because it can t tell if include lines are inside ifdefs or other conditional logic In Jambase HdrRule applies the NOCARE rule to each header file found during scanning so that if the file isn t present yet doesn t cause the compilation to fail b jam won t care Also scanning for regular expressions only works where the included file name is literally in the source file It can t handle languages that allow including files using variable names as the Jam language itself does 127 http www renderx com 3 2 fa Boost Jam Documentation Semaphores It is sometimes desirable to disallow parallel execution of some actions For example Old versions of yacc use files with fixed names So running two yacc actions is dangerous One might want to perform parallel compiling but not do parallel linking because linking is i o bound and only gets slower Craig McPeeters has extended Perforce
174. ted content Let s see what Boost Build can do First off Boost Build has no idea about verbatim files So you must register a new target type The following code does it import type type register VERBATIM verbatim The first parameter to 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 Boost Build sees code verbatim in a list of sources it knows that it s of type VERBATIM Next you tell Boost Build that the verbatim files can be transformed into C files in one build step A generator is a template for a build step that transforms targets of one type or set of types into another Our generator will be called verbatim inline file it transforms VERBATIM files into CPP files import generators generators register standard verbatim inline file VERBATIM CPP Lastly you have to inform Boost Build about the shell commands used to make that transformation That s done with an actions declaration actions inline file inline file py lt gt Now we re ready to tie it all together Put all the code above in file verbatim jam add import verbatim to Jamroot jam and it s possible to write the following in your Jamfile exe codegen codegen cpp class_template verbatim usage verbatim The listed verbatim files will be automatically converted into C source files compiled and then linked to
175. the codegen executable 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 84 http www renderx com Extender Manual Target types The first thing we did in the intruduction was declaring a new target type import type type register VERBATIM verbatim The type is the most important property of a target Boost Build can automatically generate necessary build actions only because you specify the desired type using the different main target rules and because Boost Build can guess the type of sources from their extensions The first two parameters for the type register rule are the name of new type and the list of extensions associated with it A file with an extension from the list will have the given target type In the case where a target of the declared type is generated from other sources the first specified extension will be used Sometimes you want to change the suffix used for generated targets depending on build properties such as toolset For example some compiler uses extension elf for executable files You can use the type set generated target suffix rule type set generated target suffix EXE lt toolset gt elf elf A new target type can be inherited from an existing one type register PLUGIN SHARED_LIB The above code defines a new type derived f
176. the value 259 Windows constant STILL_ACTIVE causing bjam never to detect that it exited and therefore keep running in an endless loop Jurko G 138 http www renderx com Boost Jam Documentation Solved the problem with bjam going into an active wait state hogging up processor resources when waiting for one of its child processes to terminate while not all of its available child process slots are being used Jurko G Solved a race condition between bjam s output reading child process termination detection and the child process s output generation termination which could have caused bjam not to collect the terminated process s final output Jurko G Change from vfork to fork for executing actions on Darwin to improve stability Noel B Code reformatting and cleanups Jurko G Implement ISFILE built in Vladimir P 3 1 16 This is mostly a bug fix release Work around some Windows CMD EXE programs that will fail executing a totally empty batch file Rene R Add support for detection and building with vc9 John P Plug memory leak when closing out actions Thanks to Martin Kortmann for finding this Rene R Various improvements to TIMING RULE and __ACTION_RULE__ target variable hooks Rene R Change JAMDATE to use common ISO date format Rene R Add test for result status values of simple actions i e empty actions Rene R Fix buffer overrun bug in expanding subexpression
177. tings of the target specific SEARCH and LOCATE variables In addition to local and global variables jam allows you to set a variable on a target Target specific variable values can usually not be read and take effect only in the following contexts e In updating actions variable values are first looked up on the target named by the first argument the target being updated Because Jam builds its entire dependency tree before executing actions Jam rules make target specific variable settings as a way of supplying parameters to the corresponding actions e Binding is controlled entirely by the target specific setting of the SEARCH and LOCATE variables as described here In the special rule used for header file scanning variable values are first looked up on the target named by the rule s first argument the source file being scanned The bound value of a variable is the path associated with the target named by the variable In build actions the first two arguments are automatically replaced with their bound values Target specific variables can be selectively replaced by their bound values using the bind action modifier e Note that the term binding as used in the Jam documentation indicates a phase of processing that includes three sub phases binding yes update determination and header file scanning The repetition of the term binding can lead to some confusion In particular the Modifying Binding section in t
178. tion call that creates the targets necessary to create a executable file from the source file a c Depending on configured properties different command lines may be used However add_programis higher level but rather thin level All targets are created immediately when the build description is parsed which makes it impossible to perform multi variant builds Often change in any build property requires a complete reconfiguration of the build tree In order to support true multivariant builds Boost Build introduces the concept of a metatarget an object that is created when the build description is parsed and can be called later with specific build properties to generate actual targets Consider an example exe a a cpp When this declaration is parsed Boost Build creates a metatarget but does not yet decide what files must be created or what commands must be used After all build files are parsed Boost Build considers the properties requested on the command line Supposed you have invoked Boost Build with b2 toolset gcc toolset msvc In that case the metatarget will be called twice once with toolset gcc and once with toolset msvc Both invocations will produce concrete targets that will have different extensions and use different command lines Another key concept is build property A build property is a variable that affects the build process It can be specified on the command line and is passed when calling a metatarget While
179. tion the a include directory and then b even though they are specified in the opposite order In most cases the user does not care But sometimes the order of includes or other properties is important For such cases a special syntax is provided exe a a cpp lt include gt a amp amp b The amp amp symbols separate property values and specify that their order 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 100 http www renderx com 3 2 fa Frequently Asked Questions How to control the library linking order on Unix On Unix like operating systems the order in which static libraries are specified when invoking the linker is important because by default the linker uses one pass though the libraries list Passing the libraries in the incorrect order will lead to a link error Further this behaviour is often used to make one library override symbols from another So sometimes it is necessary to force specific library linking order Boost Build tries to automatically compute the right order The primary rule is that if library a uses library b then library a will appear on the command line before library b Library a is considered to use b if b is present either in the a library s sources or its usage is listed in its requirements To explicitly specify the use re
180. tions echo echo something The only difference from the make rule is that the name of the target is not considered a name of a file so Boost Build will uncondi tionally run the action The generate rule is used when you want to express transformations using Boost Build s virtual targets as opposed to just filenames The generate rule has the standard main target rule signature but you are required to specify the generat ing rule property The value of the property should be in the form rule name the named rule should have the following signature rule generating rul project name property set sources and will be called with an instance of the project target class the name of the main target an instance of the property set class containing build properties and the list of instances of the virtual target class corresponding to sources The rule must return a list of virtual target instances The interface of the virtual target class can be learned by looking at the build virtual target jam file The generate example contained in the Boost Build distribution illustrates how the generate rule can be used 42 http www renderx com 3 2 fa Common tasks Precompiled Headers Precompiled headers is a mechanism to speed up compilation by creating a partially processed version of some header files and then using that version during compilations rather then repeatedly parsing the original headers Boost Buil
181. ttp www renderx com Reference Build process The general overview of the build process was given in the user documentation This section provides additional details and some specific rules To recap building a target with specific properties includes the following steps 1 2 applying default build selecting the main target alternative to use determining common properties building targets referred by the sources list and dependency properties adding the usage requirements produces when building dependencies to the common properties building the target using generators computing the usage requirements to be returned Alternative selection When there are several alternatives one of them must be selected The process is as follows 1 For each alternative condition is defined as the set of base properties in requirements Note it might be better to specify the condition explicitly as in conditional requirements An alternative is viable only if all properties in condition are present in build request If there s one viable alternative it s choosen Otherwise an attempt is made to find one best alternative An alternative a is better than another alternative b iff the set of properties in b s condition is a strict subset of the set of properities of a s condition If there s one viable alternative which is better than all others it s selected Otherwise an error is reported
182. utable will be valgrind bin Stoolset debug helpers_test There are few specialized testing rules listed below rule compile sources requirements target name rule compile fail sources requirements target name rule link sources requirements target name rule link fail sources requirements target name They are given a list of sources and requirements If the target name is not provided the name of the first source file is used instead The compile tests try to compile the passed source The 1ink rules try to compile and link an application from all the passed sources The compile and link rules expect that compilation linking succeeds The compile fail and link fail rules expect that the compilation linking fails There are two specialized rules for running applications which are more powerful than the unit test rule The run rule has the following signature rule run sources args input files requirements target name default build The rule builds application from the provided sources and runs it passing args and input files as command line arguments The args parameter is passed verbatim and the values of the input files parameter are treated as paths relative to containing Jamfile and are adjusted if bjam is invoked from a different directory The run fail rule is identical to the run rule except that it expects that the run fails All rules describe
183. utes command and then returns the standard output of command SHELL only works on platforms with a popen function in the C library On platforms without a working popen function SHELL is implemented as a no op SHELL works on Unix MacOS X and most Windows compilers SHELL is a no op on Metrowerks compilers under Windows There is a variable set of allowed options as additional arguments exit status In addition to the output the result status of the executed command is returned as a second element of the result nu no output Don t capture the output of the command Instead an empty string value is returned in place of the output Because the Perforce Jambase defines a SHELL rule which hides the builtin rule COMMAND can be used as an alias for SHELL in such a case MD5 rule MD5 string MD5 computes the MDS hash of the string passed as paramater and returns it SPLIT_BY_CHARACTERS rule SPLIT_BY_CHARACTERS string delimiters SPLIT_BY_CHARACTERS splits the specified string on any delimiter character present in delimiters and returns the resulting list PRECIOUS rule PRECIOUS targets The PRECIOUS rule specifies that each of the targets passed as the arguments should not be removed even if the command updating that target fails PAD rule PAD string width If string is shorter than width characters pads it with whitespace characters on the right and returns the re
184. ver specified in which case the tool is initialied only once For example if you allow using yfc using yie 2 3 3 3 using yfc 3 4 Then it s not clear if the first initialization corresponds to version 3 3 of the tool version 3 4 of the tool or some other version This can lead to building twice with the same version If possible init must be callable with no parameters In which case it should try to autodetect all the necessary information for example by looking for a tool in PATH or in common installation locations Often this is possible and allows the user to simply write using yfc e Consider using facilities in the tools common module You can take a look at how tools gcc jam uses that module in the init rule 94 http www renderx com Frequently Asked Questions render gt http www renderx com 3 2 fa Frequently Asked Questions How do get the current value of feature in Jamfile This is not possible since Jamfile does not have current value of any feature be it toolset build variant or anything else For a single run of Boost Build any given main target can be built with several property sets For example user can request two build variants on the command line Or one library is built as shared when used from one application and as static when used from another Each Jamfile is read only once so generally there is no single value of a feature you can access in Jamfile
185. view Configuration On startup Boost Build searches and reads two configuration files site config jam and user config jam The first one is usually installed and maintained by a system administrator and the second is for the user to modify You can edit the one in the top level directory of your Boost Build installation or create a copy in your home directory and edit the copy The following table explains where both files are searched Table 1 Search paths for configuration files site config jam user config jam Linux etc SHOME HOME BOOST_BUILD_PATH SBOOST_BUILD_PATH Windows SSystemRoots HOMEDRIVES HOMEPATHS SHOMEDRIVE SHOMEPATHS SHOMES SHOMES SBOOST BUILD PATH SBOOST_BUILD_PATH 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 the section called Targets in site config jam for more advanced usage A tool is configured using the following syntax using tool name The using rule is given the name of tool and will make that tool available to Boost Build For example using gcc will make the GCC compiler available All the supported tools are documented in the section called Builtin tools including the specific options they take Some general notes that apply to most C compilers are below For all the
186. wing syntax using quickbook command command is the quickbook executable If it is not specified Boost Build will compile it from source If it is unable to find the source it will search for a quickbook executable in PATH fop The fop module provides generators to convert from XSL formatting objects to Postscript and PDF To use fop you first need to configure it using the following syntax using fop fop command java home java fop command is the command to run fop If it is not specified Boost Build will search for it in PATH and FOP HOME Either java home or java can be used to specify where to find java 63 render http www renderx com Reference Builtin modules This section describes the modules that are provided by Boost Build The import rule allows rules from one module to be used in another module or Jamfile modules The modules module defines basic functionality for handling modules A module defines a number of rules that can be used in other modules Modules can contain code at the top level to initialize the module This code is executed the first time the module is loaded E Each module has its own namespaces for variables and rules If two modules A and B both use a variable named X each one gets its own copy of X They won t interfere with each other in any way Similarly importing rules into one module has no effect on any other module Note A Jamfile is a s
187. with associated values For example the debug symbols feature can have a value of on or off A property is just a feature value pair When a user initiates a build Boost Build automatically translates the requested properties into appropriate command line flags for invoking toolset components like compilers and linkers There are many built in features that can be combined to produce arbitrary build configurations The following command builds the project s release variant with inlining disabled and debug symbols enabled b2 release inlining off debug symbols on Properties on the command line are specified with the syntax feature name feature valu The release and debug that we have seen in b2 invocations are just a shorthand way to specify values of the variant feature For example the command above could also have been written this way b2 variant release inlining off debug symbols on al variant is so commonly used that it has been given special status as an implicit feature Boost Build will deduce its identity just from the name of one of its values A complete description of features can be found in the section called Features and properties Build Requests and Target Requirements The set of properties specified on the command line constitutes a build request a description of the desired properties for building the requested targets or if no targets were explicitly requested the project in the current directory
188. y Boost Build the type of the target and property set The rule can either return a string that must be used as the name of the target or an empty string in which case the default name will be used Most typical use of the tag feature is to encode build properties or library version in library target names You should take care to return non empty string from the tag rule only for types you care about otherwise you might end up modifying names of object files generated header file and other targets for which changing names does not make sense Allowed values on off The debug symbols feature specifies if produced object files executables and libraries should include debug information Typically the value of this feature is implicitly set by the variant feature but it can be explicitly specified by the user The most common usage is to build release variant with debugging information The operating system for which the code is to be generated The compiler you used should be the compiler for that operating system This option causes Boost Build to use naming conventions suitable for that operating system and adjust build process accordingly For ex ample with gcc it controls if import libraries are produced for shared libraries or not The complete list of possible values for this feature is aix bsd cygwin darwin freebsd hpux iphone linux netbsd openbsd osf qnx qnxnto sgi solaris unix unixware windows See the

Boost.Build V2 User Manual - LAR

Contents

Download Pdf Manuals

Related Search

Related Contents