Re: [jamboost] [ANN] Milestone1

From: Vladimir Prus (ghost_at_[hidden])
Date: 2002-08-15 03:33:11

David Abrahams wrote:

> > - New comand line. One example is
> >
> > bjam release <debug-symbols>off
>
> The readme file seems to confirm it's
>
> bjam release debug-symbols=off

I've made a typo in my email.

> > 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.

-0. It's not a great name but OK for me. Besides, renaming directories in CVS 
is pain...

> 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.

Moving the defining before would require changing the document structure. We 
certainly need some introduction, but what we have now is reference, so some 
forward links are OK -- I've made a link.

> 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.

Tried to clarify.

> 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.

Done.

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

Disagree ;-) This should be <em>added</em> :-)

> ------
> 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]

I meant that 
There is many ways a main target can use another target. For example, that 
another target can be executable, somehow used in construction of the the 
first target -- consider GenFile from Jambase. For every possible way of 
using another target, there are different rules whether we can use a given 
subvariant or not. However we only assume linking and therefore use a simple 
approach that I describe in the following paragraph.

> 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.

This makes sense. However, untill now I assumed that if property refinement 
fails, this is an error, except for project targets, which are skipped. Do 
you suggest that I we fail to refine properties for *any* target, it will be 
skipped with a warning?

> ----- 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.

Your wording is better, except that I don't 
"Upon startup, bjam searches for a file called "boost-build.jam"," 
as the first phrase. Reader is left wondering why all the actions are 
performed, and is never explicitly told that. I think "attempts to find the 
location of build system files" should be retained in some form.

> -----
>
> The link to "#command_line_options" is broken.

Fixed.

> ------
>
> "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".

Fixed.

> ------
>
> "Each component is converted into a set of properties"
>
> How?

I think the following text describes the process. I reworded it.

> ------
>
> "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.

"set multiplication" is the same as all combinations. And as the person who 
coded this part, I'm pretty sure the docs are accurate. It's not a build 
request expansion. Consider build request

gcc borland/<runtime-link>static borland/<runtime-link>dynamic

Here, "gcc" and "borland" conflict.

In command line you might write

gcc borland/runtime-link=static,dynamic

and get the above build request. "Set multiplication" applies to the second 
element of command line, and use to avoid excessive typing as in

gcc borland/runtime-link=static borland/runtime-link=dynamic

It's merely a syntactic shortcut, and there's no need to care about feature 
conflicts. If somebody would write 

gcc/borland,gcc

We'll get invalid build request

gcc/borland gcc/gcc

and will detect it.

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

Fixed.

> ------
>
> 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"

Fixed. There is a problem thought. I remember we've talked about naming of 
"project-root" before but I can't find that message. Do you think that now 
when every Jamfile corresponding to a project, the name "project-root" is 
accurate. I feel that "project-root" might be taken as the directory where 
*Jamfile* lives -- but maybe it's my english.

> More later,

I'm looking forward

Thanks,
Volodya