diff --git a/v2/doc/src/advanced.xml b/v2/doc/src/advanced.xml index 36c8c6197..93497275d 100644 --- a/v2/doc/src/advanced.xml +++ b/v2/doc/src/advanced.xml @@ -1399,30 +1399,31 @@ exe main : main.cpp lib_alias ; Installing For installing a built target you should use the - stage rule, which follows the install rule, which follows the common syntax. For example: -stage dist : hello helpers ; +install dist : hello helpers ; will cause the targets hello and helpers to - be moved to the dist directory. The directory can + be moved to the dist directory, relative to + Jamfile's directory. The directory can be changed with the location property: -stage dist : hello helpers : <location>/usr/bin ; +install dist : hello helpers : <location>/usr/bin ; While you can achieve the same effect by changing the target name to /usr/bin, using the location - property is better because it allows you to use a memnonic target name on the - command line and in other targets. + property is better, because it allows you to use a memnonic target + name. The location property is especially handy when the location is not fixed, but depends on build variant or environment variables: -stage dist : hello helpers : <variant>release:<location>dist/release +install dist : hello helpers : <variant>release:<location>dist/release <variant>debug:<location>dist/debug ; -stage dist2 : hello helpers : <location>$(DIST) ; +install dist2 : hello helpers : <location>$(DIST) ; See also conditional properties and environment variables @@ -1430,18 +1431,13 @@ stage dist2 : hello helpers : <location>$(DIST) ; Specifying the names of all libraries to install can be boring. The - stage allows to specify only the top-level executable + install allows you to specify only the top-level executable targets to install, and automatically install all dependencies: -stage dist : hello - : <traverse-dependencies>on <include-type>EXE - <include-type>LIB +install dist : hello + : <install-dependencies>on <install-type>EXE + <install-type>LIB ; - will find all targets that hello depends on, and install all of the which are either executables or libraries. More @@ -1459,12 +1455,33 @@ stage dist : hello rule can be used when targets must be installed into several directories: -alias install : install-bin install-lib ; -stage install-bin : applications : /usr/bin ; -stage install-lib : helper : /usr/lib ; +install 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 see the definition of "free" in . + have no effect when used in requirements of the install. + The only two which matter are + + dependency and, on Unix, + dll-path. + + + + + (Unix specific). On Unix, executables built with Boost.Build typically + contain the list of paths to all used dynamic 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 with the dll-path feature. + + + +
@@ -1581,8 +1598,31 @@ unit-test helpers_test : helpers_test.cpp helpers ; - - + + + dependency + + + + + Introduces a dependency on the target named by the + value of this feature (so it will be brought + up-to-date whenever the target being declared is), and + adds its usage requirements to the build properties + + of the target being declared. The dependency is not used + in any other way. The primary use case is when you want + the usage requirements (such as #include paths) of some + library to be applied, but don't want to link to it. + + + + + + use diff --git a/v2/test/stage.py b/v2/test/stage.py index 8f14fd00d..4188582c3 100644 --- a/v2/test/stage.py +++ b/v2/test/stage.py @@ -128,7 +128,7 @@ foo() { } t.write("Jamfile", """ lib l : l.cpp ; exe a : a.cpp l ; -stage dist : a : on EXE LIB ; +stage dist : a : on EXE LIB ; """) t.write("project-root.jam", "") @@ -147,7 +147,7 @@ lib l2 : l2.cpp ; lib l3 : l3.cpp ; lib l : l.cpp : l2 l3 ; exe a : a.cpp l ; -stage dist : a : on EXE LIB ; +stage dist : a : on EXE LIB ; """) t.rm("dist") diff --git a/v2/tools/doxygen.jam b/v2/tools/doxygen.jam index 4580c4d3a..ed2939dae 100644 --- a/v2/tools/doxygen.jam +++ b/v2/tools/doxygen.jam @@ -172,7 +172,7 @@ rule doxygen ( target-name : sources * : requirements * : default-build * ) targets.main-target-alternative $(doxyfile) ; targets.main-target-alternative - [ new stage-target-class $(target-name:S=.xml) : $(project) + [ new install-target-class $(target-name:S=.xml) : $(project) : [ $(doxyfile).name ] : [ targets.main-target-requirements $(requirements) . : $(project) ] : [ targets.main-target-default-build $(default-build) : $(project) ] diff --git a/v2/tools/stage.jam b/v2/tools/stage.jam index dd1deb631..aa3563eca 100644 --- a/v2/tools/stage.jam +++ b/v2/tools/stage.jam @@ -3,54 +3,8 @@ # all copies. This software is provided "as is" without express or implied # warranty, and with no claim as to its suitability for any purpose. -# This module defines the 'stage' rule, used to copy a set of targets to +# This module defines the 'install' rule, used to copy a set of targets to # a single location -# -# Typical usage: -# -# stage dist : hello_world : /usr/bin ; -# -# The source target will be copied to the specified location. Some targets will -# we specially processed. In particular, binaries will be relinked. Free properties -# from stage dist will be included to properties used for relinking. For example -# -# stage dist : hello_world : /usr/bin /opt/lib ; -# -# will cause 'hello_world' to be relinked to the new location, and -# property will be added when relinking. -# -# The following properties specifically control 'stage' rule. -# -# - tells where to put targets. If not specified, directory -# with the same name as stage name will be used. -# -# - tells the new name of the staged target. In this case, only -# one target can be specified in sources. -# -# - is Unix specific. It causes all staged libraries to have -# value of the feature added to the end of name. The libraries will be -# relinked during staging, so that 'soname' embedded inside the library -# has the version suffix too. - -# The stage rule can also traverse dependencies, for example to install a -# program an all required libraries. Two properties affect this. -# -# - on tells that dependencies should be traversed. -# For each target in 'stage' sources, all sources to that target and all -# dependency properties are traversed. Sources and dependecy properties of -# those target are traversed recursively. -# -# - SOME_TYPE tells that targets of SOME_TYPE or a type derived -# from SOME_TYPE, should be included. -# If no such property is specified, then all found targets will be staged. -# Otherwise, only targets with types mentioned in property -# will be included. -# -# Example usage:: -# -# stage dist : hello_world : -# on EXE SHARED_LIB ; -# import targets ; import "class" : new ; @@ -65,11 +19,11 @@ import project ; import property-set ; import virtual-target ; -feature.feature : off on : incidental ; -feature.feature : : free incidental ; +feature.feature : off on : incidental ; +feature.feature : : free incidental ; feature.feature : : free incidental ; -class stage-target-class : basic-target +class install-target-class : basic-target { import feature project type errors generators path stage ; import "class" : new ; @@ -191,12 +145,13 @@ class stage-target-class : basic-target local result ; # Traverse the dependencies, if needed. - if [ $(property-set).get ] = "on" + if [ $(property-set).get ] = "on" { source-targets = [ collect-targets $(source-targets) ] ; } # Filter the target types, if needed + local included-types = [ $(property-set).get ] ; for local r in $(source-targets) { local ty = [ $(r).type ] ; @@ -230,16 +185,6 @@ class stage-target-class : basic-target result += $(r) ; } } - - - - local included-types = [ $(property-set).get ] ; - if $(included-types) - { - } - else - { - } return $(result) ; } @@ -323,33 +268,40 @@ rule relink-file ( project : source : property-set ) return $(result) ; } -# Declare staged version of the EXE type. Generator for this type will +# Declare installed version of the EXE type. Generator for this type will # cause relinking to the new location. -type.register STAGED_EXE : : EXE ; +type.register INSTALLED_EXE : : EXE ; -class stage-exe-generator : generator +class installed-exe-generator : generator { import type property-set modules stage ; rule __init__ ( ) { - generator.__init__ stage-exe : EXE : STAGED_EXE ; + generator.__init__ install-exe : EXE : INSTALLED_EXE ; } rule run ( project name ? : property-set : source : multiple ? ) { - return [ stage.relink-file $(project) : $(source) : $(property-set) ] ; + if [ $(property-set).get ] = NT + { + # Relinking is never needed on NT + return [ stage.copy-file $(project) + : $(source) : $(property-set) ] ; + } + else + { + return [ stage.relink-file $(project) + : $(source) : $(property-set) ] ; + } } } -generators.register [ new stage-exe-generator ] ; +generators.register [ new installed-exe-generator ] ; -# Declares a stage target. When build, it will construct all sources -# and place in one directory. The directory can be specified in requirements -# with 'location' property. If not specified, the directory name will be -# the same as target name, relative to the project where the target -# is declared. -rule stage ( name : sources * : requirements * : default-build * ) + +# Main target rule for 'install' +rule install ( name : sources * : requirements * : default-build * ) { local project = [ project.current ] ; @@ -373,14 +325,15 @@ rule stage ( name : sources * : requirements * : default-build * ) } targets.main-target-alternative - [ new stage-target-class $(name) : $(project) + [ new install-target-class $(name) : $(project) : [ targets.main-target-sources $(sources) : $(name) ] : [ targets.main-target-requirements $(requirements) : $(project) ] : [ targets.main-target-default-build $(default-build) : $(project) ] ] ; } -IMPORT $(__name__) : stage : : stage ; +IMPORT $(__name__) : install : : install ; +IMPORT $(__name__) : install : : stage ; rule add-variant-and-compiler ( name : property-set ) { @@ -391,8 +344,6 @@ rule add-variant ( name : type ? : property-set ) { return [ rename $(name) : $(type) : $(property-set) : unversioned ] ; } -IMPORT $(__name__) : add-variant add-variant-and-compiler - : : stage.add-variant stage.add-variant-and-compiler ; rule rename ( name : type ? : property-set : unversioned ? ) {