Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(578)

Side by Side Diff: app/doc/dependencies.markdown

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: Re-upload. 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 unified diff | Download patch
OLDNEW
(Empty)
1 ---
2 title: "Dependencies"
3 ---
4
5 1. [Sources](#sources)
6 1. [Hosted packages](#hosted-packages)
7 1. [Git packages](#git-packages)
8 1. [Path packages](#path-packages)
9 1. [Version constraints](#version-constraints)
10 1. [Dev dependencies](#dev-dependencies)
11 {:.toc}
12
13 Dependencies are one of pub's core concepts. A dependency is another package
14 that your package needs in order to work. Dependencies are specified in your
15 [pubspec](pubspec.html). You only list
16 [immediate dependencies](glossary.html#immediate-dependency)—the stuff
17 your package uses directly. Pub handles
18 [transitive dependencies](glossary.html#transitive-dependency) for you.
19
20 For each dependency, you specify the *name* of the package you depend on. For
21 [library packages](glossary.html#library-package), you specify the *range of
22 versions* of that package that you allow. You may also specify the
23 [*source*](glossary.html#source) which tells pub how the package can be located,
24 and any additional *description* that the source needs to find the package.
25
26 There are two different ways to specify dependencies based on what data you want
27 to provide. The shortest way is to just specify a name:
28
29 {% highlight yaml %}
30 dependencies:
31 transmogrify:
32 {% endhighlight %}
33
34 This creates a dependency on `transmogrify`that allows any version, and looks
35 it up using the default source, which is this site itself. To limit the
36 dependency to a range of versions, you can provide a *version constraint*:
37
38 {% highlight yaml %}
39 dependencies:
40 transmogrify: '>=1.0.0 <2.0.0'
41 {% endhighlight %}
42
43 This creates a dependency on `transmogrify` using the default source and
44 allowing any version from `1.0.0` to `2.0.0` (but not including `2.0.0`). See
45 [below](#version-constraints) for details on the version constraint syntax.
46
47 If you want to specify a source, the syntax looks a bit different:
48
49 {% highlight yaml %}
50 dependencies:
51 transmogrify:
52 hosted:
53 name: transmogrify
54 url: http://some-package-server.com
55 {% endhighlight %}
56
57 This depends on the `transmogrify` package using the `hosted` source.
58 Everything under the source key (here, just a map with a `url:` key) is the
59 description that gets passed to the source. Each source has its own description
60 format, detailed below.
61
62 You can also provide a version constraint:
63
64 {% highlight yaml %}
65 dependencies:
66 transmogrify:
67 hosted:
68 name: transmogrify
69 url: http://some-package-server.com
70 version: '>=1.0.0 <2.0.0'
71 {% endhighlight %}
72
73 This long form is used when you don't use the default source or when you have a
74 complex description you need to specify. But in most cases, you'll just use the
75 simple "name: version" form.
76
77 ## Dependency sources
78
79 Here are the different sources pub can use to locate packages, and the
80 descriptions they allow:
81
82 ### Hosted packages
83
84 A *hosted* package is one that can be downloaded from this site (or another
85 HTTP server that speaks the same API). Most of your dependencies will be of
86 this form. They look like this:
87
88 {% highlight yaml %}
89 dependencies:
90 transmogrify: '>=0.4.0 <1.0.0'
91 {% endhighlight %}
92
93 Here, you're saying your package depends on a hosted package named
94 "transmogrify" and you'll work with any version from 0.4.0 to 1.0.0 (but not
95 1.0.0 itself).
96
97 If you want to use your own package server, you can use a description that
98 specifies its URL:
99
100 {% highlight yaml %}
101 dependencies:
102 transmogrify:
103 hosted:
104 name: transmogrify
105 url: http://your-package-server.com
106 version: '>=0.4.0 <1.0.0'
107 {% endhighlight %}
108
109 ### Git packages
110
111 Sometimes you live on the bleeding edge and you need to use stuff that hasn't
112 been formally released yet. Maybe your package itself is still in development
113 and is using other packages that are being developed at the same time. To make
114 that easier, you can depend directly on a package stored in a [Git][]
115 repository.
116
117 [git]: http://git-scm.com/
118
119 {% highlight yaml %}
120 dependencies:
121 kittens:
122 git: git://github.com/munificent/kittens.git
123 {% endhighlight %}
124
125 The `git` here says this package is found using Git, and the URL after that is
126 the Git URL that can be used to clone the package. Pub assumes that the package
127 is in the root of the git repository.
128
129 If you want to depend on a specific commit, branch, or tag, you can also
130 provide a `ref` argument:
131
132 {% highlight yaml %}
133 dependencies:
134 kittens:
135 git:
136 url: git://github.com/munificent/kittens.git
137 ref: some-branch
138 {% endhighlight %}
139
140 The ref can be anything that Git allows to [identify a commit][commit].
141
142 [commit]: http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#namin g-commits
143
144 ### Path packages
145
146 Sometimes you find yourself working on multiple related packages at the same
147 time. Maybe you are hacking on a framework while building an app that uses it.
148 In those cases, during development you really want to depend on the "live"
149 version of that package on your local file system. That way changes in one
150 package are instantly picked up by the one that depends on it.
151
152 To handle that, pub supports *path dependencies*.
153
154 {% highlight yaml %}
155 dependencies:
156 transmogrify:
157 path: /Users/me/transmogrify
158 {% endhighlight %}
159
160 This says the root directory for `transmogrify` is `/Users/me/transmogrify`.
161 When you use this, pub will generate a symlink directly to the `lib` directory
162 of the referenced package directory. Any changes you make to the dependent
163 package will be seen immediately. You don't need to run pub every time you
164 change the dependent package.
165
166 Relative paths are allowed and are considered relative to the directory
167 containing your pubspec.
168
169 Path dependencies are useful for local development, but do not play nice with
170 sharing code with the outside world. It's not like everyone can get to
171 your file system, after all. Because of this, you cannot upload a package to
172 [pub.dartlang.org][pubsite] if it has any path dependencies in its pubspec.
173
174 Instead, the typical workflow is:
175
176 1. Edit your pubspec locally to use a path dependency.
177 2. Hack on the main package and the package it depends on.
178 3. Once they're both in a happy place, publish the dependent package.
179 4. Then change your pubspec to point to the now hosted version of its dependent.
180 5. Now you can publish your main package too if you want.
181
182 ## Version constraints
183
184 If your package is an application, you don't usually need to specify [version
185 constraints](glossary.html#version-constraint) for your dependencies. You will
186 typically want to use the latest versions of the dependencies when you first
187 create your app. Then you'll create and check in a
188 [lockfile](glossary.html#lockfile) that pins your dependencies to those specific
189 versions. Specifying version constraints in your pubspec then is usually
190 redundant (though you can do it if you want).
191
192 For a [library package](glossary.html#library-package) that you want users to
193 reuse, though, it is important to specify version constraints. That lets people
194 using your package know which versions of its dependencies they can rely on to
195 be compatible with your library. Your goal is to allow a range of versions as
196 wide as possible to give your users flexibility. But it should be narrow enough
197 to exclude versions that you know don't work or haven't been tested.
198
199 The Dart community uses [semantic versioning][], which helps you know which
200 versions should work. If you know that your package works fine with `1.2.3` of
201 some dependency, then semantic versioning tells you that it should work (at
202 least) up to `2.0.0`.
203
204 A version constraint is a series of:
205
206 <dl class="dl-horizontal">
207 <dt><code>any</code></dt>
208 <dd>The string "any" allows any version. This is equivalent to an empty
209 version constraint, but is more explicit.</dd>
210
211 <dt><code>1.2.3</code></dt>
212 <dd>A concrete version number pins the dependency to only allow that
213 <em>exact</em> version. Avoid using this when you can because it can cause
214 version lock for your users and make it hard for them to use your package
215 along with other packages that also depend on it.</dd>
216
217 <dt><code>&gt;=1.2.3</code></dt>
218 <dd>Allows the given version or any greater one. You'll typically use this.
219 </dd>
220
221 <dt><code>&gt;1.2.3</code></dt>
222 <dd>Allows any version greater than the specified one but <em>not</em> that
223 version itself.</dd>
224
225 <dt><code>&lt;=1.2.3</code></dt>
226 <dd>Allows any version lower than or equal to the specified one. You
227 <em>won't</em> typically use this.</dd>
228
229 <dt><code>&lt;1.2.3</code></dt>
230 <dd>Allows any version lower than the specified one but <em>not</em> that
231 version itself. This is what you'll usually use because it lets you specify
232 the upper version that you know does <em>not</em> work with your package
233 (because it's the first version to introduce some breaking change).</dd>
234 </dl>
235
236 You can specify version parts as you want, and their ranges will be intersected
237 together. For example, `>=1.2.3 <2.0.0` allows any version from `1.2.3` to
238 `2.0.0` excluding `2.0.0` itself.
239
240 <aside class="alert alert-warning">
241
242 Note that <code>&gt;</code> is also valid YAML syntax so you will want to quote
243 the version string (like <code>'&lt;=1.2.3 &gt;2.0.0'</code>) if the version
244 constraint starts with that.
245
246 </aside>
247
248 ## Dev dependencies
249
250 Pub supports two flavors of dependencies: regular dependencies and *dev
251 dependencies.* Dev dependencies differ from regular dependencies in that *dev
252 dependencies of packages you depend on are ignored*. That's a mouthful, so
253 here's a motivating example:
254
255 Say the `transmogrify` package uses the `unittest` package in its tests and only
256 in its tests. If someone just wants to use `transmogrify`&mdash;import its
257 libraries&mdash;it doesn't actually need `unittest`. In this case, it specifies
258 `unittest` as a dev dependency. Its pubspec will have something like:
259
260 {% highlight yaml %}
261 dev_dependencies:
262 unittest: '>=0.5.0'
263 {% endhighlight %}
264
265 Pub gets every package your package package depends on, and everything *those*
266 packages depend on, transitively. It also gets your package's dev dependencies,
267 but it *ignores* the dev dependencies of any dependent packages. Pub only gets
268 *your* package's dev dependencies. So when your package depends on
269 `transmogrify` it will get `transmogrify` but not `unittest`.
270
271 The rule for deciding between a regular or dev dependency is pretty simple. If
272 the dependency is imported from something in your `lib` directory, it needs to
273 be a regular dependency. If it's only imported from `test`, `example`, etc. it
274 can and should be a dev dependency.
275
276 Using dev dependencies makes dependency graphs smaller. That makes pub run
277 faster, and makes it easier to find a set of package versions that satisfy all
278 constraints. Use them when you can and your users will thank you.
279
280 [pubsite]: http://pub.dartlang.org
281 [semantic versioning]: http://semver.org/
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698