DoItFirst command option processing


	links to this page:

Last updated at 6:50 pm UTC on 12 December 2020

The Squeak image is run in a virtual machine. On a traditional computer, the virtual machine (VM) is typically an application that may be run from a console or shell command line. Any arguments on the command line may be interpreted first by the VM application itself, and then are passed to the Squeak image where they are available for interpretation in the image itself.

For a Unix VM, the -help command line option explains the VM options, for example:

$ squeak -help
Usage: /usr/local/lib/squeak/4.19.2-3790/squeakvm [<option>...] [<imageName> [<argument>...]]
       /usr/local/lib/squeak/4.19.2-3790/squeakvm [<option>...] -- [<argument>...]

Note that the VM interprets the first argument that does not begin with '‑' (single dash, or minus) as the name of the image file to be loaded. The ‑‑ (two dashes) token may used to stop this VM argument processing. This is similar to the use of '‑‑' in the Unix bash shell, see the man page for bash.

In addition to the VM convention of treating the first argument as the image file name, an additional convention is to treat the next argument in the list as a "startup document" specification, identifying a file or resource to be loaded and processed during the image startup. This feature is controlled by the "Read document at startup" system preference in Squeak. When the preference is active, the '‑‑' token may be used on the command line to prevent the argument from being interpreted at startup time (although in this case the special processing of '‑‑' is done in the image, rather than in the VM).

With Squeak, both the VM arguments and the remaining arguments (those not used by the VM application) are available as system attributes. See SmalltalkImage>>getSystemAttribute: for details of these system attributes.

In a Squeak trunk image (as of December 2020 when this is being written), the command line arguments are available with these two methods:

Smalltalk arguments ==> the command line arguments intended for use in the image after all startup processing

Smalltalk rawArguments ==> same as above, but also including image name and '‑‑' tokens.

Regardless of the various combinations of '‑‑' tokens and Squeak preferences, "Smalltalk arguments" provides of list of arguments intended for use in Squeak after the VM option processing and the startup document processing. This argument list may be used for any purpose at all within the image.

Argument processing conventions similar to those described here have existed in Squeak for many years, although implementations have been inconsistent and sometimes buggy.

A later addition (December 2020) is DoItFirst utllity that adds startup processing for a limited number of command line options within the image. It works as follows:

Class DoItFirst is registered as the first entry in the system startup list.
The DoItFirst class>startUp: method is evaluated after VM argument processing, and before any other methods in the startup list, including the start document processing.
DoItFirst scans the argument list (Smalltalk arguments), identifying recognized argument tokens, and wrapping a corresponding method and its argument(s) in a block.
Each argument block is saved in a dictionary of blocks, it case it should be necessary to evaluate that block at a later point in the startup processing.
A list of blocks is collected, and possibly reordered such that certain options are evaluated before others.
If ‑‑debug was specified on the command line, its block is specifically excluded from the list so that it instead may be evaluated later in the startup processing. This is because the debugger does not yet work this early in the startup process.
The list of blocks is evaluated.
This completes the startup processing of DoItFirst, but the dictionary of command option blocks is retained in the singleton instances of DoItFirst for later use.
A debugger can first be successfully opened after class Delay has been processed in the startup list. Therefore Delay class>>startUp sends DoItFirst class>>reevaluateDebug, which checks the DoItFirst singleton and evaluates the —debug command option block if present. Thus, if ‑‑debug was specified on the Squeak command line, a debugger will be opened to stop the startup processing at the end of the Delay class>>startUp. Resuming from the debugger will complete the startup process normally.
A bit later in the startup processing, FileDirectory class>>startUp will also call back to the DoItFirst singleton to reapply any directory default that was specified with a ‑‑cwd command line option. This ensures that the ‑‑cwd option that was immediately applied in the initial DoItFirst processing will not be overridden by the default value set later in the FileDirectory startup processing.
The Smalltalk arguments list is not affected by DoItFirst, and remains available for any other purposes in the image.

The DoItFirst image arguments are:

	--doit argumentlist "evaluate each argument as a doIt expression"
	--evaluate arg "evaluate arg, print result then exit"
	--file filename "evaluate contents of filename, print result then exit"
	--filein filelist "file in each file named in fileList"
	--cwd path "set FileDirectory defaultDirectory to path prior to evaluating other options"
	--debug "enter a debugger as soon as possible in the startUp processing"
	--help "print this message"

Some arguments have single character synonyms, ‑f is a synonym for ‑‑file, ‑d for ‑‑doit
A single '‑' may be used instead of '‑‑', ‑help is interpreted as ‑‑help