table of contents
falpack(1) | Falcon User Manuals | falpack(1) |
NAME¶
falpack - The falcon application packaging toolSYNOPSIS¶
falpak [options] main_scriptDESCRIPTION¶
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.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/*"
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/*"
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.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/.January 2010 | Falcon toolset |