三分钟教学：手把手教你实现Arduino发布第三方库

YourLibraryName/
  ├── src/                         // 源代码目录（必须）
  │    ├── YourLibraryName.h       // 头文件
  │    └── YourLibraryName.cpp     // 源文件
  ├── examples/                    // 示例代码目录（可选但推荐）
  │    └── one/                    // 第一个示例代码文件夹
  │        └── one.ino             // 示例代码1
  │    └── two/                    // 第二个示例代码文件夹
  │        └── two.ino             // 示例代码2
  │    └── three/                  // 第三个示例代码文件夹
  │        └── three.ino           // 示例代码3
  ├── library.properties           // 库的元数据文件（必须）
  ├── keywords.txt                 // 语法高亮关键字（可选）
  ├── README.md                    // 文档
  └── LICENSE                      // 许可证

1.1 src/ `-` 源代码目录（必须）

在这个目录下，存放的是库的核心代码，主要包含。

YourLibraryName.h：头文件，声明你的库的类、函数以及其他需要公开的接口。
YourLibraryName.cpp：源文件，定义你在头文件中声明的函数和类的具体实现。

1.2 examples/ - 示例代码目录（可选但推荐）

examples 文件夹是用来存放例程的，帮助用户快速理解并使用你的库函数。

例程文件就是一个 .ino 文件，而且每一个例程放在一个文件夹中，文件夹和例程的名字需要把保持一样。

例如有三个例程，名字分别叫 one, two, three。

那么在这三个例程的文件结构应为：

bash 复制代码

── examples
    ├── one
    │   └── one.ino
    ├── two
    │   └── two.ino
    └── three
        └── three.ino

1.3 library.properties - 库的元数据文件（必须）

这是库的核心文件，包含关键信息，如库的名称、版本、作者、依赖关系等。

它是 Arduino IDE 正确识别和加载库所必须的，Arduino IDE 会根据它来识别库的相关信息。一个简单的 library.properties 文件如下：

bash 复制代码

name=MyLibrary
version=1.0.0
author=Your Name
maintainer=Your Email
sentence=MyLibrary is a simple library for controlling sensors.
paragraph=MyLibrary allows you to easily control sensors and devices.
category=Sensor
url=https://github.com/yourusername/MyLibrary
architectures=*

这个文件采用 INI文件格式（注意使用UTF-8****编码）， 该文件通常以键值对 的形式存储信息，一行一个属性，以下是它的常见字段说明：

字段	作用	示例
name	库的名称	`name=MyLibrary`
version	版本号	`version=1.2.0`
author	作者	`author=Someone`
maintainer	维护者	`maintainer=SomeoneElse`
architectures	支持的架构	`architectures=esp32`
sentence	库的简要描述	`sentence=A lightweight servo control library.`
category	库的分类	`category=Communication`
url	项目地址	url=``https://github.com/leezisheng/serial-servo
license	许可证	`license=MIT`

关于这部分的详细编写规范可以参考官方文档

1.4 keywords.txt - 语法高亮关键字（可选）

keywords.txt 文件用于定义库中的关键字（如函数、类等），以便在 Arduino IDE 中提供语法高亮显示，提升代码可读性。

该文件的语法为：

复制代码

keyword[tab]KEYWORD_TOKENTYPE

每行包含一个关键字及其对应的关键字类型，二者之间使用制表符（Tab）分隔。

关键字类型决定了关键字在 Arduino IDE 中的高亮显示方式，常用的关键字类型包括：

KEYWORD1：通常用于库的类名。
KEYWORD2：通常用于库的函数名。
KEYWORD3：通常用于常量（如宏定义）。
LITERAL1 和 LITERAL2：用于字面值常量。

KEYWORD_TOKENTYPE	Use for	Theme property
`KEYWORD1`	datatypes	`editor.data_type.style`
`KEYWORD2`	functions	`editor.function.style`
`KEYWORD3`	structures	`editor.function.style`
`LITERAL1`	constants	`editor.reserved_word_2.style`
`LITERAL2`	?	`editor.function.style`

1.5 README.md - 说明文档（可参考上期）

README.md 是你库的介绍文件，通常包含：

如何安装和使用库
库的功能说明
可能的配置选项
示例代码
常见问题解答等

1.6 LICENSE - 许可证（可参考上期）

LICENSE 文件用于明确库的使用许可条款，告知用户在使用、修改和分发您的代码时的权利和限制。

1.7 `extras/` - 补充资源目录

extras 文件夹用于存放与库相关的文档或其他附加项目。Arduino IDE 不会处理 extras 文件夹中的内容，因此您可以根据需要在此文件夹中添加任何文件。

我们 README.md 文件中的图片可以放到该文件夹中

2. 将库打包

把以上文件放到一个文件夹中，确保文件夹名称与你的库名称一致。

例如，如果你的库叫 YourLibraryName，那么文件夹的名称应该是 YourLibraryName，里面包含以下文件：

bash 复制代码

YourLibraryName/
  ├── src/                         // 源代码目录（必须）
  │    ├── YourLibraryName.h       // 头文件
  │    └── YourLibraryName.cpp     // 源文件
  ├── examples/                    // 示例代码目录（可选但推荐）
  │    └── one/                    // 第一个示例代码文件夹
  │        └── one.ino             // 示例代码1
  │    └── two/                    // 第二个示例代码文件夹
  │        └── two.ino             // 示例代码2
  │    └── three/                  // 第三个示例代码文件夹
  │        └── three.ino           // 示例代码3
  ├── library.properties           // 库的元数据文件（必须）
  ├── keywords.txt                 // 语法高亮关键字（可选）
  ├── README.md                    // 文档
  └── LICENSE                      // 许可证

Arduino 库的根文件夹名称必须以基本字母（A-Z 或 a-z）或数字（0-9）开头，可以使用基本字母、数字、下划线（_）、点（.）和破折号（-）。文件夹名最大长度为 63 个字符。

3.上传到 `GitHub`

将你的库上传到 GitHub，或者你可以选择其他的代码托管平台。

发布完成之后，就可以填写 url.

4.创建发布 `Release` 和标签 `Tag`

4.1 在 `GitHub` 上创建 `Tag`

点击 Tag 图标，可以看到不同版本的 Tag 记录：

4.1.1 什么是 `Tag`

Tag 是 Git 中的一种标记，用于指向某个特定的提交 commit，它通常用于标记重要的版本点（如 v1.0.0）：

类型：
- 轻量标签Lightweight Tag：只是一个指向某个提交的指针。
- 附注标签Annotated Tag：包含额外的元数据，如标签名称、作者、日期和描述信息。
用途：用于标记版本号、里程碑或重要的代码状态。

4.1.2 创建步骤

首先打开 Git Bash，创建带注释的 Tag（通常用于版本发布）：

bash 复制代码

git tag -a v1.0.0 -m "First stable release"

-a v1.0.0：指定标签名称（例如 v1.0.0）。
-m "First stable release"：为标签添加描述信息。

查看所有Tags：

bash 复制代码

git tag

创建 Tag 后，必须将其推送到 GitHub 才能让其他人看到。

推送单个 Tag：

bash 复制代码

git push origin v1.0.0

推送所有本地的 Tags：

bash 复制代码

git push origin --tags

然后就可以在 Github 仓库中，就可以看到提交的 Tag 了：

4.2 创建发布 `release`

4.2.1 什么是 `release`

Release 是 GitHub 提供的一个功能，基于 Tag 创建，用于发布软件的特定版本。

它可以包含一个 Tag、版本描述（如新特性、修复的 Bug）、附加的文件（如编译好的二进制文件、安装包）等，主要用于正式发布软件的版本，方便用户下载和使用。

注意：Release 必须基于一个 Tag。没有 Tag，就无法创建 Release。可以理解为Release 是对 Tag 的扩展，提供了更丰富的功能（如版本描述、附加文件）。

在使用场景上，Tag 适合标记内部开发中的版本或里程碑，而 Release 适合正式发布版本，供用户下载和使用。

4.2.2 发布步骤

访问你的 GitHub 仓库 ，在仓库的页面中，点击上方的 "Releases" 标签。

在 Releases 页面上，点击 "Draft a new release" 按钮。

选择 Tag：

在 "Tag version" 字段中，选择之前创建的 Tag（例如，v1.0.0）。如果你还没有创建 Tag，可以在这里创建新的 Tag。
如果需要，可以点击 "Create new tag" 并为其指定版本号（例如 v1.0.1）。

填写 Release 信息：

Release title ：为发布版本提供一个标题（例如 Version 1.0.0 - First Stable Release）。
Description：在描述框中添加该版本的详细说明，包括新特性、已修复的 bug 或任何变更。

附加文件（可选）：

你可以上传附加的二进制文件、构建文件或源代码的压缩包。
点击 "Attach binaries by dropping them here or selecting them"，选择文件进行上传。

发布Release：

选择发布方式：
- Pre-release ：如果这个版本还不稳定，可以选择勾选 "This is a pre-release" 选项，表示它是一个预发布版本。
- 如果版本已经稳定，直接点击 "Publish release" 按钮。

5.提交到 `Arduino` 库管理器

5.1Fork Arduino Library Registry

访问 Arduino 库注册页面

打开 Arduino Library Registry GitHub 页面。

Fork仓库

在页面上，你会看到 "Create a new fork" 按钮。点击该按钮，GitHub 会开始创建一个库的副本，这样你可以对其进行修改。

等待Fork完成

在 "Forking arduino/library-registry" 页面上，GitHub 会显示一个进度条，表示正在进行 Fork 操作。等到 Fork 完成后，GitHub 会自动跳转到你自己的仓库主页：

https://github.com/leezisheng/library-registry

5.2 编辑repositories.txt

访问 repositories.txt 文件

在你的 Fork 仓库主页中，找到 repositories.txt 文件。这个文件记录了所有已提交到 Library Manager 的库的仓库地址。点击这个文件名进入文件内容页面。

编辑 repositories.txt 文件

在 repositories.txt 文件页面中，点击右上角的铅笔图标（"Edit this file"）进入编辑模式。

添加你的库的 URL

在编辑器中，将你的库的 GitHub 仓库 URL 添加到列表中。你可以将 URL 添加到列表的任何位置。示例 URL 格式如下：

https://github.com/yourusername/your-library

确保这个 URL 是你库的 GitHub 仓库首页链接。

提交修改

编辑完成后，点击页面顶部的 Commit changes... 按钮。提交框会打开，你可以在这里为你的提交输入描述信息。输入描述后，点击 Commit changes 完成提交。

5.3 提交Pull Request

返回你的 Fork 仓库首页

提交更改后，你会回到 repositories.txt 文件页面。此时你会看到一个提醒，表示你在这个分支上做了修改："This branch is 1 commit ahead of arduino:main"。

打开 Pull Request

点击页面顶部的 Contribute 按钮，然后选择 Open pull request 。这会打开创建 Pull Request 的页面。

填写 Pull Request 信息

在 Pull Request 页面中，填写适当的标题和描述，说明你所做的更改。

创建 Pull Request

点击 Create pull request 按钮提交。这样，Arduino 的库管理系统将自动检查你提交的库是否符合要求。如果没有问题，Pull Request 会被合并，并且你的库将在一天内可通过 Library Manager 安装。

5.4 处理检查结果和错误

自动检查

一旦你提交了 Pull Request，Arduino 的自动检查系统将开始检查你库的合规性。检查会包括库的结构、library.properties 文件的格式、版本号、文档等。

检查失败或有问题的情况

如果 Pull Request 本身有问题 ，机器人会在 Pull Request 中留言，告知你需要修改的地方。你可以通过编辑你 Fork 仓库中的文件并提交更新来解决问题。

如果库本身有问题 ，你需要在你库的 GitHub 仓库中进行修复，更新 library.properties 文件中的版本号，并确保该库有一个有效的 Release 或 Tag （具体要求见下文）。修复后，重新创建一个 Release 或 Tag，并通知 ArduinoBot 来触发自动检查。

解决问题后重新提交

如果是 Pull Request 的问题，修改完毕后，提交新的修改，自动检查会重新运行。

如果是库本身的问题 ，完成修复并更新版本后，创建新的 Release 或 Tag，并通知 ArduinoBot，这样检查将重新进行。

重新提交并通过审核

只要检查通过，Pull Request 会被合并，你的库将在一天内通过 Library Manager 提供给全体用户。

https://github.com/arduino/library-registry/pull/5863

我们也可以在库管理器索引器查看库的日志：

http://downloads.arduino.cc/libraries/logs/github.com/leezisheng/SerialServo/

5.5 在 `Arduino` 中进行验证

然后就是在库版本管理器中搜索：

参考

https://zhuanlan.zhihu.com/p/389718578

三分钟教学：手把手教你实现Arduino发布第三方库

三分钟教学：手把手教你实现Arduino发布第三方库

原文链接：

摘要

往期推荐：

更多精彩内容可看：

0.引言

1.库文件基本框架

1.1 src/ - 源代码目录（必须）

1.2 examples/ - 示例代码目录（可选但推荐）

1.3 library.properties - 库的元数据文件（必须）

1.4 keywords.txt - 语法高亮关键字（可选）

1.5 README.md - 说明文档（可参考上期）

1.6 LICENSE - 许可证（可参考上期）

1.7 extras/ - 补充资源目录

2. 将库打包

3.上传到 GitHub

4.创建发布 Release 和 标签 Tag

4.1 在 GitHub 上创建 Tag

4.1.1 什么是 Tag

4.1.2 创建步骤

4.2 创建发布 release

4.2.1 什么是 release

4.2.2 发布步骤

5.提交到 Arduino 库管理器

5.1Fork Arduino Library Registry

5.2 编辑repositories.txt

5.3 提交Pull Request

5.4 处理检查结果和错误

5.5 在 Arduino 中进行验证

参考

1.1 src/ `-` 源代码目录（必须）

1.7 `extras/` - 补充资源目录

3.上传到 `GitHub`

4.创建发布 `Release` 和标签 `Tag`

4.1 在 `GitHub` 上创建 `Tag`

4.1.1 什么是 `Tag`

4.2 创建发布 `release`

4.2.1 什么是 `release`

5.提交到 `Arduino` 库管理器

5.5 在 `Arduino` 中进行验证