File roles
Pyrus and The PEAR Installer categorize file types by their role.
A file role is equivalent to the web's concept of MIME type,
a concept that allows web browsers to determine how a file should be displayed
or processed. A file role allows Pyrus and the PEAR Installer to determine
where a file should be installed, the conditions under which the role can be
used, and even whether the file should be installed at all. A file may only
have one role in a package.
Generally speaking, each file role has its own installation location. For
example, php files (files whose file role is
php) are installed into the location specified by the
php_dir configuration variable, data
files (files whose file role is data) are installed into
the location specified by the data_dir configuration
variable. Some file roles do not have a direct mapping of role name
to configuration variable, such as Pyrus's customcommand
file role. This file role is installed into the location specified by the
data_dir configuration variable.
File roles also control how package.xml attributes are handled. The
php file role installs files into the exact
relative path as specified in package.xml. The data
file role always installs files into a subdirectory containing the package name
for PEAR packages, and both the channel and package name for packages designed
to be installed by Pyrus.
Here is an example of the same file path in package.mxl as php
role and as data role. All examples assume this is a
package named PackageName in the pear2.php.net
channel.
<contents>
<dir name="\">
<dir name="base">
<file name="foo" role="php">
</dir>
</dir>
</contents>
This installs as base/foo in the location specified
by php_dir.
<contents>
<dir name="\">
<dir name="base">
<file name="foo" role="data">
</dir>
</dir>
</contents>
For PEAR Installer packages, this installs as PackageName/base/foo
in the location specified by php_dir. For Pyrus packages,
this installs as pear2.php.net/PackageName/base/foo.
How the baseinstalldir attribute is handled by different file roles
The baseinstalldir (base installation directory) attribute
is a tool that can be used to install a file into a different directory than
its location in the source repository.
As an example, the path in the subversion repository to the file
PEAR2\Foo.php is at
Foo.php. To inform the installer to install this
package into the PEAR2 directory, we would use a baseinstalldir
attribute:
<contents>
<dir name="\">
<file name="Foo.php" role="php" baseinstalldir="PEAR2">
</dir>
</contents>
The attribute can also be used on <dir> tags to apply
the base installation directory to all files within the directory:
<contents>
<dir name="\" baseinstalldir="PEAR2">
<file name="Foo.php" role="php">
</dir>
</contents>
The baseinstalldir role can also be used to inform
the PEAR Installer or Pyrus to strip all relative paths by using
/ as the base installation directory. Here is an
example from the PEAR package:
<dir name="scripts" baseinstalldir="/">
<file name="pear.bat" role="script"/>
This file would be installed as scripts/pear.bat, but
the baseinstalldir attribute of /
informs the installer to instead install it to pear.bat.
Each file role reacts differently to the baseinstalldir
attribute. Packages designed to be installed by the PEAR Installer also
handle them differently from packages designed for installation by Pyrus.
The php, script and www
file roles react the
same way as documented above. In packages designed for the PEAR Installer,
the other file roles do not honor the
baseinstalldir attribute, meaning they ignore it. For
example:
<contents>
<dir name="\" baseinstalldir="PEAR2">
<file name="Foo.dat" role="data">
</dir>
</contents>
installs Foo.dat into the PackageName/Foo.dat
directory. The same XML in a package designed for installation by Pyrus
will install the file into pear2.php.net/PackageName/PEAR2/Foo.dat.