From 69a970d5fd8759a958d756759396e0e89cff628d Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Mon, 8 Sep 2003 14:58:45 +0000 Subject: [PATCH] Added external project support docs [SVN r19963] --- build_system.htm | 108 ++++++++++++++++++++++++++++++++------------ v1/build_system.htm | 108 ++++++++++++++++++++++++++++++++------------ 2 files changed, 160 insertions(+), 56 deletions(-) diff --git a/build_system.htm b/build_system.htm index 0d7f95efe..42b438331 100644 --- a/build_system.htm +++ b/build_system.htm @@ -2,6 +2,8 @@ + @@ -131,6 +133,8 @@ +
  • Using External Projects +
  • Feature Descriptions
  • Variant Descriptions
    • @@ -271,9 +275,10 @@ bjam "-sBUILD=debug release" - bjam "-sBUILD=<define>BOOST_POSIX" + bjam "-sBUILD=<define>BOOST_POSIX" - build all, with the macro BOOST_POSIX defined for all compilers + build all, with the macro BOOST_POSIX defined for all + compilers @@ -752,8 +757,8 @@ exe my_target : my_source1.cpp my_source2.c ; -

    SubProject Jamfiles

    This section describes how to write a Jamfile for a subproject. +

    SubProject Jamfiles

    The subproject rule

    @@ -816,24 +821,45 @@ project-root ;
    -
  • sources is a list of paths to source files and dependency - targets. A dependency target path is preceded by - <template>, <lib>, <dll>, - or <exe>, and the final path component specifies the - name of a main target in a Jamfile located in the directory given by - the initial path components. Paths may be absolute or relative. The - type of dependency is also used to decide how to link to it when - needed. Specifying a <lib> indicates the use of static - linking, as opposed to specifying a <dll> which uses - dynamic linking. For example in Unix static linking will be done - directly, and dynamic linking with the common "-l" liker flag - and use of LD_LIBRARY_PATH.
    -
    - NOTE: It is important to match up the type of source dependency - with the same type the dependency is built as. Trying to specify a - source dependency of <lib> when the target is defined as - a <dll> will cause an error.
    -
    +
  • + sources is a list of paths to source files and + dependency targets. The syntax for + dependency targets is described by the following grammar: + +
    +
    +dependency-target -> type-tag location target-name
+
+type-tag -> "<template>" | "<lib>" | "<dll>" | "<exe>"
+
+location -> ( @project-id/ )? relative-path
+
+relative-path -> ( path-element/ ) *
+
    +
    + The location specifies the location of a Jamfile in which a + dependency target called target-name can be + found, declared with the given type-tag. If + @project-id is specified, the + relative-path is interpreted with respect to the root + directory of the specified + project. Otherwise, it is interpreted with respect to the + directory of the current Jamfile. + +

    The dependency's type-tag is also used to decide how to + link to it when needed. <lib> targets are linked + statically and <dll> targets are linked dynamically. + On Unix platforms dynamic linking will use (the appropriate platform + equivalent of) LD_LIBRARY_PATH and the "-l" linker + flag to avoid creating executables which expect to find dynamic + libraries in particular locations in the filesystem.

    + +

    NOTE: It is important to match the type-tag + dependency with the type of the dependency target. Trying to specify + a type-tag of <lib> when the target is defined + as a <dll> will cause an error.
    +
    +

  • @@ -950,7 +976,8 @@ exe test : test.cpp <lib>basic ;
    main targets. But one additional type of requirement is possible: <tag>... A tag specifies how to "augment" the names of the copied files. This is needed to distinguish the various files if - you're collecting different builds of the same targets. The syntax is: + you're collecting different builds of the same targets. The syntax + is: 
    @@ -1046,6 +1073,31 @@ exe fop : <template>executable fop.cpp ;
       variant.
    • +

    Using External Projects

    + + To use dependencies such as libraries from another project tree, + first use the project rule to declare a project id + and location for the external project. Then add the appropriate + external dependency target specification to your program's list of + sources. For example, if you are developing a program which uses + the Boost.Threads library, you might write + +
    +
    +project boost : /home/dave/boost-cvs ;
+
    +
    + + in your Jamrules file, and place + +
    +
    +@boost/libs/thread/build/boost_thread
+
    +
    + + in your target's list of sources. +

    Feature Descriptions

    Features are described by stating the feature type (simple features @@ -1293,10 +1345,10 @@ flags msvc HDRS <include> ;

    Please note that the build system commonly takes advantage of Jam's - Dynamic Scoping feature (see the local command in the "Flow - of Control" section below the link target) to temporarily "change" a - global variable by declaring a local of the same name.

    + "jam_src/Jam.html#bindingmods">Jam's Dynamic Scoping feature (see the + local command in the "Flow of Control" section below the link + target) to temporarily "change" a global variable by declaring a + local of the same name.

    Many of the variables that are used to configure how Boost.Build works internally are listed here with brief @@ -1407,9 +1459,9 @@ flags msvc HDRS <include> ;

    Revised 1 July, 2003 + -->8 September, 2003 + -->

    diff --git a/v1/build_system.htm b/v1/build_system.htm index 0d7f95efe..42b438331 100644 --- a/v1/build_system.htm +++ b/v1/build_system.htm @@ -2,6 +2,8 @@ + @@ -131,6 +133,8 @@ +
  • Using External Projects +
  • Feature Descriptions
  • Variant Descriptions
    • @@ -271,9 +275,10 @@ bjam "-sBUILD=debug release" - bjam "-sBUILD=<define>BOOST_POSIX" + bjam "-sBUILD=<define>BOOST_POSIX" - build all, with the macro BOOST_POSIX defined for all compilers + build all, with the macro BOOST_POSIX defined for all + compilers @@ -752,8 +757,8 @@ exe my_target : my_source1.cpp my_source2.c ; -

    SubProject Jamfiles

    This section describes how to write a Jamfile for a subproject. +

    SubProject Jamfiles

    The subproject rule

    @@ -816,24 +821,45 @@ project-root ;
    -
  • sources is a list of paths to source files and dependency - targets. A dependency target path is preceded by - <template>, <lib>, <dll>, - or <exe>, and the final path component specifies the - name of a main target in a Jamfile located in the directory given by - the initial path components. Paths may be absolute or relative. The - type of dependency is also used to decide how to link to it when - needed. Specifying a <lib> indicates the use of static - linking, as opposed to specifying a <dll> which uses - dynamic linking. For example in Unix static linking will be done - directly, and dynamic linking with the common "-l" liker flag - and use of LD_LIBRARY_PATH.
    -
    - NOTE: It is important to match up the type of source dependency - with the same type the dependency is built as. Trying to specify a - source dependency of <lib> when the target is defined as - a <dll> will cause an error.
    -
    +
  • + sources is a list of paths to source files and + dependency targets. The syntax for + dependency targets is described by the following grammar: + +
    +
    +dependency-target -> type-tag location target-name
+
+type-tag -> "<template>" | "<lib>" | "<dll>" | "<exe>"
+
+location -> ( @project-id/ )? relative-path
+
+relative-path -> ( path-element/ ) *
+
    +
    + The location specifies the location of a Jamfile in which a + dependency target called target-name can be + found, declared with the given type-tag. If + @project-id is specified, the + relative-path is interpreted with respect to the root + directory of the specified + project. Otherwise, it is interpreted with respect to the + directory of the current Jamfile. + +

    The dependency's type-tag is also used to decide how to + link to it when needed. <lib> targets are linked + statically and <dll> targets are linked dynamically. + On Unix platforms dynamic linking will use (the appropriate platform + equivalent of) LD_LIBRARY_PATH and the "-l" linker + flag to avoid creating executables which expect to find dynamic + libraries in particular locations in the filesystem.

    + +

    NOTE: It is important to match the type-tag + dependency with the type of the dependency target. Trying to specify + a type-tag of <lib> when the target is defined + as a <dll> will cause an error.
    +
    +

  • @@ -950,7 +976,8 @@ exe test : test.cpp <lib>basic ;
    main targets. But one additional type of requirement is possible: <tag>... A tag specifies how to "augment" the names of the copied files. This is needed to distinguish the various files if - you're collecting different builds of the same targets. The syntax is: + you're collecting different builds of the same targets. The syntax + is: 
    @@ -1046,6 +1073,31 @@ exe fop : <template>executable fop.cpp ;
       variant.
    • +

    Using External Projects

    + + To use dependencies such as libraries from another project tree, + first use the project rule to declare a project id + and location for the external project. Then add the appropriate + external dependency target specification to your program's list of + sources. For example, if you are developing a program which uses + the Boost.Threads library, you might write + +
    +
    +project boost : /home/dave/boost-cvs ;
+
    +
    + + in your Jamrules file, and place + +
    +
    +@boost/libs/thread/build/boost_thread
+
    +
    + + in your target's list of sources. +

    Feature Descriptions

    Features are described by stating the feature type (simple features @@ -1293,10 +1345,10 @@ flags msvc HDRS <include> ;

    Please note that the build system commonly takes advantage of Jam's - Dynamic Scoping feature (see the local command in the "Flow - of Control" section below the link target) to temporarily "change" a - global variable by declaring a local of the same name.

    + "jam_src/Jam.html#bindingmods">Jam's Dynamic Scoping feature (see the + local command in the "Flow of Control" section below the link + target) to temporarily "change" a global variable by declaring a + local of the same name.

    Many of the variables that are used to configure how Boost.Build works internally are listed here with brief @@ -1407,9 +1459,9 @@ flags msvc HDRS <include> ;

    Revised 1 July, 2003 + -->8 September, 2003 + -->