1. What you need

1.1. A PHP CLI interpreter

1.2. phkmgr

2. The Package Specification File

2.1. Structure

2.2. Subfile paths

2.3. The command section

2.3.1. Syntax

2.3.2. Variables

2.3.3. Options

2.3.3.1. '-n'/'--no-autoload'

2.3.3.2. '-a'/'--autoload'

2.3.3.3. '-s'/'--strip'

2.3.3.4. '-p'/'--plain'

2.3.3.5. '-c'/'--compression'

2.3.3.6. '-C'/'--directory', '-t'/'--target-path' and '-b'/--'target-base'

2.3.4. Commands

2.3.4.1. add

2.3.4.2. modify

2.3.4.3. mount

2.3.4.4. remove

2.3.4.5. set

2.4. The 'options' section

2.4.1. Syntax

2.4.2. Embedding an URL in a string

2.4.3. PSF options

2.4.3.1. author

2.4.3.2. auto_umount

2.4.3.3. crc_check

2.4.3.4. compress_min_size

2.4.3.5. compress_max_size

2.4.3.6. compress_ratio_limit

2.4.3.7. cli_run_script

2.4.3.8. copyright

2.4.3.9. distribution

2.4.3.10. help_prefix

2.4.3.11. icon

2.4.3.12. icon_bgcolor

2.4.3.13. icon_width

2.4.3.14. info_script

2.4.3.15. lib_run_script

2.4.3.16. license

2.4.3.17. license_prefix

2.4.3.18. max_php_version

2.4.3.19. mime_types

2.4.3.20. min_php_version

2.4.3.21. mount_script

2.4.3.22. name

2.4.3.23. packager

2.4.3.24. phpunit_package

2.4.3.25. phpunit_test_package

2.4.3.26. plugin_class

2.4.3.27. release

2.4.3.28. required_extensions

2.4.3.29. requires

2.4.3.30. summary

2.4.3.31. tabs

2.4.3.32. test_script

2.4.3.33. umount_script

2.4.3.34. url

2.4.3.35. version

2.4.3.36. web_access

2.4.3.37. web_main_redirect

2.4.3.38. web_run_script

2.4.4. Options reference table

3. Building the package

4. Registering autoload symbols

4.1. PHP source files detection

4.2. Advanced directives

5. Nested packages

5.1. Autoloading sub-packages

---

This document explains how to build a PHK package. If you just want to use an existing PHK package, refer to the PHK user's guide.

As this document is a reference guide, you may want to read this basic tutorial first.

Here is a global view of the build process :

The phkmgr tool interprets a Package Specification files and gathers a set of files into a package file.

1 - What you need

1.1 - A PHP CLI interpreter

In order to create a PHK package, you first need a PHP CLI interpreter, version 5.3.0 or more.

The PHP CLI interpreter is generally found in the bin subdirectory, under the PHP installation directory, or in /usr/bin. Its name is php on Unix/Linux, and php.exe on Windows.

In order to determine if your installation is suitable to build a PHK package, run the 'php -v' command in a shell. In the output, the first line must display version 5.3.0 or more, followed with the '(cli)' string.

1.2 - phkmgr

Then, you need the package creation software. Download the latest distribution from Github. It comes in the form of a tar/gz file. Uncompress/untar it, and you will find a file named phkmgr. This is the PHK building/management tool. The rest of the distribution is made of docs, tests, and examples. The phkmgr file can be installed anywhere on your system, provided it is in your PATH, as well as the PHP CLI interpreter. As this file is pure PHP, it is valid on every environments.

2 - The Package Specification File

Now that your platform is ready, you will create a Package Specification File. This file is interpreted by phkmgr and contains every information needed to build the package.

In the whole PHK documentation, PSF stands for Package Specification File.

2.1 - Structure

The PSF is a text file, created using any text editor (both Windows/CR-LF and Unix/LF line terminations are supported).

It is made up of two parts :

• the command section
• the options section

2.2 - Subfile paths

Basically, a package contains a tree of virtual or pseudo files, called subfiles. The subfile tree is made up of directories and files, as a usual file system. In this tree, each node is associated with a unique canonical virtual path. This path follows the Unix filesystem syntax :

• the root path is known as '/'
• The subdirectories are separated by '/' characters. In order to keep the compatibility with software using the DIRECTORY_SEPARATOR constant, the '\' character is also accepted as separator in subfile paths, but the PHK API always returns paths separated with '/' chars.

You will use this syntax when adding files to the archive and when specifying virtual paths in options like '{cli/web/lib}_run_script' and others.

2.3 - The command section

The first part in a PSF is the 'command section'. This section defines which files will be included in the package, where they come from, and their virtual path in the package.

2.3.1 - Syntax

Here is the syntax for the command section :

• Commands are composed of words, separated by spaces or tabs.
• The first word on a line is the command to run. The other words are options and arguments.
• Commands, options, and arguments cannot contain any space or tab character.
• Anything following a '#' char is considered as a comment and ignored.
• A line can be continued by setting a '\' as its last character.

2.3.2 - Variables

Variables can be set, and then used in any subsequent command. Values are strings.

A variable is set through the 'set' command described below. Environment variables from the calling environment can also be used (the variable is searched first in the PSF internal table, then in the environment).

A variable's value can be used and substituted anywhere, using a Makefile-like syntax :

Among others, variables are used to tranmit values from the calling environment to the PSF, allowing to keep the same PSF with different software locations. Look at the examples provided in the distribution to see more about this practice.

2.3.3 - Options

Options can be set anywhere on command lines. Each option has a short and a long form. Both are listed here :

2.3.3.1 - '-n'/'--no-autoload'

The default is to extract symbols from every file recognized as a PHP script. This option allows to disable this extraction for one or several files.

2.3.3.2 - '-a'/'--autoload'

This is the opposite of the '--no-autoload' option, and the default behavior.

2.3.3.3 - '-s'/'--strip'

This option indicates that comments should be removed from the file. This allows to reduce the package size and improve performance.

Unlike files processed using php_strip_whitespace(), the process used here preserves line numbers (essential for interpreting error messages).

2.3.3.4 - '-p'/'--plain'

This indicates that the files should be inserted as-is in the package (no strip)

2.3.3.5 - '-c'/'--compression'

This option is followed with a string. It may be 'none', 'gzip', or 'bzip2'. It indicates how the file(s) will be compressed before being inserted in the package. The default is 'none'.

Uncompression is tranparent and does not require any explicit action.

Note that compression and uncompression requires the corresponding PHP extension to be present to compress AND uncompress. If you choose to compress some of your files using gzip, for instance, a dependency on the zlib extension will be automatically added to your package. The same for bzip2. When loading the package, extension dependencies are checked first, and the package cannot run if those cannot be satisfied. It may be a reason to choose not to compress files when you're not sure of the runtime environment, especially for bzip2, which is more efficient but not available everywhere.

2.3.3.6 - '-C'/'--directory', '-t'/'--target-path' and '-b'/--'target-base'

These options are specific to the 'add' command and are detailed in the corresponding chapter below.

---

You may wonder why we provide options to set the default behavior. This is because the 'modify' command allows to modify the properties. So, you may add a whole set of files with a 'strip' flag, for instance, and then mark a single file inside as 'plain' (not stripped). If those options did not exist, it wouldn't be possible to revert a part of the tree to the default behavior.

The 'autoload' and 'strip' options have an effect only for files which are identified as PHP source files at package creation time. For more information about this detection mechanism, see the 'Identifying PHP source files' chapter below.

The 'compress' option sets only the way the file will be stored in the package. When this file is read at runtime, it is transparently uncompressed. So, the 'compress' option's only effect is to reduce the package size, at the expense of a slower access to the file at runtime.

2.3.4 - Commands

2.3.4.1 - add

Adds files or directories to the virtual tree. If the source path is a directory, this directory and its content are recursively included.

The '--directory' option indicates that this directory should be taken as the base source path for arguments. It can be understood as an indication to cd to the directory first.

The '--target-path' option indicates the virtual path where the files will be stored. As a side effect, it implies that the command contains only one argument. It is the only way to bypass the source file name.

The '--base-path' option indicates a virtual base that will be combined with arguments. The default base is the root of the virtual tree.

Arguments are generally relative paths. They are considered relative to the directory containg the PSF.

Examples :

If we consider that 'src' is a subdirectory, this command will add the content of the whole subdirectory under the '/src' virtual path.

Compare this with :

Which will also add the whole 'src' subdirectory, but in the '/' virtual path.

Now, let's play with other options :

This will include the src subdirectory, but in the '/sources' virtual tree. Files contained in the src subdir will have a virtual path like '/sources/filexx'.

This will include the src subdirectory as '/program/src'.

2.3.4.2 - modify

This command is used to change the options associated with a part of the virtual tree. When an argument is a virtual directory, the options are recursively applied.

Options are used only after the whole PSF is processed. So, adding files with a given option is exactly the same as adding them without the option and then using modify to set it.

Example :

2.3.4.3 - mount

This command is used when you want to extract data from an existing package to a new one.

The <path-variable> is the name of a variable which will receive the prefix to use when accessing the package's content.

An example will make it clearer :

Imagine that you want to extract the '/etc' virtual subtree from an existing package and insert it as '/params' in a new package you're building. Here's what you will write :

2.3.4.4 - remove

Removes a part of the virtual tree we are currently building.

Why would we need to destroy something we are building ? Generally to implement an exclusion, when it is easier to include a whole file tree except some parts of it.

Example:

Removing a non-existent directory is useless, but accepted.

Trying to remove the virtual root gives a fatal error.

2.3.4.5 - set

Sets a variable to be used in the rest of the command section.

Example :

2.4 - The 'options' section

This section, as its name implies, contains the packages's options.

2.4.1 - Syntax

The user has the choice between 3 syntaxes for this section :

• YAML
• JSON
• PHP code (returning an array)

The section starts with a line starting with '%options'. An optional '--syntax' modifier allows to choose the syntax. The default is YAML. Whatever the syntax, this section defines an array of package options.

When using PHP code, the leading '<?php' and trailing '?> must be omitted. Look at the 'getid3' example in the PHK distribution for an example of PSF containing options as PHP code.

Example of an options section (using the default YAML syntax) :

The same, using PHP code, would be :

2.4.2 - Embedding an URL in a string

As you may see in the previous example, in option values, the strings displayed in webinfo mode, like the license, author, packager, etc, can embed an URL, using the following syntax :

When the string is displayed in HTML mode, the URL is extracted and displayed as an hypertext link.

Example :

will give the following webinfo output :

Packager:	F. Laupretre
License:	New BSD License

2.4.3 - PSF options

• The options which can contain an URL are flagged as 'string with optional URL'.
• The options which don't have any impact on the package's behavior, except when displayed in webinfo mode, are flagged as '(Information only)'.

2.4.3.1 - author

Type: string with optional URL

The package's author (Information only)

2.4.3.2 - auto_umount

Type: Boolean - Default=false.

This parameter is used with the script referenced in the 'lib_run_script' option. When it is true, the PHK archive is automatically unmounted after the 'lib_run_script' is run, and the include/require returns null.

Using this parameter allows to define some kind of 'volatile' packages: they are available just the time to do what they have to, and then, they disappear.

Example : this parameter can be used for unit tests :

• the test code is put in a PHK package, and this package is itself embedded in a higher level PHK package (with an 'autoload=false' option),
• the test package is defined as the 'test_script' in the 1st level package,
• in the tests package, the script that will start testing is defined as 'lib_run_script' and auto_umount is set to true.

The result is that, when we request a '@test' on the main package :

• the main package includes the test package because it is defined as its 'test_script',
• once the tests package is mounted, it runs its 'lib_run_script' and executes the unit tests,
• When the tests are complete, because of the auto_umount option, the tests package is unmounted.

2.4.3.3 - crc_check

Type: Boolean (default = false)

If set, a CRC check will be forced every time the package is mounted. By default, as it is too expensive, as it requires to read the whole package file in memory. So, by default, the CRC is checked only when accessing the webinfo mode, before executing a built-in CLI command, or when using the PECL extension (as the information is cached in permanent memory).

Unlike CRC, the file size is checked each time the package is loaded, as it allows to detect typical erroneous FTP ascii/binary conversions. Please note that PHK packages, even if they can be considered as PHP scripts and run as such, must not be modified by an external tool, such as a transfer conversion. So, when transferring a PHK file through FTP, always use the binary mode.

2.4.3.4 - compress_min_size

Type: numeric. Default = 0.

This parameter is used when building the package, and for every subfile with a compression flag. If the file size (before compression) is lower than this value, the file is not compressed.

2.4.3.5 - compress_max_size

Type: numeric. Default = no limit.

This parameter is used when building the package, and for every subfile with a compression flag. If the size of the file (uncompressed) is greater than this parameter's value, the file is not compressed. This parameter allows to avoid compressing files whose size makes them too heavy for on-the-fly decompression.

2.4.3.6 - compress_ratio_limit

Type: numeric (0-100), default=90

This parameter is used when building the package, and for every subfile with a compression flag. If the file's compression ratio is greater than this value, the file is left uncompressed.

Compression ratio = 100 * <compressed size> / <uncompressed size>

The primary purpose, here, is to avoid compressing already compressed files, pictures, or very small files.

The default value is not 100% because :

• 1. we consider that, when compressing a file, if the resulting compressed size is more than 90% of the original size, the gain in space is not worth the CPU power that will be consumed at decompression time.
• 2. it allows to filter out some 'basic-RLE' compressed files (pictures generally), whose gzip-compressed size is still slightly smaller than their original size. There, again, we consider that a double compression scheme is not worth the CPU it will use.

2.4.3.7 - cli_run_script

Type: Subfile path

The script to run when the package is run in CLI mode (virtual path).

2.4.3.8 - copyright

Type: string with optional URL

Copyright notice (Information only)

2.4.3.9 - distribution

Type: string with optional URL

Self-explanatory. Information only

2.4.3.10 - help_prefix

Type : Subfile path without suffix.

The 'help_prefix' option is used when searching for the help file to display (webinfo 'Help' page or CLI '@help' built-in command). In HTML, PHK looks for a subfile with a suffix of '.htm' or '.html'. If not found, it tries to find a file with a '.txt' suffix or with no suffix.

Example: if you give '/etc/help' as 'help_prefix', PHK will look in turn for these filenames:

In HTML :

• 1. /etc/help.htm
• 2. /etc/help.html
• 3. /etc/help.txt
• 4. /etc/help

In CLI mode :

• 1. /etc/help.txt
• 2. /etc/help

As a text file can be used in both mode, and an HTML file can be used only in HTML mode, provide a text file first and, optionally, an HTML file.

2.4.3.11 - icon

Type: Subfile path

Defines the path of the subfile to take as the package's icon. In webinfo mode, this image is displayed on every page. When the user clicks on this image, he goes to the address specified with the url option :

If your image subfile's suffix is not defined in the PHK default mime table, you must provide its mime type using the mime_types option.

2.4.3.12 - icon_bgcolor

Type: String / HTML color spec

The background color to set around the icon in webinfo mode.

This parameter can contain any value suitable for a '<td bgcolor=...' element.

2.4.3.13 - icon_width

Type: HTML cell width specification. Default = 150 pixels.

The width of the cell containing the icon in webinfo mode (see figure above).

This parameter can contain any value suitable for a '<td width=...' element (absolute, percentage, etc).

2.4.3.14 - info_script

Type: Subfile path

The script to run when the webinfo Home page is displayed, instead of the default information.

As any PHP script, this can contain PHP code or just static HTML content.

2.4.3.15 - lib_run_script

Type: Subfile path

The script to run when the PHK archive is included from another PHP script.

2.4.3.16 - license

Type: string with optional URL

Information only. This parameter contains the license's name and, by convention, should contain an URL to the license home page.

Example:

2.4.3.17 - license_prefix

Type : Subfile path without suffix.

The same as 'help_prefix', but for the license.

2.4.3.18 - max_php_version

Type: String

The maximum PHP version this package supports.

2.4.3.19 - mime_types

Type: Array

This array contains additonal mime types to associate with file suffixes. These mime types are used in webinfo mode when displaying a subfiles's content, and in execution mode when accessing subfiles directly through the web (direct web access).

By default, PHK knows the following suffixes :

Suffix	Mime type
gif	image/gif
jpeg	image/jpeg
jpg	image/jpeg
png	image/png
psd	image/psd
bmp	image/bmp
tif	image/tiff
tiff	image/tiff
iff	image/iff
wbmp	image/vnd.wap.wbmp
ico	image/x-icon
xbm	image/xbm
txt	text/plain
htm	text/html
html	text/html
css	text/css
php	application/x-httpd-php
phk	application/x-httpd-php
pdf	application/pdf
js	application/x-javascript
swf	application/x-shockwave-flash
xml	application/xml
xsl	application/xml
xslt	application/xslt+xml
mp3	audio/mpeg
ram	audio/x-pn-realaudio
svg	image/svg+xml

Through this option, you can redefine suffixes from the default mime table.

Example: if you want to access some MS Word™ and MS Excel™ documents via direct web access, you will need to set the following option :

2.4.3.20 - min_php_version

Type: String

The minimum PHP version this package supports.

2.4.3.21 - mount_script

Type: Subfile path

This script is called at the end of the mount process.

If the 'mount_script' decides that the package cannot run in this environment, for any reason, it can 'refuse' the mount by throwing an exception.

When the 'mount_script' is run, the plugin object, if any, is not created yet, so it cannot be called.

2.4.3.22 - name

Type : String

The package's name (Information only)

2.4.3.23 - packager

Type: string with optional URL

The package's builder (Information only)

2.4.3.24 - phpunit_package

Type: Subfile path

This option is used, along with phpunit_test_package, when the PHPUnit test package does not contain the PHPUnit package. In this case, the container package must contain the PHPUnit package, generally flagged as 'autoload=false', not to uselessly export the PHPUnit symbols to the container's automap. In this case, you must explicitely define where the PHPUnit package lies through this option.

2.4.3.25 - phpunit_test_package

Type: Subfile path

This option, introduced with PHK 1.4, should be used when your unit tests use PHPUnit, instead of the older test_script option.

This option contains the path of a subpackage containing your test file tree.

When using this option, you should not set the test_script option.

2.4.3.26 - plugin_class

Type : class name.

For more information on this parameter, please read this document.

2.4.3.27 - release

Type : String

Self-explanatory. Information only.

2.4.3.28 - required_extensions

Type: Array

A list of PHP extensions required by the package. Each time the package is run, PHK checks that all these required extensions are present or can be loaded by dl(). If it is not the case, it triggers a fatal error.

This behavior was chosen because we consider it cleaner than getting a cryptic error message when a missing function or class is called. The philosophy here is that, if your package is not compatible with your runtime environment, you must know it as early as possible (without having to test every features).

If some of the package's subfiles are compressed, the corresponding extensions ('zlib' and/or 'bz2') are automatically appended to the list of required extensions.

When using nested packages, subpackage dependencies are automatically added to the container's dependencies.

The extensions listed here are extension names, without file suffixes (ex: 'iconv', 'gd', etc.). PHK automatically determines the filename to dl().

2.4.3.29 - requires

Type: String

What the package requires to run (Information only).

2.4.3.30 - summary

Type: String

Self-explanatory. Information only

2.4.3.31 - tabs

Type Array.

Additional tabs to display in webinfo mode.

Each array element corresponds to one additional tab. The key is the string to display in the tab, and the value gives the action to associate with this tab.

To be completed with a list of possible actions...

2.4.3.32 - test_script

Type: Subfile path

A script to call when the user displays the webinfo 'test' page, or when it runs the '@test' built-in command.

This is the low-level interface to the unit tests feature. You can use the new mechanism, specifically intended for PHPUnit tests, via the phpunit_test_package and phpunit_package options.

2.4.3.33 - umount_script

Type: Subfile path

This script is called just before a PHK archive is unmounted.

When it is run, the plugin object, if any, is already unset, but the automap is still active.

This script is called only when explicitely calling \PHK\Mgr::umount(). When the program ends, no umount script is executed.

2.4.3.34 - url

The URL to call when the user clicks on the package's icon in webinfo mode.

2.4.3.35 - version

Type: String

Self-explanatory. Information only.

2.4.3.36 - web_access

Type: Array of subfile paths

A list of subfile paths authorized for web direct access.

If an authorized path is a directory, everything under this node is authorized. So, putting '/' in the list gives an open access to the whole file tree.

2.4.3.37 - web_main_redirect

Type: Boolean - Default=false.

In web direct access mode, when the URL we receive does not contain any subfile path, or if the requested subfile path is not authorized, PHK tries to execute the script defined by the 'web_run_script' option. Then :

• If the 'web_main_redirect' option is set, PHK returns an HTTP 301/Redirect with the URL of the web_run_script, so that the browser does a redirection.
• If the 'web_main_redirect' option is not set, the web_run_script is transparently executed. In this case, the browser has no way to know which 'real' URL was executed.

The choice of the value to give to this parameter depends on the software you package. If the web_run_script uses relative links, it may be better to set the web_main_redirect option, as relative links are resolved by the browser, but there is no simple rule for this.

2.4.3.38 - web_run_script

Type: Subfile path

The script to run, in web direct access mode, when :

• the URL we receive does not contain any subfile path,
• or when the requested subfile path is not authorized (by the 'web_access' option).

2.4.4 - Options reference table

Option name	Type	Default	Info only	Comments
author	String (URL)	Empty
auto_umount	Boolean	False
crc_check	Boolean	False
test_script	Subfile path	<none>
cli_run_script	Path	<none>
compress_max_size	Integer	No limit		Unit = bytes
compress_min_size	Integer	0		Unit = bytes
compress_ratio_limit	Percentage	90
copyright	String (URL)	Empty
distribution	String (URL)	Empty
help_prefix	Subfile path	<none>
icon	Subfile path	<none>
icon_bgcolor	HTML color spec	<auto>
icon_width	HTML width spec	<auto>
info_script	Path	<none>
lib_run_script	Subfile path	<none>
license	String (URL)	Empty
license_prefix	Subfile path	<none>
max_php_version	String	<none>
mime_types	Array	Empty		Keys=suffix ; values=mime types
min_php_version	String	<none>
mount_script	Subfile path	<none>
name	String	<auto>		Default = PHK file name
packager	String (URL)	Empty
phpunit_package	Subfile path	<none>
phpunit_test_package	Subfile path	<none>
plugin_class	Class name	<none>
release	String	Empty
required_extensions	Array	Empty		Extension names without file suffix
requires	String + URL	Empty
summary	String + URL	Empty
tabs	Array	Empty		Key=String to display in tab; Value = Subfile path
umount_script	Subfile path	<none>
url	URL	<none>
version	String	Empty
web_access	Array	Empty		Array of subfile paths
web_main_redirect	Boolean	False
web_run_script	Subfile path	<none>

3 - Building the package

PHK packages are built in command-line mode. On Unix, you use a shell command. On windows, you start a command window.

You may also be interested by this tutorial

The syntax to build a package is :

where :

• we suppose that the phkmgr command is in your path. If it is not the case, replace with the full path,
• <PSF> is the path to the PSF file you want to use. The default is to derive the PSF filename from the package filename (replacing the file suffix with '.psf'),
• <package-file> is the path where the new PHK package will be created (if a previous file exists with the same name, it will be overwritten),
• The '-d' option allows to pass a variable to the PSF file. It can be used more than once, allowing to pass several variables.
• The '-v' option increases the verbose level. It can be used more than once as there are two trace levels.

During the build process, if the '-v' option was not set, phkmgr shouldn't display anything.

Return code: phkmgr returns 0 if no error, and a value != 0 if an error was encountered.

4 - Registering autoload symbols

In most cases, symbol registration is a transparent process and you don't have to care about it. The following information can be used for troubleshooting or for advanced cases.

4.1 - PHP source files detection

When creating the package, phkmgr needs to determine which files must be considered as PHP source files. Only these files will be scanned for symbols, except if they were flagged as '--no-autoload' in the PSF.

The following file suffixes are considered as PHP source : .php, .phk, .inc, .hh.

4.2 - Advanced directives

If you want to hide a symbol from being detected (in case of symbol multiply defined), or for other unusual needs, you may be interested by Automap directives. These are inserted in the PHP scripts and modify the way symbols are extracted.

5 - Nested packages

PHK supports including a package into another package. This is called a nested package, or subpackage, or meta-packaging.

There are several cases where subpackages are interesting :

• When embedding unit tests with a package, it allows to keep the code and symbol maps separate. With such an approach, embedding the unit tests does not imply any speed penalty when running the package as, until the tests are executed, the test package is totally ignored. Separating symbol maps is an important point too.
• You may group several PHK packages, with or without dependencies. This way, as they are merged in a single package file, it is easier to maintain, distribute, install, etc. It is also faster because they won't be mounted until one of their symbols is required, and only the needed packages will be loaded.
• In a similar way, it can allow to package an application with its dependencies.
• A subpackage's behavior depends on its meta-data, which is specific to this package (mime types, for instance, give a specific behavior to the package).
• A subpackage's integrity can be checked. Package signature remains valid and can be checked.
• And probably a lot of other cases...

5.1 - Autoloading sub-packages

You can specify whether an embedded package exports its symbols to the higher-level map or not, using the 'autoload/no-autoload' option. By default, the symbols are exported to the upper-level package.

When symbols are exported, the including package will automatically mount an embedded package when one of its symbols is referenced. So, as this feature is recursive, by default, every symbol of every embedded package is present in the upper-layer map and can be autoloaded, even if the corresponding package is not currently mounted.

Sometimes (for instance when embedding a package containing unit tests), you don't want the embedded package's symbols to be merged into the main map. In such cases, you will explicitely disable symbol export with a '--no-autoload' option on the subpackage.