From cdee2691d6abc08c6b60b03de1e0c6b735eaa12f Mon Sep 17 00:00:00 2001 From: Vladimir Prus Date: Mon, 16 Jun 2003 13:01:04 +0000 Subject: [PATCH] Use new target-id syntax in docs. [SVN r18804] --- boost_build_v2.html | 91 +++++++++++++++++++----------------------- v2/boost_build_v2.html | 91 +++++++++++++++++++----------------------- 2 files changed, 84 insertions(+), 98 deletions(-) diff --git a/boost_build_v2.html b/boost_build_v2.html index a03316fcd..73f498b55 100644 --- a/boost_build_v2.html +++ b/boost_build_v2.html @@ -22,12 +22,12 @@ div.alert { color: red } table { align: center; border: thin; } - + + - build request, build request expansion and directly requested targets + - conditional properties + -->

bjam there. A simple application will be built. You can also play with other projects in examples-v2. + it somewhere. + +

It is slighly better way is to copy new/user-config.jam + into one of the locations where it can be found (given in this table). This prevent you from + accidentally overwriting your config when updating.

--> @@ -327,9 +327,9 @@ boost-build /path/to/boost.build ; Then, to use this library in src/Jamfile, we can write: 
-     exe app : app.cpp ../lib/lib1/lib1 ;
+     exe app : app.cpp ../lib/lib1//lib1 ;
- While "app.cpp" is a regular source file, "../lib/lib1/lib1" is a + While "app.cpp" is a regular source file, "../lib/lib1//lib1" is a reference to another target, here, library "lib1" declared in Jamfile at "../lib/lib1". When linking the "app" binary, the needed version of the library will be built and linked in. But what is meant by "needed"? For @@ -363,11 +363,13 @@ boost-build /path/to/boost.build ; paths any longer. Or course, the path will be interpreted relatively to "lib/lib1" and will be adjusted according to the bjams invocation directory. For example, if building from project root, the - final compiler's command line will contain -Ilib/lib1. The - second problem is that we hardcode the path to library's Jamfile. Imagine - it's hardcoded in 20 different places and we change the directory layout. - The solution is to use project ids — symbolic names, not tied to - directory layout. First, we assign a project id to Jamfile in lib/lib1: + final compiler's command line will contain -Ilib/lib1. + +

The second problem is that we hardcode the path to library's Jamfile. + Imagine it's hardcoded in 20 different places and we change the directory + layout. The solution is to use project ids — symbolic names, not + tied to directory layout. First, we assign a project id to Jamfile in + lib/lib1:

     project lib1
         : usage-requirements <include>.
@@ -375,10 +377,10 @@ boost-build /path/to/boost.build ;
Second, we use the project id to refer to the library in src/Jamfile: 
-    exe app : app.cpp @/lib1/lib1 ;
+    exe app : app.cpp /lib1//lib1 ;
- The "@/lib1/lib1" syntax is used to refer to target "lib1" in project - with global id "@/lib1" (the slash is used to specify global id). This + The "/lib1//lib1" syntax is used to refer to target "lib1" in project + with global id "/lib1" (the slash is used to specify global id). This way, users of "lib1" do not depend on its location, only on id, which is supposedly stable. The only thing left, it to make sure that src/Jamfile knows the project id that it uses. We add to [top]/Jamfile the following @@ -400,7 +402,7 @@ boost-build /path/to/boost.build ; 
     lib utils : utils.cpp ; # Uses Boost.Filesystem
     lib core : core.cpp ;   # Uses 'utils'
-    exe app : app.cpp core utils @/boost/filesystem/fs ;
+    exe app : app.cpp core utils /boost/filesystem//fs ;
This works, but each application should, in effect, explicitly specify @@ -415,7 +417,7 @@ boost-build /path/to/boost.build ; executable. Seems like the effect is the same as when library is specified in sources. But the feature allows us to write:

-    lib utils : utils.cpp : : : <library>@/boost/filesystem/fs ;
+    lib utils : utils.cpp : : : <library>/boost/filesystem//fs ;
     lib core : core.cpp : : : <library>utils ;
     exe app : app.cpp core ;
    
@@ -424,16 +426,16 @@ boost-build /path/to/boost.build ;
     
The application uses "core", which has <library>utils in usage
     requirements, so that property will added to build properties for "app".
     As the result, "utils" will be linked to "app" — automatically.
-    Likewise, "@/boost/filesystem/fs" will be linked in without any
+    Likewise, "/boost/filesystem//fs" will be linked in without any
     effort.

 
     
The <library> property can be used in more ways. For example, if
-    "@/boost/filesystem/fs" should be linked to all applications in your
-    project, you can add <library>@/boost/filesystem/fs to requirements
+    "/boost/filesystem//fs" should be linked to all applications in your
+    project, you can add <library>/boost/filesystem//fs to requirements
     of the project, like this:

 
     project 
-       : requirements <library>@/boost/filesystem/fs
+       : requirements <library>/boost/filesystem//fs
        ;
    
 

@@ -495,15 +497,15 @@ boost-build /path/to/boost.build ;
         cannot change. But still, you want static linking to that library in
         all cases. You can use target references everywhere: 
 
-    exe e1 : e1.cpp @/other_project/lib1/<link>static ;
-    exe e10 : e10.cpp @/other_project/lib1/<link>static ;
+    exe e1 : e1.cpp /other_project//lib1/<link>static ;
+    exe e10 : e10.cpp /other_project//lib1/<link>static ;
    
 

         but that's far from being convenient. Another way is to introduce a
         level of indirection: create a local target, which will refer to
         static version of lib1. Here's the solution: 
 
-    alias lib1 : @/other_project/lib1/<link>static ;
+    alias lib1 : /other_project//lib1/<link>static ;
     exe e1 : e1.cpp lib1 ;
     exe e10 : e10.cpp lib1 ;
    
@@ -536,7 +538,7 @@ boost-build /path/to/boost.build ;
     depends on properties of dependents. If "app" binary should use "lib2",
     we can write: 
 
-    exe app : app.cpp @/lib/lib1/lib2 ../lib/lib2/lib2 ;
+    exe app : app.cpp /lib/lib1//lib2 ../lib/lib2//lib2 ;
 

     If we build release version of "app", then it will be linked with
     "lib2_release.a", and debug version will use "lib2_debug.a". Another
@@ -1448,17 +1450,17 @@ borland/runtime-link=static,dynamic
 
       
  • It allows to have main target names with slashes. 
       
+            That makes good rationale for why main target must contain names.
+             -->
       
    • 
     
 
@@ -1477,15 +1479,6 @@ borland/runtime-link=static,dynamic
     to be linked in even if the compiler executable is build with
     optimization for speed. 
 
-    
    Ambiguity resolution
    
-
-    
    Target reference may have the same form as a pathname, for example
-    lib/a. In order to determine if this is target reference or
-    pathname, it is checked if there's a jamfile in the specified path. If
-    there is one, it is loaded and if the specified target is declared by
-    that project it is used. Otherwise, we just treat the target reference as
-    a file name.
    
-
     
    File targets
    
     As described above, file targets corresponds to files that Boost.Build
     manages. User's may be concerned about file targets in three ways: when
diff --git a/v2/boost_build_v2.html b/v2/boost_build_v2.html
index a03316fcd..73f498b55 100644
--- a/v2/boost_build_v2.html
+++ b/v2/boost_build_v2.html
@@ -22,12 +22,12 @@
         div.alert { color: red }
         table { align: center; border: thin; }
         
-                                
+                                    
   
   
+                                                  - build request, build request expansion and directly requested targets
+                                                  - conditional properties
+                                                -->
 
   
     
    bjam there. A simple application will be built. You can also
       play with other projects in examples-v2. 
       
+                                               it somewhere. 
+                                                
+                                                  
    It is slighly better way is to copy new/user-config.jam
+                                                  into one of the locations where it can be found (given in this table). This prevent you from
+                                                  accidentally overwriting your config when updating.
     -->
       
     
 
@@ -327,9 +327,9 @@ boost-build /path/to/boost.build ;
 
    
     Then, to use this library in src/Jamfile, we can write: 
 
    -     exe app : app.cpp ../lib/lib1/lib1 ;
+     exe app : app.cpp ../lib/lib1//lib1 ;
 
    
-    While "app.cpp" is a regular source file, "../lib/lib1/lib1" is a
+    While "app.cpp" is a regular source file, "../lib/lib1//lib1" is a
     reference to another target, here, library "lib1" declared in Jamfile at
     "../lib/lib1". When linking the "app" binary, the needed version of the
     library will be built and linked in. But what is meant by "needed"? For
@@ -363,11 +363,13 @@ boost-build /path/to/boost.build ;
     paths any longer. Or course, the path will be interpreted relatively to
     "lib/lib1" and will be adjusted according to the bjams
     invocation directory. For example, if building from project root, the
-    final compiler's command line will contain -Ilib/lib1. The
-    second problem is that we hardcode the path to library's Jamfile. Imagine
-    it's hardcoded in 20 different places and we change the directory layout.
-    The solution is to use project ids — symbolic names, not tied to
-    directory layout. First, we assign a project id to Jamfile in lib/lib1: 
+    final compiler's command line will contain -Ilib/lib1. 
+
+    
    The second problem is that we hardcode the path to library's Jamfile.
+    Imagine it's hardcoded in 20 different places and we change the directory
+    layout. The solution is to use project ids — symbolic names, not
+    tied to directory layout. First, we assign a project id to Jamfile in
+    lib/lib1:
    
 
         project lib1
         : usage-requirements <include>.
@@ -375,10 +377,10 @@ boost-build /path/to/boost.build ;
 
    
     Second, we use the project id to refer to the library in src/Jamfile: 
 
    -    exe app : app.cpp @/lib1/lib1 ;
+    exe app : app.cpp /lib1//lib1 ;
 
    
-    The "@/lib1/lib1" syntax is used to refer to target "lib1" in project
-    with global id "@/lib1" (the slash is used to specify global id). This
+    The "/lib1//lib1" syntax is used to refer to target "lib1" in project
+    with global id "/lib1" (the slash is used to specify global id). This
     way, users of "lib1" do not depend on its location, only on id, which is
     supposedly stable. The only thing left, it to make sure that src/Jamfile
     knows the project id that it uses. We add to [top]/Jamfile the following
@@ -400,7 +402,7 @@ boost-build /path/to/boost.build ;
 
         lib utils : utils.cpp ; # Uses Boost.Filesystem
     lib core : core.cpp ;   # Uses 'utils'
-    exe app : app.cpp core utils @/boost/filesystem/fs ;
+    exe app : app.cpp core utils /boost/filesystem//fs ;
    
 
    
     This works, but each application should, in effect, explicitly specify
@@ -415,7 +417,7 @@ boost-build /path/to/boost.build ;
     executable. Seems like the effect is the same as when library is
     specified in sources. But the feature allows us to write:
    
 
    -    lib utils : utils.cpp : : : <library>@/boost/filesystem/fs ;
+    lib utils : utils.cpp : : : <library>/boost/filesystem//fs ;
     lib core : core.cpp : : : <library>utils ;
     exe app : app.cpp core ;
    
@@ -424,16 +426,16 @@ boost-build /path/to/boost.build ;
     
    The application uses "core", which has <library>utils in usage
     requirements, so that property will added to build properties for "app".
     As the result, "utils" will be linked to "app" — automatically.
-    Likewise, "@/boost/filesystem/fs" will be linked in without any
+    Likewise, "/boost/filesystem//fs" will be linked in without any
     effort.
    
 
     
    The <library> property can be used in more ways. For example, if
-    "@/boost/filesystem/fs" should be linked to all applications in your
-    project, you can add <library>@/boost/filesystem/fs to requirements
+    "/boost/filesystem//fs" should be linked to all applications in your
+    project, you can add <library>/boost/filesystem//fs to requirements
     of the project, like this:
    
 
         project 
-       : requirements <library>@/boost/filesystem/fs
+       : requirements <library>/boost/filesystem//fs
        ;
    
 
    
@@ -495,15 +497,15 @@ boost-build /path/to/boost.build ;
         cannot change. But still, you want static linking to that library in
         all cases. You can use target references everywhere: 
 
    -    exe e1 : e1.cpp @/other_project/lib1/<link>static ;
-    exe e10 : e10.cpp @/other_project/lib1/<link>static ;
+    exe e1 : e1.cpp /other_project//lib1/<link>static ;
+    exe e10 : e10.cpp /other_project//lib1/<link>static ;
    
 
    
         but that's far from being convenient. Another way is to introduce a
         level of indirection: create a local target, which will refer to
         static version of lib1. Here's the solution: 
 
    -    alias lib1 : @/other_project/lib1/<link>static ;
+    alias lib1 : /other_project//lib1/<link>static ;
     exe e1 : e1.cpp lib1 ;
     exe e10 : e10.cpp lib1 ;
    
@@ -536,7 +538,7 @@ boost-build /path/to/boost.build ;
     depends on properties of dependents. If "app" binary should use "lib2",
     we can write: 
 
    -    exe app : app.cpp @/lib/lib1/lib2 ../lib/lib2/lib2 ;
+    exe app : app.cpp /lib/lib1//lib2 ../lib/lib2//lib2 ;
 
    
     If we build release version of "app", then it will be linked with
     "lib2_release.a", and debug version will use "lib2_debug.a". Another
@@ -1448,17 +1450,17 @@ borland/runtime-link=static,dynamic
 
       
  • It allows to have main target names with slashes. 
       
+            That makes good rationale for why main target must contain names.
+             -->
       
    • 
     
 
@@ -1477,15 +1479,6 @@ borland/runtime-link=static,dynamic
     to be linked in even if the compiler executable is build with
     optimization for speed. 
 
-    
    Ambiguity resolution
    
-
-    
    Target reference may have the same form as a pathname, for example
-    lib/a. In order to determine if this is target reference or
-    pathname, it is checked if there's a jamfile in the specified path. If
-    there is one, it is loaded and if the specified target is declared by
-    that project it is used. Otherwise, we just treat the target reference as
-    a file name.
    
-
     
    File targets
    
     As described above, file targets corresponds to files that Boost.Build
     manages. User's may be concerned about file targets in three ways: when