USING: help.markup help.syntax words alien.c-types assocs
kernel ;
IN: tools.deploy

ARTICLE: "deploy-config" "Deployment configuration"
"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:"
{ $subsection default-config }
"The deployment configuration can be read and written with a pair of words:"
{ $subsection deploy-config }
{ $subsection set-deploy-config }
"A utility word is provided to load the configuration, change a flag, and store it back to disk:"
{ $subsection set-deploy-flag } ;

ARTICLE: "deploy-flags" "Deployment flags"
"There are two types of flags. The first set controls the major subsystems which are to be included in the deployment image:"
{ $subsection deploy-math?     }
{ $subsection deploy-compiled? }
{ $subsection deploy-io?       }
{ $subsection deploy-ui?       }
"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:"
{ $subsection strip-globals?     }
{ $subsection strip-word-props?  }
{ $subsection strip-word-names?  }
{ $subsection strip-dictionary?  }
{ $subsection strip-debugger?    }
{ $subsection strip-prettyprint? }
{ $subsection strip-c-types?     } ;

ARTICLE: "tools.deploy" "Stand-alone image deployment"
"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."
$nl
"For example, we can deploy the " { $vocab-link "hello-world" } " demo which comes with Factor:"
{ $code "\"hello-world\" deploy" }
"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" } "):"
{ $code "./factor -i=hello-world.image" "Hello world" }
"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."
{ $subsection "deploy-config" }
{ $subsection "deploy-flags" }
"Once the necessary deployment flags have been set, a deployment image can be generated:"
{ $subsection deploy } ;

ABOUT: "tools.deploy"

HELP: strip-globals?
{ $description "Deploy flag. If set, the deploy tool applies various heuristics to strip out un-needed variables from the global namespace."
$nl
"On by default. Disable this if the heuristics strip out required variables." } ;

HELP: strip-word-props?
{ $description "Deploy flag. If set, the deploy tool applies various heuristics to strip out un-needed word properties from words in the dictionary."
$nl
"On by default. Disable this if the heuristics strip out required word properties." } ;

HELP: strip-word-names?
{ $description "Deploy flag. If set, the deploy tool strips word names from words in the dictionary."
$nl
"On by default. Disable this if your program calls " { $link word-name } "." } ;

HELP: strip-dictionary?
{ $description "Deploy flag. If set, the deploy tool strips unused words."
$nl
"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." } ;

HELP: strip-debugger?
{ $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."
$nl
"On by default. Disable this if you need to debug a problem which only occurs when your program is running deployed." } ;

HELP: strip-prettyprint?
{ $description "Deploy flag. If set, the deploy tool strips variables used by the prettyprinter."
$nl
"On by default. Disable this if your program uses the prettyprinter." } ;

HELP: strip-c-types?
{ $description "Deploy flag. If set, the deploy tool strips out the " { $link c-types } " table."
$nl
"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." } ;

HELP: deploy-math?
{ $description "Deploy flag. If set, the deployed image will contain the full number tower."
$nl
"On by default. Most programs require the number tower, in particular, any program deployed with " { $link deploy-compiled? } " set." } ;

HELP: deploy-compiled?
{ $description "Deploy flag. If set, words in the deployed image will be compiled when possible."
$nl
"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." } ;

HELP: deploy-ui?
{ $description "Deploy flag. If set, the Factor UI will be included in the deployed image."
$nl
"Off by default. Programs wishing to use the UI must be deployed with this flag on." } ;

HELP: deploy-io?
{ $description "Deploy flag. If set, support for non-blocking I/O and networking will be included in the deployed image."
$nl
"Off by default. Programs wishing to use non-blocking I/O or networking must be deployed with this flag on." } ;

HELP: default-config
{ $values { "assoc" assoc } }
{ $description "Outputs the default deployment configuration." } ;

HELP: deploy-config
{ $values { "vocab" "a vocabulary specifier" } { "assoc" assoc } }
{ $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." } ;

HELP: set-deploy-config
{ $values { "assoc" assoc } { "vocab" "a vocabulary specifier" } }
{ $description "Stores a vocabulary's deployment configuration to the " { $snippet "deploy.factor" } " file in the vocabulary's directory." } ;

HELP: set-deploy-flag
{ $values { "value" object } { "key" object } { "vocab" "a vocabulary specifier" } }
{ $description "Modifies an entry in a vocabulary's deployment configuration on disk." } ;

HELP: deploy*
{ $values { "vm" "a pathname string" } { "image" "a pathname string" } { "vocab" "a vocabulary specifier" } { "config" assoc } }
{ $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" } "." }
{ $notes "This is a low-level word and in most cases " { $link deploy } " should be called instead." } ;

HELP: deploy
{ $values { "vocab" "a vocabulary specifier" } }
{ $description "Deploys " { $snippet "vocab" } ", saving the deployed image as " { $snippet { $emphasis "vocab" } ".image" } "." } ;