
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 :
$(variable) |
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
add [--target-path <target-path>] [--base-path <target-base>]
[--directory <dir>] [options] <source1> [<source2>...] |
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 :
add src |
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 :
add --directory src . |
Which will also add the whole 'src' subdirectory, but in the '/' virtual path.
Now, let's play with other options :
add --target-path /sources src |
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'.
add --base-path /program src |
This will include the src subdirectory as '/program/src'.
2.3.4.2 - modify
modify <options> <vpath1> [<vpath2> ... ] |
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 :
#-- Insert a source tree |
2.3.4.3 - mount
mount <path-variable> <path of phk package> |
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 :
mount phk_path /path/to/existing/package.phk |
2.3.4.4 - remove
remove <virtual-path1> [ <virtual-path2> ... ] |
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:
#-- I want to include everything except the doc which is in
$(SOURCE)/doc. |
Removing a non-existent directory is useless, but accepted.
Trying to remove the virtual root gives a fatal error.
2.3.4.5 - set
set <name> <value> |
Sets a variable to be used in the rest of the command section.
Example :
set doc_dir Documentation |
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 :
# Specify the URL between '<' and '>' characters |
When the string is displayed in HTML mode, the URL is extracted and displayed as an hypertext link.
Example :
'packager' => 'F. Laupretre <mailto:francois@tekwire.net>' |
'license' => 'New BSD License <http://framework.zend.com/license>' |
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:
'license' => 'New BSD License
<http://framework.zend.com/license>' |
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 |
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 :
mime_types: |
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 :
phkmgr build [-v] [-s <PSF>] [-d var=value] <package-file> |
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.