opm openresty的包管理器-中文文档

2023-10-21 13:41:58

2022年1月11日13:57:45

官方：https://opm.openresty.org/

官方文档：https://opm.openresty.org/docs#table-of-contents

为什么建议使用opm不建议使用luarocks？

http://openresty.org/cn/using-luarocks.html

官方解释：请注意！LuaRocks 并不是 OpenResty 官方推荐的装包方式。LuaRocks 上绝大部分的 Lua 库都可能会阻塞 OpenResty 的事件循环，而让性能急剧下降。推荐使用 OPM。

名称
状态
概要
描述
用法
- 安全安装
- 本地安装
HTTP 代理支持
作者工作流程
dist.ini 文件
- name
- abstract
- version
- author
- license
- requires
- repo_link
- is_original
- lib_dir
- exclude_files
- main_module
- doc_dir
File .opmrc文件
- github_account
- github_token
- upload_server
- download_server
版本号处理
安装
- For opm
安全注意事项
信用
待完成
作者
版权和许可

状态

实验性的.

概要

对于库的用户:

# 显示用法
opm --help

# 使用用户模式“lock”搜索包名称和摘要。
opm search lock

# 使用多种模式“lru”和“cache”搜索包名称和摘要。
opm search lru cache

# 在 some_author 的名称下安装一个名为 lua-resty-foo 的包
opm get some_author/lua-resty-foo

# 获取所有作者下的 lua-resty-foo 包列表。
opm get lua-resty-foo

# 显示由名称指定的已安装包的详细信息。
opm info lua-resty-foo

# 显示所有已安装的软件包。
opm list

# 升级包 lua-resty-foo 到最新版本。
opm upgrade lua-resty-foo

# 将所有已安装的软件包更新到最新版本。
opm update

# 卸载新安装的包
opm remove lua-resty-foo

所有命令都可以跟随 --cwd 选项在当前工作目录（在 ./resty/modules/ 下）而不是系统范围的位置工作。

# 安装到 ./resty_modules/ 而不是系统范围的位置：
opm --cwd get foo/lua-resty-bar

# 检查 ./resty_modules/ 下本地安装的包
opm --cwd list

# 删除 ./resty_modules/ 下本地安装的包
opm --cwd remove lua-resty-bar

对于库的作者：

cd /path/to/lua-resty-foo/

opm build

# optional:
#     cd lua-resty-foo-VERSION/ && opm server-build

# 您可能需要编辑 ~/.opmrc 文件来设置您的 github
# 个人访问令牌。 “opm upload”的第一次运行将创建
# 为您提供样板文件 ~/.opmrc 文件。
opm upload

# 清理 opm build 命令的剩余部分。
opm clean dist

描述

opm 是官方的 OpenResty 包管理器，原理上类似于 Perl 的 CPAN 和 NodeJS 的 npm。

我们在此 GitHub 代码存储库中为*包存储库提供 opm 客户端命令行实用程序和服务器端应用程序。

OpenResty 用户可以使用 opm 命令行实用程序下载在* opm 服务器（即 opm.openresty.org）上发布的包。它还可以用于打包 OpenResty 包并将其上传到服务器，以供包作者和维护者使用。您可以在 bin/ 目录下找到 opm 的来源。它目前被实现为独立的 Perl 脚本。

服务器端 Web 应用程序基于 OpenResty 构建并用 Lua 编写。您可以在 web/ 目录下找到服务器代码。

与许多其他包管理系统（如 cpan、luarocks、npm 或 pip）不同。我们的 opm 采用了类似于 github 的包命名规则，即每个包名都应该由一个发布者 ID 限定，如 agentzh/lua-resty-foo 其中 agentzh 是发布者 ID 而 lua-resty-foo 是包名本身。这种命名要求避免了占用好包名的诱惑，也允许多个同名库共存于同一个*服务器存储库中。由用户决定安装哪个库（甚至在她的不同项目中安装同一库的多个分支）。为简单起见，我们只是将 GitHub 用户 ID 和组织 ID 映射到 opm 的发布者 ID。出于这个原因，我们使用 GitHub 个人访问令牌（或 oauth 令牌）来验证我们的包发布者。这也完全消除了 opm 包作者的注册过程。

opm 内置了对 restydoc 工具的支持，即通过 opm 安装的包的文档已经被 restydoc 索引，可以直接在终端上用 restydoc 工具查看。

opm 目前只支持纯 Lua 库，但我们将很快添加对纯 C 或一些 C 组件的 Lua 库的支持。未来还希望通过 opm 添加对将 3rd-party NGINX C 模块重新分发为动态 NGINX 模块的支持。 OpenResty 世界毕竟由各种不同类型的“模块”组成。

我们还计划允许用户通过特殊用户 ID luarocks 通过 opm 安装 LuaRocks 包。安装一个与 OpenResty 无关的 Lua 模块会带来风险，该模块会在网络 I/O 上严重阻塞 NGINX 工作进程，但是，作为 opm 的开发人员，我们总是喜欢选择，尤其是那些给我们用户的选择。

Back to TOC

用法

opm [options] command package...

Options:

    -h --help　　　　　　　　打印此帮助。

    --install-dir =PATH   安装到指定的 PATH 目录而不是系统范围内包含此工具的 OpenResty 安装树。

    --cwd 　　　　　　　　   安装到 ./resty_modules/ 下的当前工作目录，而不是包含在系统范围内的OpenResty 安装树这个工具。
Commands：
    build 　　　　　　　　　　　从当前工作目录构建一个包 tarball，准备上传到服务器。

    clean ARGUMENT ...   　　做清理工作。目前有效的参数是“dist”，它清理“build”命令创建的临时文件和目录。

    info PACKAGE ...     　　输出指定的详细信息（或元数据）包。像“lua-resty-lock”这样的短包名是可以接受的。

    get PACKAGE ... 　　　　获取并安装指定的包。完全合格的包装像“openresty/lua-resty-lock”这样的名字是必需的。一个还可以指定版本约束，如“=0.05”和“>=0.01”。

    list                　　列出所有已安装的软件包。包名称和版本被显示。

    remove PACKAGE ... 　　删除（或卸载）指定的包。短包名称像“lua-resty-lock”是可以接受的。

    search QUERY ... 　　　　在服务器上搜索匹配用户查询的包名称或摘要。可以指定多个查询，并且它们必须同时实现。

    server -build 　　　　构建最终的包 tarball，准备在服务器上分发。这个命令一般是服务器用来验证上传的包压缩包。

    update 　　　　　　　　将所有已安装的软件包更新到最新版本服务器。

    upgrade PACKAGE ...  将名称指定的包升级到最新版本服务器。像“lua-resty-lock”这样的短包名是可以接受的。

    upload 　　　　　　　　　将包 tarball 上传到服务器。该命令总是调用在上传之前自动生成命令。

全局安装

要全局安装 opm 包，只需使用 sudo opm get foo/bar 命令。

Back to TOC

本地安装

当您使用 --cwd 选项将软件包安装到 ./resty_modules/ 目录时，您应该将以下行放入您的 nginx.conf 中的 http {} 块内：

lua_package_path "$prefix/resty_modules/lualib/?.lua;;";
lua_package_cpath "$prefix/resty_modules/lualib/?.so;;";

不要自己将 $prefix 更改为硬编码的绝对路径！ OpenResty 将在启动时自动解析指令值中的特殊 $prefix 变量。 $prefix 值将被解析为服务器前缀，稍后将通过 openresty 命令行的 -p 选项指定。

然后你应该像这样从当前工作目录启动你的 OpenResty 应用程序：

openresty -p $PWD/

假设您在当前目录中有以下 OpenResty 应用程序目录布局：

logs/
conf/
conf/nginx.conf
resty_modules/

或者，如果您只想使用安装在 ./resty_modules 目录中的 opm 模块的 resty 命令行实用程序，那么您应该只使用 -I ./resty_modules/lualib 选项，如

resty -I ./resty_modules/lualib -e 'require "foo.bar".go()'

Back to TOC

HTTP 代理支持

通过 http_proxy 和 https_proxy 系统环境变量支持 HTTP 代理，如

http_proxy [protocol://]<host>[:port]
      Sets the proxy server to use for HTTP.

https_proxy [protocol://]<host>[:port]
      Sets the proxy server to use for HTTPS.

Back to TOC

作者工作流程

包作者应该在 Lua 库源代码树的顶层放置一个名为 dist.ini 的元数据文件。 opm build 命令使用此文件来构建库并将其打包成一个 tarball 文件，该文件可以稍后通过 opm upload 命令上传到*包服务器。

对于 OpenResty 的 lua-resty-core 库，一个示例 dist.ini 文件如下所示：

# opm 打包的分发配置
name = lua-resty-core
abstract = New FFI-based Lua API for the ngx_lua module
author = Yichun "agentzh" Zhang (agentzh)
is_original = yes
license = 2bsd
lib_dir = lib
doc_dir = lib
repo_link = https://github.com/openresty/lua-resty-core
main_module = lib/resty/core/base.lua
requires = luajit, openresty/lua-resty-lrucache >= 0.04

正如我们所见，dist.ini 文件使用流行的 INI 文件格式。此示例中的大多数字段应该是不言自明的。有关 dist.ini 中可用字段的详细文档，请查看文件 dist.ini 部分。

opm build 命令还从当前系统用户的主目录（即文件路径 ~/.opmrc）下的配置文件 .opmrc 中读取并提取信息。如果该文件不存在， opm build 将自动在该路径中生成一个样板文件。一个示例 ~/.opmrc 文件如下所示。

# 您的 github 帐户名（您拥有的 github 组织的 github 用户名）
github_account=agentzh

# 您可以从 Web UI 生成 github 个人访问令牌：https://github.com/settings/tokens
# 重要的！ 您需要将范围“user:email”和“read:org”分配给您的 github 令牌。
# 出于安全考虑，您不应将任何其他范围分配给您的令牌。
github_token=0123456789abcdef0123456789abcdef01234567

# the opm central servers for uploading openresty packages.
upload_server=https://opm.openresty.org
download_server=https://opm.openresty.org

基本上， opm build 命令只需要此文件中的 github_account 设置。尝试将打包的 tarball 上传到远程包服务器的 opm upload 命令需要其他字段。您可以使用自己的 GitHub 登录名（在本例中为 agentzh），也可以使用您拥有的 GitHub 组织名称（即拥有管理员权限）。

opm build 成功在当前工作目录下生成一个.tar.gz 文件后，作者可以使用opm upload 命令将该文件上传到远程服务器。为确保一致性，opm upload 在尝试上传操作之前自动运行 opm build 本身。*包服务器（本例中为 opm.openresty.org）在后台调用 GitHub API 来验证作者的身份。因此，作者需要在她的 ~/.opmrc 文件中提供他的 GitHub 个人访问令牌。只有 user:email 和 read:org 权限（或 GitHub 术语中的范围）需要分配给这个访问令牌。

Back to TOC

dist.ini 文件

dist.ini 文件指定了包的元数据，并被 opm build 用来生成准备上传到远程包服务器的 tarball。该文件应位于库或模块源代码树的顶部。

此文件使用 INI 文件格式。它在默认*部分中包含以下键（或属性）：

Back to TOC

name

指定包的名称（不包括版本号）。例如，

name = lua-resty-limit-traffic

名称只能包含字母、数字和短划线 (-)。

此key是强制性的。

Back to TOC

abstract

当前包的摘要。

abstract = New FFI-based Lua API for the ngx_lua module

您可以在此字段值中使用 UTF-8 字符。但是，无效的 UTF-8 序列会导致 opm build 或 opm server-build 命令出错。

此key是强制性的。

Back to TOC

version

当前包的版本号。

如果指定了这个键，那么这里指定的版本号将自动与从“主模块”文件中提取的版本号进行比较（更多详细信息请参见 main_module 键）。

Example:

version = 1.0.2

有关软件包版本号的更多详细信息，另请参阅版本号处理部分。

该键是可选的。

Back to TOC

author

指定库的一位或多位作者。例如，

author = Yichun Zhang (agentzh)

多个作者的姓名应以逗号分隔，并带有可选的空格。

author = Yichun Zhang (agentzh), Dejiang Zhu

您可以在此字段值中使用 UTF-8 字符。但是，无效的 UTF-8 序列会导致 opm build 或 opm server-build 命令出错。

此key是强制性的。

Back to TOC

许可证 (不翻译)

Specifies the license for the library. For example,

license = 3bsd

This assigns the 3-clause BSD license to the current package.

Special IDs for common code licenses are required. For now, the following IDs are supported:

2bsd

BSD 2-Clause "Simplified" or "FreeBSD" license

3bsd

BSD 3-Clause "New" or "Revised" license

apache2

Apache License 2.0

artistic

Artistic License

artistic2

Artistic License 2.0

ccby

Creative Commons Attribution 4.0 International Public License

ccbysa

Creative Commons Attribution-ShareAlike 4.0 International Public License

ccbynd

Creative Commons Attribution-NoDerivatives 4.0 International Public License

ccbync

Creative Commons Attribution-NonCommercial 4.0 International Public License

ccbyncsa

Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License

ccbyncnd

Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International Public License

cddl

Common Development and Distribution License

eclipse

Eclipse Public License

gpl

GNU General Public License (GPL)

gpl2

GNU General Public License (GPL) version 2

gpl3

GNU General Public License (GPL) version 3

lgpl

GNU Library or "Lesser" General Public License (LGPL)

mit

MIT license

mozilla2

Mozilla Public License 2.0

proprietary

Proprietary

public

Public Domain

If you do need an open source license not listed above, please let us know.

It is also possible to specify multiple licenses at the same time, as in

license = gpl2, artistic2

This specifies dual licenses: GPLv2 and Artistic 2.0.

To upload the package to the official opm package server, you must at least specify an open source license here.

This key is mandatory.

Back to TOC

依赖

指定此包的运行时依赖项。

多个依赖项用逗号分隔，周围有可选的空格。如在

requires = foo/lua-resty-bar, baz/lua-resty-blah

在运行 opm get 或 opm build 命令时，必须同时满足此键中指定的所有依赖项约束。

您还可以指定版本号要求，如

requires = foo/lua-resty-bar >= 0.3.5

支持的版本比较运算符是 >=、= 和 >。它们的语义是不言自明的。

您还可以指定以下特殊依赖项名称：

luajit

需要包用户的 OpenResty 安装（以及包上传器）中的 LuaJIT 组件。当指定版本号约束时，也会检查 LuaJIT 的版本号。

nginx

需要包用户的 OpenResty 安装（以及包上传器）中的 NGINX 组件。当指定版本号约束时，也会检查 NGINX 内核的版本号。

openresty

仅当指定了关联的版本号约束时，此依赖关系才有意义。包用户（以及上传者）的 OpenResty 安装的版本号必须满足这里的版本约束。

ngx_http_lua

需要包用户的 OpenResty 安装（以及包上传者的）中的 ngx_http_lua_module 组件。当指定版本号约束时，安装的 ngx_http_lua_module 的版本也会被检查。

下面是这样一个例子：

requires = luajit >= 2.1.0, nginx >= 1.11.2, ngx_http_lua = 0.10.6

或者您可以在上面的示例中只指定一个 openresty 版本约束来覆盖它们：

requires = openresty >= 1.11.2.1

该键是可选的。

Back to TOC

repo_link

代码存储库的 URL（通常在 GitHub 上）。例如，

repo_link = https://github.com/openresty/lua-resty-core

如果存储库位于 GitHub 上，则 opm build 确保在 ~/.opmrc 文件中的 github_account 中指定的名称与 GitHub 存储库 URL 中的帐户匹配。否则 opm build 会报错。

此key是强制性的。

Back to TOC

is_original

取值 yes or no 来指定此包是否为原创作品（即，不是其他人的另一个包的分支）。

此key是强制性的。

Back to TOC

lib_dir

指定库文件（例如 .lua 文件）的根目录。

不得使用绝对目录路径或包含 .. 作为值的路径。

默认为库。

该键是可选的。

Back to TOC

exclude_files

通过 opm bulid 指定要在打包期间排除的文件的模式。 Unix shell 通配符，如 * 和 ? 支持。

多个模式应该用逗号分隔，周围有可选的空格。

exclude_files=foo*.lua, bar/baz/*/*.lua, lint_config.lua

Back to TOC

main_module

此项指定当前包的“主模块”文件的 PATH。例如，opm build 命令读取“主模块”文件以提取当前包的版本号。

opm build 使用简单的正则表达式来查找 Lua 代码模式，如下所示：

_VERSION = '1.0.2'

version = "0.5"

version = 0.08

如果未指定此键，则 opm build 将尝试自动查找主模块文件（尽管这可能是错误的）。

您不得使用绝对文件路径或包含 .. 作为值的路径。

This key is optional.

Back to TOC

doc_dir

指定文档文件的根目录。默认为库。

不得使用绝对目录路径或包含 .. 作为值的路径。

opm build 总是尝试以 Markdown（.md 或 .markdown）或 POD（.pod）格式收集文档文件。

不管这个 doc_dir 键的值是什么， opm build 总是尝试在当前工作目录（应该是当前包的根目录）中收集以下文件：

README.md, README.markdown, or README.pod
COPYING
COPYRIGHT
Changes.md, Changes.markdown, or Changes.pod

您可以在这些文档文件中使用 UTF-8 字符。必须避免使用其他多字节字符编码。

This key is optional.

Back to TOC

.opmrc 文件

The .opmrc file under the current system user's home directory configures various important settings for the current system user. Only library authors should care about this file since commands like opm get, opm search, or opm list do not need this file at all.

Like file dist-ini, this file is also in the INI file format. When this file is absent, the first run of the opm build or opm upload commands will automatically generate a boilerplate file for you to fill out later yourself.

This file recognizes the following keys:

Back to TOC

github_account

Specifies your GitHub account name, either your GitHub user login name or github organization that you owns.

For example, the document writer's GitHub login name is agentzh while he also owns the GitHub organization openresty. So he can choose to upload his packages either under the agentzh or openresty with the same GitHub access token (defined via the github_token key) by configuring this github_account key.

This key is required.

Back to TOC

github_token

Specifies your GitHub personal access token used for package uploads.

You can generate a GitHub personal access token from the GitHub web UI.

While you are generating your token on GitHub's web site, it is crucial to assign the right permissions (or scopes in GitHub's terminology) to your token. The opm tool chain requires that the token must contain the user:email scope. Optionally, you can also assign the read:org scope at the same time, which is required if you want to upload your OpenResty packages under an organization name that you owns.

The GitHub personal access tokens are like passwords, so be very careful when handling it. Never share it with the rest of the world otherwise anybody can upload packages to the OPM package server under your name.

Due to security considerations, the package server also rejects GitHub personal access tokens that are too permissive (that is, having more scopes than needed). The package server caches a sorted hash of your tokens in its own database, so that the server does not have to query GitHub upon subsequent uploads. Because the tokens are hashed, the package server can only verifies that your token is correct but cannot recover your original token just from the database.

This key is required.

Back to TOC

upload_server

Specifies the OPM server for uploading packages. Defaults to https://opm.openresty.org. It is strongly recommended to use https (which is the default) for communication privacy.

The official OPM package server is https://opm.openresty.org. You could, however, point this key to your own or any 3rd-party servers (then you are at your own risk).

This key can have a different value than download_server.

Back to TOC

download_server

Specifies the OPM server for downloading packages. Defaults to https://opm.openresty.org. It is strongly recommended to use https (which is the default) for communication privacy.

The official OPM package server is https://opm.openresty.org. You could, however, point this key to your own or any 3rd-party servers (then you are at your own risk).

This key can have a different value than upload_server.

Back to TOC

Version Number Handling

OPM requires all package version numbers to only consist of digits, dots, alphabetic letters, and underscores. Only the digits part are mandatory.

OPM treats all version numbers as one or more integers separated by dots (.) or any other non-digit characters. Version number comparisons are performed by comparing each integer part in the order of their appearance. For example, the following version number comparisons hold true:

12 > 10
1.0.3 > 1.0.2
1.1.0 > 1.0.9
0.10.0 > 0.9.2

There can be some surprises when your version numbers look like decimal numbers, as in

0.1 < 0.02

This is because 0.1 is parsed as the integer pair {0, 1}, while 0.02 is parsed as {0, 2}, so the latter is greater than the former. To avoid such pitfalls, always specify the decimal part of the equal length, that is, writing 0.1 as 0.10, which is of the same length as 0.02.

OPM does not support special releases like "release candidates" (RC) or "developer releases" yet. But we may add such support in the future. For forward-compatibility, the package author should avoid version numbers with suffixes like _2 or rc1.

Back to TOC

Installation

For opm

OpenResty releases since 1.11.2.2 already include and install opm by default. So usually you do not need to install opm yourself.

It worth noting that if you are using the official OpenResty prebuilt linux packages, you should install the openresty-opm package since the openresty binary package itself does not contain opm.

If you really want to update to the latest version of opm in the code repository, then just copy the file bin/opm in the repository over to <openresty-prefix>/bin/ where <openresty-prefix> is the value of the --prefix option of ./configure while you are building your OpenResty (defaults to /usr/local/openresty/).

# <openresty-prefix> defaults to `/usr/local/openresty/`
# unless you override it when building OpenResty yourself.
sudo cp bin/opm <openresty-prefix>/bin/

If you are using an older version of OpenResty that does not include opm by default, then you should also create the following directories:

cd <openresty-prefix>
sudo mkdir -p site/lualib site/manifest site/pod

Note that at least OpenResty 1.11.2.1 is needed for opm to work properly.

To run the opm tool, you just need perl, tar, and curl to run the opm tool. Ensure that your perl is not too old (should be at least 5.10.1), and your curl supports SNI.

Back to TOC

Security Considerations

The opm client tool always uses HTTPS to talk to the package server, opm.openresty.org, by default. Both for package uploading and package downloading, as well as other web service queries for meta data. Although it is possible for the user to manually switch to the HTTP protocol by editing the download_server and/or upload_server keys in her own ~/.opmrc file. The opm client tool also always verifies the SSL certificates of the remote OPM package server (via curl right now).

Similarly, the OPM package server always uses TLS to talk to remote services provided by GitHub and Mailgun. These remote sites' SSL certificates are also always verified on the server side. This cannot be turned off by the user.

The OPM package server uses PostgreSQL's pgcrypto extension to encrypt the authors' GitHub personal access tokens in the database (we cache the tokens in our own database to speed up subsequent uploads and improve site reliability when the GitHub API is down). Even the server administrators cannot recover the original access tokens from the database. The server also ensures that the author's personal token is not too permissive by rejecting such tokens.

The opm tool chain and server also always perform the MD5 checksum verification upon both the downloaded and uploaded package files, to ensure data integrity when transferred over the wire.

Back to TOC

Credit

The design of the opm tool gets various inspirations from various existing package management systems, including but not limited to, Perl's cpan and Dist::Zilla, RedHat's yum, NodeJS's npm, and Mac OS X's homebrew.

Back to TOC

TODO

Add opm reinstall command to reinstall an already installed module (at the same version).
Add opm doctor command to check if there is any inconsistency in the current opm package installation tree.
Add opm files <package> command to list all the files in the specified package.
Add opm whatprovides <package> command to find out which package the specified file belongs to.
Add plugin mechanisms to opm build (similar to Perl's Dist::Zilla packaging framework).
Turn opm.openresty.org into a full-blown web site similar to search.cpan.org.
Add support for Lua C modules and LuaJIT FFI modules with standalone C libraries.
Add support for 3rd-party NGINX C modules (which can be compiled as NGINX dynamic modules).
Add (limited) support for LuaRocks via the special name space luarocks, for example,

opm get luarocks/foo

Back to TOC

Author

Yichun Zhang (agentzh) agentzh@gmail.com, OpenResty Inc.

Back to TOC

码农公寓

opm openresty的包管理器-中文文档

目录：

状态

概要

描述

用法

全局安装

本地安装

HTTP 代理支持

作者工作流程

dist.ini 文件

name

abstract

version

author

许可证 (不翻译)

依赖

repo_link

is_original

lib_dir

exclude_files

main_module

doc_dir

.opmrc 文件

github_account

github_token

upload_server

download_server

Version Number Handling

Installation

For opm

Security Considerations

Credit

TODO

Author

码农公寓

目录：

状态

概要

描述

用法

全局安装

本地安装

HTTP 代理支持

作者工作流程

dist.ini 文件

name

abstract

version

author

许可证 (不翻译)

依赖

repo_link

is_original

lib_dir

exclude_files

main_module

doc_dir

.opmrc 文件

github_account

github_token

upload_server

download_server

Version Number Handling

Installation

For opm

Security Considerations

Credit

TODO

Author

相关文章