Contents

The pubspec file

Every pub package needs some metadata so it can specify its dependencies. Pub packages that are shared with others also need to provide some other information so users can discover them. All of this metadata goes in the package’s pubspec: a file named pubspec.yaml that’s written in the YAML language.

Supported fields

pubspec可以具有以下字段:

name
每个包装都必需. 学到更多.
version
Required for packages that are hosted on the pub.dev site. Learn more.
description
对于pub.dev站点上托管的软件包来说是必需的. 学到更多.
homepage
可选的. 指向软件包主页(或源代码存储库)的URL. 学到更多.
repository
可选的. 指向软件包的源代码存储库的URL. 学到更多.
issue_tracker
可选的. 指向程序包问题跟踪器的URL. 学到更多.
documentation
可选的. 指向软件包文档的URL. 学到更多.
dependencies
如果您的程序包没有依赖项,则可以省略. 学到更多.
dev_dependencies
如果您的软件包没有开发依赖项,可以省略. 学到更多.
dependency_overrides
如果不需要覆盖任何依赖项,可以省略. 学到更多.
environment
从Dart 2开始是必需的. 了解更多信息.
executables
可选的. 用于将软件包的可执行文件放在PATH上. 学到更多.
publish_to
可选的. 指定在何处发布软件包. 学到更多.

Pub会忽略所有其他字段,

如果添加自定义字段,请为其指定一个唯一名称,该名称不会与将来的pubspec字段冲突. 例如,您可以添加一个名为my_pkg_bugs的字段,而不是添加bugs .

Example

一个简单但完整的pubspec如下所示:

name: newtify
version: 1.2.3
description: >-
  Have you been turned into a newt?  Would you like to be?
  This package can help. It has all of the
  newt-transmogrification functionality you have been looking
  for.
homepage: https://example-pet-store.com/newtify
documentation: https://example-pet-store.com/newtify/docs
environment:
  sdk: '>=2.0.0 <3.0.0'
dependencies:
  efts: ^2.0.4
  transmogrify: ^0.4.0
dev_dependencies:
  test: '>=0.6.0 <0.12.0'

Details

本节包含有关大多数pubspec字段的更多信息.

Name

每个包装都需要一个名称. 这是其他软件包引用您的软件包的方式,以及它在您发布时如何向世界展示的方式.

名称应全部为小写,并带有下划线以分隔单词just_like_this . 仅使用基本的拉丁字母和阿拉伯数字: [a-z0-9_] . 另外,请确保该名称是有效的Dart标识符-它不能以数字开头并且不是保留字 .

尝试选择一个清晰,简洁且尚未使用的名称. 建议在pub.dev站点上快速搜索软件包,以确保没有其他人使用您的名字.

Version

每个软件包都有一个版本. 要在pub.dev站点上托管您的软件包,需要一个版本号,但对于仅本地软件包,可以省略该版本号. 如果您忽略它,则您的软件包的隐式版本为0.0.0 .

版本控制对于重用代码同时使其快速发展十分必要. 版本号是由点分隔的三个数字,例如0.2.43 . 它也可以选择具有build( +1+2+hotfix.oopsie )或-dev.4-dev.4-alpha.12-beta.7-rc.5 )后缀.

每次发布软件包时,都将其发布为特定版本. 一旦完成,请考虑将其密封:您不能再触摸它. 要进行更多更改,您需要一个新版本.

选择版本时,请遵循语义版本控制.

Description

这对于您自己的个人软件包是可选的,但是如果您打算发布您的软件包,则必须提供说明,该说明应为英文. 描述应相对简短(60到180个字符),并告诉随便的读者他们可能想了解您的包裹.

将描述视为包装的销售宣传. 用户在浏览软件包时会看到它. 描述为纯文本:无markdown或HTML.

Author/authors

不推荐使用. 请改用经过验证的发布者 .

您可能会在旧的pubspecs中看到" author或" authors部分. 这些可选字段是描述软件包作者并提供联系信息的一种方式. 每个作者可以是一个名字( Natalie Weizenbaum ),也可以是一个名字和电子邮件地址( Natalie Weizenbaum <nweiz@google.com> ). 但是,这些值未经验证.

pub.dev站点不再显示软件包作者,并且(从Dart 2.7开始),如果您的pubspec具有" author或" authors部分,则pub publish命令将显示警告.

Homepage

这应该是指向您的包裹网站的URL. 对于托管软件包 ,此URL是从软件包页面链接的. 提供homepage是可选的,但请提供 homepagerepository (或同时提供两者). 它可以帮助用户了解您的包裹的来源.

Repository

可选的repository字段应包含您软件包的源代码存储库的URL,例如https://github.com/<user>/<repository> . 如果您将软件包发布到pub.dev站点,那么软件包的页面将显示存储库URL. 虽然提供repository是可选的,但请提供 repositoryhomepage (或同时提供两者). 它可以帮助用户了解您的包裹的来源.

Issue tracker

可选的issue_tracker字段应包含该软件包的问题跟踪器的URL,可以在其中查看现有错误并可以归档新错误. pub.dev站点尝试使用此字段的值来显示每个软件包的问题跟踪器的链接. 如果缺少issue_tracker但存在repository并指向GitHub,则pub.dev站点将使用默认的问题跟踪器( https://github.com/<user>/<repository>/issues ).

Documentation

某些软件包的站点托管文档,与主页和发布的API参考不同. 如果您的软件包中有其他文档,请添加带有该URL的documentation:字段; pub在您的软件包页面上显示此文档的链接.

Dependencies

依赖关系是pubspec的存在理由 . 在此部分中,列出了您的软件包工作所需的每个软件包.

依赖关系属于两种类型之一. 常规依赖项dependencies: —这些是使用您的软件包的任何人也都需要的软件包. 在dev_dependencies下列出了仅在程序包本身的开发阶段所需的依赖dev_dependencies .

在开发过程中,您可能需要临时覆盖依赖项. 您可以使用dependency_overrides .

有关更多信息,请参见包依赖关系 .

Executables

程序包可以将其一个或多个脚本公开为可执行文件,可以直接从命令行运行. 要使脚本公开可用,请在executables字段下列出该脚本. 条目列为键/值对:

<name-of-executable>: <Dart-script-from-bin>

例如,以下pubspec条目列出了两个脚本:

executables:
  polymer-new-element: new_element
  useful-script:

使用pub global activate软件包后,键入polymer-new-element执行bin/new_element.dart . 键入useful-script执行bin/useful-script.dart . 如果不指定值,则从键推断出来.

有关更多信息,请参见pub global .

Publish_to

默认使用pub.dev网站. 不指定none以防止发布程序包. 此设置可用于指定要发布的自定义发布包服务器 .

publish_to: none

SDK constraints

程序包可以指示其支持的依赖项版本,但是程序包具有另一个隐式依赖项:Dart平台本身. Dart平台会随着时间的推移而发展,一个程序包可能仅适用于该平台的某些版本.

软件包可以使用SDK约束指定这些版本. 此约束位于pubspec中的单独的顶级environment字段中,并使用与依赖项相同的版本约束语法.

例如,以下约束条件表明此软件包可与任何2.0.0或更高版本的Dart 2 SDK配合使用:

environment:
  sdk: '>=2.0.0 <3.0.0'

Pub尝试查找其SDK约束与您已安装的Dart SDK版本兼容的软件包的最新版本.

Flutter SDK constraints

从Dart 1.19.0开始,pub在以下environment:下支持Flutter SDK约束:

environment:
  sdk: '>=1.19.0 <3.0.0'
  flutter: ^0.1.2

仅当pub在flutter可执行文件的上下文中运行并且Flutter SDK的version文件与给定的版本约束匹配时,才满足Flutter SDK约束. 否则,将不会选择该软件包.

要发布具有Flutter SDK约束的软件包,您必须指定Dart SDK约束,其最低版本至少为1.19.0,以确保较早版本的pub不会意外安装需要Flutter的软件包.

by  ICOPY.SITE