| OLD | NEW |
|---|
| (Empty) |
| 1 --- | |
| 2 layout: default | |
| 3 title: "Target 5: Install Shared Packages" | |
| 4 description: "Packages are bundles of source code, tools, and resources that hel
p you to organize and share code" | |
| 5 has-permalinks: true | |
| 6 tutorial: | |
| 7 id: packages | |
| 8 next: web-ui | |
| 9 next-title: "Get Started with Web UI" | |
| 10 prev: remove-elements | |
| 11 prev-title: "Remove DOM Elements" | |
| 12 --- | |
| 13 | |
| 14 {% capture whats_the_point %} | |
| 15 | |
| 16 * Packages are awesome. | |
| 17 * Packages are cool. | |
| 18 * Share your code in packages, with all your friends at school. | |
| 19 | |
| 20 {% endcapture %} | |
| 21 | |
| 22 {% capture sample_links %} | |
| 23 | |
| 24 <p> | |
| 25 Get the vector_math package and many others from:</p> | |
| 26 | |
| 27 <ul> | |
| 28 <li> | |
| 29 <a href="http://pub.dartlang.org/" | |
| 30 target="_blank">pub.dartlang.org</a> | |
| 31 </li> | |
| 32 </ul> | |
| 33 | |
| 34 {% endcapture %} | |
| 35 | |
| 36 {% capture content %} | |
| 37 | |
| 38 Now that you're able to create and run a Dart application | |
| 39 and have a basic understanding of DOM programming, | |
| 40 you are ready to leverage code written by other programmers. | |
| 41 Many interesting and useful packages of reusable Dart code | |
| 42 are available at the | |
| 43 <a href="http://pub.dartlang.org/">pub.dartlang.org</a> | |
| 44 repository. | |
| 45 | |
| 46 This target shows you how to use `pub`—a package manager | |
| 47 that comes with Dart—to | |
| 48 install one of the packages in the repository, | |
| 49 the vector_math package. | |
| 50 You can follow these same steps to install any package hosted at | |
| 51 <a href="http://pub.dartlang.org/">pub.dartlang.org</a>; | |
| 52 just change the package name when you get to that step. | |
| 53 This target also describes some of the resources you can expect to find | |
| 54 in a well-built package. | |
| 55 | |
| 56 * [About the pubspec.yaml file](#about-pubspec) | |
| 57 * [Name the package dependencies](#name-dependencies) | |
| 58 * [Install the package dependencies](#install-dependencies) | |
| 59 * [What did you get (and not get)?](#about-packages) | |
| 60 * [Import libraries from a package](#use-package) | |
| 61 * [Other resources](#other-resources) | |
| 62 | |
| 63 ##About the pubspec.yaml file {#about-pubspec} | |
| 64 | |
| 65 To use an external package, | |
| 66 your application must itself be a package. | |
| 67 Any application with a valid pubspec.yaml file in its top-level directory | |
| 68 is a package and can therefore use external packages. | |
| 69 When you create an application using Dart Editor, | |
| 70 Dart Editor automatically creates a `pubspec.yaml` file. | |
| 71 | |
| 72 Start Dart Editor and create a new application with the name `vector_victor`. | |
| 73 Double click pubspec.yaml to view its contents. | |
| 74 | |
| 75  | |
| 76 | |
| 77 The pubspec.yaml file contains the package specification written in YAML | |
| 78 (visit <a href="http://pub.dartlang.org/doc/pubspec.html">Pubspec Format</a> | |
| 79 for in-depth coverage). | |
| 80 Dart Editor provides a user interface for editing the pubspec.yaml file | |
| 81 so that you don't have to worry about the YAML format. | |
| 82 Or you can click the **Source** tab at the bottom of the Editor pane | |
| 83 to edit the YAML code directly. | |
| 84 Below is the pubspec.yaml file that was | |
| 85 created for the vector_victor application. | |
| 86 | |
| 87  | |
| 88 | |
| 89 The package name is required. | |
| 90 All web applications are dependent on the browser package | |
| 91 provided at pub.dartlang.org. | |
| 92 | |
| 93 {% comment %} | |
| 94 ##...Or put an existing application into a package {#old-app-in-pkg} | |
| 95 | |
| 96 If you already have an application | |
| 97 and want it to use an external package, | |
| 98 simply create a pubspec.yaml file in the application's top-level directory. | |
| 99 Your pubspec.yaml file must at least specify the package name. | |
| 100 | |
| 101  | |
| 102 | |
| 103 <aside class="alert"> | |
| 104 <strong>Tip:</strong> If you are using | |
| 105 Dart Editor to create the pubspec.yaml file, | |
| 106 you might get an error message | |
| 107 when you first create the empty pubspec.yaml file. | |
| 108 This is because Dart Editor runs pub automatically and | |
| 109 is trying to resolve the package specification file, | |
| 110 which at first has nothing in it. | |
| 111 Ignore the message, | |
| 112 add the required name field, | |
| 113 and save the pubspec.yaml file. | |
| 114 </aside> | |
| 115 {% endcomment %} | |
| 116 | |
| 117 ##Name the package dependencies {#name-dependencies} | |
| 118 | |
| 119 To use an external library package, | |
| 120 you need to add the package to your | |
| 121 application's list of _dependencies_ | |
| 122 in the pubspec.yaml file. | |
| 123 Each item in the dependencies list | |
| 124 specifies the name, and sometimes the version, | |
| 125 of a package that your application uses. | |
| 126 | |
| 127 Let's make the vector_victor application have a dependency | |
| 128 on the vector_math package, | |
| 129 which is available at pub.dartlang.org. | |
| 130 Click the **Add** button in Dart Editor. | |
| 131 | |
| 132  | |
| 133 | |
| 134 Enter the name of the package in the popup window. | |
| 135 | |
| 136  | |
| 137 | |
| 138 Dart Editor adds the package name to the list. | |
| 139 | |
| 140  | |
| 141 | |
| 142 Notice the **Version** field. | |
| 143 `any` means that this application can use | |
| 144 any version of the vector_math package. | |
| 145 You could instead specify a particular version of the package. | |
| 146 When versioning becomes important to your project, | |
| 147 check out | |
| 148 <a href="http://pub.dartlang.org/doc/versioning.html"> | |
| 149 Pub's Versioning Philosophy | |
| 150 </a>. | |
| 151 | |
| 152 Here's the new pubspec.yaml file: | |
| 153 | |
| 154  | |
| 155 | |
| 156 <a href="http://pub.dartlang.org/">pub.dartlang.org</a> | |
| 157 is the primary public repository for Dart packages. | |
| 158 `pub` automatically checks that | |
| 159 website when resolving package dependencies. | |
| 160 To use one of the packages from that site, | |
| 161 you can specify it by its simple name, | |
| 162 as we have done here. | |
| 163 | |
| 164 ##Install the package dependencies {#install-dependencies} | |
| 165 | |
| 166 In Dart Editor, save pubspec.yaml with **File > Save**. | |
| 167 When you save the file, | |
| 168 Dart Editor automatically runs | |
| 169 <a href="http://pub.dartlang.org/doc/pub-install.html">pub install</a>, | |
| 170 which recursively installs the Dart libraries | |
| 171 from the packages in the dependencies list. | |
| 172 You can also select **Pub Install** from the **Tools** menu in Dart Editor. | |
| 173 | |
| 174 Pub puts the libraries in a directory called packages | |
| 175 under the application's top-level directory. | |
| 176 Click the wee arrow to expand the packages directory. | |
| 177 There you will find the vector_math directory, | |
| 178 which links to the Dart libraries from the vector_math package. | |
| 179 | |
| 180  | |
| 181 | |
| 182 Pub install works recursively; | |
| 183 if the included package has dependencies, those packages are installed as well. | |
| 184 | |
| 185 Pub install creates a file called pubspec.lock, | |
| 186 which identifies the specific versions of the packages that were installed. | |
| 187 This helps to provide a stable development environment. | |
| 188 Later you can modify the version constraints and use `pub update` | |
| 189 to update to new versions as needed. | |
| 190 | |
| 191 ##What did you get (and not get)? {#about-packages} | |
| 192 | |
| 193 Besides the Dart libraries, | |
| 194 the vector_math package has other resources that might be useful to you | |
| 195 that do not get installed into your application directory. | |
| 196 Let's take a step back for a moment to look at what | |
| 197 you got and where it came from. | |
| 198 | |
| 199 To see the contents of the vector_math package, | |
| 200 visit the | |
| 201 <a href="https://github.com/johnmccutchan/vector_math" target="_blank"> | |
| 202 Dart vector math repository | |
| 203 </a> | |
| 204 at GitHub. | |
| 205 Although many files and directories are in the repository, | |
| 206 only one, `lib`, was installed when you ran pub install. | |
| 207 | |
| 208 <div> | |
| 209 <hr> | |
| 210 <div class="row"> | |
| 211 <div class="span2"> | |
| 212 <img src="images/libraries-folder.png" | |
| 213 alt="Dart libraries directory"/> | |
| 214 </div> | |
| 215 <div class="span7"> | |
| 216 <em>Dart libraries</em>: | |
| 217 The lib directory contains one or more Dart libraries, | |
| 218 which can be imported into your Dart programs. | |
| 219 </div> | |
| 220 </div> | |
| 221 <hr> | |
| 222 <div class="row"> | |
| 223 <div class="span2"> | |
| 224 <img src="images/housekeeping-files.png" | |
| 225 alt="Housekeeping files"/> | |
| 226 </div> | |
| 227 <div class="span7"> | |
| 228 <em>Housekeeping files</em>: | |
| 229 When using a package written by someone else, | |
| 230 the README file is a good place to start. | |
| 231 It should contain important information about the package, | |
| 232 such as its intent, contents, samples, and instructions. | |
| 233 The LICENSE file provides copyright and rules-of-use information. | |
| 234 These files can be found at the package repository. | |
| 235 They are not installed when you install a package. | |
| 236 </div> | |
| 237 </div> | |
| 238 <hr> | |
| 239 <div class="row"> | |
| 240 <div class="span2"> | |
| 241 <img src="images/other-folders.png" | |
| 242 alt="Document, scripts, tests, and other resources"/> | |
| 243 </div> | |
| 244 <div class="span7"> | |
| 245 <em>Other resources</em>: | |
| 246 Along with Dart libraries, | |
| 247 a package might also contain other resources | |
| 248 such as example code, tests, scripts, and documentation. | |
| 249 If a package contains these resources, | |
| 250 they should be in the directories as specified in the pub | |
| 251 <a href="http://pub.dartlang.org/doc/package-layout.html">conventions</a>. | |
| 252 </div> | |
| 253 </div> | |
| 254 <hr> | |
| 255 </div> | |
| 256 | |
| 257 ##Import libraries from a package {#use-package} | |
| 258 | |
| 259 Open the vector_math directory by clicking the little arrow. | |
| 260 | |
| 261  | |
| 262 | |
| 263 The directory contains a Dart file, | |
| 264 which you import into your Dart application, | |
| 265 and a `src` directory, | |
| 266 which contains all of the source code for the library. | |
| 267 As with the SDK libraries, | |
| 268 use the import directive to use code from an installed library. | |
| 269 The Dart SDK libraries are built-in and | |
| 270 are identified with the special dart: prefix. | |
| 271 For external libraries installed by pub, | |
| 272 use the `package:` prefix. | |
| 273 | |
| 274 {% prettify dart %} | |
| 275 import 'package:vector_math/vector_math.dart'; | |
| 276 {% endprettify %} | |
| 277 | |
| 278 Note that you specify the filename, not the library name. | |
| 279 | |
| 280 ##Other resources | |
| 281 | |
| 282 <ul> | |
| 283 <li> | |
| 284 Dart developers share packages at | |
| 285 <a href="http://pub.dartlang.org/">pub.dartlang.org</a>. | |
| 286 Look there for packages that might be useful to you, | |
| 287 or share your own Dart packages. | |
| 288 See the <a href="http://pub.dartlang.org/doc/">pub documentation</a> | |
| 289 to get started using and sharing packages. | |
| 290 </li> | |
| 291 <li> | |
| 292 One important package that you will find there | |
| 293 is | |
| 294 <a href="http://pub.dartlang.org/packages/web_ui">web_ui</a>—a package | |
| 295 created by the Dart team that lets you use Web components and templating. | |
| 296 The | |
| 297 <a href="/docs/tutorials/web-ui/">next target</a> covers Web UI. | |
| 298 </li> | |
| 299 </ul> | |
| 300 | |
| 301 {% endcapture %} | |
| 302 | |
| 303 {% include tutorial.html %} | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 19238002:
mockup for tute front page refresh. With tabs. Huzzah (Closed)
Base URL: https://github.com/dart-lang/dartlang.org.git@master
