core/handbook/cli.facts

   1 USING: help parser shells modules ;
   2
   3 ARTICLE: "cli" "Command line usage"
   4 "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."
   5 $terpri
   6 "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."
   7 $terpri
   8 "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)."
   9 $terpri
  10 "All file names other than the first one are source file names which will be run with " { $link run-file } " when Factor starts up."
  11 $terpri
  12 "Finally, switches can take one of the following three forms:"
  13 { $list
  14     { { $snippet "-" { $emphasis "foo" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $link t } }
  15     { { $snippet "-no-" { $emphasis "foo" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $link f } }
  16     { { $snippet "-" { $emphasis "foo" } "=" { $emphasis "bar" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $snippet "\"" { $emphasis "bar" } "\"" } }
  17 }
  18 { $subsection "runtime-cli-args" }
  19 { $subsection "bootstrap-cli-args" }
  20 { $subsection "standard-cli-args" } ;
  21
  22 ARTICLE: "runtime-cli-args" "Runtime command line switches"
  23 "A handful of command line switches are processed by the runtime and not the library. They control low-level features."
  24 { $table
  25     { { $snippet "-D=" { $emphasis "n" } } "Data stack size, kilobytes" }
  26     { { $snippet "-R=" { $emphasis "n" } } "Retain stack size, kilobytes" }
  27     { { $snippet "-C=" { $emphasis "n" } } "Call stack size, kilobytes" }
  28     { { $snippet "-G=" { $emphasis "n" } } "Number of generations, must be >= 2" }
  29     { { $snippet "-Y=" { $emphasis "n" } } { "Size of " { $snippet { $emphasis "n" } "-1" } " youngest generations, megabytes" } }
  30     { { $snippet "-A=" { $emphasis "n" } } "Size of tenured and semi-spaces, megabytes" }
  31     { { $snippet "-X=" { $emphasis "n" } } "Code heap size, megabytes" }
  32 } ;
  33
  34 ARTICLE: "bootstrap-cli-args" "Switches available when bootstrapping"
  35 "A number of command line switches can be passed to a bootstrap image to modify the behavior of the resulting " { $snippet "factor.image" } ":"
  36 { $table
  37     { { $snippet "-no-compile" } "Do not compile any words in the image or load any modules which depend on the compiler" }
  38     { { $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" }
  39     { { $snippet "-no-cocoa" } "(Mac OS X only) do not load the Cocoa UI backend" }
  40     { { $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" } }
  41     { { $snippet "-no-x11" } "(Unix only) do not load the X11 UI backend" }
  42 }
  43 "To find out how to generate a bootstrap image, see " { $link "images" } "." ;
  44
  45 ARTICLE: "standard-cli-args" "General command line switches"
  46 "The following command line switches can be passed to a bootstrapped Factor image:"
  47 { $table
  48     { { $snippet "-e=" { $emphasis "code" } } { "This specifies a code snippet to evaluate. If you want Factor to exit immediately after, also specify " { $snippet "-shell=none" } "." } }
  49     { { $snippet "-shell=" { $emphasis "shell" } } { { $snippet { $emphasis "shell" } } " is either " { $link tty } ", " { $link ui } ", " { $link none } ", or the name of any other word in the " { $vocab-link "shells" } " vocabulary. This specifies the user interface to run on startup." } }
  50     { { $snippet "-no-user-init" } { "If specified, Factor will not run the " { $snippet "~/.factor-rc" } " file on startup" } }
  51     { { $snippet "-quiet" } { "If set, " { $link run-file } " and " { $link require } " will not print load messages" } }
  52 } ;