Package Directory Structure

This document was issued on 4th November 2003 and describes which directory structure must be used in PEAR packages. The goal of this document is to unify the directory naming in SVN and after installations.

Let's assume we have a package The_Package_Name that contains one or more sub-classes (eg. The_Package_Name_Module), with some documentation (perhaps a README, copies of RFCs, etc.), a battery of test scripts (unit tests, regression tests, etc.), and it uses some data files (localization strings, etc.), the dir tree would look like:

 The_Package_Name |-- Name (contains Module.php) |-- data |-- docs |   `-- examples |-- misc |-- scripts `-- tests      

Name refers to the last part of the The_Package_Name, all subclasses of the main class, should be put in there or subdirectories of it. You can refer to http://svn.php.net/viewvc/pear/packages/Cache_Lite/trunk/ - the directory Lite as an example (this basically documents what we currently do anyway).

The data and misc directories are optional, because it will not make sense to have them for every single package in PEAR.

The directories that are required are docs/examples and tests. A package may have no extra documentation, but it should have at least one example. There must also be some basics test to be able to verify that the package is working. The preferred type of testing script system to use is PHPUnit or .phpt. But for now we would be content with any sort of test script.

Files in scripts will be installed into a directory available in $PATH, such as /usr/local/bin.

Anything that does not fit any of the above categories is placed into the misc directory.

Maintainers are expected to modify their existing packages to match this new standard.