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

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

Powered by Google App Engine
This is Rietveld 408576698