NAME
    Urlader - installer-less single-file independent executables

SYNOPSIS
     use Urlader;

DESCRIPTION
    Urlader (that's german for "bootloader" btw.) was created out of
    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 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 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.

    Having said all that, Urlader basically provides three services:

    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 (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.

EXAMPLE
    How can it be used to provide single-file executables?

    So simple, create a directory with everything that's needed, e.g.:

       # find bintree
       bintree/perl
       bintree/libperl.so.5.10
       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
       use Guard;
       guard { warn "hello, world!\n" }; # just to show off
       exit 0; # tell the urlader that everything was fine

    Then pack it:

       # wget http://urlader.schmorp.de/prebuilt/1.0/linux-x86
       # urlader-util --urlader linux-x86 --pack myprog ver1_000 bintree \
                      LD_LIBRARY_PATH=. ./perl run \
                      >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
        is prepended to a pack file to make it executable.

        You can build it yourself from sources (see prebuilt/Makefile in the
        distribution) or use one of the precompiled ones at:

           http://urlader.schmorp.de/prebuilt/1.0/

        The README there has further information on the binaries provided.

    exe_id
        A string that uniquely identifies your program - all branches of it.
        It must consist of the characters "A-Za-z0-9_-" only and should be a
        valid directory name on all systems you want to deploy on.

    exe_ver
        A string the uniquely identifies the contents of the archive, i.e.
        the version. It has the same restrictions as the "exe_id", and
        should be fixed-length, as Urlader assumes lexicographically higher
        versions are newer, and thus preferable.

    pack file (archive)
        This contains the "exe_id", the "exe_ver", a number of environment
        variable assignments, the program name to execute, the initial
        arguments it receives, and finally, a list of files (with contents
        :) 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 or when the process exits (even on
        a crash) and has a good chance of working on network drives as well.

        If the lock could not be acquired, "undef" is returned.

        This function 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 can 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
        (<http://staticperl.plan9.de>) 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
        <http://cvs.schmorp.de/deliantra/Deliantra-Client/util/>, but
        looking at them can lead to premature blindless.

    Shared Libraries
        It is often desirable to package shared libraries - for example the
        Deliantra client packages SD>, Berkely DB, Pango and amny other
        libraries that are unlikely to be available on the target system.

        This usually requires some fiddling (see below), and additionally
        some environment variables to be set.

        For example, on ELF systems you usually want LD_LIBRARY_PATH=. and
        on OS X, you want DYLD_LIBRARY_PATH=. (these are effectively the
        default on windows).

        These can most easily be specified when building the packfile:

           urlader-util ... LD_LIBRARY_PATH=. ./perl run

    Portability: RPATH
        Often perl is linked against a shared libperl.so - and might be so
        using an rpath. Perl extensikns likewise might use an rpath, which
        means the binary will mostly ignore LD_LIBRARY_PATH, which leads to
        trouble.

        There is an utility called chrpath, whose -d option can remove the
        rpath from binaries, shared library and shared objects.

    Portability: OS X DLL HELL
        OS X has the most severe form of DLL hell I have seen - if you link
        against system libraries, which is practically unavoidable, you get
        libraries of well-known names (e.g. libjpeg) that have nothing to do
        with what you normally expect libjpeg to be, and there is no way to
        get your version of libjpeg into your program.

        Moreover, even if apple ships well-known libraries (e.g. libiconv),
        they often ship patched versions which have a different ABI or even
        API then the real releases.

        The only way aorund this I found was to change all library names in
        my releases (libjpeg.dylib becomes libdeliantra-jpeg.dylin and so
        on), by patching the paths in the share dlibraries and shared
        objects. install-name-tool (with -id and -change) works in many
        cases, but often paths are embedded indirectly, so you might have to
        use a *dirty* string replacement.

SECURITY CONSIDERATIONS
    The urlader executable itself does not support setuig/setgid operation,
    or running with elevated privileges - it does no input sanitisation, and
    is trivially exploitable.

AUTHOR
     Marc Lehmann <[email protected]>
     http://home.schmorp.de/