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

   1 USING: help.markup help.syntax words alien.c-types alien.data assocs
   2 kernel math ;
   3 IN: tools.deploy.config
   4
   5 ARTICLE: "deploy-flags" "Deployment flags"
   6 "There are two sets of deployment flags. The first set controls the major subsystems which are to be included in the deployment image:"
   7 { $subsections
   8     deploy-math?
   9     deploy-unicode?
  10     deploy-threads?
  11     deploy-ui?
  12 }
  13 "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:"
  14 { $subsections
  15     deploy-io
  16     deploy-reflection
  17     deploy-word-props?
  18     deploy-c-types?
  19 } ;
  20
  21 ABOUT: "deploy-flags"
  22
  23 HELP: deploy-name
  24 { $description "Deploy setting. The name of the executable."
  25 $nl
  26 "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." } ;
  27
  28 HELP: deploy-word-props?
  29 { $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."
  30 $nl
  31 "Off by default. Enable this if the heuristics strip out required word properties." } ;
  32
  33 HELP: deploy-word-defs?
  34 { $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."
  35 $nl
  36 "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." } ;
  37
  38 HELP: deploy-c-types?
  39 { $description "Deploy flag. If set, the deploy tool retains word properties containing metadata for C types and struct classes; otherwise, these properties are stripped out, saving space."
  40 $nl
  41 "Off by default."
  42 $nl
  43 "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, for example,"
  44 { $list
  45     { $link c-type }
  46     { $link heap-size }
  47     { $link <c-array> }
  48     { $link <c-direct-array> }
  49     { $link malloc-array }
  50     { $link <ref> }
  51     { $link deref }
  52 }
  53 "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 code is not folded away and the word properties must be consulted at runtime." } ;
  54
  55 HELP: deploy-math?
  56 { $description "Deploy flag. If set, the deployed image will contain support for " { $link ratio } " and " { $link complex } " types."
  57 $nl
  58 "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." } ;
  59
  60 HELP: deploy-unicode?
  61 { $description "Deploy flag. If set, full Unicode " { $link POSTPONE: CHAR: } " syntax is included."
  62 $nl
  63 "Off by default. If your program needs to use " { $link POSTPONE: CHAR: } " with named characters, enable this flag." } ;
  64
  65 HELP: deploy-threads?
  66 { $description "Deploy flag. If set, thread support will be included in the final image."
  67 $nl
  68 "On by default. Most programs depend on libraries which use threads even if they don't use threads directly; for example, timers, 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." } ;
  69
  70 HELP: deploy-ui?
  71 { $description "Deploy flag. If set, the Factor UI will be included in the deployed image."
  72 $nl
  73 "Off by default. Programs wishing to use the UI must be deployed with this flag on." } ;
  74
  75 HELP: deploy-io
  76 { $description "The level of I/O support required by the deployed image:"
  77     { $table
  78         { "Value" "Description" }
  79         { "1" "No input/output" }
  80         { "2" "Basic ANSI C streams" }
  81         { "3" "Non-blocking streams and networking" }
  82     }
  83 "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." } ;
  84
  85 HELP: deploy-reflection
  86 { $description "The level of reflection support required by the deployed image."
  87     { $table
  88         { "Value" "Description" }
  89         { "1" "No reflection" }
  90         { "2" "Retain word names" }
  91         { "3" "Prettyprinter" }
  92         { "4" "Debugger" }
  93         { "5" "Parser" }
  94         { "6" "Full environment" }
  95     }
  96 "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." } ;
  97
  98 HELP: default-config
  99 { $values { "vocab" "a vocabulary specifier" } { "assoc" assoc } }
 100 { $description "Outputs the default deployment configuration for a vocabulary." } ;