|
|
Boost-Build : |
From: David Abrahams (dave_at_[hidden])
Date: 2004-12-28 12:39:48
-- Dave Abrahams Boost Consulting http://www.boost-consulting.com --------------080006070003070306050704 Content-Type: text/plain; name="volodya.txt" Content-Transfer-Encoding: 7bit Content-Disposition: inline; filename="volodya.txt" > Hi Dave, > here are my comments on your doc edits. > > diff -u -U10000 -r1.7 -r1.8 > --- tutorial.xml 30 Oct 2004 09:32:04 -0000 1.7 > +++ tutorial.xml 28 Dec 2004 03:39:09 -0000 1.8 > > <chapter id="bbv2.tutorial" status="draft"> > <title>Tutorial</title> > > +<!-- You can't launch into this stuff without describing how to configure --> > +<!-- Boost.Build... unless of course you think it's likely to work with --> > +<!-- no configuration. But even if you do you have to tell people how to --> > +<!-- configure their installation in case it doesn't work. --> > + > > Sure, the "how to use this document" suggest that whenever the user decides to really try > V2, he look at installation docs. There are two problems: 1. people typically turn directly to a tutorial and expect to be able to follow along. 2. When I said "configure" I meant not just installation but the neccessary user-config/site-config settings required to find toolsets. > Do you think a link is in order here, too? I don't think a link is sufficient. > things. First of all, just invoking <command>bjam</command> will > - build the debug variant of the <command>hello</command> > + build the debug variant of the <filename>hello</filename>> > > Edit noted. That's just me struggling to find the right tags for Boost.Build concepts; I was the one who originally put <command> around "hello." As you probably know I have requested BoostBook extensions for this. The lesson you should take away is that writing "hello" in quotes is probably not the right approach. > recompilation. Let's extend the example by adding another line > to our project's <filename>Jamfile</filename>: > > <programlisting> > exe hello2 : hello.cpp ; > </programlisting> > > Now we can build both the debug and release variants of our > project: > > +<!-- The phrasing above misleadingly makes it seem as though adding --> > +<!-- this line makes it possible to build two variants, whereas --> > +<!-- they're totally unrelated. --> > + > > Understood. Maybe "Now let us build both the debug and release > variants of our project again"? Very good! > Of course, you probably have better wording anyway. Don't assume I do. Unless I've suggested wording, go ahead and make the edits. I can always improve things later if I think of a way. > It's also possible to build or clean specific targets. The > following two commands, respectively, build or clean only the > - debug version of <command>hello2</command>. > + debug version of <filename>hello2</filename>. > + > +<!-- You can't say that without first telling people that the debug > +variant is the default one, or you just sow confusion. --> > > A bit earler -- after defining the "hello" target, we talk about "debug" variant. Maybe, the fact > that debug is default should be mentioned there? That would be fine. > <para>There are many built-in features that can be combined to > produce arbitrary build configurations. The following command > - builds the project's "release" variant with inlining > + builds the project's <code>release</code> variant with inlining > disabled and debug symbols enabled: > > Ok, so we'll be using <code> for all references to properties. What will be use when talking > about main targets -- quotation marks or <code>? Right now I'm using <filename> but I hope to be able to take advantage of a BoostBook extension soon enough. See my recent boost-docs postings. > - <para>The "release" and "debug" that we've seen > + <para>The <option>release</option> and <option>debug</option> that we've seen > in <command>bjam</command> invocations are just a shorthand way to > - specify values of the "variant" feature. For example, the command > + specify values of the <varname>variant</varname> feature. For example, the command > above could also have been written this way: > > Must have misunderstood something. Is <varname> for features and <code> for values? <varname> is a fairly close match for features, but again a BoostBook extension should help. For values I should be using <literal> until we get the right extension, I think. <code> is probably a mistake. > <para> > The set of properties specified in the command line constitute a > - <firstterm>build request</firstterm> — a description of > + <firstterm>build request</firstterm>—a description of > > Why spaces are gone? At least in LyX/TeX, I always surround em-dashes with spaces. My publisher never puts spaces around em-dashes. > <programlisting> > exe hello > : hello.cpp > : <include>/home/ghost/Work/boost <threading>multi > ; > </programlisting> > > +<!-- Can those requirements be written as > + "include=/home/ghost/Work/boost threading=multi"? If so, we > + should do everything in the manual, or at the very least in the > + tutorial, that way. If not, why not? --> > > We can't, because it's not implemented. I sure would like this syntax. Okay. > requirements specified above will normally always be present. > If the build request given on the <command>bjam</command> > command-line explictly contradicts a target's requirements, > the command-line usually overrides (or, in the case of open paren------------------^ > - "free" feautures like <code><include></code> > - <footnote>See <xref > - linkend="bbv2.reference.features.attributes"/></footnote>, > - augments) the target requirements. > + “free” features like <varname><include></varname>, > > What's ldquo and why it's better than quot? Well, it's illegal in BoostBook apparently, but it's a left curly double quote. I replaced it with the correct Unicode this morning. > + <footnote> > +<para> > +See <xref linkend="bbv2.reference.features.attributes"/> > + augments) the target requirements. > > Are there unmatched parenthesis? I don't think so. See above. > <para>So far we've only considered examples with one project > (i.e. with one <filename>Jamfile</filename>). A typical large > - software project would be composed of sub-projects organized > + codebase would be composed of many projects organized > into a tree. The top of the tree is called the > <firstterm>project root</firstterm>. Besides a > <filename>Jamfile</filename>, the project root directory > contains a file called <filename>project-root.jam</filename>. Every other > <filename>Jamfile</filename> in the project has a single parent > project, rooted in the nearest parent directory containing a > <filename>Jamfile</filename>. For example, in the following > directory layout: > > +<!-- Shouldn't we be introducing Jamroot here instead of --> > +<!-- project-root.jam? It certainly is simpler. --> > + > > We definitely should. Or we should eliminate the need for Jamroot, which would be simpler still. > <section id="bbv2.tutorial.libs"> > <title>Libraries and Dependent Targets</title> > > - <comment>TODO: need to make this > - section consistent with "examples-v2/libraries".</comment> > + <remark>TODO: need to make this > + section consistent with "examples-v2/libraries".</remark> > + > +<!-- > + What does that mean? Either make that change (much preferred), > + or leave a comment that someone else can understand and use to > + fix this section (only an option for the lazy ;->). > +--> > > I meant that it might be good to have and example for each section of tutorial, so that user can experiment. > The examples/libraries is not equal to what's described here. Oh. Well, that's perfectly comprehensible. Please say it that way. > <para> > - Targets that are "needed" by other targets are called > + Targets that are “needed” by other targets are called > > What are those numeric entities? “ and ” ;-) > Found: > > http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.WhichvsThat.html > > which discusses "that" vs. "which" quite clearly. OTOH, at the end > it says that using "which" in restrictive clauses is "more or less > okay (and popular among writers of British English)", so I have an > excuse ;-) (After all, my spellchecker uses British dictionary) Okay, I understand. Don't feel bad; I only learned the rule this year because of the book I wrote. Sometimes I wish I hadn't; now I see thousands of misuses all over the place and they drive me crazy! > lib foo : foo.cpp ; > </programlisting> > > - Usage requirements are requirements which are applied to > - dependents. In this case, <include> will be applied to all > - targets which use "foo" — i.e. targets which have "foo" > - either in sources or in dependency properties. You'd need to > - specify usage requirements only once, and programs which use "foo" > - don't have to care about include paths any longer. Or course, the > - path will be interpreted relatively to "util/foo" and will be > - adjusted according to the <command>bjam</command>s invocation > - directory. For > - example, if building from project root, the final compiler's > + Usage requirements are applied not to the target being declared > + but to its > + dependents. In this case, <literal><include>.</literal> will be applied to all > + targets that use <filename>foo</filename>—i.e. targets that have <filename>foo</filename> > + either in their sources or in their dependency properties. > + <!-- You can't use the term "dependency properties" without first > + defining it! This sort of thing happens over and over. I > + suggest just saying "all targets that directly depend on foo." --> > > I agree to this. Go ahead and make the change. > + You'd need to > + specify usage requirements only once, and programs that use <filename>foo</filename> > + don't have to care about include paths any longer. > + <!-- Point of good writing: programs are inanimate and don't > + "care" about include paths. > > Noted. > > I suggest striking the previous > + sentence anyway as it's redundant. --> > > Agreed. > > + Of course, the > + path will be interpreted relatively to <filename>util/foo</filename> and will be > + adjusted according to the <command>bjam</command> invocation > + directory. > + <!-- You need to explain this path adjustment in the first place > + you introduce #include paths, probably with a "Tip" > + element. > > Agreed. > > It applies to all relative paths in > + Boost.Build, some of which you've covered. --> > > What do you mean? You've already covered #include paths and paths to other projects at the very least. At a high level you just want to say "all relative paths are interpreted relative to the Jamfile where they appear." That way you don't have to talk about "adjusting" the paths. The new user has no idea that bjam runs commands from the invocation directory and not from the directory of the Jamfile (as many other build systems do) anyway. > > - <para>The second problem is that we hardcode the path to library's > - Jamfile. Imagine it's hardcoded in 20 different places and we > - change the directory layout. The solution is to use project ids > - — symbolic names, not tied to directory layout. First, we > - assign a project id to Jamfile in util/foo:</para> > + <para> > + The second problem <!-- by this point I've completely forgotten > + that there was a first problem. I suggest starting the a new > + paragraph for the first one, and describing these as improvements > + we can make, rather than problems. --> > > Agreed. > > > <programlisting> > exe app : app.cpp /foo//bar ; > </programlisting> > > - The "/foo//bar" syntax is used to refer to target "foo" in > - project with global id "/foo" (the slash is used to specify global > - id). This way, users of "foo" do not depend on its location, only > - on id, which is supposedly stable. The only thing left, it to make > - sure that src/Jamfile knows the project id that it uses. We add to > - top/Jamfile the following line: > +<!-- It is counterintuitive and confusing to assign a top-level > + absolute project ID to this subproject. It should be something > + like /myproject/foo. > + > + In fact I'm beginning to > + wonder what the point of labelling the project root with > + project-root.jam or Jamroot is. See my jamboost post. -DWA > +--> > + > + The <filename>/foo//bar</filename> syntax is used to refer to the target <filename>bar</filename> in > + <!-- I assume I was right to change foo into bar here. Please > + take care not to make errors like this one; it leaves the > + reader mightily confused about what's really going on if he > + assumes the documentation is correct. --> > + the project with global id <filename>/foo</filename> (the slash > + is used to specify global id). > + <!-- as opposed to what? There's no such thing as a "local" id > + is there? This parenthetical remark is more confusing than > + enlightening. It gives the impression that we could leave > + the slash off and still have a project id, but a path > + without a preceding slash always specifies a file path > + (right?) --> > + This way, users of <filename>foo</filename> do not depend on its location, only > + on id, which is supposedly stable. The only thing left is to make > + sure that <filename>src/Jamfile</filename> knows the project id that it uses. We add to > + <filename>top/Jamfile</filename> the following line: > > <programlisting> > use-project /foo : util/foo ; > </programlisting> > > QUERTY ?? At first I thought you meant "QWERTY," but that's too hard to mistype (at least on a US keyboard). What is that? > and must be available at run time. Boost.Build can work with both > - types. By default, all libraries are shared. This is much more > + types. > + <!-- This section seems to be introducing the idea of static and > + shared libraries, but you just spent a couple of paragraphs > + talking about them in the previous section! Clearly that is > + not "one important detail that was omitted." Please take care > + that terms are defined and concepts introduced before they're > + used. --> > > This suggests that maybe, "Library Dependencies" section should be merged into "Static and shared libaries", > maybe even as tip at the end. Maybe. > + By default, all libraries are shared. This is much more > efficient in build time and space. But the need to install all > - libraries to some location is not always convenient, especially > - for debug builds. Also, if the installed shared library changes, > - all application which use it might start to behave differently. > + libraries to some location > + <!-- If I'm a reader who doesn't know about shared linking as > + this section seems to assume, I have absolutely no context > + for "the need to install all libraries to some location." > + It has no obvious relationship to anything we're discussing > + here. --> > > Oh, that paragraph is really confusing! > > + is not always convenient, especially > + for debug builds. > + <!-- An incongruous assumption about the reader's knowledge. > + The relationship of debug builds to all this is > + non-obvious. --> > > Agreed. > > <para>Static libraries do not suffer from these problems, but > - considerably increase the size of application. Before describing > - static libraries, it's reasonable to give another, quite simple > + can considerably increase the size of an application. Before describing > + how to use static libraries, it's reasonable to give another, quite simple > approach. If your project is built with > - <hardcode-dll-paths>true property, then the application > - will include the full paths for all shared libraries, eliminating > - the above problems. Unfortunately, you no longer can move shared > + <code><hardcode-dll-paths>true</code> property, the application > + will include the full paths to all shared libraries, eliminating > + the above problems. > + <!-- Not the last one. So it solves just one of two problems > + mentioned above. --> > + Unfortunately, once that's done, you can no longer move that shared > library to a different location, which makes this option suitable > only for debug builds. Further, only gcc compiler supports this > - option.</para> > + option. > + <!-- Now you tell me?! You should put all this information in a > + <tip> box that begins "If you're a GCC user..." --> > + </para> > > I think this section should actually start with "Libraries can be either shared or static, and which one is best > depends on your situation". Do you think that adds any useful information? I don't. A user that doesn't know there are static and shared libraries will immediately infer that from the rest of the text. Saying "which one is best depends on your situation" is semantics-free. That's true of anything. > Then it will say about <link>static and <link>shared, What will it say about them? > say that putting a library in sources of other library works no > matter what kind of linking is used It's _almost_ not worth saying that. The only reason anyone would assume otherwise is experience with dumber build systems. If you want to you can add a footnote that says "Don't worry; this works even with static linking because Boost.Build passes static library dependencies along to the final application." > and then mention (in <tip>) the hardcode-dll-paths feature. That part I agree with ;-) > - <orderedlist> > - <listitem> > - <para> > - Suppose your library can be only build statically. This is > - easily achieved using requirements: > + <para> > + We can also use the <varname><link></varname> property > + to express linking requirements on a per-target basis. > + <!-- <orderedlist> The use of an orderedlist is inappropriate here. --> > > Why? I'm trying to list several situation which are possible for > shared/static linking combinations. An ordered list should be used with an introduction like "There are three ways to do <whatever>:", and probably should only be used if you're really sure you're enumerating *all* the ways to do that. I'm guessing that you're not sure of that here. > + For example, if a particular executable can be correctly built > + only with the static version of a library, we can qualify the > + executable's <link > + linkend="bbv2.reference.targets.references">target > + reference</link> to the library as follows: > + > +<!-- There has been no earlier indication that target references can > + contain properties. You can't assume that the reader will > + recognize that strange incantation as a target reference, or that > + she'll know what it means. You also can't assume that hyperlinks > + will help the reader, because she may be working from a printout, > + as I was. --> > > Does it mean that properties in target references need to be > explained here. Well, with my rephrasing above it's already a bit clearer than saying "easily achieved using requirements," which only points very indirectly at that target reference because it happens to be in the (unlabelled) requirements section of the target. I would say something like, "You can control how a dependency is built by appending elements of the form <code>/<replaceable>property</replaceable></code> to its target reference." > Also, if hyperlinks > are useless in printed docs, doesn't it mean all information have to duplicated in the parts where its used? It means you have to use <xref>. Hopefully we'll get section numbers in the doc and the cross-references will be formatted as "Section x.y.z, name-of-section." If you generate the docs you'll see that these are also hyperlinks. > <programlisting> > > - Note that the <link linkend="bbv2.builtins.alias">alias</link> > - rule is specifically used for rename a reference to a target and possibly > + The <link linkend="bbv2.builtins.alias"><functionname>alias</functionname></link> > + rule is specifically used to rename a reference to a target and possibly > change the properties. > + > + <!-- You should introduce the alias rule in an earlier > + section, before describing how it applies to this > + specific use-case, and the foregoing sentence should > + go there. --> > > Do you think "alias" deserves a separate section? Possibly, although I have doubts about whether this belongs in the tutorial at all. The tutorial ought to cover what you need to know to get started, but not neccessarily the things you need to know in order to use the system elegantly. This particular point is all about elegance. > + The processing of the <varname><link></varname> feature is > + built in, and is quite complex, but > + <!-- These two points don't make an appropriate "A but B" > + clause, because <link> doesn't allow the system to "do > + different things depending on properties. --> > + there are a couple > + of mechanisms that allow ordinary users to do different things > + depending on properties. > + <!-- They don't _allow users_ to do different things; it's the > + build system that does different things. And "different > + things" is too vague. --> > + </para> > + > + <!-- You could replace the foregoing paragraph with: > + > + "Sometimes, particular relationships need to be maintained > + among a target's build properties. In this section we'll > + discuss two mechanisms for expressing those relationships." > + > + It took me about five minutes to figure out how to say that, > + and it still isn't perfect. But at least it says what we're > + about to talk about with _some_ precision. Saying what you > + mean is hard and requires an investment of effort and > + attention. > + --> > > I think your suggestions is fine. The only problems is that alternatives are not exactly > "relationships among properties", I believe that although they aren't implemented that way, because you have the <source> property, the can thought of as being a relationship among properties. But as I said, I know my wording isn't perfect but I think it's a big improvement. It took me five minutes, so I suggest you take *ten* minutes to try to improve it ;-) > but I can't think of a better wording yet. > > <programlisting> > lib network : network.cpp > - : <link>shared:<define>NEWORK_LIB_SHARED > - <variant>release:<define>EXTRA_FAST > + : <strong><link>shared:<define>NEWORK_LIB_SHARED</strong> > + <strong><variant>release:<define>EXTRA_FAST</strong> > > Why <strong>? To mark up the interesting part of the example? > ; Yes. We did that in the book and it worked really well. Unfortunately the BoostBook toolchain seems to have put the <strong> tags in the HTML output and colored the whole thing red. I just wanted to boldify that text. > <para> > - We've just learned how to use libraries which are created by > - Boost.Build. But some libraries are not. At the same time, those > + We've just learned how to use libraries that are created by > + Boost.Build. But some libraries are not. > + <!-- You can't start a sentence with "But" --> > > A style issue or hard grammar rule? It's a "firm" rule, but not really "hard." ;-) You can do that in informal writing and for artistic effect, but it's probably not appropropriate here. > - <para>More advanced use of prebuilt target is described in <link > - linkend="bbv2.recipies.site-config">a FAQ entry</link>.</para> > + <para>A more advanced use of prebuilt targets is described in <xref > + linkend="bbv2.recipies.site-config"/>. > + > + <!-- "xxx is described in a FAQ entry" is confusing for the person > + who is working with a printed manual. --> > > Do you consider xref generally better than link? Like in TeX, where > most references do not include text? It is better if you're going to make PDFs. You can usually count on it that TeX got the right abstractions for printed output. In fact I have half a mind to make a BoostBook -> LaTeX -> PDF toolchain. We couldn't get XSL:FO to work for the book and as much as I hate LaTeX's quirks and limitations, it really works. > <!-- > Local Variables: > - mode: xml > + mode: nxml > > Hmm... now I need to reconfigure Emacs. Maybe it's good, as PSGML decided it won't auto-complete > element names for me anymore :-( Sorry. I'm using nXML mode and will never look back. PSGML sucked for me. > Now, what shall we do next? I can go ahead and apply edits which you > did not apply, if that won't cause any conflicts with what you're > doing. I'm only moving on to the other .xml files. You should do the work in tutorial and install, and edit out my comments once you've handled them. You have to learn by doing. By the way, thanks for being so receptive to my criticism and teaching. It really makes the effort I invested feel worthwhile! --------------080006070003070306050704--
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