Contents

Package layout conventions

当您构建pub软件包时 ,建议您遵循本页描述的约定. 它们描述了如何组织程序包中的文件和目录,以及如何命名事物.

这是使用这些准则的各个方面的完整软件包(名为enchilada )的样子:

enchilada/
  .dart_tool/ *
  .packages *
  pubspec.yaml
  pubspec.lock **
  LICENSE
  README.md
  CHANGELOG.md
  benchmark/
    make_lunch.dart
  bin/
    enchilada
  doc/
    api/ ***
    getting_started.md
  example/
    main.dart
  lib/
    enchilada.dart
    tortilla.dart
    guacamole.css
    src/
      beans.dart
      queso.dart
  test/
    enchilada_test.dart
    tortilla_test.dart
  tool/
    generate_docs.dart
  web/
    index.html
    main.dart
    style.css

* The .dart_tool directory and .packages file exist after you’ve run pub get. Don’t check them into source control.

**运行pub get之后, pubspec.lock文件存在. 除非您的软件包是应用程序软件包,否则请使其脱离源代码控制.

***运行dartdoc后, doc/api目录在本地存在. 不要将api目录检入源代码管理.

The pubspec

enchilada/
  pubspec.yaml
  pubspec.lock

每个软件包在软件包的根目录中都有一个pubspec (一个名为pubspec.yaml的文件). 这就是使它成为包装的原因.

在软件包上运行pub getpub upgradepub downgrade会创建一个名为pubspec.lock 文件 . 如果您的软件包是应用程序软件包 ,请将锁定文件检查到源代码管理中. 否则,请不要.

有关更多信息,请参见pubspec页面 .

LICENSE

enchilada/
  LICENSE

如果要发布软件包,请包含一个名为LICENSE的许可证文件. 我们建议使用OSI批准的许可证(例如BSD-3-Clause),以便其他人可以重用您的工作.

README.md

enchilada/
  README.md

在开源中非常常见的一个文件是描述项目的README文件. 这在酒吧中尤其重要. 当您上传到pub.dev站点时,您的README.md文件将在您的软件包页面上显示(呈现为Markdown) . 这是向人们介绍您的代码的理想场所.

CHANGELOG.md

enchilada/
  CHANGELOG.md

包括一个CHANGELOG.md文件,该文件的每个发行版都有一个小节,并带有帮助您升级软件包用户的注释. 软件包的用户经常查看变更日志,以发现错误修复和新功能,或确定升级到软件包的最新版本将花费多少精力.

要支持解析CHANGELOG.md工具,请使用以下格式:

  • 每个版本都有其自己的带有标题的部分.
  • 版本标题是全部1级或全部2级.
  • 版本标题文本包含软件包版本号,可以选择以" v"为前缀.

当您将包上传到pub.dev站点时,包的CHANGELOG.md文件(如果有)出现在Changelog选项卡中,显示为Markdown.

这是CHANGELOG.md文件的示例. 如示例所示,您可以添加小节.

# 1.0.1

* Fixed missing exclamation mark in `sayHi()` method.

# 1.0.0

* **Breaking change:** Removed deprecated `sayHello()` method.
* Initial stable release.

## Upgrading from 0.1.x

Change all calls to `sayHello()` to instead be to `sayHi()`.

# 0.1.1

* Deprecated the `sayHello()` method; use `sayHi()` instead.

# 0.1.0

* Initial development release.

Public directories

软件包中的两个目录对其他软件包是公共的: libbin . 您将公共库放置在lib ,将公共工具放置在bin .

Public libraries

以下目录结构显示了辣酱玉米饼馅的lib部分:

enchilada/
  lib/
    enchilada.dart
    tortilla.dart

许多软件包都是库软件包 :它们定义了其他软件包可以导入和使用的Dart库. 这些公共Dart库文件位于名为lib的目录中.

大多数软件包都定义了一个用户可以导入的库. 在这种情况下,其名称通常应与包的名称相同,例如此处示例中的enchilada.dart . 但是,您也可以使用对您的程序包有意义的任何名称来定义其他库.

完成后,用户可以使用包名称和库文件导入这些库,如下所示:

import 'package:enchilada/enchilada.dart';
import 'package:enchilada/tortilla.dart';

如果要组织公共库,还可以在lib内创建子目录. 如果这样做,用户将在导入时指定该路径. 假设您具有以下文件层次结构:

enchilada/
  lib/
    some/
      path/
        olives.dart

用户按以下方式导入olives.dart

import 'package:enchilada/some/path/olives.dart';

注意,只有应该在lib . 入口点-具有main()函数的Dart脚本-不能进入lib . 如果将Dart脚本放在lib ,则会发现任何package:导入其中包含的package:都无法解析. 相反,您的入口点应该放在适当的入口点目录中 .

有关库软件包的更多信息,请参见创建软件包 .

Public tools

放置在bin目录中的Dart脚本是公共的. 如果您位于软件包的目录中,则可以使用pub run从该软件包依赖的任何其他软件包的bin目录中运行脚本. 在任何目录中,您都可以使用pub global run从使用pub global activate软件包中运行脚本.

如果您打算依赖您的软件包,并且希望脚本对软件包是私有的,请将它们放在顶层tool目录中. 如果您不希望依赖软件包,则可以将脚本保留在bin .

Public assets

enchilada/
  lib/
    guacamole.css

现有大多数库程序包可让您重用Dart代码,但您也可以重用其他类型的内容. 例如,用于Bootstrap的软件包可能包括许多CSS文件,供该软件包的使用者使用.

这些位于顶级lib目录中. 您可以在其中放置任何类型的文件,并根据需要使用子目录对其进行组织.

您可以使用资源包引用另一个包的资产.

Implementation files

enchilada/
  lib/
    src/
      beans.dart
      queso.dart

lib中的库是公开可见的:其他软件包可以自由导入. 但是,程序包的大部分代码是内部实现库,仅应由程序包本身导入和使用. 它们位于lib的子目录src . 如果可以帮助您组织事物,则可以在其中创建子目录.

您可以从同一个程序包中的其他Dart代码中导入位于lib/src中的库(如lib其他库, bin和测试中的脚本),但是绝对不要从另一个程序包的lib/src目录中导入. 这些文件不是软件包公共API的一部分,它们可能会以破坏代码的方式进行更改.

当您在自己的程序包中使用库时,即使是src代码,也可以(并且应该)仍然使用package:来导入它们. 例如:

import 'package:enchilada/src/beans.dart';

您在此处使用的名称(本例中为enchilada )是您在其pubspec中为软件包指定的名称.

Web files

enchilada/
  web/
    index.html
    main.dart
    style.css

对于Web软件包,将入口点代码main()包含main()和支持文件,如CSS或HTML main()的Dart脚本放置在web下. 如果愿意,可以将web目录组织到子目录中.

库代码放在lib下. 如果该库不是由web下的代码或其他软件包直接导入的,请将其放在lib/src . 将基于网络的示例放在example之下. 有关将资产放置在何处的提示,请参见公共资产 ,例如图像.

Command-line apps

enchilada/
  bin/
    enchilada

一些软件包定义了可以直接从命令行运行的程序. 这些可以是Shell脚本或任何其他脚本语言,包括Dart. pub应用程序本身就是一个示例:它是一个简单的shell脚本,它调用pub.dart .

如果您的程序包定义了这样的代码,请将其放在名为bin的目录中. 如果使用pub global设置脚本,则可以从命令行的任何位置运行该脚本.

Tests and benchmarks

enchilada/
  test/
    enchilada_test.dart
    tortilla_test.dart

每个包装都应进行测试. 对于pub,约定是将它们放在test目录(如果需要,也可以放在其中的某个目录)中,并在文件名末尾带有_test .

通常,这些使用测试包.

enchilada/
  benchmark/
    make_lunch.dart

具有性能关键代码的软件包还可能包含基准测试 . 这些测试不是为了正确性而是为了速度(或内存使用,或其他经验指标)来测试API.

Documentation

enchilada/
  doc/
    api/
    getting_started.md

如果您有代码和测试,那么您可能需要的下一部分是好的文档. 那位于名为doc的目录内.

运行dartdoc工具时,默认情况下,它将API文档放置在doc/api . 由于API文档是从源代码生成的,因此您不应将其置于源代码控制之下.

除了生成的api ,我们没有关于您编写​​的文档的格式或组织的准则. 使用您喜欢的任何标记格式.

Examples

enchilada/
  example/
    main.dart

代码,测试,文档,您的用户还想要什么? 当然,使用您的软件包的独立示例程序! 这些放在example目录中. 如果示例很复杂并且使用多个文件,请考虑为每个示例创建一个目录. 否则,您可以将每一个放置在example .

在您的示例中,使用package:从您自己的包中导入文件. 这样可以确保程序包中的示例代码看起来与程序包外部的代码看起来完全一样.

如果您可能发布软件包,请考虑使用以下名称之一创建示例文件(不区分大小写):

  • example/example[.md]
  • example[/lib]/main.dart
  • example[/lib]/package_name.dart
  • example[/lib]/package_name_example.dart
  • example[/lib]/example.dart
  • example/readme[.md]

发布包含以上一个或多个文件的软件包时,pub.dev站点将创建一个" 示例"选项卡,以显示找到的第一个文件(按上面列表中显示的顺序搜索). 例如,如果包的example目录下有很多文件,包括名为README.md的文件,则包的"示例"选项卡将显示example/README.md的内容(解析为Markdown).

Internal tools and scripts

enchilada/
  tool/
    generate_docs.dart

成熟的程序包通常很少有人在开发程序包本身时运行的帮助程序脚本和程序. 考虑诸如测试运行程序,文档生成器或其他自动化方面的事情.

Unlike the scripts in bin, these are not for external users of the package. If you have any of these, place them in a directory called tool.

by  ICOPY.SITE