1falpack(1) Falcon User Manuals falpack(1)
2
6 falpack - The falcon application packaging tool
7
10 falpak [options] main_script
11
14 The falpack command line tool is meant to copy all the modules and
15 other dependencies needed for a standalone falcon application to run
16 into a target directory. Falpack can copy also the system files needed
17 to run the application, making the final application totally stand-
18 alone, or just store the needed modules so that a local falcon instal‐
19 lation can be used to run the application.
20 falpack searches for special attributes in the parsed modules to store
22 resources data files that an application may require. It copies also
23 needed internationalization translation tables, and eventually compiles
24 sources into binary .fam modules. It can also remove sources from the
25 final installation, so that pre-compiled applications only can be
26 shipped. Finally, it creates a script that can be used to run the
27 application with a "single click" operation on the host platform.
28 System relevant modules (as i.e. feathers or system-wide installed mod‐
30 ules) are also stored together with the application.
31 Anyhow, installation of falcon system files (which include feather mod‐
33 ules) is optional.
34 System files are copied into a fake root subdirectory (normally called
36 _system ). All the modules not lying under the same directory of the
37 application "main script" or in deeper trees, are considered "system-
38 wide" installed, and it is supposed that the script access them via -L
39 option or via FALCON_LOAD_PATH environment variable. They are then
40 stored in the system directory and a directory tree is re-created so
41 that the simple addition of the fake root to the load path (i.e. "fal‐
42 con -L _system") is enough to access all of them.
43 This method allows the application to access modules by logical name
45 and by filename, as the filename is made relative to the load path.
46 However, modules loaded with absolute filenames must be separately
47 installed on the target system so that their position matches the
48 required absolute path.
49
52 -b <module>
53 Blacklists this module (by module name). Using this option it is
54 possible to prevent default action on the given module (copy
55 into the application tree or the fake root tree). It is possible
56 to specify more blacklisted modules repeating this option.
57 --bin <dir>
60 Specify directory where falcon binary resides. Useful if falpack
61 is required to read an interpreter from a non-default installa‐
62 tion, or if it can't find it. NOTE: falpack uses falcon build
63 environment settings. If used under the build environment, it
64 will copy files from the active build tree ignoring system wide
65 installations.
66 -e <enc>
69 Source files encoding. In case the source file text encoding is
70 different from the system default encoding, the module loader
71 may detect syntax errors or fail to load the sources; also, if
72 .fam generation is required, the strings in the pre-compiled
73 modules.
74 -h Usage help. A short in-line summary of options.
77 --lib <dir>
80 Specify directory where falcon engine dynamic link library
81 resides. Useful if falpack is required to read an interpreter
82 from a non-default installation, or if it can't find it. NOTE:
83 falpack uses falcon build environment settings. If used under
84 the build environment, it will copy files from the active build
85 tree ignoring system wide installations.
86 -L <dir>
89 Redefine FALCON_LOAD_PATH. In case the main module needs a spe‐
90 cial load path which is not the system default or the one stored
91 in the FALCON_LOAD_PATH environment variable. Notice that this
92 setting overwrites system and environment variable settings.
93 Also, notice that this load path is intended for local loading
94 and compiling of the modules in the application; the modules are
95 then arranged so that this setting is not needed in the final
96 application.
97 -M Pack also pre-compiled modules. If given, this option will cause
100 .fam modules to be stored beside their source files (.fal or
101 .ftd). It is incompatible with the -s option.
102 -P <dir>
106 Save the package in this directory. By default, the package is
107 stored in a directory with the same name of the main module (its
108 extension stripped), under the current work directory. This
109 option overrides the default and allows to store the package at
110 an arbitrary location.
111 -r <name>
114 Install <name> instead of "falcon" as interpreter. Useful in
115 case only pre-compiled modules are packaged, where falrun may be
116 employed, or in case of special system-specific interpreter
117 build, as with sdl_falcon MacOSX framework compatible inter‐
118 preter.
119 -R <dir>
123 Change fake root for system data into <dir>. If the default name
124 for storage of system specific apparels (as binary modules, fal‐
125 con engine library etc.), which is "_system", is not satisfac‐
126 tory, it can be overridden through this option.
127 -s Strip sources. Using this option, source falcon files are not
130 copied in the package; only the pre-compiled bytecode .fam mod‐
131 ules are stored.
132 -S Do not store system files. Prevent copying of the falcon inter‐
135 preter, falcon engine dynamic library and feather modules.
136 -v Prints version and exit.
139 -V Verbose mode. Prints verbose messages of what falpack is doing.
142
145 falpack automatically packages needed ancillary files required by mod‐
146 ules, as the translation table files (.ftr). However, the modules may
147 specify other files to be included through a set of special attributes
148 which are interpreted by falpack as it loads and analyzes them.
149 resources
152 This attribute can indicate a list of resources that should be
153 copied together with the module. The attribute needs to be a
154 string, and different resources can be separated through a semi
155 comma (;). It is possible also to specify file masks using the
156 "*.ext" pattern; whole subdirectories can be stored using the
157 "dir/*" pattern. Please, notice that this attribute doesn't work
158 recursively; to include sub-directories in resource directories,
159 specify all of them. For example:
160 resources: "images/*; images/icons/*"
162 plugins
165 Similar to the resources attribute, the plugins attribute indi‐
166 cates a single module or a directory containing more modules
167 that may be used by the applications as dynamic plugins. Differ‐
168 ently from the data considered in the resources attribute, the
169 files indicated in the plugins attribute are loaded by the
170 loader, and their dependencies, if any, are further resolved and
171 become part of the installed application. Also, they are treated
172 as any other module in any respect; for example associated
173 translation files are copied, and in case falpack is required to
174 strip sources, only the pre-compiled fam modules will be saved.
175 It is possible to store all the modules found in a certain
177 directory using the "*" wildcard.
178 Similarly to the resources attribute, the plugin attribute
180 doesn't descend recursively in sub-directories; to include other
181 modules laying below the required directory, that subdirectory
182 must be explicitly specified, as in this example:
183 plugins: "output/*; output/helpers/*"
185 dynlib
188 This attribute stores one or more system dynamic library needed
189 for the falcon module to run. Depending on the host system, the
190 target location may be in the fake root directory or besides the
191 module (depending on how the system module loader tries to find
192 the modules). More dependencies may be separated with a semi
193 comma (;).
194
197 Relative paths are not jailed; if the resource attribute or the rela‐
198 tive path of a loaded module indicates a position above the main script
199 directory or above any position in the FALCON_LOAD_PATH specification,
200 the files may be copied outside the target package location. Be careful
201 when writing the application you want to package so that all the needed
202 files can be reached at the same level or below the main script, or at
203 the same level or below directories in the load path.
204 At the moment, it's quite complex to create cross platform packages
206 (except for script-only applications which use local falcon installa‐
207 tion to run). It is planned to provide this support in future via the
208 ability to download pre-compiled modules from a central repository.
209 In this version, dynlib attribute is not working for MacOSX style
211 framework libraries. However, it will work for MacOSX dylib that can be
212 found via the ldd command.
213
216 Giancarlo Niccolai <gc@falconpl.org>
217
220 falcon(1) falrun(1)
221
224 This document is released under the "GNU Free Documentation License,
225 version 1.2". On Debian systems, the complete text of the Free Docu‐
226 mentation License, version 1.2, can be found in /usr/share/com‐
227 mon-licenses/.
228Falcon toolset January 2010 falpack(1)