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

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: 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 unified diff | Download patch

OLD	NEW
	(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’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>—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">'>=1.0.0</span><span class="nv"> </span><span class= "s"><2.0.0'</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">'>=1.0.0</span><span class="nv"> </span><span class="s" ><2.0.0'</span>

67 </code></pre></div>

68

69 <p>This long form is used when you don’t use the default source or when yo u have a

70 complex description you need to specify. But in most cases, you’ll just us e the

71 simple “name: version” 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">'>=0.4.0</span><span class="nv"> </span><span class= "s"><1.0.0'</span>

86 </code></pre></div>

87

88 <p>Here, you’re saying your package depends on a hosted package named

89 “transmogrify” and you’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">'>=0.4.0</span><span class="nv"> </span><span class="s" ><1.0.0'</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 “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’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’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’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’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’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’t work or haven’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>>=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>>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><=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><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>>=1.2.3 <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>></code> is also valid YAML syntax so you will want to quote

232 the version string (like <code>'<=1.2.3 >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’s a mouthful , so

242 here’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>—impor t its

246 libraries—it doesn’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">'>=0.5.0'</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’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’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’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

OLD	NEW

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