[boost] Trying to learn build system

From: Gennadiy Rozental (rogeeff_at_[hidden])
Date: 2002-07-07 07:09:02

Hi,

I am trying to start using Boost.Build system. After several days of reading
and playing I must admit that I still completely lost - I do not understand
how this thing is working. I was not able to run the tests I wanted. I am
not able to write "makefile" (Jamfile?) myself and I am almost completely
clueless how to write toolset description for my Sun box ( BTW how do we
produce Compiler results on Sun without build toolset for sunpro?). I may
need some help.

  Ok. Starting with "Building Boost Libraries" page and following the
instructions there I was able to build some offline libs on my NT box. Now I
wanted to create Compiler status page. I did not find any reference how to
do this. In fact I did not find any reference how to compile and run any
tests at all. Should I look in different place?

   Next I was trying to reveal how it is done. Very quickly I realized that
there are a lot of things behind the scene and these "things" include some
agreements, global variables and scripts written in some language that I do
not understand (In fact I was not able to find language description
anywhere, only pieces here and there). So I address my eyes to Boost Build
System documentation.

Synopsis, status and TOC I understand. Getting started already a bit
confusing since it has a section "Setting Jam Variables", while both terms
"Jam" and "Jam variables are not introduced yet. Next we see "An Example
Jamfile" which is again an example of things that not defined yet. For a new
user like me it is a bit confusing. Though again maybe I should have read
something else before. Support Files section seems incomplete (there some
other files that looks like support). More over "meanings" are unclear for
unfamiliar user (unfamiliar with terms feature, rules toolset and so on).
Looking inside of these files making things even worse. What are these
files: part of Jam, Part of Build.Build, what do I need to know about them?
BTW unit_test.jam listed here But never ever mention in any other place

"Basic Design and Terminology" bring some hope. But statement about Jamrules
file is unclear: what is "Jam code", what the difference between Jamfile and
Jamrules file?

Target section defined term "main target". In what sense it is main? And
what means definition of "build targets" as an  expressions of the
corresponding main target under particular compilers and build variants?

"Features and Properties" section left me wondering how features are related
to my  Jamfiles, how to use and define them. As far as I understand
features.jam list some predefined features. Is there complete description
for all of them? But what is most important I did not get how defining the
feature affect the build system. I presume it something in ??-tools files,
but syntax unclear to me.

Pararagraphs about variant and subvariant I did not understand completely.
What is a "variant": term, feature, rule? How it is related/mentioned in
Jamfiles? What are the variant statements in features.jam? How is it related
to global variable BUILD? "subvariant" paragraph left me clueless also.

Usage:

Global variables section list only 3 variables. Is there complete
description of all global variables.
sub-project jamfiles section recommend to use project-root  rule if Jamfile
exist in a project rule directory. How is it know the path to the root then?
And why subproject path is used only of ALL_LOCATE_TARGET is set?

"Describing Main Targets":
What means: "Additional main target rules are possible"? Did you mean it
could be more than one main target?
What are the features I can use in default-BUILD section (other then
<suppress> mentioned for example) ?
And  how do they affect build variants?

"Describing Stage Targets"
Could you clarify what is <tag>? Feature? And How is it used with examples.
Could it be several tags?

"Toolset Description Files"
What is $(<), $(<)?
What are UNDEFS C++FLAGS and so on - global variables? If yes, where could I
find complete list?
Could you clarify again why do I need another level of indirection when
implementing C++-action rule?
What are the argument specification for the rules I need to redefine.
Who is defining the variable gBUILD_PROPERTIES and when it should be used?
Why do I need  to mention toolset name for flags rule? I am already in
toolset file.
What if condition is just a <feature> without value. When flag will be set?

In general before moving to the Internals, I would like to remark that there
are a lot of thing (rules, features, GLOBAL_VARIABLES) that are not
mentioned in doc. I remarked that there are about 200 rules defined in both
..base.jam files. Where could I find a description of them?

Internals.
As I sad before language description seems incomplete (descriptive). I could
not find strict syntax specification. Does you assume familiarity with some
other document?

"Jam fundamentals"
What are "actions"? Which built-in rules exist?Which built-in variables
exist and what their meanings? What are the local variables? Without this
knowledge what you writing is unclear and I could not move further.

Hope you will give some pointers,

Thank you in advance,

Gennadiy.