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