Re: [Boost-users] Building Boost question

From: Rene Rivera (grafik.list_at_[hidden])
Date: 2005-07-20 17:15:40

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 <boost\someheader.h> 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