basis/tools/deploy/deploy-docs.factor

   1 USING: help.markup help.syntax words alien.c-types assocs
   2 kernel combinators combinators.private tools.deploy.config ;
   3 IN: tools.deploy
   4
   5 ARTICLE: "prepare-deploy" "Preparing to deploy an application"
   6 "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."
   7 { $subsection "deploy-config" }
   8 { $subsection "deploy-flags" } ;
   9
  10 ARTICLE: "tools.deploy.usage" "Deploy tool usage"
  11 "Once the necessary deployment flags have been set, the application can be deployed:"
  12 { $subsection deploy }
  13 "For example, you can deploy the " { $vocab-link "hello-ui" } " demo which comes with Factor. Note that this demo already has a deployment configuration, so nothing needs to be configured:"
  14 { $code "\"hello-ui\" deploy" }
  15 { $list
  16    { "On Mac OS X, this yields a program named " { $snippet "Hello world.app" } "." }
  17    { "On Windows, it yields a directory named " { $snippet "Hello world" } " containing a program named " { $snippet "hello-ui.exe" } "." }
  18    { "On Unix-like systems (Linux, BSD, Solaris, etc), it yields a directory named " { $snippet "Hello world" } " containing a program named " { $snippet "hello-ui" } "." }
  19 }
  20 "On all platforms, running the program will display a window with a message." ;
  21
  22 ARTICLE: "tools.deploy.impl" "Deploy tool implementation"
  23 "The deployment tool works by bootstrapping a fresh image, loading the vocabulary into this image, then applying various heuristics to strip the image down to minimal size."
  24 $nl
  25 "The deploy tool generates " { $emphasis "staging images" } " containing major subsystems, and uses the staging images to derive the final application image. The first time an application is deployed using a major subsystem, such as the UI, a new staging image is made, which can take a few minutes. Subsequent deployments of applications using this subsystem will be much faster." ;
  26
  27 ARTICLE: "tools.deploy.caveats" "Deploy tool caveats"
  28 { $heading "Behavior of " { $link boa } }
  29 "In deployed applications, the " { $link boa } " word does not verify that the parameters on the stack satisfy the tuple's slot declarations, if any. This reduces deploy image size but can make bugs harder to track down. Make sure your program is fully debugged before deployment."
  30 { $heading "Behavior of " { $link POSTPONE: execute( } }
  31 "Similarly, the " { $link POSTPONE: execute( } " word does not check word stack effects in deployed applications, since stack effects are stripped out, and so it behaves exactly like " { $link POSTPONE: execute-unsafe( } "."
  32 { $heading "Error reporting" }
  33 "If the " { $link deploy-reflection } " level in the configuration is low enough, the debugger is stripped out, and error messages can be rather cryptic. Increase the reflection level to get readable error messages."
  34 { $heading "Choosing the right deploy flags" }
  35 "Finding the correct deploy flags is a trial and error process; you must find a tradeoff between deployed image size and correctness. If your program uses dynamic language features, you may need to elect to strip out fewer subsystems in order to have full functionality." ;
  36
  37 ARTICLE: "tools.deploy" "Application deployment"
  38 "The stand-alone application deployment tool, implemented in the " { $vocab-link "tools.deploy" } " vocablary, compiles a vocabulary down to a native executable which runs the vocabulary's " { $link POSTPONE: MAIN: } " hook. Deployed executables do not depend on Factor being installed, and do not expose any source code, and thus are suitable for delivering commercial end-user applications."
  39 $nl
  40 "Most of the time, the words in the " { $vocab-link "tools.deploy" } " vocabulary should not be used directly; instead, use " { $link "ui.tools.deploy" } "."
  41 $nl
  42 "You must explicitly specify major subsystems which are required, as well as the level of reflection support needed. This is done by modifying the deployment configuration prior to deployment."
  43 { $subsection "prepare-deploy" }
  44 { $subsection "tools.deploy.usage" }
  45 { $subsection "tools.deploy.impl" }
  46 { $subsection "tools.deploy.caveats" } ;
  47
  48 ABOUT: "tools.deploy"
  49
  50 HELP: deploy
  51 { $values { "vocab" "a vocabulary specifier" } }
  52 { $description "Deploys " { $snippet "vocab" } ", saving the deployed image as " { $snippet { $emphasis "vocab" } ".image" } "." } ;