Edward Diener wrote:

Rene Rivera wrote:

...

Edward Diener wrote:

First off... This documentation is being worked on. Thankfully not by me, as I make a bad documenter in this case since I wrote the install support.

The general install instructions are very good. It is just this area of explaining where everything goes that I find poor, as if it does not matter to the end-user. It does matter since the end-user may well need to know where the build of Boost for a particular compiler ends up putting files.

This applies as a general answer to some things below. Yes, explanations for all this should be added to the documentation. And I'm responding so I, and hopefully the persons updating the docs, can find out what you and other users think should be added :-) Unfortunately I don't have any link I can point to for the documentation rewrite. So I can't head off things that may have already been addressed :-(

...

It's the standard, by autoconf POV, definition, and is the location specified by "--prefix=*" option.

With all due respect to the Unix/Linux autoconf,

I'm not so sure it deserves so much respect ;-) But some people feel differently.

I do not know how it works and I would conjecture that many programmers, especially Windows and Mac programmers, have no idea what it is.

OK, that was a mistake on my part, assuming you had the context of how autoconf installs things. Sorry.

I do not specify a "--prefix=" on the command line. What is the default, and should not this be specified in the doc ?

It is specified in the docs, and when you do "bjam --help". The default values for each option is given. And in the cases where the value differs from Windows to non-Windows two values are show. For example the "--prefix" option says: --prefix=PREFIX Install architecture independent files here. Default; C:\Boost on Win32. Default; /usr/local on Unix. Linux, etc. What it doesn't say clearly is what the install structure is within that target. It does mention the two subdirectories where it installs things in step #4 http://www.boost.org/more/getting_started.html#step4. It's only one sentence though. Which I guess is not enough. One reason I'm a bad documenter in such cases is that I tend to be very terse. And it shows here :-\

...

...

In the 'install' explanation, what does "installs Boost libraries and headers" mean and why do headers need to be installed ?

It mean it will copy the built libraries, and all the headers for all the Boost libraries. Especially important as most of the Boost libraries are header only.

Are you saying that it will copy all the headers for the libraries which are built ?

It will copy *all* the headers, regardless of whether it's a built library or a header only library.

To where does it copy the headers, and to where does it copy the libraries being built when 'install' is specified ?

As it says on that one sentence I point to above: "Within those directories libraries are installed to the "lib" subdirectory, and headers to an "include/boost-1_31" subdirectory, the version will reflect the distribution you are installing." So it makes a "PREFIX/lib" directory to copy the built libraries, *.lib and *.dll files, into.

Why would it copy the headers since the normal way to use Boost headers, whether for a library being built or for a library which is completely header-based, is to specify #include and point to the root directory of the Boost installation as an include path. If it copies the headers somewhere else, then another root directory for the include path must be specified, for built libraries, in front of the root directory for Boost header-only libraries, thus complicating what was previously an easy and effective way of bringing in the correct Boost headers. Why would the system for building boost libraries for a non-header based library ever want to complicate the original way of bringing in Boost header files.

OK, a few questions and answers all in one :-) The old way of installing Boost was to leave it up to the user. This meant that users most likely extract the Boost files to where they wanted them to be. Usually it would mean all the files not just the headers. The "new" way is to extract Boost to a temporary location and build and install for a particular compiler one is using. So some observations: 1) Users are free to ignore the built in build+install process and do it the old way. Strangely, given that I wrote the install support, this is what I do when I use Boost. I also put into into my source control tree which is also common for corporate users. 2) Doing it the new way is meant to support a variety of ways of installing. 2.1) One can do the full install. Which lets one delete the Boost sources which many users don't need as they can read the docs online and only use one compiler. 2.2) One can do the build only and then the install part, copying the files where they are used from, is up to the user. I've seen where this is done to compile the libraries and put the Boost sources and compiled libraries into source control for developers to use. This is what the "stage" option is for. It just builds the libraries and puts them into a single temporary directory where you can then move to someplace else. The idea being that you would then put the Boost sources someplace and delete the temporary tree you used to build. 2.3) Or one can build only if you want to see if things work before going ahead with the "install" or "stage".

...

...

In the 'stage' explanation, what is the "common directory" to which Boost libraries are copied ?

It's the directory specified by "--stagedir=*" option, which defaults to "./stage". I.e. a "stage" directory where you unpacked the Boost sources.

Does this mean that each product gets its own "./stage" subdirectory or they all get a common one ?

Correct me if I'm wrong, but by "each product" you mean each Boost library? Then the answer is _no_. It's a single "./stage" directory. Since you have to invoke the "bjam stage" at the location where you extracted the Boost sources, commonly referred to as boost-root, it would by default be "[boost-root]/stage". So if you expanded to "C:\Stuff\boost-1_32", it would be "C:\Stuff\boost-1_32\stage".

This I begin to understand but this information should be specified in the doc, and it should be specified what the default --stagedir is also at the same time.

It does. Of course we basically know that it doesn't do it clearly enough :-)

...

...

In general where exactly are resulting libraries put for each of these options and are header files moved anywhere also ?

See above :-)

See my further comments and questions.

And to be as clear as possible here's what they do with the defaults, and taking the above extraction location, and doing this on Windows: "bjam install" produces: C:\Boost\lib\*.lib C:\Boost\lib\*.dll C:\Boost\include\boost-1_32\boost\* "bjam stage" produces: C:\Stuff\boost-1_32\stage\lib\*.lib C:\Stuff\boost-1_32\stage\lib\*.dll "bjam" produces: C:\Stuff\boost-1_32\bin\boost\*\*.dll(*.lib) -- And many other files where the subdirectories below "C:\Stuff\boost-1_32\bin\boost" are dependent on the compiler, library, type of library build, etc. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com -- 102708583/icq - grafikrobot/aim - Grafik/jabber.org

Rene Rivera wrote:

...

Edward Diener wrote:

First off... This documentation is being worked on. Thankfully not by me, as I make a bad documenter in this case since I wrote the install support.

The general install instructions are very good. It is just this area of explaining where everything goes that I find poor, as if it does not matter to the end-user. It does matter since the end-user may well need to know where the build of Boost for a particular compiler ends up putting files.

Let me add that I too found the documentation somewhat confusing. I am a Windows guy without any experience on Linux/Unix whatsoever so this could explain something. I wanted to build boost for Visual C++ 8.0 which is not by default supported (according to documentation - i found the name after a long search in the boost libraries). After the name was found, the build succeeded but not without lots of warnings (mostly about deprecated compiler options, if i remember correctly). It would be nice if the location of the compiler configuration files were mentioned and there for each configuration was an explanation as to any options that should not be used and the rationale for that (if any). Another minor point is that boost ended with an empty file called set, located in the path I gave to the compiler. When I later did a "complete" build you can guess what happened to every sourcefile that used std::set ;-). I must admit that i did not realise what happened and reinstalled my VC 8 before i discovered my bug ;-) This might sound as if Im dissatisfied with the documentation in general: this is not the case, however. Generally it is very good - also the part describing the installation.

...

[snip] /Peter