1falpack(1)                    Falcon User Manuals                   falpack(1)
2
3
4

NAME

6       falpack - The falcon application packaging tool
7
8

SYNOPSIS

10       falpak [options] main_script
11
12

DESCRIPTION

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
21       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
29       System relevant modules (as i.e. feathers or system-wide installed mod‐
30       ules) are also stored together with the application.
31
32       Anyhow, installation of falcon system files (which include feather mod‐
33       ules) is optional.
34
35       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
44       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
50

OPTIONS

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
58
59       --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
67
68       -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
75
76       -h     Usage help. A short in-line summary of options.
77
78
79       --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
87
88       -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
98
99       -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
103
104
105       -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
112
113       -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
120
121
122       -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
128
129       -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
133
134       -S     Do not store system files. Prevent copying of the falcon  inter‐
135              preter, falcon engine dynamic library and feather modules.
136
137
138       -v     Prints version and exit.
139
140
141       -V     Verbose mode. Prints verbose messages of what falpack is doing.
142
143

SPECIAL ATTRIBUTES

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
150
151       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
161                  resources: "images/*; images/icons/*"
162
163
164       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
176              It is possible to store all  the  modules  found  in  a  certain
177              directory using the "*" wildcard.
178
179              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
184                  plugins: "output/*; output/helpers/*"
185
186
187       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
195

BUGS

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
205       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
210       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
214

AUTHOR

216       Giancarlo Niccolai <gc@falconpl.org>
217
218

SEE ALSO

220       falcon(1) falrun(1)
221
222

LICENSE

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/.
228
229
230
231
232Falcon toolset                   January 2010                       falpack(1)
Impressum