| ActivePerl User Guide |

# Using PPM to install modules

- NAME
- DESCRIPTION
  - What is the PPM?
  - How do I install PPM?
  - How do I run PPM?
  - How do I use PPM?
  - PPM Commands
  - Where are the package repositories?
  - How do I make a PPM package?
  - PPM, Proxies and Firewalls
- AUTHOR AND COPYRIGHT

## NAME

Using PPM to install modules

## DESCRIPTION

How to install and upgrade modules using PPM

## What is the PPM?

The Programmer's Package Manager (PPM), formerly known as the Perl Package Manager, provides a command line interface for managing your modules and extensions (packages). PPM is used to access package repositories (or collections of packages on other machines), install and remove packages from your system, as well as update previously installed packages with the latest versions.

The PPM 3.0 release introduces a complete rewrite of PPM, featuring many additions and improvements.

## How do I install PPM?

PPM (`ppm`) is installed when you install ActivePerl.

## How do I run PPM?

Before you run PPM , you must either be connected to the Internet or have access to a local repository, like a hard drive or the ActiveState ActiveCD. If your Internet connection is via a firewall or proxy, you must set the environment variable "HTTP_proxy" to the name of the proxy server. If your proxy server requires a username and password, use the environment variables "HTTP_proxy_user" and "HTTP_proxy_pass". See PPM, Proxies and Firewalls for more information.

To run PPM, enter `ppm` in a command prompt window (Windows), or at the shell prompt (Linux / Solaris).

## How do I use PPM?

Quick start: at the PPM command prompt, type `search *` to get a listing of all available packages, then type `install <package name>`, where <`package name`> is the name of a package displayed by the `search` command. To list the packages you have previously installed using PPM, use the `query *` command.

Those using PPM can type `search` to get a listing of all available packages, then type `install <packagename>`, where `<packagename>` is the name of a package displayed by the `search` command. To list the packages you have previously installed using PPM, use the `query` command.

> Note to PPM users: If you find the listing of packages scrolls by too quickly, you may want to use the command `set more <number>` to pause the listing after <number> packages have been displayed. Use the `set save` command to save this configuration for future PPM sessions.

The first time you run PPM, the ActiveState package repository will be your default repository. If you change your default repository, that change will be saved. You can can select a different repository with the repository command. See Where are the package repositories? below.

## PPM Commands

Items in <angle brackets> are arguments that can be used with the commands, while items in [square brackets] are optional elements. PPM will recognize and accept shortened versions of the commands, as long as enough letters are typed to be recognized by PPM. For example, "des" can be typed instead of "describe".

### Describe

> describe |  | Describes default/current package
> describe <number> |  | Describes package <number> in the current search set
> describe <range> |  | Describes packages in the given <range> from the current search set
> describe <package name> |  | Describes named package
> describe <url> |  | Describes package located at <url>
> describe <glob pattern> |  | Performs a new search using <glob pattern>

When used, `describe` returns information about a package, including the name of the package, the author's name and a brief description (called an "Abstract") about the package. For example, when you enter:

>     describe libnet

returns:

>     ===============================
>     Package 1
>         Name: libnet
>      Version: 1.07.03
>       Author: Graham Barr
>     Abstract: Collection of Network protocol modules
>     Implementations:
>     	1.sun4-solaris-thread-multi
>     	2.i686-linux-thread-multi
>     	3.MSWIn32-x86-multi-thread
>     ===============================

There are two modifiers to the describe command:

> -ppd |  | Displays the raw PPD of the package.
> -dump |  | The same as -ppd.

When the `describe` command is called without arguments, it returns information about the first package in the current search. If there is no default search set, you'll be prompted to use search to find a package.

If `describe` is called with a numeric argument, that number is set as the default package and the information about that package is returned. If the number given doesn't exist, you'll be prompted to use search to find a package. Also, you can use `describe` to give descriptions of several packages. For example:

>     describe 4-7

will give you descriptions of packages 4 through 7, in the current search request. You can also enter:

>     describe 3-4,10

to get information on packages 3, 4 and 10.

If you specify a URL as the argument to describe, PPM will describe the package located at the URL. The URL must point to a PPD file. The URL can also point to a PPD file on your computer.

When the `describe` command is given a name with a wildcard (such as "*" or "?") it executes the `search` command with the given argument. With this, you can type something like `describe Tk*` will return the name(s) of any packages that match your search parameters.

See Also: Properties

### Exit

> exit |  | Exit
> quit |  | Exit
> q |  | Exit
> q <query> |  | Perform a new query (shortcut for query)

When you leave the PPM environment, the current settings are saved.

See Also: Quit

### Help

> help |  | Lists available commands and help topics
> help <command> |  | Lists detailed help about a specific command

The `help` command provides a brief description of the commands available within PPM. For help on a specific command, enter `help` followed by the command name. For example, enter `help settings` or `help set` for a detailed description of the settings command.

There are some extra help topics built into PPM. They can be accessed within the PPM environment as follows:

> HELP COMMAND |  | DESCRIPTION |
> help ppm_migration |  | shows more details about the changes from previous versions of PPM
> help quickstart |  | an easy-to-follow guide to getting started with PPM
> help prompt |  | provides a detailed explanation about the PPM prompt

### Install

> install |  | Installs default package |
> install <number> |  | Installs packages by a specific <number>
> install <range> |  | Installs packages in the given numeric range <range>.
> install <name> |  | Installs named package
> install <url> |  | Installs the package located at <url>

The `install` command is used to install packages from the repository. You can install packages by name or number (the number is given by the repository or search request), or a default package can be established through use of the `describe` command. There is also a set of modifiers that can be used with the install command:

The `install` command is used to install packages from the repository. Install packages by name or number (the number is given by the repository or search request), or set a default package using the `describe` command. You can specify a full URL to a PPD file; the URL may point to a PPD file on your computer.

If you have profile tracking enabled, (see 'help profile') the current profile will be updated to include the newly installed package(s).

The following modifiers can be used with the install command:

>     -force  -noforce
>     -follow -nofollow

The `force` and `follow` commands determine how packages are installed:

> FORCE |  | FOLLOW |  | RESULT
> false |  | false |  | Checks to see if the package is installed and if it is, installation stops. If there are any missing prerequisites, the installation will fail.
> false |  | true |  | Checks to see if the package is installed and if it is, installation stops. If there are any missing prerequisites, they are automatically installed. NOTE: this is the default setting when PPM is first installed.
> true |  | false |  | If the package is installed, PPM will reinstall the package. If there are any missing prerequisites, the installation will fail.
> true |  | true |  | If the package is installed, PPM will reinstall the package. All prerequisites are installed, missing or not.

If you do not specify any options, install uses the default settings. Set or view the current defaults using the settings command.

For example:

>     install foo

will install the package named "foo", using the default settings. Over-ride the defaults using the install modifiers described above.

For example:

>     install foo -force

will install the "foo" package, even if it has already been installed. If both `-force` and `-follow` are set to "true", all the prerequisites for any package you install will also be installed. For example, the installation of a tk-related package, like "tk-ach" which is 8.4 kB will be preceded by the installation of Tk, which is 1.7 MB.

You can also install by package number. Package numbers are based on the current repository or current search request. For example:

>     install 6

installs package number 6. You can install more than one package at one time:

>     install 3-5

installs packages 3, 4 and 5. You can also type `install 3-6,8` to receive packages 3,4,5,6 and 8.

### Profile

> profile |  | Lists profiles available on the repository
> profile <num> |  | Switches to the given profile
> profile add <name> |  | Creates a new profile on the repository
> profile delete <name or num> |  | Deletes the given profile
> profile describe [name or num] |  | Describes the current or given profile
> profile save |  | Saves the client state to the current profile
> profile restore |  | Restores the current profile
> profile rename <name or num> <name> |  | Renames the given profile to <name>

Profiles store information about packages that are installed on your system. If the `profile-track` setting is enabled, your ASPN Profile will be updated with information about installed packages. Profiles allow you to easily migrate, reinstall, upgrade or restore PPM packages in one or more locations.

To use profiles, you must have a license for ASPN Perl. For license information, see the ASPN Perl web site. Disable profile tracking by setting `profile-track=0`.

### Properties

> prop |  | Describes default installed package
> prop <number> |  | Describes installed package <number>
> prop <range> |  | Describes a <range> of installed package
> prop <package name> |  | Describes named installed package
> prop <url> |  | Describes installed package located at <url>
> prop <glob pattern> |  | Performs a new query using <glob pattern>

The `properties` command is an verbose form of the describe command. In addition to summary information, properties will display the installation date and a URL showing the location of the package within the repository.

If you specify the package as a URL, PPM determines the package name from the URL and searches for that.

When the `properties` command is used with wildcard arguments, the text entered at the PPM prompt is passed to the query command.

For example, typing `properties libnet` will give you:

>         Name: libnet
>      Version: 1.07.03
>       Author: Graham Barr
>     Abstract: Collection of Network protocol modules
>     InstDate: Fri Oct  2 16:15:15 1998
>     Location: http://ppm.ActiveState.com/cgibin/PPM/ppmserver.pl?urn:/PPMServer

See Also: Describe

### Query

> query |  | Displays list of previous queries
> query <number> |  | Displays results of previous query
> query <glob pattern> |  | Performs a new query using <glob pattern>
> query * |  | Displays a list of all installed packages

The query command displays a list of all installed packages, or a list based on the <glob pattern> switch. You can also check the list of past queries, or the results of a past query.

With PPM 3.1, you can now perform much more powerful queries. The syntax is identical to the search command, and almost all the search switches are also available for querying installed packages.

Recall previous queries with the `query <number>` command. PPM3 stores all queries from the current PPM session.

Note: Depending on the value of the "case-sensitivity" setting, the query may or may not be case-sensitive. See "help settings" for instructions on setting the default case sensitivity.

See Also: Settings

### Remove

> remove |  | Deletes default installed package
> remove <number> |  | Deletes installed package <number>
> remove <range> |  | Deletes a <range> of installed packages
> remove <name> |  | Deletes a package by a specific name
> remove <url> |  | Deletes the package located at <url>

The `remove` and `uninstall` commands function identically. They are used to delete packages from the current target (specified using the target command). If profile tracking is enabled, (see profile) the current PPM profile on ASPN will be updated.

Packages can be removed by package name, by their numerical listing, or by specifying a URL to a PPD file. For example:

>     remove XML-DOM

will delete the XML-DOM package from the target.

To remove package by number:

>     remove 6

and the sixth package in your current query will be removed. If no queries have been run in the current PPM session, you will be prompted to use a `query` to find a package before deleting it. Remember that removing packages clears all previous query requests, since the numerical sequence stored in any query will no longer be true once package(s) have been removed.

Packages can also be removed in groups. For example:

>     remove 4-7

will delete packages 4, 5, 6, and 7 from your target. You can also skip packages:

>     remove 3-5, 7

this will delete packages 3, 4, 5 and 7, but will leave 6 intact. Remember to run a new query whenever you remove a package from your target.

If you specify the package as a URL, PPM determines the package name from the URL and removes that.

Please note that wildcards like "*" or "?" cannot be used with the `remove` command.

### Repository

> rep |  | Displays all repositories
> rep add [name] <location> |  | Adds a new repository; makes it active
> rep delete <name or num> |  | Deletes specified repository
> rep describe <name or num> |  | Displays information about the specified repository
> rep rename <name or num> <name> |  | Renames the specified repository to the given name
> rep on <name> |  | Activates the specified repository
> rep off <name or num> |  | Removes the repository from the active list
> rep up <name or num> |  | Moves the specified repository up one
> rep down <name or num> |  | Moves the specified repository down one

The <name> needs to be put inside doublequotes if it contains any spaces.

The `repository` (or `rep`) command controls two lists or repositories:

1. The list of "active" repositories. This is the list of repositories used by search, install, and upgrade.

2. The list of all known repositories. You can designate a repository "inactive", which means PPM will not use it in any commands.

If no arguments are given, the `rep` command will list the active repositories defined in the PPM settings. The order is significant: when installing a package, PPM will try the first repository, then the second, and so on, until it find the package you asked for. When searching, PPM merges the results of all the repositories together, so the order is less important (see the search command).

For example, when you enter:

>     rep

PPM3 will return something resembling this:

>     Repositories:
>     [1] ActiveCD
>     [2] ActiveState Package Repository
>     [ ] An inactive repository

In the example above, entering `rep off 2` will disable the second repository (the ActiveStat Package Repository). To add another repository:

>     rep add [options]

The following options are available for the `add` command:

>     -username
>     -password

These options allow you to specify a username and password to be used when logging into a repository. Currently, these are only used for FTP and WWW repositories.

For example:

>     rep add "EZE" http://foo.com/MyPPMPackages

with "EZE" being the name of the repository (for easy reference) and the location noted by the http location. If you were to enter the rep command again, you would see:

>     ppm> rep
>     Repositories:
>     [1] ActiveCD
>     [2] ActiveState Package Repository
>     [3] EZE
>     [ ] An inactive repository

To move the new repository to the top of the Active list, you would type:

>     ppm> rep up EZE
>     Repositories:
>     [1] ActiveCD
>     [2] EZE
>     [3] ActiveState Package Repository
>     [ ] An inactive repository
>     ppm> rep up EZE
>     Repositories:
>     [1] EZE
>     [2] ActiveCD
>     [3] ActiveState Package Repository
>     [ ] An inactive repository

To disable the ActiveCD repository temporarily, enter the following:

>     ppm> rep off ActiveCD
>     Repositories:
>     [1] EZE
>     [2] ActiveState Package Repository
>     [ ] ActiveCD
>     [ ] An inactive repository

To describe a repository, refer to it either by name, or by the number displayed next to the repository in the Active Repositories list. You must refer to inactive repositories by their full name.

>     ppm> rep describe 2
>     Describing Active Repository 2:
>         Name: ActiveState Package Repository
>     Location: http://ppm.ActiveState.com/cgibin/PPM/...
>         Type: PPMServer 2.00
>     ppm> rep describe ActiveCD
>     Describing Inactive Repository:
>         Name: ActiveCD
>     Location: F:\PPMPackages\5.8plus
>         Type: Local Directory

To re-activate the ActiveCD repository, use the `rep on` command. You must refer to inactive repositories by name, not number.

>     ppm> rep on ActiveCD
>     Active Repositories:
>     [1] EZE
>     [2] ActiveState Package Repository
>     [3] ActiveCD
>     [ ] An inactive repository

PPM3 supports several types of package repositories:

1. PPM Server 3

   ActiveState's SOAP-driven package server. Because all searches are done server-side, the server can deliver much richer information about packages than other repositories.

2. PPM Server 2

   The SOAP server designed for PPM version 2. PPM 3.1 ships with the PPM2 repository as well as the PPM3 repository, so you can use either. Simple searches are performed server-side. If your search is too complicated for the server, PPM 3.1 will download the package summary and search by itself.

3. Web Repositories

   Older versions of PPM used non-SOAP repositories (directories full of PPD files accessible using a web browser). Over the history of PPM, there have been several different ways of organising the files so that PPM can search for packages properly. PPM3 tries to download a summary file first -- if that fails, it gets the directory index. It parses the summary or the index, and caches it. Searches are done from the cache.

4. FTP Repositories

   FTP is another way of exposing a directory full of PPD files. PPM3 consideres FTP repositories a subset of Web repositories. Treat them as identical: PPM3 downloads the summary or the "index" (file listing in this case), parses it, and then searches from it.

5. Local Repositories

   To support installing packages from the ActiveCD, a local directory can be a repository. PPM searches the files in the directory. All valid path formats are supported, including UNC paths.

### Search

> search |  | Displays list of previous searches
> search <number> |  | Displays results of search <number>
> search <glob pattern> |  | Performs a new search
> search <field>=<glob pattern> |  | Searches for all packages matching the field
> search * |  | Displays all packages in the current repository

The available fields are `ABSTRACT`, `NAME`, `TITLE`, `AUTHOR`, and `VERSION`. `NAME` is used when you do not specify a field.

Use the `search` command to look through the repository for packages. PPM provides powerful search functionality. For example:

> COMMAND |  | MEANING |  | SAMPLE RESULTS
> `search CGI` |  | Search for 'CGI' anywhere in the name |  | `Apache-CGI CGI-Application CGI-ArgChecker`
> `search CGI*` |  | Search for 'CGI' at beginning of name |  | `CGI-Application CGI-ArgChecker`
> `search AUTHOR=smith` |  | Search for all modules authored by someone with 'smith' in their name or email |  | `Apache-ProxyPass Business-ISBN`
> `search ABSTRACT=compress` |  | Search for 'compress' anywhere in the abstract |  | `Apache-GzipChain IO-Zlib`
> `search CGI or ABSTRACT=web` |  | Search for 'CGI' in the name, or 'web' in the abstract |  | `CGI-XMLForm HTML-Clean`
> `search XML and (parser or ABSTRACT=pars) and not XPath` |  | Search for 'XML' in the name and either 'parser' in the name or 'pars' in the abstract, but not with 'XPath' in the name |  | `XML-Node XML-Parser-EasyTree`
> `search Data::Grove` |  | PPM Server 3.0 repositories only: Search by module name, even if unrelated to the containing package |  | `libxml-perl`
> `search *` |  | Browse all packages in the repository |  | `Affix-Infix2Postfix AI-Fuzzy AI-NeuralNet-BackProp` [many more ...]

Recall previous searches using the `search` command. PPM stores searches for each session until you exit PPM.

Some package names or versions are too long to be displayed in the search results. If a name is too long, you will see a `~` (Tilde) as the last visible character in the column. You can use describe to view detailed information about such packages.

Search Results

When you type a command like `search XML`, PPM searches in each of the Active Repositories (see the repository command) for your package. The results are merged into one list, and duplicates (packages found in more than one repository) are hidden.

You can control what fields PPM shows for each package. The fields each have a built-in weight, which is used to calculate how wide to make each field based on the width of your screen. Information that doesn't fit into a field is truncated, and a tilde (`~`) character is displayed in the last column of the field.

Let's get down to an example:

>     ppm> search XML
>     Searching in Active Repositories
>         1. CGI-XMLForm           [0.10] Extension to CGI.pm which
>         2. Data-DumpXML          [1.01] Dump arbitrary data structures
>         3. DBIx-XML_RDB          [0.05] Perl extension for creating XML
>         4. DBIx-XMLMessage       [0.03] XML Message exchange between DBI
>         5. GoXML-XQI            [1.1.4] Perl extension for the XML Query
>         6. Language-DATR-DATR2~ [0.901] manipulate DATR .dtr, XML, HTML,
>         7. libxml-perl           [0.07] support for deeply nested
>         8. Mail-FilterXML         [0.1] Undetermined
>         9. Mail-XML              [0.03] Adds a toXML() method to
>        10. Pod-XML               [0.93] Module to convert POD to XML

As you can see, the three fields being displayed are:

> NAME |  | The package name
> VERSION |  | The package version
> ABSTRACT |  | The package abstract

You can customize the view somewhat. If you want to view the authors, but not the abstract, you can run the same search command after using set to change the fields:

>     ppm> set fields="NAME VERSION AUTHOR"
>     Setting 'fields' set to 'name version author'.
>     ppm> search XML
>     Using cached search result set 1.
>         1. CGI-XMLForm         [0.10] Matt Sergeant (matt@sergeant.org)
>         2. Data-DumpXML        [1.01] Gisle Aas (gisle@aas.no)
>         3. DBIx-XML_RDB        [0.05] Matt Sergeant (matt@sergeant.org)
>         4. DBIx-XMLMessage     [0.03] Andrei Nossov (andrein@andrein.com)
>         5. GoXML-XQI          [1.1.4] Matthew MacKenzie (matt@goxml.com)
>         6. Language-DATR-DAT~ [0.901] Lee Goddard (lgoddard@cpan.org)
>         7. libxml-perl         [0.07] Ken MacLeod (ken@bitsko.slc.ut.us)
>         8. Mail-FilterXML       [0.1] Matthew MacKenzie (matt@goxml.com)
>         9. Mail-XML            [0.03] Matthew MacKenzie (matt@goxml.com)
>        10. Pod-XML             [0.93] Matt Sergeant (matt@sergeant.org)

You can change the order in which the results are sorted, and what columns are displayed. The settings `fields` and `sort-field` changes this. You can sort by any valid field name (even fields which are not displayed). See the settings command for the valid field names.

PPM always hides "duplicate" results. It decides whether a result is duplicated based on the fields being displayed. If the same package is found in more than one repository, but you don't have the `REPOSITORY` field showing, PPM will only list the package once.

### Settings

> set |  | displays current options
> set <name> |  | displays the current setting of the given <name>
> set <name> <value> |  | sets <name> to <value>
> unset <name> |  | Sets <name> to a "false" value: '0' for boolean settings, '' for others.

The settings command is used to configure the default PPM environment. Settings such as the number of lines displayed per page, case-sensitivity, and the log file are configured using the settings command.

Setting names may be abbreviated to uniqueness. For example, instead of typing `case-sensitivity`, you may type `case`.

Available settings:

> NAME |  | VALUE |  | DESCRIPTION
> `case-sensitivity` |  | "0" or "1" |  | If set to "1", searches and queries are case-sensitive.
> `download-chunksize` |  | integer |  | If this is set to a positive, non-zero integer, PPM updates the status after each "integer" of bytes transferred during an install or upgrade.
> `fields` |  | fields |  | A space-separated list of fields to display in the search results. Valid fields are: `ABSTRACT AUTHOR NAME REPOSITORY TITLE VERSION` Usually, NAME and TITLE have the same content.
> `follow-install` |  | "0" or "1" |  | See install for details.
> `force-install` |  | "0" or "1" |  | See install for details.
> `install-verbose` |  | "0" or "1" |  | If "0", suppresses most output when installing packages. If "1", PPM prints each file as it is installed.
> `pager` |  | path |  | The path to an external pager program used to page long displays. If blank, or set to "internal", the internal pager is used. If "none", paging is disabled.
> `profile-track` |  | "0" or "1" |  | If "1", PPM arranges to have the ASPN server track your PPM profile. This means that every time your install or remove a package, your profile is updated on the server. If "0", you must manually save your profile using `profile save`.
> `prompt-context` |  | "0" or "1" |  | If "1", enables the prompt to change based on the current state of PPM, i.e. showing current target, query, etc.
> `prompt-slotsize` |  | integer |  | If `prompt-verbose` is "1", this defines the width of each slot in the prompt. For instance, "4" means to use 4 character-wide slots.
> `prompt-verbose` |  | "0" or "1" |  | If "0", uses numbers to represent the context in the prompt; much shorter. If `prompt-context` is set to "0", there will be no visible difference in the `prompt-verbose` settings.
> `rebuild-html` |  | "0" or "1" |  | If "0", suppresses regeneration of HTML documentation when packages are installed. If "1", enables HTML to be generated from POD documentation. Enabling this option may slow down package installation.
> `remove-verbose` |  | "0" or "1" |  | If "0", suppresses most output when removing packages. If "1", prints the name of each file as it is removed.
> `sort-field` |  | field |  | The field by which to sort search and query results. Valid fields are ABSTRACT, AUTHOR, NAME, TITLE and VERSION.
> `tempdir` |  | path |  | A temporary directory into which packages are downloaded and expanded during install and upgrade.
> `trace-file` |  | path |  | A file to which PPM will write tracing information.
> `trace-level` |  | integer |  | If "0" or negative, tracing is disabled. Positive, non-zero integers result in tracing information being written to `trace-file`. Higher settings of `trace-level` result in more trace information.
> `upgrade-verbose` |  | "0" or "1" |  | If "0", suppresses most output when upgrading packages. If "1", prints the name of each file as it is upgraded.

For information about migrating options used by previous versions of PPM, see `help ppm_migration`.

When you assign a value to a setting, PPM saves the configuration. Therefore, setting values persist across sessions.

### Tree

> tree |  | Displays the dependency-tree of the default package
> tree <number> |  | Displays the dependency-tree of the given <number>
> tree <range> |  | Displays a <range> of dependency trees
> tree <package name> |  | Displays the dependency-tree of the named package
> tree <url> |  | Displays the dependency-tree for the package at <url>
> tree <glob pattern> |  | Performs a new search using <glob pattern>

The `tree` command is used to show the "dependency tree" of a given package (additional packages that are required by the current package). For example:

>     tree SOAP-lite

returns:

>     ====================
>     SOAP-Lite 0.51
>     |__MIME-tools 5.316
>     |   |__MailTools 1.15
>     |   \__IO-stringy 1.216
>     |
>     \__MIME-Lite 2.105
>     ====================

SOAP-Lite requires four other packages.

When tree is called without a <name> or <number> switch, the command will return the dependency tree of the first package in the default search result. If there is no default search, you will be requested to use search to find a package.

### Upgrade

> upgrade [*] |  | Lists upgrades available for all installed packages
> upgrade <number> |  | Lists upgrades for installed package <number>
> upgrade <range> |  | Lists upgrades for a <range> of installed packages
> upgrade <package> |  | Lists upgrades for the named <package>

The upgrade command lists package upgrades that are available on the active repositories for packages installed on your system. To install available upgrades, use the `-install` option.

If profile tracking is enabled, (see profile), your profile will be updated to reflect changes to any packages which are upgraded.

There are several modifiers to the upgrade command:

> OPTION |  | DESCRIPTION
> Install |  | Installs, rather than lists, available upgrades
> Precious |  | Allows upgrading of "precious" packages
> Force |  | See install
> Follow |  | See install

By default, `upgrade` typed by itself only lists the available upgrades. To actually install all available upgrades, enter

>     upgrade -install

To enable upgrading "precious" packages, enter

>     upgrade -install -precious

### Version

> version |  | Prints the name and version of PPM3.

## Where are the package repositories?

By default, PPM will use the ActiveState package repository, but there are other repositories on the Internet. At the moment there are these repositories:

Note: most of these repositories are for ActivePerl 5xx builds only; they may not be compatible with ActivePerl 6xx builds. Check these repositories for the latest updates:

> http://ppm-ia.ActiveState.com/PPM/ppmserver.plex?urn:/PPM/Server/SQL | New 3.0 Repository from ActiveState
> http://www.ActiveState.com/cgibin/PPM/ppmserver.plex?urn:/PPMServer | The default package repository from ActiveState
> http://theoryx5.uwinnipeg.ca/cgi-bin/ppmserver?urn:/PPMServer | University of Winnipeg
> http://Jenda.Krynicky.cz/perl | Jan Krynicky's package repository
> http://www.roth.net/perl/packages/ | Roth Consulting's package repository
> http://www.xray.mpe.mpg.de/~ach/ptk/ppm | Achim Bohnet's package repository
> http://rto.dk/packages/ | RTO's packages repository (mostly mirrors of the above)
> http://www.fastnetltd.ndirect.co.uk/Perl/zips/ | Fastnet Software Ltd's packages - not directly accessible from PPM at present

To use these package repositories you start PPM v3 and at the prompt type:

>     repository add NAME URL

where NAME is a name by which you want to reference the repository from PPM and URL is the URL to the repository. Please note that NAME is optional, as PPM will assign a name to the repository for you. For example, entering:

>     repository add JENDA http://Jenda.Krynicky.cz/perl

will create a repository for you, by the name of JENDA and give you access to the modules available there.

## How do I make a PPM package?

If you want to make a PPM package for use on other machine you can do it like this:

Specify the AUTHOR and ABSTRACT parameters in the Makefile.PL. However you should only pass them to WriteMakefile if the version of the perl is greater than 5.005 - older perls do not have these parameters added and do not expect to see them. This is an example Makefile.PL:

> `use ExtUtils::MakeMaker;
> # See lib/ExtUtils/MakeMaker.pm for details of how to influence
> # the contents of the Makefile that is written.
> WriteMakefile(
> 'NAME' => 'Term::Control',
> 'VERSION_FROM' => 'Control.pm', # finds $VERSION
> ($] ge '5.005') ? (
> 'AUTHOR' => 'Johnny Doel (johnny@doel.org)',
> 'ABSTRACT' => 'Control the IO for terminals',
> ) : (),
> );`

Then you make the archive with the commands

> `perl Makefile.PL
> nmake`

The resulting files are placed in the blib directory that is created when you run nmake. These files should be packed into an archive like this:

> `tar cvf package.tar blib
> gzip --best package.tar`

You now have an archive called package.tar.gz. Then you generate the PPD file by:

> `nmake ppd`

You have to edit the resulting PPD file and add the location of the package archive into <CODEBASE HREF="" />. The location is relative to the PPD file.

You can get nmake from http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/Nmake15.exe.

## PPM, Proxies and Firewalls

If you use a proxy server or firewall, you might have trouble running PPM. Here is the solution.

> NOTE: If none of the changes in this document work for you, you may download individual packages from here [ActivePerl 801 and later] or here [ActivePerl 613 and later] or here [ActivePerl 522 and earlier] and install them according to the directions in the README file contained within the ZIP file. If you want, you can also keep a local repository, with several .ppd files in a permanent repository directory, and their .tar.gz files in an x86 directory beneath that.

1. ### Set Environment Vars

> Up to three environment variables need to be set.

> Under Windows 2000
> Right click on "My Computer", click on "Properties" and select the "Advanced" tab. Click the button marked "Environment Variables" and make the following changes in the "System Variables" window:

> 1. With the "New" button, add the setting HTTP_proxy, with your proxy name as the value (you must include "`http://`"), followed by a colon and the proxy port, if applicable; e.g., "`http://proxy:8080/`"
> 2. If you require a user name and/or password to access your proxy, use the "New" button to add the settings HTTP_proxy_user and HTTP_proxy_pass, with your user name and password as the respective values.

> Under Windows NT
> Right click on "My Computer", click on "Properties", select the "Environment" tab. These are your environment settings. Make the following changes:

> 1. Add the setting HTTP_proxy, with your proxy name as the value (you must include "`http://`"), followed by a colon and the proxy port, if applicable; e.g., "`http://proxy:8080/`"
> 2. If you require a user name and/or password to access your proxy, add the settings HTTP_proxy_user and HTTP_proxy_pass, with your user name and password as the respective values.

> Under Windows 9x
> In your AUTOEXEC.BAT file, place the following lines then reboot so the changes can take effect:

> 1. SET HTTP_proxy=<your proxy server (you must include "`http://`", followed by a colon and the proxy port, if applicable; e.g., `SET HTTP_proxy=http://proxy:8080/`
> 2. SET HTTP_proxy_user=<your user name> (if required)
> 3. SET HTTP_proxy_pass=<your password> (if required)

2. ### Try using PPM

> With your internet connection active, try using PPM again. Try to install a small package, like File-Slurp. You'll know that it still fails if you see an error stating that it can't find a ppd file for the specified package.

3. ### Further Information and Help

> If there were problems with any of the above hints, please see Troubleshooting for information regarding further help.

## AUTHOR AND COPYRIGHT

This FAQ was originally assembled and maintained by Evangelo Prodromou. It has been revised and updated by Brian Jepson of O'Reilly & Associates, David Grove, David Dmytryshyn, and Murray Nesbitt of ActiveState, Henning Michael Møller-Nielsen of RTO, Kevin Meltzer, and David Sparks of ActiveState.

This FAQ is in the public domain. If you use it, however, please ensure that you give credit to the original authors.

ActivePerl FAQ - PPM