CHAPTER 10 – PEAR COMMANDS

In 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.

pear install This command takes the content of a package file and installs files in your des- ignated 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 pack- age 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 pack- age 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 pack- age 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 depen- dency 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 dependen- cies, 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