# Using PPM

- What is PPM?

- Setup

- The PPM GUI
- The PPM Command Line
- Finding, Installing, Removing and Upgrading Packages

- Find a package.
- Install a package.
- Remove a package.
- Upgrade a package.

- PPM Preferences

- Areas
- Repositories

- Default Repository
- Additional Repositories
- Additional Resources

- Additional Information

- Creating an Install Area
- Using PPMX Files
- Unavailable Packages
- Creating PPM packages
- PPM, Proxies and Firewalls

- The http_proxy Environment Variable
- Setting http_proxy

- Using the CPAN shell

## What is PPM?

PPM is the package management utility for ActivePerl. It simplifies the task of locating, installing, upgrading and removing Perl packages. The PPM client accesses PPM repositories (collections of packages) on the internet or on a local network. It is also used to update previously installed packages with the latest versions and to remove unused packages from your system.

### Setup

PPM is installed automatically with ActivePerl.

To use PPM, your computer must be connected to the internet or have access to a PPM repository on a local hard drive or network share.

If you connect to the internet via firewall or proxy, you may need to set the `http_proxy` environment variable. See PPM, Proxies and Firewalls for more information.

Access to some PPM repositories requires an ActivePerl Business Edition license.

## The PPM GUI

To launch PPM's graphical user interface, run `ppm` without any command line arguments:

      ppm

The interface should look something like this:

When launched, PPM automatically synchronizes its local database with the installed perl packages (including those installed manually or via the CPAN shell). The interface is temporarily locked while this synchronization takes place.

Hovering the mouse pointer over icons in the toolbar displays tool tips describing what each button does. These buttons are:

- All packages: Displays all packages installed locally and available in the repository.
- Installed packages: Displays all installed packages.
- Upgradable packages: Displays packages for which an upgrade is available from the repository.
- Packages to install/remove: Displays packages marked for installation or removal.
- Mark for install: Marks the selected packages for installation or upgrade.
- Mark for remove: Marks the selected packages for removal.
- Run marked actions: Runs all marked actions (i.e. install, upgrade, remove)
- Refresh all data: Refreshes the list view.
- PPM Preferences: Opens the PPM Preferences dialog box.

Use the Filter text field to limit the packages displayed in the Package List pane to those matching the text entered (case insensitive substring match).

Click the magnifying glass icon to select which package meta-data to match against:

- Name
- Abstract
- Name or Abstract (default)
- Author

The Package List pane can display the following columns of package information:

- Package Name: The name of the package.
- Area: Where the package is installed. See install areas below.
- Installed: Version number of the installed package.
- Available: Version number of the package in the repository.
- Abstract: A short description of the package.
- Author: Name and email address of the package's author.

The Status tab displays messages about the current status of the PPM client, marked actions, and information about the actions being run.

The Details tab displays package information and, for installed packages, a list of all installed files.

## The PPM Command Line

All PPM operations and configuration can also be performed at the command line. See the ppm man page or 'ppm help' for more information.

## Finding, Installing, Removing and Upgrading Packages

### Find a package.

To find a package in the repository:

- Click the All packages button,
- Enter text from the package's name or abstract in the Filter field

As text is entered in the Filter field, the list of packages is automatically updated as the substring match becomes more precise. Click the magnifying glass icon to filter on different meta-data (e.g. Author).

Alternatively, just start typing the name of the package. The Package List will highlight the first package that matches the string you have typed.

### Install a package.

To install a package from the repository:

- Click on the desired package in the Package List to select it.
- Mark the package by:
  - Clicking the Mark for install button or,
  - Hitting the "+" key or,
  - Selecting Install <package-name> from the Action menu or,
  - Right-clicking the selection and choosing Install <package-name> from the context menu.
- Click the Run marked actions button or select Run Marked Actions (Ctrl-Enter) from the File menu.

### Remove a package.

To remove a package from your local perl installation:

- Click on the Installed package in the Package List to select it. You may want to use the Installed packages button to filter the list.
- Mark the package by:
  - Clicking the Mark for remove button or,
  - Hitting the "-" key or,
  - Selecting Remove <package-name> from the Action menu or,
  - Right-clicking the selection and choosing Remove <package-name> from the context menu.
- Click the Run marked actions button or select Run Marked Actions (Ctrl-Enter) from the File menu.

### Upgrade a package.

To upgrade a package to the most recent version available in the repository:

- Click on the desired package in the Package List to select it. You may want to use the Upgradable packages button to filter the list.
- Mark the package by:
  - Clicking the Mark for install button or,
  - Hitting the "+" key or,
  - Selecting Install <package-name> from the Action menu or,
  - Right-clicking the selection and choosing Install <package-name> from the context menu.
- Click the Run marked actions button or select Run Marked Actions (Ctrl-Enter) from the File menu.

## PPM Preferences

Installation Areas can be selected and Repositories configured by clicking the PPM Preferences button or selecting Preferences from the Edit menu.

### Areas

PPM allows for the addition of new install areas, which is useful for shared ActivePerl installations where the user does not have write permissions for the site and perl areas. New install areas are added by simply setting up new library directories for perl to search, and PPM will set up install areas to match. The easiest way to add library directories for perl is to specify them in the `PERL5LIB` environment variable, see the perlrun manpage for details. PPM will create etc, bin, html directories as needed when installing packages. If the last segment of the library directory path is lib then the other directories will be created as siblings of the lib directory, otherwise they will be subdirectories.

### Repositories

The Repositories tab lists the repositories that PPM is currently configured to use and allows you to add additional ones. Simple PPM repositories are just a directory containing ppm packages. You can create your own by putting packages in an HTTP, FTP directory or a locally accessible mount or filesystem directory.

To add a repository fill out the fields in the Add Repository pane and click Add.

- Name: The name you want to give the new repository.
- Location: The URL of the repository. Enter an HTTP or FTP URL, a filesystem path, or use the Browse button to select a local directory. For password protected FTP sites, use the format:

        ftp://user:password@server/path.

To remove a repository, click the icon next to it.

Enabled repositories show the icon; disabled ones show the icon. Click these icons to toggle between states.

#### Default Repository

The base URL of the default PPM repository is:

      http://ppm4.activestate.com/

The full URL is platform and version-specific, for example:

      http://ppm4.activestate.com/MSWin32-x86/5.12/1202/package.xml

#### Additional Repositories

> http://bioperl.org/DIST | A repository of Bioperl packages
> http://www.bribes.org/perl/ppm/ | the "Bribes de Perl" (Scraps of Perl) repository (en Français et Anglais)

## Additional Information

### Creating an Install Area

On systems where ActivePerl is installed in a directory that is not writable by users (i.e. owned by `root`), a new perl library location can be defined with the PERL5LIB environment variable. PPM will recognize this library as an install area.

To create a new, user-writable install area:

1. Make a directory for the library. For example:

           mkdir -p ~/perl/lib

2. Set or modify the `PERL5LIB` environment variable using the command specific to your shell (e.g. `set` or `export`). To make this change persistent, add the command to the appropriate profile file for the shell. For example, in bash, add a line like the following to your .bash_profile or .bashrc file:

           PERL5LIB=~/perl/lib; export PERL5LIB

3. Launch PPM and click the PPM Preferences button. In the Area tab, select the new install area to make it active.

Note: On Mac OS X, user-writable install areas called "ActivePerl" are created for all users during installation (in /Users/<username>/Library/ActivePerl).

### Using PPMX Files (Business Edition)

If you need to install packages on systems without direct access to repositories, you can use PPMX files. These are compressed tarballs containing the PPD file for the package and the blib tree to be installed. You can download PPMX files from http://ppm4.activestate.com/.

Note: Access to ActiveState PPMX archives require a Business Edition license.

To use a PPMX file:

1. Download the file and/or transfer it to a convenient directory on the target system.
2. Install the package by specifying the ppmx file explicitly, rather than just the package name. For example
   `ppm install c:\tmp\Date-Calc-6.3.ppmx`

Some modules have dependencies that may cause them to fail to install if those packages are not available in a repository that PPM is connected to. You can use the ppm `describe` command to see what dependencies the package has, but those packages may have their own dependencies. The dependency chain has to be resolved manually by starting with the lowest common prerequisite package.

### Unavailable Packages

Most modules available via PPM are not owned or maintained by ActiveState; we only pre-package those modules available from CPAN that can be built automatically.

Additionally, some packages are not available via PPM because of export restrictions or license incompatibility. Not all PPM packages in the repository are completely up-to-date or available for every platform.

Check package availability and build status on the PPM Index site. If a module that you require is not available via PPM, try building it using the CPAN shell as described below.

### Creating PPM packages

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 may need to set the `http_proxy` environment variable in order for PPM to work.

#### The http_proxy Environment Variable

Set the `http_proxy` variable with the hostname or IP address of the proxy server:

      http_proxy=http://proxy.example.org

If the proxy server requires a user name and password, include them in the following form:

      http_proxy=http://username:password@proxy.example.org

If the proxy server uses a port other than 80, include the port number:

      http_proxy=http://username:password@proxy.example.org:8080

#### Setting http_proxy

Windows 2012/2008

1. From the System Manager click Change System Properties
2. Select the Advanced tab, then click the Environment Variables button.
3. Click New in the System variables panel.
4. Add `http_proxy` with the appropriate proxy information (see examples above).

Windows 7/8

1. Open the Advanced System Properties tab in the Control Panel (Control Panel > System Properties > Advanced > Environment Variables...).
2. Click the Environment Variables button.
3. Click New in the System variables panel.
4. Add `http_proxy` with the appropriate proxy information (see examples above).

Mac OS X

The `http_proxy` should be set in two places on OS X:

- Shell: Add a line like the following in `.bash_profile` (/Users/<name>/.bash_profile):

            http_proxy=http://username:password@hostname:port;  export http_proxy

  This setting applies to PPM when it is launched from or used at the command line.

- Desktop: Add an entry like the following in your environment.plist file (/Users/<name>/.MacOSX/environment.plist):

            <key>http_proxy</key>
            <string>http://username:password@hostname:port</string>

  This setting applies to PPM when it is launched by clicking the PPM icon.

Linux, Solaris or HP-UX

Set the http_proxy environment variable using the command specific to your shell (e.g. `set` or `export`). To make this change persistent, add the command to the appropriate profile file for the shell. For example, in `bash`, add a line like the following to your .bash_profile or .bashrc file:

        http_proxy=http://username:password@hostname:port;  export http_proxy

### Using the CPAN shell

If you require a module that is not available via `ppm`, or you require a more recent version, you can build the module from CPAN sources. The CPAN shell is a command-line interface for fetching and building modules directly from CPAN archives. To run it, enter the following command:

        cpan

Building modules from source requires the following components:

Windows:

- Microsoft's `nmake`, which is available from: http://support.microsoft.com/default.aspx?scid=kb;en-us;Q132084, or `dmake`, which is available from http://search.cpan.org/dist/dmake.
- a C compiler (not required for 100% pure perl modules). Supported compilers are MicroSoft Visual C/C++ 6.0 and MinGW (gcc). The MinGW and MinGW64 packages are available via PPM for 32-bit and 64-bit Windows systems respectively.

Mac OS X:

- Apple's Xcode tool suite, available from: http://developer.apple.com/tools/xcode/index.html

Linux and Solaris systems will normally have a compiler and a `make` utility installed by default.

See How to install CPAN modules into ActivePerl on the ActiveState blog for more information.