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

*运行pub get之后, .dart_tool目录和.packages文件存在. 不要将它们检查到源代码管理中.

**运行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的许可证文件,并可以选择扩展名为.md的文件. 我们建议使用OSI批准的许可证,例如BSD-3-Clause,以便其他人可以重用您的工作.

README

enchilada/
  README.md

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

如果您的自述文件以.md结尾,则将其解析为Markdown.

CHANGELOG

enchilada/
  CHANGELOG.md

要向用户显示对软件包的最新更改,可以包括一个changelog文件,您可以在其中写下有关最新版本中的更改的简短说明. 当您将软件包上传到pub.dev站点时,软件包的changelog文件(如果有)出现在changelog选项卡中.

如果您的CHANGELOG以.md结尾,则将其解析为Markdown.

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软件包中运行脚本.

If you intend for your package to be depended on, and you want your scripts to be private to your package, place them in the top-level tool directory. If you do not intend for your package to be depended on, you can leave your scripts in bin.

Public assets

enchilada/
  lib/
    guacamole.css

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

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

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

Implementation files

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

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

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

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

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

The name you use here (in this case enchilada) is the name you specify for your package in its 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/readme[.md]
  • example/example[.md]
  • example[/lib]/main.dart
  • example[/lib]/package_name.dart
  • example[/lib]/package_name_example.dart
  • example[/lib]/example.dart

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

Internal tools and scripts

enchilada/
  tool/
    generate_docs.dart

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

bin的脚本不同,这些脚本不适用于程序包的外部用户. 如果有这些,请将它们放在名为tool的目录中.

by  ICOPY.SITE