Re: [jamboost] [ANN] Milestone1

From: David Abrahams (dave_at_[hidden])
Date: 2002-08-15 16:18:00

From: "Vladimir Prus" <ghost_at_[hidden]>

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

But examples aren't for you. They're for the rest of the world (especially
if you wrote them).

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

Almost. Try:

"For instance, when an optimized exectuable is requested, one usually wants
it to be linked with optimized libraries. Thus, the <optimization> feature
is propagated."

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

"The build request can originate in many ways: It may come directly from
the user's command-line, from a
dependency of a main target upon a library, or from a dependency of a
target upon an executable used to build that target, for example"

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

I think you should add exactly the above to my proposed text above it.

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

I think I see what you mean, though there's no definition for "project
targets". If it means roughly the same as "main target", I think I agree.

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

But it doesn't attempt to find the build system files.. It attempts to find
boost-build.jam, which is expected to /specify/ the location of the build
system files.

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

Okay, I see what you mean, but the docs don't communicate it.

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

I guess I don't understand your question. Examples of what you mean might
help.

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