factor/doc/handbook/cli.facts

USING: help parser shells ;

ARTICLE: "cli" "Command line usage"
"Unless the " { $snippet "-no-user-init" } " command line switch is specified, The startup routine runs the " { $snippet ".factor-rc" } " file in the user's home directory, if it exists. This file can contain initialization and customization for your development environment."
$terpri
"Zero or more command line arguments may be passed to the Factor runtime. Command line arguments starting with a dash (" { $snippet "-" } ") is interpreted as a switch. All other arguments are taken to be file names."
$terpri
"If any file names are specified at all, the first one must be the image name; otherwise, the default image file is used, which is usually a file named " { $snippet "factor.image" } " in the same directory as the runtime executable (on Windows and Mac OS X) or the current directory (on Unix)."
$terpri
"All file names other than the first one are source file names which will be run using " { $link ?run-file } " when Factor starts up."
$terpri
"Finally, switches can take one of the following three forms:"
{ $list
    { { $snippet "-" { $emphasis "foo" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $link t } }
    { { $snippet "-no-" { $emphasis "foo" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $link f } }
    { { $snippet "-" { $emphasis "foo" } "=" { $emphasis "bar" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $snippet "\"" { $emphasis "bar" } "\"" } }
}
{ $subsection "runtime-cli-args" }
{ $subsection "bootstrap-cli-args" }
{ $subsection "standard-cli-args" } ;

ARTICLE: "runtime-cli-args" "Runtime command line switches"
"A handful of command line switches are processed by the runtime and not the library. They control low-level features."
{ $table
    { { $snippet "-D=" { $emphasis "n" } } "Data stack size, kilobytes" }
    { { $snippet "-R=" { $emphasis "n" } } "Retain stack size, kilobytes" }
    { { $snippet "-C=" { $emphasis "n" } } "Call stack size, kilobytes" }
    { { $snippet "-G=" { $emphasis "n" } } "Number of generations, must be >= 2" }
    { { $snippet "-Y=" { $emphasis "n" } } { "Size of " { $snippet { $emphasis "n" } "-1" } " youngest generations, megabytes" } }
    { { $snippet "-A=" { $emphasis "n" } } "Size of tenured and semi-spaces, megabytes" }
    { { $snippet "-X=" { $emphasis "n" } } "Code heap size, megabytes" }
} ;

ARTICLE: "bootstrap-cli-args" "Switches available when bootstrapping"
"A number of command line switches can be passed to a bootstrap image to modify the behavior of the resulting " { $snippet "factor.image" } ":"
{ $table
    { { $snippet "-no-compile" } "Do not compile any words in the image or load any modules which depend on the compiler" }
    { { $snippet "-no-native-io" } "Do not load the native I/O module for your operating system; non-blocking I/O and sockets will not be available" }
    { { $snippet "-no-cocoa" } "(Mac OS X only) do not load the Cocoa UI backend" }
    { { $snippet "-x11" } { "(Unix only) load the X11 UI backend. You can specify " { $snippet "-no-cocoa -x11" } " to load the X11 UI on Mac OS X" } }
    { { $snippet "-no-x11" } "(Unix only) do not load the X11 UI backend" }
}
"To find out how to generate a bootstrap image, see " { $link "images" } "." ;

ARTICLE: "standard-cli-args" "General command line switches"
"The following command line switches can be passed to a bootstrapped Factor image:"
{ $table
    { { $snippet "-shell=" { $emphasis "shell" } } { { $snippet { $emphasis "shell" } } " is either " { $link tty } ", " { $link ui } ", or the name of any other word in the " { $vocab-link "shells" } " vocabulary. This specifies the user interface to run on startup." } }
    { { $snippet "-no-user-init" } { "If specified, Factor will not run the " { $snippet "~/.factor-rc" } " file on startup" } }
} ;