| OLD | NEW |
|---|
| (Empty) |
| 1 <ol class="toc"> | |
| 2 <li><a href="#the-basics">The basics</a></li> | |
| 3 <li><a href="#readme">README</a></li> | |
| 4 <li><a href="#public-libraries">Public libraries</a></li> | |
| 5 <li><a href="#public-assets">Public assets</a></li> | |
| 6 <li><a href="#implementation-files">Implementation files</a></li> | |
| 7 <li><a href="#web-files">Web files</a></li> | |
| 8 <li><a href="#command-line-apps">Command-line apps</a></li> | |
| 9 <li><a href="#tests-and-benchmarks">Tests and benchmarks</a></li> | |
| 10 <li><a href="#documentation">Documentation</a></li> | |
| 11 <li><a href="#examples">Examples</a></li> | |
| 12 <li><a href="#internal-tools-and-scripts">Internal tools and scripts</a></li> | |
| 13 </ol> | |
| 14 | |
| 15 <p>Part of a healthy code ecosystem is consistent conventions. When we all do th
e | |
| 16 same thing the same way, it makes it easier for us to learn our way around | |
| 17 each other’s work. It also makes it easier to write tools that can automat
ically | |
| 18 do stuff for us.</p> | |
| 19 | |
| 20 <p>When you build a Pub package, we have a set of conventions we encourage you t
o | |
| 21 follow. They describe how you organize the files and directories within your | |
| 22 package, and how to name things. You don’t have to have every single thing | |
| 23 these guidelines specify. If your package doesn’t have binaries, it doesn&
rsquo;t | |
| 24 need a directory for them. But if it does, you’ll make everyone’s li
fe easier | |
| 25 if you call it <code>bin</code>.</p> | |
| 26 | |
| 27 <p>To give you a picture of the whole enchilada, here’s what a complete pa
ckage | |
| 28 (conveniently named <code>enchilada</code>) that uses every corner of these guid
elines | |
| 29 would look like:</p> | |
| 30 | |
| 31 <pre><code>enchilada/ | |
| 32 pubspec.yaml | |
| 33 pubspec.lock * | |
| 34 README.md | |
| 35 LICENSE | |
| 36 asset/ | |
| 37 guacamole.css | |
| 38 benchmark/ | |
| 39 make_lunch.dart | |
| 40 packages/ ** | |
| 41 bin/ | |
| 42 enchilada | |
| 43 packages/ ** | |
| 44 doc/ | |
| 45 getting_started.md | |
| 46 example/ | |
| 47 lunch.dart | |
| 48 packages/ ** | |
| 49 lib/ | |
| 50 enchilada.dart | |
| 51 tortilla.dart | |
| 52 src/ | |
| 53 beans.dart | |
| 54 queso.dart | |
| 55 packages/ ** | |
| 56 test/ | |
| 57 enchilada_test.dart | |
| 58 tortilla_test.dart | |
| 59 packages/ ** | |
| 60 tool/ | |
| 61 generate_docs.dart | |
| 62 web/ | |
| 63 index.html | |
| 64 main.dart | |
| 65 style.css | |
| 66 </code></pre> | |
| 67 | |
| 68 <p>* The <code>pubspec.lock</code> will only be in source control if the package
is an | |
| 69 <a href="glossary.html#application-package">application package</a>.</p> | |
| 70 | |
| 71 <p>** The <code>packages</code> directories will exist locally after you’r
e run | |
| 72 <code>pub get</code>, but won’t be checked into source control.</p> | |
| 73 | |
| 74 <h2 id="the-basics">The basics</h2> | |
| 75 | |
| 76 <pre><code>enchilada/ | |
| 77 pubspec.yaml | |
| 78 pubspec.lock | |
| 79 </code></pre> | |
| 80 | |
| 81 <div class="learn-more"> | |
| 82 <a href="/doc/pubspec.html"> | |
| 83 Learn more about pubspecs → | |
| 84 </a> | |
| 85 </div> | |
| 86 | |
| 87 <p>Every package will have a <a href="pubspec.html"><strong>pubspec</strong></a>
, a file named | |
| 88 <code>pubspec.yaml</code>, in the root directory of the package. That’s wh
at <em>makes</em> it a | |
| 89 package.</p> | |
| 90 | |
| 91 <p>Once you’ve run <a href="pub-get.html"><code>pub get</code></a> or <a h
ref="pub-upgrade.html"><code>pub | |
| 92 upgrade</code></a> on the package, you will also have a <strong>lockfile</strong
>, | |
| 93 named <code>pubspec.lock</code>. If your package is an <a href="glossary.html#ap
plication-package">application | |
| 94 package</a>, this will be checked into source | |
| 95 control. Otherwise, it won’t be.</p> | |
| 96 | |
| 97 <pre><code>enchilada/ | |
| 98 packages/ | |
| 99 ... | |
| 100 </code></pre> | |
| 101 | |
| 102 <p>Running pub will also generate a <code>packages</code> directory. You will <e
m>not</em> check | |
| 103 this into source control, and you won’t need to worry too much about its | |
| 104 contents. Consider it pub magic, but not scary magic.</p> | |
| 105 | |
| 106 <p>The open source community has a few other files that commonly appear at the t
op | |
| 107 level of a project: <code>LICENSE</code>, <code>AUTHORS</code>, etc. If you use
any of those, they can | |
| 108 go in the top level of the package too.</p> | |
| 109 | |
| 110 <h2 id="readme">README</h2> | |
| 111 | |
| 112 <pre><code>enchilada/ | |
| 113 README.md | |
| 114 </code></pre> | |
| 115 | |
| 116 <p>One file that’s very common in open source is a README file that | |
| 117 describes the project. This is especially important in pub. When you upload | |
| 118 to <a href="/">pub.dartlang.org</a>, your README will be shown on the page for y
our | |
| 119 package. This is the perfect place to introduce people to your code.</p> | |
| 120 | |
| 121 <p>If your README ends in <code>.md</code>, <code>.markdown</code>, or <code>.md
own</code>, it will be parsed as | |
| 122 <a href="http://daringfireball.net/projects/markdown/">Markdown</a> so you can m
ake it as fancy as you like.</p> | |
| 123 | |
| 124 <h2 id="public-libraries">Public libraries</h2> | |
| 125 | |
| 126 <pre><code>enchilada/ | |
| 127 lib/ | |
| 128 enchilada.dart | |
| 129 tortilla.dart | |
| 130 </code></pre> | |
| 131 | |
| 132 <p>Many packages are <a href="glossary.html#library-package"><em>library package
s</em></a>: they | |
| 133 define Dart libraries that other packages can import and use. These public Dart | |
| 134 library files go inside a directory called <code>lib</code>.</p> | |
| 135 | |
| 136 <p>Most packages define a single library that users can import. In that case, | |
| 137 its name should usually be the same as the name of the package, like | |
| 138 <code>enchilada.dart</code> in the example here. But you can also define other l
ibraries | |
| 139 with whatever names make sense for your package.</p> | |
| 140 | |
| 141 <p>When you do, users can import these libraries using the name of the package a
nd | |
| 142 the library file, like so:</p> | |
| 143 | |
| 144 <div class="highlight"><pre><code class="dart"><span class="k">import</span> <sp
an class="s2">"package:enchilada/enchilada.dart"</span><span class="p"
>;</span> | |
| 145 <span class="k">import</span> <span class="s2">"package:enchilada/tortilla.
dart"</span><span class="p">;</span> | |
| 146 </code></pre></div> | |
| 147 | |
| 148 <p>If you feel the need to organize your public libraries, you can also create | |
| 149 subdirectories inside <code>lib</code>. If you do that, users will specify that
path when | |
| 150 they import it. Say you have a file hierarchy like this:</p> | |
| 151 | |
| 152 <pre><code>enchilada/ | |
| 153 lib/ | |
| 154 some/ | |
| 155 path/ | |
| 156 olives.dart | |
| 157 </code></pre> | |
| 158 | |
| 159 <p>Users will import <code>olives.dart</code> like:</p> | |
| 160 | |
| 161 <div class="highlight"><pre><code class="dart"><span class="k">import</span> <sp
an class="s2">"package:enchilada/some/path/olives.dart"</span><span cl
ass="p">;</span> | |
| 162 </code></pre></div> | |
| 163 | |
| 164 <p>Note that only <em>libraries</em> should be in <code>lib</code>. <em>Entrypoi
nts</em>—Dart scripts | |
| 165 with a <code>main()</code> function—cannot go in <code>lib</code>. If you
place a Dart script | |
| 166 inside <code>lib</code>, you will discover that any <code>package:</code> import
s it contains don’t | |
| 167 resolve. Instead, your entrypoints should go in the appropriate | |
| 168 <a href="glossary.html#entrypoint-directory">entrypoint directory</a>.</p> | |
| 169 | |
| 170 <h2 id="public-assets">Public assets</h2> | |
| 171 | |
| 172 <pre><code>enchilada/ | |
| 173 asset/ | |
| 174 guacamole.css | |
| 175 </code></pre> | |
| 176 | |
| 177 <p>While most library packages exist to let you reuse Dart code, you can also | |
| 178 reuse other kinds of content. For example, a package for something like | |
| 179 <a href="http://getbootstrap.com/">Bootstrap</a> might include a number of CSS f
iles for | |
| 180 consumers of the package to use.</p> | |
| 181 | |
| 182 <p>These go in a top-level directory named <code>asset</code>. You can put any k
ind of file | |
| 183 in there and organize it with subdirectories however you like. It’s effect
ively | |
| 184 a <code>lib</code> directory for stuff that isn’t Dart code.</p> | |
| 185 | |
| 186 <p>Users can reference another package’s assets using URLs that contain | |
| 187 <code>assets/<package>/<path></code> where <code><package></co
de> is the name of the package | |
| 188 containing the asset and <code><path></code> is the relative path to the a
sset within that | |
| 189 package’s <code>asset</code> directory.</p> | |
| 190 | |
| 191 <aside class="alert alert-warning"> | |
| 192 | |
| 193 <p>The mechanics of referencing assets are still being implemented. URLs that | |
| 194 contain <tt>assets/</tt> are handled by <a href="pub-serve.html"><tt>pub | |
| 195 serve</tt></a>.</p> | |
| 196 | |
| 197 <p>The <a href="pub-build.html"><tt>pub build</tt></a> command also copies | |
| 198 assets to an <tt>assets</tt> directory, but this will <em>only</em> be in the | |
| 199 root directory of the output, so you must make sure that your <tt>assets/</tt> | |
| 200 URL correctly resolves to that directory and not a subdirectory.</p> | |
| 201 | |
| 202 <p>We don't currently have a solution for referencing assets in command-line | |
| 203 Dart applications.</p> | |
| 204 | |
| 205 </aside> | |
| 206 | |
| 207 <p>Note that <code>assets</code> is plural in the URL. This is a bit like the sp
lit between | |
| 208 <code>lib</code> and <code>packages</code>. The former is the name of the <em>di
rectory in the package</em>, | |
| 209 the latter is the <em>name you use to reference it</em>.</p> | |
| 210 | |
| 211 <p>For example, let’s say your package wanted to use enchilada’s <co
de>guacamole.css</code> | |
| 212 styles. In an HTML file in your package, you can add:</p> | |
| 213 | |
| 214 <div class="highlight"><pre><code class="html"><span class="nt"><link</span>
<span class="na">href=</span><span class="s">"assets/enchilada/guacamole.cs
s"</span> <span class="na">rel=</span><span class="s">"stylesheet"
;</span><span class="nt">></span> | |
| 215 </code></pre></div> | |
| 216 | |
| 217 <p>When you run your application using <a href="pub-serve.html"><code>pub serve<
/code></a>, or build it | |
| 218 to something deployable using <a href="pub-build.html"><code>pub build</code></a
>, Pub will copy over | |
| 219 any referenced assets that your package depends on.</p> | |
| 220 | |
| 221 <h2 id="implementation-files">Implementation files</h2> | |
| 222 | |
| 223 <pre><code>enchilada/ | |
| 224 lib/ | |
| 225 src/ | |
| 226 beans.dart | |
| 227 queso.dart | |
| 228 </code></pre> | |
| 229 | |
| 230 <p>The libraries inside “lib” are publicly visible: other packages a
re free to | |
| 231 import them. But much of a package’s code is internal implementation libra
ries | |
| 232 that should only be imported and used by the package itself. Those go inside a | |
| 233 subdirectory of <code>lib</code> called <code>src</code>. You can create subdire
ctories in there if | |
| 234 it helps you organize things.</p> | |
| 235 | |
| 236 <p>You are free to import libraries that live in <code>lib/src</code> from withi
n other Dart | |
| 237 code in the <em>same</em> package (like other libraries in <code>lib</code>, scr
ipts in <code>bin</code>, and | |
| 238 tests) but you should never import from another package’s <code>lib/src</c
ode> directory. | |
| 239 Those files are not part of the package’s public API, and they might chang
e in | |
| 240 ways that could break your code.</p> | |
| 241 | |
| 242 <p>When you use libraries from within your own package, even stuff in <code>src<
/code>, you | |
| 243 can (and should) still use <code>"package:"</code> to import them. This is perfe
ctly | |
| 244 legit:</p> | |
| 245 | |
| 246 <div class="highlight"><pre><code class="dart"><span class="k">import</span> <sp
an class="s2">"package:enchilada/src/beans.dart"</span><span class="p"
>;</span> | |
| 247 </code></pre></div> | |
| 248 | |
| 249 <p>The name you use here (in this case <code>enchilada</code>) is the name you s
pecify for | |
| 250 your package in its <a href="pubspec.html">pubspec</a>.</p> | |
| 251 | |
| 252 <h2 id="web-files">Web files</h2> | |
| 253 | |
| 254 <pre><code>enchilada/ | |
| 255 web/ | |
| 256 index.html | |
| 257 main.dart | |
| 258 style.css | |
| 259 </code></pre> | |
| 260 | |
| 261 <p>Dart is a web language, so many pub packages will be doing web stuff. That | |
| 262 means HTML, CSS, images, and, heck, probably even some JavaScript. All of that | |
| 263 goes into your package’s <code>web</code> directory. You’re free to
organize the contents | |
| 264 of that to your heart’s content. Go crazy with subdirectories if that make
s you | |
| 265 happy.</p> | |
| 266 | |
| 267 <p>Also, and this is important, any Dart web entrypoints (in other words, Dart | |
| 268 scripts that are referred to in a <code><script></code> tag) go under <cod
e>web</code> and not <code>lib</code>. | |
| 269 That ensures that there is a nearby <code>packages</code> directory so that <cod
e>package:</code> | |
| 270 imports can be resolved correctly.</p> | |
| 271 | |
| 272 <p>(You may be asking yourself, “Self, where should I put my web-based exa
mple | |
| 273 programs? <code>example</code> or <code>web</code>?” Put those in <code>ex
ample</code>.)</p> | |
| 274 | |
| 275 <h2 id="command-line-apps">Command-line apps</h2> | |
| 276 | |
| 277 <pre><code>enchilada/ | |
| 278 bin/ | |
| 279 enchilada | |
| 280 </code></pre> | |
| 281 | |
| 282 <p>Some packages define programs that can be run directly from the command line. | |
| 283 These can be shell scripts or any other scripting language, including Dart. | |
| 284 The <code>pub</code> application itself is one example: it’s a simple shel
l script that | |
| 285 invokes <code>pub.dart</code>.</p> | |
| 286 | |
| 287 <p>If your package defines stuff like this, put it in a directory named <code>bi
n</code>.</p> | |
| 288 | |
| 289 <aside class="alert alert-note"> | |
| 290 | |
| 291 At some point, pub will support automatically adding that directory to your | |
| 292 system path so that these scripts can be easily invoked. | |
| 293 | |
| 294 </aside> | |
| 295 | |
| 296 <h2 id="tests-and-benchmarks">Tests and benchmarks</h2> | |
| 297 | |
| 298 <pre><code>enchilada/ | |
| 299 test/ | |
| 300 enchilada_test.dart | |
| 301 tortilla_test.dart | |
| 302 </code></pre> | |
| 303 | |
| 304 <p>Every self-respecting package should have tests. With pub, the convention is | |
| 305 that these go in a <code>test</code> directory (or some directory inside it if y
ou like) | |
| 306 and have <code>_test</code> at the end of their file names.</p> | |
| 307 | |
| 308 <p>Typically, these use the <a href="http://api.dartlang.org/unittest.html">unit
test</a> | |
| 309 package but you can use whatever testing system that gets you excited.</p> | |
| 310 | |
| 311 <pre><code>enchilada/ | |
| 312 benchmark/ | |
| 313 make_lunch.dart | |
| 314 </code></pre> | |
| 315 | |
| 316 <p>Packages that have performance critical code may also include <em>benchmarks<
/em>. | |
| 317 These test the API not for correctness but for speed (or memory use, or maybe | |
| 318 other empirical metrics).</p> | |
| 319 | |
| 320 <h2 id="documentation">Documentation</h2> | |
| 321 | |
| 322 <pre><code>enchilada/ | |
| 323 doc/ | |
| 324 getting_started.md | |
| 325 </code></pre> | |
| 326 | |
| 327 <p>If you’ve got code and tests, the next piece you need to maximize your
karma | |
| 328 is good documentation. That goes inside a directory named <code>doc</code>. We d
on’t | |
| 329 currently have any guidelines about format or organization within that. Use | |
| 330 whatever markup format you like and be happy that you’re actually writing
docs.</p> | |
| 331 | |
| 332 <p>This directory should <em>not</em> just contain docs generated automatically
from your | |
| 333 source code using | |
| 334 <a href="http://api.dartlang.org/docs/continuous/dartdoc.html">dartdoc</a>. Sinc
e that’s | |
| 335 pulled directly from the code already in the package, putting those docs in | |
| 336 here would be redundant. Instead, this is for tutorials, guides, and other | |
| 337 hand-authored documentation <em>in addition to</em> generated API references.</p
> | |
| 338 | |
| 339 <h2 id="examples">Examples</h2> | |
| 340 | |
| 341 <pre><code>enchilada/ | |
| 342 example/ | |
| 343 lunch.dart | |
| 344 </code></pre> | |
| 345 | |
| 346 <p>At this point, you’re going for the brass ring. Code, tests, docs, what
else | |
| 347 could your users want? Standalone example programs that use your package, of | |
| 348 course! Those go inside the <code>example</code> directory. If the examples are
complex | |
| 349 and use multiple files, consider making a directory for each example. Otherwise, | |
| 350 you can place each one right inside <code>example</code>.</p> | |
| 351 | |
| 352 <p>This is an important place to consider using <code>package:</code> to import
files from | |
| 353 your own package. That ensures the example code in your package looks exactly | |
| 354 like code outside of your package would look.</p> | |
| 355 | |
| 356 <h2 id="internal-tools-and-scripts">Internal tools and scripts</h2> | |
| 357 | |
| 358 <pre><code>enchilada/ | |
| 359 tool/ | |
| 360 generate_docs.dart | |
| 361 </code></pre> | |
| 362 | |
| 363 <p>Mature packages often have little helper scripts and programs that people | |
| 364 run while developing the package itself. Think things like test runners, | |
| 365 documentation generators, or other bits of automation.</p> | |
| 366 | |
| 367 <p>Unlike the scripts in <code>bin</code>, these are <em>not</em> for external u
sers of the package. | |
| 368 If you have any of these, place them in a directory called <code>tool</code>.</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