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

Side by Side Diff: app/views/doc/assets-and-transformers.html

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 <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&rsquo;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&rsquo;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&rsquo;s <code>lib</code> directory appear under a directory n amed
24 <code>packages/<em>&lt;pkg_name&gt;</em></code>, and those from the package&rsqu o;s
25 <code>asset</code> directory appear under <code>assets/<em>&lt;pkg_name&gt;</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&rsquo;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&rsquo;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&rsquo;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&rsquo;s assets, specify th e
64 transformer, as well as the package that contains the transformer, in your
65 package&rsquo;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&rsquo;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>&mdash;to either be in or be used t o
102 generate files in the built version of your package&mdash;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&rsquo;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&rsquo;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&rsquo;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&rsquo;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&rsquo;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>&lt;your_pkg&gt;</em>/web/<em>&lt;path&gt;</em></code> </ td>
162 <td> <code>/<em>&lt;path&gt;</em></code> </td>
163 </tr>
164 <tr>
165 <td> <code>.../<em>&lt;pkg_name&gt;</em>/asset/<em>&lt;path&gt;</em></code> </td>
166 <td> <code>/assets/<em>&lt;pkg_name&gt;</em>/<em>&lt;path&gt;</em></code> </ td>
167 </tr>
168 <tr>
169 <td> <code>.../<em>&lt;pkg_name&gt;</em>/lib/<em>&lt;path&gt;</em></code> </ td>
170 <td> <code>/packages/<em>&lt;pkg_name&gt;</em>/<em>&lt;path&gt;</em></code> </td>
171 </tr>
172 </table>
173
174 <p>For example, consider a helloworld app&rsquo;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>&lt;path&gt;</em>, especially the
180 filename, but they can&rsquo;t change the directory structure above
181 <em>&lt;path&gt;</em>.</p>
182
OLDNEW
« no previous file with comments | « app/pub_dartlang.py ('k') | app/views/doc/dependencies.html » ('j') | app/views/index.mustache » ('J')

Powered by Google App Engine
This is Rietveld 408576698