NAME

       falpack - The falcon application packaging tool

SYNOPSIS

       falpak [options] main_script

DESCRIPTION

       The  falpack  command  line  tool  is meant to copy all the modules and other dependencies
       needed for a standalone falcon application to run into a  target  directory.  Falpack  can
       copy  also  the  system  files needed to run the application, making the final application
       totally stand-alone, or just store the needed modules so that a local falcon  installation
       can be used to run the application.

       falpack  searches  for  special  attributes  in the parsed modules to store resources data
       files that an  application  may  require.   It  copies  also  needed  internationalization
       translation  tables, and eventually compiles sources into binary .fam modules. It can also
       remove sources from the final installation, so that pre-compiled applications only can  be
       shipped.  Finally,  it  creates  a  script  that can be used to run the application with a
       "single click" operation on the host platform.

       System relevant modules (as i.e. feathers  or  system-wide  installed  modules)  are  also
       stored together with the application.

       Anyhow, installation of falcon system files (which include feather modules) is optional.

       System  files are copied into a fake root subdirectory (normally called _system ). All the
       modules not lying under the same directory of the application "main script" or  in  deeper
       trees,  are  considered "system-wide" installed, and it is supposed that the script access
       them via -L option or via FALCON_LOAD_PATH environment variable. They are then  stored  in
       the system directory and a directory tree is re-created so that the simple addition of the
       fake root to the load path (i.e. "falcon -L _system") is enough to access all of them.

       This method allows the application to access modules by logical name and by  filename,  as
       the  filename  is  made  relative to the load path.  However, modules loaded with absolute
       filenames must be separately installed on the target system so that their position matches
       the required absolute path.

OPTIONS

       -b <module>
              Blacklists  this  module  (by  module  name).  Using  this option it is possible to
              prevent default action on the given module (copy into the application tree  or  the
              fake  root tree). It is possible to specify more blacklisted modules repeating this
              option.

       --bin <dir>
              Specify directory where falcon binary resides. Useful if  falpack  is  required  to
              read an interpreter from a non-default installation, or if it can't find it.  NOTE:
              falpack  uses  falcon  build  environment  settings.  If  used  under   the   build
              environment,  it  will  copy  files from the active build tree ignoring system wide
              installations.

       -e <enc>
              Source files encoding. In case the source file text encoding is different from  the
              system default encoding, the module loader may detect syntax errors or fail to load
              the sources; also, if .fam generation is required, the strings in the  pre-compiled
              modules.

       -h     Usage help. A short in-line summary of options.

       --lib <dir>
              Specify  directory  where  falcon  engine  dynamic  link library resides. Useful if
              falpack is required to read an interpreter from a non-default installation,  or  if
              it  can't  find  it.  NOTE: falpack uses falcon build environment settings. If used
              under the build environment, it will copy files from the active build tree ignoring
              system wide installations.

       -L <dir>
              Redefine  FALCON_LOAD_PATH. In case the main module needs a special load path which
              is not the system default or the one stored  in  the  FALCON_LOAD_PATH  environment
              variable.  Notice  that  this  setting  overwrites  system and environment variable
              settings.  Also, notice that this load path  is  intended  for  local  loading  and
              compiling  of the modules in the application; the modules are then arranged so that
              this setting is not needed in the final application.

       -M     Pack also pre-compiled modules. If given, this option will cause .fam modules to be
              stored  beside  their  source  files (.fal or .ftd). It is incompatible with the -s
              option.

       -P <dir>
              Save the package in this  directory.  By  default,  the  package  is  stored  in  a
              directory with the same name of the main module (its extension stripped), under the
              current work directory.  This option overrides the default and allows one to  store
              the package at an arbitrary location.

       -r <name>
              Install <name> instead of "falcon" as interpreter. Useful in case only pre-compiled
              modules are packaged, where falrun may be employed, or in case of  special  system-
              specific   interpreter  build,  as  with  sdl_falcon  MacOSX  framework  compatible
              interpreter.

       -R <dir>
              Change fake root for system data into <dir>. If the default  name  for  storage  of
              system  specific apparels (as binary modules, falcon engine library etc.), which is
              "_system", is not satisfactory, it can be overridden through this option.

       -s     Strip sources. Using this option,  source  falcon  files  are  not  copied  in  the
              package; only the pre-compiled bytecode .fam modules are stored.

       -S     Do not store system files. Prevent copying of the falcon interpreter, falcon engine
              dynamic library and feather modules.

       -v     Prints version and exit.

       -V     Verbose mode. Prints verbose messages of what falpack is doing.

SPECIAL ATTRIBUTES

       falpack automatically  packages  needed  ancillary  files  required  by  modules,  as  the
       translation  table  files  (.ftr).  However,  the  modules  may  specify other files to be
       included through a set of special attributes which are interpreted by falpack as it  loads
       and analyzes them.

       resources
              This attribute can indicate a list of resources that should be copied together with
              the module.  The attribute needs to be a string, and  different  resources  can  be
              separated through a semi comma (;). It is possible also to specify file masks using
              the "*.ext" pattern; whole subdirectories can be stored using the "dir/*"  pattern.
              Please,  notice  that  this  attribute  doesn't  work  recursively; to include sub-
              directories in resource directories, specify all of them. For example:

                  resources: "images/*; images/icons/*"

       plugins
              Similar to the resources attribute, the plugins attribute indicates a single module
              or  a  directory  containing  more  modules that may be used by the applications as
              dynamic plugins. Differently from the data considered in the  resources  attribute,
              the  files  indicated  in the plugins attribute are loaded by the loader, and their
              dependencies, if any, are  further  resolved  and  become  part  of  the  installed
              application. Also, they are treated as any other module in any respect; for example
              associated translation files are copied, and in case falpack is required  to  strip
              sources, only the pre-compiled fam modules will be saved.

              It  is possible to store all the modules found in a certain directory using the "*"
              wildcard.

              Similarly  to  the  resources  attribute,  the  plugin  attribute  doesn't  descend
              recursively  in sub-directories; to include other modules laying below the required
              directory, that subdirectory must be explicitly specified, as in this example:

                  plugins: "output/*; output/helpers/*"

       dynlib
              This attribute stores one or more system dynamic  library  needed  for  the  falcon
              module to run. Depending on the host system, the target location may be in the fake
              root directory or besides the module (depending on how  the  system  module  loader
              tries  to  find  the modules). More dependencies may be separated with a semi comma
              (;).

BUGS

       Relative paths are not jailed; if the resource attribute or the relative path of a  loaded
       module  indicates  a position above the main script directory or above any position in the
       FALCON_LOAD_PATH specification, the  files  may  be  copied  outside  the  target  package
       location.  Be  careful  when  writing  the application you want to package so that all the
       needed files can be reached at the same level or below the main script,  or  at  the  same
       level or below directories in the load path.

       At  the  moment,  it's quite complex to create cross platform packages (except for script-
       only applications which use local falcon installation to run). It is  planned  to  provide
       this  support  in  future  via the ability to download pre-compiled modules from a central
       repository.

       In this version, dynlib attribute is not working for  MacOSX  style  framework  libraries.
       However, it will work for MacOSX dylib that can be found via the ldd command.

AUTHOR

       Giancarlo Niccolai <gc@falconpl.org>

SEE ALSO

       falcon(1) falrun(1)

LICENSE

       This  document  is  released  under the "GNU Free Documentation License, version 1.2".  On
       Debian systems, the complete text of the Free Documentation License, version 1.2,  can  be
       found in /usr/share/common-licenses/.