As of PEAR version 1.4.3, the required format for custom file roles has been changed due to a minor security vulnerability. All custom file roles must now define a Role.xml file in order to properly declare a custom file role. See the example below for more information.
One of the programming features that the PEAR installer enforces is the separation of files into separate categories, and the important idea that files of a similar category are always installed into the same location, or at least handled the same way, as in the case of role="src" for PECL packages.
This has been quite successful for smaller library-style packages, but complete applications cannot function without customized installation locations. For instance, some files may be intended for use in a public web frontend, others for library location. PEAR 1.4 introduces the possibility of defining custom installation roles to fill this void.
To use a custom installation role that another programmer has written, there are three steps that are necessary. First, the <usesrole> tag should be used to define each custom role that is used in the package.xml. Next, the role should simply be used for the files it pertains to. Finally, a dependency on the package that provides the custom role should be added to the package.xml, just for completeness.