软件包规范

更新时间：
2024-12-27

软件包规范

通过 Armory 管理软件包时，软件包的名称、版本号、平台架构、配置文件和目录结构等必须满足相关规范。本节主要介绍软件包的具体规范及其配置方法。

名称规范

完整的软件包名称由命名空间（namespace）和软件包名（package-name）组成，格式为：@namespace/package-name。为确保软件包的可用性和可维护性，软件包名称需满足以下规范：

  • 命名空间（namespace）只能由小写字母、数字和特殊字符“-”、“_”组成，不能包含空格，且长度不能超过 30 个字符。
  • 软件包名（package-name）只能由小写字母、数字和特殊字符“-”、“_”组成，不能包含空格，且长度不能超过 50 个字符。
  • 为了提高软件包的辨识度，并帮助用户快速了解软件包的内容，软件包名应体现其功能或用途，多个单词之间可以用“-”连接，如 armory-cli。
  • 软件包名称中不应该包含版本号信息，版本号应在 armory.json 的 version 字段中定义。

名称说明符

包名称说明符（Package name specifier 简称package-spec）用于唯一标识制品仓库中的软件包或其版本。它通常包括命名空间、包名、版本号或标签。通过package-spec，可以在制品仓库中精确定位和管理不同的软件包及其版本。支持的格式如下：

  • [<@namespace/>]<package-name>：指定软件包名称。
  • [<@namespace/>]<package-name>@<tag>：指定软件包标签。
  • [<@namespace/>]<package-name>@<version>：指定软件包版本。

其中<@namespace/>为可选项，未指定时默认为 global（全局包）。

版本号规范

为了确保 Armory 软件仓库的健康、可靠和安全性，每次发布新版软件包时，版本号须遵循 Semantic Versioning open in new window 语义化版本规范，以便用户更好地掌握每个版本软件包的变化和兼容性。推荐的软件包版本号命名规则如下表所示。

代码状态产品阶段版本号命名规则版本号示例
首次发布新产品采用 X.Y.Z 格式，其中 X 为主版本号、Y 为次版本号、Z 为修订号1.0.0
向后兼容的错误修复补丁版本修订号 Z 的数值递增1.0.1
向后兼容的新功能小版本次版本号 Y 的数值递增，并将修订号 Z 重置为零1.1.0
不支持向后兼容性的更改主要版本主版本号 X 的数值递增，并将次版本号 Y 和修订号 Z 重置为零2.0.0

平台架构规范

Armory 支持管理多种平台和架构的软件包。为确保软件包搜索和依赖检测的一致性，名称和架构需遵循以下规范：

  • 平台名称不区分大小写。
  • 架构名称只能由小写字母、数字和连接符“-”组成，且长度不超过 20 个字符。在 Armory 中配置架构名称时，需将架构名称转化为小写，并将下划线（_）替换为连接符（-）。例如，X86_64 应写为 x86-64。

具体平台和架构名称，请参见下表中的命名规则。注意：每个平台支持的架构类型包括但不限于以下列举的内容：

平台名称平台别名架构名称
Windowswinnoarch、arm64、x86-64 ...
macOSmacnoarch、arm64、x86-64 ...
Linux-noarch、arm64、x86-64 ...
SylixOS-noarch、arm64-generic、x86-64 ...       更多关于 SylixOS 架构类型请参见 SylixOS 架构清单
Generic-noarch

SylixOS 架构清单

SylixOS 平台支持的架构名称映射到 Armory 中的架构命名如下表所示：

SylixOS 架构名称对应 Armory 中的架构名称
ARM_920Tarm-920t
ARM_V7Aarm-v7a
ARM64_GENERICarm64-generic
MIPS32_R2mips32-r2
MIPS32mips32
MIPS64_LS3Amips64-ls3a
MIPS64_R2mips64-r2
MIPS64mips64
PPC_E500V1ppc-e500v1
PPC_E500V2ppc-e500v2
PPC_E6500ppc-e6500
PPC_750ppc-750
PPC_464FPppc-464fp
x86_PENTIUMx86-pentium
X86_64x86-64
TI_C6000ti-c6000
SPARC_LEON3sparc-leon3
SPARC_V8sparc-v8
SPARC_V9sparc-v9
RISCV_GC32riscv-gc32
RISCV_GC64riscv-gc64
CSKY_CK803csky-ck803
CSKY_CK807csky-ck807
CSKY_CK810csky-ck810
CSKY_CK860csky-ck860
LOONGARCH32loongarch32
LOONGARCH64_LASXloongarch64-lasx
LOONGARCH64_LSXloongarch64-lsx
LOONGARCH64loongarch64
SW6Bsw6b

armory.json 规范

发布到 Armory 仓库的软件包，必须包含 armory.json 配置文件，您可以参考 创建软件包，自动创建一个符合 目录结构规范 的软件包，并参考如下示例定义 armory.json，以便快速发布软件包。以下是 armory.json 参考示例及其参数说明：

{ 
    "name": "@armory/armory-cli",
    "version": "1.0.0",
    "author": "acoinfo",
    "description": "Armory 是一款跨平台和架构的软件包管理工具，支持 Windows、macOS 和 Linux 平台的多种架构",
    "labels": [
        "armory",
        "client",
        "repository",
    ],
    "platforms": [
        {
            "name": "Windows",
            "arch": "x86-64",
            "minSupportedVersion": "Windows 8.1+",
            "baseDir": "windows/x86-64",
            "files": [
                "armory-win-x64.exe",
                "base/",
                "base/src",
                "./bin/armory.js"
            ]
        },
        {
            "name": "Windows",
            "arch": "arm64",
            "minSupportedVersion": "Windows 10+",
            "baseDir": "windows/arm64",
            "files": [
                "armory-win-arm64.zip",
            ]
        },
        {
            "name": "Linux",
            "arch": "arm64",
            "minSupportedVersion": "Linux 7, Ubuntu 14.04, Debian jessie, other distros with glibc >= 2.17",
            "baseDir": "linux/arm64",
            "files": [
                "armory-1.0.0-linux"
            ]
        },
        {
            "name": "macOS",
            "arch": "noarch",
            "minSupportedVersion": "macOS 11.0+",
            "baseDir": "macos",
            "files": [
                "armory-1.0.0-macos"
            ]
        }
    ],
    "dependencies":[
        {
            "name": "@armory/armory-cli",
            "version": "1.3.0"
        },
        {
            "name": "cloudnative_lab/armory-client",
            "version": "1.2.0"
        }
    ],
    "ignore": [
        "windows/x86-64/.ide",
        "windows/arm64/test",
        "linux/arm64/node_modules",
        "linux/arm64/*.ts",
        "macos/.metadata/"
    ],
    "installable": false
}

各参数说明如下：

参数字段类型是否必填说明
namestring是完整的软件包名称，命名时须遵循 名称规范。例如 @armory/armory-cli，其中 armory 为空间名称，armory-cli 为软件包名称。如果不指定命名空间，则默认为 global 全局空间
versionstring是软件包版本，版本号定义规则请参见 版本号规范
authorstring否软件包的作者信息，长度不能超过 50 个字符
descriptionstring否软件包描述信息，可以用一句话概括此软件的概念、功能等信息，长度不能超过 200 个字符
labelsarray否软件包标签，支持配置多个标签，每个标签不能超过 20 个字符，标签总数不超过 50 个。配置标签后可以通过标签信息搜索软件包
platformsarray是配置不同平台和架构的软件包文件，至少需要配置一个平台和架构的文件，支持配置多个，具体可支持的平台和架构请参见 平台架构规范。各字段说明如下：
  • name（必填，string）：平台名称
  • arch（必填，string）：架构名称
  • minSupportedVersion（选填，string）：描述当前软件包支持的最低平台版本，以明确软件包在此版本及以上的平台上可正常运行
  • baseDir（选填，string）：指定待发布软件包文件（即files中配置的文件）的前置路径，用于组织本地目录结构
  • files（必填，string）：指定当前平台架构下要发布的软件包文件集合，可配置多个文件或者文件夹，单个文件大小不能超过 2 GB
说明：baseDir仅用于组织本地目录结构，Armory 不会将其应用为软件包文件的实际路径。在 Web 端软件包文件视图和 安装软件包 过程中，仅使用files中配置的路径。而在发布和下载软件包时，则保留用户配置的files + baseDir组合路径
dependenciesarray否配置软件包依赖，所依赖的软件包必须已在对应仓库发布，支持配置多个依赖包。每个依赖包的字段说明如下：
  • name（必填，string）：依赖包的完整命名，包括命名空间和软件包名
  • version（选填，string）：依赖包的版本。如果不指定，则默认依赖最新版本
ignorearray否配置软件包的忽略文件，以排除 files 中不需要发布的文件，ignore 可以配置多项，并遵循 .gitignoreopen in new window 规范。配置 ignore 的注意事项如下：
  • 如果 files 中配置了 ignore 中排除的文件，则发布软件包时，Armory 客户端会终止发布并进行错误提示
  • ignore 配置不受 baseDir 字段的影响。如果要忽略 files 中的某些文件, 配置时仍需添加 baseDir 前缀。 例如，要忽略 files 下的 node_modules 文件，则 ignore 需要配置为： "ignore": ["windows/x86-64/node_modules"]，其中“windows/x86-64”为 baseURL 对应的值
installableboolean否指定软件包版本是否支持安装。可选值：true（支持安装） 或 false（不支持安装），默认值为 false
注意：在配置 installable 时，必须使用布尔值true 或false，而非字符串"true"或"false"。例如，应配置为"installable": true，而不是"installable": "true"

目录结构规范

为确保软件包发布的规范性和可行性，建议参考 创建软件包 自动生成符合规范的目录结构，并按需将待发布的软件包文件集放置在根目录下。此外，您也可以手动创建一个以软件包名称命名的文件夹，该文件夹应包含以下内容：

  • 包含待发布的软件包文件集合，可以是具体的文件或文件夹。如果涉及多平台多架构，建议将具体的包文件放置在以平台和架构命名的文件夹中。
  • 必须包含一个名称为 armory.json 的配置文件，用于发布软件包，并配置待发布软件包的详细信息，如软件包名称、版本、描述、检索标签、包资源路径等。
  • 建议包含 README 文件，用于详细描述软件包的编译、安装、配置、使用指导和更新日志等对用户有用的必要信息，README 文件的后缀必须为“.md”或“.txt”，且必须将其放置在软件包根目录下。
  • 如果 README 文件中有引用图片资源，建议将图片放置在软件包根目录的“assets/image”路径下。

下面以 armory-cli 软件包为例介绍软件包的目录结构及相关要求：

|-- armory-cli
    |-- assets
        |-- image
            |-- macos.png
            |-- windows.png
    |-- armory.json
    |-- README.md
    |-- windows
        |-- x86-64
            |-- armory-win-x64.exe
        |-- arm64
            |-- armory-win-arm64                      
    |-- linux
        |-- x86-64
            |-- armory-linux-x64
    |-- mocos
        |-- arm64      
            |-- armory-macos

目录结构说明如下：

文件名是否必配说明
armory-cli是软件包根目录，对应软件包名称，用于存放待发布的软件包的所有资源文件，名称支持自定义
assets否静态资源文件目录，用于存放软件包 README 文件中引用的图片资源，资源文件须存放在 image 文件夹中。如果没有图片资源，可以不包含此目录
armory.json是发布软件包的必备配置文件，用于配置待发布的软件包的详细信息，包括软件包名称、版本、描述、检索标签和包资源路径等，具体配置要求请参见 armory.json 规范。名称固定为 armory.json，不支持自定义
READEME.md否软件包概述文件，用于定义软件的概念、功能、使用指导和更新日志等概述性信息。此文件可选，其注意事项如下：
  • 如果软件包包含此文件，则文件名称和格式必须为 README.md 或 README.txt。此文件不需要在 armory.json 文件中配置
  • 如果此文件引用了图片资源，建议将图片放置在软件包根目录下的“assets/image”中，以便后期进行资源维护和离线迁移
windows/x86-64/armory-win-x64.exe
windows/arm64/armory-win-arm64.exe
linux/x86-64/armory-linux-x64
macos/arm64/armory-macos		是

待发布的软件包文件集合，支持配置多个文件或文件夹。您可以选择将所有文件打包为.tar.gz或.tgz格式进行发布，也可以直接发布零散的文件或文件夹


注意：若软件包需要安装到远程 SylixOS 计算机，则无论是通过压缩包还是直接发布文件，所有包文件都必须存放在 SylixOS 系统根目录下的默认内置文件夹中，如/etc、/lib、/user等。有关 SylixOS 内置文件夹的详细说明，请参见 ROOT 文件系统open in new window。您可以参考 SylixOS 安装包配置示例 进行配置

SylixOS 安装包配置示例

Armory 支持对远程 SylixOS 计算机上的软件包进行管理，提供安装、升级、卸载和查看已安装包列表等功能。为确保 SylixOS 安装包能成功发布到 Armory 并顺利安装到远程 SylixOS 计算机，建议您参考以下目录结构和 armory.json 配置示例进行配置。

目录结构配置示例

Armory 支持灵活配置待安装的软件包。您可以选择将所有文件打包为.tar.gz或.tgz格式进行发布安装，也可以将文件以零散文件或文件夹的方式直接发布。下面重点介绍两种安装包目录结构配置示例，关于各目录结构的详细说明请参见 目录结构规范 中的目录结构说明表。

方式一：将所有文件打包为.tar.gz或.tgz发布（推荐）

|-- example-app1
    |-- armory.json
    |-- README.md    
    |-- assets
        |-- image
            |-- sylixos.png
    |-- example-app1-sylixos-arm64-generic-v1.0.0-dev.tar.gz
    |-- example-app1-sylixos-x86-64-v1.0.0-dev.tar.gz

方式二：直接以零散文件或文件夹的方式发布

|-- example-app2
    |-- armory.json
    |-- README.md    
    |-- assets
        |-- image
            |-- sylixos.png
    |-- arm64
            |-- ect
                |-- example-app2
                    |-- config.yaml
            |-- lib
                |-- example-app2.so
            |-- user
                |-- bin 
                    |-- example-app2  
    |-- sylixos
        |-- x86-64
            |-- ect
                |-- example-app2
                    |-- config.yaml
            |-- lib
                |-- example-app2.so
            |-- user
                |-- bin 
                    |-- example-app2

armory.json 配置示例

下面将结合上述 目录结构配置示例，重点介绍两种目录结构对应的 armory.json 文件配置示例，关于各字段的详细说明请参见 armory.json 规范 中的各参数说明表。

示例一：.tar.gz或.tgz压缩包发布的 armory.json 配置示例

{ 
    "name": "@sylixos-middleware/example-app1",
    "version": "1.0.0",
    "author": "acoinfo",
    "description": "SylixOS 安装包配置示例",
    "labels": [
        "armory",
        "SylixOS",
        "remote",
    ],
    "platforms": [
        {
            "name": "SylixOS",
            "arch": "arm64-generic",
            "minSupportedVersion": "SylixOS 3.6.4",
            "files": [
                "example-app1-sylixos-arm64-generic-v1.0.0-dev.tar.gz"   
            ]
        },
        {
            "name": "SylixOS",
            "arch": "x86-64",
            "minSupportedVersion": "SylixOS 3.6.4",
            "files": [
               "example-app1-sylixos-x86-64-v1.0.0-dev.tar.gz"
            ]
        }
    ],
    "dependencies": [],
    "ignore": [],
    "installable": true
}

示例二：零散文件或文件夹发布的 armory.json 配置示例

{ 
    "name": "@sylixos-middleware/example-app2",
    "version": "1.0.0",
    "author": "acoinfo",
    "description": "SylixOS 安装包配置示例",
    "labels": [
        "armory",
        "SylixOS",
        "remote",
    ],
    "platforms": [
        {
            "name": "SylixOS",
            "arch": "arm64-generic",
            "minSupportedVersion": "SylixOS 3.6.4",
            "baseDir": "sylixos/arm64",
            "files": [ 
                "etc",   
                "lib",
                "usr"
            ]
        },
        {
            "name": "SylixOS",
            "arch": "x86-64",
            "minSupportedVersion": "SylixOS 3.6.4",
            "baseDir": "sylixos/x86-64",
            "files": [
                "etc",      
                "lib",
                "usr"
            ]
        },
    ],
    "dependencies": [],
    "ignore": [],
    "installable": true
}
文档内容是否对您有所帮助？
有帮助
没帮助
Copyright © 2024 ACOINFO. All Rights Reserved. 京ICP备20010248号备案号京公网安备11010802043204号