X-Git-Url: https://git.m6w6.name/?a=blobdiff_plain;f=README.md;h=dda399f7d145e6f0b09d016b56a595fab960d820;hb=f19ff9a5d4da63388654efd663f35ed2e08a8e4a;hp=c90551e14fbde638d317ef959f22774db8f10470;hpb=38589272e6101c3ed7589fd71d604d288cf68b79;p=pharext%2Fpharext diff --git a/README.md b/README.md index c90551e..dda399f 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,79 @@ # pharext -Distribute your PHP extension as self-installable phar executable +[![Join the chat at https://gitter.im/pharext/pharext](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/pharext/pharext?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) -## About +Distribute your PHP extension as self-installable phar executable. See https://pharext.org -### Disclaimer +## About You don't need this package to install any `*.ext.phar` extension packages, just run them with php: - $ ./pecl_http-2.4.0dev.ext.phar + $ ./pecl_http-2.4.2.ext.phar For a compressed phar, or if the execute permission bit got lost somehow: - $ php pecl_http-2.4.0dev.ext.phar.gz + $ php pecl_http-2.4.2.ext.phar.gz Command help: - $ ./pecl_http-2.4.0dev.ext.phar -h + $ ./pecl_http-2.4.2.ext.phar -h Yields: - pharext v1.1.0 (c) Michael Wallner - + pharext v3.0.0 (c) Michael Wallner + Usage: - - $ ./pecl_http-2.4.0dev.ext.phar [-hvqs] [-p|-n|-c ] - - -h|--help Display help - -v|--verbose More output - -q|--quiet Less output - -p|--prefix PHP installation prefix if phpize is not in $PATH, e.g. /opt/php7 - -n|--common-name PHP common program name, e.g. php5 or zts-php [php] - -c|--configure Additional extension configure flags, e.g. -c --with-flag - -s|--sudo [] Installation might need increased privileges [sudo -S %s] - --with-http-zlib-dir [] Where to find zlib [/usr] - --with-http-libcurl-dir [] Where to find libcurl [/usr] - --with-http-libevent-dir [] Where to find libevent [/usr] - - -If your installation destination needs escalated permissions, have a look at the `--sudo` option: - - $ ./pecl_http-2.4.0dev.ext.phar --sudo - Installing pecl_http-2.4.0dev.ext.phar ... - Running phpize ... OK - Running configure ... OK - Running make ... OK - Running install ... - Password:OK - Cleaning up /tmp/pecl_http-2.4.0dev.ext.phar.54fa02e3316f7 ... - Don't forget to activiate the extension in your php.ini! + + $ ./pecl_http-2.4.2.ext.phar [-hvqs] [-p|-n|-c|-i ] + + -h|--help Display help + -v|--verbose More output + -q|--quiet Less output + -p|--prefix PHP installation prefix if phpize is not in $PATH, e.g. /opt/php7 + -n|--common-name PHP common program name, e.g. php5 or zts-php [php] + -c|--configure Additional extension configure flags, e.g. -c --with-flag + -s|--sudo [] Installation might need increased privileges [sudo -S %s] + -i|--ini Activate in this php.ini instead of loaded default php.ini + --signature Show package signature + --license Show package license + --name Show package name + --date Show package release date + --release Show package release version + --version Show pharext version + --enable-propro [] Whether to enable property proxy support [yes] + --enable-raphf [] Whether to enable raphf support [yes] + --with-http-zlib-dir [] Where to find zlib [/usr] + --with-http-libcurl-dir [] Where to find libcurl [/usr] + --with-http-libevent-dir [] Where to find libevent [/usr] + + +If your installation destination needs escalated permissions, have a look at [the `--sudo` option](https://github.com/m6w6/pharext/wiki/Usage-of-*.ext.phar-packages#privileges): + + Installing propro-1.0.1.ext.phar ... + Running phpize ... + Running configure ... + Running make ... + Running make install ... + Running INI activation ... + Extension already activated ... + Successfully installed propro-1.0.1.ext.phar! + Installing raphf-1.0.5.ext.phar ... + Running phpize ... + Running configure ... + Running make ... + Running make install ... + Running INI activation ... + Extension already activated ... + Successfully installed raphf-1.0.5.ext.phar! + Installing pecl_http-2.4.2.ext.phar ... + Running phpize ... + Running configure ... + Running make ... + Running make install ... + Running INI activation ... + Extension already activated ... + Successfully installed pecl_http-2.4.2.ext.phar! ### Prerequisites @@ -60,171 +84,23 @@ The usual tools you need to build a PHP extension: A network connection is not needed. -## Download for extension maintainers - -Download the pharext binary of the [latest release](https://github.com/m6w6/pharext/releases/latest). - -## Installation for extension maintainers +## Extension maintainers - $ composer require --dev m6w6/pharext +Download the pharext binary of the [latest release](https://github.com/pharext/pharext/releases/latest). -### Prerequisites: +Be aware that you need the [public key](https://github.com/pharext/pharext/wiki/Public-key) to run official `pharext` releases. -* make -* php + phar + -----BEGIN PUBLIC KEY----- + MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA5x9bwisjDBDV/bwDiju2 + Ebx4kPir32WwT3+hxV0/qAPclA1WsrpcUJ7BChk+Rlz8ujOcyENTidgI1vj3oUpo + /P9XlLQOSrJHYz+AOg7qwhTe89xIJspS4gHHiXUAmxz0TyCNMbOyrLcjP5CmZdll + n+e3HP8Kfipr4XyWBhsKbdYUZ8Ga6IeFMYzNqCzWazcOasdCpsablmyrfCaZoJ0l + bFald0nF3/YoeYgo3fWb4Md9Xf/grpz8Ocqyq4OY49Vb0/p8FMwzBV6vbVh/eAV/ + jrP7L40Jw97nSBrP/5nK8Ylc5BayVRq/HhT3kLMC//zvPjb8xz3ZgVTQrwWTF3Zy + +wIDAQAB + -----END PUBLIC KEY----- -## Usage +Place it as `pharext.pubkey` in the same directory where the `pharext` binary is located. IF you cloned the repository or installed `pharext` through composer, it is already at the right location. +Please have a look at the [wiki](https://github.com/pharext/pharext/wiki), to learn [how to use](https://github.com/pharext/pharext/wiki/Usage-of-the-pharext-packager) the pharext installer to package self-installing PHP extensions. -Command help: - - $ ./vendor/bin/pharext --help - -Yields: - - pharext v1.1.0 (c) Michael Wallner - - Usage: - - $ ./bin/pharext [-hvqgpzZ] -n -r -s [-d ] - - -h|--help Display this help - -v|--verbose More output - -q|--quiet Less output - -n|--name Extension name (REQUIRED) - -r|--release Extension release version (REQUIRED) - -s|--source Extension source directory (REQUIRED) - -g|--git Use `git ls-files` instead of the standard ignore filter - -p|--pecl Use PECL package.xml instead of the standard ignore filter - -d|--dest Destination directory [.] - -z|--gzip Create additional PHAR compressed with gzip - -Z|--bzip Create additional PHAR compressed with bzip - -### PECL source dirs - -PECL source dirs can infer package name, release version and file list -from the package.xml. - - $ ./vendor/bin/pharext --pecl --source ../pecl_http.git - -Yields: - - Creating phar /tmp/54fa028adce40.phar ... OK - Finalizing ./pecl_http-2.4.0dev.ext.phar ... OK - -### GIT source dirs - -Another example using --git (`git ls-files`): - - $ ./vendor/bin/pharext -v -g -s ../raphf.git --name raphf --release 1.0.5 - -Yields: - - Creating phar /tmp/54fa0455a9aee.phar ... - Packaging .gitignore - Packaging CREDITS - Packaging Doxyfile - Packaging LICENSE - Packaging TODO - Packaging config.m4 - Packaging config.w32 - Packaging package.xml - Packaging php_raphf.c - Packaging php_raphf.h - Packaging raphf.png - Packaging tests/http001.phpt - Packaging tests/http002.phpt - Packaging tests/http003.phpt - Packaging tests/http004.phpt - Created executable phar /tmp/54fa0455a9aee.phar - Finalizing ./raphf-1.0.5.ext.phar ... OK - -### Packager and installer hooks - -#### Packager hook -If neither --pecl nor --git are explicitely given, pharext looks for a -`pharext_install.php` in --source. This script will be exectuted by the -Packager. It must return a callable with the following signature: - - function(Packager $pkg, $path) : function(Packager $pkg, $path); - -So, the callback should return another callable. -The primary callback is meant to set things like --name and --release, -so you don't have to on the command line; build automation FTW. -The secondary callback is meant to create the file iterator of the -source dir, but if you're in a git clone, you might easily just return a -new pharext\GitSourceDir and be done. - -##### Example for pecl_http - -pharext_package.php - - getArgs(); - $args->name = "pecl_http"; - $args->release = current(preg_filter("/^.*PHP_PECL_HTTP_VERSION\s+\"(.*)\".*$/s", "\$1", file("../http.git/php_http.h"))); - return function (Packager $packager, $path) { - return new GitSourceDir($packager, $path); - }; - }; - -#### Installer hook -The packager will look for a `pharext_install.php` file within the root of -the source dir. This script will be executed by the Installer; it must -return a callable with the following signature: - - function(Installer $installer) : function(Installer $installer); - -So, again, the callback should return another callable. -The primary callback is meant to add your own command line arguments to -the CliArgs parser, and the secnodary callback is meant to proccess -those args. - -##### Example for pecl_http - -pharext_install.php - - getArgs()->compile([ - [null, "with-http-zlib-dir", "Where to find zlib", - CliArgs::OPTARG], - [null, "with-http-libcurl-dir", "Where to find libcurl", - CliArgs::OPTARG], - [null, "with-http-libevent-dir", "Where to find libev{,ent{,2}}", - CliArgs::OPTARG], - [null, "with-http-libidn-dir", "Where to find libidn", - CliArgs::OPTARG], - ]); - - return function(Installer $installer) { - $opts = [ - "with-http-zlib-dir", - "with-http-libcurl-dir", - "with-http-libevent-dir", - "with-http-libidn-dir", - ]; - $args = $installer->getArgs(); - foreach ($opts as $opt) { - if (isset($args[$opt])) { - $args->configure = "--$opt=".$args[$opt]; - } - } - }; - }; - -#### PECL source dirs -For --pecl source dirs a pharext_install.php script is automatically -generated from the package.xml which adds defined configure options -and automatically generates a file list. - -## Rebuilding - - $ make -C vendor/m6w6/pharext