| OLD | NEW |
| 1 --- | 1 --- |
| 2 layout: default | 2 layout: default |
| 3 title: "Pub: What is a Pubspec?" | 3 title: "Pub: What is a Pubspec?" |
| 4 description: "More details about the pubspec format and contents." | 4 description: "More details about the pubspec format and contents." |
| 5 has-permalinks: true | 5 has-permalinks: true |
| 6 --- | 6 --- |
| 7 | 7 |
| 8 # {{ page.title }} | 8 # {{ page.title }} |
| 9 | 9 |
| 10 Every pub package needs some metadata so it can specify its dependencies. Pub | 10 Every pub package needs some metadata so it can specify its dependencies. Pub |
| (...skipping 11 matching lines...) Expand all Loading... |
| 22 Have you been turned into a newt? Would you like to be? This | 22 Have you been turned into a newt? Would you like to be? This |
| 23 package can help: it has all of the newt-transmogrification | 23 package can help: it has all of the newt-transmogrification |
| 24 functionality you've been looking for. | 24 functionality you've been looking for. |
| 25 dependencies: | 25 dependencies: |
| 26 efts: '>=2.0.4 <3.0.0' | 26 efts: '>=2.0.4 <3.0.0' |
| 27 transmogrify: '>=0.4.0' | 27 transmogrify: '>=0.4.0' |
| 28 {% endhighlight %} | 28 {% endhighlight %} |
| 29 | 29 |
| 30 ## Name | 30 ## Name |
| 31 | 31 |
| 32 Every package needs a name. When your stellar code gets props on the world | 32 **Required** |
| 33 stage, this is what they'll be hollering. Also, it's how other packages will | 33 |
| 34 refer to yours, and how it will appear on [pub.dartlang.org][pubsite], should | 34 Every package needs a name. When your stellar code gets props on |
| 35 you publish it. | 35 the world stage, this is what they'll be hollering. Also, it's how other |
| 36 packages will refer to yours, and how it will appear on |
| 37 [pub.dartlang.org][pubsite], should you publish it. |
| 36 | 38 |
| 37 It should be all lowercase, with underscores to separate words, | 39 It should be all lowercase, with underscores to separate words, |
| 38 `just_like_this`. Stick with basic Latin letters and Arabic digits: | 40 `just_like_this`. Stick with basic Latin letters and Arabic digits: |
| 39 `[a-z0-9_]` and ensure that it's a valid Dart identifier (i.e. doesn't start | 41 `[a-z0-9_]` and ensure that it's a valid Dart identifier (i.e. doesn't start |
| 40 with digits and isn't a reserved word). | 42 with digits and isn't a reserved word). |
| 41 | 43 |
| 42 Try to pick a name that is clear, terse, and not already in use. A quick search | 44 Try to pick a name that is clear, terse, and not already in use. A quick search |
| 43 on [pub.dartlang.org][pubsite] to make sure nothing else is using your name can | 45 on [pub.dartlang.org][pubsite] to make sure nothing else is using your name can |
| 44 save you heartache later. | 46 save you heartache later. |
| 45 | 47 |
| 46 ## Version | 48 ## Version |
| 47 | 49 |
| 48 Every package has a version. No one really gets excited about versioning, but | 50 Every package has a version. A version number is required to host your package o
n |
| 51 [pub.dartlang.org][pubsite], but can be omitted for local-only packages. If you |
| 52 omit it, your package is implicitly versioned `0.0.0`. |
| 53 |
| 54 No one really gets excited about versioning, but |
| 49 it's a necessary evil for reusing code while letting it evolve quickly. A | 55 it's a necessary evil for reusing code while letting it evolve quickly. A |
| 50 version number is three numbers separated by dots, like `0.2.43`. It can also | 56 version number is three numbers separated by dots, like `0.2.43`. It can also |
| 51 optionally have a build (`+hotfix.oopsie`) or pre-release (`-alpha.12`) suffix. | 57 optionally have a build (`+hotfix.oopsie`) or pre-release (`-alpha.12`) suffix. |
| 52 | 58 |
| 53 Each time you publish your package, you will publish it at a specific version. | 59 Each time you publish your package, you will publish it at a specific version. |
| 54 Once that's been done, consider it hermetically sealed: you can't touch it | 60 Once that's been done, consider it hermetically sealed: you can't touch it |
| 55 anymore. To make more changes, you'll need a new version. | 61 anymore. To make more changes, you'll need a new version. |
| 56 | 62 |
| 57 When you select a version, follow [semantic versioning][]. When you do, the | 63 When you select a version, follow [semantic versioning][]. When you do, the |
| 58 clouds will part and sunshine will pour into your soul. If you don't, prepare | 64 clouds will part and sunshine will pour into your soul. If you don't, prepare |
| 59 yourself for hordes of angry users. | 65 yourself for hordes of angry users. |
| 60 | 66 |
| 61 [semantic versioning]: http://semver.org | 67 [semantic versioning]: http://semver.org |
| 62 | 68 |
| 63 A version number is required to host your package on | |
| 64 [pub.dartlang.org][pubsite], but can be omitted for local-only packages. If you | |
| 65 omit it, your package is implicitly versioned `0.0.0`. | |
| 66 | |
| 67 ## Description | 69 ## Description |
| 68 | 70 |
| 69 This is optional for your own personal packages, but if you intend to share | 71 This is optional for your own personal packages, but if you intend to share |
| 70 your package with the world (and you should because, let's be honest with | 72 your package with the world (and you should because, let's be honest with |
| 71 ourselves, it's a thing of beauty) you must provide a description. This should | 73 ourselves, it's a thing of beauty) you must provide a description. This should |
| 72 be relatively short—a few sentences, maybe a whole paragraph—and | 74 be relatively short—a few sentences, maybe a whole paragraph—and |
| 73 tells a casual reader what they might want to know about your package. | 75 tells a casual reader what they might want to know about your package. |
| 74 | 76 |
| 75 Think of the description as the sales pitch for your package. Users will see it | 77 Think of the description as the sales pitch for your package. Users will see it |
| 76 when they browse [pub.dartlang.org][pubsite]. It should be simple plain text: | 78 when they browse [pub.dartlang.org][pubsite]. It should be simple plain text: |
| (...skipping 222 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 299 <aside><div class="alert alert-warning"> | 301 <aside><div class="alert alert-warning"> |
| 300 | 302 |
| 301 Note that <code>></code> is also valid YAML syntax so you will want to quote | 303 Note that <code>></code> is also valid YAML syntax so you will want to quote |
| 302 the version string (like <code>'<=1.2.3 >2.0.0'</code>) if the version | 304 the version string (like <code>'<=1.2.3 >2.0.0'</code>) if the version |
| 303 constraint starts with that. | 305 constraint starts with that. |
| 304 | 306 |
| 305 </div></aside> | 307 </div></aside> |
| 306 | 308 |
| 307 [pubsite]: http://pub.dartlang.org | 309 [pubsite]: http://pub.dartlang.org |
| 308 [semantic versioning]: http://semver.org/ | 310 [semantic versioning]: http://semver.org/ |
| OLD | NEW |