Added more docs

doc/PHAR-APPS.md

@@ -0,0 +1,100 @@
+Phar Applications
+=================
+
+This guide explains how to make single-file executables using MakePhar.
+
+
+## The workflow
+
+1.  Make sure you have a native php loader, in this example `src/stub.php`.
+    If you include a bin, such as `bin/myapp` make sure it wraps the native
+    loader or the shebang (`#!/usr/bin/env php` or similar) will be output
+    during load.
+2.  Set up the `makephar.sdl` file. You can copy and modify the example in
+    this doc, the `makephar.sdl.dist` from the source package, or simply
+    use `makephar -n > makephar.sdl` to have a template generated for you.
+3.  Call on `makephar` to generate the output file.
+
+
+## Example files
+
+### src/stub.php
+
+    <?php
+
+    require_once __DIR__."/../vendor/autoload.php";
+    $app = new MyApp\MyApp();
+    $app->run();
+
+
+### makephar.sdl
+
+    phar "myapp.phar" {
+        stub "src/stub.php";
+        include {
+            dir "src";
+            dir "vendor";
+        }
+        exclude {
+            dir ".git";
+        }
+    }
+
+
+
+## Problems and Solutions
+
+### Getting the directory of the running phar
+
+You can get the path of the command invoked using `$_SERVER['SCRIPT_NAME']`:
+
+    $root = dirname($_SERVER['SCRIPT_NAME']);
+
+Note that the script *can* be a symbolic link, in which case you need to call
+on `readlink` before you call `dirname`:
+
+    // Get the path of the script, eg. /usr/bin/myapp
+    $root = $_SERVER['SCRIPT_NAME'];
+    // Unwrap the links, eg. /usr/bin/myapp -> ~/myapp/myapp.phar
+    while (readlink($root)) {
+        $root = readlink($root);
+    }
+    // Finally get the directory (~/myapp)
+    $root = dirname($root);
+
+Use this to locate your plugins.
+
+### Find out if running from within a Phar
+
+You can easilly find out if running from within a .phar archive by calling
+`Phar::running()`. 
+
+    if (Phar::running()) { inside_phar(); }
+
+This doesn't make sense to use in phar plugins, as the main application can
+also be in a phar, in which case it will be true even for non-phar plugins.
+
+### Including the Git revision etc
+
+Use the `props` for this. If you have an executable file, say `build/genprops`
+that look like this...
+
+    #!/bin/bash
+    printf "GIT_REVISION=%s" "$(git describe --tags)"
+
+...then you can define it in your `makephar.sdl` to be evaluated when the
+phar is being built:
+
+    phar "output.phar" {
+        ...
+        stub exec="build/genprops";
+        ...
+    }
+
+When running from within the built phar, the define `GIT_REVISION` will be
+available:
+
+    if (defined('GIT_REVISION')) {
+        echo "Git Revision: ".GIT_REVISION."\n";
+    }
+