OLD | NEW |
1 // Copyright (c) 2016, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2016, 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 library front_end.compiler_options; | 5 library front_end.compiler_options; |
6 | 6 |
7 import 'package:front_end/src/base/performace_logger.dart'; | 7 import 'package:front_end/src/base/performace_logger.dart'; |
8 import 'package:front_end/src/incremental/byte_store.dart'; | 8 import 'package:front_end/src/incremental/byte_store.dart'; |
| 9 import 'package:kernel/target/targets.dart' show Target; |
9 | 10 |
10 import 'compilation_error.dart'; | 11 import 'compilation_error.dart'; |
11 import 'file_system.dart'; | 12 import 'file_system.dart'; |
12 import 'physical_file_system.dart'; | 13 import 'physical_file_system.dart'; |
13 | 14 |
14 /// Default error handler used by [CompilerOptions.onError]. | 15 /// Default error handler used by [CompilerOptions.onError]. |
15 void defaultErrorHandler(CompilationError error) => throw error; | 16 void defaultErrorHandler(CompilationError error) => throw error; |
16 | 17 |
17 /// Callback used to report errors encountered during compilation. | 18 /// Callback used to report errors encountered during compilation. |
18 typedef void ErrorHandler(CompilationError error); | 19 typedef void ErrorHandler(CompilationError error); |
19 | 20 |
20 /// Front-end options relevant to compiler back ends. | 21 /// Front-end options relevant to compiler back ends. |
21 /// | 22 /// |
22 /// Not intended to be implemented or extended by clients. | 23 /// Not intended to be implemented or extended by clients. |
23 class CompilerOptions { | 24 class CompilerOptions { |
24 /// The URI of the root of the Dart SDK (typically a "file:" URI). | 25 /// The URI of the root of the Dart SDK (typically a "file:" URI). |
25 /// | 26 /// |
26 /// If `null`, the SDK will be searched for using | 27 /// If `null`, the SDK will be searched for using |
27 /// [Platform.resolvedExecutable] as a starting point. | 28 /// [Platform.resolvedExecutable] as a starting point. |
28 /// | |
29 /// This option is mutually exclusive with [sdkSummary]. | |
30 Uri sdkRoot; | 29 Uri sdkRoot; |
31 | 30 |
32 /// Map of `dart.xyz` libraries to URIs in the [fileSystem]. | 31 /// Map of `dart:*` libraries to URIs in the [fileSystem]. |
33 /// E.g. {'core': 'file:///sdk/lib/core/core.dart'} (no `dart:` prefix). | 32 /// |
34 Map<String, Uri> dartLibraries = {}; | 33 /// Keys in the map are the name of the library with no `dart:` prefix, for |
| 34 /// example: |
| 35 /// |
| 36 /// {'core': 'file:///sdk/lib/core/core.dart'} |
| 37 /// |
| 38 /// If `null`, the default set of libraries will be loaded from |
| 39 /// `sdkRoot/lib/libraries.json`. |
| 40 // TODO(sigmund): also provide an option to specify the .json file, then |
| 41 // consider dropping this option. |
| 42 Map<String, Uri> dartLibraries; |
35 | 43 |
36 /// Callback to which compilation errors should be delivered. | 44 /// Callback to which compilation errors should be delivered. |
37 /// | 45 /// |
38 /// By default, the first error will be reported by throwing an exception of | 46 /// By default, the first error will be reported by throwing an exception of |
39 /// type [CompilationError]. | 47 /// type [CompilationError]. |
40 ErrorHandler onError = defaultErrorHandler; | 48 ErrorHandler onError = defaultErrorHandler; |
41 | 49 |
42 /// URI of the ".packages" file (typically a "file:" URI). | 50 /// URI of the ".packages" file (typically a "file:" URI). |
43 /// | 51 /// |
44 /// If `null`, the ".packages" file will be found via the standard | 52 /// If `null`, the ".packages" file will be found via the standard |
45 /// package_config search algorithm. | 53 /// package_config search algorithm. |
46 /// | 54 /// |
47 /// If the URI's path component is empty (e.g. `new Uri()`), no packages file | 55 /// If the URI's path component is empty (e.g. `new Uri()`), no packages file |
48 /// will be used. | 56 /// will be used. |
49 Uri packagesFileUri; | 57 Uri packagesFileUri; |
50 | 58 |
51 /// URIs of input summary files (excluding the SDK summary; typically these | 59 /// URIs of input summary files (excluding the SDK summary; typically these |
52 /// will be "file:" URIs). These files should all be linked summaries. They | 60 /// will be "file:" URIs). |
53 /// should also be closed, in the sense that any libraries they reference | 61 /// |
54 /// should also appear in [inputSummaries] or [sdkSummary]. | 62 /// These files should be summary files generated by this package (and not the |
| 63 /// similarly named summary files from `package:analyzer`.) |
| 64 /// |
| 65 /// Summaries may be provided in any order, but they should be acyclic and |
| 66 /// closed: any libraries that they reference should be defined in either one |
| 67 /// of [inputSummaries] or [sdkSummary]. |
55 List<Uri> inputSummaries = []; | 68 List<Uri> inputSummaries = []; |
56 | 69 |
| 70 /// URIs of other kernel programs to link. |
| 71 /// |
| 72 /// Commonly used to link the code for the SDK libraries that was compiled |
| 73 /// separately. For example, dart2js needs to link the SDK so it can |
| 74 /// optimize and tree-shake the code for the application, whereas the VM |
| 75 /// always embeds the SDK internally and doesn't need it as part of the |
| 76 /// program. |
| 77 /// |
| 78 /// The programs provided here should be closed and acyclic: any libraries |
| 79 /// that they reference should be defined in a program in [linkedDependencies] |
| 80 /// or any of the [inputSummaries] or [sdkSummary]. |
| 81 List<Uri> linkedDependencies = []; |
| 82 |
57 /// URI of the SDK summary file (typically a "file:" URI). | 83 /// URI of the SDK summary file (typically a "file:" URI). |
58 /// | 84 /// |
59 /// This should be a linked summary. If `null`, the SDK summary will be | 85 /// This should should be a summary previosly generated by this package (and |
60 /// searched for at a default location within [sdkRoot]. | 86 /// not the similarly named summary files from `package:analyzer`.) |
61 /// | 87 /// |
62 /// This option is mutually exclusive with [sdkRoot]. TODO(paulberry): if the | 88 /// If `null` and [compileSdk] is false, the SDK summary will be searched for |
63 /// VM does not contain a pickled copy of the SDK, we might need to change | 89 /// at a default location within [sdkRoot]. |
64 /// this. | |
65 Uri sdkSummary; | 90 Uri sdkSummary; |
66 | 91 |
67 /// URI override map. | |
68 /// | |
69 /// This is a map from URIs that might appear in import/export/part statements | |
70 /// to URIs that should be used to locate the corresponding files in the | |
71 /// [fileSystem]. Any URI override listed in this map takes precedence over | |
72 /// the URI resolution that would be implied by the packages file (see | |
73 /// [packagesFileUri]) and/or [multiRoots]. | |
74 /// | |
75 /// If a URI is not listed in this map, then the normal URI resolution | |
76 /// algorithm will be used. | |
77 /// | |
78 /// TODO(paulberry): transition analyzer and dev_compiler to use the | |
79 /// "multi-root:" mechanism, and then remove this. | |
80 @deprecated | |
81 Map<Uri, Uri> uriOverride = {}; | |
82 | |
83 /// Multi-roots. | 92 /// Multi-roots. |
84 /// | 93 /// |
85 /// Any Uri that resolves to "multi-root:///$rest" will be searched for | 94 /// Any Uri that resolves to "multi-root:///$absolute_path" will be searched |
86 /// at "$root/$rest", where "$root" is drawn from this list. | 95 /// for at "$root/$absolute_path", where "$root" is drawn from this list. |
87 /// | 96 /// |
88 /// Intended use: if the user has a Bazel workspace located at path | 97 /// Intended use: if the user has a Bazel workspace located at path |
89 /// "$workspace", this could be set to the file URIs corresponding to the | 98 /// "$workspace", this could be set to the file URIs corresponding to the |
90 /// paths for "$workspace", "$workspace/bazel-bin", | 99 /// paths for "$workspace", "$workspace/bazel-bin", |
91 /// and "$workspace/bazel-genfiles", effectively overlaying source and | 100 /// and "$workspace/bazel-genfiles", effectively overlaying source and |
92 /// generated files. | 101 /// generated files. |
93 List<Uri> multiRoots = []; | 102 List<Uri> multiRoots = []; |
94 | 103 |
95 /// The declared variables for use by configurable imports and constant | 104 /// The declared variables for use by configurable imports and constant |
96 /// evaluation. | 105 /// evaluation. |
97 Map<String, String> declaredVariables; | 106 Map<String, String> declaredVariables; |
98 | 107 |
99 /// The [FileSystem] which should be used by the front end to access files. | 108 /// The [FileSystem] which should be used by the front end to access files. |
100 /// | 109 /// |
101 /// All file system access performed by the front end goes through this | 110 /// All file system access performed by the front end goes through this |
102 /// mechanism, with one exception: if no value is specified for | 111 /// mechanism, with one exception: if no value is specified for |
103 /// [packagesFileUri], the packages file is located using the actual physical | 112 /// [packagesFileUri], the packages file is located using the actual physical |
104 /// file system. TODO(paulberry): fix this. | 113 /// file system. TODO(paulberry): fix this. |
105 FileSystem fileSystem = PhysicalFileSystem.instance; | 114 FileSystem fileSystem = PhysicalFileSystem.instance; |
106 | 115 |
107 /// The byte storage to get and put serialized data. | 116 /// The byte storage to access serialized data. |
108 ByteStore byteStore = new NullByteStore(); | 117 ByteStore byteStore = new NullByteStore(); |
109 | 118 |
110 /// The logger to report compilation progress. | 119 /// The logger to report compilation progress. |
111 PerformanceLog logger = new PerformanceLog(new StringBuffer()); | 120 PerformanceLog logger = new PerformanceLog(new StringBuffer()); |
112 | 121 |
113 /// Whether to generate code for the SDK when compiling a whole-program. | 122 /// Whether to generate code for the SDK. |
| 123 /// |
| 124 /// By default the front end resolves programs using a prebuilt SDK summary. |
| 125 /// When this option is `true`, [sdkSummary] must be null. |
114 bool compileSdk = false; | 126 bool compileSdk = false; |
115 | 127 |
116 /// Whether a modular build compiles only the files listed explicitly or if it | 128 /// Whether the compiler should read files that are discovered as |
117 /// compiles dependencies as well. | 129 /// dependencies, or only access the files listed explicitly. |
118 /// | 130 /// |
119 /// This option is intended only for modular APIs like `kernelForBuildUnit`. | 131 /// This option has different defaults depending on the API. |
120 /// These APIs by default ensure that builds are hermetic, where all files | |
121 /// that will be compiled are listed explicitly and all other dependencies | |
122 /// are covered by summary files. | |
123 /// | 132 /// |
124 /// When this option is true, these APIs will treat any dependency that is | 133 /// For modular APIs like `kernelForBuildUnit` and `summaryFor` the default |
125 /// not described in a summary as if it was explicitly listed as an input. | 134 /// behavior is `false`. These APIs want to ensure that builds are hermetic, |
126 bool chaseDependencies = false; | 135 /// where all files that will be compiled are listed explicitly and all other |
| 136 /// dependencies are covered by summary files. |
| 137 /// |
| 138 /// For whole-program APIs like `kernelForProgram`, this option is true by |
| 139 /// default, so they can treat any dependency that is not described in a |
| 140 /// summary as if it was explicitly listed as an input. |
| 141 bool chaseDependencies; |
127 | 142 |
128 /// Whether to interpret Dart sources in strong-mode. | 143 /// Whether to interpret Dart sources in strong-mode. |
129 bool strongMode = true; | 144 bool strongMode = true; |
130 | 145 |
131 // All options below are target-specific options. | |
132 // | |
133 // TODO(sigmund): revisit the right layout for these options. We might want to | |
134 // split them out into a separate bag of options or provide factories for | |
135 // common combinations of these options. | |
136 | |
137 /// Patch files to apply on the core libraries for a specific target platform. | 146 /// Patch files to apply on the core libraries for a specific target platform. |
138 /// | 147 /// |
139 /// Keys on this map are expected to be `dart:*` URIs. The values can be | 148 /// Keys in the map are the name of the library with no `dart:` prefix, for |
140 /// either absolute or relative URIs. Absolute URIs are read directly, while | 149 /// example: |
141 /// relative URIs are resolved from the [sdkRoot]. | 150 /// |
142 Map<Uri, List<Uri>> targetPatches = {}; | 151 /// {'core': [ |
| 152 /// 'file:///location/of/core/patch_file1.dart', |
| 153 /// 'file:///location/of/core/patch_file2.dart', |
| 154 /// ]} |
| 155 /// |
| 156 /// The values can be either absolute or relative URIs. Absolute URIs are read |
| 157 /// directly, while relative URIs are resolved from the [sdkRoot]. |
| 158 // TODO(sigmund): provide also a flag to load this data from a file (like |
| 159 // libraries.json) |
| 160 Map<String, List<Uri>> targetPatches = {}; |
143 | 161 |
144 /// Additional core libraries to be loaded when building a program. | 162 /// The target platform that will consume the compiled code. |
145 // TODO(sigmund): delete. Ideally building a program only needs what's | 163 /// |
146 // reachable and we can use kernelForBuildUnit when creating a snapshot of the | 164 /// Used to provide platform-specific details to the compiler like: |
147 // SDK itself. | 165 /// * the set of libraries are part of a platform's SDK (e.g. dart:html for |
148 List<Uri> additionalLibraries = []; | 166 /// dart2js, dart:ui for flutter). |
| 167 /// |
| 168 /// * what kernel transformations should be applied to the program |
| 169 /// (async/await, mixin inlining, etc). |
| 170 /// |
| 171 /// * how to deal with non-standard features like `native` extensions. |
| 172 /// |
| 173 /// If not specified, the default target is the VM. |
| 174 Target target; |
| 175 |
| 176 /// Whether to show verbose messages (mainly for debugging and performance |
| 177 /// tracking). |
| 178 /// |
| 179 /// Messages are printed on stdout. |
| 180 // TODO(sigmund): improve the diagnotics API to provide mechanism to intercept |
| 181 // verbose data (Issue #30056) |
| 182 bool verbose = false; |
| 183 |
| 184 /// Whether to run extra verification steps to validate that compiled programs |
| 185 /// are well formed. |
| 186 /// |
| 187 /// Errors are reported via the [onError] callback. |
| 188 // TODO(sigmund): ensure we don't print errors to stdout (Issue #30056) |
| 189 bool verify = false; |
| 190 |
| 191 /// Whether to dump generated programs in a text format (also mainly for |
| 192 /// debugging). |
| 193 /// |
| 194 /// Dumped data is printed in stdout. |
| 195 bool debugDump = false; |
149 } | 196 } |
OLD | NEW |