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