雾和狼
概述
本文介绍如何创建、构建和发布 Lua 包，以及文档和版本管理。
先决条件
需要 Lua 和 LuaRocks
创建新包
要创建新包，可以使用 LuaRocks init 命令。这是使用本地安装的依赖项设置项目的便捷方法。该 init 命令将创建一些合理的默认值，但建议至少指定支持的 Lua 版本。
如果未定义，则项目名称将从调用命令的文件夹名称中获取，默认版本为 dev-1 。至少提供这三个选项（支持的 Lua 版本、项目名称和项目启动版本），用于初始化包的命令将如下所示。
{ luarocks init --lua-versions "5.1,5.2,5.3,5.4" my-package 1.0.0这将创建一个文件夹，主要用于配置文件，以及 lua_modules 包含本地安装的依赖项的 .luarocks 文件夹，这两个文件夹在项目目录的根目录下。
该命令还创建了两个可执行文件，并且 ./luarocks ， ./lua 提供了一种为本地项目运行命令（为本地依赖关系树配置）和默认 .gitignore 文件（包含文件夹和两个本地命令）的方法。
项目结构说明
通过LuaRocks预定义的文件和文件夹，可以将编写的所有代码都放在一个 src （源）文件夹中，包括测试。项目根目录中的另一个文件夹是用于文档的 doc 文件夹。
/*.rockRockspec
.rockspec Lua 文件，其无法访问任何 Lua 函数。编辑文件时，最好通过经常运行 LuaRocks lint 命令来检查其格式是否正确。
{ ./luarocks lintPackage metadata
项目元数据是包描述的基础。该部分只有两个必填字段， package 即软件包名称和 version 。
另一个关键配置是 rockspec_format ，许多包使用最旧的格式 1.0 。为了充分利用 .rockspec 文件，建议使用版本 3.0 ，提供最大范围的选项来描述包。
-- my-package-1.0.0-1.rockspec rockspec_format = "3.0" package = "my-package" version = "1.0.0-1"Package source
创建包时，还必须定义如何在生成和安装时实际检索内容。这是通过 source.url 属性完成的，采用多种选项，从 Git 或 Mercurial 等不同的源代码管理系统到存档文件。所有选项都可以在有关构建规则的官方 LuaRocks 文档中找到。
无论使用哪种协议或存档类型，重要的是源需要可用于所使用的上下文。这意味着，如果软件包作为存档发布到官方 LuaRocks 注册表，则 URL 需要指向公开可用的来源。如果包仅在本地使用，例如，在开发过程中，则可以使用本地文件系统来使用该协议 。
一个非常常见的用例是指向与特定分支或发布标记相结合的 Git 存储库。假设发布是通过版本标签完成的，例如，版本 1.1.0 是 Git 标签 v1.1.0 ，配置如下。
-- my-package-1.0.0-1.rockspec -- earlier options ... source = { url = "git+https://github.com/MartinHelmut/lua-series", tag = "v1.1.0" }使用特定分支:
source = { url = "https://github.com/MartinHelmut/lua-series.git", -- This is also the branch name for this article -- at the companion repository. branch = "part-2" }支持的平台
如果包仅在少数平台上受支持，则可以使用该 supported_platforms 属性。它是一个字符串数组，其中包含以下平台名称的完整列表：“unix”、“bsd”、“solaris”、“netbsd”等。
可以通过在平台名称前使用 ! as 前缀来排除不支持的平台。
supported_platforms = { "!macosx" }或者，可以给出明确支持的平台列表。
supported_platforms = { "linux", "macosx" }软件包说明
description 包含简短和详细描述、软件包许可证、链接和维护者信息，以及向软件包添加类别或标签项。
-- my-package-1.0.0-1.rockspec -- earlier options ... description = { summary = "This is a Lua series package.", detailed = "This package is for educational purposes ...", license = "MIT", homepage = "https://github.com/MartinHelmut/lua-series", issues_url = "https://github.com/MartinHelmut/lua-series/issues", maintainer = "Martin Helmut Fieber <info@martin-fieber.se>", labels = { "lua-series", "educational" } }如果定义了该 description.homepage 字段，则包用户可以使用命令 doc 通过 LuaRocks 打开主页。
{ ./luarocks doc --home依赖
在项目中声明依赖项，无论哪种类型，都是通过包含依赖项名称及其使用的版本的字符串列表完成的。安装时，将在 LuaRocks 软件包注册表中查找这些名称。
可以通过多种方式指定版本，所有这些方法都记录在有关依赖项的官方 LuaRocks 文档中。指定版本的最常见方法是通过运算符 == 、 ~= 、 < 、 > 和 <= >= ;并通过逗号 , 分隔的范围。
{ -- The first two are the same, using a -- specific version. "package1 1.0", "package1 == 1.0", -- A version smaller 2. "package2 < 2", -- Multiple, exact version 2.1 and greater -- or equal 2.3, skipping 2.2. "package3 2.1, >= 2.3", }dependencies 是用来声明项目将包含和依赖的依赖项的内容。运行 init 命令后，它已经包含一个特殊的依赖项 Lua，用于定义软件包支持的 Lua 版本。
dependencies = { "lua >= 5.1, < 5.5" }在设置项目时，可以通过 LuaRocks install 命令轻松安装该列表中的所有依赖项。
{ ./luarocks install --deps-only my-package-1.0.0-1.rockspec特定于平台的依赖项
许多 .rockspec 属性都支持特定于平台的选项，依赖项也不例外。这样，就可以仅在某些系统上安装特定的软件包或软件包版本。
dependencies = { "lua >= 5.1, < 5.5", "luaunit 3.2", platforms = { windows = { "luaunit 3.3" }, unix = { "luaunit >= 3.4" } } }为 Windows 和 macOS 定义两个不同的包版本。在所有其他平台上，将使用 LuaUnit 包的默认版本 3.2。
从 git 或 url 安装
使用 LuaRocks，还可以直接从源代码管理或 URL 安装包。其工作方式是指向远程 .rockspec 文件，例如，在 Git 存储库中，如后面的示例所示。
{ ./luarocks install https://raw.github.com/MartinHelmut/lua-series/v1.0.0/lua-series-1.0.0-1.rockspec跨服务器依赖关系跟踪
如果计划从默认的 LuaRocks 以外的其他注册表安装依赖项，则可以使用 LuaRocks 配置文件来定义多个“Rock 服务器”，这可以在 .luarocks/config.lua 文件内完成。
rocks_servers = { "http://luarocks.org/repositories/rocks" }文档
LuaRocks 支持将有关包的文档捆绑在包本身中。在 .rockspec 文件中使用 build.copy_directories 以包含一个 doc 文件夹。文件夹名称很特殊，它将是调用 luarocks doc 时使用的文件夹名称。
-- my-package-1.0.0-1.rockspec -- other options ... build = { copy_directories = { "doc" } }通过此设置，调用 LuaRocks doc 命令列出包含的文档文件。
{ ./luarocks doc my-package Documentation files for my-package 1.0.0-1 ------------------------------------------ /Users/You/Projects/my-package/1.0.0-1/doc/ Usage.md该 doc 命令还有两个选项;一个是调用它来 --home 打开默认浏览器 description.homepage 中定义的项目主页。
{ ./luarocks doc my-package --home另一个使用该 --porcelain 标志来获取所包含文档文件列表的机器可读输出。
{ ./luarocks doc my-package --porcelain /Users/You/Projects/my-package/1.0.0-1/doc/Usage.mdPure-rock
所谓的 pure-rock 是一个只包含 Lua 文件的包。安装时无需编译任何内容，并且该包通常与平台无关。尽管可以通过使用属性 supported_platforms 来限制 .rockspec 使用。
Source-rock
source-rock 是一个可能需要在安装时编译的软件包。它可以包含各种文件、构建步骤，甚至是与平台相关的代码。
Binary-rock
最后是binary-rock，通常包含特定于平台的编译 C 代码，但也包含 Lua 文件。此包类型还包含一个清单文件，用于定义所有包含的可执行文件的 MD5 校验和。
构建模块
要构建一个用 Lua 编写的项目，LuaRocks 需要知道所有 Lua 模块的位置以及如何构建它们。“内置”构建类型就足够了。为此， .rockspec 该文件将获得一个 build 表。
-- my-package-1.0.0-1.rockspec -- earlier options ... build = { type = "builtin", modules = {} }在里面 build.modules ，需要列出所有可用的模块。假设有一个 src/main.lua 包的入口点和 src/my-package/utils.lua 作为子模块。
-- my-package-1.0.0-1.rockspec -- earlier options ... build = { type = "builtin", modules = { ["my-package"] = "src/main.lua", ["my-package.utils"] = "src/my-package/utils.lua" } }或者，如果在软件包根目录中使用了名为 lua 的文件夹，则将考虑构建所有包含的文件，就好像每个文件在 build.modules 里都有一个配置项一样。
{ ./luarocks make发布你的 rock
通常有两种方法可以为 LuaRocks 发布包——一种是提供打包的源代码，例如，从 Git 或 Mercurial 存储库构建;第二种选择是通过存档（如 ZIP 或 Tarball）发布代码，并让 URL 指向它。
LuaRocks 支持 Git、CVS、Subversion 和 Mercurial。以下方式通过 Git 存储库的用法，因为其他源代码管理管理系统的用法类似。
使用代码仓库
使用 Git 存储库时，使用标记版本非常重要;否则，该包将指向开发中的最新点。如果这是所需的行为， .rockspec 则应将其版本控制为 SCM（源代码管理），从而生成类似 my-package-scm-1.rockspec 。
在任何其他情况下，都应使用正确的版本标记，例如 v1.0.0 ，对于包的第一个稳定版本（假设使用语义版本控制）。如包源部分所示，将 Git 定义为源如下所示。
source = { url = "git+https://github.com/MartinHelmut/lua-series", tag = "v1.0.0" }{ git tag v1.0.0 && git push --tags当最终打包和提交rock时，这将用于打包源代码，以便用户不需要安装相应的源代码控制系统，建议使用稳定的 URL。
使用存档
档案使用ZIP或Tarball，将所有源包含在具有相同名称和版本的文件夹中。
唯一需要保留的重要结构是带有存档中版本的顶级包名称。其他所有内容都可以根据包结构进行自定义，包括源代码、文档、测试等。
{ tar czvpf my-package-1.0.0.tar.gz my-package-1.0.0/存档需要提供一个稳定的在线 URL，并从 .rockspec 来源链接。
source = { url = "https://stable.tld/my-package/my-package-1.0.0.tar.gz" }Build rock
在打包项目进行上传之前，需要对其进行构建。该 build 命令将构建rock并将其作为依赖项安装到项目文件夹中。当只有一个 .rockspec 存在时，不需要任何参数。
{ ./luarocks build默认情况下，这将生成 .rockspec 文件提供的包。对于 Git 存储库，它将在本地克隆并从那里构建。如果不需要这样做，可以通过 标志 --pack-binary-rock 创建仅限本地的构建。
{ ./luarocks build --pack-binary-rock发布
项目构建完成后，要实际发布rock，需要 luarocks.org 帐户。在帐户设置页面中，需要创建一个新的 API 密钥，以便使用该 luarocks upload 命令。
{ ./luarocks pack my-package-1.0.0-1.rockspec{ ./luarocks install lua-cjson{ ./luarocks upload my-package-1.1.0-1.rockspec --api-key=<API_KEY_HERE>然后可以在 LuaRocks 上找到成功发布的包。
版本管理
创建新版本
对项目进行更改后，可以通过 luarocks new_version 创建新版本。运行此命令将创建一个具有更新版本号的新 .rockspec 文件。
-- my-package-1.1.0-1.rockspec rockspec_format = "3.0" package = "my-package" version = "1.1.0-1" source = { url = "git+https://github.com/MartinHelmut/lua-series", tag = "v1.1.0" }
