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