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 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 @setchapternewpage odd
136 @center @titlefont{Using and Maintaining GNU Treelang}
141 @title Using GNU Treelang
144 @title Maintaining GNU Treelang
149 @vskip 0pt plus 1filll
150 For the @value{which-treelang} Version*
152 Published by the Free Software Foundation @*
153 59 Temple Place - Suite 330@*
154 Boston, MA 02111-1307, USA@*
155 @c Last printed ??ber, 19??.@*
156 @c Printed copies are available for $? each.@*
165 @node Top, Copying,, (dir)
171 This manual documents how to run, install and maintain @code{treelang}.
172 It also documents the features and incompatibilities in the @value{which-treelang}
173 version of @code{treelang}.
178 This manual documents how to run and install @code{treelang}.
179 It also documents the features and incompatibilities in the @value{which-treelang}
180 version of @code{treelang}.
183 This manual documents how to maintain @code{treelang}.
184 It also documents the features and incompatibilities in the @value{which-treelang}
185 version of @code{treelang}.
193 * GNU Free Documentation License::
196 * What is GNU Treelang?::
199 * Compiler Overview::
203 * treelang internals::
211 --- The Detailed Node Listing ---
215 * Interoperating with C and C++::
220 * treelang compiler interfaces::
223 treelang compiler interfaces
226 * treelang main compiler::
228 treelang main compiler
230 * Interfacing to toplev.c::
231 * Interfacing to the garbage collection::
232 * Interfacing to the code generation code. ::
247 @unnumbered Contributors to GNU Treelang
251 Treelang was based on 'toy' by Richard Kenner, and also uses code from
252 the GCC core code tree. Tim Josling first created the language and
253 documentation, based on the GCC Fortran compiler's documentation
254 framework. Treelang was updated to use the TreeSSA infrastructure by
259 The packaging and compiler portions of GNU Treelang are based largely
261 @xref{Contributors,,Contributors to GCC,GCC,Using and Maintaining GCC},
262 for more information.
265 There is no specific run-time library for treelang, other than the
269 It would have been difficult to build treelang without access to Joachim
270 Nadler's guide to writing a front end to GCC (written in German). A
271 translation of this document into English is available via the
272 CobolForGCC project or via the documentation links from the GCC home
273 page @uref{http://gcc.gnu.org}.
276 @include funding.texi
278 @node Getting Started
279 @chapter Getting Started
280 @cindex getting started
285 Treelang is a sample language, useful only to help people understand how
286 to implement a new language front end to GCC. It is not a useful
287 language in itself other than as an example or basis for building a new
288 language. Therefore only language developers are likely to have an
291 This manual assumes familiarity with GCC, which you can obtain by using
292 it and by reading the manuals @samp{Using the GNU Compiler Collection (GCC)}
293 and @samp{GNU Compiler Collection (GCC) Internals}.
295 To install treelang, follow the GCC installation instructions,
296 taking care to ensure you specify treelang in the configure step by adding
297 treelang to the list of languages specified by @option{--enable-langauges},
298 e.g.@: @samp{--enable-languages=all,treelang}.
300 If you're generally curious about the future of
301 @code{treelang}, see @ref{Projects}.
302 If you're curious about its past,
303 see @ref{Contributors}.
305 To see a few of the questions maintainers of @code{treelang} have,
306 and that you might be able to answer,
307 see @ref{Open Questions}.
310 @node What is GNU Treelang?, Lexical Syntax, Getting Started, Top
311 @chapter What is GNU Treelang?
312 @cindex concepts, basic
313 @cindex basic concepts
315 GNU Treelang, or @code{treelang}, is designed initially as a free
316 replacement for, or alternative to, the 'toy' language, but which is
317 amenable to inclusion within the GCC source tree.
319 @code{treelang} is largely a cut down version of C, designed to showcase
320 the features of the GCC code generation back end. Only those features
321 that are directly supported by the GCC code generation back end are
322 implemented. Features are implemented in a manner which is easiest and
323 clearest to implement. Not all or even most code generation back end
324 features are implemented. The intention is to add features incrementally
325 until most features of the GCC back end are implemented in treelang.
327 The main features missing are structures, arrays and pointers.
329 A sample program follows:
332 // @r{function prototypes}
333 // @r{function 'add' taking two ints and returning an int}
334 external_definition int add(int arg1, int arg2);
335 external_definition int subtract(int arg3, int arg4);
336 external_definition int first_nonzero(int arg5, int arg6);
337 external_definition int double_plus_one(int arg7);
339 // @r{function definition}
342 // @r{return the sum of arg1 and arg2}
354 // @r{aaa is a variable, of type integer and allocated at the start of}
357 // @r{set aaa to the value returned from add, when passed arg7 and arg7 as}
358 // @r{the two parameters}
361 aaa=subtract(subtract(aaa, arg7), arg7) + 1;
367 // @r{C-like if statement}
379 @node Lexical Syntax, Parsing Syntax, What is GNU Treelang?, Top
380 @chapter Lexical Syntax
381 @cindex Lexical Syntax
383 Treelang programs consist of whitespace, comments, keywords and names.
387 Whitespace consists of the space character, a tab, and the end of line
388 character. Line terminations are as defined by the
389 standard C library. Whitespace is ignored except within comments,
390 and where it separates parts of the program. In the example below, A and
391 B are two separate names separated by whitespace.
398 Comments consist of @samp{//} followed by any characters up to the end
399 of the line. C style comments (/* */) are not supported. For example,
400 the assignment below is followed by a not very helpful comment.
403 x = 1; // @r{Set X to 1}
407 Keywords consist of any of the following reserved words or symbols:
411 used to start the statements in a function
413 used to end the statements in a function
415 start list of function arguments, or to change the precedence of operators in
418 end list or prioritized operators in expression
420 used to separate parameters in a function prototype or in a function call
422 used to end a statement
424 addition, or unary plus for signed literals
426 subtraction, or unary minus for signed literals
434 begin 'else' portion of IF statement
436 indicate variable is permanent, or function has file scope only
438 indicate that variable is allocated for the life of the current scope
439 @item external_reference
440 indicate that variable or function is defined in another file
441 @item external_definition
442 indicate that variable or function is to be accessible from other files
444 variable is an integer (same as C int)
446 variable is a character (same as C char)
448 variable is unsigned. If this is not present, the variable is signed
450 start function return statement
452 used as function type to indicate function returns nothing
457 Names consist of any letter or "_" followed by any number of letters,
458 numbers, or "_". "$" is not allowed in a name. All names must be globally
459 unique, i.e. may not be used twice in any context, and must
460 not be a keyword. Names and keywords are case sensitive. For example:
466 are all different names.
470 @node Parsing Syntax, Compiler Overview, Lexical Syntax, Top
471 @chapter Parsing Syntax
472 @cindex Parsing Syntax
474 Declarations are built up from the lexical elements described above. A
475 file may contain one of more declarations.
480 declaration: variable declaration OR function prototype OR function declaration
483 Function Prototype: storage type NAME ( optional_parameter_list )
486 static int add (int a, int b)
490 variable_declaration: storage type NAME initial;
498 A variable declaration can be outside a function, or at the start of a
502 storage: automatic OR static OR external_reference OR external_definition
504 This defines the scope, duration and visibility of a function or variable
509 automatic: This means a variable is allocated at start of the current scope and
510 released when the current scope is exited. This can only be used for variables
511 within functions. It cannot be used for functions.
514 static: This means a variable is allocated at start of program and
515 remains allocated until the program as a whole ends. For a function, it
516 means that the function is only visible within the current file.
519 external_definition: For a variable, which must be defined outside a
520 function, it means that the variable is visible from other files. For a
521 function, it means that the function is visible from another file.
524 external_reference: For a variable, which must be defined outside a
525 function, it means that the variable is defined in another file. For a
526 function, it means that the function is defined in another file.
531 type: int OR unsigned int OR char OR unsigned char OR void
533 This defines the data type of a variable or the return type of a function.
538 int: The variable is a signed integer. The function returns a signed integer.
541 unsigned int: The variable is an unsigned integer. The function returns an unsigned integer.
544 char: The variable is a signed character. The function returns a signed character.
547 unsigned char: The variable is an unsigned character. The function returns an unsigned character.
552 parameter_list OR parameter [, parameter]...
555 parameter: variable_declaration ,
557 The variable declarations must not have initializations.
563 value: integer_constant
565 Values without a unary plus or minus are considered to be unsigned.
571 function_declaration: name @{ variable_declarations statements @}
573 A function consists of the function name then the declarations (if any)
574 and statements (if any) within one pair of braces.
576 The details of the function arguments come from the function
577 prototype. The function prototype must precede the function declaration
581 statement: if_statement OR expression_statement OR return_statement
584 if_statement: if ( expression ) @{ variable_declarations statements @}
585 else @{ variable_declarations statements @}
587 The first lot of statements is executed if the expression is
588 nonzero. Otherwise the second lot of statements is executed. Either
589 list of statements may be empty, but both sets of braces and the else must be present.
603 expression_statement: expression;
605 The expression is executed, including any side effects.
608 return_statement: return expression_opt;
610 Returns from the function. If the function is void, the expression must
611 be absent, and if the function is not void the expression must be
615 expression: variable OR integer_constant OR expression + expression
616 OR expression - expression OR expression == expression OR ( expression )
617 OR variable = expression OR function_call
619 An expression can be a constant or a variable reference or a
620 function_call. Expressions can be combined as a sum of two expressions
621 or the difference of two expressions, or an equality test of two
622 expresions. An assignment is also an expression. Expresions and operator
623 precedence work as in C.
626 function_call: function_name ( optional_comma_separated_expressions )
628 This invokes the function, passing to it the values of the expressions
629 as actual parameters.
634 @node Compiler Overview, TREELANG and GCC, Parsing Syntax, Top
635 @chapter Compiler Overview
636 treelang is run as part of the GCC compiler.
644 It reads a user's program, stored in a file and containing instructions
645 written in the appropriate language (Treelang, C, and so on). This file
646 contains @dfn{source code}.
648 @cindex translation of user programs
650 @cindex code, machine
653 It translates the user's program into instructions a computer can carry
654 out more quickly than it takes to translate the instructions in the
655 first place. These instructions are called @dfn{machine code}---code
656 designed to be efficiently translated and processed by a machine such as
657 a computer. Humans usually aren't as good writing machine code as they
658 are at writing Treelang or C, because it is easy to make tiny mistakes
659 writing machine code. When writing Treelang or C, it is easy to make
660 big mistakes. But you can only make one mistake, because the compiler
661 stops after it finds any problem.
664 @cindex bugs, finding
665 @cindex @code{gdb}, command
666 @cindex commands, @code{gdb}
668 It provides information in the generated machine code
669 that can make it easier to find bugs in the program
670 (using a debugging tool, called a @dfn{debugger},
675 @cindex @code{ld} command
676 @cindex commands, @code{ld}
678 It locates and gathers machine code already generated to perform actions
679 requested by statements in the user's program. This machine code is
680 organized into @dfn{libraries} and is located and gathered during the
681 @dfn{link} phase of the compilation process. (Linking often is thought
682 of as a separate step, because it can be directly invoked via the
683 @code{ld} command. However, the @code{gcc} command, as with most
684 compiler commands, automatically performs the linking step by calling on
685 @code{ld} directly, unless asked to not do so by the user.)
687 @cindex language, incorrect use of
688 @cindex incorrect use of language
690 It attempts to diagnose cases where the user's program contains
691 incorrect usages of the language. The @dfn{diagnostics} produced by the
692 compiler indicate the problem and the location in the user's source file
693 where the problem was first noticed. The user can use this information
694 to locate and fix the problem.
696 The compiler stops after the first error. There are no plans to fix
697 this, ever, as it would vastly complicate the implementation of treelang
698 to little or no benefit.
700 @cindex diagnostics, incorrect
701 @cindex incorrect diagnostics
702 @cindex error messages, incorrect
703 @cindex incorrect error messages
704 (Sometimes an incorrect usage of the language leads to a situation where
705 the compiler can not make any sense of what it reads---while a human
706 might be able to---and thus ends up complaining about an incorrect
707 ``problem'' it encounters that, in fact, reflects a misunderstanding of
708 the programmer's intention.)
711 @cindex questionable instructions
713 There are few warnings in treelang. A program is either correct or in
714 error. The only exception to this is an expression in a return statement for
715 functions that return nothing.
718 @cindex components of treelang
719 @cindex @code{treelang}, components of
720 @code{treelang} consists of several components:
722 @cindex @code{gcc}, command
723 @cindex commands, @code{gcc}
726 A modified version of the @code{gcc} command, which also might be
727 installed as the system's @code{cc} command.
728 (In many cases, @code{cc} refers to the
729 system's ``native'' C compiler, which
730 might be a non-GNU compiler, or an older version
731 of @code{GCC} considered more stable or that is
732 used to build the operating system kernel.)
734 @cindex @code{treelang}, command
735 @cindex commands, @code{treelang}
737 The @code{treelang} command itself.
740 The @code{libc} run-time library. This library contains the machine
741 code needed to support capabilities of the Treelang language that are
742 not directly provided by the machine code generated by the
743 @code{treelang} compilation phase. This is the same library that the
744 main C compiler uses (libc).
746 @cindex @code{tree1}, program
747 @cindex programs, @code{tree1}
749 @cindex @code{as} command
750 @cindex commands, @code{as}
751 @cindex assembly code
752 @cindex code, assembly
754 The compiler itself, is internally named @code{tree1}.
756 Note that @code{tree1} does not generate machine code directly---it
757 generates @dfn{assembly code} that is a more readable form
758 of machine code, leaving the conversion to actual machine code
759 to an @dfn{assembler}, usually named @code{as}.
762 @code{GCC} is often thought of as ``the C compiler'' only,
763 but it does more than that.
764 Based on command-line options and the names given for files
765 on the command line, @code{gcc} determines which actions to perform, including
766 preprocessing, compiling (in a variety of possible languages), assembling,
769 @cindex driver, gcc command as
770 @cindex @code{gcc}, command as driver
771 @cindex executable file
772 @cindex files, executable
774 @cindex programs, cc1
777 @cindex programs, cpp
778 For example, the command @samp{gcc foo.c} @dfn{drives} the file
779 @file{foo.c} through the preprocessor @code{cpp}, then
780 the C compiler (internally named
781 @code{cc1}), then the assembler (usually @code{as}), then the linker
782 (@code{ld}), producing an executable program named @file{a.out} (on
785 @cindex treelang program
786 @cindex programs, treelang
787 As another example, the command @samp{gcc foo.tree} would do much the
788 same as @samp{gcc foo.c}, but instead of using the C compiler named
789 @code{cc1}, @code{gcc} would use the treelang compiler (named
790 @code{tree1}). However there is no preprocessor for treelang.
792 @cindex @code{tree1}, program
793 @cindex programs, @code{tree1}
794 In a GNU Treelang installation, @code{gcc} recognizes Treelang source
795 files by name just like it does C and C++ source files. It knows to use
796 the Treelang compiler named @code{tree1}, instead of @code{cc1} or
797 @code{cc1plus}, to compile Treelang files. If a file's name ends in
798 @code{.tree} then GCC knows that the program is written in treelang. You
799 can also manually override the language.
801 @cindex @code{gcc}, not recognizing Treelang source
802 @cindex unrecognized file format
803 @cindex file format not recognized
804 Non-Treelang-related operation of @code{gcc} is generally
805 unaffected by installing the GNU Treelang version of @code{gcc}.
806 However, without the installed version of @code{gcc} being the
807 GNU Treelang version, @code{gcc} will not be able to compile
808 and link Treelang programs.
810 @cindex printing version information
811 @cindex version information, printing
812 The command @samp{gcc -v x.tree} where @samp{x.tree} is a file which
813 must exist but whose contents are ignored, is a quick way to display
814 version information for the various programs used to compile a typical
815 Treelang source file.
817 The @code{tree1} program represents most of what is unique to GNU
818 Treelang; @code{tree1} is a combination of two rather large chunks of
821 @cindex GCC Back End (GBE)
823 @cindex @code{GCC}, back end
824 @cindex back end, GCC
825 @cindex code generator
826 One chunk is the so-called @dfn{GNU Back End}, or GBE,
827 which knows how to generate fast code for a wide variety of processors.
828 The same GBE is used by the C, C++, and Treelang compiler programs @code{cc1},
829 @code{cc1plus}, and @code{tree1}, plus others.
830 Often the GBE is referred to as the ``GCC back end'' or
831 even just ``GCC''---in this manual, the term GBE is used
832 whenever the distinction is important.
834 @cindex GNU Treelang Front End (TFE)
836 @cindex @code{treelang}, front end
837 @cindex front end, @code{treelang}
838 The other chunk of @code{tree1} is the majority of what is unique about
839 GNU Treelang---the code that knows how to interpret Treelang programs to
840 determine what they are intending to do, and then communicate that
841 knowledge to the GBE for actual compilation of those programs. This
842 chunk is called the @dfn{Treelang Front End} (TFE). The @code{cc1} and
843 @code{cc1plus} programs have their own front ends, for the C and C++
844 languages, respectively. These fronts ends are responsible for
845 diagnosing incorrect usage of their respective languages by the programs
846 the process, and are responsible for most of the warnings about
847 questionable constructs as well. (The GBE in principle handles
848 producing some warnings, like those concerning possible references to
849 undefined variables, but these warnings should not occur in treelang
850 programs as the front end is meant to pick them up first).
852 Because so much is shared among the compilers for various languages,
853 much of the behavior and many of the user-selectable options for these
854 compilers are similar.
855 For example, diagnostics (error messages and
856 warnings) are similar in appearance; command-line
857 options like @samp{-Wall} have generally similar effects; and the quality
858 of generated code (in terms of speed and size) is roughly similar
859 (since that work is done by the shared GBE).
861 @node TREELANG and GCC, Compiler, Compiler Overview, Top
862 @chapter Compile Treelang, C, or Other Programs
863 @cindex compiling programs
864 @cindex programs, compiling
866 @cindex @code{gcc}, command
867 @cindex commands, @code{gcc}
868 A GNU Treelang installation includes a modified version of the @code{gcc}
871 In a non-Treelang installation, @code{gcc} recognizes C, C++,
872 and Objective-C source files.
874 In a GNU Treelang installation, @code{gcc} also recognizes Treelang source
875 files and accepts Treelang-specific command-line options, plus some
876 command-line options that are designed to cater to Treelang users
877 but apply to other languages as well.
879 @xref{G++ and GCC,,Programming Languages Supported by GCC,GCC,Using
880 the GNU Compiler Collection (GCC)},
881 for information on the way different languages are handled
882 by the GCC compiler (@code{gcc}).
884 You can use this, combined with the output of the @samp{gcc -v x.tree}
885 command to get the options applicable to treelang. Treelang programs
886 must end with the suffix @samp{.tree}.
890 Treelang programs are not by default run through the C
891 preprocessor by @code{gcc}. There is no reason why they cannot be run through the
892 preprocessor manually, but you would need to prevent the preprocessor
893 from generating #line directives, using the @samp{-P} option, otherwise
894 tree1 will not accept the input.
896 @node Compiler, Other Languages, TREELANG and GCC, Top
897 @chapter The GNU Treelang Compiler
899 The GNU Treelang compiler, @code{treelang}, supports programs written
900 in the GNU Treelang language.
902 @node Other Languages, treelang internals, Compiler, Top
903 @chapter Other Languages
906 * Interoperating with C and C++::
909 @node Interoperating with C and C++, , Other Languages, Other Languages
910 @section Tools and advice for interoperating with C and C++
912 The output of treelang programs looks like C program code to the linker
913 and everybody else, so you should be able to freely mix treelang and C
914 (and C++) code, with one proviso.
916 C promotes small integer types to 'int' when used as function parameters and
917 return values in non-prototyped functions. Since treelang has no
918 non-prototyped functions, the treelang compiler does not do this.
921 @node treelang internals, Open Questions, Other Languages, Top
922 @chapter treelang internals
926 * treelang compiler interfaces::
930 @node treelang files, treelang compiler interfaces, treelang internals, treelang internals
931 @section treelang files
933 To create a compiler that integrates into GCC, you need create many
934 files. Some of the files are integrated into the main GCC makefile, to
935 build the various parts of the compiler and to run the test
936 suite. Others are incorporated into various GCC programs such as
937 @file{gcc.c}. Finally you must provide the actual programs comprising your
947 COPYING. This is the copyright file, assuming you are going to use the
948 GNU General Public Licence. You probably need to use the GPL because if
949 you use the GCC back end your program and the back end are one program,
950 and the back end is GPLed.
952 This need not be present if the language is incorporated into the main
953 GCC tree, as the main GCC directory has this file.
956 COPYING.LIB. This is the copyright file for those parts of your program
957 that are not to be covered by the GPL, but are instead to be covered by
958 the LGPL (Library or Lesser GPL). This licence may be appropriate for
959 the library routines associated with your compiler. These are the
960 routines that are linked with the @emph{output} of the compiler. Using
961 the LGPL for these programs allows programs written using your compiler
962 to be closed source. For example LIBC is under the LGPL.
964 This need not be present if the language is incorporated into the main
965 GCC tree, as the main GCC directory has this file.
968 ChangeLog. Record all the changes to your compiler. Use the same format
969 as used in treelang as it is supported by an emacs editing mode and is
970 part of the FSF coding standard. Normally each directory has its own
971 changelog. The FSF standard allows but does not require a meaningful
972 comment on why the changes were made, above and beyond @emph{why} they
973 were made. In the author's opinion it is useful to provide this
977 treelang.texi. The manual, written in texinfo. Your manual would have a
978 different file name. You need not write it in texinfo if you don't want
979 do, but a lot of GNU software does use texinfo.
983 Make-lang.in. This file is part of the make file which in incorporated
984 with the GCC make file skeleton (Makefile.in in the GCC directory) to
985 make Makefile, as part of the configuration process.
987 Makefile in turn is the main instruction to actually build
988 everything. The build instructions are held in the main GCC manual and
989 web site so they are not repeated here.
991 There are some comments at the top which will help you understand what
994 There are make commands to build things, remove generated files with
995 various degrees of thoroughness, count the lines of code (so you know
996 how much progress you are making), build info and html files from the
997 texinfo source, run the tests etc.
1000 README. Just a brief informative text file saying what is in this
1003 @cindex config-lang.in
1005 config-lang.in. This file is read by the configuration progress and must
1006 be present. You specify the name of your language, the name(s) of the
1007 compiler(s) incouding preprocessors you are going to build, whether any,
1008 usually generated, files should be excluded from diffs (ie when making
1009 diff files to send in patches). Whether the equate 'stagestuff' is used
1014 lang.opt. This file is included into @file{gcc.c}, the main GCC driver, and
1015 tells it what options your language supports. This is also used to
1018 @cindex lang-specs.h
1020 lang-specs.h. This file is also included in @file{gcc.c}. It tells
1021 @file{gcc.c} when to call your programs and what options to send them. The
1022 mini-language 'specs' is documented in the source of @file{gcc.c}. Do not
1023 attempt to write a specs file from scratch - use an existing one as the base
1027 Your texi files. Texinfo can be used to build documentation in HTML,
1028 info, dvi and postscript formats. It is a tagged language, is documented
1029 in its own manual, and has its own emacs mode.
1032 Your programs. The relationships between all the programs are explained
1033 in the next section. You need to write or use the following programs:
1038 lexer. This breaks the input into words and passes these to the
1039 parser. This is @file{lex.l} in treelang, which is passed through flex, a lex
1040 variant, to produce C code @file{lex.c}. Note there is a school of thought
1041 that says real men hand code their own lexers. However, you may prefer to
1042 write far less code and use flex, as was done with treelang.
1045 parser. This breaks the program into recognizable constructs such as
1046 expressions, statements etc. This is @file{parse.y} in treelang, which is
1047 passed through bison, which is a yacc variant, to produce C code
1051 back end interface. This interfaces to the code generation back end. In
1052 treelang, this is @file{tree1.c} which mainly interfaces to @file{toplev.c} and
1053 @file{treetree.c} which mainly interfaces to everything else. Many languages
1054 mix up the back end interface with the parser, as in the C compiler for
1055 example. It is a matter of taste which way to do it, but with treelang
1056 it is separated out to make the back end interface cleaner and easier to
1060 header files. For function prototypes and common data items. One point
1061 to note here is that bison can generate a header files with all the
1062 numbers is has assigned to the keywords and symbols, and you can include
1063 the same header in your lexer. This technique is demonstrated in
1067 compiler main file. GCC comes with a file @file{toplev.c} which is a
1068 perfectly serviceable main program for your compiler. GNU Treelang uses
1069 @file{toplev.c} but other languages have been known to replace it with their
1070 own main program. Again this is a matter of taste and how much code you
1077 @node treelang compiler interfaces, Hints and tips, treelang files, treelang internals
1078 @section treelang compiler interfaces
1085 * treelang main compiler::
1088 @node treelang driver, treelang main compiler, treelang compiler interfaces, treelang compiler interfaces
1089 @subsection treelang driver
1091 The GCC compiler consists of a driver, which then executes the various
1092 compiler phases based on the instructions in the specs files.
1094 Typically a program's language will be identified from its suffix
1095 (e.g., @file{.tree}) for treelang programs.
1097 The driver (@file{gcc.c}) will then drive (exec) in turn a preprocessor,
1098 the main compiler, the assembler and the link editor. Options to GCC allow you
1099 to override all of this. In the case of treelang programs there is no
1100 preprocessor, and mostly these days the C preprocessor is run within the
1101 main C compiler rather than as a separate process, apparently for reasons of speed.
1103 You will be using the standard assembler and linkage editor so these are
1104 ignored from now on.
1106 You have to write your own preprocessor if you want one. This is usually
1107 totally language specific. The main point to be aware of is to ensure
1108 that you find some way to pass file name and line number information
1109 through to the main compiler so that it can tell the back end this
1110 information and so the debugger can find the right source line for each
1111 piece of code. That is all there is to say about the preprocessor except
1112 that the preprocessor will probably not be the slowest part of the
1113 compiler and will probably not use the most memory so don't waste too
1114 much time tuning it until you know you need to do so.
1116 @node treelang main compiler, , treelang driver, treelang compiler interfaces
1117 @subsection treelang main compiler
1119 The main compiler for treelang consists of @file{toplev.c} from the main GCC
1120 compiler, the parser, lexer and back end interface routines, and the
1121 back end routines themselves, of which there are many.
1123 @file{toplev.c} does a lot of work for you and you should almost certainly
1126 Writing this code is the hard part of creating a compiler using GCC. The
1127 back end interface documentation is incomplete and the interface is
1130 There are three main aspects to interfacing to the other GCC code.
1133 * Interfacing to toplev.c::
1134 * Interfacing to the garbage collection::
1135 * Interfacing to the code generation code. ::
1138 @node Interfacing to toplev.c, Interfacing to the garbage collection, treelang main compiler, treelang main compiler
1139 @subsubsection Interfacing to toplev.c
1141 In treelang this is handled mainly in tree1.c
1142 and partly in treetree.c. Peruse toplev.c for details of what you need
1145 @node Interfacing to the garbage collection, Interfacing to the code generation code. , Interfacing to toplev.c, treelang main compiler
1146 @subsubsection Interfacing to the garbage collection
1148 Interfacing to the garbage collection. In treelang this is mainly in
1151 Memory allocation in the compiler should be done using the ggc_alloc and
1152 kindred routines in ggc*.*. At the end of every 'function' in your language, toplev.c calls
1153 the garbage collection several times. The garbage collection calls mark
1154 routines which go through the memory which is still used, telling the
1155 garbage collection not to free it. Then all the memory not used is
1158 What this means is that you need a way to hook into this marking
1159 process. This is done by calling ggc_add_root. This provides the address
1160 of a callback routine which will be called duing garbage collection and
1161 which can call ggc_mark to save the storage. If storage is only
1162 used within the parsing of a function, you do not need to provide a way
1165 Note that you can also call ggc_mark_tree to mark any of the back end
1166 internal 'tree' nodes. This routine will follow the branches of the
1167 trees and mark all the subordinate structures. This is useful for
1168 example when you have created a variable declaaration that will be used
1169 across multiple functions, or for a function declaration (from a
1170 prototype) that may be used later on. See the next item for more on the
1173 @node Interfacing to the code generation code. , , Interfacing to the garbage collection, treelang main compiler
1174 @subsubsection Interfacing to the code generation code.
1176 In treelang this is done in treetree.c. A typedef called 'tree' which is
1177 defined in tree.h and tree.def in the GCC directory and largely
1178 implemented in tree.c and stmt.c forms the basic interface to the
1181 In general you call various tree routines to generate code, either
1182 directly or through toplev.c. You build up data structures and
1183 expressions in similar ways.
1185 You can read some documentation on this which can be found via the GCC
1186 main web page. In particular, the documentation produced by Joachim
1187 Nadler and translated by Tim Josling can be quite useful. the C compiler
1188 also has documentation in the main GCC manual (particularly the current
1189 CVS version) which is useful on a lot of the details.
1191 In time it is hoped to enhance this document to provide a more
1192 comprehensive overview of this topic. The main gap is in explaining how
1193 it all works together.
1195 @node Hints and tips, , treelang compiler interfaces, treelang internals
1196 @section Hints and tips
1201 TAGS: Use the make ETAGS commands to create TAGS files which can be used in
1202 emacs to jump to any symbol quickly.
1205 GREP: grep is also a useful way to find all uses of a symbol.
1208 TREE: The main routines to look at are tree.h and tree.def. You will
1209 probably want a hardcopy of these.
1212 SAMPLE: look at the sample interfacing code in treetree.c. You can use
1213 gdb to trace through the code and learn about how it all works.
1216 GDB: the GCC back end works well with gdb. It traps abort() and allows
1217 you to trace back what went wrong.
1220 Error Checking: The compiler back end does some error and consistency
1221 checking. Often the result of an error is just no code being
1222 generated. You will then need to trace through and find out what is
1223 going wrong. The rtl dump files can help here also.
1226 rtl dump files: The main compiler documents these files which are dumps
1227 of the rtl (intermediate code) which is manipulated doing the code
1228 generation process. This can provide useful clues about what is going
1229 wrong. The rtl 'language' is documented in the main GCC manual.
1235 @node Open Questions, Bugs, treelang internals, Top
1236 @chapter Open Questions
1238 If you know GCC well, please consider looking at the file treetree.c and
1239 resolving any questions marked "???".
1241 @node Bugs, Service, Open Questions, Top
1242 @chapter Reporting Bugs
1244 @cindex reporting bugs
1246 You can report bugs to @email{@value{email-bugs}}. Please make
1247 sure bugs are real before reporting them. Follow the guidelines in the
1248 main GCC manual for submitting bug reports.
1254 @node Sending Patches, , Bugs, Bugs
1255 @section Sending Patches for GNU Treelang
1257 If you would like to write bug fixes or improvements for the GNU
1258 Treelang compiler, that is very helpful. Send suggested fixes to
1259 @email{@value{email-patches}}.
1261 @node Service, Projects, Bugs, Top
1262 @chapter How To Get Help with GNU Treelang
1264 If you need help installing, using or changing GNU Treelang, there are two
1270 Look in the service directory for someone who might help you for a fee.
1271 The service directory is found in the file named @file{SERVICE} in the
1275 Send a message to @email{@value{email-general}}.
1282 @node Projects, Index, Service, Top
1286 If you want to contribute to @code{treelang} by doing research,
1287 design, specification, documentation, coding, or testing,
1288 the following information should give you some ideas.
1290 Send a message to @email{@value{email-general}} if you plan to add a
1293 The main requirement for treelang is to add features and to add
1294 documentation. Features are things that the GCC back end can do but
1295 which are not reflected in treelang. Examples include structures,
1296 unions, pointers, arrays.
1300 @node Index, , Projects, Top