Index: pkg/code_transformers/lib/src/messages.dart |
diff --git a/pkg/code_transformers/lib/src/messages.dart b/pkg/code_transformers/lib/src/messages.dart |
new file mode 100644 |
index 0000000000000000000000000000000000000000..edf0857f249b6b74b6bc8d285c8aedc9becb60b0 |
--- /dev/null |
+++ b/pkg/code_transformers/lib/src/messages.dart |
@@ -0,0 +1,171 @@ |
+// Copyright (c) 2014, the Dart project authors. Please see the AUTHORS file |
+// for details. All rights reserved. Use of this source code is governed by a |
+// BSD-style license that can be found in the LICENSE file. |
+ |
+/// Contains all warning messages produced by the code_transformers package. |
+library code_transformers.src.messages; |
+ |
+import 'package:code_transformers/messages/messages.dart'; |
+ |
+const noAbsolutePaths = const MessageTemplate( |
jakemac
2014/09/03 17:20:41
These should really be all caps names since they a
Siggi Cherem (dart-lang)
2014/09/04 02:32:13
:) I think there is not consensus on that part of
jakemac
2014/09/04 14:42:37
Weird, but ok :). To me all caps constants is the
|
+ const MessageId('code_transformers', 1), |
+ 'absolute paths not allowed: "%-url-%"', |
+ 'Absolute paths not allowed', |
+ ''' |
+The transformers processing your code were trying to resolve a URL and identify |
+a file that they correspond to. Currently only relative paths can be resolved. |
+'''); |
+ |
+const invalidUrlToOtherPackage = const MessageTemplate( |
+ const MessageId('code_transformers', 2), |
+ 'Invalid url to reach to another package: %-url-%. Path ' |
Kathy Walrath
2014/09/03 18:56:36
Global change to text:
url -> URL
Siggi Cherem (dart-lang)
2014/09/04 02:32:14
Done.
|
+ 'reaching to other packages must first reach up all the ' |
+ 'way to the %-prefix-% folder. For example, try changing the url above ' |
Kathy Walrath
2014/09/03 18:56:35
is it clear what "above" means?
Kathy Walrath
2014/09/03 18:56:36
Be consistent about using folder vs. directory. I
Siggi Cherem (dart-lang)
2014/09/04 02:32:13
Done.
Siggi Cherem (dart-lang)
2014/09/04 02:32:14
It seems we didn't need it :). removed
|
+ 'to: %-fixedUrl-%', |
+ 'Invalid url to reach another package', |
+ ''' |
+To reach an asset that belongs to another package, we use `package:` URLs in |
Kathy Walrath
2014/09/03 18:56:35
we use -> use
In general, avoid "we" in messages.
Siggi Cherem (dart-lang)
2014/09/04 02:32:14
Done.
|
+Dart code, but in any other language (like HTML or CSS) we use relative URLs. |
Kathy Walrath
2014/09/03 18:56:36
we use -> use
Siggi Cherem (dart-lang)
2014/09/04 02:32:13
Done.
|
+ |
+These are the rules you must follow to write URLs that refer to files in other |
Kathy Walrath
2014/09/03 18:56:35
-> Follow these rules when writing...
This is way
Siggi Cherem (dart-lang)
2014/09/04 02:32:13
I was debating about this - one idea I was thinkin
|
+packages: |
+ |
+ * if the file containing the relative URL is an entrypoint under `web`, use |
Kathy Walrath
2014/09/03 18:56:36
if -> If
Siggi Cherem (dart-lang)
2014/09/04 02:32:14
Done.
|
+ `packages/package_name/path_to_file` |
+ |
+ * if the file containing the URL is under `web`, but on a different directory |
Kathy Walrath
2014/09/03 18:56:35
if -> If
on -> in
Siggi Cherem (dart-lang)
2014/09/04 02:32:13
Done.
|
+ than your entrypoint, walk out to the same level as the entrypoint first, |
+ then enter the `packages` folder. |
+ |
+ **Note**: this means that if you have two entrypoints including this file, |
Kathy Walrath
2014/09/03 18:56:36
this means that if you have two entrypoints includ
Siggi Cherem (dart-lang)
2014/09/04 02:32:14
Done.
|
+ either both entrypoints have to live in the same directory, or you need to |
+ move the file to the `lib` folder. |
+ |
+ * if the file containing the URL lives under `lib`, walk up as many levels as |
Kathy Walrath
2014/09/03 18:56:36
if -> If
Siggi Cherem (dart-lang)
2014/09/04 02:32:14
Done.
|
+ directories you have + 1. This is because code in `lib/a/b` is loaded from |
+ `packages/package_name/a/b`. |
+ |
+The rules are easier to follow if you know how the code is layed out for |
Kathy Walrath
2014/09/03 18:56:35
layed -> laid
(global)
Siggi Cherem (dart-lang)
2014/09/04 02:32:14
<facepalm> thx!
Kathy Walrath
2014/09/04 17:07:28
I had to look it up to be sure. :)
|
+Dartium before you build, and how it is layed out after you build it with `pub |
+build`. Consider the following example: |
+ |
+ package a |
+ lib/ |
+ '- a1.html |
Kathy Walrath
2014/09/03 18:56:35
Could you use | instead of '? You used | below (fo
Siggi Cherem (dart-lang)
2014/09/04 02:32:13
Sure, I was basically using the style that pub use
|
+ |
+ web/ |
+ '- a2.html |
+ |
+ package b |
+ lib/ |
+ |- b1.html |
+ '- b2/ |
+ '- b3.html |
+ |
+ package c |
+ lib/ |
+ '- c3.html |
+ |
+ web/ |
+ |- index.html |
+ |- index.dart |
+ |- c1/ |
+ '- c2.html |
+ |
+If your app is package `c`, you'll notice that in your file system there is a |
Kathy Walrath
2014/09/03 18:56:36
you'll notice that in your file system there is a
Siggi Cherem (dart-lang)
2014/09/04 02:32:13
Done.
|
+packages folder generated in the web folder, like this: |
+ |
+ web/ |
+ |- index.html |
+ |- index.dart |
+ |- c1/ |
+ | '- c2.html |
+ '- packages/ |
+ |- a/ |
+ | '- a1.html |
+ |- b/ |
+ | |- b1.html |
+ | '- b2/ |
+ | '- b3.html |
+ '- c/ |
+ '- c3.html |
+ |
+Note that there is no `lib` folder under the `packages` folder. When you load |
+`index.html` in Dartium, it will infer that the package root is under |
Kathy Walrath
2014/09/03 18:56:35
what is "it"? Also, avoid "there is" when possible
Siggi Cherem (dart-lang)
2014/09/04 02:32:13
Good points. Thanks - here is what I ended up with
|
+`web/packages/`. |
+ |
+If you need to refer to any file in other packages from `index.html`, you can |
+simply do `packages/package_name/path_to_file`. For example |
+`packages/b/b2/b3.html`. From `index.html` you can also refer to files under the |
+web folder of the same package using a simple relative URL, like `c1/c2.html`. |
+ |
+However, if you want to load `a1.html` from `c2.html`, you need to reach out to |
+the packages folder that lives next to your entrypoint and then load the file |
+from there, for example `../packages/a/a1.html`. Because pub generates symlinks |
+to the packages folder also under c1, you may be tempted to write |
+`packages/a/a1.html`, but that is incorrect - it would yield a canonicalization |
+error (see more below). |
+ |
+If you want to load a file from the lib folder of your own package, you |
+should also use a package URL. For example, `packages/c/c3.html` and not |
+`../lib/c3.html`. This will allow you to write code in `lib` in a way that it |
+can be used within and outside your package without making any changes to it. |
+ |
+Because any time you reach inside a `lib/` folder you do so using a `packages/` |
+URL, the rules for reaching into other files in other packages are always |
+consistent: go up to exit the `packages` folder and go back inside to the file you |
+are looking for. For example, to reach `a1.html` from `b3.html` you need to |
+write `../../../packages/a/a1.html`. |
+ |
+The motivation behind all these rules is that we would like to have URLs that |
+work under many scenarios at once: |
+ |
+ * They need to work in Dartium without any code transformation: resolving the |
+ path in the context of a simple HTTP server, or using `file:///` URLs, |
+ should yield a valid path to assets. Since pub already creates a `packages` |
+ directory next to entrypoints of your application, we assume we can use it. |
+ |
+ * They need to be canonical. To take advantage of caching, multiple URLs |
+ reaching the same asset should resolve to the same absolute URL. |
+ |
+ Also, in projects that use HTML imports (like polymer) we make sure that if |
+ you reach a library twice, once with Dart imports, and a second time with |
+ HTML imports, then they are correctly resolved to be the same library. Our |
+ rules are designed to allow tools to ensure this. |
+ |
+ For example, consider you have an import might like: |
+ |
+ <link rel=import href=packages/a/a.html> |
+ |
+ where a.html has `<script type="application/dart" src="a.dart">`. If your |
+ Dart entrypoint also loads `"package:a/a.dart"`, then we need to make sure |
+ that both versions of `a.dart` are loaded from the same URL. Otherwise, you |
+ may see errors at runtime like: `A is not a subtype of A`, which can be |
+ extremely confusing. |
+ |
+ When you follow the rules above, our tools can detect the pattern in the |
+ HTML-import URL containing `packages/` and canonicalize the import |
+ by converting `packages/a/a.dart` into `package:a/a.dart` under the hood. |
+ |
+ * They need to continue to be valid after applications are built. |
+ Technically this could be done automatically with pub transformers, but to |
+ make sure that code works also in Dartium with a simple HTTP Server, |
+ existing transformers do not fix URLs, they just detect inconsistencies and |
+ produce an error message like this one, instead. |
Kathy Walrath
2014/09/03 18:56:36
This is a lot of doc! How about I put it in a page
Siggi Cherem (dart-lang)
2014/09/04 02:32:14
That's actually how it works, I'm just storing the
Kathy Walrath
2014/09/04 17:07:27
What I meant was I didn't want to bury this doc (a
|
+'''); |
+ |
+const incompletePrefixPath = const MessageTemplate( |
+ const MessageId('code_transformers', 3), |
+ 'incomplete %-prefix-%/ path. It should have at least 3 ' |
+ 'segments %-prefix-%/name/path_from_name\'s_%-folder-%_dir', |
+ 'Incomplete import to asset in another package', |
Kathy Walrath
2014/09/03 18:56:36
to -> of?
Siggi Cherem (dart-lang)
2014/09/04 02:32:14
rephrased, I should not use the word import here a
|
+ ''' |
+Currently we require that URLs that refer to assets in other packages to |
+explicitly mention the `packages/` folder. In the future we might remove this |
+requiremnt, but for now we ask that you use a canonical URL form for it. |
Kathy Walrath
2014/09/03 18:56:36
requiremnt -> requirement
Siggi Cherem (dart-lang)
2014/09/04 02:32:14
Done.
|
+ |
+For example, if you have `packages/a/a.html` using an HTML import to |
+`packages/b/b.html`, you could technically just write `../b/b.html`, but we |
Kathy Walrath
2014/09/03 18:56:35
who is "we" really? polymer.dart? The polymer tran
Siggi Cherem (dart-lang)
2014/09/04 02:32:14
Done. also removed `we` elsewhere...
|
+require that you write `../../packages/b/b.html`. |
+See [issue 15797](http://dartbug.com/15797). |
+'''); |