| OLD | NEW |
|---|
| (Empty) |
| 1 <p>The <a href="pub-serve.html"><code>pub serve</code></a> and <a href="pub-buil
d.html"><code>pub build</code></a> | |
| 2 commands use <a href="glossary.html#transformer">transformers</a> to prepare a p
ackage’s <a href="glossary.html#asset">assets</a> to be served | |
| 3 locally or to be deployed, respectively.</p> | |
| 4 | |
| 5 <p>Use the <code>pubspec.yaml</code> file to specify which transformers your pac
kage uses | |
| 6 and, if necessary, to configure the transformers. (See | |
| 7 <a href="#specifying-transformers">Specifying transformers</a> for details.) For
example:</p> | |
| 8 | |
| 9 <pre> | |
| 10 name: myapp | |
| 11 dependencies: | |
| 12 <b>polymer: any</b> | |
| 13 <b>transformers: | |
| 14 - polymer: | |
| 15 entry_points: | |
| 16 - web/index.html | |
| 17 - web/index2.html</b> | |
| 18 </pre> | |
| 19 | |
| 20 <p>A package’s assets must be in one or more of the following directories: | |
| 21 <code>lib</code>, <code>asset</code>, and <code>web</code>. After transformation
by <code>pub build</code>, assets are | |
| 22 available under a directory called <code>build</code>. Assets generated from | |
| 23 files in a package’s <code>lib</code> directory appear under a directory n
amed | |
| 24 <code>packages/<em><pkg_name></em></code>, and those from the package&rsqu
o;s | |
| 25 <code>asset</code> directory appear under <code>assets/<em><pkg_name></em>
</code>. | |
| 26 For details, see | |
| 27 <a href="#where-to-put-assets">Where to put assets</a> and | |
| 28 <a href="#how-to-refer-to-assets">How to refer to assets</a>.</p> | |
| 29 | |
| 30 <h2 id="how-transformers-work">How transformers work</h2> | |
| 31 | |
| 32 <p>Here are some examples of transformers:</p> | |
| 33 | |
| 34 <ul> | |
| 35 <li>The dart2js transformer, which reads in all of the <code>.dart</code> file
s for a | |
| 36 program and compiles them to a single <code>.js</code> file.</li> | |
| 37 <li>The polymer transformer, which converts HTML and Dart files into | |
| 38 optimized HTML and Dart files.</li> | |
| 39 <li>A linter that reads in files and produces warnings but no actual file.</li
> | |
| 40 </ul> | |
| 41 | |
| 42 <p>Although you specify which transformers to use, you don’t explicitly sa
y | |
| 43 which transformers should be applied to which assets. Instead, each | |
| 44 transformer determines which assets it can apply itself to. For <code>pub serve<
/code>, | |
| 45 the transformers run when the dev server starts up and whenever a source | |
| 46 asset changes. The <code>pub build</code> command runs the transformers once and | |
| 47 then exits.</p> | |
| 48 | |
| 49 <p>As the following figure shows, source assets can pass through, untransformed, | |
| 50 and become generated assets. Or a source asset can be transformed, such as a | |
| 51 <code>.dart</code> file (along with the <code>.dart</code> files that it refers
to) that is | |
| 52 compiled to <code>.js</code>.</p> | |
| 53 | |
| 54 <p><img src="/img/assets-and-transformers.png" alt="a figure showing source asse
ts and generated assets; the .html, .css, and .png files pass through, untransfo
rmed; the .dart file is transformed into a .js file (and, for pub serve only, th
e .dart file is passed through, as well)" /></p> | |
| 55 | |
| 56 <p>Dart files are a special case. The <code>pub build</code> command doesn&rsquo
;t produce <code>.dart</code> | |
| 57 files because browsers in the wild don’t support Dart natively (yet). The
<code>pub | |
| 58 serve</code> command, on the other hand, does generate <code>.dart</code> assets
, because | |
| 59 you can use Dartium while you’re developing your app.</p> | |
| 60 | |
| 61 <h2 id="specifying-transformers">Specifying transformers</h2> | |
| 62 | |
| 63 <p>To tell pub to apply a transformer to your package’s assets, specify th
e | |
| 64 transformer, as well as the package that contains the transformer, in your | |
| 65 package’s <code>pubspec.yaml</code> file. In the following pubspec, the bo
ld lines | |
| 66 specify that this package requires the polymer transformer, which is in the | |
| 67 polymer package (along with the rest of Polymer.dart):</p> | |
| 68 | |
| 69 <pre> | |
| 70 name: myapp | |
| 71 dependencies: | |
| 72 <b>polymer: any</b> | |
| 73 <b>transformers: | |
| 74 - polymer: | |
| 75 entry_points: web/index.html</b> | |
| 76 </pre> | |
| 77 | |
| 78 <p>We expect more transformers to be available in the future. You can specify | |
| 79 multiple transformers, to run either in parallel (if they’re independent o
f | |
| 80 each other) or in separate phases. To specify that transformers run in | |
| 81 parallel, use [<code><em>transformer_1</em>, ..., | |
| 82 <em>transformer_n</em></code>]. If order matters, put the transformers on | |
| 83 separate lines.</p> | |
| 84 | |
| 85 <p>For example, consider three transformers, specified as follows:</p> | |
| 86 | |
| 87 <div class="highlight"><pre><code class="yaml"><span class="l-Scalar-Plain">tran
sformers</span><span class="p-Indicator">:</span> | |
| 88 <span class="p-Indicator">-</span> <span class="p-Indicator">[</span><span class
="nv">t1</span><span class="p-Indicator">,</span> <span class="nv">t2</span><spa
n class="p-Indicator">]</span> | |
| 89 <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">t3</span> | |
| 90 </code></pre></div> | |
| 91 | |
| 92 <p>The <code>t1</code> and <code>t2</code> transformers run first, in parallel.
The <code>t3</code> transformer | |
| 93 runs in a separate phase, after <code>t1</code> and <code>t2</code> are finished
, and can see the | |
| 94 outputs of <code>t1</code> and <code>t2</code>.</p> | |
| 95 | |
| 96 <p>Pub implicitly appends a transformer that converts your Dart code to | |
| 97 JavaScript, so your code can run in any modern browser.</p> | |
| 98 | |
| 99 <h2 id="where-to-put-assets">Where to put assets</h2> | |
| 100 | |
| 101 <p>If you want a file to be an <em>asset</em>—to either be in or be used t
o | |
| 102 generate files in the built version of your package—then you need to | |
| 103 put it under one of the following directories:</p> | |
| 104 | |
| 105 <ul> | |
| 106 <li><code>lib</code>: Dart libraries defining the package’s public API.
Visible in all | |
| 107 packages that use this package.</li> | |
| 108 <li><code>asset</code>: Other public files. Visible in all packages that use t
his | |
| 109 package.</li> | |
| 110 <li><code>web</code>: A web app’s static content plus its main Dart file
(the one that | |
| 111 defines <code>main()</code>). Visible <em>only</em> to this package.</li> | |
| 112 </ul> | |
| 113 | |
| 114 <p>The following picture shows how you might structure your app’s source a
ssets, | |
| 115 with your main Dart file under <code>web</code> and additional Dart files under
<code>lib</code>.</p> | |
| 116 | |
| 117 <pre> | |
| 118 <em>app</em>/ | |
| 119 lib/ | |
| 120 *.dart | |
| 121 packages/ | |
| 122 pck/ | |
| 123 lib/ | |
| 124 *.dart | |
| 125 *.js | |
| 126 asset/ | |
| 127 *.png | |
| 128 *.html | |
| 129 ... | |
| 130 web/ | |
| 131 <em>app</em>.dart | |
| 132 *.html | |
| 133 *.css | |
| 134 *.png | |
| 135 ... | |
| 136 </pre> | |
| 137 | |
| 138 <p>After transformation, <code>pub build</code> places generated assets under a
directory | |
| 139 named <code>build</code>, which we’ll call the <em>build root</em>. The bu
ild root has two | |
| 140 special subdirectories: <code>packages</code> and <code>assets</code>. The dev s
erver simulates this | |
| 141 hierarchy without generating files.</p> | |
| 142 | |
| 143 <p>The following figure shows the source assets above, plus the generated assets | |
| 144 produced by <code>pub build</code> if the only transformer is dart2js. In this e
xample, | |
| 145 all the source files have corresponding generated files, and all the Dart | |
| 146 files have been compiled into a single JavaScript file.</p> | |
| 147 | |
| 148 <p><img src="/img/input-and-output-assets.png" alt="under the build directory ar
e assets/ and packages/ directories, plus a bunch of files derived from the web/
directory: app.dart.js, *.html, *.css, *.png, ..." /></p> | |
| 149 | |
| 150 <h2 id="how-to-refer-to-assets">How to refer to assets</h2> | |
| 151 | |
| 152 <p>Here’s how source asset locations correlate to generated asset location
s, | |
| 153 for untransformed files:</p> | |
| 154 | |
| 155 <table> | |
| 156 <tr> | |
| 157 <th> Source asset location </th> | |
| 158 <th> Generated asset location<br />(under the build root) </th> | |
| 159 </tr> | |
| 160 <tr> | |
| 161 <td> <code>.../<em><your_pkg></em>/web/<em><path></em></code> </
td> | |
| 162 <td> <code>/<em><path></em></code> </td> | |
| 163 </tr> | |
| 164 <tr> | |
| 165 <td> <code>.../<em><pkg_name></em>/asset/<em><path></em></code>
</td> | |
| 166 <td> <code>/assets/<em><pkg_name></em>/<em><path></em></code> </
td> | |
| 167 </tr> | |
| 168 <tr> | |
| 169 <td> <code>.../<em><pkg_name></em>/lib/<em><path></em></code> </
td> | |
| 170 <td> <code>/packages/<em><pkg_name></em>/<em><path></em></code>
</td> | |
| 171 </tr> | |
| 172 </table> | |
| 173 | |
| 174 <p>For example, consider a helloworld app’s HTML file, which is in the | |
| 175 helloworld directory at <code>web/helloworld.html</code>. Running <code>pub buil
d</code> produces a | |
| 176 copy at <code>build/helloworld.html</code>. In the dev server, you can get the H
TML file | |
| 177 contents by using the URL <code>http://localhost:8080/helloworld.html</code>.</p
> | |
| 178 | |
| 179 <p>Transformers might change any part of <em><path></em>, especially the | |
| 180 filename, but they can’t change the directory structure above | |
| 181 <em><path></em>.</p> | |
| 182 | |
| 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