File:  [gforth] / gforth / doc / gforth.1
Revision 1.6: download - view: text, annotated - select for diffs
Thu Aug 1 21:14:25 2002 UTC (19 years, 2 months ago) by anton
Branches: MAIN
CVS tags: v0-7-0, v0-6-2, v0-6-1, v0-6-0, HEAD
documentation changes

    1: .de TQ
    2: .br
    3: .ns
    4: .IP "\fB\\$1\fI\\$2" 9
    5: ..
    6: .TH GForth 1 "April 14, 1999" \" -*- nroff -*-
    7: .SH NAME
    8: gforth, gforth-fast, gforthmi \- a fast and portable Forth system
    9: .SH SYNOPSIS
   10: 
   11: \fCgforth\fR [initialization options] [image-specific options]
   12: \fCgforth-fast\fR [initialization options] [image-specific options]
   13: 
   14: \fCgforthmi\fR \fIfilename\fR [initialization options] [image-specific options]
   15: .SH DESCRIPTION
   16: 
   17: \fBGForth\fR is a fast and portable implementation of the Forth
   18: programming language. For details read the manual.
   19: .SH ENVIRONMENT VARIABLES
   20: 
   21: \fCGFORTHPATH\fR contains the search path for source and image files.
   22: 
   23: \fCGFORTHD\fR gives the gforth executable used by
   24: \fCgforthmi\fR for creating the base images. It should be a
   25: double indirect threaded system.  Default: \fCgforth-ditc\fR.
   26: 
   27: \fCGFORTH\fR gives the gforth executable used by
   28: \fCgforthmi\fR for computing the relocatable image from the
   29: base images. Default: \fCgforth\fR.
   30: 
   31: \fCGFORTHHIST\fR gives the location of the history file used by gforth
   32: to allow command-line recall. Default: \fC$HOME\fR. (The history
   33: file is named \fC.gforth-history\fR).
   34: 
   35: .SH EXAMPLES
   36: 
   37: \fCgforth\fR
   38: 
   39: starts the system and goes into interactive mode.
   40: 
   41: \fCgforth file1 file2 \-e bye\fR
   42: 
   43: loads and interprets the files \fCfile1\fR and \fCfile2\fR, then
   44: exits.
   45: 
   46: \fCgforth-fast\fR
   47: 
   48: is the same as \fCgforth\fR, except that it does not support
   49: accurate backtraces for signals, and is faster by up to a factor of 2.
   50: Use it for debugged, performance-critical programs such as benchmarks.
   51: 
   52: \fCgforthmi asm.fi \-m 1M asm.fs\fR
   53: 
   54: creates an image \fCasm.fi\fR that has a default dictionary size of
   55: 1MB and has the file \fCasm.fs\fR loaded.
   56: 
   57: .SH OPTIONS
   58: 
   59: .BI "\-\-help"
   60: .TQ "\-h"
   61: Lists the available options, including some not described here (see
   62: also the manual).
   63: .TP
   64: .BI "\-\-image\-file " "file"
   65: .TQ "\-i " "file"
   66: Loads the Forth image
   67: .I file
   68: instead of the default \fCgforth.fi\fR.
   69: .TP
   70: .BI "\-\-path " "path"
   71: .TQ "\-p " "path"
   72: Uses
   73: .I path
   74: for searching the image file and Forth source code
   75: files instead of the default in the environment variable
   76: \fCGFORTHPATH\fR
   77: or the path specified at installation time (typically
   78: \fC/usr/local/lib/gforth:.\fR. A path is given as a 
   79: .BR : -separated
   80: list.
   81: .TP
   82: .BI "\-\-dictionary\-size " "size"
   83: .TQ "\-m " "size"
   84: Allocate
   85: .I size
   86: space for the Forth dictionary space instead of
   87: using the default specified in the image (typically 256K). The
   88: .I size
   89: specification consists of an integer and a unit (e.g., \fC4M\fR).
   90: The unit can be one of \fCb\fR (bytes),
   91: \fCe\fR (element size, in this case Cells),
   92: \fCk\fR (kilobytes), and
   93: \fCM\fR (Megabytes). If no unit is specified,
   94: \fCe\fR is used.
   95: .TP
   96: .BI "\-\-data\-stack\-size " "size"
   97: .TQ "\-d " "size"
   98: Allocate
   99: .I size
  100: space for the data stack instead of using the
  101: default specified in the image (typically 16K).
  102: .TP
  103: .BI "\-\-return\-stack\-size " "size"
  104: .TQ "\-r " "size"
  105: Allocate
  106: .I size
  107: space for the return stack instead of using the
  108: default specified in the image (typically 16K).
  109: .TP
  110: .BI "\-\-fp\-stack\-size " "size"
  111: .TQ "\-f " "size"
  112: Allocate
  113: .I size
  114: space for the floating point stack instead of
  115: using the default specified in the image (typically 16K). In this case
  116: the unit specifier
  117: \fCe\fR
  118: refers to floating point numbers.
  119: .TP
  120: .BI "\-\-locals\-stack\-size " "size"
  121: .TQ "\-l " "size"
  122: Allocate
  123: .I size
  124: space for the locals stack instead of using the
  125: default specified in the image (typically 16K).
  126: 
  127: .TP
  128: .BI "\-\-evaluate " "forth"
  129: .TQ "\-e " "forth"
  130: Evaluates the
  131: .I forth
  132: code. This option takes only one argument; if you want to evaluate
  133: more Forth words, you have to quote them or use several \fC-e\fRs.  To
  134: exit after processing the command line (instead of entering
  135: interactive mode) append \fC-e bye\fR to the command line. This is an
  136: image-specific option of the default image.
  137: .SH FILES
  138: .nf
  139: .ta \w'\fC.../gforth.fi\fP 	'u
  140: \&\fC.../gforth.fi\fP	default Forth image
  141: \&\fC*.fi\fP	Forth loadable image
  142: \&\fC*.fs\fP	Forth source (sequential)
  143: \&\fC*.fb\fP	Forth source (block)
  144: \&\fC*.fd\fP	generated with \fCmakedoc.fs\fP
  145: \&\fC*.i\fP	C include files
  146: \&\fC*.ds\fP	documentation source
  147: \&\fC*TAGS\fP	etags files
  148: .fi
  149: .SH SEE ALSO
  150: The Gforth manual - available in hypertext (Info, HTML) and printable
  151: (TeX, PS, ASCII) forms.
  152: 
  153: The ANSI document X3.215-1994 (i.e., the ANS Forth standard).
  154: 
  155: More information on Gforth (e.g., pointers to new versions, to the
  156: manual on the WWW and to papers about Gforth) is available through
  157: \fChttp://www.complang.tuwien.ac.at/projects/forth.html\fR.
  158: .SH AUTHORS
  159: \fBGforth\fR was written by Anton Ertl, Bernd Paysan, Jens Wilke and
  160: others.

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>