OSDN Git Service

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