| Index: app/views/doc/glossary.html
|
| diff --git a/app/views/doc/glossary.html b/app/views/doc/glossary.html
|
| deleted file mode 100644
|
| index d6dbe357338604929002511d82990530a38f2561..0000000000000000000000000000000000000000
|
| --- a/app/views/doc/glossary.html
|
| +++ /dev/null
|
| @@ -1,211 +0,0 @@
|
| -<h3 id="application-package">Application package</h3>
|
| -
|
| -<p>A package that is not intended to be used as a library. Application packages may
|
| -have <a href="#dependency">dependencies</a> on other packages, but are never depended on
|
| -themselves. They are usually meant to be run directly, either on the command
|
| -line or in a browser. The opposite of an application package is a <a href="#library-package">library
|
| -package</a>.</p>
|
| -
|
| -<p>Application packages should check their <a href="#lockfile">lockfiles</a> into source
|
| -control, so that everyone working on the application and every location the
|
| -application is deployed has a consistent set of dependencies. Because their
|
| -dependencies are constrained by the lockfile, application packages usually
|
| -specify <code>any</code> for their dependencies’ <a href="#version-constraint">version
|
| -constraints</a>.</p>
|
| -
|
| -<h3 id="asset">Asset</h3>
|
| -
|
| -<div class="learn-more">
|
| - <a href="/doc/assets-and-transformers.html">
|
| - Learn more about assets →
|
| - </a>
|
| -</div>
|
| -
|
| -<p>A resource—Dart, HTML, JavaScript, CSS, image, or anything
|
| -else—intended to be part of a deployed package. The package can be a web
|
| -app, a package used by a web app, or any other package that benefits from a
|
| -build step. Tools such as <a href="pub-serve.html"><code>pub serve</code></a> and <a href="pub-
|
| -build.html"><code>pub build</code></a> take <em>source</em> assets (such as an HTML file, a CSS file, and
|
| -several Dart files) and produce <em>generated</em> assets (such as the same HTML and
|
| -CSS files, plus a single JavaScript file).</p>
|
| -
|
| -<p>Assets fall into four groups, with some overlap:</p>
|
| -
|
| -<ul>
|
| - <li>Source asset: An actual, authored file on disk that <code>pub build</code> and
|
| -<code>pub serve</code> can find and use.</li>
|
| - <li>Generated asset: An asset (possibly the output of a
|
| -<a href="#transformer">transformer</a>) that’s either served by <code>pub serve</code> or saved
|
| -to disk by <code>pub build</code>.</li>
|
| - <li>Input asset: An asset that is the input to a transformer. An input asset
|
| -might be a source asset, or it might be the output of a transformer in a
|
| -previous phase.</li>
|
| - <li>Output asset: An asset that is created by a transformer. An output asset
|
| -might be a generated asset, or it might be the input to a transformer in a
|
| -later phase.</li>
|
| -</ul>
|
| -
|
| -<h3 id="dependency">Dependency</h3>
|
| -
|
| -<p>Another package that your package relies on. If your package wants to import
|
| -code from some other package, that package must be a dependency. Dependencies
|
| -are specified in your package’s <a href="pubspec.html">pubspec</a> and described
|
| -<a href="dependencies.html">here</a>.</p>
|
| -
|
| -<h3 id="entrypoint">Entrypoint</h3>
|
| -
|
| -<p>“Entrypoint” is used to mean two things. In the general context of Dart, it is
|
| -a Dart library that is directly invoked by a Dart implementation. When you
|
| -reference a Dart library in a <code><script></code> tag or pass it as a command line
|
| -argument to the standalone Dart VM, that library is the entrypoint. In other
|
| -words, it’s usually the <code>.dart</code> file that contains <code>main()</code>.</p>
|
| -
|
| -<p>In the context of pub, an “entrypoint package” or “root package” is the root
|
| -of a dependency graph. It will usually be an application. When you run your app,
|
| -it’s the entrypoint package. Every other package it depends on will not be an
|
| -entrypoint in that context.</p>
|
| -
|
| -<p>A package can be an entrypoint in some contexts and not in others. Lets say your
|
| -app uses a library package A. When you run your app, A is not the entrypoint
|
| -package. However, if you go over to A and execute its unit tests, in that
|
| -context, it <em>is</em> the entrypoint since your app isn’t involved.</p>
|
| -
|
| -<h3 id="entrypoint-directory">Entrypoint directory</h3>
|
| -
|
| -<p>A directory inside your package that is allowed to contain
|
| -<a href="#entrypoint">Dart entrypoints</a>. Pub will ensure all of these directories get
|
| -a “packages” directory, which is needed for “package:” imports to work.</p>
|
| -
|
| -<p>Pub has a whitelist of these directories: <code>benchmark</code>, <code>bin</code>, <code>example</code>,
|
| -<code>test</code>, <code>tool</code>, and <code>web</code>. Any subdirectories of those (except <code>bin</code>) may also
|
| -contain entrypoints.</p>
|
| -
|
| -<h3 id="immediate-dependency">Immediate dependency</h3>
|
| -
|
| -<p>A <a href="#dependency">dependency</a> that your package directly uses itself. The
|
| -dependencies you list in your pubspec are your package’s immediate dependencies.
|
| -All other dependencies are <a href="#transitive-dependency">transitive dependencies</a>.</p>
|
| -
|
| -<h3 id="library-package">Library package</h3>
|
| -
|
| -<p>A package that other packages will depend on. Library packages may have
|
| -<a href="#dependency">dependencies</a> on other packages <em>and</em> may be dependencies
|
| -themselves. They may also include scripts that will be run directly. The
|
| -opposite of a library package is an <a href="#application-package">application package</a>.</p>
|
| -
|
| -<p>Library packages should not check their <a href="#lockfile">lockfile</a> into source
|
| -control, since they should support a range of dependency versions. Their
|
| -<a href="#immediate-dependency">immediate dependencies</a>’ <a href="#version-constraints">version
|
| -constraints</a> should be as wide as possible while still
|
| -ensuring that the dependencies will be compatible with the versions that were
|
| -tested against.</p>
|
| -
|
| -<p>Since <a href="http://semver.org">semantic versioning</a> requires that libraries increment
|
| -their major version numbers for any backwards incompatible changes, library
|
| -packages will usually require their dependencies’ versions to be greater than or
|
| -equal to the versions that were tested and less than the next major version. So
|
| -if your library depended on the (fictional) <code>transmogrify</code> package and you
|
| -tested it at version 1.2.1, your version constraint would be <code>">=1.2.1 <2.0.0"</code>.</p>
|
| -
|
| -<h3 id="lockfile">Lockfile</h3>
|
| -
|
| -<p>A file named <code>pubspec.lock</code> that specifies the concrete versions and other
|
| -identifying information for every immediate and transitive dependency a package
|
| -relies on.</p>
|
| -
|
| -<p>Unlike the pubspec, which only lists immediate dependencies and allows version
|
| -ranges, the lock file comprehensively pins down the entire dependency graph to
|
| -specific versions of packages. A lockfile ensures that you can recreate the
|
| -exact configuration of packages used by an application.</p>
|
| -
|
| -<p>The lockfile is generated automatically for you by pub when you run
|
| -<a href="pub-get.html"><code>pub get</code></a> or <a href="pub-upgrade.html"><code>pub upgrade</code></a>. If your
|
| -package is an application package, you will typically check this into source
|
| -control. For library packages, you usually won’t.</p>
|
| -
|
| -<h3 id="sdk-constraint">SDK constraint</h3>
|
| -
|
| -<p>The declared versions of the Dart SDK itself that a package declares that it
|
| -supports. An SDK constraint is specified using normal
|
| -<a href="#version-constraint">version constraint</a> syntax, but in a special “environment”
|
| -section <a href="pubspec.html#sdk-constraints">in the pubspec</a>.</p>
|
| -
|
| -<h3 id="source">Source</h3>
|
| -
|
| -<p>A kind of place that pub can get packages from. A source isn’t a specific place
|
| -like pub.dartlang.org or some specific Git URL. Each source describes a general
|
| -procedure for accessing a package in some way. For example, “git” is one source.
|
| -The git source knows how to download packages given a Git URL. There are a few
|
| -different <a href="dependencies.html#sources">supported sources</a>.</p>
|
| -
|
| -<h3 id="system-cache">System cache</h3>
|
| -
|
| -<p>When pub gets a remote package, it downloads it into a single “system cache”
|
| -directory maintained by pub. When it generates a “packages” directory for a
|
| -package, that only contains symlinks to the real packages in the system cache.
|
| -On Mac and Linux, this directory defaults to <code>~/.pub-cache</code>. On Windows, it
|
| -goes in <code>AppData\Roaming\Pub\Cache</code>.</p>
|
| -
|
| -<p>This means you only have to download a given version of a package once and can
|
| -then reuse it in as many packages as you would like. It also means you can
|
| -delete and regenerate your “packages” directory without having to access the
|
| -network.</p>
|
| -
|
| -<h3 id="transformer">Transformer</h3>
|
| -
|
| -<div class="learn-more">
|
| - <a href="/doc/assets-and-transformers.html">
|
| - Learn more about transformers →
|
| - </a>
|
| -</div>
|
| -
|
| -<p>A transformer is a Dart object that converts input <a href="#asset">assets</a> (such as
|
| -Dart files or Polymer-formatted HTML) into output assets (such as JavaScript
|
| -and HTML). The <a href="pub-build.html"><code>pub build</code></a> command puts the generated assets
|
| -into files. The <a href="pub-serve.html"><code>pub serve</code></a> command, on the other hand,
|
| -doesn’t produce files; its generated assets are served directly by the dev
|
| -server.</p>
|
| -
|
| -<h3 id="transitive-dependency">Transitive dependency</h3>
|
| -
|
| -<p>A dependency that your package indirectly uses because one of its dependencies
|
| -requires it. If your package depends on A, which in turn depends on B which
|
| -depends on C, then A is an <a href="#immediate-dependency">immediate dependency</a> and B
|
| -and C are transitive ones.</p>
|
| -
|
| -<h3 id="uploader">Uploader</h3>
|
| -
|
| -<p>An uploader of a package is someone who has administrative permissions
|
| -for that package. They can not only upload new versions of a package,
|
| -but also <a href="pub-uploader.html">add and remove other uploaders</a> for that
|
| -package. The uploader of a package is often, but not necessarily, the
|
| -same as the <a href="pubspec.html#authorauthors">author</a> of a package.</p>
|
| -
|
| -<p>Anyone uploading a new package automatically becomes an uploader for
|
| -that package. Otherwise, to become an uploader, you need to contact an
|
| -existing uploader and ask them to add you as another uploader.</p>
|
| -
|
| -<h3 id="version-constraint">Version constraint</h3>
|
| -
|
| -<div class="learn-more">
|
| - <a href="/doc/dependencies.html#version-constraints">
|
| - Learn more about version constaints →
|
| - </a>
|
| -</div>
|
| -
|
| -<p>A constraint placed on each <a href="#dependency">dependency</a> of a package that
|
| -specifies which versions of that dependency the package is expected to work
|
| -with. This can be a single version (e.g. <code>0.3.0</code>), a range of versions (e.g.
|
| -<code>">=1.2.1 <2.0.0"</code>), or <code>any</code> (or just empty) to specify that any version is
|
| -allowed.</p>
|
| -
|
| -<div class="learn-more">
|
| - <a href="/doc/versioning.html">
|
| - Learn about pub's versioning philosophy →
|
| - </a>
|
| -</div>
|
| -
|
| -<p><a href="#library-package">Library packages</a> should always specify version constraints
|
| -for all of their dependencies, but <a href="#application-package">application packages</a>
|
| -should usually allow any version of their dependencies, since they use the
|
| -<a href="#lockfile">lockfile</a> to manage their dependency versions.</p>
|
|
|