Re: [Boost-users] [bjam] using bjam as a build tool

From: Jurko Gospodnetić (jurko.gospodnetic_at_[hidden])
Date: 2008-02-12 19:59:17

   Hi Ovanes.

> I currently read through the docs for bjam and try to build my first 
> project using. We currently need an automated build system in the 
> current project to run directly from the version control system.
> 
> The doc which I read currently leaves many items open which I do not 
> understand, despite the fact I see bjam as a very cool thing! far 
> superior as make;)

   First, I'd suggest to move further Boost Jam and Boost Build related 
questions to the boost.build list. Less chance of your post getting 
overlooked by 'bjam developers'. On the other hand... less change boost 
library users read your it as well. :-)

> 1. From the userman.pdf I learned that there is a possibility to use 
> modules. Is there any location where I can what the modules do or how 
> they work. Since such examples are not very well to understand:

   Modules are similar to namespaces in C++. You just use the 'module' 
keyword instead of 'namespace'. One difference is that they are not 
nested and so there are not sub-modules.

   Variables you define always live in a single module. They may be 
accessed from other modules by first changing into their module. Two 
rules to help you with this are modules.peek and modules poke which 
effectively do the above for you (see their source for more information 
- it's quite simple).

   There are two 'special' types of modules - the global unnamed module 
and a module that gets created automatically for each Jamfile (for which 
I believe you can not know the name without depending on internal 
implementation details).

> userman.pdf page 47-48
> -------
> "Accessing environment variables
> Many users would like to use environment variables in Jamfiles, for 
> example, to control location of external libraries.
> In many cases you better declare those external libraries in the 
> site-config.jam file, as documented in the recipes
> section. However, if the users already have the environment variables 
> set up, it's not convenient to ask them to set up
> site-config.jam files as well, and using environment variables might be 
> reasonable.
> In Boost.Build V2, each Jamfile is a separate namespace, and the 
> variables defined in environment is imported into
> the global namespace. Therefore, to access environment variable from 
> Jamfile, you'd need the following code:
> 
> import modules ;
> local SOME_LIBRARY_PATH = [ modules.peek : SOME_LIBRARY_PATH ] ;
> exe a : a.cpp : <include>$(SOME_LIBRARY_PATH) ;"
> -------

   What it says above is that if you have an environment variable XXX 
then during initialization Boost Jam automatically loaded its value into 
a Boost Jam variable called XXX and located in the anonymous global 
module. If you want to read it from other modules (such as those created 
for each Jamfile) you should any mechanism for accessing variables in 
other modules, and the example demonstrates using the modules.peek rule 
I mentioned above).

   You might find the following recent thread from the boost.build list 
useful: 
http://www.nabble.com/Sharing-variables-across-multiple-files-td15399393.html

> 2. As I understood I can use user-config.jam to make default 
> configurations for my project. I copied the user-config.jam into the 
> project root, but it is not read, at least bjam issues warnings that 
> toolset was not set and msvc is the default one. How can I specify in 
> user-config.jam a default toolset? Or is the user-config-jam a file to 
> declare available toolset, but toolspecification must be somewhere else? 
> My user-config.jam contains:
> 
> import toolset : using ;
> using msvc ;

   I do not believe user-config.jam is not supposed to be project 
specific but user specific for a given Boost Build installation. If you 
want to set project configuration use the project's Jamroot/Jamfile script.

   I.e. use site-config.jam (or user-config.jam) to specify which Boost 
Build toolsets are available on this machine (or for this user) and 
configure them (e.g. specify where corresponding command-line tools are 
located in case they are not installed in their default location).

   But, if your project always uses msvc and you expect everyone to have 
it installed in its default location then feel free to use 'using msvc' 
directly in your project's Jamroot file.

> 3. How is it possible to specify the source location to 3d party lib 
> (libpath)? I can't build a project with bjam v2 which uses boost libs. I 
> don't want to enumerate each lib which my project depends on, but submit 
> to the linker the lib path. My file content is:
> 
> import modules ;
> local BOOST_STAGE_INCLUDE  = [ modules.peek : BOOST_STAGE_INCLUDE ] ;
> local BOOST_STAGE_LIBS         = [ modules.peek : BOOST_STAGE_LIBS      ] ;
> 
> exe MTSentry   
>                             : main.cpp <source>$(BOOST_STAGE_LIBS)
>                             : <include>$(BOOST_STAGE_INCLUDE) 
> <threading>multi
>                             ;
> 
> The resulting error is:
> bjam.exe --v2 --toolset=msvc
> error: at Jamroot:7
> error: properties found in the 'sources' parameter for ./MTSentry
> 
> Removing the <source> option will build the app, but the linking fails, 
> since boost/thread lib is not found. How can I specify a source 
> directory for libs?

   If you want to use boost libraries use the auto-linking feature if 
the toolset you use supports it and you do not need to specify the used 
boost libraries explicitly at all.

   You specified a 'requirement' property <source>XXX for the MTSentry 
target but you specified it in the list of sources. If you want to 
specify sources using the <source> feature then you need to do it with 
the other requirements, i.e. behind the next colon - together with the 
<include>XXX property.

   If you build Boost library on your computer directly and do not use 
some prepackaged binary distribution then you can use Boost library's 
build system directly and use its library targets as your sources. This 
will automatically build those targets if that becomes needed. See the 
use-project rule for specifying that you use some project and then 
reference targets from it using the projectName//targetName syntax.

   You can also directly specify your own library target's for prebuilt
libraries using the lib rule. Whether you then add an extra layer for 
reading some of its parameters from some environment variables or write 
them in directly in the project's Jamfiles - is up to you. For some 
examples and otherwise potentially useful discussion from a recent 
thread on the boost.build list see 
http://www.nabble.com/Using-boost-libraries-on-Ubuntu-through-Boost.Build-td15333685.html

   Hope this helps.

   Best regards,
     Jurko Gospodnetić