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

   1 USING: help.markup help.syntax parser vocabs.loader strings ;
   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 command line parameters which were passed to the Factor VM on startup." } ;
  26
  27 HELP: command-line
  28 { $var-description "When Factor is run with a script, this variable contains command line parameters which follow the name of the script on the command line. In deployed applications, it contains the entire command line. In all other cases it is set to " { $link f } "." } ;
  29
  30 HELP: main-vocab-hook
  31 { $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)." } ;
  32
  33 HELP: main-vocab
  34 { $values { "vocab" string } }
  35 { $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." } ;
  36
  37 HELP: default-cli-args
  38 { $description "Sets global variables corresponding to default command line arguments." } ;
  39
  40 ARTICLE: "runtime-cli-args" "Command line switches for the VM"
  41 "A handful of command line switches are processed by the VM and not the library. They control low-level features."
  42 { $table
  43     { { $snippet "-i=" { $emphasis "image" } } { "Specifies the image file to use; see " { $link "images" } } }
  44     { { $snippet "-datastack=" { $emphasis "n" } } "Data stack size, kilobytes" }
  45     { { $snippet "-retainstack=" { $emphasis "n" } } "Retain stack size, kilobytes" }
  46     { { $snippet "-callstack=" { $emphasis "n" } } "Call stack size, kilobytes" }
  47     { { $snippet "-young=" { $emphasis "n" } } { "Size of youngest generation (0), megabytes" } }
  48     { { $snippet "-aging=" { $emphasis "n" } } "Size of aging generation (1), megabytes" }
  49     { { $snippet "-tenured=" { $emphasis "n" } } "Size of oldest generation (2), megabytes" }
  50     { { $snippet "-codeheap=" { $emphasis "n" } } "Code heap size, megabytes" }
  51     { { $snippet "-callbacks=" { $emphasis "n" } } "Callback heap size, megabytes" }
  52     { { $snippet "-pic=" { $emphasis "n" } } "Maximum inline cache size. Setting of 0 disables inline caching, > 1 enables polymorphic inline caching" }
  53     { { $snippet "-securegc" } "If specified, unused portions of the data heap will be zeroed out after every garbage collection" }
  54 }
  55 "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." ;
  56
  57 ARTICLE: "bootstrap-cli-args" "Command line switches for bootstrap"
  58 "A number of command line switches can be passed to a bootstrap image to modify the behavior of the resulting image:"
  59 { $table
  60     { { $snippet "-output-image=" { $emphasis "image" } } { "Save the result to " { $snippet "image" } ". The default is " { $snippet "factor.image" } "." } }
  61     { { $snippet "-no-user-init" } { "Inhibits the running of user initialization files on startup. See " { $link "rc-files" } "." } }
  62     { { $snippet "-include=" { $emphasis "components..." } } "A list of components to include (see below)." }
  63     { { $snippet "-exclude=" { $emphasis "components..." } } "A list of components to exclude." }
  64     { { $snippet "-ui-backend=" { $emphasis "backend" } } { "One of " { $snippet "x11" } ", " { $snippet "windows" } ", or " { $snippet "cocoa" } ". The default is platform-specific." } }
  65 }
  66 "Bootstrap can load various optional components:"
  67 { $table
  68     { { $snippet "math" } "Rational and complex number support." }
  69     { { $snippet "threads" } "Thread support." }
  70     { { $snippet "compiler" } "The compiler." }
  71     { { $snippet "tools" } "Terminal-based developer tools." }
  72     { { $snippet "help" } "The help system." }
  73     { { $snippet "help.handbook" } "The help handbook." }
  74     { { $snippet "ui" } "The graphical user interface." }
  75     { { $snippet "ui.tools" } "Graphical developer tools." }
  76     { { $snippet "io" } "Non-blocking I/O and networking." }
  77 }
  78 "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=" } "."
  79 $nl
  80 "For example, to build an image with the compiler but no other components, you could do:"
  81 { $code "./factor -i=boot.macosx-ppc.image -include=compiler" }
  82 "To build an image with everything except for the user interface and graphical tools,"
  83 { $code "./factor -i=boot.macosx-ppc.image -exclude=\"ui ui.tools\"" }
  84 "To generate a bootstrap image in the first place, see " { $link "bootstrap.image" } "." ;
  85
  86 ARTICLE: "standard-cli-args" "Command line switches for general usage"
  87 "The following command line switches can be passed to a bootstrapped Factor image:"
  88 { $table
  89     { { $snippet "-e=" { $emphasis "code" } } { "This specifies a code snippet to evaluate. If you want Factor to exit immediately after, also specify " { $snippet "-run=none" } "." } }
  90     { { $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.tools" } " or " { $vocab-link "none" } "." } }
  91     { { $snippet "-no-user-init" } { "Inhibits the running of user initialization files on startup. See " { $link "rc-files" } "." } }
  92 } ;
  93
  94 ARTICLE: ".factor-boot-rc" "Bootstrap initialization file"
  95 "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."
  96 $nl
  97 "A word to run this file from an existing Factor session:"
  98 { $subsections run-bootstrap-init }
  99 "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." ;
 100
 101 ARTICLE: ".factor-rc" "Startup initialization file"
 102 "The startup initialization file is named " { $snippet ".factor-rc" } ". If it exists, it is run every time Factor starts."
 103 $nl
 104 "A word to run this file from an existing Factor session:"
 105 { $subsections run-user-init } ;
 106
 107 ARTICLE: ".factor-roots" "Additional vocabulary roots file"
 108 "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" } "."
 109 $nl
 110 "A word to run this file from an existing Factor session:"
 111 { $subsections load-vocab-roots } ;
 112
 113 ARTICLE: "rc-files" "Running code on startup"
 114 "Factor looks for three optional files in your home directory."
 115 { $subsections
 116     ".factor-boot-rc"
 117     ".factor-rc"
 118     ".factor-roots"
 119 }
 120 "The " { $snippet "-no-user-init" } " command line switch will inhibit loading running of these files."
 121 $nl
 122 "If you are unsure where the files should be located, evaluate the following code:"
 123 { $code
 124     "USE: command-line"
 125     "\".factor-rc\" rc-path print"
 126     "\".factor-boot-rc\" rc-path print"
 127 }
 128 "Here is an example " { $snippet ".factor-boot-rc" } " which sets up GVIM editor integration:"
 129 { $code
 130     "USING: editors.gvim namespaces ;"
 131     "\"/opt/local/bin\" \\ gvim-path set-global"
 132 } ;
 133
 134 ARTICLE: "cli" "Command line arguments"
 135 "Factor command line usage:"
 136 { $code "factor [VM args...] [script] [args...]" }
 137 "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:"
 138 { $subsections command-line }
 139 "Instead of running a script, it is also possible to run a vocabulary; this invokes the vocabulary's " { $link POSTPONE: MAIN: } " word:"
 140 { $code "factor [system switches...] -run=<vocab name>" }
 141 "If no script file or " { $snippet "-run=" } " switch is specified, Factor will start " { $link "listener" } " or " { $link "ui-tools" } ", depending on the operating system."
 142 $nl
 143 "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 "-" } ")."
 144 $nl
 145 "Switches can take one of the following three forms:"
 146 { $list
 147     { { $snippet "-" { $emphasis "foo" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $link t } }
 148     { { $snippet "-no-" { $emphasis "foo" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $link f } }
 149     { { $snippet "-" { $emphasis "foo" } "=" { $emphasis "bar" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $snippet "\"" { $emphasis "bar" } "\"" } }
 150 }
 151 { $subsections
 152     "runtime-cli-args"
 153     "bootstrap-cli-args"
 154     "standard-cli-args"
 155 }
 156 "The raw list of command line arguments can also be obtained and inspected directly:"
 157 { $subsections (command-line) }
 158 "There is a way to override the default vocabulary to run on startup, if no script name or " { $snippet "-run" } " switch is specified:"
 159 { $subsections main-vocab-hook } ;
 160
 161 HELP: run-script
 162 { $values { "file" "a pathname string" } }
 163 { $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." }
 164 { $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." }  ;
 165
 166 ABOUT: "cli"