Thanks for your feedback!
Need to tell us more? Click here or use the Feedback button.

Is this page helpful?

Contents

Purpose
Getting Started
Overview of Module Definitions
Configuration
Discovery
Module Lifecycle
Other Commands
See Also

Introduction to InterSystems Package Manager

This page describes how to install InterSystems Package Manager (IPM) and get started with it. It also summarizes commands needed for configuring IPM, discovering modules, managing modules, and other tasks.

Purpose

InterSystems Package Manager (IPM) is a package manager for InterSystems products. Use IPM to search, install, update, remove, and publish modules (also known as packages). Each module could be an application, framework, tool, or technology example. With IPM, you can install:

InterSystems class definitions and ObjectScript routines
Front end applications
Interoperability applications
IRIS BI solutions
IRIS data sets
Embedded Python wheels or any other files

The modules can reside in multiple locations, depending on how you want to share code:

The InterSystems Community registry, at https://pm.community.intersystems.comOpens in a new tab (the default)
The Open Exchange, a community registry at https://openexchange.intersystems.com/Opens in a new tab, which contains code and libraries not written or supported by InterSystems.
Private registries
Local directories

Initial setup code for IPM is provided as part of your InterSystems product distribution. Once you load and use this code, you can upgrade IPM, retrieving the most recent version of the code from the default registry.

Getting Started

To install IPM and start using it:

Open an ObjectScript shell.
If you want to enable IPM only in a specific namespace, switch to that namespace.
You can later enable it in other namespaces, if you change your mind.
Enter the following command:
```
 do $system.OBJ.Load($System.Util.InstallDirectory()_"dist/install/misc.zpm.xml","ck")
```
This loads the file install-dir/dist/install/misc/zpm.xml.
You will see a series of messages as the installer extracts items and then loads and compiles code. The process can take a couple of minutes.

Enter zpm to launch the shell. The prompt looks something like this:

=============================================================================
|| Welcome to the Package Manager Shell (ZPM). Version: 0.10.2             ||
|| Enter q/quit to exit the shell. Enter ?/help to view available commands ||
|| No registry configured                                                  ||
|| System Mode: <unset>                                                    ||
|| Mirror Status: NOTINIT                                                  ||
=============================================================================
IRIS for Windows <version information here>
zpm:USER>

You can now enter IPM shell commands. Notice that this message indicates that no registry is configured, so the next step is generally to configure IPM to use the default registry (https://pm.community.intersystems.comOpens in a new tab).

Enter one of the following commands, depending on whether you want to configure IPM in all namespaces:
- repo -reset-defaults — Use this command if you want to configure IPM to use the default registry.
- repo -community — Use this command if you want to configure IPM to use the default registry and you also want to enable IPM in all namespaces.
This generates additional messages including these:
```
 
registry
        Source:                         https://pm.community.intersystems.com
        Enabled?                        Yes
        Available?                      Yes
        Use for Snapshots?              Yes
        Use for Prereleases?            Yes
        Is Read-Only?                   No
        Default Deployment Registry?    No
 
```

Now you can use the search command, which displays a list of packages that are available to install. The search command accepts wildcards. For example:

zpm:USER>search *data*
registry https://pm.community.intersystems.com:
ccd-data-profiler             1.1.3
databasesizemonitoring        1.0.0
dataset-apachelog             1.0.5
dataset-countries             1.1.4
dataset-finance               1.0.8
dataset-health                1.2.1
dataset-medical               1.0.5
dataset-oex-reviews           1.0.0
dataset-simple-m-n            1.0.5
dataset-titanic               1.0.0
iris-data-analysis            1.0.0
iris-datapipe                 2.0.5
iris-dataviz                  0.0.1
iris-energy-isodata           1.1.0
iris-rest-api-databasemanager 1.0.0
iristestdatagenerator         1.0.0
test-data                     1.0.4

You may want to try using IPM to download and install a package. If so, make sure that you are in the namespace where you want the code to reside. Then use the following command in the IPM shell:
```
install modulename
```
Where modulename is the name of a module that is available to you (as seen by the search command). You will see a series of messages, that vary depending on which module is being installed. The downloaded files are in <install-dir>/ipm/modulename.
The modulename directory has a subdirectory for the version that you downloaded. That subdirectory should contain a README.md file or other explanatory file. The module.xml file defines the module. Other directories and files vary by module.

Overview of Module Definitions

At a high level, use the following general process to define a module:

Identify the code and related artifacts that you want to package together and organize the files into a suitable directory structure. The goal is to have one directory that completely contains all the needed files.
Typically, the code source files are in different subdirectories depending on the language used, and by the type of code as well (classes versus routines, for example). Related artifacts such as exported globals or other data files are generally contained in other directories.
The directory structure may need to be aligned with the directory structure used by your source control integration.
Within this directory structure, create an IPM manifest file (module.xmlOpens in a new tab). This file describes what the module is, what it depends on, what code and resources it installs, and what to do before and after installation, optionally including running tests.
There are two ways to start creating this file:
- Copy the module.xml file from an existing package that looks similar to what you need.
- Use the generate command, which prompts you for input and then generates a module.xml file.
Make sure that you understand the dependencies of the new module and declare them in the manifest. This includes both the system dependencies (such as the InterSystems IRIS version or the OS version) and dependencies on any other modules.
Use the load command to load the module into your local instance, specifying the location of the manifest file. For example:
```
zpm:USER>load C:\InterSystems\IRISTest\ipm\mysample\1.0.0
```

Commands for IPM Configuration

The following commands configure how IPM works:

initOpens in a new tab – Configures the namespace for use of IPM (interactive). This sets up the local cache and allows for configuration of extensions for source control and IPM itself. Use this, for example, if you add a new namespace to the server.
configOpens in a new tab – Updates IPM settings.
enableOpens in a new tab – Enables IPM in other namespaces from a namespace in which IPM is already installed.
repoOpens in a new tab – Configures the current namespace to search for modules on a remote server or on the local file system.
default-modifiersOpens in a new tab – Manages default modifiers to use for all package manager commands in the current namespace.
unmapOpens in a new tab – Remove IPM code and repository mappings in specified namespaces.

Commands for Discovery

The following commands enable you to obtain information about modules:

searchOpens in a new tab – Lists modules in the current registry.
list-installedOpens in a new tab – Lists installed modules in the current namespace.
list-dependentsOpens in a new tab – Lists modules dependent on a specified module.
namespaceOpens in a new tab – Switches to a namespace and lists the modules installed in that namespace. There is also an option to list modules in all namespaces.
orphansOpens in a new tab – Lists resources in the default code database (of the current namespace) that are not part of any module.

Commands for Module Lifecycle and Management

The following commands apply to the process of installing, compiling, testing, packaging, and publishing modules:

module-actionOpens in a new tab – Performs operations on modules: compiling, running tests, packaging, registering, and so on). Many of the other commands in this list are synonyms for module-action used with different keywords.
installOpens in a new tab – Installs a module from a configured repository.
reinstallOpens in a new tab – Reinstalls a module from a repository.
updateOpens in a new tab – Updates an installed module to a newer version and runs all the update steps needed.
reloadOpens in a new tab – Reloads module source into the namespace, without recompiling it.
compileOpens in a new tab – Compiles resources in a module.
makedeployedOpens in a new tab – Marks resources as deployed, where possible.
module-versionOpens in a new tab – Displays or modifies the version of a module.
testOpens in a new tab – Runs unit tests for a module, if defined.
verifyOpens in a new tab – Runs the unit tests that are specified to run in the verify phase.
packageOpens in a new tab – Exports the module’s resources and bundles them into a module artifact (.tgz file).
generateOpens in a new tab – Generates a stub module.xml for use as a starting place for a new module manifest.
arrangeOpens in a new tab – Rearranges the resources in the given module manifest to follow the standard format.
publishOpens in a new tab – Uploads the module to the repository for which deployment is enabled. Currently, there may only be one of these per namespace.
unpublishOpens in a new tab – Removes a module from a repository.
uninstallOpens in a new tab – Uninstalls a module that is currently installed locally.

Other Commands

The rest of the commands are as follows:

helpOpens in a new tab – Shows help for the IPM shell or for an individual IPM command.
versionOpens in a new tab – Prints the version numbers of the currently installed IPM and current registry.
run-from-fileOpens in a new tab – Executes a sequence of IPM commands from a text or JSON script.
loadOpens in a new tab – Loads a module from the specified directory or archive into the current namespace. Dependencies are also loaded automatically, provided that they can be found in repositories configured with the repo command. This command (and import) are useful when working with files that are not yet in any repo.
importOpens in a new tab – Imports classes from a file or file(s), reexporting to source control if needed.
execOpens in a new tab – Executes the given ObjectScript statement and displays any output from it. This IPM option enables you to accomplish additional tasks without having to exit the IPM shell.
quitOpens in a new tab – Exits the IPM shell.