| OLD | NEW |
|---|
| (Empty) |
| 1 --- | |
| 2 title: "Pubspec Format" | |
| 3 --- | |
| 4 | |
| 5 1. [Name](#name) | |
| 6 1. [Version](#version) | |
| 7 1. [Description](#description) | |
| 8 1. [Author/Authors](#authorauthors) | |
| 9 1. [Homepage](#homepage) | |
| 10 1. [Documentation](#documentation) | |
| 11 1. [Dependencies](#dependencies) | |
| 12 1. [SDK constraints](#sdk-constraints) | |
| 13 {:.toc} | |
| 14 | |
| 15 Every pub package needs some metadata so it can specify its | |
| 16 [dependencies](glossary.html#dependency). Pub packages that are shared with | |
| 17 others also need to provide some other information so users can discover them. | |
| 18 Pub stores this in a file named `pubspec.yaml`, which (naturally) is written in | |
| 19 the [YAML](http://www.yaml.org/) language. | |
| 20 | |
| 21 At the top level are a series of fields. The currently supported ones are: | |
| 22 | |
| 23 <dl class="dl-horizontal"> | |
| 24 <dt>Name</dt> | |
| 25 <dd>Required for every package.</dd> | |
| 26 <dt>Version</dt> | |
| 27 <dd>Required for packages that will be hosted on pub.dartlang.org.</dd> | |
| 28 <dt>Description</dt> | |
| 29 <dd>Required for packages that will be hosted on pub.dartlang.org.</dd> | |
| 30 <dt>Author/Authors</dt> | |
| 31 <dd>Optional.</dd> | |
| 32 <dt>Homepage</dt> | |
| 33 <dd>Optional.</dd> | |
| 34 <dt>Documentation</dt> | |
| 35 <dd>Optional.</dd> | |
| 36 <dt>Dependencies</dt> | |
| 37 <dd>Can be omitted if your package has no dependencies.</dd> | |
| 38 <dt>Dev dependencies</dt> | |
| 39 <dd>Can be omitted if your package has no dev dependencies.</dd> | |
| 40 </dl> | |
| 41 | |
| 42 All other fields will be ignored. A simple but complete pubspec looks something | |
| 43 like this: | |
| 44 | |
| 45 {% highlight yaml %} | |
| 46 name: newtify | |
| 47 version: 1.2.3 | |
| 48 description: > | |
| 49 Have you been turned into a newt? Would you like to be? This | |
| 50 package can help: it has all of the newt-transmogrification | |
| 51 functionality you've been looking for. | |
| 52 author: Nathan Weizenbaum <nweiz@google.com> | |
| 53 homepage: http://newtify.dartlang.org | |
| 54 documentation: http://docs.newtify.com | |
| 55 dependencies: | |
| 56 efts: '>=2.0.4 <3.0.0' | |
| 57 transmogrify: '>=0.4.0' | |
| 58 dev_dependencies: | |
| 59 unittest: '>=0.6.0' | |
| 60 {% endhighlight %} | |
| 61 | |
| 62 ## Name | |
| 63 | |
| 64 Every package needs a name. When your stellar code gets props on | |
| 65 the world stage, this is what they'll be hollering. Also, it's how other | |
| 66 packages will refer to yours, and how it will appear here, should you publish | |
| 67 it. | |
| 68 | |
| 69 It should be all lowercase, with underscores to separate words, | |
| 70 `just_like_this`. Stick with basic Latin letters and Arabic digits: | |
| 71 `[a-z0-9_]` and ensure that it's a valid Dart identifier (i.e. doesn't start | |
| 72 with digits and isn't a reserved word). | |
| 73 | |
| 74 Try to pick a name that is clear, terse, and not already in use. A quick search | |
| 75 [here](/packages) to make sure nothing else is using your name can save you | |
| 76 heartache later. | |
| 77 | |
| 78 ## Version | |
| 79 | |
| 80 Every package has a version. A version number is required to host your package | |
| 81 here, but can be omitted for local-only packages. If you omit it, your package | |
| 82 is implicitly versioned `0.0.0`. | |
| 83 | |
| 84 No one really gets excited about versioning, but it's a necessary evil for | |
| 85 reusing code while letting it evolve quickly. A version number is three numbers | |
| 86 separated by dots, like `0.2.43`. It can also optionally have a build | |
| 87 (`+hotfix.oopsie`) or pre-release (`-alpha.12`) suffix. | |
| 88 | |
| 89 Each time you publish your package, you will publish it at a specific version. | |
| 90 Once that's been done, consider it hermetically sealed: you can't touch it | |
| 91 anymore. To make more changes, you'll need a new version. | |
| 92 | |
| 93 When you select a version, follow [semantic versioning][]. When you do, the | |
| 94 clouds will part and sunshine will pour into your soul. If you don't, prepare | |
| 95 yourself for hordes of angry users. | |
| 96 | |
| 97 [semantic versioning]: http://semver.org | |
| 98 | |
| 99 ## Description | |
| 100 | |
| 101 This is optional for your own personal packages, but if you intend to share | |
| 102 your package with the world (and you should because, let's be honest with | |
| 103 ourselves, it's a thing of beauty) you must provide a description. This should | |
| 104 be relatively short—a few sentences, maybe a whole paragraph—and | |
| 105 tells a casual reader what they might want to know about your package. | |
| 106 | |
| 107 Think of the description as the sales pitch for your package. Users will see it | |
| 108 when they [browse for packages](/packages). It should be simple plain text: | |
| 109 no markdown or HTML. That's what your README is for. | |
| 110 | |
| 111 ## Author/Authors | |
| 112 | |
| 113 You're encouraged to use these fields to describe the author(s) of your package | |
| 114 and provide contact information. `author` should be used if your package has a | |
| 115 single author, while `authors` should be used with a YAML list if more than one | |
| 116 person wrote the package. Each author can either be a single name (e.g. `Nathan | |
| 117 Weizenbaum`) or a name and an email address (e.g. `Nathan Weizenbaum | |
| 118 <nweiz@google.com>`). For example: | |
| 119 | |
| 120 {% highlight yaml %} | |
| 121 authors: | |
| 122 - Nathan Weizenbaum <nweiz@google.com> | |
| 123 - Bob Nystrom <rnystrom@google.com> | |
| 124 {% endhighlight %} | |
| 125 | |
| 126 If anyone uploads your package here, we will show this email address so make | |
| 127 sure you're OK with that. | |
| 128 | |
| 129 ## Homepage | |
| 130 | |
| 131 This should be a URL pointing to the website for your package. For | |
| 132 [hosted packages](#hosted-packages), this URL will be linked from the | |
| 133 package's page. While this is technically optional *please do* provide one. It | |
| 134 helps users understand where your package is coming from. If nothing else, you | |
| 135 can always use the URL where you host the source code: | |
| 136 [GitHub](http://github.com), [code.google.com](http://code.google.com/), | |
| 137 whatever. | |
| 138 | |
| 139 ## Documentation | |
| 140 | |
| 141 Some packages may have a site that hosts documentation separate from the main | |
| 142 homepage. If your package has that, you can also add a `documentation:` field | |
| 143 with that URL. If provided, a link to it will be shown on your package's page. | |
| 144 | |
| 145 ## Dependencies | |
| 146 | |
| 147 <div class="learn-more"> | |
| 148 <a href="/doc/dependencies.html"> | |
| 149 Learn more about dependencies → | |
| 150 </a> | |
| 151 </div> | |
| 152 | |
| 153 Finally, the pubspec's *raison d'être*: [dependencies](glossary.html#dependency)
. Here, | |
| 154 you list each package that your package needs in order to work. | |
| 155 | |
| 156 There are two separate sections. Dependencies under `dependencies:` are | |
| 157 "regular" dependencies. They are packages that anyone using your package will | |
| 158 also need. Dependencies under `dev_dependencies` are | |
| 159 [dev dependencies](glossary.html#dev-dependency). These are packages that are | |
| 160 only needed in the development of your package itself. | |
| 161 | |
| 162 ## SDK constraints | |
| 163 | |
| 164 A package can indicate which versions of its dependencies it supports, but there | |
| 165 is also another implicit dependency all packages have: the Dart SDK itself. | |
| 166 Since the Dart platform evolves over time, a package may only work with certain | |
| 167 versions of it. | |
| 168 | |
| 169 A package can specify that using an *SDK constraint*. This goes inside a | |
| 170 separate top-level "environment" field in the pubspec and uses the same | |
| 171 [version constraint](dependencies.html#version-constraints) syntax as | |
| 172 dependencies. For example, this constraint says that this package works with any | |
| 173 Dart SDK from 0.3.4 or later: | |
| 174 | |
| 175 {% highlight yaml %} | |
| 176 environment: | |
| 177 sdk: ">=0.3.4" | |
| 178 {% endhighlight %} | |
| 179 | |
| 180 Pub will try to find the latest version of a package whose SDK constraint works | |
| 181 with the version of the Dart SDK that you have installed. | |
| 182 | |
| 183 [pubsite]: http://pub.dartlang.org | |
| 184 [semantic versioning]: http://semver.org/ | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 162403002:
Remove docs and point to ones on dartlang.org. (Closed)
Base URL: https://github.com/dart-lang/pub-dartlang.git@master