--- Urlader/README 2012/01/04 14:19:05 1.2 +++ Urlader/README 2012/01/08 09:12:52 1.3 @@ -6,17 +6,18 @@ DESCRIPTION Urlader (that's german for "bootloader" btw.) was created out of - frustration over PAR again not working, again not being flexible enough - for simple things, and again causing mysterious missing files issues on - various platforms. + frustration over PAR always being horribly slow, again not working, + again not being flexible enough for simple things such as software + upgrades, and again causing mysterious missing file issues on various + platforms. That doesn't mean this module replaces PAR, in fact, you should stay - with it for many reasons, user-friendlyness is one of them. + with PAR for many reasons right now, user-friendlyness is one of them. However, if you want to make single-file distributions out of your perl programs (or python, or C or whatever), and you are prepared to fiddle a - LOT, this module might provide a tiny step towards your goal. Well, if - it ever gets finished. + LOT, this module might provide a faster and more versatile deployment + technique then PAR. Well, if it ever gets finished. Also, *nothing in this module is considered very stable yet*, and it's far from feature-complete. @@ -25,7 +26,7 @@ A simple archiver that packs a directory tree into a single file. A small C program that works on windows and unix, which unpacks an - attached archive and runs a program. + attached archive and runs a program (perl, python, whatever...). A perl module support module (*this one*), that can be used to query the runtime environment, find out where to install updates and so on. @@ -40,6 +41,12 @@ bintree/run bintree/pm/Guard.pm bintree/pm/auto/Guard/Guard.so + bintree/pm/XSLoader.pm + bintree/pm/DynaLoader.pm + bintree/pm/Config.pm + bintree/pm/strict.pm + bintree/pm/vars.pm + bintree/pm/warnings.pm # cat bintree/run @INC = ("pm", "."); # "." works around buggy AutoLoader @@ -55,6 +62,12 @@ >myprog # chmod 755 myprog + The packing step takes a binary loader and appends all the files in the + directory tree, plus some meta information. + + The resulting file is an executable that, when run, will unpack all the + files and run the embedded program. + CONCEPTS urlader A small (hopefully) and relatively portable (hopefully) binary that @@ -85,8 +98,170 @@ :) and directories. override + When the urlader starts, it first finds out what "exe_id" is + embedded in it. It then looks for an override file for this id + ($URLADER_EXE_DIR/override) and verifies that it is for the same + "exe_id", and the version is newer. If this is the case, then it + will unpack and run the override file instead of unpacking the files + attched to itself. + + This way one can implement software upgrades - download a new + executable, write it safely to disk and move it to the override + path. + +ENVIRONMENT VARIABLES + The urlader sets and maintains the following environment variables, in + addition to any variables specified on the commandline. The values in + parentheses are typical (but not gauranteed) values for unix - on + windows, ~/.urlader is replaced by %AppData%/urlader. + + URLADER_VERSION (1.0) + Set to the version of the urlader binary itself. All versions with + the same major number should be compatible to older versions with + the same major number. + + URLADER_DATADIR (~/.urlader) + The data directory used to store whatever urlader needs to store. + + URLADER_CURRDIR + This is set to the full path of the current working directory where + the urlader was started. Atfer unpacking, the urlader changes to the + "URLADER_EXECDIR", so any relative paths should be resolved via this + path. + + URLADER_EXEPATH + This is set to the path of the urlader executable itself, usually + relative to $URLADER_CURRDIR. + + URLADER_EXE_ID + This stores the executable id of the pack file attached to the + urlader. + + URLADER_EXE_VER + This is the executable version of the pack file attached to the + urlader, or the override, whichever was newer. Or in other words, + this is the version of the application running at the moment. + + URLADER_EXE_DIR (~/.urlader/$URLADER_EXE_ID> + The directory where urlader stores files related to the executable + with the given id. + + URLADER_EXECDIR (~/.urlader/$URLADER_EXE_ID/i-$URLADER_EXE_VER) + The directory where the files from the pack file are unpacked and + the program is being run. Also the working directory of the program + when it is run. + + URLADER_OVERRIDE (empty or override) + The override file used, if any, relative to $URLADER_EXECDIR. This + is either missing, when no override was used, or the string + override, as thta is currently the only override file urlader is + looking for. FUNCTIONS AND VARIABLES IN THIS MODULE + $Urlader::URLADER_VERSION + Set to the urlader version ("URLADER_VERSION") when the program is + running form within urlader, undef otherwise. + + $Urlader::DATADIR, $Urlader::EXE_ID, $Urlader::EXE_VER, + $Urlader::EXE_DIR, $Urlader::EXECDIR + Contain the same value as the environment variable of the (almost) + same name. You should prefer these, though, as these might even be + set to correct values when not running form within an urlader + environment. + + Urlader::set_exe_info $exe_id, $exe_ver + Sets up the paths and variables as if running the given executable + and version from within urlader. + + $lock = Urlader::lock $path, $exclusive, $wait + Tries to acquire a lock on the given path (which must specify a file + which will be created if necessary). If $exclusive is true, then it + tries to acquire an exclusive lock, otherwise the lock will be + shared. If $wait is true, then it will wait until the lock can be + acquired, otherwise it only attempts to acquire it and returns + immediately if it can't. + + If successful it returns a lock object - the lock will be given up + when the lock object is destroyed. + + If the lock could not be acquired, "undef" is returned. + + This function will probably go awway in the future, but is provided + to assist applications that want to clean up old versions, see "TIPS + AND TRICKS", below. + +TIPS AND TRICKS + Gathering files + Gathering all the files needed for distribution cna be a big + problem. Right now, Urlader does not assist you in this task in any + way, however, just like perl source stripping, it is planned to + unbundle the relevant technology from staticperl + () for use with this module. + + You could always use par to find all library files, unpack the + bundle and add perl, libperl and other support libraries (e.g. + libgcc_s). + + Software update + Updating the software can be done by downloading a new packfile + (with the same "exe_id" but a higher "exe_ver" - this can simply be + the executable you create when making a release) and replacing the + override file in the $URLADER_EXE_DIR. + + When looking for updates, you should include $URLADER_VERSION, + $URLADER_EXE_ID and $URLADER_EXE_VER - the first two must be + identical for update and currently running program, while the last + one should be lexicographically higher. + + Replacing the override file can be done like this: + + rename "new-override.tmp", "$Urlader::EXE_DIR/override" + or die "could not replace override"; + + This can fail on windows when another urlader currently reads it, + but should work on all platforms even when other urlader programs + execute concurrently. + + Cleaning up old directories + Urlader only packs executables once and then caches them in the + $URLADER_EXECDIR. After upgrades there will be old versions in there + that are not being used anymore. Or are they? + + Each instance directory (i-*) in the $URLADER_EXE_DIR) has an + associated lock file (i-*.lck) - while urlader executes an app it + keeps a shared lock on this file. + + To detect whether a version is in use or not, you must try to + acquire an exclusive lock, i.e.: + + my $lock = Urlader::lock "~/.urlader/myexe/i-ver01.lck", 1, 0; + if (!$lock) { + # instance dir is not in use and can be safely deleted + } + + If an older urlader wants to use an instance that was deleted or is + currently being deleted it will wait until it's gone and simply + recreate it, so while less efficient, deleting instance directories + should always be safe. + + The lockfile itself can be deleted as long as you have an exclusive + lock on it (if your platform allows this). + + A real world project + The only real world project using this that I know of at the moment + is the deliantra client (http://www.deliantra.net for more info). + + It uses some scary scripts to build the client and some dependnet + modules (build.*), to gather perl source files into a distribution + tree, shared objects and system shared libraries (some of which have + to be patched or, due to the horrible dll hell on OS X, even + renamed), called "gatherer", and a script called "gendist" to build + executable distributions. + + These can be found at + , but + looking at them can lead to premature blindless. + AUTHOR Marc Lehmann http://home.schmorp.de/