OSDN Git Service

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