| OLD | NEW |
|---|
| (Empty) |
| 1 <h3 id="application-package">Application package</h3> | |
| 2 | |
| 3 <p>A package that is not intended to be used as a library. Application packages
may | |
| 4 have <a href="#dependency">dependencies</a> on other packages, but are never dep
ended on | |
| 5 themselves. They are usually meant to be run directly, either on the command | |
| 6 line or in a browser. The opposite of an application package is a <a href="#libr
ary-package">library | |
| 7 package</a>.</p> | |
| 8 | |
| 9 <p>Application packages should check their <a href="#lockfile">lockfiles</a> int
o source | |
| 10 control, so that everyone working on the application and every location the | |
| 11 application is deployed has a consistent set of dependencies. Because their | |
| 12 dependencies are constrained by the lockfile, application packages usually | |
| 13 specify <code>any</code> for their dependencies’ <a href="#version-constra
int">version | |
| 14 constraints</a>.</p> | |
| 15 | |
| 16 <h3 id="asset">Asset</h3> | |
| 17 | |
| 18 <div class="learn-more"> | |
| 19 <a href="/doc/assets-and-transformers.html"> | |
| 20 Learn more about assets → | |
| 21 </a> | |
| 22 </div> | |
| 23 | |
| 24 <p>A resource—Dart, HTML, JavaScript, CSS, image, or anything | |
| 25 else—intended to be part of a deployed package. The package can be a web | |
| 26 app, a package used by a web app, or any other package that benefits from a | |
| 27 build step. Tools such as <a href="pub-serve.html"><code>pub serve</code></a> an
d <a href="pub- | |
| 28 build.html"><code>pub build</code></a> take <em>source</em> assets (such as an H
TML file, a CSS file, and | |
| 29 several Dart files) and produce <em>generated</em> assets (such as the same HTML
and | |
| 30 CSS files, plus a single JavaScript file).</p> | |
| 31 | |
| 32 <p>Assets fall into four groups, with some overlap:</p> | |
| 33 | |
| 34 <ul> | |
| 35 <li>Source asset: An actual, authored file on disk that <code>pub build</code>
and | |
| 36 <code>pub serve</code> can find and use.</li> | |
| 37 <li>Generated asset: An asset (possibly the output of a | |
| 38 <a href="#transformer">transformer</a>) that’s either served by <code>pub
serve</code> or saved | |
| 39 to disk by <code>pub build</code>.</li> | |
| 40 <li>Input asset: An asset that is the input to a transformer. An input asset | |
| 41 might be a source asset, or it might be the output of a transformer in a | |
| 42 previous phase.</li> | |
| 43 <li>Output asset: An asset that is created by a transformer. An output asset | |
| 44 might be a generated asset, or it might be the input to a transformer in a | |
| 45 later phase.</li> | |
| 46 </ul> | |
| 47 | |
| 48 <h3 id="dependency">Dependency</h3> | |
| 49 | |
| 50 <p>Another package that your package relies on. If your package wants to import | |
| 51 code from some other package, that package must be a dependency. Dependencies | |
| 52 are specified in your package’s <a href="pubspec.html">pubspec</a> and des
cribed | |
| 53 <a href="dependencies.html">here</a>.</p> | |
| 54 | |
| 55 <h3 id="entrypoint">Entrypoint</h3> | |
| 56 | |
| 57 <p>“Entrypoint” is used to mean two things. In the general context o
f Dart, it is | |
| 58 a Dart library that is directly invoked by a Dart implementation. When you | |
| 59 reference a Dart library in a <code><script></code> tag or pass it as a co
mmand line | |
| 60 argument to the standalone Dart VM, that library is the entrypoint. In other | |
| 61 words, it’s usually the <code>.dart</code> file that contains <code>main()
</code>.</p> | |
| 62 | |
| 63 <p>In the context of pub, an “entrypoint package” or “root pac
kage” is the root | |
| 64 of a dependency graph. It will usually be an application. When you run your app, | |
| 65 it’s the entrypoint package. Every other package it depends on will not be
an | |
| 66 entrypoint in that context.</p> | |
| 67 | |
| 68 <p>A package can be an entrypoint in some contexts and not in others. Lets say y
our | |
| 69 app uses a library package A. When you run your app, A is not the entrypoint | |
| 70 package. However, if you go over to A and execute its unit tests, in that | |
| 71 context, it <em>is</em> the entrypoint since your app isn’t involved.</p> | |
| 72 | |
| 73 <h3 id="entrypoint-directory">Entrypoint directory</h3> | |
| 74 | |
| 75 <p>A directory inside your package that is allowed to contain | |
| 76 <a href="#entrypoint">Dart entrypoints</a>. Pub will ensure all of these directo
ries get | |
| 77 a “packages” directory, which is needed for “package:” i
mports to work.</p> | |
| 78 | |
| 79 <p>Pub has a whitelist of these directories: <code>benchmark</code>, <code>bin</
code>, <code>example</code>, | |
| 80 <code>test</code>, <code>tool</code>, and <code>web</code>. Any subdirectories o
f those (except <code>bin</code>) may also | |
| 81 contain entrypoints.</p> | |
| 82 | |
| 83 <h3 id="immediate-dependency">Immediate dependency</h3> | |
| 84 | |
| 85 <p>A <a href="#dependency">dependency</a> that your package directly uses itself
. The | |
| 86 dependencies you list in your pubspec are your package’s immediate depende
ncies. | |
| 87 All other dependencies are <a href="#transitive-dependency">transitive dependenc
ies</a>.</p> | |
| 88 | |
| 89 <h3 id="library-package">Library package</h3> | |
| 90 | |
| 91 <p>A package that other packages will depend on. Library packages may have | |
| 92 <a href="#dependency">dependencies</a> on other packages <em>and</em> may be dep
endencies | |
| 93 themselves. They may also include scripts that will be run directly. The | |
| 94 opposite of a library package is an <a href="#application-package">application p
ackage</a>.</p> | |
| 95 | |
| 96 <p>Library packages should not check their <a href="#lockfile">lockfile</a> into
source | |
| 97 control, since they should support a range of dependency versions. Their | |
| 98 <a href="#immediate-dependency">immediate dependencies</a>’ <a href="#vers
ion-constraints">version | |
| 99 constraints</a> should be as wide as possible while still | |
| 100 ensuring that the dependencies will be compatible with the versions that were | |
| 101 tested against.</p> | |
| 102 | |
| 103 <p>Since <a href="http://semver.org">semantic versioning</a> requires that libra
ries increment | |
| 104 their major version numbers for any backwards incompatible changes, library | |
| 105 packages will usually require their dependencies’ versions to be greater t
han or | |
| 106 equal to the versions that were tested and less than the next major version. So | |
| 107 if your library depended on the (fictional) <code>transmogrify</code> package an
d you | |
| 108 tested it at version 1.2.1, your version constraint would be <code>">=1.2.1 &
lt;2.0.0"</code>.</p> | |
| 109 | |
| 110 <h3 id="lockfile">Lockfile</h3> | |
| 111 | |
| 112 <p>A file named <code>pubspec.lock</code> that specifies the concrete versions a
nd other | |
| 113 identifying information for every immediate and transitive dependency a package | |
| 114 relies on.</p> | |
| 115 | |
| 116 <p>Unlike the pubspec, which only lists immediate dependencies and allows versio
n | |
| 117 ranges, the lock file comprehensively pins down the entire dependency graph to | |
| 118 specific versions of packages. A lockfile ensures that you can recreate the | |
| 119 exact configuration of packages used by an application.</p> | |
| 120 | |
| 121 <p>The lockfile is generated automatically for you by pub when you run | |
| 122 <a href="pub-get.html"><code>pub get</code></a> or <a href="pub-upgrade.html"><c
ode>pub upgrade</code></a>. If your | |
| 123 package is an application package, you will typically check this into source | |
| 124 control. For library packages, you usually won’t.</p> | |
| 125 | |
| 126 <h3 id="sdk-constraint">SDK constraint</h3> | |
| 127 | |
| 128 <p>The declared versions of the Dart SDK itself that a package declares that it | |
| 129 supports. An SDK constraint is specified using normal | |
| 130 <a href="#version-constraint">version constraint</a> syntax, but in a special &l
dquo;environment” | |
| 131 section <a href="pubspec.html#sdk-constraints">in the pubspec</a>.</p> | |
| 132 | |
| 133 <h3 id="source">Source</h3> | |
| 134 | |
| 135 <p>A kind of place that pub can get packages from. A source isn’t a specif
ic place | |
| 136 like pub.dartlang.org or some specific Git URL. Each source describes a general | |
| 137 procedure for accessing a package in some way. For example, “git” is
one source. | |
| 138 The git source knows how to download packages given a Git URL. There are a few | |
| 139 different <a href="dependencies.html#sources">supported sources</a>.</p> | |
| 140 | |
| 141 <h3 id="system-cache">System cache</h3> | |
| 142 | |
| 143 <p>When pub gets a remote package, it downloads it into a single “system c
ache” | |
| 144 directory maintained by pub. When it generates a “packages” director
y for a | |
| 145 package, that only contains symlinks to the real packages in the system cache. | |
| 146 On Mac and Linux, this directory defaults to <code>~/.pub-cache</code>. On Windo
ws, it | |
| 147 goes in <code>AppData\Roaming\Pub\Cache</code>.</p> | |
| 148 | |
| 149 <p>This means you only have to download a given version of a package once and ca
n | |
| 150 then reuse it in as many packages as you would like. It also means you can | |
| 151 delete and regenerate your “packages” directory without having to ac
cess the | |
| 152 network.</p> | |
| 153 | |
| 154 <h3 id="transformer">Transformer</h3> | |
| 155 | |
| 156 <div class="learn-more"> | |
| 157 <a href="/doc/assets-and-transformers.html"> | |
| 158 Learn more about transformers → | |
| 159 </a> | |
| 160 </div> | |
| 161 | |
| 162 <p>A transformer is a Dart object that converts input <a href="#asset">assets</a
> (such as | |
| 163 Dart files or Polymer-formatted HTML) into output assets (such as JavaScript | |
| 164 and HTML). The <a href="pub-build.html"><code>pub build</code></a> command puts
the generated assets | |
| 165 into files. The <a href="pub-serve.html"><code>pub serve</code></a> command, on
the other hand, | |
| 166 doesn’t produce files; its generated assets are served directly by the dev | |
| 167 server.</p> | |
| 168 | |
| 169 <h3 id="transitive-dependency">Transitive dependency</h3> | |
| 170 | |
| 171 <p>A dependency that your package indirectly uses because one of its dependencie
s | |
| 172 requires it. If your package depends on A, which in turn depends on B which | |
| 173 depends on C, then A is an <a href="#immediate-dependency">immediate dependency<
/a> and B | |
| 174 and C are transitive ones.</p> | |
| 175 | |
| 176 <h3 id="uploader">Uploader</h3> | |
| 177 | |
| 178 <p>An uploader of a package is someone who has administrative permissions | |
| 179 for that package. They can not only upload new versions of a package, | |
| 180 but also <a href="pub-uploader.html">add and remove other uploaders</a> for that | |
| 181 package. The uploader of a package is often, but not necessarily, the | |
| 182 same as the <a href="pubspec.html#authorauthors">author</a> of a package.</p> | |
| 183 | |
| 184 <p>Anyone uploading a new package automatically becomes an uploader for | |
| 185 that package. Otherwise, to become an uploader, you need to contact an | |
| 186 existing uploader and ask them to add you as another uploader.</p> | |
| 187 | |
| 188 <h3 id="version-constraint">Version constraint</h3> | |
| 189 | |
| 190 <div class="learn-more"> | |
| 191 <a href="/doc/dependencies.html#version-constraints"> | |
| 192 Learn more about version constaints → | |
| 193 </a> | |
| 194 </div> | |
| 195 | |
| 196 <p>A constraint placed on each <a href="#dependency">dependency</a> of a package
that | |
| 197 specifies which versions of that dependency the package is expected to work | |
| 198 with. This can be a single version (e.g. <code>0.3.0</code>), a range of version
s (e.g. | |
| 199 <code>">=1.2.1 <2.0.0"</code>), or <code>any</code> (or just empty) to spe
cify that any version is | |
| 200 allowed.</p> | |
| 201 | |
| 202 <div class="learn-more"> | |
| 203 <a href="/doc/versioning.html"> | |
| 204 Learn about pub's versioning philosophy → | |
| 205 </a> | |
| 206 </div> | |
| 207 | |
| 208 <p><a href="#library-package">Library packages</a> should always specify version
constraints | |
| 209 for all of their dependencies, but <a href="#application-package">application pa
ckages</a> | |
| 210 should usually allow any version of their dependencies, since they use the | |
| 211 <a href="#lockfile">lockfile</a> to manage their dependency versions.</p> | |
| 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