git.m6w6.name Git - pharext/pharext/blob - README.md

   1 # pharext
   2
   3 Distribute your PHP extension as self-installable phar executable
   4
   5 ## About
   6
   7 ### Disclaimer
   8
   9 You don't need this package to install any `*.ext.phar` extension packages,
  10 just run them with php:
  11
  12         $ ./pecl_http-2.4.0dev.ext.phar
  13
  14 For a compressed phar, or if the execute permission bit got lost somehow:
  15
  16         $ php pecl_http-2.4.0dev.ext.phar.gz
  17
  18 Command help:
  19
  20         $ ./pecl_http-2.4.0dev.ext.phar -h
  21
  22 Yields:
  23
  24         pharext v1.1.0 (c) Michael Wallner <mike@php.net>
  25
  26         Usage:
  27
  28           $ ./pecl_http-2.4.0dev.ext.phar [-hvqs] [-p|-n|-c <arg>]
  29
  30             -h|--help                                  Display help
  31             -v|--verbose                               More output
  32             -q|--quiet                                 Less output
  33             -p|--prefix <arg>                          PHP installation prefix if phpize is not in $PATH, e.g. /opt/php7
  34             -n|--common-name <arg>                     PHP common program name, e.g. php5 or zts-php [php]
  35             -c|--configure <arg>                       Additional extension configure flags, e.g. -c --with-flag
  36             -s|--sudo [<arg>]                          Installation might need increased privileges [sudo -S %s]
  37             --with-http-zlib-dir [<arg>]               Where to find zlib [/usr]
  38             --with-http-libcurl-dir [<arg>]            Where to find libcurl [/usr]
  39             --with-http-libevent-dir [<arg>]           Where to find libevent [/usr]
  40
  41
  42 If your installation destination needs escalated permissions, have a look at the `--sudo` option:
  43
  44         $ ./pecl_http-2.4.0dev.ext.phar --sudo
  45         Installing pecl_http-2.4.0dev.ext.phar ...
  46         Running phpize ... OK
  47         Running configure ... OK
  48         Running make ... OK
  49         Running install ...
  50         Password:OK
  51         Cleaning up /tmp/pecl_http-2.4.0dev.ext.phar.54fa02e3316f7 ...
  52         Don't forget to activiate the extension in your php.ini!
  53
  54
  55 ### Prerequisites
  56
  57 The usual tools you need to build a PHP extension:
  58 * php, phpize and php-config
  59 * make, cc and autotools
  60
  61 A network connection is not needed.
  62
  63 ## Download for extension maintainers
  64
  65 Download the pharext binary of the [latest release](https://github.com/m6w6/pharext/releases/latest).
  66
  67 ## Installation for extension maintainers
  68
  69         $ composer require --dev m6w6/pharext
  70
  71 ### Prerequisites:
  72
  73 * make
  74 * php + phar
  75
  76 ## Usage
  77
  78
  79 Command help:
  80
  81         $ ./vendor/bin/pharext --help
  82
  83 Yields:
  84
  85         pharext v1.1.0 (c) Michael Wallner <mike@php.net>
  86
  87         Usage:
  88
  89           $ ./bin/pharext [-hvqgpzZ] -n <arg> -r <arg> -s <arg> [-d <arg>]
  90
  91             -h|--help                    Display this help
  92             -v|--verbose                 More output
  93             -q|--quiet                   Less output
  94             -n|--name <arg>              Extension name (REQUIRED)
  95             -r|--release <arg>           Extension release version (REQUIRED)
  96             -s|--source <arg>            Extension source directory (REQUIRED)
  97             -g|--git                     Use `git ls-files` instead of the standard ignore filter
  98             -p|--pecl                    Use PECL package.xml instead of the standard ignore filter
  99             -d|--dest <arg>              Destination directory [.]
 100             -z|--gzip                    Create additional PHAR compressed with gzip
 101             -Z|--bzip                    Create additional PHAR compressed with bzip
 102
 103 ### PECL source dirs
 104
 105 PECL source dirs can infer package name, release version and file list
 106 from the package.xml.
 107
 108         $ ./vendor/bin/pharext --pecl --source ../pecl_http.git
 109
 110 Yields:
 111
 112         Creating phar /tmp/54fa028adce40.phar ... OK
 113         Finalizing ./pecl_http-2.4.0dev.ext.phar ... OK
 114
 115 ### GIT source dirs
 116
 117 Another example using --git (`git ls-files`):
 118
 119         $ ./vendor/bin/pharext -v -g -s ../raphf.git --name raphf --release 1.0.5
 120
 121 Yields:
 122
 123         Creating phar /tmp/54fa0455a9aee.phar ...
 124         Packaging .gitignore
 125         Packaging CREDITS
 126         Packaging Doxyfile
 127         Packaging LICENSE
 128         Packaging TODO
 129         Packaging config.m4
 130         Packaging config.w32
 131         Packaging package.xml
 132         Packaging php_raphf.c
 133         Packaging php_raphf.h
 134         Packaging raphf.png
 135         Packaging tests/http001.phpt
 136         Packaging tests/http002.phpt
 137         Packaging tests/http003.phpt
 138         Packaging tests/http004.phpt
 139         Created executable phar /tmp/54fa0455a9aee.phar
 140         Finalizing ./raphf-1.0.5.ext.phar ... OK
 141
 142 ### Packager and installer hooks
 143
 144 #### Packager hook
 145 If neither --pecl nor --git are explicitely given, pharext looks for a
 146 `pharext_install.php` in --source. This script will be exectuted by the
 147 Packager. It must return a callable with the following signature:
 148
 149         function(Packager $pkg, $path) : function(Packager $pkg, $path);
 150
 151 So, the callback should return another callable.
 152 The primary callback is meant to set things like --name and --release,
 153 so you don't have to on the command line; build automation FTW.
 154 The secondary callback is meant to create the file iterator of the
 155 source dir, but if you're in a git clone, you might easily just return a
 156 new pharext\GitSourceDir and be done.
 157
 158 ##### Example for pecl_http
 159
 160 pharext_package.php
 161
 162         <?php
 163
 164         namespace pharext;
 165
 166         return function(Packager $packager, $path) {
 167                 $args = $packager->getArgs();
 168                 $args->name = "pecl_http";
 169                 $args->release = current(preg_filter("/^.*PHP_PECL_HTTP_VERSION\s+\"(.*)\".*$/s", "\$1", file("../http.git/php_http.h")));
 170                 return function (Packager $packager, $path) {
 171                         return new GitSourceDir($packager, $path);
 172                 };
 173         };
 174
 175 #### Installer hook
 176 The packager will look for a `pharext_install.php` file within the root of
 177 the source dir. This script will be executed by the Installer; it must
 178 return a callable with the following signature:
 179
 180         function(Installer $installer) : function(Installer $installer);
 181
 182 So, again, the callback should return another callable.
 183 The primary callback is meant to add your own command line arguments to
 184 the CliArgs parser, and the secnodary callback is meant to proccess
 185 those args.
 186
 187 ##### Example for pecl_http
 188
 189 pharext_install.php
 190
 191         <?php
 192
 193         namespace pharext;
 194
 195         return function(Installer $installer) {
 196                 $installer->getArgs()->compile([
 197                         [null, "with-http-zlib-dir", "Where to find zlib",
 198                                 CliArgs::OPTARG],
 199                         [null, "with-http-libcurl-dir", "Where to find libcurl",
 200                                 CliArgs::OPTARG],
 201                         [null, "with-http-libevent-dir", "Where to find libev{,ent{,2}}",
 202                                 CliArgs::OPTARG],
 203                         [null, "with-http-libidn-dir", "Where to find libidn",
 204                                 CliArgs::OPTARG],
 205                 ]);
 206
 207                 return function(Installer $installer) {
 208                         $opts = [
 209                                 "with-http-zlib-dir",
 210                                 "with-http-libcurl-dir",
 211                                 "with-http-libevent-dir",
 212                                 "with-http-libidn-dir",
 213                         ];
 214                         $args = $installer->getArgs();
 215                         foreach ($opts as $opt) {
 216                                 if (isset($args[$opt])) {
 217                                         $args->configure = "--$opt=".$args[$opt];
 218                                 }
 219                         }
 220                 };
 221         };
 222
 223 #### PECL source dirs
 224 For --pecl source dirs a pharext_install.php script is automatically
 225 generated from the package.xml which adds defined configure options
 226 and automatically generates a file list.
 227
 228 ## Rebuilding
 229
 230         $ make -C vendor/m6w6/pharext