extra/tools/deploy/deploy-docs.factor

   1 USING: help.markup help.syntax words alien.c-types assocs
   2 kernel ;
   3 IN: tools.deploy
   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
  14 ARTICLE: "deploy-flags" "Deployment flags"
  15 "There are two types of flags. The first set controls the major subsystems which are to be included in the deployment image:"
  16 { $subsection deploy-math?     }
  17 { $subsection deploy-compiled? }
  18 { $subsection deploy-io?       }
  19 { $subsection deploy-ui?       }
  20 "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:"
  21 { $subsection strip-globals?     }
  22 { $subsection strip-word-props?  }
  23 { $subsection strip-word-names?  }
  24 { $subsection strip-dictionary?  }
  25 { $subsection strip-debugger?    }
  26 { $subsection strip-prettyprint? }
  27 { $subsection strip-c-types?     } ;
  28
  29 ARTICLE: "tools.deploy" "Stand-alone image deployment"
  30 "The stand-alone image deployment tool takes a vocabulary and generates an image, which when passed to the VM, runs the vocabulary's " { $link POSTPONE: MAIN: } " hook."
  31 $nl
  32 "For example, we can deploy the " { $vocab-link "hello-world" } " demo which comes with Factor:"
  33 { $code "\"hello-world\" deploy" }
  34 "This generates an image file named " { $snippet "hello-world.image" } ". Now we can start this image from the operating system's command line (see " { $link "runtime-cli-args" } "):"
  35 { $code "./factor -i=hello-world.image" "Hello world" }
  36 "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."
  37 { $subsection "deploy-config" }
  38 { $subsection "deploy-flags" }
  39 "Once the necessary deployment flags have been set, a deployment image can be generated:"
  40 { $subsection deploy } ;
  41
  42 ABOUT: "tools.deploy"
  43
  44 HELP: strip-globals?
  45 { $description "Deploy flag. If set, the deploy tool applies various heuristics to strip out un-needed variables from the global namespace."
  46 $nl
  47 "On by default. Disable this if the heuristics strip out required variables." } ;
  48
  49 HELP: strip-word-props?
  50 { $description "Deploy flag. If set, the deploy tool applies various heuristics to strip out un-needed word properties from words in the dictionary."
  51 $nl
  52 "On by default. Disable this if the heuristics strip out required word properties." } ;
  53
  54 HELP: strip-word-names?
  55 { $description "Deploy flag. If set, the deploy tool strips word names from words in the dictionary."
  56 $nl
  57 "On by default. Disable this if your program calls " { $link word-name } "." } ;
  58
  59 HELP: strip-dictionary?
  60 { $description "Deploy flag. If set, the deploy tool strips unused words."
  61 $nl
  62 "On by default. Disable this if your program calls " { $link lookup } " to look up words by name, or needs to parse code at run-time." } ;
  63
  64 HELP: strip-debugger?
  65 { $description "Deploy flag. If set, the deploy tool strips the verbose error reporting facility; any errors thrown by the program will start the low-level debugger in the VM."
  66 $nl
  67 "On by default. Disable this if you need to debug a problem which only occurs when your program is running deployed." } ;
  68
  69 HELP: strip-prettyprint?
  70 { $description "Deploy flag. If set, the deploy tool strips variables used by the prettyprinter."
  71 $nl
  72 "On by default. Disable this if your program uses the prettyprinter." } ;
  73
  74 HELP: strip-c-types?
  75 { $description "Deploy flag. If set, the deploy tool strips out the " { $link c-types } " table."
  76 $nl
  77 "On by default. Disable this if your program calls " { $link c-type } ", " { $link heap-size } ", " { $link <c-object> } ", " { $link <c-array> } ", " { $link malloc-object } ", or " { $link malloc-array } " with a C type name which is not a literal pushed directly at the call site. In this situation, the compiler is unable to fold away the C type lookup, and thus must use the global table at runtime." } ;
  78
  79 HELP: deploy-math?
  80 { $description "Deploy flag. If set, the deployed image will contain the full number tower."
  81 $nl
  82 "On by default. Most programs require the number tower, in particular, any program deployed with " { $link deploy-compiled? } " set." } ;
  83
  84 HELP: deploy-compiled?
  85 { $description "Deploy flag. If set, words in the deployed image will be compiled when possible."
  86 $nl
  87 "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." } ;
  88
  89 HELP: deploy-ui?
  90 { $description "Deploy flag. If set, the Factor UI will be included in the deployed image."
  91 $nl
  92 "Off by default. Programs wishing to use the UI must be deployed with this flag on." } ;
  93
  94 HELP: deploy-io?
  95 { $description "Deploy flag. If set, support for non-blocking I/O and networking will be included in the deployed image."
  96 $nl
  97 "Off by default. Programs wishing to use non-blocking I/O or networking must be deployed with this flag on." } ;
  98
  99 HELP: default-config
 100 { $values { "assoc" assoc } }
 101 { $description "Outputs the default deployment configuration." } ;
 102
 103 HELP: deploy-config
 104 { $values { "vocab" "a vocabulary specifier" } { "assoc" assoc } }
 105 { $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." } ;
 106
 107 HELP: set-deploy-config
 108 { $values { "assoc" assoc } { "vocab" "a vocabulary specifier" } }
 109 { $description "Stores a vocabulary's deployment configuration to the " { $snippet "deploy.factor" } " file in the vocabulary's directory." } ;
 110
 111 HELP: set-deploy-flag
 112 { $values { "value" object } { "key" object } { "vocab" "a vocabulary specifier" } }
 113 { $description "Modifies an entry in a vocabulary's deployment configuration on disk." } ;
 114
 115 HELP: deploy*
 116 { $values { "vm" "a pathname string" } { "image" "a pathname string" } { "vocab" "a vocabulary specifier" } { "config" assoc } }
 117 { $description "Deploys " { $snippet "vocab" } ", which must have a " { $link POSTPONE: MAIN: } " hook, using the specified VM and configuration. The deployed image is saved as " { $snippet "image" } "." }
 118 { $notes "This is a low-level word and in most cases " { $link deploy } " should be called instead." } ;
 119
 120 HELP: deploy
 121 { $values { "vocab" "a vocabulary specifier" } }
 122 { $description "Deploys " { $snippet "vocab" } ", saving the deployed image as " { $snippet { $emphasis "vocab" } ".image" } "." } ;