如何编写发布Arduino库

Posted 2021-08-13 三明治开发社区

如何编写一个Arduino库？在你的库编写完成后，如果你想要通过Arduino IDE中的库管理工具来下载你的库，又该如何做呢？

本文将分享如何让你编写的Arduino库可以通过Arduino IDE下载。

Arduino 库文件结构和作用

首先我们先对Arduino的库文件格式进行一个简单的了解，对于一个Arduino 库来说，下面的文件夹和文件几乎是必须的

├── examples	//例程存放的文件夹
├── src	//库源代码存放的文件夹
├── extras	//其他文件存放的文件夹（PDF什么的）
├── keywords.txt	//关键字文件
└── library.properties	//库特性说明文件

2 directories, 2 files

examples 文件夹介绍

examples 文件夹是用来存放例程的，例程文件是一个Arduino工程，即每一个例程放在一个文件夹中，文件夹的名字和例程的名字一样。例如有三个例程，名字分别叫one, two, three。那么在这三个例程的文件结构应为：

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

src 文件夹介绍

src文件夹是用来存放库源代码的文件。

extras 文件夹介绍

extras文件夹用来放置文档或其他与库捆绑的项目。Arduino IDE 不会理会 extra文件夹的内容，该文件夹你可以随便放任何东西。但是，放在这个文件夹里的文件会增加库的大小，所以在一个只有几 kb 的库里放一个20MB的PDF可能不是一个好主意。

keywords.txt 文件介绍

keywords.txt 文件的作用是用来在Arduino IDE中使一些类名、函数名等显示不同的颜色。

该文件的语法为

keyword[tab]KEYWORD_TOKENTYPE

keyword 是要用来高亮显示的关键字类名、函数名和常量名等

[tab] 为一个tab缩进（不要是空格！！！）

KEYWORD_TOKENTYPE 的取值为 KEYWORD1, KEYWORD2, KEYWORD3, LITERAL1, LITERAL2

在Arduino IDE的关键字高亮中，会识别KEYWORD1为数据类型高亮，KEYWORD2为函数高亮，KEYWORD3为结构体高亮，LITERAL1为常量。

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

library.properties 文件介绍

library.properties 文件的内容格式是一个key=value 属性列表。（注意使用UTF-8编码）

library.properties 文件中的可以用的字段有以下几种：

• name - 库名。库名可使用的字符有大写英文字母（A-Z），小写英文字母（a-z），阿拉伯数字（0-9），空格（ ），下划线（_），点（.）和破折号（-）。库名以字母或数字开头。不要使用Arduino开头，这是官方给自己预留的；

• version - 库版本。版本应符合semver标准。可以使用1.2.0或1.2；不能使用 r5、003、1.1c ；

• author - 库的作者名字和作者的电子邮件地址（不是必须的），多个作者时可以用逗号（,）分开；

• maintainer - 库维护者的姓名和电子邮件；

• sentence - 用一句话描述这个库的作用；

• paragraph - 用于详细描述这个库；

• category - （默认为Uncategorized）value为：

  • Display
  • Communication
  • Signal Input/Output
  • Sensors
  • Device Control
  • Timing
  • Data Storage
  • Data Processing
  • Other

  大家望文生义的选择就可以了，可以选择多个分类词用, (英文逗号)隔开；

• url - 库项目的链接，一般为该库存放的github仓库的链接；

• architectures - (value默认使用 *)；

• depends - 该字段为可选字段（从IDE 1.8.10/Arduino CLI 0.7.0版本开始可用）。该字段的作用是如果你编写的库依赖于Arduino中的其它库，使用逗号分隔的依赖项列表，Arduino IDE的库管理器将在安装你的库的过程中安装提供依赖的库；

• dot_a_linkage - 该字段为可选字段（从Arduino IDE 1.6.0 / arduino-builder 1.0.0-beta13版本开始可用）。当该字段设备为true，将会将你的库封装为静态库文件；

• includes - 该字段为可选字段（从Arduino IDE 1.6.10版本开始可用）。使用逗号分割列表，如果没有该字段将会将源目录下的所有.h 文件都包含在内；

• precompiled - 该字段为可选字段（从Arduino IDE 1.8.6/arduino-builder 1.4.0版本开始可用）。对静态库和动态库进行支持。有两个支持的值：

  • true - 源文件总是被编译。在Arduino IDE 1.8.12/arduino-builder 1.5.2/Arduino CLI 0.8.0中该功能丢失了不支持，在Arduino IDE 1.8.13/arduino-builder 1.5.3/Arduino CLI 0.11.0中恢复了。
  • full - （从Arduino IDE 1.8.13/arduino-builder 1.5.3/Arduino CLI 0.11.0版本开始可用）。如果该库为正在编译的板子提供了一个预编译库，那么源文件将不会被编译。如果没有提供，源文件将被编译。可以减少编译时间。

• ldflags - 该字段为可选字段（从available from Arduino IDE 1.8.6/arduino-builder 1.4.0版本开始可用）。要添加的链接器标志。例如：ldflags=-lm。

示例：

库的根目录文件夹

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

使你的库在Arduino IDE 库管理中可以被搜索到

1. 将你的库上传到github中，需要创建一个和 library.properties 文件中的version 一致的 release 或 tag。

2. 去arduino的Arduino仓库提issue ，等待管理员审核完成后将你的库添加进去就可以了。issue内容可以参考下面。提完issue，等待管理员审核完成即可，如果有问题的话管理员也会在issue里面回复你的，可以多关注一下你的issue。

   

   （各位老爷觉得不错的话，给GitHub仓库赏个⭐吧）