ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Urlader/README
(Generate patch)

Comparing Urlader/README (file contents):
Revision 1.2 by root, Wed Jan 4 14:19:05 2012 UTC vs.
Revision 1.3 by root, Sun Jan 8 09:12:52 2012 UTC

… …
4SYNOPSIS 4SYNOPSIS
5 use Urlader; 5 use Urlader;
6 6
7DESCRIPTION 7DESCRIPTION
8 Urlader (that's german for "bootloader" btw.) was created out of 8 Urlader (that's german for "bootloader" btw.) was created out of
9 frustration over PAR again not working, again not being flexible enough 9 frustration over PAR always being horribly slow, again not working,
10 again not being flexible enough for simple things such as software
10 for simple things, and again causing mysterious missing files issues on 11 upgrades, and again causing mysterious missing file issues on various
11 various platforms. 12 platforms.
12 13
13 That doesn't mean this module replaces PAR, in fact, you should stay 14 That doesn't mean this module replaces PAR, in fact, you should stay
14 with it for many reasons, user-friendlyness is one of them. 15 with PAR for many reasons right now, user-friendlyness is one of them.
15 16
16 However, if you want to make single-file distributions out of your perl 17 However, if you want to make single-file distributions out of your perl
17 programs (or python, or C or whatever), and you are prepared to fiddle a 18 programs (or python, or C or whatever), and you are prepared to fiddle a
18 LOT, this module might provide a tiny step towards your goal. Well, if 19 LOT, this module might provide a faster and more versatile deployment
19 it ever gets finished. 20 technique then PAR. Well, if it ever gets finished.
20 21
21 Also, *nothing in this module is considered very stable yet*, and it's 22 Also, *nothing in this module is considered very stable yet*, and it's
22 far from feature-complete. 23 far from feature-complete.
23 24
24 Having said all that, Urlader basically provides three services: 25 Having said all that, Urlader basically provides three services:
25 26
26 A simple archiver that packs a directory tree into a single file. 27 A simple archiver that packs a directory tree into a single file.
27 A small C program that works on windows and unix, which unpacks an 28 A small C program that works on windows and unix, which unpacks an
28 attached archive and runs a program. 29 attached archive and runs a program (perl, python, whatever...).
29 A perl module support module (*this one*), that can be used to query the 30 A perl module support module (*this one*), that can be used to query the
30 runtime environment, find out where to install updates and so on. 31 runtime environment, find out where to install updates and so on.
31 32
32EXAMPLE 33EXAMPLE
33 How can it be used to provide single-file executables? 34 How can it be used to provide single-file executables?
… …
38 bintree/perl 39 bintree/perl
39 bintree/libperl.so.5.10 40 bintree/libperl.so.5.10
40 bintree/run 41 bintree/run
41 bintree/pm/Guard.pm 42 bintree/pm/Guard.pm
42 bintree/pm/auto/Guard/Guard.so 43 bintree/pm/auto/Guard/Guard.so
44 bintree/pm/XSLoader.pm
45 bintree/pm/DynaLoader.pm
46 bintree/pm/Config.pm
47 bintree/pm/strict.pm
48 bintree/pm/vars.pm
49 bintree/pm/warnings.pm
43 50
44 # cat bintree/run 51 # cat bintree/run
45 @INC = ("pm", "."); # "." works around buggy AutoLoader 52 @INC = ("pm", "."); # "." works around buggy AutoLoader
46 use Guard; 53 use Guard;
47 guard { warn "hello, world!\n" }; # just to show off 54 guard { warn "hello, world!\n" }; # just to show off
… …
53 # urlader-util --urlader linux-x86 --pack myprog ver1_000 bintree \ 60 # urlader-util --urlader linux-x86 --pack myprog ver1_000 bintree \
54 LD_LIBRARY_PATH=. ./perl run \ 61 LD_LIBRARY_PATH=. ./perl run \
55 >myprog 62 >myprog
56 # chmod 755 myprog 63 # chmod 755 myprog
57 64
65 The packing step takes a binary loader and appends all the files in the
66 directory tree, plus some meta information.
67
68 The resulting file is an executable that, when run, will unpack all the
69 files and run the embedded program.
70
58CONCEPTS 71CONCEPTS
59 urlader 72 urlader
60 A small (hopefully) and relatively portable (hopefully) binary that 73 A small (hopefully) and relatively portable (hopefully) binary that
61 is prepended to a pack file to make it executable. 74 is prepended to a pack file to make it executable.
62 75
… …
83 variable assignments, the program name to execute, the initial 96 variable assignments, the program name to execute, the initial
84 arguments it receives, and finally, a list of files (with contents 97 arguments it receives, and finally, a list of files (with contents
85 :) and directories. 98 :) and directories.
86 99
87 override 100 override
101 When the urlader starts, it first finds out what "exe_id" is
102 embedded in it. It then looks for an override file for this id
103 ($URLADER_EXE_DIR/override) and verifies that it is for the same
104 "exe_id", and the version is newer. If this is the case, then it
105 will unpack and run the override file instead of unpacking the files
106 attched to itself.
107
108 This way one can implement software upgrades - download a new
109 executable, write it safely to disk and move it to the override
110 path.
111
112ENVIRONMENT VARIABLES
113 The urlader sets and maintains the following environment variables, in
114 addition to any variables specified on the commandline. The values in
115 parentheses are typical (but not gauranteed) values for unix - on
116 windows, ~/.urlader is replaced by %AppData%/urlader.
117
118 URLADER_VERSION (1.0)
119 Set to the version of the urlader binary itself. All versions with
120 the same major number should be compatible to older versions with
121 the same major number.
122
123 URLADER_DATADIR (~/.urlader)
124 The data directory used to store whatever urlader needs to store.
125
126 URLADER_CURRDIR
127 This is set to the full path of the current working directory where
128 the urlader was started. Atfer unpacking, the urlader changes to the
129 "URLADER_EXECDIR", so any relative paths should be resolved via this
130 path.
131
132 URLADER_EXEPATH
133 This is set to the path of the urlader executable itself, usually
134 relative to $URLADER_CURRDIR.
135
136 URLADER_EXE_ID
137 This stores the executable id of the pack file attached to the
138 urlader.
139
140 URLADER_EXE_VER
141 This is the executable version of the pack file attached to the
142 urlader, or the override, whichever was newer. Or in other words,
143 this is the version of the application running at the moment.
144
145 URLADER_EXE_DIR (~/.urlader/$URLADER_EXE_ID>
146 The directory where urlader stores files related to the executable
147 with the given id.
148
149 URLADER_EXECDIR (~/.urlader/$URLADER_EXE_ID/i-$URLADER_EXE_VER)
150 The directory where the files from the pack file are unpacked and
151 the program is being run. Also the working directory of the program
152 when it is run.
153
154 URLADER_OVERRIDE (empty or override)
155 The override file used, if any, relative to $URLADER_EXECDIR. This
156 is either missing, when no override was used, or the string
157 override, as thta is currently the only override file urlader is
158 looking for.
88 159
89FUNCTIONS AND VARIABLES IN THIS MODULE 160FUNCTIONS AND VARIABLES IN THIS MODULE
161 $Urlader::URLADER_VERSION
162 Set to the urlader version ("URLADER_VERSION") when the program is
163 running form within urlader, undef otherwise.
164
165 $Urlader::DATADIR, $Urlader::EXE_ID, $Urlader::EXE_VER,
166 $Urlader::EXE_DIR, $Urlader::EXECDIR
167 Contain the same value as the environment variable of the (almost)
168 same name. You should prefer these, though, as these might even be
169 set to correct values when not running form within an urlader
170 environment.
171
172 Urlader::set_exe_info $exe_id, $exe_ver
173 Sets up the paths and variables as if running the given executable
174 and version from within urlader.
175
176 $lock = Urlader::lock $path, $exclusive, $wait
177 Tries to acquire a lock on the given path (which must specify a file
178 which will be created if necessary). If $exclusive is true, then it
179 tries to acquire an exclusive lock, otherwise the lock will be
180 shared. If $wait is true, then it will wait until the lock can be
181 acquired, otherwise it only attempts to acquire it and returns
182 immediately if it can't.
183
184 If successful it returns a lock object - the lock will be given up
185 when the lock object is destroyed.
186
187 If the lock could not be acquired, "undef" is returned.
188
189 This function will probably go awway in the future, but is provided
190 to assist applications that want to clean up old versions, see "TIPS
191 AND TRICKS", below.
192
193TIPS AND TRICKS
194 Gathering files
195 Gathering all the files needed for distribution cna be a big
196 problem. Right now, Urlader does not assist you in this task in any
197 way, however, just like perl source stripping, it is planned to
198 unbundle the relevant technology from staticperl
199 (<http://staticperl.plan9.de>) for use with this module.
200
201 You could always use par to find all library files, unpack the
202 bundle and add perl, libperl and other support libraries (e.g.
203 libgcc_s).
204
205 Software update
206 Updating the software can be done by downloading a new packfile
207 (with the same "exe_id" but a higher "exe_ver" - this can simply be
208 the executable you create when making a release) and replacing the
209 override file in the $URLADER_EXE_DIR.
210
211 When looking for updates, you should include $URLADER_VERSION,
212 $URLADER_EXE_ID and $URLADER_EXE_VER - the first two must be
213 identical for update and currently running program, while the last
214 one should be lexicographically higher.
215
216 Replacing the override file can be done like this:
217
218 rename "new-override.tmp", "$Urlader::EXE_DIR/override"
219 or die "could not replace override";
220
221 This can fail on windows when another urlader currently reads it,
222 but should work on all platforms even when other urlader programs
223 execute concurrently.
224
225 Cleaning up old directories
226 Urlader only packs executables once and then caches them in the
227 $URLADER_EXECDIR. After upgrades there will be old versions in there
228 that are not being used anymore. Or are they?
229
230 Each instance directory (i-*) in the $URLADER_EXE_DIR) has an
231 associated lock file (i-*.lck) - while urlader executes an app it
232 keeps a shared lock on this file.
233
234 To detect whether a version is in use or not, you must try to
235 acquire an exclusive lock, i.e.:
236
237 my $lock = Urlader::lock "~/.urlader/myexe/i-ver01.lck", 1, 0;
238 if (!$lock) {
239 # instance dir is not in use and can be safely deleted
240 }
241
242 If an older urlader wants to use an instance that was deleted or is
243 currently being deleted it will wait until it's gone and simply
244 recreate it, so while less efficient, deleting instance directories
245 should always be safe.
246
247 The lockfile itself can be deleted as long as you have an exclusive
248 lock on it (if your platform allows this).
249
250 A real world project
251 The only real world project using this that I know of at the moment
252 is the deliantra client (http://www.deliantra.net for more info).
253
254 It uses some scary scripts to build the client and some dependnet
255 modules (build.*), to gather perl source files into a distribution
256 tree, shared objects and system shared libraries (some of which have
257 to be patched or, due to the horrible dll hell on OS X, even
258 renamed), called "gatherer", and a script called "gendist" to build
259 executable distributions.
260
261 These can be found at
262 <http://cvs.schmorp.de/deliantra/Deliantra-Client/util/>, but
263 looking at them can lead to premature blindless.
264
90AUTHOR 265AUTHOR
91 Marc Lehmann <schmorp@schmorp.de> 266 Marc Lehmann <schmorp@schmorp.de>
92 http://home.schmorp.de/ 267 http://home.schmorp.de/
93 268

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines