| OLD | NEW |
|---|
| (Empty) |
| 1 <ol class="toc"> | |
| 2 <li><a href="#installing-and-configuring-pub">Installing and configuring pub</
a></li> | |
| 3 <li><a href="#creating-a-package">Creating a package</a></li> | |
| 4 <li><a href="#adding-a-dependency">Adding a dependency</a></li> | |
| 5 <li><a href="#getting-dependencies">Getting dependencies</a></li> | |
| 6 <li><a href="#importing-code-from-a-dependency">Importing code from a dependen
cy</a></li> | |
| 7 <li><a href="#upgrading-a-dependency">Upgrading a dependency</a></li> | |
| 8 <li><a href="#publishing-a-package">Publishing a package</a></li> | |
| 9 </ol> | |
| 10 | |
| 11 <p><em>Pub</em> is a package manager for Dart. It helps you reuse existing Dart
code | |
| 12 and bundle your Dart apps and libraries so that you can reuse and share them | |
| 13 with other people. Pub handles versioning and dependency management so that you | |
| 14 can ensure that your app runs on other machines exactly the same as it does on | |
| 15 yours.</p> | |
| 16 | |
| 17 <p>To <strong>find</strong> a package that’s on pub.dartlang.org, | |
| 18 use the Search box at the top right of this page.</p> | |
| 19 | |
| 20 <p>To <strong>use</strong> a package that’s on pub.dartlang.org:</p> | |
| 21 | |
| 22 <ol> | |
| 23 <li> | |
| 24 <p>Create a <code>pubspec.yaml</code> file | |
| 25 (if one doesn’t already exist) | |
| 26 and list the package as dependency. | |
| 27 For example, to use the <a href="/packages/web_ui">web_ui</a> package | |
| 28 in an app, put this in a top-level file named <code>pubspec.yaml</code>:</p> | |
| 29 | |
| 30 <pre><code> name: my_app | |
| 31 dependencies: | |
| 32 web_ui: any | |
| 33 </code></pre> | |
| 34 </li> | |
| 35 <li> | |
| 36 <p>Run <code>pub get</code>, either on the command line | |
| 37 or through the Dart Editor menu: Tools > Pub Get.</p> | |
| 38 </li> | |
| 39 <li> | |
| 40 <p>Import one or more libraries from the package:</p> | |
| 41 | |
| 42 <pre><code> import 'package:web_ui/web_ui.dart'; | |
| 43 </code></pre> | |
| 44 </li> | |
| 45 </ol> | |
| 46 | |
| 47 <p>For details and pointers to more documentation, read on.</p> | |
| 48 | |
| 49 <h2 id="installing-and-configuring-pub">Installing and configuring pub</h2> | |
| 50 | |
| 51 <p>Pub is in the <a href="http://www.dartlang.org/docs/sdk/">Dart SDK</a>, | |
| 52 which you can download by itself or as part of | |
| 53 <a href="http://www.dartlang.org/docs/editor/">Dart Editor</a>. | |
| 54 You can use pub through | |
| 55 <a href="http://www.dartlang.org/docs/editor/">Dart Editor</a>, or through the | |
| 56 <code>pub</code> command-line app, which lives inside the <code>bin</code> direc
tory of the Dart SDK.</p> | |
| 57 | |
| 58 <p>To use pub and other tools on the command line, | |
| 59 you might want to add the SDK’s <code>bin</code> directory to your system
path. | |
| 60 For example, on Mac and Linux:</p> | |
| 61 | |
| 62 <pre><code>export PATH=$PATH:<path to sdk>/bin | |
| 63 </code></pre> | |
| 64 | |
| 65 <p>Here, <code><path to sdk></code> is the absolute path | |
| 66 to the main directory of the SDK. For example, | |
| 67 if you install Dart Editor in | |
| 68 <code>/home/me/dart</code>, then add this to your PATH:</p> | |
| 69 | |
| 70 <pre><code>/home/me/dart/dart-sdk/bin | |
| 71 </code></pre> | |
| 72 | |
| 73 <p>On Windows, you can set the system PATH environment variable through the | |
| 74 Control Panel. A quick | |
| 75 <a href="https://www.google.com/search?q=windows+set+environment+variable">searc
h</a> | |
| 76 should find the instructions for your version of Windows.</p> | |
| 77 | |
| 78 <h2 id="creating-a-package">Creating a package</h2> | |
| 79 | |
| 80 <div class="learn-more"> | |
| 81 <a href="/doc/package-layout.html"> | |
| 82 Learn more about packages → | |
| 83 </a> | |
| 84 </div> | |
| 85 | |
| 86 <p>A <strong>package</strong> in pub is a directory that contains Dart code and
any other stuff | |
| 87 that goes along with it like resources, tests, and docs. Frameworks and | |
| 88 reusable libraries are obviously packages, but applications are too. If your | |
| 89 app wants to use pub packages, it needs to be a package too.</p> | |
| 90 | |
| 91 <p>While everything is a package in pub, there are two flavors of packages that
are | |
| 92 used slightly differently in practice. A <a href="glossary.html#library-package"
><strong>library | |
| 93 package</strong></a> is a package that is intended to be | |
| 94 reused by other packages. It will usually have code that other packages import, | |
| 95 and it will likely be hosted somewhere that people can get to. An <a href="gloss
ary.html#application-package"><strong>application | |
| 96 package</strong></a> only <em>consumes</em> packages but | |
| 97 doesn’t itself get reused. In other words, library packages will be used a
s | |
| 98 dependencies, but application packages won’t.</p> | |
| 99 | |
| 100 <p>In most cases, there’s no difference between the two and we’ll ju
st say | |
| 101 “package”. In the few places where it does matter, we’ll speci
fy “library | |
| 102 package” or “application package”.</p> | |
| 103 | |
| 104 <div class="learn-more"> | |
| 105 <a href="/doc/pubspec.html"> | |
| 106 Learn more about pubspecs → | |
| 107 </a> | |
| 108 </div> | |
| 109 | |
| 110 <p>To turn your app into an application package so it can use other packages, yo
u | |
| 111 just need to give it a <strong>pubspec</strong>. This file is written using the | |
| 112 <a href="http://yaml.org">YAML language</a> and is named <code>pubspec.yaml</cod
e>. The simplest | |
| 113 possible pubspec just contains the name of the package. Save the pubspec file as | |
| 114 <code>pubspec.yaml</code> in the root directory of your app.</p> | |
| 115 | |
| 116 <p>Behold, the simplest possible <code>pubspec.yaml</code>:</p> | |
| 117 | |
| 118 <div class="highlight"><pre><code class="yaml"><span class="l-Scalar-Plain">name
</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">my_app</s
pan> | |
| 119 </code></pre></div> | |
| 120 | |
| 121 <p>Now <code>my_app</code> is a pub package!</p> | |
| 122 | |
| 123 <h2 id="adding-a-dependency">Adding a dependency</h2> | |
| 124 | |
| 125 <div class="learn-more"> | |
| 126 <a href="/doc/dependencies.html"> | |
| 127 Learn more about dependencies → | |
| 128 </a> | |
| 129 </div> | |
| 130 | |
| 131 <p>One of pub’s main jobs is managing <strong>dependencies</strong>. A dep
endency is just | |
| 132 another package that your package relies on. If your app is using some | |
| 133 transformation library called “transmogrify”, then your app package
will depend | |
| 134 on the <code>transmogrify</code> package.</p> | |
| 135 | |
| 136 <p>You specify your package’s dependencies in the pubspec file immediately
after | |
| 137 your package name. For example:</p> | |
| 138 | |
| 139 <div class="highlight"><pre><code class="yaml"><span class="l-Scalar-Plain">name
</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">my_app</s
pan> | |
| 140 <span class="l-Scalar-Plain">dependencies</span><span class="p-Indicator">:</spa
n> | |
| 141 <span class="l-Scalar-Plain">transmogrify</span><span class="p-Indicator">:</s
pan> | |
| 142 </code></pre></div> | |
| 143 | |
| 144 <p>Here, we are declaring a dependency on the (fictional) <code>transmogrify</co
de> package.</p> | |
| 145 | |
| 146 <h2 id="getting-dependencies">Getting dependencies</h2> | |
| 147 | |
| 148 <div class="learn-more"> | |
| 149 <a href="/doc/pub-get.html"> | |
| 150 Learn more about <tt>pub get</tt> → | |
| 151 </a> | |
| 152 </div> | |
| 153 | |
| 154 <p>Once you’ve declared a dependency, you then tell pub to get it for you.
If | |
| 155 you’re using the Editor, select “Pub Get” from the “Tool
s” menu. If you’re | |
| 156 rocking the command line, do:</p> | |
| 157 | |
| 158 <pre><code>$ cd path/to/your_app | |
| 159 $ pub get | |
| 160 </code></pre> | |
| 161 | |
| 162 <aside class="alert alert-warning"> | |
| 163 Today, this command must be run from the directory containing | |
| 164 <tt>pubspec.yaml</tt>. In the future, you will be able to run it from any | |
| 165 sub-directory of the package. | |
| 166 </aside> | |
| 167 | |
| 168 <p>When you do this, pub will create a <code>packages</code> directory in the sa
me directory | |
| 169 as <code>pubspec.yaml</code>. In there, it will place each package that your pac
kage | |
| 170 depends on (these are called your <strong>immediate dependencies</strong>). It w
ill also | |
| 171 look at all of those packages and get everything <em>they</em> depend on, recurs
ively | |
| 172 (these are your <strong>transitive dependencies</strong>).</p> | |
| 173 | |
| 174 <p>When this is done, you will have a <code>packages</code> directory that conta
ins every | |
| 175 single package your program needs in order to run.</p> | |
| 176 | |
| 177 <h2 id="importing-code-from-a-dependency">Importing code from a dependency</h2> | |
| 178 | |
| 179 <p>Now that you have a dependency wired up, you want to be able to use code from | |
| 180 it. To access a library in a another package, you will import it using the | |
| 181 <code>package:</code> scheme:</p> | |
| 182 | |
| 183 <div class="highlight"><pre><code class="dart"><span class="k">import</span> <sp
an class="s1">'package:transmogrify/transmogrify.dart'</span><span class
="p">;</span> | |
| 184 </code></pre></div> | |
| 185 | |
| 186 <p>This looks inside the <code>transmogrify</code> package for a top-level file
named | |
| 187 <code>transmogrify.dart</code>. Most packages just define a single entrypoint wh
ose name | |
| 188 is the same as the name of the package. Check the documentation for the package | |
| 189 to see if it exposes anything different for you to import.</p> | |
| 190 | |
| 191 <aside class="alert alert-info"> | |
| 192 This works by looking inside the generated <tt>packages</tt> directory. If you | |
| 193 get an error, the directory may be out of date. Fix it by running | |
| 194 <tt>pub get</tt> whenever you change your pubspec. | |
| 195 </aside> | |
| 196 | |
| 197 <p>You can also use this style to import libraries from within your own package. | |
| 198 For example, let’s say your package is laid out like:</p> | |
| 199 | |
| 200 <pre><code>transmogrify/ | |
| 201 lib/ | |
| 202 transmogrify.dart | |
| 203 parser.dart | |
| 204 test/ | |
| 205 parser/ | |
| 206 parser_test.dart | |
| 207 </code></pre> | |
| 208 | |
| 209 <p>The <code>parser_test</code> file <em>could</em> import <code>parser.dart</co
de> like this:</p> | |
| 210 | |
| 211 <div class="highlight"><pre><code class="dart"><span class="k">import</span> <sp
an class="s1">'../../lib/parser.dart'</span><span class="p">;</span> | |
| 212 </code></pre></div> | |
| 213 | |
| 214 <p>But that’s a pretty nasty relative path. If <code>parser_test.dart</cod
e> is ever moved | |
| 215 up or down a directory, that path will break and you’ll have to fix the co
de. | |
| 216 Instead, you can do:</p> | |
| 217 | |
| 218 <div class="highlight"><pre><code class="dart"><span class="k">import</span> <sp
an class="s1">'package:transmogrify/parser.dart'</span><span class="p">;
</span> | |
| 219 </code></pre></div> | |
| 220 | |
| 221 <p>This way, the import can always get to <code>parser.dart</code> regardless of
where the | |
| 222 importing file is.</p> | |
| 223 | |
| 224 <!-- TODO(rnystrom): Enable this when that doc exists. | |
| 225 <div class="learn-more"> | |
| 226 <a href="/doc/package-scheme.html"> | |
| 227 Learn more about the <tt>package:</tt> scheme | |
| 228 <i class="icon-hand-right icon-white"> </i> | |
| 229 </a> | |
| 230 </div> | |
| 231 --> | |
| 232 | |
| 233 <h2 id="upgrading-a-dependency">Upgrading a dependency</h2> | |
| 234 | |
| 235 <div class="learn-more"> | |
| 236 <a href="/doc/pub-upgrade.html"> | |
| 237 Learn more about <tt>pub upgrade</tt> → | |
| 238 </a> | |
| 239 </div> | |
| 240 | |
| 241 <p>The first time you get a new dependency for your package, pub will download t
he | |
| 242 latest version of it that’s compatible with your other dependencies. It th
en | |
| 243 locks your package to <em>always</em> use that version by creating a <strong>loc
kfile</strong>. | |
| 244 This is a file named <code>pubspec.lock</code> that pub creates and stores next
to your | |
| 245 pubspec. It lists the specific versions of each dependency (immediate and | |
| 246 transitive) that your package uses.</p> | |
| 247 | |
| 248 <p>If this is an application package, you will check this file into source contr
ol. | |
| 249 That way, everyone hacking on your app ensures they are using the same versions | |
| 250 of all of the packages. This also makes sure you use the same versions of stuff | |
| 251 when you deploy your app to production.</p> | |
| 252 | |
| 253 <p>When you are ready to upgrade your dependencies to the latest versions, do:</
p> | |
| 254 | |
| 255 <pre><code>$ pub upgrade | |
| 256 </code></pre> | |
| 257 | |
| 258 <p>This tells pub to regenerate the lockfile using the newest available versions
of | |
| 259 your package’s dependencies. If you only want to upgrade a specific depend
ency, | |
| 260 you can specify that too:</p> | |
| 261 | |
| 262 <pre><code>$ pub upgrade transmogrify | |
| 263 </code></pre> | |
| 264 | |
| 265 <p>This upgrades <code>transmogrify</code> to the latest version but leaves ever
ything else | |
| 266 the same.</p> | |
| 267 | |
| 268 <h2 id="publishing-a-package">Publishing a package</h2> | |
| 269 | |
| 270 <div class="learn-more"> | |
| 271 <a href="/doc/pub-lish.html"> | |
| 272 Learn more about <tt>pub publish</tt> → | |
| 273 </a> | |
| 274 </div> | |
| 275 | |
| 276 <p>Pub isn’t just for using other people’s packages. It also allows
you to share | |
| 277 your packages with the world. Once you’ve written some useful code and you
want | |
| 278 everyone else to be able to use it, just run:</p> | |
| 279 | |
| 280 <pre><code>$ pub publish | |
| 281 </code></pre> | |
| 282 | |
| 283 <p>Pub will check to make sure that your package follows the <a href="pubspec.ht
ml">pubspec | |
| 284 format</a> and <a href="package-layout.html">package layout conventions</a>, and | |
| 285 then upload your package to <a href="http://pub.dartlang.org">pub.dartlang.org</
a>. Then | |
| 286 any Pub user will be able to download it or depend on it in their pubspecs. For | |
| 287 example, if you just published version 1.0.0 of a package named <code>transmogri
fy</code>, | |
| 288 then they can write:</p> | |
| 289 | |
| 290 <div class="highlight"><pre><code class="yaml"><span class="l-Scalar-Plain">depe
ndencies</span><span class="p-Indicator">:</span> | |
| 291 <span class="l-Scalar-Plain">transmogrify</span><span class="p-Indicator">:</s
pan> <span class="s">">=</span><span class="nv"> </span><span class="s">
1.0.0</span><span class="nv"> </span><span class="s"><</span><span class="nv"
> </span><span class="s">2.0.0"</span> | |
| 292 </code></pre></div> | |
| 293 | |
| 294 <p>Keep in mind that publishing is forever. As soon as you publish your awesome | |
| 295 package, users will be able to depend on it. Once they start doing that, | |
| 296 removing the package would break theirs. To avoid that, pub strongly discourages | |
| 297 deleting packages. You can always upload new versions of your package, but old | |
| 298 ones will continue to be available for users that aren’t ready to upgrade
yet.</p> | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 162403002:
Remove docs and point to ones on dartlang.org. (Closed)
Base URL: https://github.com/dart-lang/pub-dartlang.git@master