ZPM – package manager for InterSystems IRIS

4 min


Package managers for various platforms are very widely used, they allow you to quickly install and configure many ready-made components and libraries. They are also used to deploy custom solutions. It is important that the package manager handles dependencies, i.e. if your application uses some kind of library of a certain version, then the package manager, when installing your application, will also install the necessary version of this library.

Now for InterSystems IRIS, a package manager, ZPM, is also available.

ZPM allows you to find, install, update a module, and can also be used to publish modules. Each module can be a separate application, library, framework, utility, or an example of using InterSystems technologies.

ZPM Package Manager

ZPM consists of two components:

  • Client (CLI)
    A utility that installs into your IRIS and is used to manage modules (for example, for installation)
  • Registry
    A database of modules and meta-information used to manage modules.

By default, the ZPM client is configured to use the registry: pm.community.intersystems.com is the registry of the developer community. This registry has published many examples, utilities, and libraries.

You can also pick up and use your own registry (more on that later in this article).

Where to begin

1. Install the ZPM client

Download the latest installer for this the link.

Import the downloaded class to any area in any way convenient for you: through the portal, through the Studio or through the terminal.

USER>Do $System.OBJ.Load("/path/zpm.xml", "ck")

If you use Docker, then you can use the InterSystems IRIS Community Edition and InterSystems IRIS for Health Community Edition images that already contain the latest version of ZPM (more details in the documentation)

2. Starting ZPM

After installation, ZPM is available in any area.
To use ZPM, just type the zpm command in the terminal and you will run the ZPM package manager command line interface (CLI).

MYNS> zpm
zpm: MYNS>

Using the help command, you can get a list of all available commands.

zpm: MYNS>help

3. Installing the module

First of all, using the search command, look at the list of available modules in the registry:

zpm: MYNS>search
 
registry https://pm.community.intersystems.com:
analyzethis 1.1.4
blocksexplorer 2.2.1
dsw 2.1.41
…

Use the install command to install the latest module or update. Installation will be performed in the current area.

zpm: MYNS>install dsw
 
[mdx2json] 	Reload START
[mdx2json] 	Reload SUCCESS
[mdx2json] 	Module object refreshed.
[mdx2json] 	Validate START
[mdx2json] 	Validate SUCCESS
[mdx2json] 	Compile START
[mdx2json] 	Compile SUCCESS
[mdx2json] 	Activate START
[mdx2json] 	Configure START
[mdx2json] 	Configure SUCCESS
[mdx2json] 	Activate SUCCESS
[dsw] 	Reload START
[dsw] 	Reload SUCCESS
[dsw] 	Module object refreshed.
[dsw] 	Validate START
[dsw] 	Validate SUCCESS
[dsw] 	Compile START
[dsw] 	Compile SUCCESS
[dsw] 	Activate START
[dsw] 	Configure START
[dsw] 	Configure SUCCESS
[dsw] 	Activate SUCCESS

As you can see, the mdx2json module is installed first, on which the dsw module depends, and then dsw.

That’s all – the module is installed and configured!

Many commands have special flags, for example, the -v or -verbose flag allows you to see details, for example:

zpm: MYNS>install dsw -v

See the full list of commands for their arguments and flags on the page documentation or using the help command.

Preparing and publishing your own package

In order for you to publish your own package, you must:

  • make your code work in InterSystems IRIS;
  • prepare the module.xml file.

The module.xml file describes your package, the resources included in the package, the dependencies and components necessary when installing the package (for example, creating web applications).

If you have used before InterSystems IRIS Installation Manifest (% Installer), then you will find a lot in common in module.xml and in the XDATA block.

Xml format description in documentation

You can check out the module.xml examples for published modules:
github.com/isc-zpm/DeepSeeWeb/blob/master/module.xml
github.com/isc-zpm/Samples-BI/blob/master/module.xml

In order to publish your package to the public registry pm.community.intersystems.com it is enough to publish the application in Open Exchange and specify its public repository.

Set your own registry

Creating your own registry is optional, but with it you can check how your module is assembled and installed.

If you plan to publish your application in the public registry pm.community.intersystems.com, it is recommended that you first check all the steps in your local registry.

To install your own registry, you can use the install command.
Go to the registry area (hereinafter we will assume that it is called REGISTRY) and execute

REGISTRY>zpm
zpm: REGISTRY>install zpm-registry

Check that your registry is working – open the page in your browser localhost: 52773 / registry / _ping (you may need to specify a different port, depending on the settings of your IRIS). When accessing the page, you will need to specify the login and password of the IRIS user (for example: _system / SYS).

If you saw {“message”: “ping”} – your registry is installed successfully.

Now configure your ZPM client to work with the new registry.

Run the command:

zpm: MYNS>repo -r -n registry -url http://localhost:52773/registry/ -user _system -pass SYS

This command says that the ZPM client needs to use the registry available at the specified URL as a remote registry and pass the username and password specified in the arguments -user and -pass when accessing, respectively.

Publish module

Check that you have created a separate folder in which module.xml and the classes of your module are located (classes are usually placed in the / src folder). In the example below, this module will be called demo-module (the name is specified in module.xml).

Verify that you have switched to the test registry.

Use the load command to load your code into the current area:

zpm: MYNS>load /path/to/module/folder
[demo-module]  Reload START
[demo-module]  Reload SUCCESS
[demo-module]  Module object refreshed.
[demo-module]  Validate START
[demo-module]  Validate SUCCESS
[demo-module]  Compile START
[demo-module]  Compile SUCCESS
[demo-module]  Activate START
[demo-module]  Configure START
[demo-module]  Configure SUCCESS
[demo-module]  Activate SUCCESS

This command performs a number of actions – downloads and compiles your code and configures your module.

Now ZPM client knows everything about your module and can publish it.

To publish, use the module-action command with the publish argument:

zpm: MYNS>module-action demo-module publish

The module-action command can be omitted, and written shorter:

zpm: MYNS>demo-module publish
[demo-module]  Reload START
[demo-module]  Reload SUCCESS
[demo-module]  Module object refreshed.
[demo-module]  Validate START
[demo-module]  Validate SUCCESS
[demo-module]  Compile START
[demo-module]  Compile SUCCESS
[demo-module]  Activate START
[demo-module]  Configure START
[demo-module]  Configure SUCCESS
[demo-module]  Activate SUCCESS
[demo-module]  Package START
Module exported to:
 	/var/folders/9f/r62h3fxj42b5fzb0hgnb28m40000gn/T/direyLtX5/demo-module-1.0.0/
 
Module package generated:
 	/var/folders/9f/r62h3fxj42b5fzb0hgnb28m40000gn/T/direyLtX5/demo-module-1.0.0.tgz
[demo-module]  Package SUCCESS
[demo-module]  Register START
[demo-module]  Register SUCCESS
[demo-module]  Publish START
[demo-module]  Publish SUCCESS

When this command is executed, the module will first be “assembled” (ie, prepared for publication) and exported to a temporary directory, archived and then published to the currently active registry.

Now if you run the search command you should see your module in the list:

zpm: MYNS>search                          
 
registry http://localhost:52773/registry/:
demo-module 1.0.0

In order to verify that the installation is successful, install your module from the test registry using ZPM into a new IRIS installation or a new area.

To publish an application in the community registry, just publish the application repository in Open exchange.

Switch to default registry

To switch to working with the default registry (pm.community.intersystems.com) use the -reset-defaults flag:

zpm: MYNS>repo -r -n registry -reset-defaults

Need your help!

ZPM is community supported – please report any issues or suggestions for improvement – create issues in the project repository.

A note on the license.

The ZPM client and registry located at pm.community.intersystems.com are not supported by InterSystems Corporation and are presented as is under the MIT license.


0 Comments

Leave a Reply