basis/tools/deploy/config/config-docs.factor

   1 USING: help.markup help.syntax words alien.c-types assocs
   2 kernel math ;
   3 IN: tools.deploy.config
   4
   5 ARTICLE: "deploy-config" "Deployment configuration"
   6 "The deployment configuration is a key/value mapping stored in the " { $snippet "deploy.factor" } " file in the vocabulary's directory. If this file does not exist, the default deployment configuration is used:"
   7 { $subsection default-config }
   8 "The deployment configuration can be read and written with a pair of words:"
   9 { $subsection deploy-config }
  10 { $subsection set-deploy-config }
  11 "A utility word is provided to load the configuration, change a flag, and store it back to disk:"
  12 { $subsection set-deploy-flag }
  13 "The " { $link "ui.tools.deploy" } " provides a graphical way of editing the configuration." ;
  14
  15 ARTICLE: "deploy-flags" "Deployment flags"
  16 "There are two sets of deployment flags. The first set controls the major subsystems which are to be included in the deployment image:"
  17 { $subsection deploy-math?     }
  18 { $subsection deploy-compiler? }
  19 { $subsection deploy-random?   }
  20 { $subsection deploy-threads?  }
  21 { $subsection deploy-ui?       }
  22 "The second set of flags controls the level of stripping to be performed on the deployment image; there is a trade-off between image size, and retaining functionality which is required by the application:"
  23 { $subsection deploy-io          }
  24 { $subsection deploy-reflection  }
  25 { $subsection deploy-word-props? }
  26 { $subsection deploy-c-types?    } ;
  27
  28 ARTICLE: "prepare-deploy" "Preparing to deploy an application"
  29 "In order to deploy an application as a stand-alone image, the application's vocabulary must first be given a " { $link POSTPONE: MAIN: } " hook. Then, a " { $emphasis "deployment configuration" } " must be created."
  30 { $subsection "deploy-config" }
  31 { $subsection "deploy-flags" } ;
  32
  33 ABOUT: "prepare-deploy"
  34
  35 HELP: deploy-name
  36 { $description "Deploy setting. The name of the executable."
  37 $nl
  38 "On Mac OS X, this becomes the name of the application bundle, with " { $snippet ".app" } " appended. On Windows, this becomes the name of the directory containing the executable." } ;
  39
  40 HELP: deploy-word-props?
  41 { $description "Deploy flag. If set, the deploy tool retains all word properties. Otherwise, it applies various heuristics to strip out un-needed word properties from words in the dictionary."
  42 $nl
  43 "Off by default. Enable this if the heuristics strip out required word properties." } ;
  44
  45 HELP: deploy-word-defs?
  46 { $description "Deploy flag. If set, the deploy tool retains word definition quotations for words compiled with the optimizing compiler. Otherwise, word definitions are stripped from words compiled with the optimizing compiler."
  47 $nl
  48 "Off by default. During normal execution, the word definition quotation of a word compiled with the optimizing compiler is not used, so disabling this flag can save space. However, some libraries introspect word definitions dynamically (for example, " { $vocab-link "inverse" } ") and so programs using these libraries must retain word definition quotations." } ;
  49
  50 HELP: deploy-c-types?
  51 { $description "Deploy flag. If set, the deploy tool retains the " { $link c-types } " table, otherwise this table is stripped out, saving space."
  52 $nl
  53 "Off by default."
  54 $nl
  55 "The optimizing compiler is able to fold away calls to various words which take a C type as an input if the C type is a literal string:"
  56 { $list
  57     { $link c-type }
  58     { $link heap-size }
  59     { $link <c-object> }
  60     { $link <c-array> }
  61     { $link malloc-object }
  62     { $link malloc-array }
  63 }
  64 "If your program looks up C types dynamically or from words which do not have a stack effect, you must enable this flag, because in these situations the C type lookup is not folded away and the global table must be consulted at runtime." } ;
  65
  66 HELP: deploy-math?
  67 { $description "Deploy flag. If set, the deployed image will contain support for " { $link ratio } " and " { $link complex } " types."
  68 $nl
  69 "On by default. Often the programmer will use rationals without realizing it. A small amount of space can be saved by stripping these features out, but some code may require changes to work properly." } ;
  70
  71 HELP: deploy-compiler?
  72 { $description "Deploy flag. If set, words in the deployed image will be compiled with the optimizing compiler when possible."
  73 $nl
  74 "On by default. Most programs should be compiled, not only for performance but because features which depend on the C library interface only function after compilation." } ;
  75
  76 HELP: deploy-random?
  77 { $description "Deploy flag. If set, the random number generator protocol is included, together with two implementations: a native OS-specific random number generator, and the Mersenne Twister."
  78 $nl
  79 "On by default. If your program does not generate random numbers you can disable this to save some space." } ;
  80
  81 HELP: deploy-threads?
  82 { $description "Deploy flag. If set, thread support will be included in the final image."
  83 $nl
  84 "On by default. Most programs depend on libraries which use threads even if they don't use threads directly; for example, alarms, non-blocking I/O, and the UI are built on top of threads. If after testing your program still works without threads, you can disable this feature to save some space." } ;
  85
  86 HELP: deploy-ui?
  87 { $description "Deploy flag. If set, the Factor UI will be included in the deployed image."
  88 $nl
  89 "Off by default. Programs wishing to use the UI must be deployed with this flag on." } ;
  90
  91 HELP: deploy-io
  92 { $description "The level of I/O support required by the deployed image:"
  93     { $table
  94         { "Value" "Description" }
  95         { "1" "No input/output" }
  96         { "2" "Basic ANSI C streams" }
  97         { "3" "Non-blocking streams and networking" }
  98     }
  99 "The default value is 2, basic ANSI C streams. This enables basic console and file I/O, however more advanced features such as networking are not available." } ;
 100
 101 HELP: deploy-reflection
 102 { $description "The level of reflection support required by the deployed image."
 103     { $table
 104         { "Value" "Description" }
 105         { "1" "No reflection" }
 106         { "2" "Retain word names" }
 107         { "3" "Prettyprinter" }
 108         { "4" "Debugger" }
 109         { "5" "Parser" }
 110         { "6" "Full environment" }
 111     }
 112 "The defalut value is 1, no reflection. Programs which use the above features will need to be deployed with a higher level of reflection support." } ;
 113
 114 HELP: default-config
 115 { $values { "vocab" "a vocabulary specifier" } { "assoc" assoc } }
 116 { $description "Outputs the default deployment configuration for a vocabulary." } ;
 117
 118 HELP: deploy-config
 119 { $values { "vocab" "a vocabulary specifier" } { "assoc" assoc } }
 120 { $description "Loads a vocabulary's deployment configuration from the " { $snippet "deploy.factor" } " file in the vocabulary's directory. If the file does not exist, the " { $link default-config } " is output." } ;
 121
 122 HELP: set-deploy-config
 123 { $values { "assoc" assoc } { "vocab" "a vocabulary specifier" } }
 124 { $description "Stores a vocabulary's deployment configuration to the " { $snippet "deploy.factor" } " file in the vocabulary's directory." } ;
 125
 126 HELP: set-deploy-flag
 127 { $values { "value" object } { "key" object } { "vocab" "a vocabulary specifier" } }
 128 { $description "Modifies an entry in a vocabulary's deployment configuration on disk." } ;