This is the mail archive of the gdb@sources.redhat.com mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

toplevel doc, first draft


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.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]