Re: more bundle identification possibilities

Cipriano Groenendal wrote:

Greg, After reading all the recent mails on bundles and subpackages, I am confused. Could you explain the difference between the bundles and subpackages, and the relationship between bundles and packages? If I think of bundles, I picture something like say, Auth + The complete set of dependancies, or something else fun like say, Mail_IMAP + Net_IMAP, or maybe even PEAR::Text_Wiki + CIAWEB::YAWP (Hi Paul!). To me, right now, Bundles sound like a quick way to define a set of packages that don't depend on each other, but can work together nicely. As such, cross-channel connections would be nice to have, me thinks.

This is why I post questions to the list before coding :). It's always insightful to catch other perspectives and be forced to clarify my thinking, and it will definitely help the documentation when this is all in between <?php and ?>. Before I begin, some basic assumptions you should know about: - PEAR 1.4.0 will allow dependencies on other channels - all ways of doing things now are fully supported in the new package.xml, you don't *have* to change any of your ways, just the contents of the package.xml - PEAR 1.4.0 already provides both an xsl script and a php-based way to convert your package.xml version 1.0 into a version 2.0 package.xml format. - package.xml 2.0 format is not set in stone, it's too new for that kind of stability. Stupid things can be changed. - there has been some discussion on pear-core about the contents of package.xml 2.0, but not much. It's 99% my work, which makes it automatically suspect until others review it :). - I use "#" as the bundle separator only for consistency, I'll use whatever consensus decides is best (but may make the final call if there is no consensus, since I'm writing the code - I promise this is last resort) The best way to start is to examine the problems that exist, and how they have been solved if they are now, and how I hope to solve some of them better with these things I've been calling bundles. ## Problem (1) "My package X can optionally use package Y if the user has it installed, but doesn't need it" Solution: optional dependency as it exists now is perfect for this simple case ## Problem (1.5) "My package X can optionally use package Y if the user has it installed, but if it isn't present, must use a totally different file with the same API in place of the standard file that uses package Y *and* speed is important so I can't do an 'if (is_installed(package))'" -or- "My package can work in both PHP4 and PHP5 with the same API, but the changes require different files to avoid parse errors" -or- "My package needs different installations for different operating systems" etc. Solution: in package.xml 1.0, the filelist is tied to a release. In package.xml 2.0, the filelist is tied to the archive, and separate releases can be defined. They are differentiated only by their required dependencies. In pseudo-package.xml XML: <package> <filelist><files_in_archive/></filelist> <!-- this is a package containing php code, as opposed to <extsrc> or <extbin> --> <php> <!-- this release is only installed if package Y is installed --> <dependencies> <package name="Y" recommended="1.5" min="1.2"/> </dependencies> <filelist> <ignorefile name="SimulatesY.php"/> </filelist> </php> <php> <!-- this release is only installed if package Y is not installed --> <dependencies> <package name="Y" recommended="1.5" min="1.2"/> </dependencies> <filelist> <file name="SimulatesY.php" install-as "usesY.php"/> <ignorefile name="usesY.php"/> </filelist> </php> </package> This is not the best example of the need for multiple releases in a single package.xml. extension binary packages could include binaries for different OSes, and using an OS dependency, install the correct binary. In this way, binaries can be distributed in one archive for an application, for instance, making it cross-platform. ## Problem (2) "My package X can be used in two different ways, gronk and foo. Gronk requires pear::Net_URL, foo requires otherchannel::URLPackage. Both ways require package Z, but each way has the same API" Solution: an optional dependency is not fully adequate, as the dependency is not really optional, it is either necessary or unneeded. I want a system of defining these dependencies more sufficiently. This is one use of package-specific bundles $ pear install X#gronk install package pear::X OK installing bundle gronk: pear::Net_URL already installed installing package pear::X_gronk installing package pear::Z $ pear install X#foo pear::X already installed installing bundle foo: install otherchannel::URLPackage OK pear::Z already installed $ pear uninstall X uninstall of pear::X OK $ pear install X install of pear::X OK $ pear uninstall pear::X#foo uninstall of pear::X OK uninstalling contents of bundle foo: uninstall of otherchannel::URLPackage OK uninstall of pear::Z OK This hypothetical example doesn't apply to PEAR, as I'm sure we won't allow dependencies on outside packages, but it does apply to every other channel. ## Problem (2.5) "My package X has a subpackage that is required for basic operation, but is a separate, much smaller entity (think Console_Getopt and PEAR) that should have its own release cycle. If this smaller entity breaks BC, it screws the major package" Solution: there is no solution in package.xml 1.0 except to not allow it to be a separate package. In package.xml 2.0, you can create a default bundle that will be installed when the user types: $ pear install PEAR-1.5.0 install of PEAR 1.5.0 OK install of Console_Getopt 1.2 OK <bundle name="default"> <package name="Console_Getopt" recommended="1.2"/> </bundle> version 1.2 will be installed unless there is a newer version that *explicitly* states in Console_Getopt's package.xml that installing with PEAR 1.5.0 is OK. If a newer version of Console_Getopt is already installed, installation of PEAR would fail without --force. ## Problem (3) "My package X is a server-style model, with a central class and lots of external sub-packages that require the main X server (think phpDocumentor, DB, etc.). I want to split up the package into separate modules, and develop them independently." Solution: no solution in package.xml 1.0. In 2.0, the default bundle can again be used to install all of the subpackages as it does not for DB and phpDocumentor. Then, smaller bundles can be created. phpDocumentor, for instance, would likely define these bundles: core (no converters or templates) minimal (HTMLSmartyConverter and the HandS template, possibly) allSmartyTemplates (speaks for itself) HTMLframes (HTMLframesConverter and all templates) PDF CHM and bundles for each template This would allow commands like $ pear install pear::PhpDocumentor#core thirdparty::PhpDocumentor_CustomConverter and unlimited variations. ## Problem (4) "These packages work well together, and could be used to develop customized websites very quickly, I'd like to get a set of releases that have been certified as compatible" -or- "These packages all have won the uber-PHP award" -or- "Every XML developer should have a set of these packages" etc. Solution: independent of the packages, a special bundle.xml should be created to handle these bundles of separate packages. I hope this clarifies, at the very least, some of the larger problems I've been wrestling with. Package-specific bundles can contain subpackages, or just custom configuration packages, like the packages needed for the web installer of PEAR. Perhaps we could call the unrelated things "bundles" and the package-specific ones "install sets" <installset name="default"> <package name="Console_Getopt" recommended="1.2" min="1.1"/> <installset> Greg