From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 4259 invoked by alias); 30 Dec 2002 12:01:16 -0000 Mailing-List: contact gcc-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Archive: List-Post: List-Help: Sender: gcc-owner@gcc.gnu.org Received: (qmail 4249 invoked from network); 30 Dec 2002 12:01:14 -0000 Received: from unknown (HELO mailout6-0.nyroc.rr.com) (24.92.226.177) by 209.249.29.67 with SMTP; 30 Dec 2002 12:01:14 -0000 Received: from doctormoo (syr-24-24-16-193.twcny.rr.com [24.24.16.193]) by mailout6-0.nyroc.rr.com (8.11.6/RoadRunner 1.20) with ESMTP id gBUC11k17867; Mon, 30 Dec 2002 07:01:01 -0500 (EST) Received: from neroden by doctormoo with local (Exim 3.36 #1 (Debian)) id 18Sya7-0000DU-00; Mon, 30 Dec 2002 06:59:43 -0500 Date: Mon, 30 Dec 2002 07:35:00 -0000 To: gcc@gcc.gnu.org, gdb@sources.redhat.com, binutils@sources.redhat.com Subject: toplevel doc, first draft Message-ID: <20021230115943.GA833@doctormoo> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.4i From: Nathanael Nerode X-SW-Source: 2002-12/txt/msg01570.txt.bz2 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 '-', as above. For build subdirectories, they are of the form '-build-'. So 'make all-build-libiberty' will make the 'build' version of libiberty. For target subdirectories, they are of the form '-target-'. 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.