1.1 Command line arguments

The GNU Smalltalk virtual machine may be invoked via the following command:

gst [ flags … ] [ file … ]

When you invoke GNU Smalltalk, it will ensure that the binary image file (called gst.im) is up to date; if not, it will build a new one as described in Loading an image or creating a new one. Your first invocation should look something like this:

"Global garbage collection... done"
GNU Smalltalk ready

st>

If you specify one or more files, they will be read and executed in order, and Smalltalk will exit when end of file is reached. If you don’t specify file, GNU Smalltalk reads standard input, issuing a ‘st>’ prompt if the standard input is a terminal. You may specify - for the name of a file to invoke an explicit read from standard input.

To exit while at the ‘st>’ prompt, use Ctrl-d, or type ObjectMemory quit followed by RET. Use ObjectMemory snapshot first to save a new image that you can reload later, if you wish.

As is standard for GNU-style options, specifying -- stops the interpretation of options so that every argument that follows is considered a file name even if it begins with a ‘-’.

You can specify both short and long flags; for example, --version is exactly the same as -v, but is easier to remember. Short flags may be specified one at a time, or in a group. A short flag or a group of short flags always starts off with a single dash to indicate that what follows is a flag or set of flags instead of a file name; a long flag starts off with two consecutive dashes, without spaces between them.

In the current implementation the flags can be intermixed with file names, but their effect is as if they were all specified first. The various flags are interpreted as follows:

-a

--smalltalk-args

Treat all options afterward as arguments to be given to Smalltalk code retrievable with Smalltalk arguments, ignoring them as arguments to GNU Smalltalk itself.

Examples:

command line	Options seen by GNU Smalltalk	Smalltalk arguments
(empty)	(none)	#()
-Via foo bar	-Vi	#('foo' 'bar')
-Vai test	-Vi	#('test')
-Vaq	-Vq	#()
--verbose -aq -c	--verbose -q	#('-c')

-c

--core-dump

When a fatal signal occurs, produce a core dump before terminating. Without this option, only a backtrace is provided.

-D

--declaration-trace

Print the class name, the method name, and the byte codes that the compiler generates as it compiles methods. Only applies to files that are named explicitly on the command line, unless the flag is given multiple times on the command line.

-E

--execution-trace

Print the byte codes being executed as the interpreter operates. Only works for statements explicitly issued by the user (either interactively or from files given on the command line), unless the flag is given multiple times on the command line.

--kernel-directory

Specify the directory from which the kernel source files will be loaded. This is used mostly while compiling GNU Smalltalk itself. Smalltalk code can retrieve this information with Directory kernel.

--no-user-files

Don’t load any files from ~/.st/ (see Loading an image or creating a new one).¹ This is used mostly while compiling GNU Smalltalk itself, to ensure that the installed image is built only from files in the source tree.

-K file

--kernel-file file

Load file in the usual way, but look for it relative to the kernel directory’s parent directory, which is usually /usr/local/share/smalltalk/. See --kernel-dir above.

-f

--file

The following two command lines are equivalent:

gst -f file args...
gst -q file -a args...

This is meant to be used in the so called “sharp-bang” sequence at the beginning of a file, as in

#! /usr/bin/gst -f

… Smalltalk source code …

GNU Smalltalk treats the first line as a comment, and the -f option ensures that the arguments are passed properly to the script. Use this instead to avoid hard-coding the path to gst:²

#! /bin/sh
"exec" "gst" "-f" "$0" "$@" 

… Smalltalk source code …

-g

--no-gc-messages

Suppress garbage collection messages.

-h

--help

Print out a brief summary of the command line syntax of GNU Smalltalk, including the definitions of all of the option flags, and then exit.

-i

--rebuild-image

Always build and save a new image file; see Loading an image or creating a new one.

--maybe-rebuild-image

Perform the image checks and rebuild as described in Loading an image or creating a new one. This is the default when -I is not given.

-I file

--image-file file

Use the image file named file as the image file to load instead of the default location, and set file’s directory part as the image path. This option completely bypasses checking the file dates on the kernel files; use --maybe-rebuild-image to restore the usual behavior, writing the newly built image to file if needed.

-q

--quiet

--silent

Suppress the printing of answered values from top-level expressions while GNU Smalltalk runs.

-r

--regression-test

This is used by the regression testing system and is probably not of interest to the general user. It controls printing of certain information.

-S

--snapshot

Save the image after loading files from the command line. Of course this “snapshot” is not saved if you include - (stdin) on the command line and exit by typing Ctrl-c.

-v

--version

Print out the GNU Smalltalk version number, then exit.

-V

--verbose

Print various diagnostic messages while executing (the name of each file as it’s loaded, plus messages about the beginning of execution or how many byte codes were executed).