Section 10.6. PEAR Commands
|
10.6. PEAR CommandsIn this section, you learn all the PEAR Installer commands for installation and maintenance of packages on your system. For each of the commands, you will have the output of pear help command, and a thorough explanation of every option the command offers. If you notice commands mentioned in some of the help text that you do not find covered here, those commands are used by PEAR package maintaners during development. The development commands are covered in Chapter 12. 10.6.1. pear installThis command takes the content of a package file and installs files in your designated PEAR directories. You may specify the package to install as a local file, just the package name or as a full HTTP URL. Here's the help text for pear install: $ pear help install pear install [options] <package> ... Installs one or more PEAR packages. You can specify a package to install in four ways: "Package-1.0.tgz" : installs from a local file "http://example.com/Package-1.0.tgz" : installs from anywhere on the net. "package.xml" : installs the package described in package.xml. Useful for testing, or for wrapping a PEAR package in another package manager such as RPM. "Package" : queries your configured server (pear.php.net) and downloads the newest package with the preferred quality/state (stable). More than one package may be specified at once. It is ok to mix these four ways of specifying packages. Options: -f, --force will overwrite newer installed packages The -force option lets you install the package even if the same release or a newer release is already installed. This is useful for repairing broken installs, or during testing. -n, --nodeps ignore dependencies, install anyway Use this option to ignore dependencies and pretend that they are already installed. Use it only if you understand the consequences, the installed package may not work at all. -r, --register-only do not install files, only register the package as installed The -register-only option makes the installer list your package as installed, but it does not actually install any files. The purpose of this is to make it possible for non-PEAR package managers to also register packages as installed in the PEAR package registry. For example, if you install DB (the PEAR database layer) with an RPM, all the files are installed and you can use it, but the pear list command does not show that it is installed because RPM does not (by default) update the PEAR package registry. But, if the RPM package has a post-install command that runs pear -register-only package.xm, the package will be registered, both from RPM's and PEAR's point of view. -s, --soft soft install, fail silently, or upgrade if already installed This option is another way of saying, "Please give me the latest version of this package." If the package is not installed already, it will be installed. If the package is installed but you are specifying a package tarball with a newer package, or the latest online version is newer, the package will be upgraded. The difference between pear install -s and pear upgrade is that upgrade upgrades only if the package is already installed. -B, --nobuild don't build C extensions If you are installing a package that is a mix of PHP and C code and don't want to build and install the C code, or you simply want to test-install a package with C code, use -nobuild. -Z, --nocompress request uncompressed files when downloading If your PHP build does not include the zlib extension, PHP cannot uncompress gzipped package files. The installer detects this automatically, and will download non-gzipped packages when necessary. But, if this detection doesn't work, you can override it with the -nocompres option. -R DIR, --installroot=DIR root directory used when installing files (ala PHP's INSTALL_ROOT) This option is useful when you are installing PEAR packages from a script or using another package manager. All file names created by the installer will have DIR prepended. --ignore-errors force install even if there were errors If there are errors in a package and the installer refuses to go ahead and install it, you can use the ignore-errors option to force installation. There is a risk of an inconsistent install when using this option, so use it with care! -a, --alldeps install all required and optional dependencies Use this option to automatically download and install any dependencies. -o, --onlyreqdeps install all required dependencies Some packages have optional dependencies, which means a dependency that exists to use optional features of the package. If you want to satisfy all the dependencies, but don't need the optional features, use this option. Here are some examples of typical use. First, a plain example installing a package with no dependencies: $ pear install Console_Table downloading Console_Table-1.0.1.tgz ... Starting to download Console_Table-1.0.1.tgz (3,319 bytes) ....done: 3,319 bytes install ok: Console_Table 1.0.1 Here is an example of installing a package with many optional dependencies, but pulling only the packages that are required: $ pear install o HTML_QuickForm downloading HTML_Progress-1.1.tgz ... Starting to download HTML_Progress-1.1.tgz (163,298 bytes) ...................................done: 163,298 bytes skipping Package 'html_progress' optional dependency 'HTML_CSS' skipping Package 'html_progress' optional dependency 'HTML_Page' skipping Package 'html_progress' optional dependency 'HTML_QuickForm' skipping Package 'html_progress' optional dependency 'HTML_QuickForm_Controller'skipping Package 'html_progress' optional dependency 'Config' downloading HTML_Common-1.2.1.tgz ... Starting to download HTML_Common-1.2.1.tgz (3,637 bytes) ...done: 3,637 bytes install ok: HTML_Common 1.2.1 Optional dependencies: package 'HTML_CSS' version >= 0.3.1 is recommended to utilize some features. package 'HTML_Page' version >= 2.0.0RC2 is recommended to utilize some features.package 'HTML_QuickForm' version >= 3.1.1 is recommended to utilize some features. package 'HTML_QuickForm_Controller' version >= 0.9.3 is recommended to utilize some features. package 'Config' version >= 1.9 is recommended to utilize some features. install ok: HTML_Progress 1.1 Finally, this example installs a package and all dependencies, looking for releases of beta or better quality: $ pear d preferred_state=beta install a Services_Weather downloading Services_Weather-1.2.2.tgz ... Starting to download Services_Weather-1.2.2.tgz (29,205 bytes) .........done: 29,205 bytes downloading Cache-1.5.4.tgz ... Starting to download Cache-1.5.4.tgz (30,690 bytes) ...done: 30,690 bytes downloading HTTP_Request-1.2.1.tgz ... Starting to download HTTP_Request-1.2.1.tgz (12,021 bytes) ...done: 12,021 bytes downloading SOAP-0.8RC3.tgz ... Starting to download SOAP-0.8RC3.tgz (67,608 bytes) ...done: 67,608 bytes downloading XML_Serializer-0.9.2.tgz ... Starting to download XML_Serializer-0.9.2.tgz (12,340 bytes) ...done: 12,340 bytes downloading Net_URL-1.0.11.tgz ... Starting to download Net_URL-1.0.11.tgz (4,474 bytes) ...done: 4,474 bytes downloading Mail_Mime-1.2.1.tgz ... Starting to download Mail_Mime-1.2.1.tgz (15,268 bytes) ...done: 15,268 bytes downloading Net_DIME-0.3.tgz ... Starting to download Net_DIME-0.3.tgz (6,740 bytes) ...done: 6,740 bytes downloading XML_Util-0.5.2.tgz ... Starting to download XML_Util-0.5.2.tgz (6,540 bytes) ...done: 6,540 bytes install ok: Mail_Mime 1.2.1 install ok: Net_DIME 0.3 install ok: XML_Util 0.5.2 install ok: Net_URL 1.0.11 install ok: XML_Serializer 0.9.2 install ok: HTTP_Request 1.2.1 install ok: Cache 1.5.4 install ok: SOAP 0.8RC3 install ok: Services_Weather 1.2.2 10.6.2. pear listThe pear list command lists the contents of either your package registry or a single package. First, let's list the currently installed packages to see how the Date package is doing: INSTALLED PACKAGES: =================== PACKAGE VERSION STATE Archive_Tar 1.1 stable Cache 1.4 stable Console_Getopt 1.2 stable Console_Table 1.0.1 stable DB 1.6.3 stable Date 1.4.2 stable HTTP_Request 1.2.1 stable Log 1.2 stable Mail 1.1.2 stable Mail_Mime 1.2.1 stable Net_DIME 0.3 beta Net_SMTP 1.2.6 stable Net_Socket 1.0.2 stable Net_URL 1.0.11 stable PEAR 1.3.1 stable PHPUnit2 2.0.0beta1 beta SOAP 0.8RC3 beta XML_Parser 1.1.0 stable XML_RPC 1.1.0 stable XML_Serializer 0.9.2 beta XML_Util 0.5.2 stable To inspect the contents of the recently installed Date package, use the list command: $ pear list Net_Socket INSTALLED FILES FOR NET_SOCKET ============================== TYPE INSTALL PATH php /usr/local/lib/php/Net/Socket.php This package contains only php files. The PEAR package contains different types of files. The following example also illustrates how "data" files are installed with the package name as part of the file path: $ pear list PEAR INSTALLED FILES FOR PEAR ======================== TYPE INSTALL PATH data /usr/local/lib/php/data/PEAR/package.dtd data /usr/local/lib/php/data/PEAR/template.spec php /usr/local/lib/php/PEAR.php php /usr/local/lib/php/System.php php /usr/local/lib/php/PEAR/Autoloader.php php /usr/local/lib/php/PEAR/Command.php php /usr/local/lib/php/PEAR/Command/Auth.php php /usr/local/lib/php/PEAR/Command/Build.php php /usr/local/lib/php/PEAR/Command/Common.php php /usr/local/lib/php/PEAR/Command/Config.php php /usr/local/lib/php/PEAR/Command/Install.php php /usr/local/lib/php/PEAR/Command/Package.php php /usr/local/lib/php/PEAR/Command/Registry.php php /usr/local/lib/php/PEAR/Command/Remote.php php /usr/local/lib/php/PEAR/Command/Mirror.php php /usr/local/lib/php/PEAR/Common.php php /usr/local/lib/php/PEAR/Config.php php /usr/local/lib/php/PEAR/Dependency.php php /usr/local/lib/php/PEAR/Downloader.php php /usr/local/lib/php/PEAR/ErrorStack.php php /usr/local/lib/php/PEAR/Frontend/CLI.php php /usr/local/lib/php/PEAR/Builder.php php /usr/local/lib/php/PEAR/Installer.php php /usr/local/lib/php/PEAR/Packager.php php /usr/local/lib/php/PEAR/Registry.php php /usr/local/lib/php/PEAR/Remote.php php /usr/local/lib/php/OS/Guess.php script /usr/local/bin/pear php /usr/local/lib/php/pearcmd.php 10.6.3. pear infoThe pear info command displays information about an installed package, a package tarball, or a package definition (XML) file. This example shows the information about the XML-RPC package: $ pear info XML_RPC About XML_RPC-1.1.0 =================== Provides Classes: Package XML_RPC Summary PHP implementation of the XML-RPC protocol Description This is a PEAR-ified version of Useful inc's XML-RPC for PHP. It has support for HTTP transport, proxies and authentication. Maintainers Stig S?ther Bakken <stig@php.net> (lead) Version 1.1.0 Release Date 2003-03-15 Release License PHP License Release State stable Release Notes - Added support for sequential arrays to XML_RPC_encode() (mroch) - Cleaned up new XML_RPC_encode() changes a bit (mroch, pierre) - Remove "require_once 'PEAR.php'", include only when needed to raise an error - Replace echo and error_log() with raiseError() (mroch) - Make all classes extend XML_RPC_Base, which will handle common functions (mroch) - be tolerant of junk after methodResponse (Luca Mariano, mroch) - Silent notice even in the error log (pierre) - fix include of shared xml extension on win32 (pierre) Last Modified 2004-05-03 If you have downloaded a package file (.tgz file), you may also run pear info on it to display information about the contents without installing the package first; for example: $ pear info XML-RPC-1.1.0.tgz You can even specify a full URL to a package you want to view: $ pear info http://www.example.com/packages/Foo_Bar-4.2.tgz See also the remote-info command. 10.6.4. pear list-allWhile pear list displays all the packages installed on your system, pear list-all displays an alphabetically sorted list of all packages with the latest stable version, and which version you have installed, if any. The full output of this command is long because it lists every package that has a stable release. ALL PACKAGES: ============= PACKAGE LATEST LOCAL APC 2.0.3 Cache 1.5.4 1.4 Cache_Lite 1.3 apd 0.4p2 ...truncated... XML_Transformer 1.0.1 XML_Tree 1.1 XML_Util 0.5.2 0.5.2 PHPUnit2 2.0.0beta1 Net_DIME 0.3 XML_Serializer 0.9.2 SOAP 0.8RC3 10.6.5. pear list-upgradesThe pear list-upgrades command compares the version you have installed containing the newest version with the release state you have configured (see the preferred_state configuration parameter). Here's an example: $ pear list-upgrades AVAILABLE UPGRADES (STABLE): ============================ PACKAGE LOCAL REMOTE SIZE Cache 1.4 (stable) 1.5.4 (stable) 30kB DB 1.6.3 (stable) 1.6.4 (stable) 90kB Log 1.2 (stable) 1.8.4 (stable) 29kB Mail 1.1.2 (stable) 1.1.3 (stable) 13.2kB The version listed here is not the one you have installed, but the one you will upgrade to if you use the upgrade command. 10.6.6. pear upgradeThe pear upgrade command replaces one or more installed packages with a newer release, if a newer release can be found. As with many other commands taking a package argument, you may refer to the package just by name, the URL or name of a tarball, or the URL or name of a package description (XML) file. This section only demonstrates specifying the package by name because that is by far the most common usage. In the list-upgrades example, you saw a few packages where newer releases were available. Upgrade the Log package: $ pear upgrade Log downloading Log-1.8.4.tgz ... Starting to download Log-1.8.4.tgz (29,453 bytes) .........done: 29,453 bytes Optional dependencies: 'sqlite' PHP extension is recommended to utilize some features upgrade ok: Log 1.8.4 The upgrade command has the same options as the install command, with the exception that the S / --soft option is missing. The options are listed here; refer to the install command, shown previously, for a more detailed description. $ pear help upgrade pear upgrade [options] <package> ... Upgrades one or more PEAR packages. See documentation for the "install" command for ways to specify a package. When upgrading, your package will be updated if the provided new package has a higher version number (use the -f option if you need to upgrade anyway). More than one package may be specified at once. Options: -f, --force overwrite newer installed packages -n, --nodeps ignore dependencies, upgrade anyway -r, --register-only do not install files, only register the package as upgraded -B, --nobuild don't build C extensions -Z, --nocompress request uncompressed files when downloading -R DIR, --installroot=DIR root directory used when installing files (ala PHP's INSTALL_ROOT) --ignore-errors force install even if there were errors -a, --alldeps install all required and optional dependencies -o, --onlyreqdeps install all required dependencies 10.6.7. pear upgrade-allFor your convenience, the upgrade-all command provides a combination of the list-upgrades and upgrade commands, upgrading every package that has a newer release available. The command-line options available are -n, --nodeps ignore dependencies, upgrade anyway -r, --register-only do not install files, only register the package as upgraded -B, --nobuild don't build C extensions -Z, --nocompress request uncompressed files when downloading -R DIR, --installroot=DIR root directory used when installing files (ala PHP's INSTALL_ROOT) --ignore-errors force install even if there were errors See the install command for a description of each of these options. If you have followed the examples in this chapter, you have still not upgraded three out of the four packages that list-upgrades reported as having newer releases. Upgrade them all at once like this: $ pear upgrade-all Will upgrade cache Will upgrade db Will upgrade mail downloading Cache-1.5.4.tgz ... Starting to download Cache-1.5.4.tgz (30,690 bytes) .........done: 30,690 bytes downloading DB-1.6.4.tgz ... Starting to download DB-1.6.4.tgz (91,722 bytes) ...done: 91,722 bytes downloading Mail-1.1.3.tgz ... Starting to download Mail-1.1.3.tgz (13,415 bytes) ...done: 13,415 bytes upgrade-all ok: Mail 1.1.3 upgrade-all ok: DB 1.6.4 upgrade-all ok: Cache 1.5.4 Optional dependencies: 'sqlite' PHP extension is recommended to utilize some features upgrade-all ok: Log 1.8.4 10.6.8. pear uninstallTo delete a package, you must uninstall it. Here's an example: $ pear uninstall Cache Warning: Package 'services_weather' optionally depends on 'Cache' uninstall ok: Cache The uninstall command has three options: pear uninstall [options] <package> ... Uninstalls one or more PEAR packages. More than one package may be specified at once. Options: -n, --nodeps ignore dependencies, uninstall anyway -r, --register-only do not remove files, only register the packages as not installed -R DIR, --installroot=DIR root directory used when installing files (ala PHP's INSTALL_ROOT) --ignore-errors force install even if there were errors These options all correspond to the same options to the install command. 10.6.9. pear searchIf you want to install a package but don't remember what it was called, or just wonder if there is a package that does X, you can search for it with the pear search command, which does a substring search in package names. Here's an example: $ pear search xml MATCHED PACKAGES: ================= PACKAGE LATEST LOCAL XML_Beautifier 1.1 Class to format XML documents. XML_CSSML 1.1 The PEAR::XML_CSSML package provides methods for creating cascading style sheets (CSS) from an XML standard called CSSML. XML_fo2pdf 0.98 Converts a xsl-fo file to pdf/ps/pcl text/etc with the help of apache-fop XML_HTMLSax 2.1.2 A SAX based parser for HTML and other badly formed XML documents XML_image2svg 0.1 Image to SVG conversion XML_NITF 1.0.0 Parse NITF documents. XML_Parser 1.1.0 1.1.0 XML parsing class based on PHP's bundled expat XML_RSS 0.9.2 RSS parser XML_SVG 0.0.3 XML_SVG API XML_Transformer 1.0.1 XML Transformations in PHP XML_Tree 1.1 Represent XML data in a tree structure XML_Util 0.5.2 0.5.2 XML utility class. XML_RPC 1.1.0 1.1.0 PHP implementation of the XML-RPC protocol The output is displayed in four columns: package name, latest version available online, locally installed version (or blank if you do not have that package installed), and a short description. 10.6.10. pear remote-listThis command displays a list of all packages and stable releases that are available in the package repository: $ pear remote-list AVAILABLE PACKAGES: =================== PACKAGE VERSION APC 2.0.3 apd 0.4p2 Archive_Tar 1.1 Auth 1.2.3 Auth_HTTP 2.0 Auth_PrefManager 1.1.2 Auth_RADIUS 1.0.4 Auth_SASL 1.0.1 Benchmark 1.2.1 bz2 1.0 Cache 1.5.4 ... The difference from list-all is that remote-list only shows the last available version, while list-all also shows which releases you have installed. This command obeys your preferred_state configuration setting, which defaults to stable. All the packages and releases in the output of the previous example are tagged as stable. You may temporarily set preferred_state for just one command. The following example shows all packages that are of alpha quality or better: $ pear d preferred_state=alpha remote-list AVAILABLE PACKAGES: =================== PACKAGE VERSION APC 2.0.3 apd 0.4p2 Archive_Tar 1.1 Archive_Zip 0 Auth 1.2.3 Auth_Enterprise 0 Auth_HTTP 2.1.0RC2 Auth_PrefManager 1.1.2 Auth_RADIUS 1.0.4 Auth_SASL 1.0.1 bcompiler 0.5 Benchmark 1.2.1 bz2 1.0 ... As you can see, some new packages showed up: Archive_Zip, and Auth_Enterprise (which did not have any releases at all at this point), and bcompiler 0.5. 10.6.11. pear remote-infoTo display detailed information about a package you have not installed, use the pear remote-info command. $ pear remote-info apc PACKAGE DETAILS: ================ Latest 2.0 Installed - no - ackage APC License PHP Category Caching Summary Alternative PHP Cache Description APC is the Alternative PHP Cache. It was conceived of to provide a free, open, and robust framework for caching and optimizing PHP intermediate code. The package description shown by the remote-info command is taken from the newest release of the package. 10.6.12. pear downloadThe pear install command does not store the package file it downloads anywhere. If all you want is the package tarball (for installing later or something else), you can use the pear download command: $ pear download DB File DB-1.3.tgz downloaded (59332 bytes) By default, you will receive the latest release matching your preferred_state configuration parameter. If you want to download a specific release, give the full file name instead: $ pear download DB-1.2.tgz File DB-1.2.tgz downloaded (58090 bytes) Tip If you don't have the zlib PHP extension built in, use the -Z or --nocompress option to download .tar files. 10.6.13. pear config-getAs you have already seen, the pear config-get command is used to display a configuration parameter: $ pear config-get php_dir php_dir=/usr/share/pear If you do not specify a layer, the value is read from the first layer that defines it (in the order user, system, default). You may also specify a specific configuration layer from where you want to get the value: $ pear config-get http_proxy system system.http_proxy=proxy.example.com:3128 10.6.14. pear config-setThe pear config-set command changes a configuration parameter: $ pear config-set preferred_state beta By default, the change is performed in the user configuration layer. You may specify the configuration layer with an additional parameter: $ pear config-set preferred_state beta system (You need write access to the system configuration file for this to have any effect.) 10.6.15. pear config-showThe pear config-show command is used to display all configuration settings, treating layers just like the config-get command. $ pear config-show CONFIGURATION: ============== PEAR executables directory bin_dir /usr/local/bin PEAR documentation directory doc_dir /usr/local/lib/php/doc PHP extension directory ext_dir /usr/local/lib/php/ extensions/no-debug-non-zts-20040316 PEAR directory php_dir /usr/local/lib/php PEAR Installer cache directory cache_dir /tmp/pear/cache PEAR data directory data_dir /usr/local/lib/php/data PHP CLI/CGI binary php_bin /usr/local/bin/php PEAR test directory test_dir /usr/local/lib/php/test Cache TimeToLive cache_ttl 3600 Preferred Package State preferred_state stable Unix file mask umask 22 Debug Log Level verbose 1 HTTP Proxy Server Address http_proxy <not set> PEAR server master_server pear.php.net PEAR password (for password <not set> maintainers) Signature Handling Program sig_bin /usr/bin/gpg Signature Key Directory sig_keydir /usr/local/etc/pearkeys Signature Key Id sig_keyid <not set> Package Signature Type sig_type gpg PEAR username (for username <not set> maintainers) Tip By adding an extra parameter (user or system), you can view the contents of a specific configuration layer. 10.6.16. ShortcutsEvery command in the PEAR Installer may specify a command-line shortcut, just to save people from typing. Type pear help shortcuts to see them: $ pear help shortcuts Shortcuts: li login lo logout b build csh config-show cg config-get cs config-set ch config-help i install up upgrade ua upgrade-all un uninstall bun bundle p package pv package-validate cd cvsdiff ct cvstag rt run-tests pd package-dependencies si sign rpm makerpm l list st shell-test in info ri remote-info lu list-upgrades rl remote-list sp search la list-all d download cc clear-cache da download-all Instead of pear config-set foo=bar, you may type pear cs foo=bar, or pear pd instead of pear package-dependencies. |
|
EAN: 2147483647
Pages: 240