--- gforth/Attic/gforth.ds 1997/02/01 14:59:30 1.43 +++ gforth/Attic/gforth.ds 1997/04/10 15:00:06 1.48 @@ -3,6 +3,10 @@ @comment %**start of header (This is for running Texinfo on a region.) @setfilename gforth.info @settitle Gforth Manual +@dircategory GNU programming tools +@direntry +* Gforth: (gforth). A fast interpreter for the Forth language. +@end direntry @comment @setchapternewpage odd @comment %**end of header (This is for running Texinfo on a region.) @@ -99,7 +103,7 @@ personal machines. This manual correspon * Concept Index:: A menu covering many topics @end menu -@node License, Preface, Top, Top +@node License, Goals, Top, Top @unnumbered GNU GENERAL PUBLIC LICENSE @center Version 2, June 1991 @@ -492,8 +496,6 @@ library. If this is what you want to do Public License instead of this License. @iftex -@node Preface, Goals, License, Top -@comment node-name, next, previous, up @unnumbered Preface @cindex Preface This manual documents Gforth. The reader is expected to know @@ -501,7 +503,7 @@ Forth. This manual is primarily a refere for introductory material. @end iftex -@node Goals, Other Books, Preface, Top +@node Goals, Other Books, License, Top @comment node-name, next, previous, up @chapter Goals of Gforth @cindex Goals @@ -566,7 +568,7 @@ can also get it from Global Engineering for publication is available electronically and for free in some MS Word format, and it has been converted to HTML. Some pointers to these versions can be found through -@*@file{http://www.complang.tuwien.ac.at/projects/forth.html}. +@*@url{http://www.complang.tuwien.ac.at/projects/forth.html}. @cindex introductory book @cindex book, introductory @@ -1371,6 +1373,10 @@ The index of the innermost loop can be a of the next loop with @code{j}, and the index of the third loop with @code{k}. +doc-i +doc-j +doc-k + The loop control data are kept on the return stack, so there are some restrictions on mixing return stack accesses and counted loop words. E.g., if you put values on the return stack outside the loop, you @@ -1607,7 +1613,7 @@ implemented the ANS Forth locals wordset The ideas in this section have also been published in the paper @cite{Automatic Scoping of Local Variables} by M. Anton Ertl, presented at EuroForth '94; it is available at -@*@file{http://www.complang.tuwien.ac.at/papers/ertl94l.ps.gz}. +@*@url{http://www.complang.tuwien.ac.at/papers/ertl94l.ps.gz}. @menu * Gforth locals:: @@ -4392,7 +4398,7 @@ convention, we use the extension @code{. * Image File Background:: Why have image files? * Non-Relocatable Image Files:: don't always work. * Data-Relocatable Image Files:: are better. -* Fully Relocatable Image Files:: are hard to create. +* Fully Relocatable Image Files:: better yet. * Stack and Dictionary Sizes:: Setting the default sizes for an image. * Running Image Files:: @code{gforth -i @var{file}} or @var{file}. * Modifying the Startup Sequence:: and turnkey applications. @@ -4403,13 +4409,13 @@ convention, we use the extension @code{. @cindex image file background Our Forth system consists not only of primitives, but also of -definitions written in Forth. Since the Forth compiler itself belongs -to those definitions, it is not possible to start the system with the +definitions written in Forth. Since the Forth compiler itself belongs to +those definitions, it is not possible to start the system with the primitives and the Forth source alone. Therefore we provide the Forth code as an image file in nearly executable form. At the start of the -system a C routine loads the image file into memory, sets up the -memory (stacks etc.) according to information in the image file, and -starts executing Forth code. +system a C routine loads the image file into memory, optionally +relocates the addresses, then sets up the memory (stacks etc.) according +to information in the image file, and starts executing Forth code. The image file variants represent different compromises between the goals of making it easy to generate image files and making them @@ -4422,10 +4428,10 @@ files are data relocatable without furth (one addition per memory access). @cindex relocation at load-time -Our loader performs relocation at image load time. The loader also has -to replace tokens standing for primitive calls with the appropriate -code-field addresses (or code addresses in the case of direct -threading). +By contrast, our loader performs relocation at image load time. The +loader also has to replace tokens standing for primitive calls with the +appropriate code-field addresses (or code addresses in the case of +direct threading). There are three kinds of image files, with different degrees of relocatability: non-relocatable, data-relocatable, and fully relocatable @@ -4444,9 +4450,9 @@ cannot represent @code{ALLOCATE}d memory them). And the contents of the stacks are not represented, either. @item -The only kinds of relocation supported are: the addition of the same -offset to all cells that represent data addresses; and the replacement of -special tokens with code addresses. +The only kinds of relocation supported are: adding the same offset to +all cells that represent data addresses; and replacing special tokens +with code addresses or with pieces of machine code. If any complex computations involving addresses are performed, the results cannot be represented in the image file. Several applications that @@ -4467,6 +4473,14 @@ startup.@footnote{In my opinion, though, using a doubly-linked list (whatever implementation).} @item +The code addresses of run-time routines like @code{docol:} cannot be +represented in the image file (because their tokens would be replaced by +machine code in direct threaded implementations). As a workaround, +compute these addresses at run-time with @code{>code-address} from the +executions tokens of appropriate words (see the definitions of +@code{docol:} and friends in @file{kernel.fs}). + +@item On many architectures addresses are represented in machine code in some shifted or mangled form. You cannot put @code{CODE} words that contain absolute addresses in this form in a relocatable image file. Workarounds @@ -4499,81 +4513,109 @@ doc-savesystem @cindex data-relocatable image files @cindex image files, data-relocatable -@cindex @file{gforth.fi}, relocatability These files contain relocatable data addresses, but fixed code addresses (instead of tokens). They are specific to the executable (i.e., -@file{gforth} file) they were created with. E.g., the image -@code{gforth.fi} is a data-relocatable image file. +@file{gforth} file) they were created with. For direct threading on some +architectures (e.g., the i386), data-relocatable images do not work. You +get a data-relocatable image, if you use @file{gforth-makeimage} with a +Gforth binary that is not doubly indirect threaded (@pxref{Fully +Relocatable Image Files}). +@node Fully Relocatable Image Files, Stack and Dictionary Sizes, Data-Relocatable Image Files, Image Files +@section Fully Relocatable Image Files +@cindex fully relocatable image files +@cindex image files, fully relocatable + +@cindex @file{kern*.fi}, relocatability +@cindex @file{gforth.fi}, relocatability +These image files have relocatable data addresses, and tokens for code +addresses. They can be used with different binaries (e.g., with and +without debugging) on the same machine, and even across machines with +the same data formats (byte order, cell size, floating point +format). However, they are usually specific to the version of Gforth +they were created with. The files @file{gforth.fi} and @file{kernl*.fi} +are fully relocatable. + +There are two ways to create a fully relocatable image file: + +@menu +* gforth-makeimage:: The normal way +* cross.fs:: The hard way +@end menu + +@node gforth-makeimage, cross.fs, Fully Relocatable Image Files, Fully Relocatable Image Files +@subsection @file{gforth-makeimage} @cindex @file{comp-image.fs} -You can create a data-relocatable image file by creating two -non-relocatable image files for different base addresses and processing -them with @file{comp-image.fs}, which generates the relocation -information by comparing the images. - -After loading @file{comp-image.fs}, you can invoke the word -@code{comp-image}, which reads the names of the two input files and the -name of the output file from the input stream. This program also -produces some output on the standard output: It displays the offset -(i.e., the difference between the base addresses of the images); -moreover, for each cell that cannot be represented correctly in the -image files, it displays a line like the following one: +@cindex @file{gforth-makeimage} +You will usually use @file{gforth-makeimage}. If you want to create an +image @var{file} that contains everything you would load by invoking +Gforth with @code{gforth @var{options}}, you simply say @example - 78DC BFFFFA50 BFFFFA40 +gforth-makeimage @var{file} @var{options} @end example -This means that at offset $78dc from @code{forthstart}, one input image -contains $bffffa50, and the other contains $bffffa40. Since these cells -cannot be represented correctly in the output image, you should examine -these places in the dictionary and verify that these cells are dead -(i.e., not read before they are written). - E.g., if you want to create an image @file{asm.fi} that has the file @file{asm.fs} loaded in addition to the usual stuff, you could do it like this: @example -gforth --clear-dictionary asm.fs "savesystem asm.fi1 bye" -gforth --clear-dictionary --offset-image asm.fs "savesystem asm.fi2 bye" -gforth -m 100000 comp-image.fs -e "comp-image asm.fi1 asm.fi2 asm.fi bye" +gforth-makeimage asm.fi asm.fs @end example -@cindex --clear-dictionary, creating image files -@cindex --offset-image, creating image files -The flag @code{--clear-dictionary} ensures that the dictionary memory is -cleared at the start (so you won't see @code{comp-image} messages about -spurious differences). The flag @code{--offset-image} loads the image at -a small offset from its normal position, ensuring that the resulting -nonrelocatable images have different bases (otherwise @code{comp-image} -cannot work). +@file{gforth-makeimage} works like this: It produces two non-relocatable +images for different addresses and then compares them. Its output +reflects this: first you see the output (if any) of the two Gforth +invocations that produce the nonrelocatable image files, then you see +the output of the comparing program: It displays the offset used for +data addresses and the offset used for code addresses; +moreover, for each cell that cannot be represented correctly in the +image files, it displays a line like the following one: -@node Fully Relocatable Image Files, Stack and Dictionary Sizes, Data-Relocatable Image Files, Image Files -@section Fully Relocatable Image Files -@cindex fully relocatable image files -@cindex image files, fully relocatable +@example + 78DC BFFFFA50 BFFFFA40 +@end example -@cindex @file{kern*.fi}, relocatability -These image files have relocatable data addresses, and tokens for code -addresses. They are still a bit machine dependent with respect to the -size and format (byte order, floating point format) of their data. The -@file{kernlxxx.fi} files are fully relocatable. +This means that at offset $78dc from @code{forthstart}, one input image +contains $bffffa50, and the other contains $bffffa40. Since these cells +cannot be represented correctly in the output image, you should examine +these places in the dictionary and verify that these cells are dead +(i.e., not read before they are written). +@cindex @code{savesystem} during @file{gforth-makeimage} +@cindex @code{bye} during @file{gforth-makeimage} +@cindex doubly indirect threaded code +@cindex environment variable @code{GFORTHD} +@cindex @code{GFORTHD} environment variable +@cindex @code{gforth-ditc} +There are a few wrinkles: After processing the passed @var{options}, the +words @code{savesystem} and @code{bye} must be visible. A special doubly +indirect threaded version of the @file{gforth} executable is used for +creating the nonrelocatable images; you can pass the exact filename of +this executable through the environment variable @code{GFORTHD} +(default: @file{gforth-ditc}); if you pass a version that is not doubly +indirect threaded, you will not get a fully relocatable image, but a +data-relocatable image (because there is no code address offset). + +@node cross.fs, , gforth-makeimage, Fully Relocatable Image Files +@subsection @file{cross.fs} +@cindex @file{cross.fs} @cindex cross-compiler @cindex metacompiler -At present a fully relocatable image file can only be produced by -@code{cross}, a batch compiler that accepts a Forth-like programming -language. This @code{cross} language has to be documented + +You can also use @code{cross}, a batch compiler that accepts a Forth-like +programming language. This @code{cross} language has to be documented yet. @cindex target compiler -@code{cross} not only allows the programmer to create fully relocatable -image files, but also to create image files for machines with different -data sizes and data formats than the one used for generating the image -file. This convenience is bought with restrictions and inconveniences in -programming. E.g., addresses have to be stored in memory with special -words (@code{A!}, @code{A,}, etc.) in order to make the code -relocatable. +@code{cross} also allows you to create image files for machines with +different data sizes and data formats than the one used for generating +the image file. You can also use it to create an application image that +does not contain a Forth compiler. These features are bought with +restrictions and inconveniences in programming. E.g., addresses have to +be stored in memory with special words (@code{A!}, @code{A,}, etc.) in +order to make the code relocatable. + @node Stack and Dictionary Sizes, Running Image Files, Fully Relocatable Image Files, Image Files @section Stack and Dictionary Sizes @@ -4583,19 +4625,18 @@ relocatable. If you invoke Gforth with a command line flag for the size (@pxref{Invoking Gforth}), the size you specify is stored in the -dictionary. If you save the dictionary with @code{savesystem}, this size -will become the default for the resulting image file. E.g., the -following will create a non-relocatable version of gforth.fi with a 1MB -dictionary: +dictionary. If you save the dictionary with @code{savesystem} or create +an image with @file{gforth-makeimage}, this size will become the default +for the resulting image file. E.g., the following will create a +fully relocatable version of gforth.fi with a 1MB dictionary: @example -gforth -m 1M -e "savesystem gforth1M.fi bye" +gforth-makeimage gforth.fi -m 1M @end example In other words, if you want to set the default size for the dictionary -and the stacks of an image, just invoke Gforth with the appropriate -options when creating the image. When creating a data-relocatable image, -you have to use the same size options for both @code{savesystem}s. +and the stacks of an image, just invoke @file{gforth-makeimage} with the +appropriate options when creating the image. @cindex stack size, cache-friendly Note: For cache-friendly behaviour (i.e., good performance), you should @@ -4620,19 +4661,12 @@ gforth -i @var{image} @cindex executable image file @cindex image files, executable If your operating system supports starting scripts with a line of the -form @code{#! ...}, you can make your image file executable, and you'll -just have to type the image file name to start Gforth with this image -file (note that the file extension @code{.fi} is just a convention). - -I.e., in most Unix systems, you just have to make the image file -@var{image} executable with - -@example -chmod +x @var{image} -@end example +form @code{#! ...}, you just have to type the image file name to start +Gforth with this image file (note that the file extension @code{.fi} is +just a convention). I.e., to run Gforth with the image file @var{image}, +you can just type @var{image} instead of @code{gforth -i @var{image}}. -and then you can invoke it by simply typing @var{image} instead of -@code{gforth -i @var{image}}. +doc-#! @node Modifying the Startup Sequence, , Running Image Files, Image Files @section Modifying the Startup Sequence @@ -4646,7 +4680,7 @@ deferred word doc-'cold @code{'cold} is invoked just before the image-specific command line -processing (by default, loading files and evaluating (@code{-e}) strings +processing (by default, loading files and evaluating (@code{-e}) strings) starts. A sequence for adding your initialization usually looks like this: @@ -4664,6 +4698,20 @@ You can make a turnkey image by letting (your turnkey application) that never returns; instead, it exits Gforth via @code{bye} or @code{throw}. +@cindex command-line arguments, access +@cindex arguments on the command line, access +You can access the (image-specific) command-line arguments through the +variables @code{argc} and @code{argv}. @code{arg} provides conventient +access to @code{argv}. + +doc-argc +doc-argv +doc-arg + +If @code{'cold} exits normally, Gforth processes the command-line +arguments as files to be loaded and strings to be evaluated. Therefore, +@code{'cold} should remove the arguments it has used in this case. + @c ****************************************************************** @node Engine, Bugs, Image Files, Top @chapter Engine @@ -4677,7 +4725,7 @@ The ideas in this section have also been @cite{ANS fig/GNU/??? Forth} (in German) by Bernd Paysan, presented at the Forth-Tagung '93 and @cite{A Portable Forth Engine} by M. Anton Ertl, presented at EuroForth '93; the latter is available at -@*@file{http://www.complang.tuwien.ac.at/papers/ertl93.ps.Z}. +@*@url{http://www.complang.tuwien.ac.at/papers/ertl93.ps.Z}. @menu * Portability:: @@ -5157,12 +5205,12 @@ predictive value for the performance of In @cite{Translating Forth to Efficient C} by M. Anton Ertl and Martin Maierhofer (presented at EuroForth '95), an indirect threaded version of Gforth is compared with Win32Forth, NT Forth, PFE, and ThisForth; that -version of Gforth is 2\%@minus{}8\% slower on a 486 than the version -used here. The paper available at -@*@file{http://www.complang.tuwien.ac.at/papers/ertl&maierhofer95.ps.gz}; +version of Gforth is 2%@minus{}8% slower on a 486 than the direct +threaded version used here. The paper available at +@*@url{http://www.complang.tuwien.ac.at/papers/ertl&maierhofer95.ps.gz}; it also contains numbers for some native code systems. You can find a newer version of these measurements at -@file{http://www.complang.tuwien.ac.at/forth/performance.html}. You can +@url{http://www.complang.tuwien.ac.at/forth/performance.html}. You can find numbers for Gforth on various machines in @file{Benchres}. @node Bugs, Origin, Engine, Top @@ -5172,7 +5220,7 @@ find numbers for Gforth on various machi Known bugs are described in the file BUGS in the Gforth distribution. If you find a bug, please send a bug report to -@code{bug-gforth@@gnu.ai.mit.edu}. A bug report should +@email{bug-gforth@@gnu.ai.mit.edu}. A bug report should describe the Gforth version used (it is announced at the start of an interactive Gforth session), the machine and operating system (on Unix systems you can use @code{uname -a} to produce this information), the