1 \input texinfo @c -*-texinfo-*-
3 @c NOTE THIS IS NOT A GOOD EXAMPLE OF HOW TO DO A MANUAL. FIXME!!!
4 @c NOTE THIS IS NOT A GOOD EXAMPLE OF HOW TO DO A MANUAL. FIXME!!!
8 @setfilename treelang.info
10 @include gcc-common.texi
12 @set copyrights-treelang 1995,1996,1997,1998,1999,2000,2001,2002,2003,2004,2005
14 @set email-general gcc@@gcc.gnu.org
15 @set email-bugs gcc-bugs@@gcc.gnu.org or bug-gcc@@gnu.org
16 @set email-patches gcc-patches@@gcc.gnu.org
17 @set path-treelang gcc/gcc/treelang
19 @set which-treelang GCC-@value{version-GCC}
22 @set email-josling tej@@melbpc.org.au
23 @set www-josling http://www.geocities.com/timjosling
25 @c This tells @include'd files that they're part of the overall TREELANG doc
26 @c set. (They might be part of a higher-level doc set too.)
29 @c @setfilename usetreelang.info
30 @c @setfilename maintaintreelang.info
31 @c To produce the full manual, use the "treelang.info" setfilename, and
32 @c make sure the following do NOT begin with '@c' (and the @clear lines DO)
35 @c To produce a user-only manual, use the "usetreelang.info" setfilename, and
36 @c make sure the following does NOT begin with '@c':
38 @c To produce a maintainer-only manual, use the "maintaintreelang.info" setfilename,
39 @c and make sure the following does NOT begin with '@c':
44 @settitle Using and Maintaining GNU Treelang
47 @c seems reasonable to assume at least one of INTERNALS or USING is set...
49 @settitle Using GNU Treelang
52 @settitle Maintaining GNU Treelang
54 @c then again, have some fun
57 @settitle Doing Very Little at all with GNU Treelang
65 @c Cause even numbered pages to be printed on the left hand side of
66 @c the page and odd numbered pages to be printed on the right hand
67 @c side of the page. Using this, you can print on both sides of a
68 @c sheet of paper and have the text on the same part of the sheet.
70 @c The text on right hand pages is pushed towards the right hand
71 @c margin and the text on left hand pages is pushed toward the left
73 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
76 @c \global\bindingoffset=0.75in
77 @c \global\normaloffset =0.75in
81 Copyright @copyright{} @value{copyrights-treelang} Free Software Foundation, Inc.
83 Permission is granted to copy, distribute and/or modify this document
84 under the terms of the GNU Free Documentation License, Version 1.2 or
85 any later version published by the Free Software Foundation; with the
86 Invariant Sections being ``GNU General Public License'', the Front-Cover
87 texts being (a) (see below), and with the Back-Cover Texts being (b)
88 (see below). A copy of the license is included in the section entitled
89 ``GNU Free Documentation License''.
91 (a) The FSF's Front-Cover Text is:
95 (b) The FSF's Back-Cover Text is:
97 You have freedom to copy and modify this GNU Manual, like GNU
98 software. Copies published by the Free Software Foundation raise
99 funds for GNU development.
103 @dircategory Programming
105 * treelang: (treelang). The GNU Treelang compiler.
109 This file documents the use and the internals of the GNU Treelang
110 (@code{treelang}) compiler. At the moment this manual is not
111 incorporated into the main GCC manual as it is too incomplete. It
112 corresponds to the @value{which-treelang} version of @code{treelang}.
116 This file documents the internals of the GNU Treelang (@code{treelang}) compiler.
117 It corresponds to the @value{which-treelang} version of @code{treelang}.
120 This file documents the use of the GNU Treelang (@code{treelang}) compiler.
121 It corresponds to the @value{which-treelang} version of @code{treelang}.
124 Published by the Free Software Foundation
125 59 Temple Place - Suite 330
126 Boston, MA 02111-1307 USA
131 treelang was Contributed by Tim Josling (@email{@value{email-josling}}).
132 Inspired by and based on the 'toy' language, written by Richard Kenner.
134 This document was written by Tim Josling, based on the GNU C++
137 @setchapternewpage odd
142 @center @titlefont{Using and Maintaining GNU Treelang}
147 @title Using GNU Treelang
150 @title Maintaining GNU Treelang
155 @vskip 0pt plus 1filll
156 For the @value{which-treelang} Version*
158 Published by the Free Software Foundation @*
159 59 Temple Place - Suite 330@*
160 Boston, MA 02111-1307, USA@*
161 @c Last printed ??ber, 19??.@*
162 @c Printed copies are available for $? each.@*
171 @node Top, Copying,, (dir)
177 This manual documents how to run, install and maintain @code{treelang},
178 as well as its new features and incompatibilities,
179 and how to report bugs.
180 It corresponds to the @value{which-treelang} version of @code{treelang}.
185 This manual documents how to run and install @code{treelang},
186 as well as its new features and incompatibilities, and how to report
188 It corresponds to the @value{which-treelang} version of @code{treelang}.
191 This manual documents how to maintain @code{treelang}, as well as its
192 new features and incompatibilities, and how to report bugs. It
193 corresponds to the @value{which-treelang} version of @code{treelang}.
201 * GNU Free Documentation License::
204 * What is GNU Treelang?::
207 * Compiler Overview::
211 * treelang internals::
219 --- The Detailed Node Listing ---
223 * Interoperating with C and C++::
228 * treelang compiler interfaces::
231 treelang compiler interfaces
234 * treelang main compiler::
236 treelang main compiler
238 * Interfacing to toplev.c::
239 * Interfacing to the garbage collection::
240 * Interfacing to the code generation code. ::
255 @unnumbered Contributors to GNU Treelang
259 Treelang was based on 'toy' by Richard Kenner, and also uses code from
260 the GCC core code tree. Tim Josling first created the language and
261 documentation, based on the GCC Fortran compiler's documentation
262 framework. Treelang was updated to use the TreeSSA infrastructure by James A.
267 The packaging and compiler portions of GNU Treelang are based largely
269 @xref{Contributors,,Contributors to GCC,GCC,Using and Maintaining GCC},
270 for more information.
273 There is no specific run-time library for treelang, other than the
277 It would have been difficult to build treelang without access to Joachim
278 Nadler's guide to writing a front end to GCC (written in German). A
279 translation of this document into English is available via the
280 CobolForGCC project or via the documentation links from the GCC home
281 page @uref{http://gcc.gnu.org}.
284 @include funding.texi
286 @node Getting Started
287 @chapter Getting Started
288 @cindex getting started
293 Treelang is a sample language, useful only to help people understand how
294 to implement a new language front end to GCC. It is not a useful
295 language in itself other than as an example or basis for building a new
296 language. Therefore only language developers are likely to have an
299 This manual assumes familiarity with GCC, which you can obtain by using
300 it and by reading the manuals @samp{Using the GNU Compiler Collection (GCC)}
301 and @samp{GNU Compiler Collection (GCC) Internals}.
303 To install treelang, follow the GCC installation instructions,
304 taking care to ensure you specify treelang in the configure step by adding
305 treelang to the list of languages specified by @option{--enable-langauges},
306 e.g.@: @samp{--enable-languages=all,treelang}.
308 If you're generally curious about the future of
309 @code{treelang}, see @ref{Projects}.
310 If you're curious about its past,
311 see @ref{Contributors}.
313 To see a few of the questions maintainers of @code{treelang} have,
314 and that you might be able to answer,
315 see @ref{Open Questions}.
318 @node What is GNU Treelang?, Lexical Syntax, Getting Started, Top
319 @chapter What is GNU Treelang?
320 @cindex concepts, basic
321 @cindex basic concepts
323 GNU Treelang, or @code{treelang}, is designed initially as a free
324 replacement for, or alternative to, the 'toy' language, but which is
325 amenable to inclusion within the GCC source tree.
327 @code{treelang} is largely a cut down version of C, designed to showcase
328 the features of the GCC code generation back end. Only those features
329 that are directly supported by the GCC code generation back end are
330 implemented. Features are implemented in a manner which is easiest and
331 clearest to implement. Not all or even most code generation back end
332 features are implemented. The intention is to add features incrementally
333 until most features of the GCC back end are implemented in treelang.
335 The main features missing are structures, arrays and pointers.
337 A sample program follows:
340 // @r{function prototypes}
341 // @r{function 'add' taking two ints and returning an int}
342 external_definition int add(int arg1, int arg2);
343 external_definition int subtract(int arg3, int arg4);
344 external_definition int first_nonzero(int arg5, int arg6);
345 external_definition int double_plus_one(int arg7);
347 // @r{function definition}
350 // @r{return the sum of arg1 and arg2}
362 // @r{aaa is a variable, of type integer and allocated at the start of}
365 // @r{set aaa to the value returned from add, when passed arg7 and arg7 as}
366 // @r{the two parameters}
369 aaa=subtract(subtract(aaa, arg7), arg7) + 1;
375 // @r{C-like if statement}
387 @node Lexical Syntax, Parsing Syntax, What is GNU Treelang?, Top
388 @chapter Lexical Syntax
389 @cindex Lexical Syntax
391 Treelang programs consist of whitespace, comments, keywords and names.
395 Whitespace consists of the space character, a tab, and the end of line
396 character. Line terminations are as defined by the
397 standard C library. Whitespace is ignored except within comments,
398 and where it separates parts of the program. In the example below, A and
399 B are two separate names separated by whitespace.
406 Comments consist of @samp{//} followed by any characters up to the end
407 of the line. C style comments (/* */) are not supported. For example,
408 the assignment below is followed by a not very helpful comment.
411 x = 1; // @r{Set X to 1}
415 Keywords consist of any of the following reserved words or symbols:
419 used to start the statements in a function
421 used to end the statements in a function
423 start list of function arguments, or to change the precedence of operators in
426 end list or prioritized operators in expression
428 used to separate parameters in a function prototype or in a function call
430 used to end a statement
442 begin 'else' portion of IF statement
444 indicate variable is permanent, or function has file scope only
446 indicate that variable is allocated for the life of the function
447 @item external_reference
448 indicate that variable or function is defined in another file
449 @item external_definition
450 indicate that variable or function is to be accessible from other files
452 variable is an integer (same as C int)
454 variable is a character (same as C char)
456 variable is unsigned. If this is not present, the variable is signed
458 start function return statement
460 used as function type to indicate function returns nothing
465 Names consist of any letter or "_" followed by any number of letters,
466 numbers, or "_". "$" is not allowed in a name. All names must be globally
467 unique, i.e. may not be used twice in any context, and must
468 not be a keyword. Names and keywords are case sensitive. For example:
474 are all different names.
478 @node Parsing Syntax, Compiler Overview, Lexical Syntax, Top
479 @chapter Parsing Syntax
480 @cindex Parsing Syntax
482 Declarations are built up from the lexical elements described above. A
483 file may contain one of more declarations.
488 declaration: variable declaration OR function prototype OR function declaration
491 Function Prototype: storage type NAME ( optional_parameter_list )
494 static int add (int a, int b)
498 variable_declaration: storage type NAME initial;
506 A variable declaration can be outside a function, or at the start of a
510 storage: automatic OR static OR external_reference OR external_definition
512 This defines the scope, duration and visibility of a function or variable
517 automatic: This means a variable is allocated at start of function and
518 released when the function returns. This can only be used for variables
519 within functions. It cannot be used for functions.
522 static: This means a variable is allocated at start of program and
523 remains allocated until the program as a whole ends. For a function, it
524 means that the function is only visible within the current file.
527 external_definition: For a variable, which must be defined outside a
528 function, it means that the variable is visible from other files. For a
529 function, it means that the function is visible from another file.
532 external_reference: For a variable, which must be defined outside a
533 function, it means that the variable is defined in another file. For a
534 function, it means that the function is defined in another file.
539 type: int OR unsigned int OR char OR unsigned char OR void
541 This defines the data type of a variable or the return type of a function.
546 int: The variable is a signed integer. The function returns a signed integer.
549 unsigned int: The variable is an unsigned integer. The function returns an unsigned integer.
552 char: The variable is a signed character. The function returns a signed character.
555 unsigned char: The variable is an unsigned character. The function returns an unsigned character.
560 parameter_list OR parameter [, parameter]...
563 parameter: variable_declaration ,
565 The variable declarations must not have initialisations.
571 value: integer_constant
578 function_declaration: name @{variable_declarations statements @}
580 A function consists of the function name then the declarations (if any)
581 and statements (if any) within one pair of braces.
583 The details of the function arguments come from the function
584 prototype. The function prototype must precede the function declaration
588 statement: if_statement OR expression_statement OR return_statement
591 if_statement: if (expression) @{ statements @} else @{ statements @}
593 The first lot of statements is executed if the expression is
594 nonzero. Otherwise the second lot of statements is executed. Either
595 list of statements may be empty, but both sets of braces and the else must be present.
609 expression_statement: expression;
611 The expression is executed and any side effects, such
614 return_statement: return expression_opt;
616 Returns from the function. If the function is void, the expression must
617 be absent, and if the function is not void the expression must be
621 expression: variable OR integer_constant OR expression+expression
622 OR expression-expression OR expression==expression OR (expression)
623 OR variable=expression OR function_call
625 An expression can be a constant or a variable reference or a
626 function_call. Expressions can be combined as a sum of two expressions
627 or the difference of two expressions, or an equality test of two
628 expresions. An assignment is also an expression. Expresions and operator
629 precedence work as in C.
632 function_call: function_name (comma_separated_expressions)
634 This invokes the function, passing to it the values of the expressions
635 as actual parameters.
640 @node Compiler Overview, TREELANG and GCC, Parsing Syntax, Top
641 @chapter Compiler Overview
642 treelang is run as part of the GCC compiler.
650 It reads a user's program, stored in a file and containing instructions
651 written in the appropriate language (Treelang, C, and so on). This file
652 contains @dfn{source code}.
654 @cindex translation of user programs
656 @cindex code, machine
659 It translates the user's program into instructions a computer can carry
660 out more quickly than it takes to translate the instructions in the
661 first place. These instructions are called @dfn{machine code}---code
662 designed to be efficiently translated and processed by a machine such as
663 a computer. Humans usually aren't as good writing machine code as they
664 are at writing Treelang or C, because it is easy to make tiny mistakes
665 writing machine code. When writing Treelang or C, it is easy to make
666 big mistakes. But you can only make one mistake, because the compiler
667 stops after it finds any problem.
670 @cindex bugs, finding
671 @cindex @code{gdb}, command
672 @cindex commands, @code{gdb}
674 It provides information in the generated machine code
675 that can make it easier to find bugs in the program
676 (using a debugging tool, called a @dfn{debugger},
681 @cindex @code{ld} command
682 @cindex commands, @code{ld}
684 It locates and gathers machine code already generated to perform actions
685 requested by statements in the user's program. This machine code is
686 organized into @dfn{libraries} and is located and gathered during the
687 @dfn{link} phase of the compilation process. (Linking often is thought
688 of as a separate step, because it can be directly invoked via the
689 @code{ld} command. However, the @code{gcc} command, as with most
690 compiler commands, automatically performs the linking step by calling on
691 @code{ld} directly, unless asked to not do so by the user.)
693 @cindex language, incorrect use of
694 @cindex incorrect use of language
696 It attempts to diagnose cases where the user's program contains
697 incorrect usages of the language. The @dfn{diagnostics} produced by the
698 compiler indicate the problem and the location in the user's source file
699 where the problem was first noticed. The user can use this information
700 to locate and fix the problem.
702 The compiler stops after the first error. There are no plans to fix
703 this, ever, as it would vastly complicate the implementation of treelang
704 to little or no benefit.
706 @cindex diagnostics, incorrect
707 @cindex incorrect diagnostics
708 @cindex error messages, incorrect
709 @cindex incorrect error messages
710 (Sometimes an incorrect usage of the language leads to a situation where
711 the compiler can not make any sense of what it reads---while a human
712 might be able to---and thus ends up complaining about an incorrect
713 ``problem'' it encounters that, in fact, reflects a misunderstanding of
714 the programmer's intention.)
717 @cindex questionable instructions
719 There are no warnings in treelang. A program is either correct or in
723 @cindex components of treelang
724 @cindex @code{treelang}, components of
725 @code{treelang} consists of several components:
727 @cindex @code{gcc}, command
728 @cindex commands, @code{gcc}
731 A modified version of the @code{gcc} command, which also might be
732 installed as the system's @code{cc} command.
733 (In many cases, @code{cc} refers to the
734 system's ``native'' C compiler, which
735 might be a non-GNU compiler, or an older version
736 of @code{GCC} considered more stable or that is
737 used to build the operating system kernel.)
739 @cindex @code{treelang}, command
740 @cindex commands, @code{treelang}
742 The @code{treelang} command itself.
745 The @code{libc} run-time library. This library contains the machine
746 code needed to support capabilities of the Treelang language that are
747 not directly provided by the machine code generated by the
748 @code{treelang} compilation phase. This is the same library that the
749 main c compiler uses (libc).
751 @cindex @code{tree1}, program
752 @cindex programs, @code{tree1}
754 @cindex @code{as} command
755 @cindex commands, @code{as}
756 @cindex assembly code
757 @cindex code, assembly
759 The compiler itself, is internally named @code{tree1}.
761 Note that @code{tree1} does not generate machine code directly---it
762 generates @dfn{assembly code} that is a more readable form
763 of machine code, leaving the conversion to actual machine code
764 to an @dfn{assembler}, usually named @code{as}.
767 @code{GCC} is often thought of as ``the C compiler'' only,
768 but it does more than that.
769 Based on command-line options and the names given for files
770 on the command line, @code{gcc} determines which actions to perform, including
771 preprocessing, compiling (in a variety of possible languages), assembling,
774 @cindex driver, gcc command as
775 @cindex @code{gcc}, command as driver
776 @cindex executable file
777 @cindex files, executable
779 @cindex programs, cc1
782 @cindex programs, cpp
783 For example, the command @samp{gcc foo.c} @dfn{drives} the file
784 @file{foo.c} through the preprocessor @code{cpp}, then
785 the C compiler (internally named
786 @code{cc1}), then the assembler (usually @code{as}), then the linker
787 (@code{ld}), producing an executable program named @file{a.out} (on
790 @cindex treelang program
791 @cindex programs, treelang
792 As another example, the command @samp{gcc foo.tree} would do much the
793 same as @samp{gcc foo.c}, but instead of using the C compiler named
794 @code{cc1}, @code{gcc} would use the treelang compiler (named
795 @code{tree1}). However there is no preprocessor for treelang.
797 @cindex @code{tree1}, program
798 @cindex programs, @code{tree1}
799 In a GNU Treelang installation, @code{gcc} recognizes Treelang source
800 files by name just like it does C and C++ source files. It knows to use
801 the Treelang compiler named @code{tree1}, instead of @code{cc1} or
802 @code{cc1plus}, to compile Treelang files. If a file's name ends in
803 @code{.tree} then GCC knows that the program is written in treelang. You
804 can also manually override the language.
806 @cindex @code{gcc}, not recognizing Treelang source
807 @cindex unrecognized file format
808 @cindex file format not recognized
809 Non-Treelang-related operation of @code{gcc} is generally
810 unaffected by installing the GNU Treelang version of @code{gcc}.
811 However, without the installed version of @code{gcc} being the
812 GNU Treelang version, @code{gcc} will not be able to compile
813 and link Treelang programs.
815 @cindex printing version information
816 @cindex version information, printing
817 The command @samp{gcc -v x.tree} where @samp{x.tree} is a file which
818 must exist but whose contents are ignored, is a quick way to display
819 version information for the various programs used to compile a typical
820 Treelang source file.
822 The @code{tree1} program represents most of what is unique to GNU
823 Treelang; @code{tree1} is a combination of two rather large chunks of
826 @cindex GCC Back End (GBE)
828 @cindex @code{GCC}, back end
829 @cindex back end, GCC
830 @cindex code generator
831 One chunk is the so-called @dfn{GNU Back End}, or GBE,
832 which knows how to generate fast code for a wide variety of processors.
833 The same GBE is used by the C, C++, and Treelang compiler programs @code{cc1},
834 @code{cc1plus}, and @code{tree1}, plus others.
835 Often the GBE is referred to as the ``GCC back end'' or
836 even just ``GCC''---in this manual, the term GBE is used
837 whenever the distinction is important.
839 @cindex GNU Treelang Front End (TFE)
841 @cindex @code{treelang}, front end
842 @cindex front end, @code{treelang}
843 The other chunk of @code{tree1} is the majority of what is unique about
844 GNU Treelang---the code that knows how to interpret Treelang programs to
845 determine what they are intending to do, and then communicate that
846 knowledge to the GBE for actual compilation of those programs. This
847 chunk is called the @dfn{Treelang Front End} (TFE). The @code{cc1} and
848 @code{cc1plus} programs have their own front ends, for the C and C++
849 languages, respectively. These fronts ends are responsible for
850 diagnosing incorrect usage of their respective languages by the programs
851 the process, and are responsible for most of the warnings about
852 questionable constructs as well. (The GBE in principle handles
853 producing some warnings, like those concerning possible references to
854 undefined variables, but these warnings should not occur in treelang
855 programs as the front end is meant to pick them up first).
857 Because so much is shared among the compilers for various languages,
858 much of the behavior and many of the user-selectable options for these
859 compilers are similar.
860 For example, diagnostics (error messages and
861 warnings) are similar in appearance; command-line
862 options like @samp{-Wall} have generally similar effects; and the quality
863 of generated code (in terms of speed and size) is roughly similar
864 (since that work is done by the shared GBE).
866 @node TREELANG and GCC, Compiler, Compiler Overview, Top
867 @chapter Compile Treelang, C, or Other Programs
868 @cindex compiling programs
869 @cindex programs, compiling
871 @cindex @code{gcc}, command
872 @cindex commands, @code{gcc}
873 A GNU Treelang installation includes a modified version of the @code{gcc}
876 In a non-Treelang installation, @code{gcc} recognizes C, C++,
877 and Objective-C source files.
879 In a GNU Treelang installation, @code{gcc} also recognizes Treelang source
880 files and accepts Treelang-specific command-line options, plus some
881 command-line options that are designed to cater to Treelang users
882 but apply to other languages as well.
884 @xref{G++ and GCC,,Programming Languages Supported by GCC,GCC,Using
885 the GNU Compiler Collection (GCC)},
886 for information on the way different languages are handled
887 by the GCC compiler (@code{gcc}).
889 You can use this, combined with the output of the @samp{gcc -v x.tree}
890 command to get the options applicable to treelang. Treelang programs
891 must end with the suffix @samp{.tree}.
895 Treelang programs are not by default run through the C
896 preprocessor by @code{gcc}. There is no reason why they cannot be run through the
897 preprocessor manually, but you would need to prevent the preprocessor
898 from generating #line directives, using the @samp{-P} option, otherwise
899 tree1 will not accept the input.
901 @node Compiler, Other Languages, TREELANG and GCC, Top
902 @chapter The GNU Treelang Compiler
904 The GNU Treelang compiler, @code{treelang}, supports programs written
905 in the GNU Treelang language.
907 @node Other Languages, treelang internals, Compiler, Top
908 @chapter Other Languages
911 * Interoperating with C and C++::
914 @node Interoperating with C and C++, , Other Languages, Other Languages
915 @section Tools and advice for interoperating with C and C++
917 The output of treelang programs looks like C program code to the linker
918 and everybody else, so you should be able to freely mix treelang and C
919 (and C++) code, with one proviso.
921 C promotes small integer types to 'int' when used as function parameters and
922 return values. The treelang compiler does not do this, so if you want to interface
923 to C, you need to specify the promoted value, not the nominal value.
926 @node treelang internals, Open Questions, Other Languages, Top
927 @chapter treelang internals
931 * treelang compiler interfaces::
935 @node treelang files, treelang compiler interfaces, treelang internals, treelang internals
936 @section treelang files
938 To create a compiler that integrates into GCC, you need create many
939 files. Some of the files are integrated into the main GCC makefile, to
940 build the various parts of the compiler and to run the test
941 suite. Others are incorporated into various GCC programs such as
942 GCC.c. Finally you must provide the actual programs comprising your
952 COPYING. This is the copyright file, assuming you are going to use the
953 GNU General Public Licence. You probably need to use the GPL because if
954 you use the GCC back end your program and the back end are one program,
955 and the back end is GPLed.
957 This need not be present if the language is incorporated into the main
958 GCC tree, as the main GCC directory has this file.
961 COPYING.LIB. This is the copyright file for those parts of your program
962 that are not to be covered by the GPL, but are instead to be covered by
963 the LGPL (Library or Lesser GPL). This licence may be appropriate for
964 the library routines associated with your compiler. These are the
965 routines that are linked with the @emph{output} of the compiler. Using
966 the LGPL for these programs allows programs written using your compiler
967 to be closed source. For example LIBC is under the LGPL.
969 This need not be present if the language is incorporated into the main
970 GCC tree, as the main GCC directory has this file.
973 ChangeLog. Record all the changes to your compiler. Use the same format
974 as used in treelang as it is supported by an emacs editing mode and is
975 part of the FSF coding standard. Normally each directory has its own
976 changelog. The FSF standard allows but does not require a meaningful
977 comment on why the changes were made, above and beyond @emph{why} they
978 were made. In the author's opinion it is useful to provide this
982 treelang.texi. The manual, written in texinfo. Your manual would have a
983 different file name. You need not write it in texinfo if you don't want
984 do, but a lot of GNU software does use texinfo.
988 Make-lang.in. This file is part of the make file which in incorporated
989 with the GCC make file skeleton (Makefile.in in the GCC directory) to
990 make Makefile, as part of the configuration process.
992 Makefile in turn is the main instruction to actually build
993 everything. The build instructions are held in the main GCC manual and
994 web site so they are not repeated here.
996 There are some comments at the top which will help you understand what
999 There are make commands to build things, remove generated files with
1000 various degrees of thoroughness, count the lines of code (so you know
1001 how much progress you are making), build info and html files from the
1002 texinfo source, run the tests etc.
1005 README. Just a brief informative text file saying what is in this
1008 @cindex config-lang.in
1010 config-lang.in. This file is read by the configuration progress and must
1011 be present. You specify the name of your language, the name(s) of the
1012 compiler(s) incouding preprocessors you are going to build, whether any,
1013 usually generated, files should be excluded from diffs (ie when making
1014 diff files to send in patches). Whether the equate 'stagestuff' is used
1017 @cindex lang-options
1019 lang-options. This file is included into GCC.c, the main GCC driver, and
1020 tells it what options your language supports. This is only used to
1021 display help (is this true ???).
1025 lang-specs. This file is also included in GCC.c. It tells GCC.c when to
1026 call your programs and what options to send them. The mini-language
1027 'specs' is documented in the source of GCC.c. Do not attempt to write a
1028 specs file from scratch - use an existing one as the base and enhance
1032 Your texi files. Texinfo can be used to build documentation in HTML,
1033 info, dvi and postscript formats. It is a tagged language, is documented
1034 in its own manual, and has its own emacs mode.
1037 Your programs. The relationships between all the programs are explained
1038 in the next section. You need to write or use the following programs:
1043 lexer. This breaks the input into words and passes these to the
1044 parser. This is lex.l in treelang, which is passed through flex, a lex
1045 variant, to produce C code lex.c. Note there is a school of thought that
1046 says real men hand code their own lexers, however you may prefer to
1047 write far less code and use flex, as was done with treelang.
1050 parser. This breaks the program into recognizable constructs such as
1051 expressions, statements etc. This is parse.y in treelang, which is
1052 passed through bison, which is a yacc variant, to produce C code parse.c.
1055 back end interface. This interfaces to the code generation back end. In
1056 treelang, this is tree1.c which mainly interfaces to toplev.c and
1057 treetree.c which mainly interfaces to everything else. Many languages
1058 mix up the back end interface with the parser, as in the C compiler for
1059 example. It is a matter of taste which way to do it, but with treelang
1060 it is separated out to make the back end interface cleaner and easier to
1064 header files. For function prototypes and common data items. One point
1065 to note here is that bison can generate a header files with all the
1066 numbers is has assigned to the keywords and symbols, and you can include
1067 the same header in your lexer. This technique is demonstrated in
1071 compiler main file. GCC comes with a program toplev.c which is a
1072 perfectly serviceable main program for your compiler. treelang uses
1073 toplev.c but other languages have been known to replace it with their
1074 own main program. Again this is a matter of taste and how much code you
1081 @node treelang compiler interfaces, Hints and tips, treelang files, treelang internals
1082 @section treelang compiler interfaces
1089 * treelang main compiler::
1092 @node treelang driver, treelang main compiler, treelang compiler interfaces, treelang compiler interfaces
1093 @subsection treelang driver
1095 The GCC compiler consists of a driver, which then executes the various
1096 compiler phases based on the instructions in the specs files.
1098 Typically a program's language will be identified from its suffix (eg
1099 .tree) for treelang programs.
1101 The driver (gcc.c) will then drive (exec) in turn a preprocessor, the main
1102 compiler, the assembler and the link editor. Options to GCC allow you to
1103 override all of this. In the case of treelang programs there is no
1104 preprocessor, and mostly these days the C preprocessor is run within the
1105 main C compiler rather than as a separate process, apparently for reasons of speed.
1107 You will be using the standard assembler and linkage editor so these are
1108 ignored from now on.
1110 You have to write your own preprocessor if you want one. This is usually
1111 totally language specific. The main point to be aware of is to ensure
1112 that you find some way to pass file name and line number information
1113 through to the main compiler so that it can tell the back end this
1114 information and so the debugger can find the right source line for each
1115 piece of code. That is all there is to say about the preprocessor except
1116 that the preprocessor will probably not be the slowest part of the
1117 compiler and will probably not use the most memory so don't waste too
1118 much time tuning it until you know you need to do so.
1120 @node treelang main compiler, , treelang driver, treelang compiler interfaces
1121 @subsection treelang main compiler
1123 The main compiler for treelang consists of toplev.c from the main GCC
1124 compiler, the parser, lexer and back end interface routines, and the
1125 back end routines themselves, of which there are many.
1127 toplev.c does a lot of work for you and you should almost certainly use it,
1129 Writing this code is the hard part of creating a compiler using GCC. The
1130 back end interface documentation is incomplete and the interface is
1133 There are three main aspects to interfacing to the other GCC code.
1136 * Interfacing to toplev.c::
1137 * Interfacing to the garbage collection::
1138 * Interfacing to the code generation code. ::
1141 @node Interfacing to toplev.c, Interfacing to the garbage collection, treelang main compiler, treelang main compiler
1142 @subsubsection Interfacing to toplev.c
1144 In treelang this is handled mainly in tree1.c
1145 and partly in treetree.c. Peruse toplev.c for details of what you need
1148 @node Interfacing to the garbage collection, Interfacing to the code generation code. , Interfacing to toplev.c, treelang main compiler
1149 @subsubsection Interfacing to the garbage collection
1151 Interfacing to the garbage collection. In treelang this is mainly in
1154 Memory allocation in the compiler should be done using the ggc_alloc and
1155 kindred routines in ggc*.*. At the end of every 'function' in your language, toplev.c calls
1156 the garbage collection several times. The garbage collection calls mark
1157 routines which go through the memory which is still used, telling the
1158 garbage collection not to free it. Then all the memory not used is
1161 What this means is that you need a way to hook into this marking
1162 process. This is done by calling ggc_add_root. This provides the address
1163 of a callback routine which will be called duing garbage collection and
1164 which can call ggc_mark to save the storage. If storage is only
1165 used within the parsing of a function, you do not need to provide a way
1168 Note that you can also call ggc_mark_tree to mark any of the back end
1169 internal 'tree' nodes. This routine will follow the branches of the
1170 trees and mark all the subordinate structures. This is useful for
1171 example when you have created a variable declaaration that will be used
1172 across multiple functions, or for a function declaration (from a
1173 prototype) that may be used later on. See the next item for more on the
1176 @node Interfacing to the code generation code. , , Interfacing to the garbage collection, treelang main compiler
1177 @subsubsection Interfacing to the code generation code.
1179 In treelang this is done in treetree.c. A typedef called 'tree' which is
1180 defined in tree.h and tree.def in the GCC directory and largely
1181 implemented in tree.c and stmt.c forms the basic interface to the
1184 In general you call various tree routines to generate code, either
1185 directly or through toplev.c. You build up data structures and
1186 expressions in similar ways.
1188 You can read some documentation on this which can be found via the GCC
1189 main web page. In particular, the documentation produced by Joachim
1190 Nadler and translated by Tim Josling can be quite useful. the C compiler
1191 also has documentation in the main GCC manual (particularly the current
1192 CVS version) which is useful on a lot of the details.
1194 In time it is hoped to enhance this document to provide a more
1195 comprehensive overview of this topic. The main gap is in explaining how
1196 it all works together.
1198 @node Hints and tips, , treelang compiler interfaces, treelang internals
1199 @section Hints and tips
1204 TAGS: Use the make ETAGS commands to create TAGS files which can be used in
1205 emacs to jump to any symbol quickly.
1208 GREP: grep is also a useful way to find all uses of a symbol.
1211 TREE: The main routines to look at are tree.h and tree.def. You will
1212 probably want a hardcopy of these.
1215 SAMPLE: look at the sample interfacing code in treetree.c. You can use
1216 gdb to trace through the code and learn about how it all works.
1219 GDB: the GCC back end works well with gdb. It traps abort() and allows
1220 you to trace back what went wrong.
1223 Error Checking: The compiler back end does some error and consistency
1224 checking. Often the result of an error is just no code being
1225 generated. You will then need to trace through and find out what is
1226 going wrong. The rtl dump files can help here also.
1229 rtl dump files: The main compiler documents these files which are dumps
1230 of the rtl (intermediate code) which is manipulated doing the code
1231 generation process. This can provide useful clues about what is going
1232 wrong. The rtl 'language' is documented in the main GCC manual.
1238 @node Open Questions, Bugs, treelang internals, Top
1239 @chapter Open Questions
1241 If you know GCC well, please consider looking at the file treetree.c and
1242 resolving any questions marked "???".
1244 @node Bugs, Service, Open Questions, Top
1245 @chapter Reporting Bugs
1247 @cindex reporting bugs
1249 You can report bugs to @email{@value{email-bugs}}. Please make
1250 sure bugs are real before reporting them. Follow the guidelines in the
1251 main GCC manual for submitting bug reports.
1257 @node Sending Patches, , Bugs, Bugs
1258 @section Sending Patches for GNU Treelang
1260 If you would like to write bug fixes or improvements for the GNU
1261 Treelang compiler, that is very helpful. Send suggested fixes to
1262 @email{@value{email-patches}}.
1264 @node Service, Projects, Bugs, Top
1265 @chapter How To Get Help with GNU Treelang
1267 If you need help installing, using or changing GNU Treelang, there are two
1273 Look in the service directory for someone who might help you for a fee.
1274 The service directory is found in the file named @file{SERVICE} in the
1278 Send a message to @email{@value{email-general}}.
1285 @node Projects, Index, Service, Top
1289 If you want to contribute to @code{treelang} by doing research,
1290 design, specification, documentation, coding, or testing,
1291 the following information should give you some ideas.
1293 Send a message to @email{@value{email-general}} if you plan to add a
1296 The main requirement for treelang is to add features and to add
1297 documentation. Features are things that the GCC back end can do but
1298 which are not reflected in treelang. Examples include structures,
1299 unions, pointers, arrays.
1303 @node Index, , Projects, Top