2002-11-21 Phil Edwards <pme@gcc.gnu.org>
[official-gcc.git] / gcc / treelang / treelang.texi
blob52bcb7ddd235c18400651d54fb0836d6c091165c
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!!!
5 @c NOTE THIS IS NOT A GOOD EXAMPLE OF HOW TO DO A MANUAL. FIXME!!!
8 @c %**start of header
9 @setfilename treelang.info
11 @set last-update 2001-07-30
12 @set copyrights-treelang 1995,1996,1997,1998,1999,2000,2001,2002
13 @c DEVELOPMENT is set to indicate an in-development version,
14 @c as compared to a release version.  When making a release
15 @c (e.g. a release branch in the CVS repository for GCC),
16 @c clear this and set the version information correctly.
17 @clear DEVELOPMENT
18 @set version-treelang 1.0
19 @set version-GCC 3.0
21 @set email-general gcc@@gcc.gnu.org
22 @set email-bugs gcc-bugs@@gcc.gnu.org or bug-gcc@@gnu.org
23 @set email-patches gcc-patches@@gcc.gnu.org 
24 @set path-treelang gcc/gcc/treelang
26 @set which-treelang GCC-@value{version-GCC}
27 @set which-GCC GCC
29 @set email-josling tej@@melbpc.org.au
30 @set www-josling http://www.geocities.com/timjosling
32 @c This tells @include'd files that they're part of the overall TREELANG doc
33 @c set.  (They might be part of a higher-level doc set too.)
34 @set DOC-TREELANG
36 @c @setfilename usetreelang.info
37 @c @setfilename maintaintreelang.info
38 @c To produce the full manual, use the "treelang.info" setfilename, and
39 @c make sure the following do NOT begin with '@c' (and the @clear lines DO)
40 @set INTERNALS
41 @set USING
42 @c To produce a user-only manual, use the "usetreelang.info" setfilename, and
43 @c make sure the following does NOT begin with '@c':
44 @c @clear INTERNALS
45 @c To produce a maintainer-only manual, use the "maintaintreelang.info" setfilename,
46 @c and make sure the following does NOT begin with '@c':
47 @c @clear USING
49 @c 6/27/96 FSF DO wants smallbook fmt for 1st bound edition. (from gcc.texi)
50 @c @smallbook
52 @c i also commented out the finalout command, so if there *are* any
53 @c overfulls, you'll (hopefully) see the rectangle in the right hand
54 @c margin. -- burley 1999-03-13 (from mew's comment in GCC.texi).
55 @c @finalout
57 @ifset INTERNALS
58 @ifset USING
59 @settitle Using and Maintaining GNU Treelang
60 @end ifset
61 @end ifset
62 @c seems reasonable to assume at least one of INTERNALS or USING is set...
63 @ifclear INTERNALS
64 @settitle Using GNU Treelang
65 @end ifclear
66 @ifclear USING
67 @settitle Maintaining GNU Treelang
68 @end ifclear
69 @c then again, have some fun
70 @ifclear INTERNALS
71 @ifclear USING
72 @settitle Doing Very Little at all with GNU Treelang
73 @end ifclear
74 @end ifclear
76 @syncodeindex fn cp
77 @syncodeindex vr cp
78 @c %**end of header
80 @c Cause even numbered pages to be printed on the left hand side of
81 @c the page and odd numbered pages to be printed on the right hand
82 @c side of the page.  Using this, you can print on both sides of a
83 @c sheet of paper and have the text on the same part of the sheet.
85 @c The text on right hand pages is pushed towards the right hand
86 @c margin and the text on left hand pages is pushed toward the left
87 @c hand margin.
88 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
90 @c @tex
91 @c \global\bindingoffset=0.75in
92 @c \global\normaloffset =0.75in
93 @c @end tex
95 @ifinfo
96 @dircategory Programming
97 @direntry
98 * treelang: (treelang).                  The GNU Treelang compiler.
99 @end direntry
100 @ifset INTERNALS
101 @ifset USING
102 This file documents the use and the internals of the GNU Treelang
103 (@code{treelang}) compiler. At the moment this manual is not
104 incorporated into the main GCC manual as it is too incomplete. It
105 corresponds to the @value{which-treelang} version of @code{treelang}.
106 @end ifset
107 @end ifset
108 @ifclear USING
109 This file documents the internals of the GNU Treelang (@code{treelang}) compiler.
110 It corresponds to the @value{which-treelang} version of @code{treelang}.
111 @end ifclear
112 @ifclear INTERNALS
113 This file documents the use of the GNU Treelang (@code{treelang}) compiler.
114 It corresponds to the @value{which-treelang} version of @code{treelang}.
115 @end ifclear
117 Published by the Free Software Foundation
118 59 Temple Place - Suite 330
119 Boston, MA 02111-1307 USA
121 Copyright (C) @value{copyrights-treelang} Free Software Foundation, Inc.
123 Permission is granted to copy, distribute and/or modify this document
124 under the terms of the GNU Free Documentation License, Version 1.1 or
125 any later version published by the Free Software Foundation; with the
126 Invariant Sections being ``GNU General Public License'', the Front-Cover
127 texts being (a) (see below), and with the Back-Cover Texts being (b)
128 (see below).  A copy of the license is included in the section entitled
129 ``GNU Free Documentation License''.
131 (a) The FSF's Front-Cover Text is:
133      A GNU Manual
135 (b) The FSF's Back-Cover Text is:
137      You have freedom to copy and modify this GNU Manual, like GNU
138      software.  Copies published by the Free Software Foundation raise
139      funds for GNU development.
140 @end ifinfo
142 treelang was Contributed by Tim Josling (@email{@value{email-josling}}).
143 Inspired by and based on the 'toy' language, written by Richard Kenner.
145 This document was written by Tim Josling, based on the GNU C++
146 documentation.
148 @setchapternewpage odd
149 @c @finalout
150 @titlepage
151 @ifset INTERNALS
152 @ifset USING
153 @center @titlefont{Using and Maintaining GNU Treelang}
155 @end ifset
156 @end ifset
157 @ifclear INTERNALS
158 @title Using GNU Treelang
159 @end ifclear
160 @ifclear USING
161 @title Maintaining GNU Treelang
162 @end ifclear
163 @sp 2
164 @center Tim Josling
165 @sp 3
166 @center Last updated @value{last-update}
167 @sp 1
168 @center for version @value{version-treelang}
169 @page
170 @vskip 0pt plus 1filll
171 Copyright @copyright{} @value{copyrights-treelang} Free Software Foundation, Inc.
172 @sp 2
173 For the @value{which-treelang} Version*
174 @sp 1
175 Published by the Free Software Foundation @*
176 59 Temple Place - Suite 330@*
177 Boston, MA 02111-1307, USA@*
178 @c Last printed ??ber, 19??.@*
179 @c Printed copies are available for $? each.@*
180 @c ISBN ???
181 @sp 1
182 Permission is granted to copy, distribute and/or modify this document
183 under the terms of the GNU Free Documentation License, Version 1.1 or
184 any later version published by the Free Software Foundation; with the
185 Invariant Sections being ``GNU General Public License'', the Front-Cover
186 texts being (a) (see below), and with the Back-Cover Texts being (b)
187 (see below).  A copy of the license is included in the section entitled
188 ``GNU Free Documentation License''.
190 (a) The FSF's Front-Cover Text is:
192      A GNU Manual
194 (b) The FSF's Back-Cover Text is:
196      You have freedom to copy and modify this GNU Manual, like GNU
197      software.  Copies published by the Free Software Foundation raise
198      funds for GNU development.
199 @end titlepage
200 @page
202 @ifinfo
204 @node Top, Copying,, (dir)
205 @top Introduction
206 @cindex Introduction
208 @ifset INTERNALS
209 @ifset USING
210 This manual documents how to run, install and maintain @code{treelang},
211 as well as its new features and incompatibilities,
212 and how to report bugs.
213 It corresponds to the @value{which-treelang} version of @code{treelang}.
214 @end ifset
215 @end ifset
217 @ifclear INTERNALS
218 This manual documents how to run and install @code{treelang},
219 as well as its new features and incompatibilities, and how to report
220 bugs.
221 It corresponds to the @value{which-treelang} version of @code{treelang}.
222 @end ifclear
223 @ifclear USING
224 This manual documents how to maintain @code{treelang}, as well as its
225 new features and incompatibilities, and how to report bugs.  It
226 corresponds to the @value{which-treelang} version of @code{treelang}.
227 @end ifclear
229 @end ifinfo
231 @ifset DEVELOPMENT
232 @emph{Warning:} This document is still under development, and might not
233 accurately reflect the @code{treelang} code base of which it is a part.
234 @end ifset
236 @menu
237 * Copying::                     
238 * Contributors::                
239 * GNU Free Documentation License::                
240 * Funding::                     
241 * Getting Started::             
242 * What is GNU Treelang?::       
243 * Lexical Syntax::              
244 * Parsing Syntax::              
245 * Compiler Overview::           
246 * TREELANG and GCC::            
247 * Compiler::                    
248 * Other Languages::             
249 * treelang internals::          
250 * Open Questions::              
251 * Bugs::                        
252 * Service::                     
253 * Projects::                    
254 * Index::                       
256 @detailmenu
257  --- The Detailed Node Listing ---
259 Other Languages
261 * Interoperating with C and C++::  
263 treelang internals
265 * treelang files::              
266 * treelang compiler interfaces::  
267 * Hints and tips::              
269 treelang compiler interfaces
271 * treelang driver::             
272 * treelang main compiler::      
274 treelang main compiler
276 * Interfacing to toplev.c::     
277 * Interfacing to the garbage collection::  
278 * Interfacing to the code generation code. ::  
280 Reporting Bugs
282 * Sending Patches::             
284 @end detailmenu
285 @end menu
287 @include gpl.texi
289 @include fdl.texi
291 @node Contributors
293 @unnumbered Contributors to GNU Treelang
294 @cindex contributors
295 @cindex credits
297 Treelang was based on 'toy' by Richard Kenner, and also uses code from
298 the GCC core code tree. Tim Josling first created the language and
299 documentation, based on the GCC Fortran compiler's documentation
300 framework.
302 @itemize @bullet
303 @item
304 The packaging and compiler portions of GNU Treelang are based largely
305 on the GCC compiler.
306 @xref{Contributors,,Contributors to GCC,GCC,Using and Maintaining GCC},
307 for more information.
309 @item
310 There is no specific run-time library for treelang, other than the
311 standard C runtime.
313 @item
314 It would have been difficult to build treelang without access to Joachim
315 Nadler's guide to writing a front end to GCC (written in German). A
316 translation of this document into English is available via the
317 CobolForGCC project or via the documentation links from the GCC home
318 page @uref{http://GCC.gnu.org}.
319 @end itemize
321 @include funding.texi
323 @node Getting Started
324 @chapter Getting Started
325 @cindex getting started
326 @cindex new users
327 @cindex newbies
328 @cindex beginners
330 Treelang is a sample language, useful only to help people understand how
331 to implement a new language front end to GCC. It is not a useful
332 language in itself other than as an example or basis for building a new
333 language. Therefore only language developers are likely to have an
334 interest in it.
336 This manual assumes familiarity with GCC, which you can obtain by using
337 it and by reading the manual @samp{Using and Porting GCC}.
339 To install treelang, follow the GCC installation instructions, 
340 taking care to ensure you specify treelang in the configure step.
342 If you're generally curious about the future of
343 @code{treelang}, see @ref{Projects}.
344 If you're curious about its past,
345 see @ref{Contributors}.
347 To see a few of the questions maintainers of @code{treelang} have,
348 and that you might be able to answer,
349 see @ref{Open Questions}.
351 @ifset USING
352 @node What is GNU Treelang?, Lexical Syntax, Getting Started, Top
353 @chapter What is GNU Treelang?
354 @cindex concepts, basic
355 @cindex basic concepts
357 GNU Treelang, or @code{treelang}, is designed initially as a free
358 replacement for, or alternative to, the 'toy' language, but which is
359 amenable to inclusion within the GCC source tree. 
361 @code{treelang} is largely a cut down version of C, designed to showcase
362 the features of the GCC code generation back end. Only those features
363 that are directly supported by the GCC code generation back end are
364 implemented. Features are implemented in a manner which is easiest and
365 clearest to implement. Not all or even most code generation back end
366 features are implemented. The intention is to add features incrementally
367 until most features of the GCC back end are implemented in treelang.
369 The main features missing are structures, arrays and pointers.
371 A sample program follows:
373 @example
374 // function prototypes
375 // function 'add' taking two ints and returning an int
376 external_definition int add(int arg1, int arg2);
377 external_definition int subtract(int arg3, int arg4);
378 external_definition int first_nonzero(int arg5, int arg6);
379 external_definition int double_plus_one(int arg7);
381 // function definition
382 add 
384 // return the sum of arg1 and arg2
385   return arg1 + arg2;
388         
389 subtract 
391   return arg3 - arg4;
394 double_plus_one
396 // aaa is a variable, of type integer and allocated at the start of the function
397   automatic int aaa;
398 // set aaa to the value returned from aaa, when passed arg7 and arg7 as the two parameters
399   aaa=add(arg7, arg7);
400   aaa=add(aaa, aaa);
401   aaa=subtract(subtract(aaa, arg7), arg7) + 1;
402   return aaa;
405 first_nonzero
407 // C-like if statement
408   if (arg5)
409     @{
410       return arg5;
411     @}
412   else
413     @{
414     @}
415   return arg6;
417 @end example
419 @node Lexical Syntax, Parsing Syntax, What is GNU Treelang?, Top
420 @chapter Lexical Syntax
421 @cindex Lexical Syntax
423 Treelang programs consist of whitespace, comments, keywords and names.
424 @itemize @bullet
426 @item
427 Whitespace consists of the space character and the end of line
428 character. Tabs are not allowed. Line terminations are as defined by the
429 standard C library. Whitespace is ignored except within comments,
430 and where it separates parts of the program. In the example below, A and
431 B are two separate names separated by whitespace. 
433 @smallexample
434 A B
435 @end smallexample
437 @item
438 Comments consist of @samp{//} followed by any characters up to the end
439 of the line. C style comments (/* */) are not supported. For example,
440 the assignment below is followed by a not very helpful comment.
442 @smallexample
443 x=1; // Set X to 1
444 @end smallexample
446 @item
447 Keywords consist of any reserved words or symbols as described
448 later. The list of keywords follows:
450 @smallexample
451 @{ - used to start the statements in a function
452 @} - used to end the statements in a function
453 ( - start list of function arguments, or to change the precedence of operators in an expression
454 ) - end list or prioritized operators in expression
455 , - used to separate parameters in a function prototype or in a function call 
456 ; - used to end a statement
457 + - addition
458 - - subtraction
459 = - assignment
460 == - equality test
461 if - begin IF statement
462 else - begin 'else' portion of IF statement
463 static - indicate variable is permanent, or function has file scope only
464 automatic - indicate that variable is allocated for the life of the function
465 external_reference - indicate that variable or function is defined in another file
466 external_definition - indicate that variable or function is to be accessible from other files
467 int - variable is an integer (same as C int) 
468 char - variable is a character (same as C char)
469 unsigned - variable is unsigned. If this is not present, the variable is signed
470 return - start function return statement
471 void - used as function type to indicate function returns nothing
472 @end smallexample
475 @item
476 Names consist of any letter or "_" followed by any number of letters or
477 numbers or "_". "$" is not allowed in a name. All names must be globally
478 unique - the same name may not be used twice in any context - and must
479 not be a keyword. Names and keywords are case sensitive. For example:
481 @smallexample
482 a A _a a_ IF_X
483 @end smallexample
485 are all different names.
487 @end itemize
489 @node Parsing Syntax, Compiler Overview, Lexical Syntax, Top
490 @chapter Parsing Syntax
491 @cindex Parsing Syntax
493 Declarations are built up from the lexical elements described above. A
494 file may contain one of more declarations.
496 @itemize @bullet
498 @item
499 declaration: variable declaration OR function prototype OR function declaration
501 @item
502 Function Prototype: storage type NAME ( parameter_list )
504 @smallexample
505 static int add (int a, int b)
506 @end smallexample
508 @item
509 variable_declaration: storage type NAME initial;
511 Example:
513 @smallexample
514 int temp1=1;
515 @end smallexample
517 A variable declaration can be outside a function, or at the start of a function.
519 @item
520 storage: automatic OR static OR external_reference OR external_definition
522 This defines the scope, duration and visibility of a function or variable
524 @enumerate 1
526 @item 
527 automatic: This means a variable is allocated at start of function and
528 released when the function returns. This can only be used for variables
529 within functions. It cannot be used for functions.
531 @item 
532 static: This means a variable is allocated at start of program and
533 remains allocated until the program as a whole ends. For a function, it
534 means that the function is only visible within the current file.
536 @item
537 external_definition: For a variable, which must be defined outside a
538 function, it means that the variable is visible from other files. For a
539 function, it means that the function is visible from another file.
541 @item
542 external_reference: For a variable, which must be defined outside a
543 function, it means that the variable is defined in another file. For a
544 function, it means that the function is defined in another file.
546 @end enumerate
548 @item
549 type: int OR unsigned int OR char OR unsigned char OR void
551 This defines the data type of a variable or the return type of a function.
553 @enumerate a
555 @item 
556 int: The variable is a signed integer. The function returns a signed integer.
558 @item 
559 unsigned int: The variable is an unsigned integer. The function returns an unsigned integer.
561 @item 
562 char: The variable is a signed character. The function returns a signed character.
564 @item 
565 unsigned char: The variable is an unsigned character. The function returns an unsigned character.
567 @end enumerate
569 @item
570 parameter_list OR parameter [, parameter]...
572 @item
573 parameter: variable_declaration ,
575 The variable declarations must not have initialisations.
577 @item 
578 initial: = value
580 @item
581 value: integer_constant
583 @smallexample
584 eg 1 +2 -3
585 @end smallexample
587 @item
588 function_declaration: name @{variable_declarations statements @}
590 A function consists of the function name then the declarations (if any)
591 and statements (if any) within one pair of braces.
593 The details of the function arguments come from the function
594 prototype. The function prototype must precede the function declaration
595 in the file.
597 @item
598 statement: if_statement OR expression_statement OR return_statement
600 @item
601 if_statement: if (expression) @{ statements @} else @{ statements @}
603 The first lot of statements is executed if the expression is
604 nonzero. Otherwise the second lot of statements is executed. Either
605 list of statements may be empty, but both sets of braces and the else must be present. 
607 @smallexample
608 if (a==b) 
610 // nothing
612 else
614 a=b;
616 @end smallexample
618 @item
619 expression_statement: expression;
621 The expression is executed and any side effects, such 
623 @item
624 return_statement: return expression_opt;
626 Returns from the function. If the function is void, the expression must
627 be absent, and if the function is not void the expression must be
628 present.
630 @item
631 expression: variable OR integer_constant OR expression+expression OR expression-expression
632  OR expression==expression OR (expression) OR variable=expression OR function_call
634 An expression can be a constant or a variable reference or a
635 function_call. Expressions can be combined as a sum of two expressions
636 or the difference of two expressions, or an equality test of two
637 expresions. An assignment is also an expression. Expresions and operator
638 precedence work as in C.
640 @item
641 function_call: function_name (comma_separated_expressions)
643 This invokes the function, passing to it the values of the expressions
644 as actual parameters.
646 @end itemize
648 @cindex compilers
649 @node Compiler Overview, TREELANG and GCC, Parsing Syntax, Top
650 @chapter Compiler Overview
651 treelang is run as part of the GCC compiler. 
653 @itemize @bullet
654 @cindex source code
655 @cindex file, source
656 @cindex code, source
657 @cindex source file
658 @item
659 It reads a user's program, stored in a file and containing instructions
660 written in the appropriate language (Treelang, C, and so on).  This file
661 contains @dfn{source code}.
663 @cindex translation of user programs
664 @cindex machine code
665 @cindex code, machine
666 @cindex mistakes
667 @item
668 It translates the user's program into instructions a computer can carry
669 out more quickly than it takes to translate the instructions in the
670 first place.  These instructions are called @dfn{machine code}---code
671 designed to be efficiently translated and processed by a machine such as
672 a computer.  Humans usually aren't as good writing machine code as they
673 are at writing Treelang or C, because it is easy to make tiny mistakes
674 writing machine code.  When writing Treelang or C, it is easy to make
675 big mistakes. But you can only make one mistake, because the compiler
676 stops after it finds any problem.
678 @cindex debugger
679 @cindex bugs, finding
680 @cindex @code{gdb}, command
681 @cindex commands, @code{gdb}
682 @item
683 It provides information in the generated machine code
684 that can make it easier to find bugs in the program
685 (using a debugging tool, called a @dfn{debugger},
686 such as @code{gdb}).
688 @cindex libraries
689 @cindex linking
690 @cindex @code{ld} command
691 @cindex commands, @code{ld}
692 @item
693 It locates and gathers machine code already generated to perform actions
694 requested by statements in the user's program.  This machine code is
695 organized into @dfn{libraries} and is located and gathered during the
696 @dfn{link} phase of the compilation process.  (Linking often is thought
697 of as a separate step, because it can be directly invoked via the
698 @code{ld} command.  However, the @code{gcc} command, as with most
699 compiler commands, automatically performs the linking step by calling on
700 @code{ld} directly, unless asked to not do so by the user.)
702 @cindex language, incorrect use of
703 @cindex incorrect use of language
704 @item
705 It attempts to diagnose cases where the user's program contains
706 incorrect usages of the language.  The @dfn{diagnostics} produced by the
707 compiler indicate the problem and the location in the user's source file
708 where the problem was first noticed.  The user can use this information
709 to locate and fix the problem.
711 The compiler stops after the first error. There are no plans to fix
712 this, ever, as it would vastly complicate the implementation of treelang
713 to little or no benefit.
715 @cindex diagnostics, incorrect
716 @cindex incorrect diagnostics
717 @cindex error messages, incorrect
718 @cindex incorrect error messages
719 (Sometimes an incorrect usage of the language leads to a situation where
720 the compiler can not make any sense of what it reads---while a human
721 might be able to---and thus ends up complaining about an incorrect
722 ``problem'' it encounters that, in fact, reflects a misunderstanding of
723 the programmer's intention.)
725 @cindex warnings
726 @cindex questionable instructions
727 @item
728 There are no warnings in treelang. A program is either correct or in
729 error.
730 @end itemize
732 @cindex components of treelang
733 @cindex @code{treelang}, components of
734 @code{treelang} consists of several components:
736 @cindex @code{gcc}, command
737 @cindex commands, @code{gcc}
738 @itemize @bullet
739 @item
740 A modified version of the @code{gcc} command, which also might be
741 installed as the system's @code{cc} command.
742 (In many cases, @code{cc} refers to the
743 system's ``native'' C compiler, which
744 might be a non-GNU compiler, or an older version
745 of @code{GCC} considered more stable or that is
746 used to build the operating system kernel.)
748 @cindex @code{treelang}, command
749 @cindex commands, @code{treelang}
750 @item
751 The @code{treelang} command itself.
753 @item
754 The @code{libc} run-time library.  This library contains the machine
755 code needed to support capabilities of the Treelang language that are
756 not directly provided by the machine code generated by the
757 @code{treelang} compilation phase. This is the same library that the
758 main c compiler uses (libc).
760 @cindex @code{tree1}, program
761 @cindex programs, @code{tree1}
762 @cindex assembler
763 @cindex @code{as} command
764 @cindex commands, @code{as}
765 @cindex assembly code
766 @cindex code, assembly
767 @item
768 The compiler itself, is internally named @code{tree1}.
770 Note that @code{tree1} does not generate machine code directly---it
771 generates @dfn{assembly code} that is a more readable form
772 of machine code, leaving the conversion to actual machine code
773 to an @dfn{assembler}, usually named @code{as}.
774 @end itemize
776 @code{GCC} is often thought of as ``the C compiler'' only,
777 but it does more than that.
778 Based on command-line options and the names given for files
779 on the command line, @code{gcc} determines which actions to perform, including
780 preprocessing, compiling (in a variety of possible languages), assembling,
781 and linking.
783 @cindex driver, gcc command as
784 @cindex @code{gcc}, command as driver
785 @cindex executable file
786 @cindex files, executable
787 @cindex cc1 program
788 @cindex programs, cc1
789 @cindex preprocessor
790 @cindex cpp program
791 @cindex programs, cpp
792 For example, the command @samp{gcc foo.c} @dfn{drives} the file
793 @file{foo.c} through the preprocessor @code{cpp}, then
794 the C compiler (internally named
795 @code{cc1}), then the assembler (usually @code{as}), then the linker
796 (@code{ld}), producing an executable program named @file{a.out} (on
797 UNIX systems).
799 @cindex treelang program
800 @cindex programs, treelang
801 As another example, the command @samp{gcc foo.tree} would do much the
802 same as @samp{gcc foo.c}, but instead of using the C compiler named
803 @code{cc1}, @code{gcc} would use the treelang compiler (named
804 @code{tree1}). However there is no preprocessor for treelang.
806 @cindex @code{tree1}, program
807 @cindex programs, @code{tree1}
808 In a GNU Treelang installation, @code{gcc} recognizes Treelang source
809 files by name just like it does C and C++ source files.  It knows to use
810 the Treelang compiler named @code{tree1}, instead of @code{cc1} or
811 @code{cc1plus}, to compile Treelang files. If a file's name ends in
812 @code{.tree} then GCC knows that the program is written in treelang. You
813 can also manually override the language.
815 @cindex @code{gcc}, not recognizing Treelang source
816 @cindex unrecognized file format
817 @cindex file format not recognized
818 Non-Treelang-related operation of @code{gcc} is generally
819 unaffected by installing the GNU Treelang version of @code{gcc}.
820 However, without the installed version of @code{gcc} being the
821 GNU Treelang version, @code{gcc} will not be able to compile
822 and link Treelang programs.
824 @cindex printing version information
825 @cindex version information, printing
826 The command @samp{gcc -v x.tree} where @samp{x.tree} is a file which
827 must exist but whose contents are ignored, is a quick way to display
828 version information for the various programs used to compile a typical
829 Treelang source file. 
831 The @code{tree1} program represents most of what is unique to GNU
832 Treelang; @code{tree1} is a combination of two rather large chunks of
833 code.
835 @cindex GCC Back End (GBE)
836 @cindex GBE
837 @cindex @code{GCC}, back end
838 @cindex back end, GCC
839 @cindex code generator
840 One chunk is the so-called @dfn{GNU Back End}, or GBE,
841 which knows how to generate fast code for a wide variety of processors.
842 The same GBE is used by the C, C++, and Treelang compiler programs @code{cc1},
843 @code{cc1plus}, and @code{tree1}, plus others.
844 Often the GBE is referred to as the ``GCC back end'' or
845 even just ``GCC''---in this manual, the term GBE is used
846 whenever the distinction is important.
848 @cindex GNU Treelang Front End (TFE)
849 @cindex tree1
850 @cindex @code{treelang}, front end
851 @cindex front end, @code{treelang}
852 The other chunk of @code{tree1} is the majority of what is unique about
853 GNU Treelang---the code that knows how to interpret Treelang programs to
854 determine what they are intending to do, and then communicate that
855 knowledge to the GBE for actual compilation of those programs.  This
856 chunk is called the @dfn{Treelang Front End} (TFE).  The @code{cc1} and
857 @code{cc1plus} programs have their own front ends, for the C and C++
858 languages, respectively.  These fronts ends are responsible for
859 diagnosing incorrect usage of their respective languages by the programs
860 the process, and are responsible for most of the warnings about
861 questionable constructs as well.  (The GBE in principle handles
862 producing some warnings, like those concerning possible references to
863 undefined variables, but these warnings should not occur in treelang
864 programs as the front end is meant to pick them up first).
866 Because so much is shared among the compilers for various languages,
867 much of the behavior and many of the user-selectable options for these
868 compilers are similar.
869 For example, diagnostics (error messages and
870 warnings) are similar in appearance; command-line
871 options like @samp{-Wall} have generally similar effects; and the quality
872 of generated code (in terms of speed and size) is roughly similar
873 (since that work is done by the shared GBE).
875 @node TREELANG and GCC, Compiler, Compiler Overview, Top
876 @chapter Compile Treelang, C, or Other Programs
877 @cindex compiling programs
878 @cindex programs, compiling
880 @cindex @code{gcc}, command
881 @cindex commands, @code{gcc}
882 A GNU Treelang installation includes a modified version of the @code{gcc}
883 command.
885 In a non-Treelang installation, @code{gcc} recognizes C, C++,
886 and Objective-C source files.
888 In a GNU Treelang installation, @code{gcc} also recognizes Treelang source
889 files and accepts Treelang-specific command-line options, plus some
890 command-line options that are designed to cater to Treelang users
891 but apply to other languages as well.
893 @xref{G++ and GCC,,Compile C; C++; or Objective-C,GCC,Using and Porting GCC},
894 for information on the way different languages are handled
895 by the GCC compiler (@code{gcc}).
897 You can use this, combined with the output of the @samp{GCC -v x.tree}
898 command to get the options applicable to treelang. Treelang programs
899 must end with the suffix @samp{.tree}.
901 @cindex preprocessor
903 Treelang programs are not by default run through the C
904 preprocessor by @code{gcc}. There is no reason why they cannot be run through the
905 preprocessor manually, but you would need to prevent the preprocessor
906 from generating #line directives, using the @samp{-P} option, otherwise
907 tree1 will not accept the input.
909 @node Compiler, Other Languages, TREELANG and GCC, Top
910 @chapter The GNU Treelang Compiler
912 The GNU Treelang compiler, @code{treelang}, supports programs written
913 in the GNU Treelang language.
915 @node Other Languages, treelang internals, Compiler, Top
916 @chapter Other Languages
918 @menu
919 * Interoperating with C and C++::  
920 @end menu
922 @node Interoperating with C and C++,  , Other Languages, Other Languages
923 @section Tools and advice for interoperating with C and C++
925 The output of treelang programs looks like C program code to the linker
926 and everybody else, so you should be able to freely mix treelang and C
927 (and C++) code, with one proviso.
929 C promotes small integer types to 'int' when used as function parameters and 
930 return values. The treelang compiler does not do this, so if you want to interface
931 to C, you need to specify the promoted value, not the nominal value. 
933 @ifset INTERNALS
934 @node treelang internals, Open Questions, Other Languages, Top
935 @chapter treelang internals
937 @menu
938 * treelang files::              
939 * treelang compiler interfaces::  
940 * Hints and tips::              
941 @end menu
943 @node treelang files, treelang compiler interfaces, treelang internals, treelang internals
944 @section treelang files
946 To create a compiler that integrates into GCC, you need create many
947 files. Some of the files are integrated into the main GCC makefile, to
948 build the various parts of the compiler and to run the test
949 suite. Others are incorporated into various GCC programs such as
950 GCC.c. Finally you must provide the actual programs comprising your
951 compiler. 
953 @cindex files
955 The files are:
957 @enumerate 1
959 @item
960 COPYING. This is the copyright file, assuming you are going to use the
961 GNU General Public Licence. You probably need to use the GPL because if
962 you use the GCC back end your program and the back end are one program,
963 and the back end is GPLed.
965 This need not be present if the language is incorporated into the main
966 GCC tree, as the main GCC directory has this file. 
968 @item
969 COPYING.LIB. This is the copyright file for those parts of your program
970 that are not to be covered by the GPL, but are instead to be covered by
971 the LGPL (Library or Lesser GPL). This licence may be appropriate for
972 the library routines associated with your compiler. These are the
973 routines that are linked with the @emph{output} of the compiler. Using
974 the LGPL for these programs allows programs written using your compiler
975 to be closed source. For example LIBC is under the LGPL. 
977 This need not be present if the language is incorporated into the main
978 GCC tree, as the main GCC directory has this file. 
980 @item
981 ChangeLog. Record all the changes to your compiler. Use the same format
982 as used in treelang as it is supported by an emacs editing mode and is
983 part of the FSF coding standard. Normally each directory has its own
984 changelog. The FSF standard allows but does not require a meaningful
985 comment on why the changes were made, above and beyond @emph{why} they
986 were made. In the author's opinion it is useful to provide this
987 information.
989 @item
990 treelang.texi. The manual, written in texinfo. Your manual would have a
991 different file name. You need not write it in texinfo if you don't want
992 do, but a lot of GNU software does use texinfo. 
994 @cindex Make-lang.in
995 @item
996 Make-lang.in. This file is part of the make file which in incorporated
997 with the GCC make file skeleton (Makefile.in in the GCC directory) to
998 make Makefile, as part of the configuration process.
1000 Makefile in turn is the main instruction to actually build
1001 everything. The build instructions are held in the main GCC manual and
1002 web site so they are not repeated here. 
1004 There are some comments at the top which will help you understand what
1005 you need to do.
1007 There are make commands to build things, remove generated files with
1008 various degrees of thoroughness, count the lines of code (so you know
1009 how much progress you are making), build info and html files from the
1010 texinfo source, run the tests etc.
1012 @item
1013 README. Just a brief informative text file saying what is in this
1014 directory. 
1016 @cindex config-lang.in
1017 @item
1018 config-lang.in. This file is read by the configuration progress and must
1019 be present. You specify the name of your language, the name(s) of the
1020 compiler(s) incouding preprocessors you are going to build, whether any,
1021 usually generated, files should be excluded from diffs (ie when making
1022 diff files to send in patches). Whether the equate 'stagestuff' is used
1023 is unknown (???).
1025 @cindex lang-options
1026 @item
1027 lang-options. This file is included into GCC.c, the main GCC driver, and
1028 tells it what options your language supports. This is only used to
1029 display help (is this true ???).
1031 @cindex lang-specs
1032 @item
1033 lang-specs. This file is also included in GCC.c. It tells GCC.c when to
1034 call your programs and what options to send them. The mini-language
1035 'specs' is documented in the source of GCC.c. Do not attempt to write a
1036 specs file from scratch - use an existing one as the base and enhance
1037 it. 
1039 @item
1040 Your texi files. Texinfo can be used to build documentation in HTML,
1041 info, dvi and postscript formats. It is a tagged language, is documented
1042 in its own manual, and has its own emacs mode.
1044 @item
1045 Your programs. The relationships between all the programs are explained
1046 in the next section. You need to write or use the following programs:
1048 @itemize @bullet
1050 @item
1051 lexer. This breaks the input into words and passes these to the
1052 parser. This is lex.l in treelang, which is passed through flex, a lex
1053 variant, to produce C code lex.c. Note there is a school of thought that
1054 says real men hand code their own lexers, however you may prefer to
1055 write far less code and use flex, as was done with treelang.
1057 @item
1058 parser. This breaks the program into recognizable constructs such as
1059 expressions, statements etc. This is parse.y in treelang, which is
1060 passed through bison, which is a yacc variant, to produce C code parse.c.
1062 @item
1063 back end interface. This interfaces to the code generation back end. In
1064 treelang, this is tree1.c which mainly interfaces to toplev.c and
1065 treetree.c which mainly interfaces to everything else. Many languages
1066 mix up the back end interface with the parser, as in the C compiler for
1067 example. It is a matter of taste which way to do it, but with treelang
1068 it is separated out to make the back end interface cleaner and easier to
1069 understand.
1071 @item
1072 header files. For function prototypes and common data items. One point
1073 to note here is that bison can generate a header files with all the
1074 numbers is has assigned to the keywords and symbols, and you can include
1075 the same header in your lexer. This technique is demonstrated in
1076 treelang.
1078 @item
1079 compiler main file. GCC comes with a program toplev.c which is a
1080 perfectly serviceable main program for your compiler. treelang uses
1081 toplev.c but other languages have been known to replace it with their
1082 own main program. Again this is a matter of taste and how much code you
1083 want to write. 
1085 @end itemize
1087 @end enumerate
1089 @node treelang compiler interfaces, Hints and tips, treelang files, treelang internals
1090 @section treelang compiler interfaces
1092 @cindex driver
1093 @cindex toplev.c
1095 @menu
1096 * treelang driver::             
1097 * treelang main compiler::      
1098 @end menu
1100 @node treelang driver, treelang main compiler, treelang compiler interfaces, treelang compiler interfaces
1101 @subsection treelang driver
1103 The GCC compiler consists of a driver, which then executes the various
1104 compiler phases based on the instructions in the specs files. 
1106 Typically a program's language will be identified from its suffix (eg
1107 .tree) for treelang programs.
1109 The driver (gcc.c) will then drive (exec) in turn a preprocessor, the main
1110 compiler, the assembler and the link editor. Options to GCC allow you to
1111 override all of this. In the case of treelang programs there is no
1112 preprocessor, and mostly these days the C preprocessor is run within the
1113 main C compiler rather than as a separate process, apparently for reasons of speed.
1115 You will be using the standard assembler and linkage editor so these are
1116 ignored from now on. 
1118 You have to write your own preprocessor if you want one. This is usually
1119 totally language specific. The main point to be aware of is to ensure
1120 that you find some way to pass file name and line number information
1121 through to the main compiler so that it can tell the back end this
1122 information and so the debugger can find the right source line for each
1123 piece of code. That is all there is to say about the preprocessor except
1124 that the preprocessor will probably not be the slowest part of the
1125 compiler and will probably not use the most memory so don't waste too
1126 much time tuning it until you know you need to do so.
1128 @node treelang main compiler,  , treelang driver, treelang compiler interfaces
1129 @subsection treelang main compiler
1131 The main compiler for treelang consists of toplev.c from the main GCC
1132 compiler, the parser, lexer and back end interface routines, and the
1133 back end routines themselves, of which there are many.
1135 toplev.c does a lot of work for you and you should almost certainly use it,
1137 Writing this code is the hard part of creating a compiler using GCC. The
1138 back end interface documentation is incomplete and the interface is
1139 complex. 
1141 There are three main aspects to interfacing to the other GCC code. 
1143 @menu
1144 * Interfacing to toplev.c::     
1145 * Interfacing to the garbage collection::  
1146 * Interfacing to the code generation code. ::  
1147 @end menu
1149 @node Interfacing to toplev.c, Interfacing to the garbage collection, treelang main compiler, treelang main compiler
1150 @subsubsection Interfacing to toplev.c
1152 In treelang this is handled mainly in tree1.c
1153 and partly in treetree.c. Peruse toplev.c for details of what you need
1154 to do.
1156 @node Interfacing to the garbage collection, Interfacing to the code generation code. , Interfacing to toplev.c, treelang main compiler
1157 @subsubsection Interfacing to the garbage collection
1159 Interfacing to the garbage collection. In treelang this is mainly in
1160 tree1.c. 
1162 Memory allocation in the compiler should be done using the ggc_alloc and
1163 kindred routines in ggc*.*. At the end of every 'function' in your language, toplev.c calls
1164 the garbage collection several times. The garbage collection calls mark
1165 routines which go through the memory which is still used, telling the
1166 garbage collection not to free it. Then all the memory not used is
1167 freed.
1169 What this means is that you need a way to hook into this marking
1170 process. This is done by calling ggc_add_root. This provides the address
1171 of a callback routine which will be called duing garbage collection and
1172 which can call ggc_mark to save the storage. If storage is only
1173 used within the parsing of a function, you do not need to provide a way
1174 to mark it. 
1176 Note that you can also call ggc_mark_tree to mark any of the back end
1177 internal 'tree' nodes. This routine will follow the branches of the
1178 trees and mark all the subordinate structures. This is useful for
1179 example when you have created a variable declaaration that will be used
1180 across multiple functions, or for a function declaration (from a
1181 prototype) that may be used later on. See the next item for more on the
1182 tree nodes. 
1184 @node Interfacing to the code generation code. ,  , Interfacing to the garbage collection, treelang main compiler
1185 @subsubsection Interfacing to the code generation code. 
1187 In treelang this is done in treetree.c. A typedef called 'tree' which is
1188 defined in tree.h and tree.def in the GCC directory and largely
1189 implemented in tree.c and stmt.c forms the basic interface to the
1190 compiler back end.
1192 In general you call various tree routines to generate code, either
1193 directly or through toplev.c. You build up data structures and
1194 expressions in similar ways. 
1196 You can read some documentation on this which can be found via the GCC
1197 main web page. In particular, the documentation produced by Joachim
1198 Nadler and translated by Tim Josling can be quite useful. the C compiler
1199 also has documentation in the main GCC manual (particularly the current
1200 CVS version) which is useful on a lot of the details.
1202 In time it is hoped to enhance this document to provide a more
1203 comprehensive overview of this topic. The main gap is in explaining how
1204 it all works together. 
1206 @node Hints and tips,  , treelang compiler interfaces, treelang internals
1207 @section Hints and tips
1209 @itemize @bullet
1211 @item
1212 TAGS: Use the make ETAGS commands to create TAGS files which can be used in
1213 emacs to jump to any symbol quickly. 
1215 @item
1216 GREP: grep is also a useful way to find all uses of a symbol.
1218 @item
1219 TREE: The main routines to look at are tree.h and tree.def. You will
1220 probably want a hardcopy of these. 
1222 @item
1223 SAMPLE: look at the sample interfacing code in treetree.c. You can use
1224 gdb to trace through the code and learn about how it all works. 
1226 @item
1227 GDB: the GCC back end works well with gdb. It traps abort() and allows
1228 you to trace back what went wrong. 
1230 @item
1231 Error Checking: The compiler back end does some error and consistency
1232 checking. Often the result of an error is just no code being
1233 generated. You will then need to trace through and find out what is
1234 going wrong. The rtl dump files can help here also.
1236 @item
1237 rtl dump files: The main compiler documents these files which are dumps
1238 of the rtl (intermediate code) which is manipulated doing the code
1239 generation process. This can provide useful clues about what is going
1240 wrong. The rtl 'language' is documented in the main GCC manual.
1242 @end itemize
1244 @end ifset
1246 @node Open Questions, Bugs, treelang internals, Top
1247 @chapter Open Questions
1249 If you know GCC well, please consider looking at the file treetree.c and
1250 resolving any questions marked "???".
1252 @node Bugs, Service, Open Questions, Top
1253 @chapter Reporting Bugs
1254 @cindex bugs
1255 @cindex reporting bugs
1257 You can report bugs to @email{@value{email-bugs}}. Please make
1258 sure bugs are real before reporting them. Follow the guidelines in the
1259 main GCC manual for submitting bug reports.
1261 @menu
1262 * Sending Patches::             
1263 @end menu
1265 @node Sending Patches,  , Bugs, Bugs
1266 @section Sending Patches for GNU Treelang
1268 If you would like to write bug fixes or improvements for the GNU
1269 Treelang compiler, that is very helpful.  Send suggested fixes to
1270 @email{@value{email-patches}}.
1272 @node Service, Projects, Bugs, Top
1273 @chapter How To Get Help with GNU Treelang
1275 If you need help installing, using or changing GNU Treelang, there are two
1276 ways to find it:
1278 @itemize @bullet
1280 @item
1281 Look in the service directory for someone who might help you for a fee.
1282 The service directory is found in the file named @file{SERVICE} in the
1283 GCC distribution.
1285 @item
1286 Send a message to @email{@value{email-general}}.
1288 @end itemize
1290 @end ifset
1291 @ifset INTERNALS
1293 @node Projects, Index, Service, Top
1294 @chapter Projects
1295 @cindex projects
1297 If you want to contribute to @code{treelang} by doing research,
1298 design, specification, documentation, coding, or testing,
1299 the following information should give you some ideas.
1301 Send a message to @email{@value{email-general}} if you plan to add a
1302 feature.
1304 The main requirement for treelang is to add features and to add
1305 documentation. Features are things that the GCC back end can do but
1306 which are not reflected in treelang. Examples include structures,
1307 unions, pointers, arrays.
1309 @end ifset
1311 @node Index,  , Projects, Top
1312 @unnumbered Index
1314 @printindex cp
1315 @summarycontents
1316 @contents
1317 @bye