PEAR Channels, draft 0.4
| From: | Greg Beaver | Date: | Fri, 20 Feb 2004 17:35:21 +0000 |
| Subject: | PEAR Channels, draft 0.4 | ||
| Groups: | php.pear.core | ||
| Request: | Send a blank email to pear-core+get-111@lists.php.net to get a copy of this message | ||
Hi,
I'm going to start coding the channels stuff, this is the last chance for input before code begins to commit to CVS.
Thanks,
Greg
PEAR Channels draft rev. 0.4
----------------------------
February 20, 2004
Author (rev 0.1-0.4):
Greg Beaver
What it is
----------
Channels are a logical grouping of packages. Just as a Package is a logical grouping of related classes, a channel is a logical grouping of related packages. Unlike the code in a package, there need not be any actual code relationship between the packages in a channel.
The problem channels solve
--------------------------
The primary benefit of the PEAR installer is its ability to automatically upgrade packages when passed only a package name, and to automatically resolve dependencies and install them
$ pear install Package
However, for a non-PEAR package, such as packages distributed by Horde, it is not possible to take advantage of this, as full URLs must be used.
$ pear install http://www.example.com/examplePackage-1.0.tgz
Upon upgrade, the user must again specify a full URL to a package.
Channels will be associated with a specific server, allowing custom PEAR-style servers to be set up and used by the PEAR installer automatically. In other words, this would now work:
$ pear install org.horde.pear::examplePackage
This also defines a namespace for packages: every package within a channel can be automatically installed into a separate location from the primary PEAR php directory. For certain cases this will not be necessary, such as the PECL channel, which will be devoted to PHP extensions that must go into the same directory.
Details
-------
A channel has associated with it:
- A summary, or brief description of what the channel provides
- A master server (http://pear.php.net, http://pecl.php.net, http://pear.horde.org <http://www.horde.org/>)
- A name based on the master server, java-style (net.php.pear, net.php.pecl, org.horde.pear)
- A possible default installroot ('', '', 'Horde') defining the subdirectory that files will be installed in (the Horde Log package will be installed in Horde/Log.php, PEAR’s Log package will be installed in Log.php. If installroot were 'Grob' the Horde Log package would be installed in Grob/Log.php).
The installer can have new channels registered with it manually
$ pear register-channel myserver.com MyInstallRoot
or, automatically
$ pear update-channels
Updating new channel net.php.pecl
(http://pecl.php.net, no installroot)
Updating new channel org.horde.pear
(http://pear.horde.org, "Horde" installroot)
To download a package from a specific channel, use the format "name.nick.channel::Packagename"
$ pear install net.php.pear::Log
$ pear install org.horde.pear::Log
$ pear install com.myserver::Log
If a non-specific package name is passed to the installer, a search path will be used to find the package. The default search order will be the order in which channels were registered, but this can be set in the config
$ pear config-set channel-path com.myserver org.horde.pear net.php.pear net.php.pecl
Channel search path set to myserver.com->pear.horde.org->pear.php.net->pecl.php.net
In package.xml, channel can be specified in the package name
<package>
<name>net.php.pear::Log</name>
For Backwards Compatibility, if no channel is specified, the net.php.pear channel will be assumed for all dependencies.
Dependency specification might look like:
<dep rel="has" type="pkg">net.php.pecl::APC</dep>
<dep rel="eq" version="1.7.0" type="pkg">org.horde.pear::Log</dep>
In order to refer to a channel for listing commands, use the syntax "net.name.channel::" as in:
$ pear list-all net.php.pear::
It is NOT possible to upgrade across a channel. In other words:
$ pear install net.php.pear::Foo
$ pear upgrade org.horde.pear::Foo
this sequence will fail because net.php.pear::Foo is not the same as org.horde.pear::Foo even though the package name is the same.
Sub-Channels
------------
A sub-channel is a separate collection of packages that share the same namespace as a channel. In other words, if PEAR has a sub-channel named QA, this sequence is possible:
$ pear install net.php.pear::Log
install to 1.10 OK
$ pear upgrade net.php.pear.qa::Log
upgrade to 1.10.1 OK
A sub-channel must be a sub-domain of a primary channel.
A sub-channel may NEVER be specified in a package.xml, this is a server-only implementation.
Database Implementation for pearweb
-----------------------------------
CREATE TABLE channels (
id INTEGER NOT NULL,
parent VARCHAR(30),
summary TEXT NOT NULL,
server VARCHAR(255),
installroot VARCHAR(255),
PRIMARY KEY(id),
UNIQUE INDEX(name),
INDEX(parent)
);
INSERT INTO channels (id, parent, name, summary, server, installroot) VALUES(1, 0, 'PHP Extension and Application Repository, PHP 4', 'pear.php.net', '');
INSERT INTO channels (id, parent, name, summary, server, installroot) VALUES(2, 0, 'PHP PHP Extension Community Library', 'pecl.php.net', '');
installroot) VALUES(3, 1, 'PHP Extension and Application Repository, QA channel', 'qa.pear.php.net', '');
Modify releases:
ALTER TABLE releases ADD channel INTEGER NOT NULL REFERENCES channels(id) default 1;
Modify packages:
ALTER TABLE packages ADD channel INTEGER NOT NULL REFERENCES channels(id) default 1;
UPDATE packages SET channel = 1 WHERE package_type = "pear";
UPDATE packages SET channel = 2 WHERE package_type = "pecl";
ALTER TABLE packages DROP package_type;
A package may only belong to a channel, and not to a sub-channel, and a release's channel may only belong to either its package's channel or a sub-channel of that channel.
Possible enhancements
---------------------
Allow local mirroring of channels. This should be described in a completely separate RFC.
<channel mirrors="PEAR">
<name>PEAR</name>
<source type="relpath">pear/</source>
<summary>Copy of PEAR repository as of 12-05-2003 on CD-ROM</summary>
</channel>
add packagelist.xml which is a listing of all packages in a source channel. It contains all the <package> tags for every release available in the channel (perhaps an abbreviated version with only the package name, summary, relative path to the .tgz, and dependencies to save space?)