Comments, readme, bugfixes

2017-01-10 13:50:11 +01:00
parent dd2bb032dd
commit 156bb62367
3 changed files with 101 additions and 4 deletions
@@ -0,0 +1,69 @@
+MakePhar mk2
+============
+
+This is a rewrite of my old MakePhar utility, with cleaner code and added
+portability. Besides being able to pack executables, this version can also
+create libraries, such as portable plugins.
+
+
+## Executables
+
+If your project is using composer, and your main stub is located in the
+source directory as specified in the composer.json, you can create a
+manifest easily:
+
+    $ makephar -n > makephar.sdl
+
+Now, just update `makephar.sdl` to make sure the **stub** points to the
+executable stub. Here is an example:
+
+    phar "my-project.phar" {
+      include {
+        dir "src";
+        dir "vendor";
+      }
+      stub "src/boot.php";
+    }
+
+To build this into a .phar archive, just call `makephar`:
+
+    $ makephar
+
+The output file `my-project.phar` should be created and be executable out of
+the box.
+
+
+## Libraries
+
+Libraries work like executables, with the difference that they **require** a
+composer project, or rather it requires a file named `vendor/autoload.php` in
+the package.
+
+To load your own bootstrap using composer, add them as file autoloaders:
+
+    ...
+    "autoload": {
+      "psr-4": ...
+      "files": [ "src/my-library-stub.php" ]
+    }
+
+Next, make sure you have a line in your `makephar.sdl` that reads:
+
+    library true;
+
+You should now be able to create a library phar by invoking `makephar`.
+
+It is recommended that you add a check in your main stub to make sure that
+the plugin or library has what is needed, such as checking a define or making
+sure that a method or class already exists.
+
+
+## Pro Tips
+
+* You can have multiple `phar` blocks in your `makephar.conf`. This lets
+  you build a main executable, libraries etc in one go. You currently can't
+  pick the rule to build tho, but rather all defined phars will be built.
+* MakePhar will minify your files using `php_strip_whitespace()` before adding
+  them to the archive. This shouldn't be an issue, but if your code depends on
+  a specific character index in a specific php file, you might want to use
+  another tool for the time being.