Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(863)

Side by Side Diff: app/doc/pubspec.markdown

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: Re-upload. 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
OLDNEW
(Empty)
1 ---
2 title: "Pubspec Format"
3 ---
4
5 1. [Name](#name)
6 1. [Version](#version)
7 1. [Description](#description)
8 1. [Author/Authors](#authorauthors)
9 1. [Homepage](#homepage)
10 1. [Documentation](#documentation)
11 1. [Dependencies](#dependencies)
12 1. [SDK constraints](#sdk-constraints)
13 {:.toc}
14
15 Every pub package needs some metadata so it can specify its
16 [dependencies](glossary.html#dependency). Pub packages that are shared with
17 others also need to provide some other information so users can discover them.
18 Pub stores this in a file named `pubspec.yaml`, which (naturally) is written in
19 the [YAML](http://www.yaml.org/) language.
20
21 At the top level are a series of fields. The currently supported ones are:
22
23 <dl class="dl-horizontal">
24 <dt>Name</dt>
25 <dd>Required for every package.</dd>
26 <dt>Version</dt>
27 <dd>Required for packages that will be hosted on pub.dartlang.org.</dd>
28 <dt>Description</dt>
29 <dd>Required for packages that will be hosted on pub.dartlang.org.</dd>
30 <dt>Author/Authors</dt>
31 <dd>Optional.</dd>
32 <dt>Homepage</dt>
33 <dd>Optional.</dd>
34 <dt>Documentation</dt>
35 <dd>Optional.</dd>
36 <dt>Dependencies</dt>
37 <dd>Can be omitted if your package has no dependencies.</dd>
38 <dt>Dev dependencies</dt>
39 <dd>Can be omitted if your package has no dev dependencies.</dd>
40 </dl>
41
42 All other fields will be ignored. A simple but complete pubspec looks something
43 like this:
44
45 {% highlight yaml %}
46 name: newtify
47 version: 1.2.3
48 description: >
49 Have you been turned into a newt? Would you like to be? This
50 package can help: it has all of the newt-transmogrification
51 functionality you've been looking for.
52 author: Nathan Weizenbaum <nweiz@google.com>
53 homepage: http://newtify.dartlang.org
54 documentation: http://docs.newtify.com
55 dependencies:
56 efts: '>=2.0.4 <3.0.0'
57 transmogrify: '>=0.4.0'
58 dev_dependencies:
59 unittest: '>=0.6.0'
60 {% endhighlight %}
61
62 ## Name
63
64 Every package needs a name. When your stellar code gets props on
65 the world stage, this is what they'll be hollering. Also, it's how other
66 packages will refer to yours, and how it will appear here, should you publish
67 it.
68
69 It should be all lowercase, with underscores to separate words,
70 `just_like_this`. Stick with basic Latin letters and Arabic digits:
71 `[a-z0-9_]` and ensure that it's a valid Dart identifier (i.e. doesn't start
72 with digits and isn't a reserved word).
73
74 Try to pick a name that is clear, terse, and not already in use. A quick search
75 [here](/packages) to make sure nothing else is using your name can save you
76 heartache later.
77
78 ## Version
79
80 Every package has a version. A version number is required to host your package
81 here, but can be omitted for local-only packages. If you omit it, your package
82 is implicitly versioned `0.0.0`.
83
84 No one really gets excited about versioning, but it's a necessary evil for
85 reusing code while letting it evolve quickly. A version number is three numbers
86 separated by dots, like `0.2.43`. It can also optionally have a build
87 (`+hotfix.oopsie`) or pre-release (`-alpha.12`) suffix.
88
89 Each time you publish your package, you will publish it at a specific version.
90 Once that's been done, consider it hermetically sealed: you can't touch it
91 anymore. To make more changes, you'll need a new version.
92
93 When you select a version, follow [semantic versioning][]. When you do, the
94 clouds will part and sunshine will pour into your soul. If you don't, prepare
95 yourself for hordes of angry users.
96
97 [semantic versioning]: http://semver.org
98
99 ## Description
100
101 This is optional for your own personal packages, but if you intend to share
102 your package with the world (and you should because, let's be honest with
103 ourselves, it's a thing of beauty) you must provide a description. This should
104 be relatively short&mdash;a few sentences, maybe a whole paragraph&mdash;and
105 tells a casual reader what they might want to know about your package.
106
107 Think of the description as the sales pitch for your package. Users will see it
108 when they [browse for packages](/packages). It should be simple plain text:
109 no markdown or HTML. That's what your README is for.
110
111 ## Author/Authors
112
113 You're encouraged to use these fields to describe the author(s) of your package
114 and provide contact information. `author` should be used if your package has a
115 single author, while `authors` should be used with a YAML list if more than one
116 person wrote the package. Each author can either be a single name (e.g. `Nathan
117 Weizenbaum`) or a name and an email address (e.g. `Nathan Weizenbaum
118 <nweiz@google.com>`). For example:
119
120 {% highlight yaml %}
121 authors:
122 - Nathan Weizenbaum <nweiz@google.com>
123 - Bob Nystrom <rnystrom@google.com>
124 {% endhighlight %}
125
126 If anyone uploads your package here, we will show this email address so make
127 sure you're OK with that.
128
129 ## Homepage
130
131 This should be a URL pointing to the website for your package. For
132 [hosted packages](#hosted-packages), this URL will be linked from the
133 package's page. While this is technically optional *please do* provide one. It
134 helps users understand where your package is coming from. If nothing else, you
135 can always use the URL where you host the source code:
136 [GitHub](http://github.com), [code.google.com](http://code.google.com/),
137 whatever.
138
139 ## Documentation
140
141 Some packages may have a site that hosts documentation separate from the main
142 homepage. If your package has that, you can also add a `documentation:` field
143 with that URL. If provided, a link to it will be shown on your package's page.
144
145 ## Dependencies
146
147 <div class="learn-more">
148 <a href="/doc/dependencies.html">
149 Learn more about dependencies &rarr;
150 </a>
151 </div>
152
153 Finally, the pubspec's *raison d'ĂȘtre*: [dependencies](glossary.html#dependency) . Here,
154 you list each package that your package needs in order to work.
155
156 There are two separate sections. Dependencies under `dependencies:` are
157 "regular" dependencies. They are packages that anyone using your package will
158 also need. Dependencies under `dev_dependencies` are
159 [dev dependencies](glossary.html#dev-dependency). These are packages that are
160 only needed in the development of your package itself.
161
162 ## SDK constraints
163
164 A package can indicate which versions of its dependencies it supports, but there
165 is also another implicit dependency all packages have: the Dart SDK itself.
166 Since the Dart platform evolves over time, a package may only work with certain
167 versions of it.
168
169 A package can specify that using an *SDK constraint*. This goes inside a
170 separate top-level "environment" field in the pubspec and uses the same
171 [version constraint](dependencies.html#version-constraints) syntax as
172 dependencies. For example, this constraint says that this package works with any
173 Dart SDK from 0.3.4 or later:
174
175 {% highlight yaml %}
176 environment:
177 sdk: ">=0.3.4"
178 {% endhighlight %}
179
180 Pub will try to find the latest version of a package whose SDK constraint works
181 with the version of the Dart SDK that you have installed.
182
183 [pubsite]: http://pub.dartlang.org
184 [semantic versioning]: http://semver.org/
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698