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

Side by Side Diff: pkg/code_transformers/lib/src/messages.dart

Issue 513023002: Step one towards stable error messages with details: (Closed) Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart
Patch Set: Created 6 years, 3 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 | Annotate | Revision Log
« no previous file with comments | « pkg/code_transformers/lib/messages/messages.dart ('k') | pkg/code_transformers/pubspec.yaml » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
(Empty)
1 // Copyright (c) 2014, the Dart project authors. Please see the AUTHORS file
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.
4
5 /// Contains all warning messages produced by the code_transformers package.
6 library code_transformers.src.messages;
7
8 import 'package:code_transformers/messages/messages.dart';
9
10 const NO_ABSOLUTE_PATHS = const MessageTemplate(
11 const MessageId('code_transformers', 1),
12 'absolute paths not allowed: "%-url-%"',
13 'Absolute paths not allowed',
14 '''
15 The transformers processing your code were trying to resolve a URL and identify
16 a file that they correspond to. Currently only relative paths can be resolved.
17 ''');
18
19 const INVALID_URL_TO_OTHER_PACKAGE = const MessageTemplate(
20 const MessageId('code_transformers', 2),
21 'Invalid URL to reach to another package: %-url-%. Path '
22 'reaching to other packages must first reach up all the '
23 'way to the %-prefix-% directory. For example, try changing the URL '
24 'to: %-fixedUrl-%',
25 'Invalid URL to reach another package',
26 '''
27 To reach an asset that belongs to another package, use `package:` URLs in
28 Dart code, but in any other language (like HTML or CSS) use relative URLs.
29
30 These are the rules you must follow to write URLs that refer to files in other
31 packages:
32
33 * If the file containing the relative URL is an entrypoint under `web`, use
34 `packages/package_name/path_to_file`
35
36 * If the file containing the URL is under `web`, but in a different directory
37 than your entrypoint, walk out to the same level as the entrypoint first,
38 then enter the `packages` directory.
39
40 **Note**: If two entrypoints include the file under `web` containing the
41 URL, either both entrypoints have to live in the same directory, or you need
42 to move the file to the `lib` directory.
43
44 * If the file containing the URL lives under `lib`, walk up as many levels as
45 directories you have + 1. This is because code in `lib/a/b` is loaded from
46 `packages/package_name/a/b`.
47
48 The rules are easier to follow if you know how the code is laid out for
49 Dartium before you build, and how it is laid out after you build it with `pub
50 build`. Consider the following example:
51
52 package a
53 lib/
54 |- a1.html
55
56 web/
57 |- a2.html
58
59 package b
60 lib/
61 |- b1.html
62 |- b2/
63 |- b3.html
64
65 package c
66 lib/
67 |- c3.html
68
69 web/
70 |- index.html
71 |- index.dart
72 |- c1/
73 |- c2.html
74
75 If your app is package `c`, then `pub get` generates a packages directory under
76 the web directory, like this:
77
78 web/
79 |- index.html
80 |- index.dart
81 |- c1/
82 | |- c2.html
83 |- packages/
84 |- a/
85 | |- a1.html
86 |- b/
87 | |- b1.html
88 | |- b2/
89 | |- b3.html
90 |- c/
91 |- c3.html
92
93 Note that no `lib` directory is under the `packages` directory.
94 When you launch `web/index.html` in Dartium, Dartium loads `package:` imports fr om
95 `web/packages/`.
96
97 If you need to refer to any file in other packages from `index.html`, you can
98 simply do `packages/package_name/path_to_file`. For example
99 `packages/b/b2/b3.html`. From `index.html` you can also refer to files under the
100 web directory of the same package using a simple relative URL, like
101 `c1/c2.html`.
102
103 However, if you want to load `a1.html` from `c2.html`, you need to reach out to
104 the packages directory that lives next to your entrypoint and then load the file
105 from there, for example `../packages/a/a1.html`. Because pub generates symlinks
106 to the packages directory also under c1, you may be tempted to write
107 `packages/a/a1.html`, but that is incorrect - it would yield a canonicalization
108 error (see more below).
109
110 If you want to load a file from the lib directory of your own package, you
111 should also use a package URL. For example, `packages/c/c3.html` and not
112 `../lib/c3.html`. This will allow you to write code in `lib` in a way that it
113 can be used within and outside your package without making any changes to it.
114
115 Because any time you reach inside a `lib/` directory you do so using a
116 `packages/` URL, the rules for reaching into other files in other packages are
117 always consistent: go up to exit the `packages` directory and go back inside to
118 the file you are looking for. For example, to reach `a1.html` from `b3.html`
119 you need to write `../../../packages/a/a1.html`.
120
121 The motivation behind all these rules is that URLs need to work under many
122 scenarios at once:
123
124 * They need to work in Dartium without any code transformation: resolving the
125 path in the context of a simple HTTP server, or using `file:///` URLs,
126 should yield a valid path to assets. The `packages` directory is safe to use
127 because pub already creates it next to entrypoints of your application.
128
129 * They need to be canonical. To take advantage of caching, multiple URLs
130 reaching the same asset should resolve to the same absolute URL.
131
132 Also, in projects that use HTML imports (like polymer) tools support that
133 you reach a library with either Dart imports or HTML imports, and correctly
134 resolve them to be the same library. The rules are designed to allow tools
135 to support this.
136
137 For example, consider you have an import might like:
138
139 <link rel=import href=packages/a/a.html>
140
141 where a.html has `<script type="application/dart" src="a.dart">`. If your
142 Dart entrypoint also loads `"package:a/a.dart"`, then a tool need to make
143 sure that both versions of `a.dart` are loaded from the same URL. Otherwise,
144 you may see errors at runtime like: `A is not a subtype of A`, which can be
145 extremely confusing.
146
147 When you follow the rules above, our tools can detect the pattern in the
148 HTML-import URL containing `packages/` and canonicalize the import
149 by converting `packages/a/a.dart` into `package:a/a.dart` under the hood.
150
151 * They need to continue to be valid after applications are built.
152 Technically this could be done automatically with pub transformers, but to
153 make sure that code works also in Dartium with a simple HTTP Server,
154 existing transformers do not fix URLs, they just detect inconsistencies and
155 produce an error message like this one, instead.
156 ''');
157
158 const INVALID_PREFIX_PATH = const MessageTemplate(
159 const MessageId('code_transformers', 3),
160 'incomplete %-prefix-%/ path. It should have at least 3 '
161 'segments %-prefix-%/name/path_from_name\'s_%-folder-%_dir',
162 'Incomplete URL to asset in another package',
163 '''
164 URLs that refer to assets in other packages need to explicitly mention the
165 `packages/` directory. In the future this requirement might be removed, but for
166 now you must use a canonical URL form for it.
167
168 For example, if `packages/a/a.html` needs to import `packages/b/b.html`,
169 you might expect a.html to import `../b/b.html`. Instead, it must import
170 `../../packages/b/b.html`.
171 See [issue 15797](http://dartbug.com/15797).
172 ''');
OLDNEW
« no previous file with comments | « pkg/code_transformers/lib/messages/messages.dart ('k') | pkg/code_transformers/pubspec.yaml » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698