Re: toplevel doc, first draft

Re: toplevel doc, first draft

[Michael Elizabeth Chastain]

There is a list of standard targets in "info make", node
"standard targets for users".

I think it would be fine to say: "the standard targets (all, install,
info, et cetera)" as documented in 'info make', node 'standard targets
for users'".  People are very inductive and love examples, and then
you can point to an authoritative list.

I read all the notes.  They struck me as great notes that need preservation,
but they could use more narrative to tie them all together.  But as long
as they are accurate then any docs are fine with me.  My two cents.

Michael C

Re: toplevel doc, first draft

[Ranjit Mathew]

Michael Elizabeth Chastain wrote:
> I read all the notes.  They struck me as great notes that need preservation,
> but they could use more narrative to tie them all together.  But as long
> as they are accurate then any docs are fine with me.  My two cents.

Forgive me if this is a FAQ, but some times great information
is posted to this list that one can not find even in the
official "GCC Internals" documentation. The root post for
this message is an example as is this great "[DWARF2] EH
newbies howto" posted by Aldy Hernandez:

http://gcc.gnu.org/ml/gcc/2002-07/msg00391.html

These notes are a great help for newbies like yours truly
to understand what is going on in GCC.

Does someone maintain a list of such insightful postings
that have not made to the "official" documentation? If nothing,
can these design notes not be added to the "GCC Specific
Literature" section of the "Further Readings" page on the
GCC web site?

Sincerely Yours,
Ranjit.

-- 
Ranjit Mathew          Email: rmathew AT hotmail DOT com

Bangalore, INDIA.      Web: http://ranjitmathew.tripod.com/

Re: toplevel doc, first draft

[Joseph S. Myers]

On Mon, 30 Dec 2002, Phil Edwards wrote:

> On Mon, Dec 30, 2002 at 06:59:43AM -0500, Nathanael Nerode wrote:
> > And information on where to put the
> > documentation when it's ready is always welcome; etc/configure.texi is soooo
> > out-of-date I don't know what to make of it.
> 
> We still have an etc directory?  I thought it was killed a while ago.

This is etc in the src repository.

At least the documentation there for multilibs in target libraries may
still be relevant (but that file would need to be assigned to the FSF);  
certainly those interfaces were not covered in the documentation just
posted.

-- 
Joseph S. Myers
jsm28@cam.ac.uk

Re: toplevel doc, first draft

[Phil Edwards]

On Mon, Dec 30, 2002 at 06:59:43AM -0500, Nathanael Nerode wrote:
> And information on where to put the
> documentation when it's ready is always welcome; etc/configure.texi is soooo
> out-of-date I don't know what to make of it.

We still have an etc directory?  I thought it was killed a while ago.


> The Makefile for a subdirectory is expected to provide the usual public 
> targets: all, install, info, etc.  

I think there's an official recommended list somewhere in the pesky GNU
Coding Standards[tm].


Phil

-- 
I would therefore like to posit that computing's central challenge, viz. "How
not to make a mess of it," has /not/ been met.
                                                 - Edsger Dijkstra, 1930-2002

toplevel doc, first draft

[Nathanael Nerode]

The following is a first draft of rough documentation for the top level
build system.  Improvements and feedback welcome.  Texification welcome too,
since I don't do much texinfo. :-)  And information on where to put the
documentation when it's ready is always welcome; etc/configure.texi is soooo
out-of-date I don't know what to make of it.

I'm working on this out of a sense of responsibility ("never write code 
without documenting it"), but I'd be happy to have the work taken from me. :-)

--Nathanael

--
GCC, GDB, GNU binutils, and several other projects use a unified top level
configure/build system.  This document attempts to describe it.

Subdirectories:
Each project or subproject has its own subdirectory; there is a gdb 
subdirectory, a gcc subdirectory, a libstdc++-v3 subdirectory, etc.  

Each subdirectory contains a 'configure' script of its own, which generates
a Makefile of its own.  These are generated and managed in the usual ways; 
the top level doesn't really care.

Subdirectories themselves fall into three categories:
* Those which create programs to run on the build machine.
* Those which create programs to run on the host machine (the usual case).
* Those which create programs to run on the target machine (mostly runtime
libraries).

(GCC is theoretically a host subdir, but in fact is a special case, since it 
does some of each.)

Some directories, such as libiberty, are built multiple times, in a 
'build version', 'host version', and 'target version'.

The Makefile for a subdirectory is expected to provide the usual public 
targets: all, install, info, etc.  

Glue targets:
The top level Makefile contains a large number of targets which hook into 
the corresponding targets in a subdirectory.  For instance, 'make all-gcc' 
runs 'make all' in the 'gcc' subdirectory.  

The top level Makefile also contains targets for configuring the 
subdirectories; for instance, 'make configure-gdb' runs 'configure' in the 
gdb subdirectory.

These 'glue targets' provide the primary mechanism for well-behaved recursion 
into subdirectories.  They can also be used directly. if you only want to
reconfigure libjava, you can run 'make configure-target-libjava'.

For host subdirectories, the top level Make targets follow the form 
'<action>-<subdir>', as above.  

For build subdirectories, they are of the form '<action>-build-<subdir>'.  So
'make all-build-libiberty' will make the 'build' version of libiberty.

For target subdirectories, they are of the form '<action>-target-<subdir>'.
So 'make all-target-libjava' will make 'libjava' (a target subdir), and
'make install-target-libjava' will install it.

The top level Makefile knows what order the subdirectories need to be
configured and built in, and will (theoretically) handle this transparently.
It's also smart enough to pass down the correct arguments to build and target
subdirs (thanks to top level configure).  And it knows that you have to 
configure a subdirectory before building it.  

For these reasons, it's generally preferable to use the glue targets
rather than manually running 'make' in the subdirectories.

Standard targets:
The standard targets at the top level recurse into all configured 
subdirectories.  So the 'all' target at the top level depends on all of 
the 'all-*' targets for subdirectories (build, host, and target).  Similarly
for the 'install' target, and all of the usual standard public targets.

The top level is clever enough that 'configure; make' will generally configure
and make all the appropriate subdirectories in the appropriate order.

Special targets:
'configure-host' causes all the host subdirectories to be configured.
'all-host' causes all the host subdirectories to be built.

'configure-target' causes all the target subdirectories to be configured.
'all-target' causes all the target subdirectories to be built.

'bootstrap' performs the corresponding target in the 'gcc' 
subdirectory, and then 'make all'.  The related bootstrap targets act
similarly.

Top level configure:
Top level configure is generated by autoconf from configure.in.

It mostly has the job of determining which subdirectories
should be configured and built.  This varies according to the host and target.
It also varies depending on which subdirectories are actually present in the
source tree, so that it works properly with all known distributions of each
project, and with both master CVS trees.  This logic comprises most of the code
in the top level configure.in.

If you add a new subdirectory to the tree, you need to add it
to one of the lists at the top of configure.in, as well as to one of the lists
in Makefile.def.

Top level configure also determines the values of some tools, which is done 
in a more typical autoconf manner; this uses auxilliary macros in config/acx.m4.

Makefile.tpl and Makefile.def:
The huge mass of repetitious targets ('all-gcc','all-gdb','install-gcc',
'install-gdb', etc.) is far too tedious to write by hand.  Accordingly,
Makefile.in is generated from 'Makefile.tpl' and 'Makefile.def' by the
'autogen' utility.

Makefile.tpl looks like an ordinary Makefile.in, and can be treated as such,
except for the autogen macro directives enclosed in [+ +] delimeters.  The
one used the most is FOR, to make substantially identical targets with
different subdirectories plugged in.  This could be done with Make macros,
but it would be a lot slower and even less readable.

Makefile.def contains lists of build modules, host modules, and target modules.
If you're adding a new subdirectory to the tree, add it here, in whichever
list is appropriate, as well as adding it to the lists in configure.in.