OLD | NEW |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 /** | 5 /// Common logic to make it easy to run the polymer linter and deploy tool. |
6 * Common logic to make it easy to run the polymer linter and deploy tool. | 6 /// |
7 * | 7 /// The functions in this library are designed to make it easier to create |
8 * The functions in this library are designed to make it easier to create | 8 /// `build.dart` files. A `build.dart` file is a Dart script that can be invoked |
9 * `build.dart` files. A `build.dart` file is a Dart script that can be invoked | 9 /// from the command line, but that can also invoked automatically by the Dart |
10 * from the command line, but that can also invoked automatically by the Dart | 10 /// Editor whenever a file in your project changes or when selecting some menu |
11 * Editor whenever a file in your project changes or when selecting some menu | 11 /// options, such as 'Reanalyze Sources'. |
12 * options, such as 'Reanalyze Sources'. | 12 /// |
13 * | 13 /// To work correctly, place the `build.dart` in the root of your project (where |
14 * To work correctly, place the `build.dart` in the root of your project (where | 14 /// pubspec.yaml lives). The file must be named exactly `build.dart`. |
15 * pubspec.yaml lives). The file must be named exactly `build.dart`. | 15 /// |
16 * | 16 /// It's quite likely that in the near future `build.dart` will be replaced with |
17 * It's quite likely that in the near future `build.dart` will be replaced with | 17 /// something else. For example, `pub deploy` will deal with deploying |
18 * something else. For example, `pub deploy` will deal with deploying | 18 /// applications automatically, and the Dart Editor might provide other |
19 * applications automatically, and the Dart Editor might provide other | 19 /// mechanisms to hook linters. |
20 * mechanisms to hook linters. | 20 /// |
21 * | 21 /// There are three important functions exposed by this library [build], [lint], |
22 * There are three important functions exposed by this library [build], [lint], | 22 /// and [deploy]. The following examples show common uses of these functions |
23 * and [deploy]. The following examples show common uses of these functions when | 23 /// when writing a `build.dart` file. |
24 * writing a `build.dart` file. | 24 /// |
25 * | 25 /// **Example 1**: Uses build.dart to run the linter tool. |
26 * **Example 1**: Uses build.dart to run the linter tool. | 26 /// |
27 * | 27 /// import 'dart:io'; |
28 * import 'dart:io'; | 28 /// import 'package:polymer/builder.dart'; |
29 * import 'package:polymer/builder.dart'; | 29 /// |
30 * | 30 /// main() { |
31 * main() { | 31 /// lint(); |
32 * lint(); | 32 /// } |
33 * } | 33 /// |
34 * | 34 /// **Example 2**: Runs the linter and creates a deployable version of the app |
35 * **Example 2**: Runs the linter and creates a deployable version of the app | 35 /// every time. |
36 * every time. | 36 /// |
37 * | 37 /// import 'dart:io'; |
38 * import 'dart:io'; | 38 /// import 'package:polymer/builder.dart'; |
39 * import 'package:polymer/builder.dart'; | 39 /// |
40 * | 40 /// main() { |
41 * main() { | 41 /// deploy(); // deploy also calls the linter internally. |
42 * deploy(); // deploy also calls the linter internally. | 42 /// } |
43 * } | 43 /// |
44 * | 44 /// **Example 3**: Always run the linter, but conditionally build a deployable |
45 * **Example 3**: Always run the linter, but conditionally build a deployable | 45 /// version. See [parseOptions] for a description of options parsed |
46 * version. See [parseOptions] for a description of options parsed automatically | 46 /// automatically by this helper library. |
47 * by this helper library. | 47 /// |
48 * | 48 /// import 'dart:io'; |
49 * import 'dart:io'; | 49 /// import 'package:polymer/builder.dart'; |
50 * import 'package:polymer/builder.dart'; | 50 /// |
51 * | 51 /// main(args) { |
52 * main(args) { | 52 /// var options = parseOptions(args); |
53 * var options = parseOptions(args); | 53 /// if (options.forceDeploy) { |
54 * if (options.forceDeploy) { | 54 /// deploy(); |
55 * deploy(); | 55 /// } else { |
56 * } else { | 56 /// lint(); |
57 * lint(); | 57 /// } |
58 * } | 58 /// } |
59 * } | 59 /// |
60 * | 60 /// **Example 4**: Same as above, but uses [build] (which internally calls |
61 * **Example 4**: Same as above, but uses [build] (which internally calls either | 61 /// either [lint] or [deploy]). |
62 * [lint] or [deploy]). | 62 /// |
63 * | 63 /// import 'dart:io'; |
64 * import 'dart:io'; | 64 /// import 'package:polymer/builder.dart'; |
65 * import 'package:polymer/builder.dart'; | 65 /// |
66 * | 66 /// main(args) { |
67 * main(args) { | 67 /// build(options: parseOptions(args)); |
68 * build(options: parseOptions(args)); | 68 /// } |
69 * } | 69 /// |
70 * | 70 /// **Example 5**: Like the previous example, but indicates to the linter and |
71 * **Example 5**: Like the previous example, but indicates to the linter and | 71 /// deploy tool which files are actually used as entry point files. See the |
72 * deploy tool which files are actually used as entry point files. See the | 72 /// documentation of [build] below for more details. |
73 * documentation of [build] below for more details. | 73 /// |
74 * | 74 /// import 'dart:io'; |
75 * import 'dart:io'; | 75 /// import 'package:polymer/builder.dart'; |
76 * import 'package:polymer/builder.dart'; | 76 /// |
77 * | 77 /// main(args) { |
78 * main(args) { | 78 /// build(entryPoints: ['web/index.html'], options: parseOptions(args)); |
79 * build(entryPoints: ['web/index.html'], options: parseOptions(args)); | 79 /// } |
80 * } | |
81 */ | |
82 library polymer.builder; | 80 library polymer.builder; |
83 | 81 |
84 import 'dart:async'; | 82 import 'dart:async'; |
85 import 'dart:io'; | 83 import 'dart:io'; |
86 | 84 |
87 import 'package:args/args.dart'; | 85 import 'package:args/args.dart'; |
88 | 86 |
89 import 'src/build/linter.dart'; | 87 import 'src/build/linter.dart'; |
90 import 'src/build/runner.dart'; | 88 import 'src/build/runner.dart'; |
91 import 'src/build/common.dart'; | 89 import 'src/build/common.dart'; |
92 | 90 |
93 import 'transformer.dart'; | 91 import 'transformer.dart'; |
94 | 92 |
95 | 93 |
96 /** | 94 /// Runs the polymer linter on any relevant file in your package, such as any |
97 * Runs the polymer linter on any relevant file in your package, such as any | 95 /// .html file under 'lib/', 'asset/', and 'web/'. And, if requested, creates a |
98 * .html file under 'lib/', 'asset/', and 'web/'. And, if requested, creates a | 96 /// directory suitable for deploying a Polymer application to a server. |
99 * directory suitable for deploying a Polymer application to a server. | 97 /// |
100 * | 98 /// The [entryPoints] list contains files under web/ that should be treated as |
101 * The [entryPoints] list contains files under web/ that should be treated as | 99 /// entry points. Each entry on this list is a relative path from the package |
102 * entry points. Each entry on this list is a relative path from the package | 100 /// root (for example 'web/index.html'). If null, all files under 'web/' are |
103 * root (for example 'web/index.html'). If null, all files under 'web/' are | 101 /// treated as possible entry points. |
104 * treated as possible entry points. | 102 /// |
105 * | 103 /// Options must be passed by |
106 * Options must be passed by | 104 /// passing the [options] argument. The deploy operation is run only when the |
107 * passing the [options] argument. The deploy operation is run only when the | 105 /// command-line argument `--deploy` is present, or equivalently when |
108 * command-line argument `--deploy` is present, or equivalently when | 106 /// `options.forceDeploy` is true. |
109 * `options.forceDeploy` is true. | 107 /// |
110 * | 108 /// The linter and deploy steps needs to know the name of the [currentPackage] |
111 * The linter and deploy steps needs to know the name of the [currentPackage] | 109 /// and the location where to find the code for any package it depends on |
112 * and the location where to find the code for any package it depends on | 110 /// ([packageDirs]). This is inferred automatically, but can be overriden if |
113 * ([packageDirs]). This is inferred automatically, but can be overriden if | 111 /// those arguments are provided. |
114 * those arguments are provided. | |
115 */ | |
116 Future build({List<String> entryPoints, CommandLineOptions options, | 112 Future build({List<String> entryPoints, CommandLineOptions options, |
117 String currentPackage, Map<String, String> packageDirs}) { | 113 String currentPackage, Map<String, String> packageDirs}) { |
118 if (options == null) { | 114 if (options == null) { |
119 print('warning: now that main takes arguments, you need to explicitly pass' | 115 print('warning: now that main takes arguments, you need to explicitly pass' |
120 ' options to build(). Running as if no options were passed.'); | 116 ' options to build(). Running as if no options were passed.'); |
121 options = parseOptions([]); | 117 options = parseOptions([]); |
122 } | 118 } |
123 return options.forceDeploy | 119 return options.forceDeploy |
124 ? deploy(entryPoints: entryPoints, options: options, | 120 ? deploy(entryPoints: entryPoints, options: options, |
125 currentPackage: currentPackage, packageDirs: packageDirs) | 121 currentPackage: currentPackage, packageDirs: packageDirs) |
126 : lint(entryPoints: entryPoints, options: options, | 122 : lint(entryPoints: entryPoints, options: options, |
127 currentPackage: currentPackage, packageDirs: packageDirs); | 123 currentPackage: currentPackage, packageDirs: packageDirs); |
128 } | 124 } |
129 | 125 |
130 | 126 |
131 /** | 127 /// Runs the polymer linter on any relevant file in your package, |
132 * Runs the polymer linter on any relevant file in your package, | 128 /// such as any .html file under 'lib/', 'asset/', and 'web/'. |
133 * such as any .html file under 'lib/', 'asset/', and 'web/'. | 129 /// |
134 * | 130 /// The [entryPoints] list contains files under web/ that should be treated as |
135 * The [entryPoints] list contains files under web/ that should be treated as | 131 /// entry points. Each entry on this list is a relative path from the package |
136 * entry points. Each entry on this list is a relative path from the package | 132 /// root (for example 'web/index.html'). If null, all files under 'web/' are |
137 * root (for example 'web/index.html'). If null, all files under 'web/' are | 133 /// treated as possible entry points. |
138 * treated as possible entry points. | 134 /// |
139 * | 135 /// Options must be passed by passing the [options] argument. |
140 * Options must be passed by passing the [options] argument. | 136 /// |
141 * | 137 /// The linter needs to know the name of the [currentPackage] and the location |
142 * The linter needs to know the name of the [currentPackage] and the location | 138 /// where to find the code for any package it depends on ([packageDirs]). This |
143 * where to find the code for any package it depends on ([packageDirs]). This is | 139 /// is inferred automatically, but can be overriden by passing the arguments. |
144 * inferred automatically, but can be overriden if those arguments are provided. | |
145 */ | |
146 Future lint({List<String> entryPoints, CommandLineOptions options, | 140 Future lint({List<String> entryPoints, CommandLineOptions options, |
147 String currentPackage, Map<String, String> packageDirs}) { | 141 String currentPackage, Map<String, String> packageDirs}) { |
148 if (options == null) { | 142 if (options == null) { |
149 print('warning: now that main takes arguments, you need to explicitly pass' | 143 print('warning: now that main takes arguments, you need to explicitly pass' |
150 ' options to lint(). Running as if no options were passed.'); | 144 ' options to lint(). Running as if no options were passed.'); |
151 options = parseOptions([]); | 145 options = parseOptions([]); |
152 } | 146 } |
153 if (currentPackage == null) currentPackage = readCurrentPackageFromPubspec(); | 147 if (currentPackage == null) currentPackage = readCurrentPackageFromPubspec(); |
154 var linterOptions = new TransformOptions(entryPoints: entryPoints); | 148 var linterOptions = new TransformOptions(entryPoints: entryPoints); |
155 var linter = new Linter(linterOptions); | 149 var linter = new Linter(linterOptions); |
156 return runBarback(new BarbackOptions([[linter]], null, | 150 return runBarback(new BarbackOptions([[linter]], null, |
157 currentPackage: currentPackage, packageDirs: packageDirs, | 151 currentPackage: currentPackage, packageDirs: packageDirs, |
158 machineFormat: options.machineFormat)); | 152 machineFormat: options.machineFormat)); |
159 } | 153 } |
160 | 154 |
161 /** | 155 /// Creates a directory suitable for deploying a Polymer application to a |
162 * Creates a directory suitable for deploying a Polymer application to a server. | 156 /// server. |
163 * | 157 /// |
164 * **Note**: this function will be replaced in the future by the `pub deploy` | 158 /// **Note**: this function will be replaced in the future by the `pub deploy` |
165 * command. | 159 /// command. |
166 * | 160 /// |
167 * The [entryPoints] list contains files under web/ that should be treated as | 161 /// The [entryPoints] list contains files under web/ that should be treated as |
168 * entry points. Each entry on this list is a relative path from the package | 162 /// entry points. Each entry on this list is a relative path from the package |
169 * root (for example 'web/index.html'). If null, all files under 'web/' are | 163 /// root (for example 'web/index.html'). If null, all files under 'web/' are |
170 * treated as possible entry points. | 164 /// treated as possible entry points. |
171 * | 165 /// |
172 * Options must be passed by passing the [options] list. | 166 /// Options must be passed by passing the [options] list. |
173 * | 167 /// |
174 * The deploy step needs to know the name of the [currentPackage] and the | 168 /// The deploy step needs to know the name of the [currentPackage] and the |
175 * location where to find the code for any package it depends on | 169 /// location where to find the code for any package it depends on |
176 * ([packageDirs]). This is inferred automatically, but can be overriden if | 170 /// ([packageDirs]). This is inferred automatically, but can be overriden if |
177 * those arguments are provided. | 171 /// those arguments are provided. |
178 */ | |
179 Future deploy({List<String> entryPoints, CommandLineOptions options, | 172 Future deploy({List<String> entryPoints, CommandLineOptions options, |
180 String currentPackage, Map<String, String> packageDirs}) { | 173 String currentPackage, Map<String, String> packageDirs}) { |
181 if (options == null) { | 174 if (options == null) { |
182 print('warning: now that main takes arguments, you need to explicitly pass' | 175 print('warning: now that main takes arguments, you need to explicitly pass' |
183 ' options to deploy(). Running as if no options were passed.'); | 176 ' options to deploy(). Running as if no options were passed.'); |
184 options = parseOptions([]); | 177 options = parseOptions([]); |
185 } | 178 } |
186 if (currentPackage == null) currentPackage = readCurrentPackageFromPubspec(); | 179 if (currentPackage == null) currentPackage = readCurrentPackageFromPubspec(); |
187 | 180 |
188 var transformOptions = new TransformOptions( | 181 var transformOptions = new TransformOptions( |
189 entryPoints: entryPoints, | 182 entryPoints: entryPoints, |
190 directlyIncludeJS: options.directlyIncludeJS, | 183 directlyIncludeJS: options.directlyIncludeJS, |
191 contentSecurityPolicy: options.contentSecurityPolicy, | 184 contentSecurityPolicy: options.contentSecurityPolicy, |
192 releaseMode: options.releaseMode); | 185 releaseMode: options.releaseMode); |
193 | 186 |
194 var phases = new PolymerTransformerGroup(transformOptions).phases; | 187 var phases = new PolymerTransformerGroup(transformOptions).phases; |
195 var barbackOptions = new BarbackOptions( | 188 var barbackOptions = new BarbackOptions( |
196 phases, options.outDir, currentPackage: currentPackage, | 189 phases, options.outDir, currentPackage: currentPackage, |
197 packageDirs: packageDirs, machineFormat: options.machineFormat, | 190 packageDirs: packageDirs, machineFormat: options.machineFormat, |
198 // TODO(sigmund): include here also smoke transformer when it's on by | 191 // TODO(sigmund): include here also smoke transformer when it's on by |
199 // default. | 192 // default. |
200 packagePhases: {'polymer': phasesForPolymer}); | 193 packagePhases: {'polymer': phasesForPolymer}); |
201 return runBarback(barbackOptions) | 194 return runBarback(barbackOptions) |
202 .then((_) => print('Done! All files written to "${options.outDir}"')); | 195 .then((_) => print('Done! All files written to "${options.outDir}"')); |
203 } | 196 } |
204 | 197 |
205 | 198 |
206 /** | 199 /// Options that may be used either in build.dart or by the linter and deploy |
207 * Options that may be used either in build.dart or by the linter and deploy | 200 /// tools. |
208 * tools. | |
209 */ | |
210 class CommandLineOptions { | 201 class CommandLineOptions { |
211 /** Files marked as changed. */ | 202 /// Files marked as changed. |
212 final List<String> changedFiles; | 203 final List<String> changedFiles; |
213 | 204 |
214 /** Files marked as removed. */ | 205 /// Files marked as removed. |
215 final List<String> removedFiles; | 206 final List<String> removedFiles; |
216 | 207 |
217 /** Whether to clean intermediate artifacts, if any. */ | 208 /// Whether to clean intermediate artifacts, if any. |
218 final bool clean; | 209 final bool clean; |
219 | 210 |
220 /** Whether to do a full build (as if all files have changed). */ | 211 /// Whether to do a full build (as if all files have changed). |
221 final bool full; | 212 final bool full; |
222 | 213 |
223 /** Whether to print results using a machine parseable format. */ | 214 /// Whether to print results using a machine parseable format. |
224 final bool machineFormat; | 215 final bool machineFormat; |
225 | 216 |
226 /** Whether the force deploy option was passed in the command line. */ | 217 /// Whether the force deploy option was passed in the command line. |
227 final bool forceDeploy; | 218 final bool forceDeploy; |
228 | 219 |
229 /** Location where to generate output files. */ | 220 /// Location where to generate output files. |
230 final String outDir; | 221 final String outDir; |
231 | 222 |
232 /** True to use the CSP-compliant JS file. */ | 223 /// True to use the CSP-compliant JS file. |
233 final bool contentSecurityPolicy; | 224 final bool contentSecurityPolicy; |
234 | 225 |
235 /** | 226 /// True to include the JS script tag directly, without the |
236 * True to include the JS script tag directly, without the | 227 /// "packages/browser/dart.js" trampoline. |
237 * "packages/browser/dart.js" trampoline. | |
238 */ | |
239 final bool directlyIncludeJS; | 228 final bool directlyIncludeJS; |
240 | 229 |
241 /** | 230 /// Run transformers in release mode. For instance, uses the minified versions |
242 * Run transformers in release mode. For instance, uses the minified versions | 231 /// of the web_components polyfill. |
243 * of the web_components polyfill. | |
244 */ | |
245 final bool releaseMode; | 232 final bool releaseMode; |
246 | 233 |
247 CommandLineOptions(this.changedFiles, this.removedFiles, this.clean, | 234 CommandLineOptions(this.changedFiles, this.removedFiles, this.clean, |
248 this.full, this.machineFormat, this.forceDeploy, this.outDir, | 235 this.full, this.machineFormat, this.forceDeploy, this.outDir, |
249 this.directlyIncludeJS, this.contentSecurityPolicy, | 236 this.directlyIncludeJS, this.contentSecurityPolicy, |
250 this.releaseMode); | 237 this.releaseMode); |
251 } | 238 } |
252 | 239 |
253 /** | 240 /// Parse command-line arguments and return a [CommandLineOptions] object. The |
254 * Parse command-line arguments and return a [CommandLineOptions] object. The | 241 /// following flags are parsed by this method. |
255 * following flags are parsed by this method. | 242 /// |
256 * | 243 /// * `--changed file-path`: notify of a file change. |
257 * * `--changed file-path`: notify of a file change. | 244 /// * `--removed file-path`: notify that a file was removed. |
258 * * `--removed file-path`: notify that a file was removed. | 245 /// * `--clean`: remove temporary artifacts (if any) |
259 * * `--clean`: remove temporary artifacts (if any) | 246 /// * `--full`: build everything, similar to marking every file as changed |
260 * * `--full`: build everything, similar to marking every file as changed | 247 /// * `--machine`: produce output that can be parsed by tools, such as the |
261 * * `--machine`: produce output that can be parsed by tools, such as the Dart | 248 /// Dart Editor. |
262 * Editor. | 249 /// * `--deploy`: force deploy. |
263 * * `--deploy`: force deploy. | 250 /// * `--no-js`: deploy replaces *.dart scripts with *.dart.js. You can turn |
264 * * `--no-js`: deploy replaces *.dart scripts with *.dart.js. You can turn | 251 /// this feature off with --no-js, which leaves "packages/browser/dart.js". |
265 * this feature off with --no-js, which leaves "packages/browser/dart.js". | 252 /// * `--csp`: replaces *.dart with *.dart.precompiled.js to comply with |
266 * * `--csp`: replaces *.dart with *.dart.precompiled.js to comply with | 253 /// Content Security Policy restrictions. |
267 * Content Security Policy restrictions. | 254 /// * `--help`: print documentation for each option and exit. |
268 * * `--help`: print documentation for each option and exit. | 255 /// |
269 * | 256 /// Currently not all the flags are used by [lint] or [deploy] above, but they |
270 * Currently not all the flags are used by [lint] or [deploy] above, but they | 257 /// are available so they can be used from your `build.dart`. For instance, see |
271 * are available so they can be used from your `build.dart`. For instance, see | 258 /// the top-level library documentation for an example that uses the |
272 * the top-level library documentation for an example that uses the force-deploy | 259 /// force-deploy option to conditionally call [deploy]. |
273 * option to conditionally call [deploy]. | 260 /// |
274 * | 261 /// If this documentation becomes out of date, the best way to discover which |
275 * If this documentation becomes out of date, the best way to discover which | 262 /// flags are supported is to invoke this function from your build.dart, and run |
276 * flags are supported is to invoke this function from your build.dart, and run | 263 /// it with the `--help` command-line flag. |
277 * it with the `--help` command-line flag. | |
278 */ | |
279 CommandLineOptions parseOptions([List<String> args]) { | 264 CommandLineOptions parseOptions([List<String> args]) { |
280 if (args == null) { | 265 if (args == null) { |
281 print('warning: the list of arguments from main(List<String> args) now ' | 266 print('warning: the list of arguments from main(List<String> args) now ' |
282 'needs to be passed explicitly to parseOptions.'); | 267 'needs to be passed explicitly to parseOptions.'); |
283 args = []; | 268 args = []; |
284 } | 269 } |
285 var parser = new ArgParser() | 270 var parser = new ArgParser() |
286 ..addOption('changed', help: 'The file has changed since the last build.', | 271 ..addOption('changed', help: 'The file has changed since the last build.', |
287 allowMultiple: true) | 272 allowMultiple: true) |
288 ..addOption('removed', help: 'The file was removed since the last build.', | 273 ..addOption('removed', help: 'The file was removed since the last build.', |
(...skipping 37 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
326 } | 311 } |
327 if (res['help']) { | 312 if (res['help']) { |
328 print('A build script that invokes the polymer linter and deploy tools.'); | 313 print('A build script that invokes the polymer linter and deploy tools.'); |
329 showUsage(); | 314 showUsage(); |
330 exit(0); | 315 exit(0); |
331 } | 316 } |
332 return new CommandLineOptions(res['changed'], res['removed'], res['clean'], | 317 return new CommandLineOptions(res['changed'], res['removed'], res['clean'], |
333 res['full'], res['machine'], res['deploy'], res['out'], res['js'], | 318 res['full'], res['machine'], res['deploy'], res['out'], res['js'], |
334 res['csp'], !res['debug']); | 319 res['csp'], !res['debug']); |
335 } | 320 } |
OLD | NEW |