From: Vladimir Prus (ghost_at_[hidden])
Date: 2005-09-23 10:06:45
On Thursday 22 September 2005 19:36, David Abrahams wrote:
> >> What about hierarchy like this:
> >> 1. Getting Started
> >> [ includes installation and tutorial, with 1-2 small, but complete
> >> examples (points 1. and 2.) ]
> > What I'd prefer is this:
> > - "Hello world" -- a single Jamroot project
> Wait, wait! As Andrey recently wrote:
> Also, at this point the user doesn't know what are toolsets and
> projects. So we should restructure the documentation and put an
> introductory chapter before the Installation chapter. It's
> impossible to install BB without understanding the toolsets.
> So clearly we need to lay some groundwork before we do "Hello World,"
> don't we?
Well, I tend to dislike documentation that don't have a simple example right
away. We can remove "project" and everything else from "Hello, world"
In fact, version of "Hello, World" what Alexey has posted:
seems pretty good to me.
> > - Project structure.
> > Some real-looking example with Jamroot and child Jamfiles
> Okay, but we need to avoid descending into details like target
> references, and we especially need to avoid the problems we currently
> have of vague hints about these things -- even in later material
> > - Libraries -- how to declare and how to use
> Okay, but we need to resist the temptation to descend into details
> like shared vs. static linking on Windows vs. Unix, PATH and
> LD_LIBRARY_PATH, etc.
Agreed, that will be given in user manual in section about libraries.
> > - Testing -- the "unit-test" rule
> > - Installing -- the "install" rule
> > So that this covers much of lifecycle of project.
> >> 2. Writing Jamfiles
> >> [ includes detailed reference of what you can do with Jamfiles, e.g
> >> targets, variables, dependencies, projects; starting simple,
> >> moving towards more complex things (3, 4, 5) ]
> what do these mean?
Those are points that were raised by Alo Sarv in:
> I really dislike that title for a chapter. It encompasses too much,
> including things that may be conceptually necessary for writing
> Jamfiles, but are also conceptually necessary for understanding
> Boost.Build as a whole. Things like targets and projects are highly
> relevant to invoking bjam and extending Boost.Build. And separating
> the command-line stuff from writing Jamfiles is artificial: you're
> going to want to talk about the build request and how it interacts
> with target requirements, about how a build of individual targets can
> be requested from the command line.
> I guess that "[Creating] Boost.Build Projects" might be an appropriate
> title. For some reason, it seems to imply something more general than
> just "writing jamfiles."
> I think you ought to go back and think about the various things you're
> talking about covering in this section and break each one down in more
> detail into sub-elements, then see how they should be organized. In
> fact, this whole outline needs more detail [I see you try to do that
> below -- put that information in context]
In fact, I'm now thinking that we should try flat structure for the whole
"User manual section".
> > I think this organization is fine. The biggest question now is
> > detailed structure of section 2. Topics should include:
> > - Language reference (current (just added)
> > http://boost.org/boost-build2/doc/html/bbv2/advanced.html#bbv2.advanced.j
> >am_language) - Features and properties
> > - Configuration
> > - Declaring targets (current
> > http://boost.org/boost-build2/doc/html/bbv2/advanced/targets.html) -
> > Builtin features
> I don't think that makes sense. Are we really going to introduce
> people to features and properties in general as a separate topic
> without showing them builtin features?
All builting features? There's a lot of them.
> > - Shared/static libraries
> The topic should be "libraries." Shared and static linkage issues
> should be a subtopic.
> > - testing rule
> > - install rules
> > - low-level rules (make and notfile)
> Hmm, I'm not sure these should be in separate topics without an
> overarching topic, "Globally Available Rules" or something. I don't
> quite like the wording, but the point is to distinguish these rules,
> which are automatically injected into Jamfiles for use without
> qualification, from any old "builtin rule."
> > - declaring project constants
> > Any additions?
> Explain target references early on.
> Be sure to explain where target and project references are required
> and clearly distinguish them from filesystem paths.
Ok, I'll try to prepare a more detailed outline and post it on Monday.
-- Vladimir Prus http://vladimir_prus.blogspot.com Boost.Build V2: http://boost.org/boost-build2
Boost-Build list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk