X-Git-Url: https://oss.titaniummirror.com/gitweb?a=blobdiff_plain;f=gcc%2Fdoc%2Fgccint.info-1;fp=gcc%2Fdoc%2Fgccint.info-1;h=0000000000000000000000000000000000000000;hb=6fed43773c9b0ce596dca5686f37ac3fc0fa11c0;hp=1729a7c6d45b00606d169f37a5b991e7d4addf6b;hpb=27b11d56b743098deb193d510b337ba22dc52e5c;p=msp430-gcc.git diff --git a/gcc/doc/gccint.info-1 b/gcc/doc/gccint.info-1 deleted file mode 100644 index 1729a7c6..00000000 --- a/gcc/doc/gccint.info-1 +++ /dev/null @@ -1,1187 +0,0 @@ -This is doc/gccint.info, produced by makeinfo version 4.5 from -doc/gccint.texi. - -INFO-DIR-SECTION Programming -START-INFO-DIR-ENTRY -* gccint: (gccint). Internals of the GNU Compiler Collection. -END-INFO-DIR-ENTRY - This file documents the internals of the GNU compilers. - - Published by the Free Software Foundation -59 Temple Place - Suite 330 -Boston, MA 02111-1307 USA - - Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -1999, 2000, 2001, 2002 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with the -Invariant Sections being "GNU General Public License" and "Funding Free -Software", the Front-Cover texts being (a) (see below), and with the -Back-Cover Texts being (b) (see below). A copy of the license is -included in the section entitled "GNU Free Documentation License". - - (a) The FSF's Front-Cover Text is: - - A GNU Manual - - (b) The FSF's Back-Cover Text is: - - You have freedom to copy and modify this GNU Manual, like GNU -software. Copies published by the Free Software Foundation raise -funds for GNU development. - - -File: gccint.info, Node: Top, Next: Contributing, Up: (DIR) - -Introduction -************ - - This manual documents the internals of the GNU compilers, including -how to port them to new targets and some information about how to write -front ends for new languages. It corresponds to GCC version 3.2.3. -The use of the GNU compilers is documented in a separate manual. *Note -Introduction: (gcc)Top. - - This manual is mainly a reference manual rather than a tutorial. It -discusses how to contribute to GCC (*note Contributing::), the -characteristics of the machines supported by GCC as hosts and targets -(*note Portability::), how GCC relates to the ABIs on such systems -(*note Interface::), and the characteristics of the languages for which -GCC front ends are written (*note Languages::). It then describes the -GCC source tree structure and build system, some of the interfaces to -GCC front ends, and how support for a target system is implemented in -GCC. - - Additional tutorial information is linked to from -`http://gcc.gnu.org/readings.html'. - -* Menu: - -* Contributing:: How to contribute to testing and developing GCC. -* Portability:: Goals of GCC's portability features. -* Interface:: Function-call interface of GCC output. -* Languages:: Languages for which GCC front ends are written. -* Source Tree:: GCC source tree structure and build system. -* Passes:: Order of passes, what they do, and what each file is for. -* Trees:: The source representation used by the C and C++ front ends. -* RTL:: The intermediate representation that most passes work on. -* Machine Desc:: How to write machine description instruction patterns. -* Target Macros:: How to write the machine description C macros and functions. -* Host Config:: Writing the `xm-MACHINE.h' file. -* Fragments:: Writing the `t-TARGET' and `x-HOST' files. -* Collect2:: How `collect2' works; how it finds `ld'. -* Header Dirs:: Understanding the standard header file directories. - -* Funding:: How to help assure funding for free software. -* GNU Project:: The GNU Project and GNU/Linux. - -* Copying:: GNU General Public License says - how you can copy and share GCC. -* GNU Free Documentation License:: How you can copy and share this manual. -* Contributors:: People who have contributed to GCC. - -* Option Index:: Index to command line options. -* Index:: Index of concepts and symbol names. - - -File: gccint.info, Node: Contributing, Next: Portability, Prev: Top, Up: Top - -Contributing to GCC Development -******************************* - - If you would like to help pretest GCC releases to assure they work -well, our current development sources are available by CVS (see -`http://gcc.gnu.org/cvs.html'). Source and binary snapshots are also -available for FTP; see `http://gcc.gnu.org/snapshots.html'. - - If you would like to work on improvements to GCC, please read the -advice at these URLs: - - `http://gcc.gnu.org/contribute.html' - `http://gcc.gnu.org/contributewhy.html' - -for information on how to make useful contributions and avoid -duplication of effort. Suggested projects are listed at -`http://gcc.gnu.org/projects/'. - - -File: gccint.info, Node: Portability, Next: Interface, Prev: Contributing, Up: Top - -GCC and Portability -******************* - - The main goal of GCC was to make a good, fast compiler for machines -in the class that the GNU system aims to run on: 32-bit machines that -address 8-bit bytes and have several general registers. Elegance, -theoretical power and simplicity are only secondary. - - GCC gets most of the information about the target machine from a -machine description which gives an algebraic formula for each of the -machine's instructions. This is a very clean way to describe the -target. But when the compiler needs information that is difficult to -express in this fashion, I have not hesitated to define an ad-hoc -parameter to the machine description. The purpose of portability is to -reduce the total work needed on the compiler; it was not of interest -for its own sake. - - GCC does not contain machine dependent code, but it does contain code -that depends on machine parameters such as endianness (whether the most -significant byte has the highest or lowest address of the bytes in a -word) and the availability of autoincrement addressing. In the -RTL-generation pass, it is often necessary to have multiple strategies -for generating code for a particular kind of syntax tree, strategies -that are usable for different combinations of parameters. Often I have -not tried to address all possible cases, but only the common ones or -only the ones that I have encountered. As a result, a new target may -require additional strategies. You will know if this happens because -the compiler will call `abort'. Fortunately, the new strategies can be -added in a machine-independent fashion, and will affect only the target -machines that need them. - - -File: gccint.info, Node: Interface, Next: Languages, Prev: Portability, Up: Top - -Interfacing to GCC Output -************************* - - GCC is normally configured to use the same function calling -convention normally in use on the target system. This is done with the -machine-description macros described (*note Target Macros::). - - However, returning of structure and union values is done differently -on some target machines. As a result, functions compiled with PCC -returning such types cannot be called from code compiled with GCC, and -vice versa. This does not cause trouble often because few Unix library -routines return structures or unions. - - GCC code returns structures and unions that are 1, 2, 4 or 8 bytes -long in the same registers used for `int' or `double' return values. -(GCC typically allocates variables of such types in registers also.) -Structures and unions of other sizes are returned by storing them into -an address passed by the caller (usually in a register). The -machine-description macros `STRUCT_VALUE' and `STRUCT_INCOMING_VALUE' -tell GCC where to pass this address. - - By contrast, PCC on most target machines returns structures and -unions of any size by copying the data into an area of static storage, -and then returning the address of that storage as if it were a pointer -value. The caller must copy the data from that memory area to the -place where the value is wanted. This is slower than the method used -by GCC, and fails to be reentrant. - - On some target machines, such as RISC machines and the 80386, the -standard system convention is to pass to the subroutine the address of -where to return the value. On these machines, GCC has been configured -to be compatible with the standard compiler, when this method is used. -It may not be compatible for structures of 1, 2, 4 or 8 bytes. - - GCC uses the system's standard convention for passing arguments. On -some machines, the first few arguments are passed in registers; in -others, all are passed on the stack. It would be possible to use -registers for argument passing on any machine, and this would probably -result in a significant speedup. But the result would be complete -incompatibility with code that follows the standard convention. So this -change is practical only if you are switching to GCC as the sole C -compiler for the system. We may implement register argument passing on -certain machines once we have a complete GNU system so that we can -compile the libraries with GCC. - - On some machines (particularly the Sparc), certain types of arguments -are passed "by invisible reference". This means that the value is -stored in memory, and the address of the memory location is passed to -the subroutine. - - If you use `longjmp', beware of automatic variables. ISO C says that -automatic variables that are not declared `volatile' have undefined -values after a `longjmp'. And this is all GCC promises to do, because -it is very difficult to restore register variables correctly, and one -of GCC's features is that it can put variables in registers without -your asking it to. - - If you want a variable to be unaltered by `longjmp', and you don't -want to write `volatile' because old C compilers don't accept it, just -take the address of the variable. If a variable's address is ever -taken, even if just to compute it and ignore it, then the variable -cannot go in a register: - - { - int careful; - &careful; - ... - } - - Code compiled with GCC may call certain library routines. Most of -them handle arithmetic for which there are no instructions. This -includes multiply and divide on some machines, and floating point -operations on any machine for which floating point support is disabled -with `-msoft-float'. Some standard parts of the C library, such as -`bcopy' or `memcpy', are also called automatically. The usual function -call interface is used for calling the library routines. - - Some of these routines can be defined in mostly machine-independent -C; they appear in `libgcc2.c'. Others must be hand-written in assembly -language for each processor. Wherever they are defined, they are -compiled into the support library, `libgcc.a', which is automatically -searched when you link programs with GCC. - - -File: gccint.info, Node: Languages, Next: Source Tree, Prev: Interface, Up: Top - -Language Front Ends in GCC -************************** - - The interface to front ends for languages in GCC, and in particular -the `tree' structure (*note Trees::), was initially designed for C, and -many aspects of it are still somewhat biased towards C and C-like -languages. It is, however, reasonably well suited to other procedural -languages, and front ends for many such languages have been written for -GCC. - - Writing a compiler as a front end for GCC, rather than compiling -directly to assembler or generating C code which is then compiled by -GCC, has several advantages: - - * GCC front ends benefit from the support for many different target - machines already present in GCC. - - * GCC front ends benefit from all the optimizations in GCC. Some of - these, such as alias analysis, may work better when GCC is - compiling directly from source code then when it is compiling from - generated C code. - - * Better debugging information is generated when compiling directly - from source code than when going via intermediate generated C code. - - Because of the advantages of writing a compiler as a GCC front end, -GCC front ends have also been created for languages very different from -those for which GCC was designed, such as the declarative -logic/functional language Mercury. For these reasons, it may also be -useful to implement compilers created for specialized purposes (for -example, as part of a research project) as GCC front ends. - - -File: gccint.info, Node: Source Tree, Next: Passes, Prev: Languages, Up: Top - -Source Tree Structure and Build System -************************************** - - This chapter describes the structure of the GCC source tree, and how -GCC is built. The user documentation for building and installing GCC -is in a separate manual (`http://gcc.gnu.org/install/'), with which it -is presumed that you are familiar. - -* Menu: - -* Configure Terms:: Configuration terminology and history. -* Top Level:: The top level source directory. -* gcc Directory:: The `gcc' subdirectory. -* Test Suites:: The GCC test suites. - - -File: gccint.info, Node: Configure Terms, Next: Top Level, Up: Source Tree - -Configure Terms and History -=========================== - - The configure and build process has a long and colorful history, and -can be confusing to anyone who doesn't know why things are the way they -are. While there are other documents which describe the configuration -process in detail, here are a few things that everyone working on GCC -should know. - - There are three system names that the build knows about: the machine -you are building on ("build"), the machine that you are building for -("host"), and the machine that GCC will produce code for ("target"). -When you configure GCC, you specify these with `--build=', `--host=', -and `--target='. - - Specifying the host without specifying the build should be avoided, -as `configure' may (and once did) assume that the host you specify is -also the build, which may not be true. - - If build, host, and target are all the same, this is called a -"native". If build and host are the same but target is different, this -is called a "cross". If build, host, and target are all different this -is called a "canadian" (for obscure reasons dealing with Canada's -political party and the background of the person working on the build -at that time). If host and target are the same, but build is -different, you are using a cross-compiler to build a native for a -different system. Some people call this a "host-x-host", "crossed -native", or "cross-built native". If build and target are the same, -but host is different, you are using a cross compiler to build a cross -compiler that produces code for the machine you're building on. This -is rare, so there is no common way of describing it (although I propose -calling it a "crossback"). - - If build and host are the same, the GCC you are building will also be -used to build the target libraries (like `libstdc++'). If build and -host are different, you must have already build and installed a cross -compiler that will be used to build the target libraries (if you -configured with `--target=foo-bar', this compiler will be called -`foo-bar-gcc'). - - In the case of target libraries, the machine you're building for is -the machine you specified with `--target'. So, build is the machine -you're building on (no change there), host is the machine you're -building for (the target libraries are built for the target, so host is -the target you specified), and target doesn't apply (because you're not -building a compiler, you're building libraries). The configure/make -process will adjust these variables as needed. It also sets -`$with_cross_host' to the original `--host' value in case you need it. - - The `libiberty' support library is built up to three times: once for -the host, once for the target (even if they are the same), and once for -the build if build and host are different. This allows it to be used -by all programs which are generated in the course of the build process. - - -File: gccint.info, Node: Top Level, Next: gcc Directory, Prev: Configure Terms, Up: Source Tree - -Top Level Source Directory -========================== - - The top level source directory in a GCC distribution contains several -files and directories that are shared with other software distributions -such as that of GNU Binutils. It also contains several subdirectories -that contain parts of GCC and its runtime libraries: - -`boehm-gc' - The Boehm conservative garbage collector, used as part of the Java - runtime library. - -`contrib' - Contributed scripts that may be found useful in conjunction with - GCC. One of these, `contrib/texi2pod.pl', is used to generate man - pages from Texinfo manuals as part of the GCC build process. - -`fastjar' - An implementation of the `jar' command, used with the Java front - end. - -`gcc' - The main sources of GCC itself (except for runtime libraries), - including optimizers, support for different target architectures, - language front ends, and test suites. *Note The `gcc' - Subdirectory: gcc Directory, for details. - -`include' - Headers for the `libiberty' library. - -`libf2c' - The Fortran runtime library. - -`libffi' - The `libffi' library, used as part of the Java runtime library. - -`libiberty' - The `libiberty' library, used for portability and for some - generally useful data structures and algorithms. *Note - Introduction: (libiberty)Top, for more information about this - library. - -`libjava' - The Java runtime library. - -`libobjc' - The Objective-C runtime library. - -`libstdc++-v3' - The C++ runtime library. - -`maintainer-scripts' - Scripts used by the `gccadmin' account on `gcc.gnu.org'. - -`zlib' - The `zlib' compression library, used by the Java front end and as - part of the Java runtime library. - - The build system in the top level directory, including how recursion -into subdirectories works and how building runtime libraries for -multilibs is handled, is documented in a separate manual, included with -GNU Binutils. *Note GNU configure and build system: (configure)Top, -for details. - - -File: gccint.info, Node: gcc Directory, Next: Test Suites, Prev: Top Level, Up: Source Tree - -The `gcc' Subdirectory -====================== - - The `gcc' directory contains many files that are part of the C -sources of GCC, other files used as part of the configuration and build -process, and subdirectories including documentation and a test suite. -The files that are sources of GCC are documented in a separate chapter. -*Note Passes and Files of the Compiler: Passes. - -* Menu: - -* Subdirectories:: Subdirectories of `gcc'. -* Configuration:: The configuration process, and the files it uses. -* Build:: The build system in the `gcc' directory. -* Makefile:: Targets in `gcc/Makefile'. -* Library Files:: Library source files and headers under `gcc/'. -* Headers:: Headers installed by GCC. -* Documentation:: Building documentation in GCC. -* Front End:: Anatomy of a language front end. -* Back End:: Anatomy of a target back end. - - -File: gccint.info, Node: Subdirectories, Next: Configuration, Up: gcc Directory - -Subdirectories of `gcc' ------------------------ - - The `gcc' directory contains the following subdirectories: - -`LANGUAGE' - Subdirectories for various languages. Directories containing a - file `config-lang.in' are language subdirectories. The contents of - the subdirectories `cp' (for C++) and `objc' (for Objective-C) are - documented in this manual (*note Passes and Files of the Compiler: - Passes.); those for other languages are not. *Note Anatomy of a - Language Front End: Front End, for details of the files in these - directories. - -`config' - Configuration files for supported architectures and operating - systems. *Note Anatomy of a Target Back End: Back End, for - details of the files in thie directory. - -`doc' - Texinfo documentation for GCC, together with automatically - generated man pages and support for converting the installation - manual to HTML. *Note Documentation::. - -`fixinc' - The support for fixing system headers to work with GCC. See - `fixinc/README' for more information. The headers fixed by this - mechanism are installed in `LIBSUBDIR/include'. Along with those - headers, `README-fixinc' is also installed, as - `LIBSUBDIR/include/README'. - -`ginclude' - System headers installed by GCC, mainly those required by the C - standard of freestanding implementations. *Note Headers Installed - by GCC: Headers, for details of when these and other headers are - installed. - -`intl' - GNU `libintl', from GNU `gettext', for systems which do not - include it in libc. Properly, this directory should be at top - level, parallel to the `gcc' directory. - -`po' - Message catalogs with translations of messages produced by GCC into - various languages, `LANGUAGE.po'. This directory also contains - `gcc.pot', the template for these message catalogues, `exgettext', - a wrapper around `gettext' to extract the messages from the GCC - sources and create `gcc.pot', which is run by `make gcc.pot', and - `EXCLUDES', a list of files from which messages should not be - extracted. - -`testsuite' - The GCC test suites (except for those for runtime libraries). - *Note Test Suites::. - - -File: gccint.info, Node: Configuration, Next: Build, Prev: Subdirectories, Up: gcc Directory - -Configuration in the `gcc' Directory ------------------------------------- - - The `gcc' directory is configured with an Autoconf-generated script -`configure'. The `configure' script is generated from `configure.in' -and `aclocal.m4'. From the files `configure.in' and `acconfig.h', -Autoheader generates the file `config.in'. The file `cstamp-h.in' is -used as a timestamp. - -* Menu: - -* Config Fragments:: Scripts used by `configure'. -* System Config:: The `config.gcc' file. -* Configuration Files:: Files created by running `configure'. - - -File: gccint.info, Node: Config Fragments, Next: System Config, Up: Configuration - -Scripts Used by `configure' -........................... - - `configure' uses some other scripts to help in its work: - - * The standard GNU `config.sub' and `config.guess' files, kept in - the top level directory, are used. FIXME: when is the - `config.guess' file in the `gcc' directory (that just calls the - top level one) used? - - * The file `config.gcc' is used to handle configuration specific to - the particular build, host or target machine. (In general, this - should only be used for features that cannot reasonably be tested - in Autoconf feature tests.) *Note The `config.gcc' File: System - Config, for details of the contents of this file. - - * Each language subdirectory has a file `LANGUAGE/config-lang.in' - that is used for front-end-specific configuration. *Note The - Front End `config-lang.in' File: Front End Config, for details of - this file. - - * A helper script `configure.frag' is used as part of creating the - output of `configure'. - - -File: gccint.info, Node: System Config, Next: Configuration Files, Prev: Config Fragments, Up: Configuration - -The `config.gcc' File -..................... - - FIXME: document the contents of this file, and what variables should -be set to control build, host and target configuration. - - -File: gccint.info, Node: Configuration Files, Prev: System Config, Up: Configuration - -Files Created by `configure' -............................ - - Here we spell out what files will be set up by `configure' in the -`gcc' directory. Some other files are created as temporary files in -the configuration process, and are not used in the subsequent build; -these are not documented. - - * `Makefile' is constructed from `Makefile.in', together with the - host and target fragments (*note Makefile Fragments: Fragments.) - `t-TARGET' and `x-HOST' from `config', if any, and language - Makefile fragments `LANGUAGE/Make-lang.in'. - - * `auto-host.h' contains information about the host machine - determined by `configure'. If the host machine is different from - the build machine, then `auto-build.h' is also created, containing - such information about the build machine. - - * `config.status' is a script that may be run to recreate the - current configuration. - - * `configargs.h' is a header containing details of the arguments - passed to `configure' to configure GCC, and of the thread model - used. - - * `cstamp-h' is used as a timestamp. - - * `fixinc/Makefile' is constructed from `fixinc/Makefile.in'. - - * `gccbug', a script for reporting bugs in GCC, is constructed from - `gccbug.in'. - - * `intl/Makefile' is constructed from `intl/Makefile.in'. - - * `mklibgcc', a shell script to create a Makefile to build libgcc, - is constructed from `mklibgcc.in'. - - * If a language `config-lang.in' file (*note The Front End - `config-lang.in' File: Front End Config.) sets `outputs', then the - files listed in `outputs' there are also generated. - - The following configuration headers are created from the Makefile, -using `mkconfig.sh', rather than directly by `configure'. `config.h', -`hconfig.h' and `tconfig.h' all contain the `xm-MACHINE.h' header, if -any, appropriate to the host, build and target machines respectively, -the configuration headers for the target, and some definitions; for the -host and build machines, these include the autoconfigured headers -generated by `configure'. The other configuration headers are -determined by `config.gcc'. They also contain the typedefs for `rtx', -`rtvec' and `tree'. - - * `config.h', for use in programs that run on the host machine. - - * `hconfig.h', for use in programs that run on the build machine. - - * `tconfig.h', for use in programs and libraries for the target - machine. - - * `tm_p.h', which includes the header `MACHINE-protos.h' that - contains prototypes for functions in the target `.c' file. FIXME: - why is such a separate header necessary? - - -File: gccint.info, Node: Build, Next: Makefile, Prev: Configuration, Up: gcc Directory - -Build System in the `gcc' Directory ------------------------------------ - - FIXME: describe the build system, including what is built in what -stages. Also list the various source files that are used in the build -process but aren't source files of GCC itself and so aren't documented -below (*note Passes::). - - -File: gccint.info, Node: Makefile, Next: Library Files, Prev: Build, Up: gcc Directory - -Makefile Targets ----------------- - -`all' - This is the default target. Depending on what your - build/host/target configuration is, it coordinates all the things - that need to be built. - -`doc' - Produce info-formatted documentation. Also, `make dvi' is - available for DVI-formatted documentation, and `make - generated-manpages' to generate man pages. - -`mostlyclean' - Delete the files made while building the compiler. - -`clean' - That, and all the other files built by `make all'. - -`distclean' - That, and all the files created by `configure'. - -`extraclean' - That, and any temporary or intermediate files, like emacs backup - files. - -`maintainer-clean' - Distclean plus any file that can be generated from other files. - Note that additional tools may be required beyond what is normally - needed to build gcc. - -`install' - Installs gcc. - -`uninstall' - Deletes installed files. - -`check' - Run the testsuite. This creates a `testsuite' subdirectory that - has various `.sum' and `.log' files containing the results of the - testing. You can run subsets with, for example, `make check-gcc'. - You can specify specific tests by setting RUNTESTFLAGS to be the - name of the `.exp' file, optionally followed by (for some tests) - an equals and a file wildcard, like: - - make check-gcc RUNTESTFLAGS="execute.exp=19980413-*" - - Note that running the testsuite may require additional tools be - installed, such as TCL or dejagnu. - -`bootstrap' - Builds gcc three times--once with the native compiler, once with - the native-built compiler it just built, and once with the - compiler it built the second time. In theory, the last two should - produce the same results, which `make compare' can check. Each - step of this process is called a "stage", and the results of each - stage N (N = 1...3) are copied to a subdirectory `stageN/'. - -`bootstrap-lean' - Like `bootstrap', except that the various stages are removed once - they're no longer needed. This saves disk space. - -`bubblestrap' - Once bootstrapped, this incrementally rebuilds each of the three - stages, one at a time. It does this by "bubbling" the stages up - from their subdirectories, rebuilding them, and copying them back - to their subdirectories. This will allow you to, for example, - quickly rebuild a bootstrapped compiler after changing the - sources, without having to do a full bootstrap. - -`quickstrap' - Rebuilds the most recently built stage. Since each stage requires - special invocation, using this target means you don't have to keep - track of which stage you're on or what invocation that stage needs. - -`cleanstrap' - Removed everything (`make clean') and rebuilds (`make bootstrap'). - -`stageN (N = 1...4)' - For each stage, moves the appropriate files to the `stageN' - subdirectory. - -`unstageN (N = 1...4)' - Undoes the corresponding `stageN'. - -`restageN (N = 1...4)' - Undoes the corresponding `stageN' and rebuilds it with the - appropriate flags. - -`compare' - Compares the results of stages 2 and 3. This ensures that the - compiler is running properly, since it should produce the same - object files regardless of how it itself was compiled. - - - -File: gccint.info, Node: Library Files, Next: Headers, Prev: Makefile, Up: gcc Directory - -Library Source Files and Headers under the `gcc' Directory ----------------------------------------------------------- - - FIXME: list here, with explanation, all the C source files and -headers under the `gcc' directory that aren't built into the GCC -executable but rather are part of runtime libraries and object files, -such as `crtstuff.c' and `unwind-dw2.c'. *Note Headers Installed by -GCC: Headers, for more information about the `ginclude' directory. - - -File: gccint.info, Node: Headers, Next: Documentation, Prev: Library Files, Up: gcc Directory - -Headers Installed by GCC ------------------------- - - In general, GCC expects the system C library to provide most of the -headers to be used with it. However, GCC will fix those headers if -necessary to make them work with GCC, and will install some headers -required of freestanding implementations. These headers are installed -in `LIBSUBDIR/include'. Headers for non-C runtime libraries are also -installed by GCC; these are not documented here. (FIXME: document them -somewhere.) - - Several of the headers GCC installs are in the `ginclude' directory. -These headers, `iso646.h', `stdarg.h', `stdbool.h', `stddef.h' and -`varargs.h', are installed in `LIBSUBDIR/include', unless the target -Makefile fragment (*note Target Fragment::) overrides this by setting -`USER_H'. - - In addition to these headers and those generated by fixing system -headers to work with GCC, some other headers may also be installed in -`LIBSUBDIR/include'. `config.gcc' may set `extra_headers'; this -specifies additional headers under `config' to be installed on some -systems. GCC normally installs a `' file; these are kept as -`config/float-FORMAT.h', where FORMAT is specified by a `float_format' -setting in `config.gcc', and a setting `float_format=none' disables -installation of this header. GCC also installs its own version of -`'; this is generated from `glimits.h', together with -`limitx.h' and `limity.h' if the system also has its own version of -`'. (GCC provides its own header because it is required of -ISO C freestanding implementations, but needs to include the system -header from its own header as well because other standards such as -POSIX specify additional values to be defined in `'.) The -system's `' header is used via -`LIBSUBDIR/include/syslimits.h', which is copied from `gsyslimits.h' if -it does not need fixing to work with GCC; if it needs fixing, -`syslimits.h' is the fixed copy. - - -File: gccint.info, Node: Documentation, Next: Front End, Prev: Headers, Up: gcc Directory - -Building Documentation ----------------------- - - The main GCC documentation is in the form of manuals in Texinfo -format. These are installed in Info format, and DVI versions may be -generated by `make dvi'. In addition, some man pages are generated -from the Texinfo manuals, there are some other text files with -miscellaneous documentation, and runtime libraries have their own -documentation outside the `gcc' directory. FIXME: document the -documentation for runtime libraries somewhere. - -* Menu: - -* Texinfo Manuals:: GCC manuals in Texinfo format. -* Man Page Generation:: Generating man pages from Texinfo manuals. -* Miscellaneous Docs:: Miscellaneous text files with documentation. - - -File: gccint.info, Node: Texinfo Manuals, Next: Man Page Generation, Up: Documentation - -Texinfo Manuals -............... - - The manuals for GCC as a whole, and the C and C++ front ends, are in -files `doc/*.texi'. Other front ends have their own manuals in files -`LANGUAGE/*.texi'. Common files `doc/include/*.texi' are provided -which may be included in multiple manuals; the following files are in -`doc/include': - -`fdl.texi' - The GNU Free Documentation License. - -`funding.texi' - The section "Funding Free Software". - -`gcc-common.texi' - Common definitions for manuals. - -`gpl.texi' - The GNU General Public License. - -`texinfo.tex' - A copy of `texinfo.tex' known to work with the GCC manuals. - - DVI formatted manuals are generated by `make dvi', which uses -`texi2dvi' (via the Makefile macro `$(TEXI2DVI)'). Info manuals are -generated by `make info' (which is run as part of a bootstrap); this -generates the manuals in the source directory, using `makeinfo' via the -Makefile macro `$(MAKEINFO)', and they are included in release -distributions. - - Manuals are also provided on the GCC web site, in both HTML and -PostScript forms. This is done via the script -`maintainer-scripts/update_web_docs'. Each manual to be provided -online must be listed in the definition of `MANUALS' in that file; a -file `NAME.texi' must only appear once in the source tree, and the -output manual must have the same name as the source file. (However, -other Texinfo files, included in manuals but not themselves the root -files of manuals, may have names that appear more than once in the -source tree.) The manual file `NAME.texi' should only include other -files in its own directory or in `doc/include'. HTML manuals will be -generated by `makeinfo --html' and PostScript manuals by `texi2dvi' and -`dvips'. All Texinfo files that are parts of manuals must be checked -into CVS, even if they are generated files, for the generation of -online manuals to work. - - The installation manual, `doc/install.texi', is also provided on the -GCC web site. The HTML version is generated by the script -`doc/install.texi2html'. - - -File: gccint.info, Node: Man Page Generation, Next: Miscellaneous Docs, Prev: Texinfo Manuals, Up: Documentation - -Man Page Generation -................... - - Because of user demand, in addition to full Texinfo manuals, man -pages are provided which contain extracts from those manuals. These man -pages are generated from the Texinfo manuals using -`contrib/texi2pod.pl' and `pod2man'. (The man page for `g++', -`cp/g++.1', just contains a `.so' reference to `gcc.1', but all the -other man pages are generated from Texinfo manuals.) - - Because many systems may not have the necessary tools installed to -generate the man pages, they are only generated if the `configure' -script detects that recent enough tools are installed, and the -Makefiles allow generating man pages to fail without aborting the -build. Man pages are also included in release distributions. They are -generated in the source directory. - - Magic comments in Texinfo files starting `@c man' control what parts -of a Texinfo file go into a man page. Only a subset of Texinfo is -supported by `texi2pod.pl', and it may be necessary to add support for -more Texinfo features to this script when generating new man pages. To -improve the man page output, some special Texinfo macros are provided -in `doc/include/gcc-common.texi' which `texi2pod.pl' understands: - -`@gcctabopt' - Use in the form `@table @gcctabopt' for tables of options, where - for printed output the effect of `@code' is better than that of - `@option' but for man page output a different effect is wanted. - -`@gccoptlist' - Use for summary lists of options in manuals. - -`@gol' - Use at the end of each line inside `@gccoptlist'. This is - necessary to avoid problems with differences in how the - `@gccoptlist' macro is handled by different Texinfo formatters. - - FIXME: describe the `texi2pod.pl' input language and magic comments -in more detail. - - -File: gccint.info, Node: Miscellaneous Docs, Prev: Man Page Generation, Up: Documentation - -Miscellaneous Documentation -........................... - - In addition to the formal documentation that is installed by GCC, -there are several other text files with miscellaneous documentation: - -`ABOUT-GCC-NLS' - Notes on GCC's Native Language Support. FIXME: this should be - part of this manual rather than a separate file. - -`ABOUT-NLS' - Notes on the Free Translation Project. - -`COPYING' - The GNU General Public License. - -`COPYING.LIB' - The GNU Lesser General Public License. - -`*ChangeLog*' -`*/ChangeLog*' - Change log files for various parts of GCC. - -`LANGUAGES' - Details of a few changes to the GCC front-end interface. FIXME: - the information in this file should be part of general - documentation of the front-end interface in this manual. - -`ONEWS' - Information about new features in old versions of GCC. (For recent - versions, the information is on the GCC web site.) - -`README.Portability' - Information about portability issues when writing code in GCC. - FIXME: why isn't this part of this manual or of the GCC Coding - Conventions? - -`SERVICE' - A pointer to the GNU Service Directory. - - FIXME: document such files in subdirectories, at least `config', -`cp', `objc', `testsuite'. - - -File: gccint.info, Node: Front End, Next: Back End, Prev: Documentation, Up: gcc Directory - -Anatomy of a Language Front End -------------------------------- - - A front end for a language in GCC has the following parts: - - * A directory `LANGUAGE' under `gcc' containing source files for - that front end. *Note The Front End `LANGUAGE' Directory: Front - End Directory, for details. - - * A mention of the language in the list of supported languages in - `gcc/doc/install.texi'. - - * Details of contributors to that front end in - `gcc/doc/contrib.texi'. If the details are in that front end's - own manual then there should be a link to that manual's list in - `contrib.texi'. - - * Information about support for that language in - `gcc/doc/frontends.texi'. - - * Information about standards for that language, and the front end's - support for them, in `gcc/doc/standards.texi'. This may be a link - to such information in the front end's own manual. - - * Details of source file suffixes for that language and `-x LANG' - options supported, in `gcc/doc/invoke.texi'. - - * Entries in `default_compilers' in `gcc.c' for source file suffixes - for that language. - - * Preferably test suites, which may be under `gcc/testsuite' or - runtime library directories. FIXME: document somewhere how to - write test suite harnesses. - - * Probably a runtime library for the language, outside the `gcc' - directory. FIXME: document this further. - - * Details of the directories of any runtime libraries in - `gcc/doc/sourcebuild.texi'. - - If the front end is added to the official GCC CVS repository, the -following are also necessary: - - * At least one GNATS category for bugs in that front end and runtime - libraries. This category needs to be mentioned in - `gcc/gccbug.in', and in `gnats.html' on the GCC web site, as well - as being added to the GNATS database. - - * Normally, one or more maintainers of that front end listed in - `MAINTAINERS'. - - * Mentions on the GCC web site in `index.html' and `frontends.html', - with any relevant links on `readings.html'. (Front ends that are - not an official part of GCC may also be listed on - `frontends.html', with relevant links.) - - * A news item on `index.html', and possibly an announcement on the - mailing list. - - * The front end's manuals should be mentioned in - `maintainer-scripts/update_web_docs' (*note Texinfo Manuals::) and - the online manuals should be linked to from - `onlinedocs/index.html'. - - * Any old releases or CVS repositories of the front end, before its - inclusion in GCC, should be made available on the GCC FTP site - `ftp://gcc.gnu.org/pub/gcc/old-releases/'. - - * The release and snapshot script `maintainer-scripts/gcc_release' - should be updated to generate appropriate tarballs for this front - end. - - * If this front end includes its own version files that include the - current date, `maintainer-scripts/update_version' should be - updated accordingly. - - * `CVSROOT/modules' in the GCC CVS repository should be updated. - -* Menu: - -* Front End Directory:: The front end `LANGUAGE' directory. -* Front End Config:: The front end `config-lang.in' file. - - -File: gccint.info, Node: Front End Directory, Next: Front End Config, Up: Front End - -The Front End `LANGUAGE' Directory -.................................. - - A front end `LANGUAGE' directory contains the source files of that -front end (but not of any runtime libraries, which should be outside -the `gcc' directory). This includes documentation, and possibly some -subsidiary programs build alongside the front end. Certain files are -special and other parts of the compiler depend on their names: - -`config-lang.in' - This file is required in all language subdirectories. *Note The - Front End `config-lang.in' File: Front End Config, for details of - its contents - -`Make-lang.in' - This file is required in all language subdirectories. It contains - targets `LANG.HOOK' (where `LANG' is the setting of `language' in - `config-lang.in') for the following values of `HOOK', and any - other Makefile rules required to build those targets (which may if - necessary use other Makefiles specified in `outputs' in - `config-lang.in', although this is deprecated). - - `all.build' - `all.cross' - `start.encap' - `rest.encap' - FIXME: exactly what goes in each of these targets? - - `info' - Build info documentation for the front end, in the source - directory. This target is only called by `make bootstrap' if - a suitable version of `makeinfo' is available, so does not - need to check for this, and should fail if an error occurs. - - `dvi' - Build DVI documentation for the front end, in the build - directory. This should be done using `$(TEXI2DVI)', with - appropriate `-I' arguments pointing to directories of - included files. - - `generated-manpages' - Build generated man pages for the front end from Texinfo - manuals (*note Man Page Generation::), in the source - directory. This target is only called if the necessary tools - are available, but should ignore errors so as not to stop the - build if errors occur; man pages are optional and the tools - involved may be installed in a broken way. - - `install-normal' - FIXME: what is this target for? - - `install-common' - Install everything that is part of the front end, apart from - the compiler executables listed in `compilers' in - `config-lang.in' that are installed in `LIBSUBDIR' by the - main `Makefile'. - - `install-info' - Install info documentation for the front end, if it is - present in the source directory. (It may not be present if a - suitable version of `makeinfo' was not installed.) This - target should run the command `install-info' to update the - info directory, but should ignore errors when running that - command. - - `install-man' - Install man pages for the front end. This target should - ignore errors. - - `uninstall' - Uninstall files installed by installing the compiler. This is - currently documented not to be supported, so the hook need - not do anything. - - `mostlyclean' - `clean' - `distclean' - `extraclean' - `maintainer-clean' - Except for `extraclean', the language parts of the standard - GNU `*clean' targets. *Note Standard Targets for Users: - (standards)Standard Targets, for details of the standard - targets. `extraclean' does `distclean' and also deletes - anything likely to be found in the source directory that - shouldn't be in the distribution. For GCC, - `maintainer-clean' should delete all generated files in the - source directory that are not checked into CVS, but should - not delete anything checked into CVS. - - `stage1' - `stage2' - `stage3' - `stage4' - Move to the stage directory files not included in - `stagestuff' in `config-lang.in' or otherwise moved by the - main `Makefile'. - -`lang-options.h' - This file provides entries for `documented_lang_options' in - `toplev.c' describing command-line options the front end accepts - for `--help' output. - -`lang-specs.h' - This file provides entries for `default_compilers' in `gcc.c' - which override the default of giving an error that a compiler for - that language is not installed. - -`LANGUAGE-tree.def' - This file, which need not exist, defines any language-specific tree - codes. - - -File: gccint.info, Node: Front End Config, Prev: Front End Directory, Up: Front End - -The Front End `config-lang.in' File -................................... - - Each language subdirectory contains a `config-lang.in' file. This -file is a shell script that may define some variables describing the -language: - -`language' - This definition must be present, and gives the name of the language - for some purposes such as arguments to `--enable-languages'. - -`lang_requires' - If defined, this variable lists (space-separated) language front - ends other than C that this front end requires to be enabled (with - the names given being their `language' settings). For example, the - Java front end depends on the C++ front end, so sets - `lang_requires=c++'. - -`target_libs' - If defined, this variable lists (space-separated) targets in the - top level `Makefile' to build the runtime libraries for this - language, such as `target-libobjc'. - -`lang_dirs' - If defined, this variable lists (space-separated) top level - directories (parallel to `gcc'), apart from the runtime libraries, - that should not be configured if this front end is not built. - -`build_by_default' - If defined to `no', this language front end is not built unless - enabled in a `--enable-languages' argument. Otherwise, front ends - are built by default, subject to any special logic in - `configure.in' (as is present to disable the Ada front end if the - Ada compiler is not already installed). - -`boot_language' - If defined to `yes', this front end is built in stage 1 of the - bootstrap. This is only relevant to front ends written in their - own languages. - -`compilers' - If defined, a space-separated list of compiler executables that - should be installed in `LIBSUBDIR'. The names here will each end - with `\$(exeext)'. - -`stagestuff' - If defined, a space-separated list of files that should be moved to - the `stageN' directories in each stage of bootstrap. - -`outputs' - If defined, a space-separated list of files that should be - generated by `configure' substituting values in them. This - mechanism can be used to create a file `LANGUAGE/Makefile' from - `LANGUAGE/Makefile.in', but this is deprecated, building - everything from the single `gcc/Makefile' is preferred. -