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

   1 USING: help.markup help.syntax parser vocabs.loader strings
   2 command-line.private ;
   3 IN: command-line
   4
   5 HELP: run-bootstrap-init
   6 { $description "Runs the bootstrap initialization file in the user's home directory, unless the " { $snippet "-no-user-init" } " command line switch was given. This file is named " { $snippet ".factor-boot-rc" } " on Unix and " { $snippet "factor-boot-rc" } " on Windows." } ;
   7
   8 HELP: run-user-init
   9 { $description "Runs the startup initialization file in the user's home directory, unless the " { $snippet "-no-user-init" } " command line switch was given. This file is named " { $snippet ".factor-rc" } " on Unix and " { $snippet "factor-rc" } " on Windows." } ;
  10
  11 HELP: load-vocab-roots
  12 { $description "Loads the newline-separated list of additional vocabulary roots from the file named " { $snippet ".factor-roots" } " on Unix and " { $snippet "factor-roots" } " on Windows." } ;
  13
  14 HELP: param
  15 { $values { "param" string } }
  16 { $description "Process a command-line switch."
  17 $nl
  18 "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."
  19 $nl
  20 "If the parameter begins with " { $snippet "no-" } ", sets the global variable named by the parameter with the prefix removed to " { $link f } "."
  21 $nl
  22 "Otherwise, sets the global variable named by the parameter to " { $link t } "." } ;
  23
  24 HELP: (command-line)
  25 { $values { "args" "a sequence of strings" } }
  26 { $description "Outputs the command line parameters which were passed to the Factor VM on startup." } ;
  27
  28 HELP: command-line
  29 { $var-description "The command line parameters which follow the name of the script on the command line." } ;
  30
  31 HELP: main-vocab-hook
  32 { $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)." } ;
  33
  34 HELP: main-vocab
  35 { $values { "vocab" string } }
  36 { $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." } ;
  37
  38 HELP: default-cli-args
  39 { $description "Sets global variables corresponding to default command line arguments." } ;
  40
  41 HELP: ignore-cli-args?
  42 { $values { "?" "a boolean" } }
  43 { $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." } ;
  44
  45 ARTICLE: "runtime-cli-args" "Command line switches for the VM"
  46 "A handful of command line switches are processed by the VM and not the library. They control low-level features."
  47 { $table
  48     { { $snippet "-i=" { $emphasis "image" } } { "Specifies the image file to use; see " { $link "images" } } }
  49     { { $snippet "-datastack=" { $emphasis "n" } } "Data stack size, kilobytes" }
  50     { { $snippet "-retainstack=" { $emphasis "n" } } "Retain stack size, kilobytes" }
  51     { { $snippet "-generations=" { $emphasis "n" } } "Number of generations, must equal 1, 2 or 3" }
  52     { { $snippet "-young=" { $emphasis "n" } } { "Size of youngest generation (0), megabytes" } }
  53     { { $snippet "-aging=" { $emphasis "n" } } "Size of aging generation (1), megabytes" }
  54     { { $snippet "-tenured=" { $emphasis "n" } } "Size of oldest generation (2), megabytes" }
  55     { { $snippet "-codeheap=" { $emphasis "n" } } "Code heap size, megabytes" }
  56     { { $snippet "-securegc" } "If specified, unused portions of the data heap will be zeroed out after every garbage collection" }
  57 }
  58 "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)." ;
  59
  60 ARTICLE: "bootstrap-cli-args" "Command line switches for bootstrap"
  61 "A number of command line switches can be passed to a bootstrap image to modify the behavior of the resulting image:"
  62 { $table
  63     { { $snippet "-output-image=" { $emphasis "image" } } { "Save the result to " { $snippet "image" } ". The default is " { $snippet "factor.image" } "." } }
  64     { { $snippet "-no-user-init" } { "Inhibits the running of user initialization files on startup. See " { $link "rc-files" } "." } }
  65     { { $snippet "-include=" { $emphasis "components..." } } "A list of components to include (see below)." }
  66     { { $snippet "-exclude=" { $emphasis "components..." } } "A list of components to exclude." }
  67     { { $snippet "-ui-backend=" { $emphasis "backend" } } { "One of " { $snippet "x11" } ", " { $snippet "windows" } ", or " { $snippet "cocoa" } ". The default is platform-specific." } }
  68 }
  69 "Bootstrap can load various optional components:"
  70 { $table
  71     { { $snippet "math" } "Rational and complex number support." }
  72     { { $snippet "threads" } "Thread support." }
  73     { { $snippet "compiler" } "The compiler." }
  74     { { $snippet "tools" } "Terminal-based developer tools." }
  75     { { $snippet "help" } "The help system." }
  76     { { $snippet "help.handbook" } "The help handbook." }
  77     { { $snippet "ui" } "The graphical user interface." }
  78     { { $snippet "ui.tools" } "Graphical developer tools." }
  79     { { $snippet "io" } "Non-blocking I/O and networking." }
  80 }
  81 "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=" } "."
  82 $nl
  83 "For example, to build an image with the compiler but no other components, you could do:"
  84 { $code "./factor -i=boot.macosx-ppc.image -include=compiler" }
  85 "To build an image with everything except for the user interface and graphical tools,"
  86 { $code "./factor -i=boot.macosx-ppc.image -exclude=\"ui ui.tools\"" }
  87 "To generate a bootstrap image in the first place, see " { $link "bootstrap.image" } "." ;
  88
  89 ARTICLE: "standard-cli-args" "Command line switches for general usage"
  90 "The following command line switches can be passed to a bootstrapped Factor image:"
  91 { $table
  92     { { $snippet "-e=" { $emphasis "code" } } { "This specifies a code snippet to evaluate. If you want Factor to exit immediately after, also specify " { $snippet "-run=none" } "." } }
  93     { { $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" } "." } }
  94     { { $snippet "-no-user-init" } { "Inhibits the running of user initialization files on startup. See " { $link "rc-files" } "." } }
  95     { { $snippet "-quiet" } { "If set, " { $link run-file } " and " { $link require } " will not print load messages." } }
  96 } ;
  97
  98 ARTICLE: "factor-boot-rc" "Bootstrap initialization file"
  99 "The botstrap initialization file is named " { $snippet "factor-boot-rc" } " on Windows and " { $snippet ".factor-boot-rc" } " on Unix. This file can contain " { $link require } " calls for vocabularies you use frequently, and other such long-running tasks that you do not want to perform every time Factor starts."
 100 $nl
 101 "A word to run this file from an existing Factor session:"
 102 { $subsection run-bootstrap-init }
 103 "For example, if you changed " { $snippet ".factor-boot-rc" } " and do not want to bootstrap again, you can just invoke " { $link run-bootstrap-init } " in the listener." ;
 104
 105 ARTICLE: "factor-rc" "Startup initialization file"
 106 "The startup initialization file is named " { $snippet "factor-rc" } " on Windows and " { $snippet ".factor-rc" } " on Unix. If it exists, it is run every time Factor starts."
 107 $nl
 108 "A word to run this file from an existing Factor session:"
 109 { $subsection run-user-init } ;
 110
 111 ARTICLE: "factor-roots" "Additional vocabulary roots file"
 112 "The vocabulary roots file is named " { $snippet "factor-roots" } " on Windows and " { $snippet ".factor-roots" } " on Unix. If it exists, it is loaded every time Factor starts. It contains a newline-separated list of " { $link "vocabs.roots" } "."
 113 $nl
 114 "A word to run this file from an existing Factor session:"
 115 { $subsection load-vocab-roots } ;
 116
 117 ARTICLE: "rc-files" "Running code on startup"
 118 "Factor looks for three optional files in your home directory."
 119 { $subsection "factor-boot-rc" }
 120 { $subsection "factor-rc" }
 121 { $subsection "factor-roots" }
 122 "The " { $snippet "-no-user-init" } " command line switch will inhibit loading running of these files."
 123 $nl
 124 "If you are unsure where the files should be located, evaluate the following code:"
 125 { $code
 126     "USE: command-line"
 127     "\"factor-rc\" rc-path print"
 128     "\"factor-boot-rc\" rc-path print"
 129 }
 130 "Here is an example " { $snippet ".factor-boot-rc" } " which sets up GVIM editor integration, adds an additional vocabulary root (see " { $link "vocabs.roots" } "), and increases the font size in the UI by setting the DPI (dots-per-inch) variable:"
 131 { $code
 132     "USING: editors.gvim vocabs.loader ui.freetype namespaces sequences ;"
 133     "\"/opt/local/bin\" \\ gvim-path set-global"
 134     "\"/home/jane/src/\" vocab-roots get push"
 135     "100 dpi set-global"
 136 } ;
 137
 138 ARTICLE: "cli" "Command line arguments"
 139 "Factor command line usage:"
 140 { $code "factor [system switches...] [script args...]" }
 141 "Zero or more system switches can be passed in, followed by an optional script file name. If the script file is specified, it will be run on startup, any arguments after the script file are stored in a variable, with no further processing by Factor itself:"
 142 { $subsection command-line }
 143 "Instead of running a script, it is also possible to run a vocabulary; this invokes the vocabulary's " { $link POSTPONE: MAIN: } " word:"
 144 { $code "factor [system switches...] -run=<vocab name>" }
 145 "If no script file or " { $snippet "-run=" } " switch is specified, Factor will start " { $link "listener" } " or " { $link "ui-tools" } ", depending on the operating system."
 146 $nl
 147 "As stated above, arguments in the first part of the command line, before the optional script name, are interpreted by to the Factor system. These arguments all start with a dash (" { $snippet "-" } ")."
 148 $nl
 149 "Switches can take one of the following three forms:"
 150 { $list
 151     { { $snippet "-" { $emphasis "foo" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $link t } }
 152     { { $snippet "-no-" { $emphasis "foo" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $link f } }
 153     { { $snippet "-" { $emphasis "foo" } "=" { $emphasis "bar" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $snippet "\"" { $emphasis "bar" } "\"" } }
 154 }
 155 { $subsection "runtime-cli-args" }
 156 { $subsection "bootstrap-cli-args" }
 157 { $subsection "standard-cli-args" }
 158 "The raw list of command line arguments can also be obtained and inspected directly:"
 159 { $subsection (command-line) }
 160 "There is a way to override the default vocabulary to run on startup, if no script name or " { $snippet "-run" } " switch is specified:"
 161 { $subsection main-vocab-hook } ;
 162
 163 ABOUT: "cli"