ZPM介绍(2)

发布您自己的软件

首先：要发布您的软件，您要支持这个”命名规范。其中和zmp最相关的是包名和l类名的设计，你要定义成这样：

company.project.subpackage.TheClass.cls

如果您的Package Name定义是： Company.Project, 有大写字母，对不起，是无法用zpm打包的。

这个链接给了最简单的例子，但还不详细，我来总结一下：

发布您的软件前，有几件事情要了解：

1. zpm的注册中心并不存代码，存的只是一个到您代码的链接。因此，您得找地方放您的代码。当前最常用的是github。

2. 文件目录的结构

   举例：有一个class定义是 com.tony.Test1.cls, 你的目录应该这么组织，假设您要放在 /myDemo, 那么class应该在/myDemo/src/com/tony/Test1.cls。这是使用VSCode组织代码的默认方式，只有保证这样的目录结构，您才可能用zpm加载代码到iris.

让我来做个简单的例子。

首先，有这样的class:

Class com.tony.Test1
{   Property p1;
}

我的文件目录设置

$ ls -l /external/myDemo/src
total 4
-rw-r--r-- 1 irisowner irisowner 40 Nov 12 10:00 Test1.cls
$

这时候我来使用zpm打包测试

module.xml的生成和加载

第一步，生成module.xml

我们看看最简单的用zpm generate命令生成module的例子：

zpm:USER>generate /external/myDemo/project1
 
Enter module name: project1
Enter module version: 1.0.0 =>
Enter module description:
Enter module keywords:
Enter module source folder: src =>
 
Existing Web Applications:
    /csp/user
    /terminal
    /terminalsocket
    Enter a comma separated list of web applications or * for all:
Dependencies:
    Enter module:version or empty string to continue:
zpm:USER>

zpm generate会把/external/myDemo/project1目录下的文件打包，在这个目录下创建一个module.xml文件， 是这样的：

<?xml version="1.0" encoding="UTF-8"?>
<Export generator="Cache" version="25">
  <Document name="project1.ZPM">
    <Module>
      <Name>project1</Name>
      <Version>1.0.0</Version>
      <Packaging>module</Packaging>
      <Resource Name="com.PKG" />
      <SourcesRoot>src</SourcesRoot>
    </Module>
  </Document>
</Export>

先等等解释这个xml, 让我们先执行第2步。

第2步： 把文件load到iris

zpm:USER>load /external/myDemo/
[USER|firstdemo]    Reload START (/external/myDemo/)
[USER|firstdemo]    Reload SUCCESS
[firstdemo] Module object refreshed.
[USER|firstdemo]    Validate START
[USER|firstdemo]    Validate SUCCESS
[USER|firstdemo]    Compile START
[USER|firstdemo]    Compile SUCCESS
[USER|firstdemo]    Activate START
[USER|firstdemo]    Configure START
[USER|firstdemo]    Configure SUCCESS
[USER|firstdemo]    Activate SUCCESS
zpm:USER>

您去iris里看看， 确认class已经被loaded

第3步： 删除(optional, 但你可能会用到这个命令)

zpm:USER>uninstall firstdemo
 
[USER|firstdemo]    Clean START
[USER|firstdemo]    Unconfigure START
[USER|firstdemo]    Unconfigure SUCCESS
Deleting class com.tony.Test1
[USER|firstdemo]    Clean SUCCESS
zpm:USER>

这时候您应该可以发现com.tong.Test1类已经从Iris删除了。

对上面的例子总结一下：

1. 打包是对一个文件夹打包

2. 使用zpm把软件包加载进iris是先找包里面的module.xml文件。通过module.xml里定义的信息来知道包的名字，版本，打包的内容等等。 这个module.xml是在打包的时候用zpm generate创建的， 但您也可以自己手工创建，比如copy其他包的module.xml改改， 有时候会更快捷，尤其是您对zpm命令不是很熟悉的时候， 对很多打包的需求，比如后面会提到的定义依赖等等，直接改module.xml比zpm generate容易多了。

3. 让我来说说可能的问题：

   module.xml中<Resource Name="com.PKG"/>定义了包名com.PKG, 加载数据包到iris很成功。但是，如果您还记得，刚刚例子里打包的是class是com.tony.Test1，那么如果你再定义一个新的类，叫com.tiedan.Test1, 用zpm generate一个新module, 名字叫project2(注意第一个打包的module名字是project1), project2的"Resource Name"也还是"com.PKG， 它能正确加载吗？

   不会， 你会被告知："ERROR! Resource 'com.PKG' is already defined as part of module 'project1'; cannot also be listed in module 'project2'"

​ 解决方法：手工将module.xml里面的Resource Name改成“com.tony.PKG"和"com.tiedan.PKG", 这样两个包都能成功加载了。

还有个小问题，Mac用户可能会看到这样的提示：

zpm:USER>load /external/myDemo/project1

[USER|project1] Reload START (/external/myDemo/project1/)
[project1] Reload FAILURE
ERROR! Unable to import file '/external/myDemo/project1/src/com/.DS_Store' as this is not a supported type.
zpm:USER>

这是说打包的文件夹下面有.DS_Store文件，而zpm不认识。zpm会把里面认识的文件, 比如.cls文件成功加载， 然后告诉你"Roload FAILURE"

好吧， 到这里我们知道怎么打包和把包加载到iris里， 接着看看什么文件可以被打包。

Package可以包含的文件类型

这时候要好好了解module.xml的内容的细节了， 请阅读技术文档的module.xml部分。

其中的resource部分，阐明了您可以打包的内容：

第一部分：可以被加载到iris的文件类型。

Use the following suffixes for different types of resources:

.PKG - Package
.CLS - Class
.INC - Include
.MAC - Routine
.LOC - LocalizedErrorMessages
.GBL - Global
.DFI - DeepSee Item

第二部分：jar包

<FileCopy Name="lib/" Target="${libdir}my-lib/"/>               Copies content of lib folder to Target
<FileCopy Name="somefile.jar" Target="${libdir}my-lib/"/>       Copies just desired file to Target

第三部分：UnitTest

module.xml的例子里给出的UnitTest部分是这个样子

<UnitTest Name="/tests/unit_tests/" Package="Test.Unit" Phase="test"/>

说实话，我还没研究怎么使用zpm generate可以做到这一点，能想到的就是手工去修改module.xml文件。

第四部分：Web Application

执行zpm generate的时候， 会列出当前命名空间可以使用的Web Application列表。让我重新执行一下打包的第一步，看看结果是什么样子

zpm:USER>generate /external/myDemo/project1
 
Enter module name: project11
Enter module version: 1.0.0 =>
Enter module description:
Enter module keywords:
Enter module source folder: src =>
 
Existing Web Applications:
    /csp/user
    /terminal
    /terminalsocket
    Enter a comma separated list of web applications or * for all: /csp/user
    Enter path to csp files for /csp/user: 
Dependencies:
    Enter module:version or empty string to continue:
zpm:USER>

得出的module.xml里多了如下内容：

<CSPApplication CookiePath="/csp/user/" DefaultTimeout="900" DeployPath="${cspdir}user/" Description="User Namespace applications" GroupById="%ISCMgtPortal" MatchRoles=":{$dbrole}" PasswordAuthEnabled="1" Recurse="1" ServeFiles="2" ServeFilesTimeout="3600" UnauthenticatedEnabled="1" Url="/csp/user" UseSessionCookie="2"/>
      <SourcesRoot>src</SourcesRoot>

其中，打包时提问`Enter path to csp files for /csp/user：。 这里，您需要填入的是当前要load的csp文件。比如：您有一个tony.csp要加载，那么您可以在要打包的目录下创建一个子目录“cspfiles", 把tony.csp放在cspfiles目录里， 回答提问的使用这样

Enter path to csp files for /csp/user：/cspfiles

这里用的是相对路径，但格式是绝对路径的格式，我把它看成一个bug。

module.xml中还有其他很多配置的内容，我在后面会介绍包的依赖的部分。

软件包的Package

用package命令，在iris里将软件打包。打包的结果是得倒一个project1-1.0.0.tgz的文件。 package -v显示verbose信息，您可以清楚的看到project1-1.0.0.tgz和module.xml的存放位置。

zpm:USER>project1 package -v
 
[USER|project1] Reload START (/external/myDemo/project1/)
Skipping preload - directory does not exist.
Load of directory started on 11/20/2022 13:15:17 '*'
 
Loading file /external/myDemo/project1/src/com/tony/Test1.cls as udl
Load finished successfully.
 
[USER|project1] Reload SUCCESS
[project1]  Module object refreshed.
[USER|project1] Validate START
[USER|project1] Validate SUCCESS
[USER|project1] Compile START
Compilation started on 11/20/2022 13:15:17 with qualifiers 'd-lck'
Compiling class com.tony.Test1
Compiling routine com.tony.Test1.1
Compilation finished successfully in 0.008s.
 
[USER|project1] Compile SUCCESS
[USER|project1] Activate START
[USER|project1] Configure START
[USER|project1] Configure SUCCESS
Studio project created/updated: project1.PRJ
[USER|project1] Activate SUCCESS
[USER|project1] Package START
Exporting 'com.tony.Test1.cls' to '/usr/irissys/mgr/Temp/dirKBwoaM/project1-1.0.0/src/com/tony/Test1.cls'
Exported to /usr/irissys/mgr/Temp/dirKBwoaM/project1-1.0.0/module.xml
Module exported to:
    /usr/irissys/mgr/Temp/dirKBwoaM/project1-1.0.0/
 
Module package generated:
    /usr/irissys/mgr/Temp/dirKBwoaM/project1-1.0.0.tgz
[USER|project1] Package SUCCESS
zpm:USER>

软件包的Publish

我们并没有权限把软件包直接发布到官方的registry去。您需要去InterSystems的OpenExchange页面，提交您的软件包。如下图填入软件包的信息，Github URL, 注意勾选右下角的"Publish in Package Manager" 。

后面， 我会介绍怎么创建自己team的私服， 用zpm publish可以简单的把iris的软件包发布到私服上去，这对一个开发团队共享软件包并方便部署应该是更有吸引力些。