35 lines
3 KiB
ReStructuredText
35 lines
3 KiB
ReStructuredText
创建示例项目
|
||
============
|
||
|
||
每个 ESP-IDF 的示例都是一个完整的项目，其他人可以复制并修改代码以解决他们自己的问题。请注意，示例项目的主要目的是为了展示 ESP-IDF 的功能。
|
||
|
||
示例项目结构
|
||
------------
|
||
|
||
- ``main`` 目录需要包含一个名为 ``(something)_example_main.c`` 的源文件，里面包含示例项目的主要功能。
|
||
- 如果该示例项目的子任务比较多，请根据逻辑将其拆分为 ``main`` 目录下的多个 C 或者 C++ 源文件，并将相应的头文件放在同一目录下。
|
||
- 如果该示例项目具有多种功能，可以考虑在项目中增加一个 ``components`` 子目录，以组件的形式为示例项目提供服务。如果该组件提供的功能具有一定的通用性和完整性，则应该将它们添加到 ESP-IDF 的 ``components`` 目录中，使其成为 ESP-IDF 的一部分。
|
||
- 示例项目需要包含一个 ``README.md`` 文件，建议在 :idf_file:`示例项目 README 模板 <docs/TEMPLATE_EXAMPLE_README.md>` 的基础上进行修改，使其适配你的项目。
|
||
- 示例项目需要包含一个 ``example_test.py`` 文件，用于自动化测试本示例项目。如果在 GitHub Pull Request 上初次提交示例项目，可以先不包含这个脚本文件，该文件的实现细节可以在后续的 PR 中进行讨论。
|
||
|
||
一般准则
|
||
--------
|
||
|
||
示例代码需要遵循 :doc:`《乐鑫物联网开发框架风格指南》 <style-guide>`。
|
||
|
||
检查清单
|
||
--------
|
||
|
||
提交示例项目之前需要检查的清单如下：
|
||
|
||
- 示例项目的名字（在 ``Makefile`` 和 ``README.md`` 中）使用单词 ``example`` 而不是 “demo”，“test” 类似的单词。
|
||
- 示例项目的目的只能有一个，如果有多个，请将它们拆分为两个或更多示例项目。
|
||
- 示例项目中需要包含一个 ``README.md`` 文件，建议使用 :idf_file:`示例项目 README 模板 <docs/TEMPLATE_EXAMPLE_README.md>`。
|
||
- 示例项目中的函数和变量的命令要遵循 :ref:`命名规范 <style-guide-naming>` 中的要求。
|
||
- 示例项目中的所有代码结构良好，并且关键代码有详细注释。
|
||
- 示例项目中清除不必要的代码（旧的调试日志，注释掉的代码等）。
|
||
- 示例项目中用使用的选项（比如网络名称，地址等）不应该被硬编码，尽可能地使用可配置项或者宏定义和常量。
|
||
- 配置项在 ``KConfig.projbuild`` 文件中提供，该文件中包含有名为 “Example Configuration” 的菜单。查看现有的示例项目以了解如何实现该操作。
|
||
- 所有的原始代码都需要在文件开头指定许可证和免责声明，表示它 ``in the public domain CC0``。或者，示例项目可以在 ``Apache License 2.0`` 协议下获得许可。请查看已有的示例项目然后做相应的修改。
|
||
- 任何改动的或直接使用的第三方代码都需要在文件开头声明其原始的许可证，且该许可证必须要与 ``Apache License 2.0`` 协议兼容。
|