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 { $subsections
   8     "deploy-config"
   9     "deploy-flags"
  10     "deploy-resources"
  11 } ;
  12
  13 ARTICLE: "deploy-resources" "Deployed resource files"
  14 "To include additional files in your deployed application, specify their names in a vocabulary's " { $snippet "resources.txt" } " file. The " { $snippet "resources.txt" } " file contains one glob pattern per line. These patterns are expanded relative to the vocabulary directory; files outside of the vocabulary directory cannot be referenced. If a file inside the vocabulary directory matches any of these patterns, it will be included in deployed applications that reference the vocabulary. If a subdirectory matches, its contents will be included recursively."
  15 $nl
  16 "If the deployed vocabulary includes an icon file for the current platform, it will be embedded in the deployed application as its GUI icon. See " { $link "vocabs.icons" } "." ;
  17
  18 ARTICLE: "tools.deploy.usage" "Deploy tool usage"
  19 "Once the necessary deployment flags have been set, the application can be deployed:"
  20 { $subsections deploy deploy-image-only }
  21 "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:"
  22 { $code "\"hello-ui\" deploy" }
  23 { $list
  24    { "On Mac OS X, this yields a program named " { $snippet "Hello world.app" } "." }
  25    { "On Windows, it yields a directory named " { $snippet "Hello world" } " containing a program named " { $snippet "hello-ui.exe" } "." }
  26    { "On Unix-like systems (Linux, BSD, Solaris, etc), it yields a directory named " { $snippet "Hello world" } " containing a program named " { $snippet "hello-ui" } "." }
  27 }
  28 "On all platforms, running the program will display a window with a message." ;
  29
  30 ARTICLE: "tools.deploy.impl" "Deploy tool implementation"
  31 "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."
  32 $nl
  33 "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." ;
  34
  35 ARTICLE: "tools.deploy.caveats" "Deploy tool caveats"
  36 { $heading "Behavior of " { $link boa } }
  37 "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."
  38 { $heading "Behavior of " { $link POSTPONE: execute( } }
  39 "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-effect-unsafe } "."
  40 { $heading "Behavior of " { $link POSTPONE: call-next-method } }
  41 "The " { $link POSTPONE: call-next-method } " word does not check if the input is of the right type in deployed applications."
  42 { $heading "Error reporting" }
  43 "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."
  44 { $heading "Choosing the right deploy flags" }
  45 "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." ;
  46
  47 ARTICLE: "tools.deploy" "Application deployment"
  48 "The stand-alone application deployment tool, implemented in the " { $vocab-link "tools.deploy" } " vocabulary, 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."
  49 $nl
  50 "Most of the time, the words in the " { $vocab-link "tools.deploy" } " vocabulary should not be used directly; instead, use " { $link "ui.tools.deploy" } "."
  51 $nl
  52 "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."
  53 { $subsections
  54     "prepare-deploy"
  55     "tools.deploy.usage"
  56     "tools.deploy.impl"
  57     "tools.deploy.caveats"
  58 } ;
  59
  60 ABOUT: "tools.deploy"
  61
  62 HELP: deploy
  63 { $values { "vocab" "a vocabulary specifier" } }
  64 { $description "Deploys " { $snippet "vocab" } " into a packaged application. This will create a directory containing the Factor VM, a deployed image set up to run the " { $link POSTPONE: MAIN: } " entry point of " { $snippet "vocab" } " at startup, and any " { $link "deploy-resources" } " and shared libraries the application depends on. On Mac OS X, the deployment directory will be a standard " { $snippet ".app" } " bundle executable from Finder. To only generate the Factor image, use " { $link deploy-image-only } "." } ;
  65
  66 HELP: deploy-image-only
  67 { $values { "vocab" "a vocabulary specifier" } { "image" "a pathname" } }
  68 { $description "Deploys " { $snippet "vocab" } ", saving the deployed image to the location specified by " { $snippet "image" } ". This only builds the Factor image for the vocabulary; to create a complete packaged application, use " { $link deploy } "." } ;
  69
  70 { deploy deploy-image-only } related-words