Re: [jamboost] [ANN] Milestone1

From: David Abrahams (dave_at_[hidden])
Date: 2002-08-14 16:40:46

----- Original Message -----
From: "Vladimir Prus" <ghost_at_[hidden]>
To: <jamboost_at_[hidden]>
Sent: Wednesday, August 14, 2002 8:04 AM
Subject: [jamboost] [ANN] Milestone1

>
> I think we've close to what I envisioned as our first milestone, and
which
> can be shown to the world. The focus of Milestone1 has been on
foundations:
>
> - Project loading and relationship
> - Internal mechanisms for declaring main targets
> - Dependency graph representation ("virtual targets")
> - Command line
>
> If you're interested in looking at current state, and have g++ installed:
> 1. Update to the CVS state
> 2. Build jam (bjam -v output should give version 3.1.1 or later)
> 3. Go to tools/build/examples-v2/make
> 4. Run bjam
> 5. File readme.txt suggests other command lines for bjam.
>
> The example mainly shows
> - Project declaration (there's no mandatory "subproject" any more, and
it's
> possible to declare project requirements which will be inherited.
> - Using targets from other projects. It would allow anybody to write
> something like
>
> exe a : a.cpp @/boost/threads ;
>
> It means that Boost.Build can easily pass project boundaries -- you don't
> have to manually specify locations for boost libraries, for example.
>
> - New comand line. One example is
>
> bjam release <debug-symbols>off

The readme file seems to confirm it's

bjam release debug-symbols=off

> There's also beginning of the user manual in
tools/build/boost_build_v2.html.
> I would appreciate any comments on the example and documentation.

The example uses "make" as the name of the main project. I think that's a
bit confusing in light of the "make" rule that is used all over.

I would like to see "main target" defined in the docs before it is used...
or at least a definition linked to everywhere the term is used.

It would be useful to have an example of a "propagated" feature. Someone
reading this should go "ah, I see why that's useful" for each feature
attribute.

The description of optional features mentions "the default value", but
never says where it comes from. Should say that the default value of
non-free features is the first one listed in the feature's declaration.

In the description of composite features, "/added/" should be
"<i>added</i>" ;-)

------
The wording of this doesn't make much sense to me:

"In general, there are many possible situations: a libary which is
dependency of a main target and should be linked into it, target which is
directly requested on the command line, or build executable which is used
in the build process itself. At this moment we use a simple approach."

I feel that the wording I had proposed was very clear, if too specific to
one case. Your change made it unclear. Maybe this would be better:

"The build request may come directly from the user's command-line or from a
dependency of a main target upon a library." [I didn't understand "or build
executable which is used in the build process itself", so I didn't try to
reword it. I also didn't think the final sentence helped in any way...maybe
it would work better if you ended with a colon and joined the following
paragraph, though I'm not sure if that reflects your intended meaning]

You end with "Whenever requested and actual properties are link-compatible,
it's OK. Otherwise, it's an error". I think we don't want that behavior.
Currently in v1, if the command-line build request is, e.g.
<runtime-link>static, and we have a target which requires
<runtime-link>dynamic, it simply warns that it's skipping that target due
to incompatible requirements.

That also seems to contradict what you say about "property refinement"
(nice name, BTW), in which the properties of the build request are adjusted
to match the target.

----- New wording for Initialization section ----

Upon startup, bjam searches for a file called "boost-build.jam", first in
the invocation directory, then in its parent and so forth up to the
filesystem root, and finally in the directories specified by the
environment variable BOOST_BUILD_PATH. When found, the file is interpreted,
and should specify the build system location by calling the boost-build
rule:

rule boost-build ( location ? )

If location is a relative path, it is treated as relative to the directory
of boost-build.jam. The directory specified by location and directories in
BOOST_BUILD_PATH are then searched for a file called bootstrap.jam which is
interpreted and is expected to bootstrap the build system.
This arrangement allows the build system to work without any command-line
or environment variable settings. For example, if the build system files
were located in a directory "build-system/" at your project root, you might
place a boost-build.jam at the project root containing:

boost-build build-system ;

In this case, running bjam anywhere in the project tree will automatically
find the build system.
-----

The link to "#command_line_options" is broken.

------

"An argument which does not contain slashes or the "=" symbol is either a
value of an implicit feature, or target to be build"

Should be "built" not "build".

------

"Each component is converted into a set of properties"

How?

------

"Property sets for each of the component are set-theoretically
multiplicated"

Should be "multiplied", grammatically speaking. However, I don't know what
this means, and I'm pretty sure it doesn't match the actual semantics.
Somewhere we have docs of what this really does (the Wiki, perhaps?). What
happens in short is that it produces all combinations of specified features
which don't induce feature-conflict.

-------

"Boost.Build considers every software it build as organized into
projects, which corresponds to a single Jamfile"
^------- "each of"

------

Rewrite "The project are organized in a hierarchical structure, so for each
project we can talk about parent project, which is always unique and a
number of subprojects"

as "Projects are organized in a hierarchical structure, so each project may
have a single parent project and a number of subprojects"

More later,
Dave

-----------------------------------------------------------
David Abrahams * Boost Consulting
dave_at_[hidden] * http://www.boost-consulting.com