Boost.Build V2/Documentation Todo

Comments from Alo

> Can you suggest the organization that would work better for you?

1. In the beginning of Tutorial, start out with something like is shown on "Project Hiararchies" page - list all files, and their purposes in order to build minimal project; currently the first Hello, world chapter has no mention of project-root.jam, so the reader is unable to create a hello-world sample before he reads 4 more chapters.

2. Moving on from 1., list the purposes and functions different files in the hierarchy have; I'v used BB now for about a week, and I'm still confused between Jamfile, project-root.jam, site-config.jam, user-config.jam and custom .jam files, e.g. what can I do in each of them.

3. Then list target types (exe, lib, more?); the syntax for describing a target includes many fields (4 I think?), separated by :'s; describe each fields purpose, and add a complete list of values that can be placed in each field; for example, SOURCES field can also contain references to libraries, which wasn't intuitive at first.

4. Using the title "pre-built targets" isn't intuitivly refering to external libraries, I would suggest titling it as "Linking against external libraries".

5. Projects, why, how. Personally I'm still confused between project "requirements" and "usage-requirements"; I was unable to specify both. For example, I'm keeping Boost libraries sources in my code tree, so I have something like this: local BOOST_ROOT ; project boost

        : requirements <include>$(BOOST_ROOT)
           <threading>multi <define>BOOST_ALL_DYN_LINK=1
        :

        : $(THREAD_SOURCES).cpp
        : <define>BOOST_THREAD_BUILD_DLL=1
        : : <include>$(BOOST_ROOT) <threading>multi

6. Command-line arguments full reference - currently all command-line arguments are spread across the manual. You go briefly over command-line args in Chapter 23, subsection "Command line" - but how does this fit under "Detailed Rerefence" heading?

  ... Adding custom command-line arguments. Requesting specific compiler 

8. Variables, their usage; local, global variables; accessing variables cross Jamfiles (again from the above example, I'm unable to access BOOST_ROOT variable from anywhere else except the Jamfile that declared it, even with the 'local' keyword dropped from variale declaration).

Concrete actions

- Document 'symlink' - Document --debug-configuration

Installation

/Installation

• It should be clear from the user-config.jam instructions if it's necessary to specify a location explicitly for each tool
• We need a section early on that describes the overall structure and main concepts of Boost.Build. That will help to address troy d. straszheim's sense of being "at sea" with the architecture.
• "CVS state" should be avoided
• We should point that on Windows it's a bad idea to copy anything to the system folders. By default only the system folders are in PATH, so we should recommend a folder structure and give some instructions to change the PATH on Windows.
• Remember that we are dealing with two kinds of people. The first have never used command-line tools.
• We recommend this approach: once you've set up a boost-build.jam file in a parent directory of the one in which you do most of your development, it should almost never be necessary to think about it again, and you won't be cluttering your environment with settings specific to a single tool.
• If a user creates c:\boost_build, puts bjam.exe there and adds c:\boost_build to the path, it will be "cluttering your environment with settings specific to a single tool" too. So we should discourage such policy and recommend to use a common folder like \dev\bin for bjam and other tools like doxygen etc. Consider swapping the two bullets.We can even recommend the environment as a last resort only if it's impossible to use the files.

Hello, World

/HelloWorld

[buy lipitor online] [buy lipitor] [[buy lipitor online]]