Re: [Boost-users] WG: Boost Build

From: Jurko Gospodnetić (jurko.gospodnetic_at_[hidden])
Date: 2008-02-18 15:29:31

   Hi Stefan.

   First... for Boost Build related problems - the boost.build list 
might be a better choice.

> Project-root
>      |  \	\   \	
> Include src doc examples
> 		 	/	|   
> 		testcase1 testcase2 ...

   Seems doable. :-)

> Now I need some help to make bjam perform the following tasks:
> 
> 1) build the library (this one works already)
> 2) generate a doxygen based documentation out of the the *.cpp files in
> src
> 3) build the  testcases in the "testcaseX" directories

   I can not directly help you with the doxygen part as I never actually 
used it but there is a doxygen toolset that should be able to do what 
you want. Grep under the boost libs folder for Boost library Jamfiles 
using this toolset for examples.

   Any way... do the following:

   1. Prepare a top level Jamroot file in the Project-root folder.
   2. Prepare a Jamfile in 'doc', 'src', 'examples' and 'testcaseX' folders.
   3. Make 'testcaseX' Jamfile build the corresponding test project.
   4. Make the 'examples' Jamfile list its testcaseX projects using the 
build-project rule. You can possibly use the glob rule here so you do 
not need to specify each testcaseX folder.
   5. Make the 'doc' Jamfile build the doxygen documentation (which I 
can not help with :-)).
   6. Make the 'src' Jamfile build the main program.
   7. Make the Jamroot file define the top level project, specify its 
source-location as src and call build-project on 'doc', 'src' & 
'examples' projects.

> For the time being I'm lacking the knowledge how to build targets (the
> above tasks separately - I tried to use the "explicit" keyword but it
> seems that missed something - bjam works trough all targets given in the
> Jamroot file which I placed in the "project-root" directory - could
> somebody please give me an example how to use targets and "explicit"
> correctly 

   For example:

   exe myExecutable : source1.cpp source2.cpp : <myFeature>1 ;
   explicit myExecutable ;

   Now myExecutable will only get build if you explicitly request it on 
the command line or some other build target explicitly lists it as one 
of its sources.

   I am not sure at the moment whether explicit works with sub-project 
targets or whether you need to use the use-project rule instead of 
build-project in order not to have them build by default, by that should 
be easy to test.

> And last but not least : how is the correct syntax for building sources
> in  subdirectories - where have I to put the Jamfiles and how to I tell
> bjam to look for them ?

   You can place the Jamfiles wherever you like. :-) You can point your 
project to where its sources are by specifying its source-location 
(possibly multiple ones) in its project rule call. Then all (well 
actually most... it makes more sense to search for some stuff from the 
Jamfile anyway) file and folder names you list will be searched for from 
that location instead of from the Jamfile's location.

   [Note though that paths used in <include> properties are always 
searched from the Jamfile's location. I remember some discussions a long 
time ago about changing it to work based on the source-location as well, 
but nothing seems to have been done.]

   You make bjam process your Jamfiles in any of the following ways:
   1. Go to its folder and run bjam.
   2. Go to one of its parent project's folders and run bjam <projectId> 
or bjam <pathToProject> (not sure about this).
   3. Make some other project build it using the build-project rule.
   4. Make some other project reference it using the use-project rule 
and then have its targets available.

   Hope this helps.

   Best regards,
     Jurko Gospodnetić