[Boost-build] projects and usage requirements

From: Emil Dotchevski (emildotchevski_at_[hidden])
Date: 2006-05-04 20:44:00

Hello,

I am using boost-build v2 to build my own code, and as a side bonus I can 
refer to boost libs from my jamfiles, and they get built and linked 
automatically.

But I have to admit I am very confused about projects. Can someone help me 
understand this: if I have a jamfile which defines a project and a lib 
target, what is the difference between specifying usage requirements through 
the usage-requirements attribute of the project vs. specifying them in the 
lib target?

Going through the boost-build documentation didn't help so I decided to look 
at some jamfile.v2 files in boost. I'm puzzled by the content of jamfile.v2 
for boost.thread:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
import os ;

if [ os.name ] = NT
{
    reqts = <link>shared:<define>BOOST_THREAD_BUILD_DLL=1 ;
}
else
{
    # Declare the uses system library
    lib pthread : : <name>pthread ;
    usage = <library>pthread ;
}

project boost/thread
    : source-location ../src
    : usage-requirements $(usage)
    : requirements $(reqts)  <threading>multi
    : default-build <threading>multi
    ;

CPP_SOURCES = condition mutex recursive_mutex thread xtime once
                  exceptions barrier tss tss_hooks tss_dll tss_pe ;

lib boost_thread
   : $(CPP_SOURCES).cpp
   ;
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Ideally I want any of my projects that ends up linking boost_thread to have 
been built with <threading>multi without me having to specify it explicityl 
in my requirements. But it doesn't seem to work.

In fact I am so confused by projects that I don't understand how am I 
supposed to refer to boost.thread in my jamfiles! Do I use /boost/thread? 
Or, do I have to refer to the boost_thread target explicitly like so: 
/boost/thread//boost_thread. It seems that either way boost.thread is built 
and linked, but the referring projects don't get built with 
<threading>multi -- unless I explicitly put it in their requirements. And 
even this is confusing: do I have to add <threading>multi to the project's 
requirements, or to the lib target found in the same jamfile?

Please help, my head hurts from trying to understand this stuff!

Thanks,
Emil