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