Re: [Boost-build] help! Are there any good examples of bjam in action?

From: Jurko Gospodnetić (jurko.gospodnetic_at_[hidden])
Date: 2007-12-22 08:11:12

   Hi David.

> There seems to be a fair few people using bjam and, whilst it's nice 
> there's an 'example' directory packaged with the source, I I cannot find 
> any 'non-trivial' examples of bjam being applied.

   Yup, until better user docs get prepared there is a log of research 
involved in using Boost Build, but we for one use it now for most of our 
projects.. :-) And it is great that you can look under the hood and push 
for new features or implement them yourself when needed. :-)

   I'm going to try and give you a few hints to get you started in the 
right direction, and if I get the time a bit later on (does not look 
like it at the moment :-( ) I'll try to prepare an example Jamfile.

> 1. how would you specify separate <include>s for the standard template 
> libraries dependent on whether the system is being built on windows (VC) 
> or linux (gcc)?

   Hmmm, first thing that pops to mind is using the <include> feature to 
specify the include directory and conditioning it on the value of the 
<os> feature. E.g. specifying something like this in your project's 
requirements clause:

project SuperJam
     :
     requirements

     <os>NT:<include>/WindowsHeaders
     <os>CYGWIN:<include>/CygwinHeaders
     <os>LINUX:<include>/LinuxHeaders
;

You may do similar conditioning based e.g. on the <toolset> feature to 
get different includes/defined based on which compiler you're using.

> 2. how would you recursively compiling a hierarchy of folders into a 
> library (to .lib or/and .dll) ?

   When specifying files to include in your library use the glob() rule. 
For example instead of specifying:

exe sjDevelopment
     :
     $(SOURCE)/module1.cpp
     $(SOURCE)/module2.cpp
     $(SOURCE)/module3.cpp
     $(SOURCE)/module4.cpp
     $(SOURCE)/module5.cpp
     $(SOURCE)/module6.cpp
;

   you can specify:

exe yourExe
     :
     [ glob $(SOURCE)/*.cpp ]
;

   See the Boost Build docs/source or ask on the list for more 
information on what type of filters you can specify with the glob() rule.

   Also, note that specifying files like this does not immediately imply 
them being of the same type. Your glob() call could include different 
types such as .cpp files, .rc files, whatever, and each could get built 
using its own separate actions (depending of course on how you specify 
those in the rest of your Jamfiles).

> 3. how do you link against pre-built dlls ?

   We do it like this:

     1. Declare the prebuilt libraries using the lib rule, assigning it 
a logical name for use under Boost Build.
     2. Reference the library by the name specified in the step above 
wherever needed in the rest of the Jam files.

   Here's an example for using OpenSSL libraries (statically linked in 
this case, but does not matter, same lib rule is used for DLL's as 
well). Note that the same 'logical library' actually means different 
things depending on which build settings you use (e.g. which compiler 
you use or whether you're building your project in debug or release mode):

Declaration in Jamroot:

lib eaylib_static_rtlStatic : : <name>crypto      <toolset>gcc 
                    <search>$(SSL_ROOT)/lib           ;
lib eaylib_static_rtlStatic : : <name>libeay32MTd <toolset>msvc 
<variant>debug             <search>$(SSL_ROOT)/lib/VC/static ;
lib eaylib_static_rtlStatic : : <name>libeay32MT  <toolset>msvc 
<variant>release           <search>$(SSL_ROOT)/lib/VC/static ;
lib ssllib_static_rtlStatic : : <name>ssl         <toolset>gcc 
                    <search>$(SSL_ROOT)/lib           ;
lib ssllib_static_rtlStatic : : <name>ssleay32MTd <toolset>msvc 
<variant>debug             <search>$(SSL_ROOT)/lib/VC/static ;
lib ssllib_static_rtlStatic : : <name>ssleay32MT  <toolset>msvc 
<variant>release           <search>$(SSL_ROOT)/lib/VC/static ;

Usage in a subproject's Jamfile:

exe subprojectExe
     :
     $(SOURCE)/subprojectModule1.cpp
     $(SOURCE)/subprojectModule2.cpp
     ..//eaylib_static_rtlStatic
;

   Btw. one resource I recently found helpful in locating usage examples 
is the Google code search... :-) try it out if you get stuck figuring 
our how to use some feature...

   Hope this helps.

   Best regards,
     Jurko Gospodnetić