OSDN Git Service

501c4bfca953f8e3a264aa2912bedb11f733b9a4
[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 2001-07-30
16 @set copyrights-treelang 1995,1996,1997,1998,1999,2000,2001,2002
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,,Compile C; C++; or Objective-C,GCC,Using and Porting GCC},
889 for information on the way different languages are handled
890 by the GCC compiler (@code{gcc}).
891
892 You can use this, combined with the output of the @samp{GCC -v x.tree}
893 command to get the options applicable to treelang. Treelang programs
894 must end with the suffix @samp{.tree}.
895
896 @cindex preprocessor
897
898 Treelang programs are not by default run through the C
899 preprocessor by @code{gcc}. There is no reason why they cannot be run through the
900 preprocessor manually, but you would need to prevent the preprocessor
901 from generating #line directives, using the @samp{-P} option, otherwise
902 tree1 will not accept the input.
903
904 @node Compiler, Other Languages, TREELANG and GCC, Top
905 @chapter The GNU Treelang Compiler
906
907 The GNU Treelang compiler, @code{treelang}, supports programs written
908 in the GNU Treelang language.
909
910 @node Other Languages, treelang internals, Compiler, Top
911 @chapter Other Languages
912
913 @menu
914 * Interoperating with C and C++::  
915 @end menu
916
917 @node Interoperating with C and C++,  , Other Languages, Other Languages
918 @section Tools and advice for interoperating with C and C++
919
920 The output of treelang programs looks like C program code to the linker
921 and everybody else, so you should be able to freely mix treelang and C
922 (and C++) code, with one proviso.
923
924 C promotes small integer types to 'int' when used as function parameters and 
925 return values. The treelang compiler does not do this, so if you want to interface
926 to C, you need to specify the promoted value, not the nominal value. 
927
928 @ifset INTERNALS
929 @node treelang internals, Open Questions, Other Languages, Top
930 @chapter treelang internals
931
932 @menu
933 * treelang files::              
934 * treelang compiler interfaces::  
935 * Hints and tips::              
936 @end menu
937
938 @node treelang files, treelang compiler interfaces, treelang internals, treelang internals
939 @section treelang files
940
941 To create a compiler that integrates into GCC, you need create many
942 files. Some of the files are integrated into the main GCC makefile, to
943 build the various parts of the compiler and to run the test
944 suite. Others are incorporated into various GCC programs such as
945 GCC.c. Finally you must provide the actual programs comprising your
946 compiler. 
947
948 @cindex files
949
950 The files are:
951
952 @enumerate 1
953
954 @item
955 COPYING. This is the copyright file, assuming you are going to use the
956 GNU General Public Licence. You probably need to use the GPL because if
957 you use the GCC back end your program and the back end are one program,
958 and the back end is GPLed.
959
960 This need not be present if the language is incorporated into the main
961 GCC tree, as the main GCC directory has this file. 
962
963 @item
964 COPYING.LIB. This is the copyright file for those parts of your program
965 that are not to be covered by the GPL, but are instead to be covered by
966 the LGPL (Library or Lesser GPL). This licence may be appropriate for
967 the library routines associated with your compiler. These are the
968 routines that are linked with the @emph{output} of the compiler. Using
969 the LGPL for these programs allows programs written using your compiler
970 to be closed source. For example LIBC is under the LGPL. 
971
972 This need not be present if the language is incorporated into the main
973 GCC tree, as the main GCC directory has this file. 
974
975 @item
976 ChangeLog. Record all the changes to your compiler. Use the same format
977 as used in treelang as it is supported by an emacs editing mode and is
978 part of the FSF coding standard. Normally each directory has its own
979 changelog. The FSF standard allows but does not require a meaningful
980 comment on why the changes were made, above and beyond @emph{why} they
981 were made. In the author's opinion it is useful to provide this
982 information.
983
984 @item
985 treelang.texi. The manual, written in texinfo. Your manual would have a
986 different file name. You need not write it in texinfo if you don't want
987 do, but a lot of GNU software does use texinfo. 
988
989 @cindex Make-lang.in
990 @item
991 Make-lang.in. This file is part of the make file which in incorporated
992 with the GCC make file skeleton (Makefile.in in the GCC directory) to
993 make Makefile, as part of the configuration process.
994
995 Makefile in turn is the main instruction to actually build
996 everything. The build instructions are held in the main GCC manual and
997 web site so they are not repeated here. 
998
999 There are some comments at the top which will help you understand what
1000 you need to do.
1001
1002 There are make commands to build things, remove generated files with
1003 various degrees of thoroughness, count the lines of code (so you know
1004 how much progress you are making), build info and html files from the
1005 texinfo source, run the tests etc.
1006
1007 @item
1008 README. Just a brief informative text file saying what is in this
1009 directory. 
1010
1011 @cindex config-lang.in
1012 @item
1013 config-lang.in. This file is read by the configuration progress and must
1014 be present. You specify the name of your language, the name(s) of the
1015 compiler(s) incouding preprocessors you are going to build, whether any,
1016 usually generated, files should be excluded from diffs (ie when making
1017 diff files to send in patches). Whether the equate 'stagestuff' is used
1018 is unknown (???).
1019
1020 @cindex lang-options
1021 @item
1022 lang-options. This file is included into GCC.c, the main GCC driver, and
1023 tells it what options your language supports. This is only used to
1024 display help (is this true ???).
1025
1026 @cindex lang-specs
1027 @item
1028 lang-specs. This file is also included in GCC.c. It tells GCC.c when to
1029 call your programs and what options to send them. The mini-language
1030 'specs' is documented in the source of GCC.c. Do not attempt to write a
1031 specs file from scratch - use an existing one as the base and enhance
1032 it. 
1033
1034 @item
1035 Your texi files. Texinfo can be used to build documentation in HTML,
1036 info, dvi and postscript formats. It is a tagged language, is documented
1037 in its own manual, and has its own emacs mode.
1038
1039 @item
1040 Your programs. The relationships between all the programs are explained
1041 in the next section. You need to write or use the following programs:
1042
1043 @itemize @bullet
1044
1045 @item
1046 lexer. This breaks the input into words and passes these to the
1047 parser. This is lex.l in treelang, which is passed through flex, a lex
1048 variant, to produce C code lex.c. Note there is a school of thought that
1049 says real men hand code their own lexers, however you may prefer to
1050 write far less code and use flex, as was done with treelang.
1051
1052 @item
1053 parser. This breaks the program into recognizable constructs such as
1054 expressions, statements etc. This is parse.y in treelang, which is
1055 passed through bison, which is a yacc variant, to produce C code parse.c.
1056
1057 @item
1058 back end interface. This interfaces to the code generation back end. In
1059 treelang, this is tree1.c which mainly interfaces to toplev.c and
1060 treetree.c which mainly interfaces to everything else. Many languages
1061 mix up the back end interface with the parser, as in the C compiler for
1062 example. It is a matter of taste which way to do it, but with treelang
1063 it is separated out to make the back end interface cleaner and easier to
1064 understand.
1065
1066 @item
1067 header files. For function prototypes and common data items. One point
1068 to note here is that bison can generate a header files with all the
1069 numbers is has assigned to the keywords and symbols, and you can include
1070 the same header in your lexer. This technique is demonstrated in
1071 treelang.
1072
1073 @item
1074 compiler main file. GCC comes with a program toplev.c which is a
1075 perfectly serviceable main program for your compiler. treelang uses
1076 toplev.c but other languages have been known to replace it with their
1077 own main program. Again this is a matter of taste and how much code you
1078 want to write. 
1079
1080 @end itemize
1081
1082 @end enumerate
1083
1084 @node treelang compiler interfaces, Hints and tips, treelang files, treelang internals
1085 @section treelang compiler interfaces
1086
1087 @cindex driver
1088 @cindex toplev.c
1089
1090 @menu
1091 * treelang driver::             
1092 * treelang main compiler::      
1093 @end menu
1094
1095 @node treelang driver, treelang main compiler, treelang compiler interfaces, treelang compiler interfaces
1096 @subsection treelang driver
1097
1098 The GCC compiler consists of a driver, which then executes the various
1099 compiler phases based on the instructions in the specs files. 
1100
1101 Typically a program's language will be identified from its suffix (eg
1102 .tree) for treelang programs.
1103
1104 The driver (gcc.c) will then drive (exec) in turn a preprocessor, the main
1105 compiler, the assembler and the link editor. Options to GCC allow you to
1106 override all of this. In the case of treelang programs there is no
1107 preprocessor, and mostly these days the C preprocessor is run within the
1108 main C compiler rather than as a separate process, apparently for reasons of speed.
1109
1110 You will be using the standard assembler and linkage editor so these are
1111 ignored from now on. 
1112
1113 You have to write your own preprocessor if you want one. This is usually
1114 totally language specific. The main point to be aware of is to ensure
1115 that you find some way to pass file name and line number information
1116 through to the main compiler so that it can tell the back end this
1117 information and so the debugger can find the right source line for each
1118 piece of code. That is all there is to say about the preprocessor except
1119 that the preprocessor will probably not be the slowest part of the
1120 compiler and will probably not use the most memory so don't waste too
1121 much time tuning it until you know you need to do so.
1122
1123 @node treelang main compiler,  , treelang driver, treelang compiler interfaces
1124 @subsection treelang main compiler
1125
1126 The main compiler for treelang consists of toplev.c from the main GCC
1127 compiler, the parser, lexer and back end interface routines, and the
1128 back end routines themselves, of which there are many.
1129
1130 toplev.c does a lot of work for you and you should almost certainly use it,
1131
1132 Writing this code is the hard part of creating a compiler using GCC. The
1133 back end interface documentation is incomplete and the interface is
1134 complex. 
1135
1136 There are three main aspects to interfacing to the other GCC code. 
1137
1138 @menu
1139 * Interfacing to toplev.c::     
1140 * Interfacing to the garbage collection::  
1141 * Interfacing to the code generation code. ::  
1142 @end menu
1143
1144 @node Interfacing to toplev.c, Interfacing to the garbage collection, treelang main compiler, treelang main compiler
1145 @subsubsection Interfacing to toplev.c
1146
1147 In treelang this is handled mainly in tree1.c
1148 and partly in treetree.c. Peruse toplev.c for details of what you need
1149 to do.
1150
1151 @node Interfacing to the garbage collection, Interfacing to the code generation code. , Interfacing to toplev.c, treelang main compiler
1152 @subsubsection Interfacing to the garbage collection
1153
1154 Interfacing to the garbage collection. In treelang this is mainly in
1155 tree1.c. 
1156
1157 Memory allocation in the compiler should be done using the ggc_alloc and
1158 kindred routines in ggc*.*. At the end of every 'function' in your language, toplev.c calls
1159 the garbage collection several times. The garbage collection calls mark
1160 routines which go through the memory which is still used, telling the
1161 garbage collection not to free it. Then all the memory not used is
1162 freed.
1163
1164 What this means is that you need a way to hook into this marking
1165 process. This is done by calling ggc_add_root. This provides the address
1166 of a callback routine which will be called duing garbage collection and
1167 which can call ggc_mark to save the storage. If storage is only
1168 used within the parsing of a function, you do not need to provide a way
1169 to mark it. 
1170
1171 Note that you can also call ggc_mark_tree to mark any of the back end
1172 internal 'tree' nodes. This routine will follow the branches of the
1173 trees and mark all the subordinate structures. This is useful for
1174 example when you have created a variable declaaration that will be used
1175 across multiple functions, or for a function declaration (from a
1176 prototype) that may be used later on. See the next item for more on the
1177 tree nodes. 
1178
1179 @node Interfacing to the code generation code. ,  , Interfacing to the garbage collection, treelang main compiler
1180 @subsubsection Interfacing to the code generation code. 
1181
1182 In treelang this is done in treetree.c. A typedef called 'tree' which is
1183 defined in tree.h and tree.def in the GCC directory and largely
1184 implemented in tree.c and stmt.c forms the basic interface to the
1185 compiler back end.
1186
1187 In general you call various tree routines to generate code, either
1188 directly or through toplev.c. You build up data structures and
1189 expressions in similar ways. 
1190
1191 You can read some documentation on this which can be found via the GCC
1192 main web page. In particular, the documentation produced by Joachim
1193 Nadler and translated by Tim Josling can be quite useful. the C compiler
1194 also has documentation in the main GCC manual (particularly the current
1195 CVS version) which is useful on a lot of the details.
1196
1197 In time it is hoped to enhance this document to provide a more
1198 comprehensive overview of this topic. The main gap is in explaining how
1199 it all works together. 
1200
1201 @node Hints and tips,  , treelang compiler interfaces, treelang internals
1202 @section Hints and tips
1203
1204 @itemize @bullet
1205
1206 @item
1207 TAGS: Use the make ETAGS commands to create TAGS files which can be used in
1208 emacs to jump to any symbol quickly. 
1209
1210 @item
1211 GREP: grep is also a useful way to find all uses of a symbol.
1212
1213 @item
1214 TREE: The main routines to look at are tree.h and tree.def. You will
1215 probably want a hardcopy of these. 
1216
1217 @item
1218 SAMPLE: look at the sample interfacing code in treetree.c. You can use
1219 gdb to trace through the code and learn about how it all works. 
1220
1221 @item
1222 GDB: the GCC back end works well with gdb. It traps abort() and allows
1223 you to trace back what went wrong. 
1224
1225 @item
1226 Error Checking: The compiler back end does some error and consistency
1227 checking. Often the result of an error is just no code being
1228 generated. You will then need to trace through and find out what is
1229 going wrong. The rtl dump files can help here also.
1230
1231 @item
1232 rtl dump files: The main compiler documents these files which are dumps
1233 of the rtl (intermediate code) which is manipulated doing the code
1234 generation process. This can provide useful clues about what is going
1235 wrong. The rtl 'language' is documented in the main GCC manual.
1236
1237 @end itemize
1238
1239 @end ifset
1240
1241 @node Open Questions, Bugs, treelang internals, Top
1242 @chapter Open Questions
1243
1244 If you know GCC well, please consider looking at the file treetree.c and
1245 resolving any questions marked "???".
1246
1247 @node Bugs, Service, Open Questions, Top
1248 @chapter Reporting Bugs
1249 @cindex bugs
1250 @cindex reporting bugs
1251
1252 You can report bugs to @email{@value{email-bugs}}. Please make
1253 sure bugs are real before reporting them. Follow the guidelines in the
1254 main GCC manual for submitting bug reports.
1255
1256 @menu
1257 * Sending Patches::             
1258 @end menu
1259
1260 @node Sending Patches,  , Bugs, Bugs
1261 @section Sending Patches for GNU Treelang
1262
1263 If you would like to write bug fixes or improvements for the GNU
1264 Treelang compiler, that is very helpful.  Send suggested fixes to
1265 @email{@value{email-patches}}.
1266
1267 @node Service, Projects, Bugs, Top
1268 @chapter How To Get Help with GNU Treelang
1269
1270 If you need help installing, using or changing GNU Treelang, there are two
1271 ways to find it:
1272
1273 @itemize @bullet
1274
1275 @item
1276 Look in the service directory for someone who might help you for a fee.
1277 The service directory is found in the file named @file{SERVICE} in the
1278 GCC distribution.
1279
1280 @item
1281 Send a message to @email{@value{email-general}}.
1282
1283 @end itemize
1284
1285 @end ifset
1286 @ifset INTERNALS
1287
1288 @node Projects, Index, Service, Top
1289 @chapter Projects
1290 @cindex projects
1291
1292 If you want to contribute to @code{treelang} by doing research,
1293 design, specification, documentation, coding, or testing,
1294 the following information should give you some ideas.
1295
1296 Send a message to @email{@value{email-general}} if you plan to add a
1297 feature.
1298
1299 The main requirement for treelang is to add features and to add
1300 documentation. Features are things that the GCC back end can do but
1301 which are not reflected in treelang. Examples include structures,
1302 unions, pointers, arrays.
1303
1304 @end ifset
1305
1306 @node Index,  , Projects, Top
1307 @unnumbered Index
1308
1309 @printindex cp
1310 @summarycontents
1311 @contents
1312 @bye