435: documentation improvements for 1.4.0 features

Author: asgrim

README.md

@@ -2,11 +2,12 @@
 
 ## What is PIE?
 
-PIE is a new installer for PHP extensions, intended to eventually replace PECL.
-It is distributed as a [PHAR](https://www.php.net/manual/en/intro.phar.php),
-just like Composer, and works in a similar way to Composer, but it installs PHP
-extensions (PHP Modules or Zend Extensions) to your PHP installation, rather
-than pulling PHP packages into your project or library.
+PIE is the official installer for PHP extensions, which replaces
+[PECL](https://pecl.php.net/) (which is now deprecated). PIE is distributed as a
+[PHAR](https://www.php.net/manual/en/intro.phar.php), just like Composer, and
+works in a similar way to Composer, but it installs PHP extensions (PHP Modules
+or Zend Extensions) to your PHP installation, rather than pulling PHP packages
+into your project or library.
 
 # Using PIE - what do I need to get started?
 
@@ -15,12 +16,8 @@ than pulling PHP packages into your project or library.
 You will need PHP 8.1 or newer to run PIE, but PIE can install an extension to
 any other installed PHP version.
 
-On Linux, you will need a build toolchain installed. On Debian/Ubuntu type
-systems, you could run something like:
-
-```shell
-sudo apt install gcc make autoconf libtool bison re2c pkg-config php-dev
-```
+On Linux/OSX, if any build tools needed are missing, PIE will ask if you would
+like to automatically install them first (this is a new feature in 1.4.0).
 
 On Windows, you do not need any build toolchain installed, since PHP extensions
 for Windows are distributed as pre-compiled packages containing the extension
@@ -38,7 +35,9 @@ Further installation details can be found in the [usage](./docs/usage.md) docs.
 This documentation assumes you have moved `pie.phar` into your `$PATH`, e.g.
 `/usr/local/bin/pie` on non-Windows systems or created an alias in your shell RC file.
 
-## Installing a single extension using PIE
+## Using PIE
+
+### Installing a single extension using PIE
 
 You can install an extension using the `install` command. For example, to
 install the `example_pie_extension` extension, you would run:
@@ -57,7 +56,7 @@ You must now add "extension=example_pie_extension" to your php.ini
 $
 ```
 
-## Installing all extensions for a PHP project
+### Installing all extensions for a PHP project
 
 When in your PHP project, you can install any missing top-level extensions:
 
@@ -87,6 +86,12 @@ The following packages may be suitable, which would you like to install:
 Finished checking extensions.
 ```
 
+> [!TIP]
+> If you are running PIE in a non-interactive shell (for example, CI, a
+> container), pass the `--allow-non-interactive-project-install` flag to run
+> this command. It may still fail if more than one PIE package provides a
+> particular extension.
+
 ## Extensions that support PIE
 
 A list of extensions that support PIE can be found on
@@ -105,6 +110,6 @@ A list of extensions that support PIE can be found on
 If you are an extension maintainer wanting to add PIE support to your extension,
 please read [extension-maintainers](./docs/extension-maintainers.md).
 
-## More documentation...
+# More documentation...
 
 The full documentation for PIE can be found in [usage](./docs/usage.md) docs.

docs/extension-maintainers.md

@@ -345,11 +345,16 @@ The list of accepted OS families: "windows", "bsd", "darwin", "solaris", "linux"
 
 #### Extension dependencies
 
-Extension authors may define some dependencies in `require`, but practically,
+Extension authors may define some dependencies in `require`, but typically,
 most extensions would not need to define dependencies, except for the PHP
-versions supported by the extension. Dependencies on other extensions may be
-defined, for example `ext-json`. However, dependencies on a regular PHP package
-(such as `monolog/monolog`) SHOULD NOT be specified in your `require` section.
+versions supported by the extension, and system libraries.
+
+Dependencies on a regular PHP package (such as `monolog/monolog`) SHOULD NOT be
+specified in your extension's `require` section.
+
+##### Dependencies on other extensions
+
+Dependencies on other extensions may be defined, for example `ext-json`.
 
 It is worth noting that if your extension does define a dependency on another
 dependency, and this is not available, someone installing your extension would
@@ -360,6 +365,47 @@ Cannot use myvendor/myextension's latest version 1.2.3 as it requires
 ext-something * which is missing from your platform.
 ```
 
+##### System Library Dependencies
+
+In PIE 1.4.0, the ability for extension authors to define system library
+dependencies was added, and in some cases, automatically install them.
+
+The following libraries are supported at the moment. **If you would like to add
+a library, please [open a discussion](https://github.com/php/pie/discussions)
+in the first instance.** Don't just open a PR without discussing first please!
+
+We are adding libraries and improving this feature over time. If the automatic
+install of a system dependency that is supported below in your package manager
+is NOT working, then please [report a bug](https://github.com/php/pie/issues).
+
+| Library       | Checked by PIE | Auto-installs in   |
+|---------------|----------------|--------------------|
+| lib-curl      | ✅              | apt, apk, dnf, yum |
+| lib-enchant   | ✅              | ❌                  |
+| lib-enchant-2 | ✅              | ❌                  |
+| lib-sodium    | ✅              | apt, apk, dnf, yum |
+| lib-ffi       | ✅              | apt, apk, dnf, yum |
+| lib-xslt      | ✅              | apt, apk, dnf, yum |
+| lib-zip       | ✅              | apt, apk, dnf, yum |
+| lib-png       | ✅              | ❌                  |
+| lib-avif      | ✅              | ❌                  |
+| lib-webp      | ✅              | ❌                  |
+| lib-jpeg      | ✅              | apt, apk, dnf, yum |
+| lib-xpm       | ✅              | ❌                  |
+| lib-freetype2 | ✅              | ❌                  |
+| lib-gdlib     | ✅              | ❌                  |
+| lib-gmp       | ✅              | ❌                  |
+| lib-sasl      | ✅              | ❌                  |
+| lib-onig      | ✅              | ❌                  |
+| lib-odbc      | ✅              | ❌                  |
+| lib-capstone  | ✅              | ❌                  |
+| lib-pcre      | ✅              | ❌                  |
+| lib-edit      | ✅              | ❌                  |
+| lib-snmp      | ✅              | ❌                  |
+| lib-argon2    | ✅              | ❌                  |
+| lib-uriparser | ✅              | ❌                  |
+| lib-exslt     | ✅              | ❌                  |
+
 #### Checking the extension will work
 
 First up, you can use `composer validate` to check your `composer.json` is

docs/usage.md

@@ -281,6 +281,31 @@ pie install example/some-extension --with-some-library-name=/path/to/the/lib
 pie install example/some-extension --with-some-library-name=/path/to/the/lib --enable-some-functionality
 ```
 
+### Build tools check
+
+PIE will attempt to check the presence of build tools (such as gcc, make, etc.)
+before running. If any are missing, an interactive prompt will ask if you would
+like to install the missing tools. If you are running in non-interactive mode
+(for example, in a CI pipeline, container build, etc), PIE will **not**
+install these tools automatically. If you would like to install the build tools
+in a non-interactive terminal, pass the `--auto-install-build-tools` and the
+prompt will be skipped.
+
+To skip the build tools check entirely, pass the `--no-build-tools-check` flag.
+
+### System library dependencies check
+
+PIE will attempt to check the presence of system library dependencies before
+installing an extension. If any are missing, an interactive prompt will ask if
+you would like to install the missing tools. If you are running in
+non-interactive mode (for example, in a CI pipeline, container build, etc), PIE
+will **not** install these dependencies automatically. If you would like to
+install the system dependencies in a non-interactive terminal, pass the
+`--auto-install-system-dependencies` and the prompt will be skipped.
+
+To skip the dependencies check entirely, pass the
+`--no-system-dependencies-check` flag.
+
 ### Configuring the INI file
 
 PIE will automatically try to enable the extension by adding `extension=...` or