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