app/views/doc/dependencies.html - Issue 162403002: Remove docs and point to ones on dartlang.org.

Unified Diff: app/views/doc/dependencies.html

Issue 162403002: Remove docs and point to ones on dartlang.org. (Closed) Base URL: https://github.com/dart-lang/pub-dartlang.git@master

Patch Set: Fit in 80 columns. Created 6 years, 10 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View side-by-side diff with in-line comments

Download patch

Index: app/views/doc/dependencies.html

diff --git a/app/views/doc/dependencies.html b/app/views/doc/dependencies.html

deleted file mode 100644

index 8c8df54674138628b2efc37483a729be54a61397..0000000000000000000000000000000000000000

--- a/app/views/doc/dependencies.html

+++ /dev/null

@@ -1,267 +0,0 @@

-<ol class="toc">

- <li><a href="#sources">Sources</a>

- <ol>

- <li><a href="#hosted-packages">Hosted packages</a></li>

- <li><a href="#git-packages">Git packages</a></li>

- <li><a href="#path-packages">Path packages</a></li>

- </ol>

- </li>

- <li><a href="#version-constraints">Version constraints</a></li>

- <li><a href="#dev-dependencies">Dev dependencies</a></li>

-</ol>

-Dependencies are one of pub’s core concepts. A dependency is another package

-that your package needs in order to work. Dependencies are specified in your

-<a href="pubspec.html">pubspec</a>. You only list

-<a href="glossary.html#immediate-dependency">immediate dependencies</a>—the stuff

-your package uses directly. Pub handles

-<a href="glossary.html#transitive-dependency">transitive dependencies</a> for you.

-For each dependency, you specify the name of the package you depend on. For

-<a href="glossary.html#library-package">library packages</a>, you specify the range of

-versions of that package that you allow. You may also specify the

-<a href="glossary.html#source">source</a> which tells pub how the package can be located,

-and any additional description that the source needs to find the package.

-There are two different ways to specify dependencies based on what data you want

-to provide. The shortest way is to just specify a name:

-<div class="highlight"><pre><code class="yaml">dependencies:

- transmogrify:

-</code></pre></div>

-This creates a dependency on <code>transmogrify</code>that allows any version, and looks

-it up using the default source, which is this site itself. To limit the

-dependency to a range of versions, you can provide a version constraint:

-<div class="highlight"><pre><code class="yaml">dependencies:

- transmogrify: '>=1.0.0 <2.0.0'

-</code></pre></div>

-This creates a dependency on <code>transmogrify</code> using the default source and

-allowing any version from <code>1.0.0</code> to <code>2.0.0</code> (but not including <code>2.0.0</code>). See

-<a href="#version-constraints">below</a> for details on the version constraint syntax.

-If you want to specify a source, the syntax looks a bit different:

-<div class="highlight"><pre><code class="yaml">dependencies:

- transmogrify:

- hosted:

- name: transmogrify

- url: http://some-package-server.com

-</code></pre></div>

-This depends on the <code>transmogrify</code> package using the <code>hosted</code> source.

-Everything under the source key (here, just a map with a <code>url:</code> key) is the

-description that gets passed to the source. Each source has its own description

-format, detailed below.

-You can also provide a version constraint:

-<div class="highlight"><pre><code class="yaml">dependencies:

- transmogrify:

- hosted:

- name: transmogrify

- url: http://some-package-server.com

- version: '>=1.0.0 <2.0.0'

-</code></pre></div>

-This long form is used when you don’t use the default source or when you have a

-complex description you need to specify. But in most cases, you’ll just use the

-simple “name: version” form.

-<h2 id="dependency-sources">Dependency sources</h2>

-Here are the different sources pub can use to locate packages, and the

-descriptions they allow:

-<h3 id="hosted-packages">Hosted packages</h3>

-A hosted package is one that can be downloaded from this site (or another

-HTTP server that speaks the same API). Most of your dependencies will be of

-this form. They look like this:

-<div class="highlight"><pre><code class="yaml">dependencies:

- transmogrify: '>=0.4.0 <1.0.0'

-</code></pre></div>

-Here, you’re saying your package depends on a hosted package named

-“transmogrify” and you’ll work with any version from 0.4.0 to 1.0.0 (but not

-1.0.0 itself).

-If you want to use your own package server, you can use a description that

-specifies its URL:

-<div class="highlight"><pre><code class="yaml">dependencies:

- transmogrify:

- hosted:

- name: transmogrify

- url: http://your-package-server.com

- version: '>=0.4.0 <1.0.0'

-</code></pre></div>

-<h3 id="git-packages">Git packages</h3>

-Sometimes you live on the bleeding edge and you need to use stuff that hasn’t

-been formally released yet. Maybe your package itself is still in development

-and is using other packages that are being developed at the same time. To make

-that easier, you can depend directly on a package stored in a <a href="http://git-scm.com/">Git</a>

-repository.

-<div class="highlight"><pre><code class="yaml">dependencies:

- kittens:

- git: git://github.com/munificent/kittens.git

-</code></pre></div>

-The <code>git</code> here says this package is found using Git, and the URL after that is

-the Git URL that can be used to clone the package. Pub assumes that the package

-is in the root of the git repository.

-If you want to depend on a specific commit, branch, or tag, you can also

-provide a <code>ref</code> argument:

-<div class="highlight"><pre><code class="yaml">dependencies:

- kittens:

- git:

- url: git://github.com/munificent/kittens.git

- ref: some-branch

-</code></pre></div>

-The ref can be anything that Git allows to <a href="http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#naming-commits">identify a commit</a>.

-<h3 id="path-packages">Path packages</h3>

-Sometimes you find yourself working on multiple related packages at the same

-time. Maybe you are hacking on a framework while building an app that uses it.

-In those cases, during development you really want to depend on the “live”

-version of that package on your local file system. That way changes in one

-package are instantly picked up by the one that depends on it.

-To handle that, pub supports path dependencies.

-<div class="highlight"><pre><code class="yaml">dependencies:

- transmogrify:

- path: /Users/me/transmogrify

-</code></pre></div>

-This says the root directory for <code>transmogrify</code> is <code>/Users/me/transmogrify</code>.

-When you use this, pub will generate a symlink directly to the <code>lib</code> directory

-of the referenced package directory. Any changes you make to the dependent

-package will be seen immediately. You don’t need to run pub every time you

-change the dependent package.

-Relative paths are allowed and are considered relative to the directory

-containing your pubspec.

-Path dependencies are useful for local development, but do not play nice with

-sharing code with the outside world. It’s not like everyone can get to

-your file system, after all. Because of this, you cannot upload a package to

-<a href="http://pub.dartlang.org">pub.dartlang.org</a> if it has any path dependencies in its pubspec.

-Instead, the typical workflow is:

-<ol>

- <li>Edit your pubspec locally to use a path dependency.</li>

- <li>Hack on the main package and the package it depends on.</li>

- <li>Once they’re both in a happy place, publish the dependent package.</li>

- <li>Then change your pubspec to point to the now hosted version of its dependent.</li>

- <li>Now you can publish your main package too if you want.</li>

-</ol>

-<h2 id="version-constraints">Version constraints</h2>

-If your package is an application, you don’t usually need to specify <a href="glossary.html#version-constraint">version

-constraints</a> for your dependencies. You will

-typically want to use the latest versions of the dependencies when you first

-create your app. Then you’ll create and check in a

-<a href="glossary.html#lockfile">lockfile</a> that pins your dependencies to those specific

-versions. Specifying version constraints in your pubspec then is usually

-redundant (though you can do it if you want).

-For a <a href="glossary.html#library-package">library package</a> that you want users to

-reuse, though, it is important to specify version constraints. That lets people

-using your package know which versions of its dependencies they can rely on to

-be compatible with your library. Your goal is to allow a range of versions as

-wide as possible to give your users flexibility. But it should be narrow enough

-to exclude versions that you know don’t work or haven’t been tested.

-The Dart community uses <a href="http://semver.org/">semantic versioning</a>, which helps you know which

-versions should work. If you know that your package works fine with <code>1.2.3</code> of

-some dependency, then semantic versioning tells you that it should work (at

-least) up to <code>2.0.0</code>.

-A version constraint is a series of:

-<dl class="dl-horizontal">

- <dt><code>any</code></dt>

- <dd>The string "any" allows any version. This is equivalent to an empty

- version constraint, but is more explicit.</dd>

- <dt><code>1.2.3</code></dt>

- <dd>A concrete version number pins the dependency to only allow that

- exact version. Avoid using this when you can because it can cause

- version lock for your users and make it hard for them to use your package

- along with other packages that also depend on it.</dd>

- <dt><code>>=1.2.3</code></dt>

- <dd>Allows the given version or any greater one. You'll typically use this.

- </dd>

- <dt><code>>1.2.3</code></dt>

- <dd>Allows any version greater than the specified one but not that

- version itself.</dd>

- <dt><code><=1.2.3</code></dt>

- <dd>Allows any version lower than or equal to the specified one. You

- won't typically use this.</dd>

- <dt><code><1.2.3</code></dt>

- <dd>Allows any version lower than the specified one but not that

- version itself. This is what you'll usually use because it lets you specify

- the upper version that you know does not work with your package

- (because it's the first version to introduce some breaking change).</dd>

-</dl>

-You can specify version parts as you want, and their ranges will be intersected

-together. For example, <code>>=1.2.3 <2.0.0</code> allows any version from <code>1.2.3</code> to

-<code>2.0.0</code> excluding <code>2.0.0</code> itself.

-<aside class="alert alert-warning">

-Note that <code>></code> is also valid YAML syntax so you will want to quote

-the version string (like <code>'<=1.2.3 >2.0.0'</code>) if the version

-constraint starts with that.

-</aside>

-<h2 id="dev-dependencies">Dev dependencies</h2>

-Pub supports two flavors of dependencies: regular dependencies and dev

-dependencies. Dev dependencies differ from regular dependencies in that dev

-dependencies of packages you depend on are ignored. That’s a mouthful, so

-here’s a motivating example:

-Say the <code>transmogrify</code> package uses the <code>unittest</code> package in its tests and only

-in its tests. If someone just wants to use <code>transmogrify</code>—import its

-libraries—it doesn’t actually need <code>unittest</code>. In this case, it specifies

-<code>unittest</code> as a dev dependency. Its pubspec will have something like:

-<div class="highlight"><pre><code class="yaml">dev_dependencies:

- unittest: '>=0.5.0'

-</code></pre></div>

-Pub gets every package your package package depends on, and everything those

-packages depend on, transitively. It also gets your package’s dev dependencies,

-but it ignores the dev dependencies of any dependent packages. Pub only gets

-your package’s dev dependencies. So when your package depends on

-<code>transmogrify</code> it will get <code>transmogrify</code> but not <code>unittest</code>.

-The rule for deciding between a regular or dev dependency is pretty simple. If

-the dependency is imported from something in your <code>lib</code> directory, it needs to

-be a regular dependency. If it’s only imported from <code>test</code>, <code>example</code>, etc. it

-can and should be a dev dependency.

-Using dev dependencies makes dependency graphs smaller. That makes pub run

-faster, and makes it easier to find a set of package versions that satisfy all

-constraints. Use them when you can and your users will thank you.

« no previous file with comments | « app/views/doc/assets-and-transformers.html ('k') | app/views/doc/faq.html » ('j') | no next file with comments »