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

   1 USING: help.markup help.syntax strings system vocabs vocabs.loader ;
   2 IN: command-line
   3
   4 HELP: run-bootstrap-init
   5 { $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" } "." } ;
   6
   7 HELP: run-user-init
   8 { $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" } "." } ;
   9
  10 HELP: load-vocab-roots
  11 { $description "Loads the newline-separated list of additional vocabulary roots from the file named " { $snippet ".factor-roots" } "." } ;
  12
  13 HELP: param
  14 { $values { "param" string } }
  15 { $description "Process a command-line switch."
  16 $nl
  17 "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."
  18 $nl
  19 "If the parameter begins with " { $snippet "no-" } ", sets the global variable named by the parameter with the prefix removed to " { $link f } "."
  20 $nl
  21 "Otherwise, sets the global variable named by the parameter to " { $link t } "." } ;
  22
  23 HELP: (command-line)
  24 { $values { "args" "a sequence of strings" } }
  25 { $description "Outputs the raw command line parameters which were passed to the Factor VM on startup."
  26 $nl
  27 "We recommend using the " { $link vm-path } " and " { $link command-line } " symbols instead." } ;
  28
  29 HELP: command-line
  30 { $var-description "When Factor is run with a script, this variable contains the list of command line arguments which follow the name of the script on the command line. In deployed applications, it contains the full list of command line arguments. In all other cases it is set to " { $link f } "." }
  31 { $see-also vm-path } ;
  32
  33 HELP: main-vocab-hook
  34 { $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)." } ;
  35
  36 HELP: main-vocab
  37 { $values { "vocab" string } }
  38 { $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." } ;
  39
  40 HELP: default-cli-args
  41 { $description "Sets global variables corresponding to default command line arguments." } ;
  42
  43 ARTICLE: "runtime-cli-args" "Command line switches for the VM"
  44 "A handful of command line switches are processed by the VM and not the library. They control low-level features."
  45 { $table
  46     { { $snippet "-i=" { $emphasis "image" } } { "Specifies the image file to use; see " { $link "images" } } }
  47     { { $snippet "-datastack=" { $emphasis "n" } } "Datastack size, kilobytes" }
  48     { { $snippet "-retainstack=" { $emphasis "n" } } "Retainstack size, kilobytes" }
  49     { { $snippet "-callstack=" { $emphasis "n" } } "Callstack size, kilobytes" }
  50     { { $snippet "-callbacks=" { $emphasis "n" } } "Callback heap size, kilobytes" }
  51     { { $snippet "-young=" { $emphasis "n" } } { "Size of youngest generation (0), megabytes" } }
  52     { { $snippet "-aging=" { $emphasis "n" } } "Size of aging generation (1), megabytes" }
  53     { { $snippet "-tenured=" { $emphasis "n" } } "Size of oldest generation (2), megabytes" }
  54     { { $snippet "-codeheap=" { $emphasis "n" } } "Code heap size, megabytes" }
  55     { { $snippet "-pic=" { $emphasis "n" } } "Maximum inline cache size. Setting of 0 disables inline caching, >= 1 enables polymorphic inline caching" }
  56     { { $snippet "-fep" } "enter low-level debbugger, aka fep mode immediately" }
  57     { { $snippet "-no-signals" } "turn off OS signal handling" }
  58     { { $snippet "-console" } "open console if possible" }
  59 }
  60 "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 Factor executable." ;
  61
  62 ARTICLE: "bootstrap-cli-args" "Command line switches for bootstrap"
  63 "A number of command line switches can be passed to a bootstrap image to modify the behavior of the resulting image:"
  64 { $table
  65     { { $snippet "-output-image=" { $emphasis "image" } } { "Save the result to " { $snippet "image" } ". The default is " { $snippet "factor.image" } "." } }
  66     { { $snippet "-no-user-init" } { "Inhibits the running of user initialization files on startup. See " { $link "rc-files" } "." } }
  67     { { $snippet "-include=" { $emphasis "components..." } } "A list of components to include (see below)." }
  68     { { $snippet "-exclude=" { $emphasis "components..." } } "A list of components to exclude." }
  69     { { $snippet "-ui-backend=" { $emphasis "backend" } } { "One of " { $snippet "x11" } ", " { $snippet "windows" } ", or " { $snippet "cocoa" } ". The default is platform-specific." } }
  70 }
  71 "Bootstrap can load various optional components:"
  72 { $table
  73     { { $snippet "math" } "Rational and complex number support." }
  74     { { $snippet "threads" } "Thread support." }
  75     { { $snippet "compiler" } "The compiler." }
  76     { { $snippet "tools" } "Terminal-based developer tools." }
  77     { { $snippet "help" } "The help system." }
  78     { { $snippet "help.handbook" } "The help handbook." }
  79     { { $snippet "ui" } "The graphical user interface." }
  80     { { $snippet "ui.tools" } "Graphical developer tools." }
  81     { { $snippet "io" } "Non-blocking I/O and networking." }
  82 }
  83 "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=" } "."
  84 $nl
  85 "For example, to build an image with the compiler but no other components, you could do:"
  86 { $code "./factor -i=boot.unix-x86.64.image -include=compiler" }
  87 "To build an image with everything except for the user interface and graphical tools,"
  88 { $code "./factor -i=boot.unix-x86.64.image -exclude=\"ui ui.tools\"" }
  89 "To generate a bootstrap image in the first place, see " { $link "bootstrap.image" } "." ;
  90
  91 ARTICLE: "standard-cli-args" "Command line switches for general usage"
  92 "The following command line switches can be passed to a bootstrapped Factor image:"
  93 { $table
  94     { { $snippet "-help" } { "Show help for the command line switches." } }
  95     { { $snippet "-e=" { $emphasis "code" } } { "This specifies a code snippet to evaluate and then exit Factor." } }
  96     { { $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" } " or " { $vocab-link "ui.tools" } "." } }
  97     { { $snippet "-no-user-init" } { "Inhibits the running of user initialization files on startup. See " { $link "rc-files" } "." } }
  98 } ;
  99
 100 ARTICLE: ".factor-boot-rc" "Bootstrap initialization file"
 101 "The bootstrap initialization file is named " { $snippet ".factor-boot-rc" } ". 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."
 102 $nl
 103 "A word to run this file from an existing Factor session:"
 104 { $subsections run-bootstrap-init }
 105 "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." ;
 106
 107 ARTICLE: ".factor-rc" "Startup initialization file"
 108 "The startup initialization file is named " { $snippet ".factor-rc" } ". If it exists, it is run every time Factor starts."
 109 $nl
 110 "A word to run this file from an existing Factor session:"
 111 { $subsections run-user-init } ;
 112
 113 ARTICLE: ".factor-roots" "Additional vocabulary roots file"
 114 "The vocabulary roots file is named " { $snippet ".factor-roots" } ". If it exists, it is loaded every time Factor starts. It contains a newline-separated list of " { $link "vocabs.roots" } "."
 115 $nl
 116 "A word to load this file from an existing Factor session:"
 117 { $subsections load-vocab-roots } ;
 118
 119 ARTICLE: "rc-files" "Running code on startup"
 120 "Factor looks for three optional files in your home directory."
 121 { $subsections
 122     ".factor-boot-rc"
 123     ".factor-rc"
 124     ".factor-roots"
 125 }
 126 "The " { $snippet "-no-user-init" } " command line switch will inhibit loading running of these files."
 127 $nl
 128 "If you are unsure where the files should be located, evaluate the following code:"
 129 { $code
 130     "USE: command-line"
 131     "\".factor-rc\" rc-path print"
 132     "\".factor-boot-rc\" rc-path print"
 133 }
 134 "Here is an example " { $snippet ".factor-boot-rc" } " which sets up your developer name:"
 135 { $code
 136     "USING: tools.scaffold namespaces ;"
 137     "\"Sheeple Sheepleton\" developer-name set-global"
 138 } ;
 139
 140 ARTICLE: "command-line" "Command line arguments"
 141 "Factor command line usage:"
 142 { $code "factor [VM args...] [script] [args...]" }
 143 "Zero or more VM arguments can be passed in, followed by an optional script file name. If the script file is specified, it will be run on startup using " { $link run-script } ". Any arguments after the script file are stored in the following variable, with no further processing by Factor itself:"
 144 { $subsections command-line }
 145 "Instead of running a script, it is also possible to run a vocabulary; this invokes the vocabulary's " { $link POSTPONE: MAIN: } " word:"
 146 { $code "factor [system switches...] -run=<vocab name>" }
 147 "If no script file or " { $snippet "-run=" } " switch is specified, Factor will start " { $link "listener" } " or " { $link "ui-tools" } ", depending on the operating system."
 148 $nl
 149 "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 "-" } ")."
 150 $nl
 151 "Switches can take one of the following three forms:"
 152 { $list
 153     { { $snippet "-" { $emphasis "foo" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $link t } }
 154     { { $snippet "-no-" { $emphasis "foo" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $link f } }
 155     { { $snippet "-" { $emphasis "foo" } "=" { $emphasis "bar" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $snippet "\"" { $emphasis "bar" } "\"" } }
 156 }
 157 { $subsections
 158     "runtime-cli-args"
 159     "bootstrap-cli-args"
 160     "standard-cli-args"
 161 }
 162 "The raw list of command line arguments can also be obtained and inspected directly:"
 163 { $subsections (command-line) }
 164 "There is a way to override the default vocabulary to run on startup, if no script name or " { $snippet "-run" } " switch is specified:"
 165 { $subsections main-vocab-hook } ;
 166
 167 HELP: run-script
 168 { $values { "file" "a pathname string" } }
 169 { $description "Parses the Factor source code stored in a file and runs it. The initial vocabulary search path is used. If the source file contains a " { $link POSTPONE: MAIN: } " declaration, the main entry point of the file will be also be executed. Loading messages will be suppressed." }
 170 { $errors "Throws an error if loading the file fails, there input is malformed, or if a runtime error occurs while calling the parsed quotation or executing the main entry point." } ;
 171
 172 ABOUT: "command-line"