basis/command-line/command-line-docs.factor

   1 USING: help.markup help.syntax parser vocabs.loader strings ;
   2 IN: command-line
   3
   4 ARTICLE: "runtime-cli-args" "Command line switches for the VM"
   5 "A handful of command line switches are processed by the VM and not the library. They control low-level features."
   6 { $table
   7     { { $snippet "-i=" { $emphasis "image" } } { "Specifies the image file to use; see " { $link "images" } } }
   8     { { $snippet "-datastack=" { $emphasis "n" } } "Data stack size, kilobytes" }
   9     { { $snippet "-retainstack=" { $emphasis "n" } } "Retain stack size, kilobytes" }
  10     { { $snippet "-generations=" { $emphasis "n" } } "Number of generations, must equal 1, 2 or 3" }
  11     { { $snippet "-young=" { $emphasis "n" } } { "Size of youngest generation (0), megabytes" } }
  12     { { $snippet "-aging=" { $emphasis "n" } } "Size of aging generation (1), megabytes" }
  13     { { $snippet "-tenured=" { $emphasis "n" } } "Size of oldest generation (2), megabytes" }
  14     { { $snippet "-codeheap=" { $emphasis "n" } } "Code heap size, megabytes" }
  15     { { $snippet "-securegc" } "If specified, unused portions of the data heap will be zeroed out after every garbage collection" }
  16 }
  17 "If an " { $snippet "-i=" } " switch is not present, 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)." ;
  18
  19 ARTICLE: "bootstrap-cli-args" "Command line switches for bootstrap"
  20 "A number of command line switches can be passed to a bootstrap image to modify the behavior of the resulting image:"
  21 { $table
  22     { { $snippet "-output-image=" { $emphasis "image" } } { "Save the result to " { $snippet "image" } ". The default is " { $snippet "factor.image" } "." } }
  23     { { $snippet "-no-user-init" } { "Inhibits the running of the " { $snippet ".factor-boot-rc" } " file in the user's home directory." } }
  24     { { $snippet "-include=" { $emphasis "components..." } } "A list of components to include (see below)." }
  25     { { $snippet "-exclude=" { $emphasis "components..." } } "A list of components to exclude." }
  26     { { $snippet "-ui-backend=" { $emphasis "backend" } } { "One of " { $snippet "x11" } ", " { $snippet "windows" } ", or " { $snippet "cocoa" } ". The default is platform-specific." } }
  27 }
  28 "Bootstrap can load various optional components:"
  29 { $table
  30     { { $snippet "compiler" } "The compiler." }
  31     { { $snippet "tools" } "Terminal-based developer tools." }
  32     { { $snippet "help" } "The help system." }
  33     { { $snippet "ui" } "The graphical user interface." }
  34     { { $snippet "ui.tools" } "Graphical developer tools." }
  35     { { $snippet "io" } "Non-blocking I/O and networking." }
  36 }
  37 "By default, all optional components are loaded. To load all optional components except for a given list, use the " { $snippet "-exclude=" } " switch; to only load specified optional components, use the " { $snippet "-include=" } "."
  38 $nl
  39 "For example, to build an image with the compiler but no other components, you could do:"
  40 { $code "./factor -i=boot.ppc.image -include=compiler" }
  41 "To build an image with everything except for the user interface and graphical tools,"
  42 { $code "./factor -i=boot.ppc.image -exclude=\"ui ui.tools\"" }
  43 "To generate a bootstrap image in the first place, see " { $link "bootstrap.image" } "." ;
  44
  45 ARTICLE: "standard-cli-args" "Command line switches for general usage"
  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 "-run=none" } "." } }
  49     { { $snippet "-run=" { $emphasis "vocab" } } { { $snippet { $emphasis "vocab" } } " is the name of a vocabulary with a " { $link POSTPONE: MAIN: } " hook to run on startup, for example " { $vocab-link "listener" } ", " { $vocab-link "ui" } " or " { $vocab-link "none" } "." } }
  50     { { $snippet "-no-user-init" } { "Inhibits the running of the " { $snippet ".factor-rc" } " file in the user's home directory on startup." } }
  51     { { $snippet "-quiet" } { "If set, " { $link run-file } " and " { $link require } " will not print load messages." } }
  52     { { $snippet "-script" } { "Equivalent to " { $snippet "-quiet -run=none" } "." $nl "On Unix systems, Factor can be used for scripting - just create an executable text file whose first line is:" { $code "#! /usr/local/bin/factor -script" } "The space after " { $snippet "#!" } " is necessary because of Factor syntax." } }
  53 } ;
  54
  55 ARTICLE: "cli" "Command line usage"
  56 "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."
  57 $nl
  58 "Zero or more command line arguments may be passed to the Factor runtime. Command line arguments starting with a dash (" { $snippet "-" } ") is interpreted as switches. All other arguments are taken to be file names to be run by " { $link run-file } "."
  59 $nl
  60 "Switches can take one of the following three forms:"
  61 { $list
  62     { { $snippet "-" { $emphasis "foo" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $link t } }
  63     { { $snippet "-no-" { $emphasis "foo" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $link f } }
  64     { { $snippet "-" { $emphasis "foo" } "=" { $emphasis "bar" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $snippet "\"" { $emphasis "bar" } "\"" } }
  65 }
  66 { $subsection "runtime-cli-args" }
  67 { $subsection "bootstrap-cli-args" }
  68 { $subsection "standard-cli-args" }
  69 "The list of command line arguments can be obtained and inspected directly:"
  70 { $subsection cli-args }
  71 "The " { $snippet ".factor-rc" } " and " { $snippet ".factor-boot-rc" } " files can be run explicitly:"
  72 { $subsection run-user-init }
  73 { $subsection run-bootstrap-init }
  74 "There is a way to override the default vocabulary to run on startup:"
  75 { $subsection main-vocab-hook } ;
  76
  77 ABOUT: "cli"
  78
  79 HELP: run-bootstrap-init
  80 { $description "Runs the " { $snippet ".factor-boot-rc" } " file in the user's home directory unless the " { $snippet "-no-user-init" } " command line switch was given." } ;
  81
  82 HELP: run-user-init
  83 { $description "Runs the " { $snippet ".factor-rc" } " file in the user's home directory unless the " { $snippet "-no-user-init" } " command line switch was given." } ;
  84
  85 HELP: cli-param
  86 { $values { "param" string } }
  87 { $description "Process a command-line switch."
  88 $nl
  89 "If the parameter contains " { $snippet "=" } ", the global variable named by the string before the equals sign is set to the string after the equals sign."
  90 $nl
  91 "If the parameter begins with " { $snippet "no-" } ", sets the global variable named by the parameter with the prefix removed to " { $link f } "."
  92 $nl
  93 "Otherwise, sets the global variable named by the parameter to " { $link t } "." } ;
  94
  95 HELP: cli-args
  96 { $values { "args" "a sequence of strings" } }
  97 { $description "Outputs the command line parameters which were passed to the Factor VM on startup." } ;
  98
  99 HELP: main-vocab-hook
 100 { $var-description "Global variable holding a quotation which outputs a vocabulary name. UI backends set this so that the UI can automatically start if the prerequisites are met (for example, " { $snippet "$DISPLAY" } " being set on X11)." } ;
 101
 102 HELP: main-vocab
 103 { $values { "vocab" string } }
 104 { $description "Outputs the name of the vocabulary which is to be run on startup using the " { $link run } " word. The " { $snippet "-run" } " command line switch overrides this setting." } ;
 105
 106 HELP: default-cli-args
 107 { $description "Sets global variables corresponding to default command line arguments." } ;
 108
 109 HELP: ignore-cli-args?
 110 { $values { "?" "a boolean" } }
 111 { $description "On Mac OS X, source files to run are supplied by the Cocoa API, so to avoid running them twice the startup code has to call this word." } ;
 112
 113 HELP: parse-command-line
 114 { $description "Called on startup to process command line arguments. This sets global variables with " { $link cli-param } ", runs source files, and evaluates the string given by the " { $snippet "-e" } " switch, if there is one." } ;