Skip to content
Browse files

Remove docs and point to ones on dartlang.org.

  • Loading branch information...
1 parent 2345ef3 commit e2ab489f01a454960a12dc8a591192770b93b9e9 @munificent munificent committed Feb 14, 2014
Showing with 31 additions and 8,966 deletions.
  1. +0 −2 .gitignore
  2. +0 −3 Gemfile
  3. +0 −42 Gemfile.lock
  4. +0 −1 Procfile
  5. +10 −17 README.md
  6. +0 −8 _config.yml
  7. +0 −3,920 app/doc/assets-and-transformers.graffle
  8. +0 −186 app/doc/assets-and-transformers.markdown
  9. +0 −281 app/doc/dependencies.markdown
  10. +0 −137 app/doc/faq.markdown
  11. +0 −213 app/doc/glossary.markdown
  12. +0 −296 app/doc/index.markdown
  13. +0 −362 app/doc/package-layout.markdown
  14. +0 −51 app/doc/pub-build.markdown
  15. +0 −15 app/doc/pub-cache.markdown
  16. +0 −99 app/doc/pub-get.markdown
  17. +0 −91 app/doc/pub-lish.markdown
  18. +0 −65 app/doc/pub-serve.markdown
  19. +0 −76 app/doc/pub-upgrade.markdown
  20. +0 −30 app/doc/pub-uploader.markdown
  21. +0 −184 app/doc/pubspec.markdown
  22. +0 −379 app/doc/versioning.markdown
  23. +0 −59 app/handlers/doc.py
  24. +0 −5 app/pub_dartlang.py
  25. +0 −182 app/views/doc/assets-and-transformers.html
  26. +0 −267 app/views/doc/dependencies.html
  27. +0 −116 app/views/doc/faq.html
  28. +0 −211 app/views/doc/glossary.html
  29. +0 −298 app/views/doc/index.html
  30. +0 −368 app/views/doc/package-layout.html
  31. +0 −51 app/views/doc/pub-build.html
  32. +0 −12 app/views/doc/pub-cache.html
  33. +0 −96 app/views/doc/pub-get.html
  34. +0 −93 app/views/doc/pub-lish.html
  35. +0 −66 app/views/doc/pub-serve.html
  36. +0 −75 app/views/doc/pub-upgrade.html
  37. +0 −29 app/views/doc/pub-uploader.html
  38. +0 −174 app/views/doc/pubspec.html
  39. +0 −372 app/views/doc/versioning.html
  40. +4 −1 app/views/index.mustache
  41. +15 −15 app/views/layout.mustache
  42. +2 −2 app/views/packages/show.mustache
  43. +0 −16 app/views/site_map.mustache
View
2 .gitignore
@@ -1,5 +1,3 @@
*.pyc
.sass-cache/
.DS_Store
-
-/app/views/doc/assets-and-transformers.graffle
View
3 Gemfile
@@ -2,7 +2,4 @@ source "https://rubygems.org"
gem "compass"
gem "compass_twitter_bootstrap", "~>2.0.3"
-gem "jekyll"
-gem "kramdown"
gem "foreman"
-gem "pygments.rb"
View
42 Gemfile.lock
@@ -2,58 +2,19 @@ GEM
remote: https://rubygems.org/
specs:
chunky_png (1.2.9)
- classifier (1.3.3)
- fast-stemmer (>= 1.0.0)
- colorator (0.1)
- commander (4.1.5)
- highline (~> 1.6.11)
compass (0.12.2)
chunky_png (~> 1.2)
fssm (>= 0.2.7)
sass (~> 3.1)
compass_twitter_bootstrap (2.0.3)
compass
dotenv (0.9.0)
- fast-stemmer (1.0.2)
- ffi (1.9.3)
foreman (0.63.0)
dotenv (>= 0.7)
thor (>= 0.13.6)
fssm (0.2.10)
- highline (1.6.20)
- jekyll (1.3.0)
- classifier (~> 1.3)
- colorator (~> 0.1)
- commander (~> 4.1.3)
- liquid (~> 2.5.2)
- listen (~> 1.3)
- maruku (~> 0.6.0)
- pygments.rb (~> 0.5.0)
- redcarpet (~> 2.3.0)
- safe_yaml (~> 0.9.7)
- kramdown (1.2.0)
- liquid (2.5.4)
- listen (1.3.1)
- rb-fsevent (>= 0.9.3)
- rb-inotify (>= 0.9)
- rb-kqueue (>= 0.2)
- maruku (0.6.1)
- syntax (>= 1.0.0)
- posix-spawn (0.3.6)
- pygments.rb (0.5.4)
- posix-spawn (~> 0.3.6)
- yajl-ruby (~> 1.1.0)
- rb-fsevent (0.9.3)
- rb-inotify (0.9.2)
- ffi (>= 0.5.0)
- rb-kqueue (0.2.0)
- ffi (>= 0.5.0)
- redcarpet (2.3.0)
- safe_yaml (0.9.7)
sass (3.2.12)
- syntax (1.0.0)
thor (0.18.1)
- yajl-ruby (1.1.0)
PLATFORMS
ruby
@@ -62,6 +23,3 @@ DEPENDENCIES
compass
compass_twitter_bootstrap (~> 2.0.3)
foreman
- jekyll
- kramdown
- pygments.rb
View
1 Procfile
@@ -1,2 +1 @@
-jekyll: bundle exec jekyll build -w
compass: bundle exec compass watch css
View
27 README.md
@@ -40,7 +40,7 @@ it locally, perform the following steps:
./test.py
* To publish packages to your local test server, visit <http://localhost:8080/admin>
- (sign in as administrator), go to the "Private Key" tab & enter any string
+ (sign in as administrator), go to the "Private Key" tab & enter any string
into the private key field.
<sup>1</sup> This might have been done already if you allowed the Google App
@@ -50,7 +50,7 @@ it locally, perform the following steps:
* Beautiful Soup & WebTest are only required for running tests.
* Some Linux distributions come with PyCrypto installed by default. Make sure
at least version 2.6 installed.
-* If using Mac and `pip` is not available, install [brew](http://brew.sh) and
+* If using Mac and `pip` is not available, install [brew](http://brew.sh) and
run `brew install python`.
### Deploying
@@ -62,16 +62,12 @@ See the docs on [branches and versions][].
### Modifying the CSS and Documentation
The CSS files are generated from the source [Sass][] files using [Compass][].
-The HTML documentation files are generated from the source [Markdown][] using
-[Jekyll][]. To get ready to make changes, you'll need [Ruby][] and [Python][].
-Then:
+To get ready to make changes, you'll need [Ruby][] and [Python][]. Then:
[ruby]: http://ruby-lang.org
[python]: http://python.org
[sass]: http://sass-lang.com
[compass]: http://compass-style.org
-[markdown]: http://daringfireball.net/projects/markdown/
-[jekyll]: http://jekyllrb.com/
1. Ensure you have bundler installed:
@@ -85,21 +81,18 @@ Then:
sudo pip install --upgrade pygments
-Note that this is only needed on your development machine to iterate on the CSS
-and documentation. The deployed server just uses the pre-compiled CSS and HTML
-and only requires Python.
+Note that this is only needed on your development machine to iterate on the CSS. The deployed server just uses the pre-compiled CSS and only requires Python.
-Once you have everything installed, to modify the styles and documentation:
+Once you have everything installed, to modify the styles:
- 1. Run [Foreman][] to automatically regenerate the CSS and HTML files when any
- Sass or Markdown files change:
+ 1. Run [Foreman][] to automatically regenerate the CSS files when any Sass
+ files change:
bundle exec foreman start
- 1. Edit the `.scss` files under `css/sass` and the `.markdown` files under
- `doc`.
+ 1. Edit the `.scss` files under `css/sass`.
[foreman]: http://ddollar.github.com/foreman/
-When you make changes to SCSS or Markdown files, make sure to check in the
-generated CSS or HTML files with them.
+When you make changes to SCSS files, make sure to check in the generated CSS
+files with them.
View
8 _config.yml
@@ -1,8 +0,0 @@
-safe: false
-port: 8080
-source: app/doc
-destination: app/views/doc
-markdown: kramdown
-kramdown:
- entity_output: symbolic
-pygments: true
View
3,920 app/doc/assets-and-transformers.graffle
0 additions, 3,920 deletions not shown because the diff is too large. Please use a local Git client to view these changes.
View
186 app/doc/assets-and-transformers.markdown
@@ -1,186 +0,0 @@
----
-title: "Assets and Transformers"
----
-
-The [`pub serve`](pub-serve.html) and [`pub build`](pub-build.html)
-commands use [transformers][] to prepare a package's [assets][] to be served
-locally or to be deployed, respectively.
-
-Use the `pubspec.yaml` file to specify which transformers your package uses
-and, if necessary, to configure the transformers. (See
-[Specifying transformers](#specifying-transformers) for details.) For example:
-
-<pre>
-name: myapp
-dependencies:
- <b>polymer: any</b>
-<b>transformers:
-- polymer:
- entry_points:
- - web/index.html
- - web/index2.html</b>
-</pre>
-
-A package's assets must be in one or more of the following directories:
-`lib`, `asset`, and `web`. After transformation by `pub build`, assets are
-available under a directory called `build`. Assets generated from
-files in a package's `lib` directory appear under a directory named
-<code>packages/<em>&lt;pkg_name></em></code>, and those from the package's
-`asset` directory appear under <code>assets/<em>&lt;pkg_name></em></code>.
-For details, see
-[Where to put assets](#where-to-put-assets) and
-[How to refer to assets](#how-to-refer-to-assets).
-
-## How transformers work {#how-transformers-work}
-
-Here are some examples of transformers:
-
-* The dart2js transformer, which reads in all of the `.dart` files for a
- program and compiles them to a single `.js` file.
-* The polymer transformer, which converts HTML and Dart files into
- optimized HTML and Dart files.
-* A linter that reads in files and produces warnings but no actual file.
-
-Although you specify which transformers to use, you don't explicitly say
-which transformers should be applied to which assets. Instead, each
-transformer determines which assets it can apply itself to. For `pub serve`,
-the transformers run when the dev server starts up and whenever a source
-asset changes. The `pub build` command runs the transformers once and
-then exits.
-
-As the following figure shows, source assets can pass through, untransformed,
-and become generated assets. Or a source asset can be transformed, such as a
-`.dart` file (along with the `.dart` files that it refers to) that is
-compiled to `.js`.
-
-![a figure showing source assets and generated assets; the .html, .css, and .png files pass through, untransformed; the .dart file is transformed into a .js file (and, for pub serve only, the .dart file is passed through, as well)](/img/assets-and-transformers.png)
-
-Dart files are a special case. The `pub build` command doesn't produce `.dart`
-files because browsers in the wild don't support Dart natively (yet). The `pub
-serve` command, on the other hand, does generate `.dart` assets, because
-you can use Dartium while you're developing your app.
-
-## Specifying transformers {#specifying-transformers}
-
-To tell pub to apply a transformer to your package's assets, specify the
-transformer, as well as the package that contains the transformer, in your
-package's `pubspec.yaml` file. In the following pubspec, the bold lines
-specify that this package requires the polymer transformer, which is in the
-polymer package (along with the rest of Polymer.dart):
-
-<pre>
-name: myapp
-dependencies:
- <b>polymer: any</b>
-<b>transformers:
-- polymer:
- entry_points: web/index.html</b>
-</pre>
-
-We expect more transformers to be available in the future. You can specify
-multiple transformers, to run either in parallel (if they're independent of
-each other) or in separate phases. To specify that transformers run in
-parallel, use [<code><em>transformer_1</em>, ...,
-<em>transformer_n</em></code>]. If order matters, put the transformers on
-separate lines.
-
-For example, consider three transformers, specified as follows:
-
-{% highlight yaml %}
-transformers:
-- [t1, t2]
-- t3
-{% endhighlight %}
-
-The `t1` and `t2` transformers run first, in parallel. The `t3` transformer
-runs in a separate phase, after `t1` and `t2` are finished, and can see the
-outputs of `t1` and `t2`.
-
-Pub implicitly appends a transformer that converts your Dart code to
-JavaScript, so your code can run in any modern browser.
-
-## Where to put assets {#where-to-put-assets}
-
-If you want a file to be an _asset_&mdash;to either be in or be used to
-generate files in the built version of your package&mdash;then you need to
-put it under one of the following directories:
-
-* `lib`: Dart libraries defining the package's public API. Visible in all
- packages that use this package.
-* `asset`: Other public files. Visible in all packages that use this
- package.
-* `web`: A web app's static content plus its main Dart file (the one that
- defines `main()`). Visible _only_ to this package.
-
-The following picture shows how you might structure your app's source assets,
-with your main Dart file under `web` and additional Dart files under `lib`.
-
-<pre>
-<em>app</em>/
- lib/
- *.dart
- packages/
- pck/
- lib/
- *.dart
- *.js
- asset/
- *.png
- *.html
- ...
- web/
- <em>app</em>.dart
- *.html
- *.css
- *.png
- ...
-</pre>
-
-After transformation, `pub build` places generated assets under a directory
-named `build`, which we'll call the _build root_. The build root has two
-special subdirectories: `packages` and `assets`. The dev server simulates this
-hierarchy without generating files.
-
-The following figure shows the source assets above, plus the generated assets
-produced by `pub build` if the only transformer is dart2js. In this example,
-all the source files have corresponding generated files, and all the Dart
-files have been compiled into a single JavaScript file.
-
-![under the build directory are assets/ and packages/ directories, plus a bunch of files derived from the web/ directory: app.dart.js, *.html, *.css, *.png, ...](/img/input-and-output-assets.png)
-
-
-## How to refer to assets
-
-Here's how source asset locations correlate to generated asset locations,
-for untransformed files:
-
-<table>
- <tr>
- <th> Source asset location </th>
- <th> Generated asset location<br>(under the build root) </th>
- </tr>
- <tr>
- <td> <code>.../<em>&lt;your_pkg></em>/web/<em>&lt;path></em></code> </td>
- <td> <code>/<em>&lt;path></em></code> </td>
- </tr>
- <tr>
- <td> <code>.../<em>&lt;pkg_name></em>/asset/<em>&lt;path></em></code> </td>
- <td> <code>/assets/<em>&lt;pkg_name></em>/<em>&lt;path></em></code> </td>
- </tr>
- <tr>
- <td> <code>.../<em>&lt;pkg_name></em>/lib/<em>&lt;path></em></code> </td>
- <td> <code>/packages/<em>&lt;pkg_name></em>/<em>&lt;path></em></code> </td>
- </tr>
-</table>
-
-For example, consider a helloworld app's HTML file, which is in the
-helloworld directory at `web/helloworld.html`. Running `pub build` produces a
-copy at `build/helloworld.html`. In the dev server, you can get the HTML file
-contents by using the URL `http://localhost:8080/helloworld.html`.
-
-Transformers might change any part of <em>&lt;path></em>, especially the
-filename, but they can't change the directory structure above
-<em>&lt;path></em>.
-
-[assets]: glossary.html#asset
-[transformers]: glossary.html#transformer
View
281 app/doc/dependencies.markdown
@@ -1,281 +0,0 @@
----
-title: "Dependencies"
----
-
-1. [Sources](#sources)
- 1. [Hosted packages](#hosted-packages)
- 1. [Git packages](#git-packages)
- 1. [Path packages](#path-packages)
-1. [Version constraints](#version-constraints)
-1. [Dev dependencies](#dev-dependencies)
-{:.toc}
-
-Dependencies are one of pub's core concepts. A dependency is another package
-that your package needs in order to work. Dependencies are specified in your
-[pubspec](pubspec.html). You only list
-[immediate dependencies](glossary.html#immediate-dependency)&mdash;the stuff
-your package uses directly. Pub handles
-[transitive dependencies](glossary.html#transitive-dependency) for you.
-
-For each dependency, you specify the *name* of the package you depend on. For
-[library packages](glossary.html#library-package), you specify the *range of
-versions* of that package that you allow. You may also specify the
-[*source*](glossary.html#source) which tells pub how the package can be located,
-and any additional *description* that the source needs to find the package.
-
-There are two different ways to specify dependencies based on what data you want
-to provide. The shortest way is to just specify a name:
-
-{% highlight yaml %}
-dependencies:
- transmogrify:
-{% endhighlight %}
-
-This creates a dependency on `transmogrify`that allows any version, and looks
-it up using the default source, which is this site itself. To limit the
-dependency to a range of versions, you can provide a *version constraint*:
-
-{% highlight yaml %}
-dependencies:
- transmogrify: '>=1.0.0 <2.0.0'
-{% endhighlight %}
-
-This creates a dependency on `transmogrify` using the default source and
-allowing any version from `1.0.0` to `2.0.0` (but not including `2.0.0`). See
-[below](#version-constraints) for details on the version constraint syntax.
-
-If you want to specify a source, the syntax looks a bit different:
-
-{% highlight yaml %}
-dependencies:
- transmogrify:
- hosted:
- name: transmogrify
- url: http://some-package-server.com
-{% endhighlight %}
-
-This depends on the `transmogrify` package using the `hosted` source.
-Everything under the source key (here, just a map with a `url:` key) is the
-description that gets passed to the source. Each source has its own description
-format, detailed below.
-
-You can also provide a version constraint:
-
-{% highlight yaml %}
-dependencies:
- transmogrify:
- hosted:
- name: transmogrify
- url: http://some-package-server.com
- version: '>=1.0.0 <2.0.0'
-{% endhighlight %}
-
-This long form is used when you don't use the default source or when you have a
-complex description you need to specify. But in most cases, you'll just use the
-simple "name: version" form.
-
-## Dependency sources
-
-Here are the different sources pub can use to locate packages, and the
-descriptions they allow:
-
-### Hosted packages
-
-A *hosted* package is one that can be downloaded from this site (or another
-HTTP server that speaks the same API). Most of your dependencies will be of
-this form. They look like this:
-
-{% highlight yaml %}
-dependencies:
- transmogrify: '>=0.4.0 <1.0.0'
-{% endhighlight %}
-
-Here, you're saying your package depends on a hosted package named
-"transmogrify" and you'll work with any version from 0.4.0 to 1.0.0 (but not
-1.0.0 itself).
-
-If you want to use your own package server, you can use a description that
-specifies its URL:
-
-{% highlight yaml %}
-dependencies:
- transmogrify:
- hosted:
- name: transmogrify
- url: http://your-package-server.com
- version: '>=0.4.0 <1.0.0'
-{% endhighlight %}
-
-### Git packages
-
-Sometimes you live on the bleeding edge and you need to use stuff that hasn't
-been formally released yet. Maybe your package itself is still in development
-and is using other packages that are being developed at the same time. To make
-that easier, you can depend directly on a package stored in a [Git][]
-repository.
-
-[git]: http://git-scm.com/
-
-{% highlight yaml %}
-dependencies:
- kittens:
- git: git://github.com/munificent/kittens.git
-{% endhighlight %}
-
-The `git` here says this package is found using Git, and the URL after that is
-the Git URL that can be used to clone the package. Pub assumes that the package
-is in the root of the git repository.
-
-If you want to depend on a specific commit, branch, or tag, you can also
-provide a `ref` argument:
-
-{% highlight yaml %}
-dependencies:
- kittens:
- git:
- url: git://github.com/munificent/kittens.git
- ref: some-branch
-{% endhighlight %}
-
-The ref can be anything that Git allows to [identify a commit][commit].
-
-[commit]: http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#naming-commits
-
-### Path packages
-
-Sometimes you find yourself working on multiple related packages at the same
-time. Maybe you are hacking on a framework while building an app that uses it.
-In those cases, during development you really want to depend on the "live"
-version of that package on your local file system. That way changes in one
-package are instantly picked up by the one that depends on it.
-
-To handle that, pub supports *path dependencies*.
-
-{% highlight yaml %}
-dependencies:
- transmogrify:
- path: /Users/me/transmogrify
-{% endhighlight %}
-
-This says the root directory for `transmogrify` is `/Users/me/transmogrify`.
-When you use this, pub will generate a symlink directly to the `lib` directory
-of the referenced package directory. Any changes you make to the dependent
-package will be seen immediately. You don't need to run pub every time you
-change the dependent package.
-
-Relative paths are allowed and are considered relative to the directory
-containing your pubspec.
-
-Path dependencies are useful for local development, but do not play nice with
-sharing code with the outside world. It's not like everyone can get to
-your file system, after all. Because of this, you cannot upload a package to
-[pub.dartlang.org][pubsite] if it has any path dependencies in its pubspec.
-
-Instead, the typical workflow is:
-
-1. Edit your pubspec locally to use a path dependency.
-2. Hack on the main package and the package it depends on.
-3. Once they're both in a happy place, publish the dependent package.
-4. Then change your pubspec to point to the now hosted version of its dependent.
-5. Now you can publish your main package too if you want.
-
-## Version constraints
-
-If your package is an application, you don't usually need to specify [version
-constraints](glossary.html#version-constraint) for your dependencies. You will
-typically want to use the latest versions of the dependencies when you first
-create your app. Then you'll create and check in a
-[lockfile](glossary.html#lockfile) that pins your dependencies to those specific
-versions. Specifying version constraints in your pubspec then is usually
-redundant (though you can do it if you want).
-
-For a [library package](glossary.html#library-package) that you want users to
-reuse, though, it is important to specify version constraints. That lets people
-using your package know which versions of its dependencies they can rely on to
-be compatible with your library. Your goal is to allow a range of versions as
-wide as possible to give your users flexibility. But it should be narrow enough
-to exclude versions that you know don't work or haven't been tested.
-
-The Dart community uses [semantic versioning][], which helps you know which
-versions should work. If you know that your package works fine with `1.2.3` of
-some dependency, then semantic versioning tells you that it should work (at
-least) up to `2.0.0`.
-
-A version constraint is a series of:
-
-<dl class="dl-horizontal">
- <dt><code>any</code></dt>
- <dd>The string "any" allows any version. This is equivalent to an empty
- version constraint, but is more explicit.</dd>
-
- <dt><code>1.2.3</code></dt>
- <dd>A concrete version number pins the dependency to only allow that
- <em>exact</em> version. Avoid using this when you can because it can cause
- version lock for your users and make it hard for them to use your package
- along with other packages that also depend on it.</dd>
-
- <dt><code>&gt;=1.2.3</code></dt>
- <dd>Allows the given version or any greater one. You'll typically use this.
- </dd>
-
- <dt><code>&gt;1.2.3</code></dt>
- <dd>Allows any version greater than the specified one but <em>not</em> that
- version itself.</dd>
-
- <dt><code>&lt;=1.2.3</code></dt>
- <dd>Allows any version lower than or equal to the specified one. You
- <em>won't</em> typically use this.</dd>
-
- <dt><code>&lt;1.2.3</code></dt>
- <dd>Allows any version lower than the specified one but <em>not</em> that
- version itself. This is what you'll usually use because it lets you specify
- the upper version that you know does <em>not</em> work with your package
- (because it's the first version to introduce some breaking change).</dd>
-</dl>
-
-You can specify version parts as you want, and their ranges will be intersected
-together. For example, `>=1.2.3 <2.0.0` allows any version from `1.2.3` to
-`2.0.0` excluding `2.0.0` itself.
-
-<aside class="alert alert-warning">
-
-Note that <code>&gt;</code> is also valid YAML syntax so you will want to quote
-the version string (like <code>'&lt;=1.2.3 &gt;2.0.0'</code>) if the version
-constraint starts with that.
-
-</aside>
-
-## Dev dependencies
-
-Pub supports two flavors of dependencies: regular dependencies and *dev
-dependencies.* Dev dependencies differ from regular dependencies in that *dev
-dependencies of packages you depend on are ignored*. That's a mouthful, so
-here's a motivating example:
-
-Say the `transmogrify` package uses the `unittest` package in its tests and only
-in its tests. If someone just wants to use `transmogrify`&mdash;import its
-libraries&mdash;it doesn't actually need `unittest`. In this case, it specifies
-`unittest` as a dev dependency. Its pubspec will have something like:
-
-{% highlight yaml %}
-dev_dependencies:
- unittest: '>=0.5.0'
-{% endhighlight %}
-
-Pub gets every package your package package depends on, and everything *those*
-packages depend on, transitively. It also gets your package's dev dependencies,
-but it *ignores* the dev dependencies of any dependent packages. Pub only gets
-*your* package's dev dependencies. So when your package depends on
-`transmogrify` it will get `transmogrify` but not `unittest`.
-
-The rule for deciding between a regular or dev dependency is pretty simple. If
-the dependency is imported from something in your `lib` directory, it needs to
-be a regular dependency. If it's only imported from `test`, `example`, etc. it
-can and should be a dev dependency.
-
-Using dev dependencies makes dependency graphs smaller. That makes pub run
-faster, and makes it easier to find a set of package versions that satisfy all
-constraints. Use them when you can and your users will thank you.
-
-[pubsite]: http://pub.dartlang.org
-[semantic versioning]: http://semver.org/
View
137 app/doc/faq.markdown
@@ -1,137 +0,0 @@
----
-title: "Frequently Asked Questions"
----
-
-### What are pub's system requirements?
-
-Pub runs on any platform that supports the Dart VM. That basically means
-relatively recent versions of Mac, Linux and Windows.
-
-However, there are a couple of limitations on Windows:
-
-* Windows XP is not supported.
-* FAT32 file systems are not supported.
-* Packages cannot be stored on a different drive than your user directory.
-* Packages cannot be stored on network shares.
-
-Pub relies on junction points for core functionality, and those aren't available
-on the above. We realize these limitations are painful and we're hoping to
-address the root cause but it will take a while to get there.
-
-### What are all the "packages" directories for?
-
-After you run pub, you'll notice that your package has little `packages`
-directories sprinkled all over it. These are needed to make "package:" imports
-work. When your code has an import with the "package" scheme, a Dart
-implementation like the VM or dart2js translates that to a path or URL using a
-simple rewriting rule:
-
- 1. Take the URI of your application's [entrypoint](glossary.dart#entrypoint).
- 2. Strip off the trailing file name.
- 3. Append "/packages/" followed by the rest of the import URL.
-
-For example, if you app's entrypoint is `/dev/myapp/web/main.dart` then:
-
-{% highlight dart %}
-import 'package:unittest/unittest.dart';
-{% endhighlight %}
-
-Magically turns into:
-
-{% highlight dart %}
-import '/dev/myapp/web/packages/unittest/unittest.dart';
-{% endhighlight %}
-
-Then Dart loads that as normal. This behavior is a [specified][spec] part of
-the Dart language. The example only works if you have a directory named
-`packages` inside your `web` directory and that directory in turn contains the
-packages that your app uses.
-
-[spec]: http://www.dartlang.org/docs/spec/
-
-Pub creates these directories for you. The main one it creates is in the root
-of your package. Inside that, it creates symlinks pointing to the `lib`
-directories of each package your app [depends][] on. (The dependencies
-themselves will usually live in your [system cache][].)
-
-[depends]: http://glossary.html#dependency
-[system cache]: http://glossary.html#system-cache
-
-After creating the main `packages` directory in your package's root, pub then
-creates secondary ones in every [directory in your package where a Dart
-entrypoint may appear](glossary.html#entrypoint-directory). Currently that's
-`benchmark`, `bin`, `example`, `test`, `tool`, and `web`.
-
-Pub also creates `packages` symlinks in *subdirectories* of any of those that
-point back to the main one. Since you may have entrypoints under, for example,
-`web/admin/controllers/`, pub makes sure there is always a nearby `packages`
-directory. Otherwise the imports won't work.
-
-### I found a bug in pub. How do I report it?
-
-We use the main [Dart bug tracker][]. Feel free to file a ticket. When you do,
-please include:
-
-[dart bug tracker]: https://code.google.com/p/dart/issues/list
-
-* Your platform (Windows, Mac, Linux, etc.).
-* The version you are running. (Run `pub version`.)
-* If possible, include a log by running `pub --verbose <your command>`.
-
-### How do I delete a package?
-
-Once a package is published, you're strongly discouraged from deleting it.
-After all, some user could already be depending on it! If you accidentally
-include your password or something similarly secret in the package,
-[file an issue][delete-request] and the Pub authors will take down your
-package. You'll need to use a different version when you re-upload it.
-
-[delete-request]: http://code.google.com/p/dart/issues/entry?summary=Request%20to%20delete%20package%20from%20pub&status=Triaged&labels=Type-Task,Priority-Medium,Area-Pub,Pub-DeleteRequest
-
-### I get a timeout when I run pub. What do I do?
-
-The [pub package server][] is hosted on [App Engine][]. We've seen a few times
-where App Engine has run slowly for us and other users, leading to some
-timeouts. If this happens, send us a note on the [mailing list][] and we'll
-look into it. Usually it resolves itself in a few hours.
-
-[pub package server]: http://pub.dartlang.org
-[app engine]: https://appengine.google.com
-[mailing list]: https://groups.google.com/a/dartlang.org/forum/?fromgroups#!forum/misc
-
-### Why doesn't pub do ___?
-
-Probably because we haven't implemented yet. Pub is still under active
-development. If there are features you would like to see, go ahead and
-[file a ticket][dart bug tracker]. Please search and make sure it hasn't
-already been requested yet. If it has, star it so we know what things are
-important to users.
-
-Also, patches are more than welcome! Pub is [open source][] and we love outside
-contributions. Both the [client][] and [server][] are well-tested,
-well-documented, and, we hope, easy to contribute to.
-
-[open source]: https://code.google.com/p/dart/wiki/GettingTheSource?tm=4
-[client]: https://code.google.com/p/dart/source/browse/#svn%2Fbranches%2Fbleeding_edge%2Fdart%2Fsdk%2Flib%2F_internal%2Fpub
-[server]: https://github.com/dart-lang/pub-dartlang
-
-### What is the roadmap for pub?
-
-We don't generally make public roadmaps for pub. The Dart project is very fluid
-and priorities and schedules change very frequently. If we make promises for
-the future, we are likely to end up disappointing users when plans change.
-
-You can usually get a picture for what we are working on now by seeing which
-[bugs we have started][started].
-
-[started]: https://code.google.com/p/dart/issues/list?can=2&q=Area%3DPub+status%3AStarted+&colspec=ID+Type+Status+Priority+Area+Milestone+Owner+Summary&cells=tiles
-
-### How do I report abuse of pub.dartlang.org?
-
-Please contact us at [pub-abuse@dartlang.org][abuse] to discuss the situation.
-
-[abuse]: mailto:pub-abuse@dartlang.org
-
-### I still have questions. What should I do?
-
-Send an email to the main Dart [mailing list][] and we'll see it.
View
213 app/doc/glossary.markdown
@@ -1,213 +0,0 @@
----
-title: "Glossary"
----
-
-### Application package
-
-A package that is not intended to be used as a library. Application packages may
-have [dependencies](#dependency) on other packages, but are never depended on
-themselves. They are usually meant to be run directly, either on the command
-line or in a browser. The opposite of an application package is a [library
-package](#library-package).
-
-Application packages should check their [lockfiles](#lockfile) into source
-control, so that everyone working on the application and every location the
-application is deployed has a consistent set of dependencies. Because their
-dependencies are constrained by the lockfile, application packages usually
-specify `any` for their dependencies' [version
-constraints](#version-constraint).
-
-### Asset
-
-<div class="learn-more">
- <a href="/doc/assets-and-transformers.html">
- Learn more about assets &rarr;
- </a>
-</div>
-
-A resource&mdash;Dart, HTML, JavaScript, CSS, image, or anything
-else&mdash;intended to be part of a deployed package. The package can be a web
-app, a package used by a web app, or any other package that benefits from a
-build step. Tools such as [`pub serve`](pub-serve.html) and [`pub build`](pub-
-build.html) take _source_ assets (such as an HTML file, a CSS file, and
-several Dart files) and produce _generated_ assets (such as the same HTML and
-CSS files, plus a single JavaScript file).
-
-Assets fall into four groups, with some overlap:
-
-* Source asset: An actual, authored file on disk that `pub build` and
- `pub serve` can find and use.
-* Generated asset: An asset (possibly the output of a
- [transformer](#transformer)) that's either served by `pub serve` or saved
- to disk by `pub build`.
-* Input asset: An asset that is the input to a transformer. An input asset
- might be a source asset, or it might be the output of a transformer in a
- previous phase.
-* Output asset: An asset that is created by a transformer. An output asset
- might be a generated asset, or it might be the input to a transformer in a
- later phase.
-
-### Dependency
-
-Another package that your package relies on. If your package wants to import
-code from some other package, that package must be a dependency. Dependencies
-are specified in your package's [pubspec](pubspec.html) and described
-[here](dependencies.html).
-
-### Entrypoint
-
-"Entrypoint" is used to mean two things. In the general context of Dart, it is
-a Dart library that is directly invoked by a Dart implementation. When you
-reference a Dart library in a `<script>` tag or pass it as a command line
-argument to the standalone Dart VM, that library is the entrypoint. In other
-words, it's usually the `.dart` file that contains `main()`.
-
-In the context of pub, an "entrypoint package" or "root package" is the root
-of a dependency graph. It will usually be an application. When you run your app,
-it's the entrypoint package. Every other package it depends on will not be an
-entrypoint in that context.
-
-A package can be an entrypoint in some contexts and not in others. Lets say your
-app uses a library package A. When you run your app, A is not the entrypoint
-package. However, if you go over to A and execute its unit tests, in that
-context, it *is* the entrypoint since your app isn't involved.
-
-### Entrypoint directory
-
-A directory inside your package that is allowed to contain
-[Dart entrypoints](#entrypoint). Pub will ensure all of these directories get
-a "packages" directory, which is needed for "package:" imports to work.
-
-Pub has a whitelist of these directories: `benchmark`, `bin`, `example`,
-`test`, `tool`, and `web`. Any subdirectories of those (except `bin`) may also
-contain entrypoints.
-
-### Immediate dependency
-
-A [dependency](#dependency) that your package directly uses itself. The
-dependencies you list in your pubspec are your package's immediate dependencies.
-All other dependencies are [transitive dependencies](#transitive-dependency).
-
-### Library package
-
-A package that other packages will depend on. Library packages may have
-[dependencies](#dependency) on other packages *and* may be dependencies
-themselves. They may also include scripts that will be run directly. The
-opposite of a library package is an [application package](#application-package).
-
-Library packages should not check their [lockfile](#lockfile) into source
-control, since they should support a range of dependency versions. Their
-[immediate dependencies](#immediate-dependency)' [version
-constraints](#version-constraints) should be as wide as possible while still
-ensuring that the dependencies will be compatible with the versions that were
-tested against.
-
-Since [semantic versioning](http://semver.org) requires that libraries increment
-their major version numbers for any backwards incompatible changes, library
-packages will usually require their dependencies' versions to be greater than or
-equal to the versions that were tested and less than the next major version. So
-if your library depended on the (fictional) `transmogrify` package and you
-tested it at version 1.2.1, your version constraint would be `">=1.2.1 <2.0.0"`.
-
-### Lockfile
-
-A file named `pubspec.lock` that specifies the concrete versions and other
-identifying information for every immediate and transitive dependency a package
-relies on.
-
-Unlike the pubspec, which only lists immediate dependencies and allows version
-ranges, the lock file comprehensively pins down the entire dependency graph to
-specific versions of packages. A lockfile ensures that you can recreate the
-exact configuration of packages used by an application.
-
-The lockfile is generated automatically for you by pub when you run
-[`pub get`](pub-get.html) or [`pub upgrade`](pub-upgrade.html). If your
-package is an application package, you will typically check this into source
-control. For library packages, you usually won't.
-
-### SDK constraint
-
-The declared versions of the Dart SDK itself that a package declares that it
-supports. An SDK constraint is specified using normal
-[version constraint](#version-constraint) syntax, but in a special "environment"
-section [in the pubspec](pubspec.html#sdk-constraints).
-
-### Source
-
-A kind of place that pub can get packages from. A source isn't a specific place
-like pub.dartlang.org or some specific Git URL. Each source describes a general
-procedure for accessing a package in some way. For example, "git" is one source.
-The git source knows how to download packages given a Git URL. There are a few
-different [supported sources](dependencies.html#sources).
-
-### System cache
-
-When pub gets a remote package, it downloads it into a single "system cache"
-directory maintained by pub. When it generates a "packages" directory for a
-package, that only contains symlinks to the real packages in the system cache.
-On Mac and Linux, this directory defaults to `~/.pub-cache`. On Windows, it
-goes in `AppData\Roaming\Pub\Cache`.
-
-This means you only have to download a given version of a package once and can
-then reuse it in as many packages as you would like. It also means you can
-delete and regenerate your "packages" directory without having to access the
-network.
-
-### Transformer
-
-<div class="learn-more">
- <a href="/doc/assets-and-transformers.html">
- Learn more about transformers &rarr;
- </a>
-</div>
-
-A transformer is a Dart object that converts input [assets](#asset) (such as
-Dart files or Polymer-formatted HTML) into output assets (such as JavaScript
-and HTML). The [`pub build`](pub-build.html) command puts the generated assets
-into files. The [`pub serve`](pub-serve.html) command, on the other hand,
-doesn't produce files; its generated assets are served directly by the dev
-server.
-
-### Transitive dependency
-
-A dependency that your package indirectly uses because one of its dependencies
-requires it. If your package depends on A, which in turn depends on B which
-depends on C, then A is an [immediate dependency](#immediate-dependency) and B
-and C are transitive ones.
-
-### Uploader
-
-An uploader of a package is someone who has administrative permissions
-for that package. They can not only upload new versions of a package,
-but also [add and remove other uploaders](pub-uploader.html) for that
-package. The uploader of a package is often, but not necessarily, the
-same as the [author](pubspec.html#authorauthors) of a package.
-
-Anyone uploading a new package automatically becomes an uploader for
-that package. Otherwise, to become an uploader, you need to contact an
-existing uploader and ask them to add you as another uploader.
-
-### Version constraint
-
-<div class="learn-more">
- <a href="/doc/dependencies.html#version-constraints">
- Learn more about version constaints &rarr;
- </a>
-</div>
-
-A constraint placed on each [dependency](#dependency) of a package that
-specifies which versions of that dependency the package is expected to work
-with. This can be a single version (e.g. `0.3.0`), a range of versions (e.g.
-`">=1.2.1 <2.0.0"`), or `any` (or just empty) to specify that any version is
-allowed.
-
-<div class="learn-more">
- <a href="/doc/versioning.html">
- Learn about pub's versioning philosophy &rarr;
- </a>
-</div>
-
-[Library packages](#library-package) should always specify version constraints
-for all of their dependencies, but [application packages](#application-package)
-should usually allow any version of their dependencies, since they use the
-[lockfile](#lockfile) to manage their dependency versions.
View
296 app/doc/index.markdown
@@ -1,296 +0,0 @@
----
-title: "Getting Started"
----
-
-1. [Installing and configuring pub](#installing-and-configuring-pub)
-1. [Creating a package](#creating-a-package)
-1. [Adding a dependency](#adding-a-dependency)
-1. [Getting dependencies](#getting-dependencies)
-1. [Importing code from a dependency](#importing-code-from-a-dependency)
-1. [Upgrading a dependency](#upgrading-a-dependency)
-1. [Publishing a package](#publishing-a-package)
-{:.toc}
-
-*Pub* is a package manager for Dart. It helps you reuse existing Dart code
-and bundle your Dart apps and libraries so that you can reuse and share them
-with other people. Pub handles versioning and dependency management so that you
-can ensure that your app runs on other machines exactly the same as it does on
-yours.
-
-To **find** a package that's on pub.dartlang.org,
-use the Search box at the top right of this page.
-
-To **use** a package that's on pub.dartlang.org:
-
-1. Create a `pubspec.yaml` file
- (if one doesn't already exist)
- and list the package as dependency.
- For example, to use the [web_ui](/packages/web_ui) package
- in an app, put this in a top-level file named `pubspec.yaml`:
-
- name: my_app
- dependencies:
- web_ui: any
-
-1. Run `pub get`, either on the command line
- or through the Dart Editor menu: Tools > Pub Get.
-
-1. Import one or more libraries from the package:
-
- import 'package:web_ui/web_ui.dart';
-
-For details and pointers to more documentation, read on.
-
-## Installing and configuring pub
-
-Pub is in the [Dart SDK](http://www.dartlang.org/docs/sdk/),
-which you can download by itself or as part of
-[Dart Editor](http://www.dartlang.org/docs/editor/).
-You can use pub through
-[Dart Editor](http://www.dartlang.org/docs/editor/), or through the
-`pub` command-line app, which lives inside the `bin` directory of the Dart SDK.
-
-To use pub and other tools on the command line,
-you might want to add the SDK's `bin` directory to your system path.
-For example, on Mac and Linux:
-
- export PATH=$PATH:<path to sdk>/bin
-
-For Windows, here's an equivalent in PowerShell:
-
- [Environment]::SetEnvironmentVariable("PATH", "$env:PATH;<path to sdk>\bin", "User")
-
-In the examples above, `<path to sdk>` is the absolute path
-to the main directory of the SDK. For example,
-if you install Dart Editor in
-`/home/me/dart`, then add this to your PATH:
-
- /home/me/dart/dart-sdk/bin
-
-On Windows, you can also set the system PATH environment variable through the
-Control Panel. A quick
-[search](https://www.google.com/search?q=windows+set+environment+variable)
-should find the instructions for your version of Windows.
-
-## Creating a package
-
-<div class="learn-more">
- <a href="/doc/package-layout.html">
- Learn more about packages &rarr;
- </a>
-</div>
-
-A **package** in pub is a directory that contains Dart code and any other stuff
-that goes along with it like resources, tests, and docs. Frameworks and
-reusable libraries are obviously packages, but applications are too. If your
-app wants to use pub packages, it needs to be a package too.
-
-While everything is a package in pub, there are two flavors of packages that are
-used slightly differently in practice. A [**library
-package**](glossary.html#library-package) is a package that is intended to be
-reused by other packages. It will usually have code that other packages import,
-and it will likely be hosted somewhere that people can get to. An [**application
-package**](glossary.html#application-package) only *consumes* packages but
-doesn't itself get reused. In other words, library packages will be used as
-dependencies, but application packages won't.
-
-In most cases, there's no difference between the two and we'll just say
-"package". In the few places where it does matter, we'll specify "library
-package" or "application package".
-
-<div class="learn-more">
- <a href="/doc/pubspec.html">
- Learn more about pubspecs &rarr;
- </a>
-</div>
-
-To turn your app into an application package so it can use other packages, you
-just need to give it a **pubspec**. This file is written using the
-[YAML language](http://yaml.org) and is named `pubspec.yaml`. The simplest
-possible pubspec just contains the name of the package. Save the pubspec file as
-`pubspec.yaml` in the root directory of your app.
-
-Behold, the simplest possible `pubspec.yaml`:
-
-{% highlight yaml %}
-name: my_app
-{% endhighlight %}
-
-Now `my_app` is a pub package!
-
-## Adding a dependency
-
-<div class="learn-more">
- <a href="/doc/dependencies.html">
- Learn more about dependencies &rarr;
- </a>
-</div>
-
-One of pub's main jobs is managing **dependencies**. A dependency is just
-another package that your package relies on. If your app is using some
-transformation library called "transmogrify", then your app package will depend
-on the `transmogrify` package.
-
-You specify your package's dependencies in the pubspec file immediately after
-your package name. For example:
-
-{% highlight yaml %}
-name: my_app
-dependencies:
- transmogrify:
-{% endhighlight %}
-
-Here, we are declaring a dependency on the (fictional) `transmogrify` package.
-
-## Getting dependencies
-
-<div class="learn-more">
- <a href="/doc/pub-get.html">
- Learn more about <tt>pub get</tt> &rarr;
- </a>
-</div>
-
-Once you've declared a dependency, you then tell pub to get it for you. If
-you're using the Editor, select "Pub Get" from the "Tools" menu. If you're
-rocking the command line, do:
-
- $ cd path/to/your_app
- $ pub get
-
-<aside class="alert alert-warning">
-Today, this command must be run from the directory containing
-<tt>pubspec.yaml</tt>. In the future, you will be able to run it from any
-sub-directory of the package.
-</aside>
-
-When you do this, pub will create a `packages` directory in the same directory
-as `pubspec.yaml`. In there, it will place each package that your package
-depends on (these are called your **immediate dependencies**). It will also
-look at all of those packages and get everything *they* depend on, recursively
-(these are your **transitive dependencies**).
-
-When this is done, you will have a `packages` directory that contains every
-single package your program needs in order to run.
-
-## Importing code from a dependency
-
-Now that you have a dependency wired up, you want to be able to use code from
-it. To access a library in a another package, you will import it using the
-`package:` scheme:
-
-{% highlight dart %}
-import 'package:transmogrify/transmogrify.dart';
-{% endhighlight %}
-
-This looks inside the `transmogrify` package for a top-level file named
-`transmogrify.dart`. Most packages just define a single entrypoint whose name
-is the same as the name of the package. Check the documentation for the package
-to see if it exposes anything different for you to import.
-
-<aside class="alert alert-info">
-This works by looking inside the generated <tt>packages</tt> directory. If you
-get an error, the directory may be out of date. Fix it by running
-<tt>pub get</tt> whenever you change your pubspec.
-</aside>
-
-You can also use this style to import libraries from within your own package.
-For example, let's say your package is laid out like:
-
- transmogrify/
- lib/
- transmogrify.dart
- parser.dart
- test/
- parser/
- parser_test.dart
-
-The `parser_test` file *could* import `parser.dart` like this:
-
-{% highlight dart %}
-import '../../lib/parser.dart';
-{% endhighlight %}
-
-But that's a pretty nasty relative path. If `parser_test.dart` is ever moved
-up or down a directory, that path will break and you'll have to fix the code.
-Instead, you can do:
-
-{% highlight dart %}
-import 'package:transmogrify/parser.dart';
-{% endhighlight %}
-
-This way, the import can always get to `parser.dart` regardless of where the
-importing file is.
-
-<!-- TODO(rnystrom): Enable this when that doc exists.
-<div class="learn-more">
- <a href="/doc/package-scheme.html">
- Learn more about the <tt>package:</tt> scheme
- <i class="icon-hand-right icon-white">&nbsp;</i>
- </a>
-</div>
--->
-
-## Upgrading a dependency
-
-<div class="learn-more">
- <a href="/doc/pub-upgrade.html">
- Learn more about <tt>pub upgrade</tt> &rarr;
- </a>
-</div>
-
-The first time you get a new dependency for your package, pub will download the
-latest version of it that's compatible with your other dependencies. It then
-locks your package to *always* use that version by creating a **lockfile**.
-This is a file named `pubspec.lock` that pub creates and stores next to your
-pubspec. It lists the specific versions of each dependency (immediate and
-transitive) that your package uses.
-
-If this is an application package, you will check this file into source control.
-That way, everyone hacking on your app ensures they are using the same versions
-of all of the packages. This also makes sure you use the same versions of stuff
-when you deploy your app to production.
-
-When you are ready to upgrade your dependencies to the latest versions, do:
-
- $ pub upgrade
-
-This tells pub to regenerate the lockfile using the newest available versions of
-your package's dependencies. If you only want to upgrade a specific dependency,
-you can specify that too:
-
- $ pub upgrade transmogrify
-
-This upgrades `transmogrify` to the latest version but leaves everything else
-the same.
-
-## Publishing a package
-
-<div class="learn-more">
- <a href="/doc/pub-lish.html">
- Learn more about <tt>pub publish</tt> &rarr;
- </a>
-</div>
-
-Pub isn't just for using other people's packages. It also allows you to share
-your packages with the world. Once you've written some useful code and you want
-everyone else to be able to use it, just run:
-
- $ pub publish
-
-Pub will check to make sure that your package follows the [pubspec
-format](pubspec.html) and [package layout conventions](package-layout.html), and
-then upload your package to [pub.dartlang.org](http://pub.dartlang.org). Then
-any Pub user will be able to download it or depend on it in their pubspecs. For
-example, if you just published version 1.0.0 of a package named `transmogrify`,
-then they can write:
-
-{% highlight yaml %}
-dependencies:
- transmogrify: ">= 1.0.0 < 2.0.0"
-{% endhighlight %}
-
-Keep in mind that publishing is forever. As soon as you publish your awesome
-package, users will be able to depend on it. Once they start doing that,
-removing the package would break theirs. To avoid that, pub strongly discourages
-deleting packages. You can always upload new versions of your package, but old
-ones will continue to be available for users that aren't ready to upgrade yet.
View
362 app/doc/package-layout.markdown
@@ -1,362 +0,0 @@
----
-title: "Package layout conventions"
----
-
-1. [The basics](#the-basics)
-1. [README](#readme)
-1. [Public libraries](#public-libraries)
-1. [Public assets](#public-assets)
-1. [Implementation files](#implementation-files)
-1. [Web files](#web-files)
-1. [Command-line apps](#command-line-apps)
-1. [Tests and benchmarks](#tests-and-benchmarks)
-1. [Documentation](#documentation)
-1. [Examples](#examples)
-1. [Internal tools and scripts](#internal-tools-and-scripts)
-{:.toc}
-
-Part of a healthy code ecosystem is consistent conventions. When we all do the
-same thing the same way, it makes it easier for us to learn our way around
-each other's work. It also makes it easier to write tools that can automatically
-do stuff for us.
-
-When you build a Pub package, we have a set of conventions we encourage you to
-follow. They describe how you organize the files and directories within your
-package, and how to name things. You don't have to have every single thing
-these guidelines specify. If your package doesn't have binaries, it doesn't
-need a directory for them. But if it does, you'll make everyone's life easier
-if you call it `bin`.
-
-To give you a picture of the whole enchilada, here's what a complete package
-(conveniently named `enchilada`) that uses every corner of these guidelines
-would look like:
-
- enchilada/
- pubspec.yaml
- pubspec.lock *
- README.md
- LICENSE
- asset/
- guacamole.css
- benchmark/
- make_lunch.dart
- packages/ **
- bin/
- enchilada
- packages/ **
- doc/
- getting_started.md
- example/
- lunch.dart
- packages/ **
- lib/
- enchilada.dart
- tortilla.dart
- src/
- beans.dart
- queso.dart
- packages/ **
- test/
- enchilada_test.dart
- tortilla_test.dart
- packages/ **
- tool/
- generate_docs.dart
- web/
- index.html
- main.dart
- style.css
-
-\* The `pubspec.lock` will only be in source control if the package is an
-[application package](glossary.html#application-package).
-
-\** The `packages` directories will exist locally after you've run
-`pub get`, but won't be checked into source control.
-
-## The basics
-
- enchilada/
- pubspec.yaml
- pubspec.lock
-
-<div class="learn-more">
- <a href="/doc/pubspec.html">
- Learn more about pubspecs &rarr;
- </a>
-</div>
-
-Every package will have a [**pubspec**](pubspec.html), a file named
-`pubspec.yaml`, in the root directory of the package. That's what *makes* it a
-package.
-
-Once you've run [`pub get`](pub-get.html) or [`pub
-upgrade`](pub-upgrade.html) on the package, you will also have a **lockfile**,
-named `pubspec.lock`. If your package is an [application
-package](glossary.html#application-package), this will be checked into source
-control. Otherwise, it won't be.
-
- enchilada/
- packages/
- ...
-
-Running pub will also generate a `packages` directory. You will *not* check
-this into source control, and you won't need to worry too much about its
-contents. Consider it pub magic, but not scary magic.
-
-The open source community has a few other files that commonly appear at the top
-level of a project: `LICENSE`, `AUTHORS`, etc. If you use any of those, they can
-go in the top level of the package too.
-
-## README
-
- enchilada/
- README.md
-
-One file that's very common in open source is a README file that
-describes the project. This is especially important in pub. When you upload
-to [pub.dartlang.org](/), your README will be shown on the page for your
-package. This is the perfect place to introduce people to your code.
-
-If your README ends in `.md`, `.markdown`, or `.mdown`, it will be parsed as
-[Markdown][] so you can make it as fancy as you like.
-
-[markdown]: http://daringfireball.net/projects/markdown/
-
-## Public libraries
-
- enchilada/
- lib/
- enchilada.dart
- tortilla.dart
-
-Many packages are [*library packages*](glossary.html#library-package): they
-define Dart libraries that other packages can import and use. These public Dart
-library files go inside a directory called `lib`.
-
-Most packages define a single library that users can import. In that case,
-its name should usually be the same as the name of the package, like
-`enchilada.dart` in the example here. But you can also define other libraries
-with whatever names make sense for your package.
-
-When you do, users can import these libraries using the name of the package and
-the library file, like so:
-
-{% highlight dart %}
-import "package:enchilada/enchilada.dart";
-import "package:enchilada/tortilla.dart";
-{% endhighlight %}
-
-If you feel the need to organize your public libraries, you can also create
-subdirectories inside `lib`. If you do that, users will specify that path when
-they import it. Say you have a file hierarchy like this:
-
- enchilada/
- lib/
- some/
- path/
- olives.dart
-
-Users will import `olives.dart` like:
-
-{% highlight dart %}
-import "package:enchilada/some/path/olives.dart";
-{% endhighlight %}
-
-Note that only *libraries* should be in `lib`. *Entrypoints*&mdash;Dart scripts
-with a `main()` function&mdash;cannot go in `lib`. If you place a Dart script
-inside `lib`, you will discover that any `package:` imports it contains don't
-resolve. Instead, your entrypoints should go in the appropriate
-[entrypoint directory](glossary.html#entrypoint-directory).
-
-## Public assets
-
- enchilada/
- asset/
- guacamole.css
-
-While most library packages exist to let you reuse Dart code, you can also
-reuse other kinds of content. For example, a package for something like
-[Bootstrap](http://getbootstrap.com/) might include a number of CSS files for
-consumers of the package to use.
-
-These go in a top-level directory named `asset`. You can put any kind of file
-in there and organize it with subdirectories however you like. It's effectively
-a `lib` directory for stuff that isn't Dart code.
-
-Users can reference another package's assets using URLs that contain
-`assets/<package>/<path>` where `<package>` is the name of the package
-containing the asset and `<path>` is the relative path to the asset within that
-package's `asset` directory.
-
-<aside class="alert alert-warning">
-
-<p>The mechanics of referencing assets are still being implemented. URLs that
-contain <tt>assets/</tt> are handled by <a href="pub-serve.html"><tt>pub
-serve</tt></a>.</p>
-
-<p>The <a href="pub-build.html"><tt>pub build</tt></a> command also copies
-assets to an <tt>assets</tt> directory, but this will <em>only</em> be in the
-root directory of the output, so you must make sure that your <tt>assets/</tt>
-URL correctly resolves to that directory and not a subdirectory.</p>
-
-<p>We don't currently have a solution for referencing assets in command-line
-Dart applications.</p>
-
-</aside>
-
-Note that `assets` is plural in the URL. This is a bit like the split between
-`lib` and `packages`. The former is the name of the *directory in the package*,
-the latter is the *name you use to reference it*.
-
-For example, let's say your package wanted to use enchilada's `guacamole.css`
-styles. In an HTML file in your package, you can add:
-
-{% highlight html %}
-<link href="assets/enchilada/guacamole.css" rel="stylesheet">
-{% endhighlight %}
-
-When you run your application using [`pub serve`](pub-serve.html), or build it
-to something deployable using [`pub build`](pub-build.html), Pub will copy over
-any referenced assets that your package depends on.
-
-## Implementation files
-
- enchilada/
- lib/
- src/
- beans.dart
- queso.dart
-
-The libraries inside "lib" are publicly visible: other packages are free to
-import them. But much of a package's code is internal implementation libraries
-that should only be imported and used by the package itself. Those go inside a
-subdirectory of `lib` called `src`. You can create subdirectories in there if
-it helps you organize things.
-
-You are free to import libraries that live in `lib/src` from within other Dart
-code in the *same* package (like other libraries in `lib`, scripts in `bin`, and
-tests) but you should never import from another package's `lib/src` directory.
-Those files are not part of the package's public API, and they might change in
-ways that could break your code.
-
-When you use libraries from within your own package, even stuff in `src`, you
-can (and should) still use `"package:"` to import them. This is perfectly
-legit:
-
-{% highlight dart %}
-import "package:enchilada/src/beans.dart";
-{% endhighlight %}
-
-The name you use here (in this case `enchilada`) is the name you specify for
-your package in its [pubspec](pubspec.html).
-
-## Web files
-
- enchilada/
- web/
- index.html
- main.dart
- style.css
-
-Dart is a web language, so many pub packages will be doing web stuff. That
-means HTML, CSS, images, and, heck, probably even some JavaScript. All of that
-goes into your package's `web` directory. You're free to organize the contents
-of that to your heart's content. Go crazy with subdirectories if that makes you
-happy.
-
-Also, and this is important, any Dart web entrypoints (in other words, Dart
-scripts that are referred to in a `<script>` tag) go under `web` and not `lib`.
-That ensures that there is a nearby `packages` directory so that `package:`
-imports can be resolved correctly.
-
-(You may be asking yourself, "Self, where should I put my web-based example
-programs? `example` or `web`?" Put those in `example`.)
-
-## Command-line apps
-
- enchilada/
- bin/
- enchilada
-
-Some packages define programs that can be run directly from the command line.
-These can be shell scripts or any other scripting language, including Dart.
-The `pub` application itself is one example: it's a simple shell script that
-invokes `pub.dart`.
-
-If your package defines stuff like this, put it in a directory named `bin`.
-
-<aside class="alert alert-note">
-
-At some point, pub will support automatically adding that directory to your
-system path so that these scripts can be easily invoked.
-
-</aside>
-
-## Tests and benchmarks
-
- enchilada/
- test/
- enchilada_test.dart
- tortilla_test.dart
-
-Every self-respecting package should have tests. With pub, the convention is
-that these go in a `test` directory (or some directory inside it if you like)
-and have `_test` at the end of their file names.
-
-Typically, these use the [unittest](http://api.dartlang.org/unittest.html)
-package but you can use whatever testing system that gets you excited.
-
- enchilada/
- benchmark/
- make_lunch.dart
-
-Packages that have performance critical code may also include *benchmarks*.
-These test the API not for correctness but for speed (or memory use, or maybe
-other empirical metrics).
-
-## Documentation
-
- enchilada/
- doc/
- getting_started.md
-
-If you've got code and tests, the next piece you need to maximize your karma
-is good documentation. That goes inside a directory named `doc`. We don't
-currently have any guidelines about format or organization within that. Use
-whatever markup format you like and be happy that you're actually writing docs.
-
-This directory should *not* just contain docs generated automatically from your
-source code using
-[dartdoc](http://api.dartlang.org/docs/continuous/dartdoc.html). Since that's
-pulled directly from the code already in the package, putting those docs in
-here would be redundant. Instead, this is for tutorials, guides, and other
-hand-authored documentation *in addition to* generated API references.
-
-## Examples
-
- enchilada/
- example/
- lunch.dart
-
-At this point, you're going for the brass ring. Code, tests, docs, what else
-could your users want? Standalone example programs that use your package, of
-course! Those go inside the `example` directory. If the examples are complex
-and use multiple files, consider making a directory for each example. Otherwise,
-you can place each one right inside `example`.
-
-This is an important place to consider using `package:` to import files from
-your own package. That ensures the example code in your package looks exactly
-like code outside of your package would look.
-
-## Internal tools and scripts
-
- enchilada/
- tool/
- generate_docs.dart
-
-Mature packages often have little helper scripts and programs that people
-run while developing the package itself. Think things like test runners,
-documentation generators, or other bits of automation.
-
-Unlike the scripts in `bin`, these are *not* for external users of the package.
-If you have any of these, place them in a directory called `tool`.
View
51 app/doc/pub-build.markdown
@@ -1,51 +0,0 @@
----
-title: "Command: Build"
----
-
- $ pub build [--mode=<mode>]
-
-Use `pub build` when you're ready to deploy your web app. When you run
-`pub build`, it generates the [assets](glossary.html#asset) for the current
-package and all of its dependencies, putting them into a new directory
-named `build`.
-
-To use `pub build`, just run it in your package's root directory. For example:
-
- $ cd ~/dart/helloworld
- $ pub build
- Building helloworld......
- Built 5 files!
-
-If the build directory already exists, `pub build` deletes it and then creates
-it again.
-
-To generate assets, `pub build` uses
-[transformers](glossary.html#transformer). Any source assets that aren't
-transformed are copied, as is, into the build directory or one of its
-subdirectories. Pub also automatically compiles your Dart application to
-JavaScript using dart2js.
-
-See [Assets and Transformers](assets-and-transformers.html) for information on:
-
-* Where in your package to put assets.
-* What URLs to use when referring to assets.
-* How to use `pubspec.yaml` to specify which transformers run, and in
- what order.
-
-Also see [`pub serve`](pub-serve.html). With `pub serve`, you can run a
-development server that continuously generates and serves assets.
-
-## Options
-
-### `--mode=<mode>`
-
-Specifies a transformation mode. Typical values are "debug" and "release", but
-any word is allowed. Transformers may use this to change how they behave.
-
-If set to "release" pub will generate minified JavaScript using dart2js.
-Otherwise, it generates it unminified. Also, in release mode, Pub will not
-include any source .dart files in the resulting build output since they have
-been compiled to JavaScript. In any other mode, the raw Dart files will be
-included.
-
-If omitted, it defaults to "release".
View
15 app/doc/pub-cache.markdown
@@ -1,15 +0,0 @@
----
-title: "Command: Cache"
----
-
- $ pub cache list
-
-This command lists information about packages currently downloaded into your
-[system cache](glossary.html#system-cache). Currently, it only outputs
-information in JSON form and exists mainly for the Editor's benefit.
-
-<aside class="alert alert-warning">
- Eventually, this command will be more useful for end users. For now, you
- probably just want to ignore it. We may change the format of its output at
- any time.
-</aside>
View
99 app/doc/pub-get.markdown
@@ -1,99 +0,0 @@
----
-title: "Command: Get"
----
-
- $ pub get [--offline]
-
-This command gets all the dependencies listed in the
-[`pubspec.yaml`](pubspec.html) file in the current working directory, as well as
-their [transitive dependencies](glossary.html#transitive-dependency), and places
-them in a `packages` directory located next to the pubspec. For example:
-
- $ pub get
- Got dependencies!
-
-Once the dependencies are acquired, they may be referenced in Dart code. For
-example, if a package depends on `unittest`:
-
-{% highlight dart %}
-import "package:unittest/unittest.dart;
-{% endhighlight %}
-
-When `pub get` gets new dependencies, it writes a
-[lockfile](glossary.html#lockfile) to ensure that future gets will use the
-same versions of those dependencies. Application packages should check in the
-lockfile to source control; this ensures the application will use the exact same
-versions of all dependencies for all developers and when deployed to production.
-Library packages should not check in the lockfile, though, since they're
-expected to work with a range of dependency versions.
-
-If a lockfile already exists, `pub get` uses the versions of dependencies
-locked in it if possible. If a dependency isn't locked, pub will get the
-latest version of that dependency that satisfies all the [version
-constraints](glossary.html#version-constraint). This is the primary difference
-between `pub get` and [`pub upgrade`](pub-upgrade.html), which always tries to
-get the latest versions of all dependencies.
-
-## Getting a new dependency
-
-If a dependency is added to the pubspec and then `pub get` is run, it will
-get the new dependency and any of its transitive dependencies and place them in
-the `packages` directory. However, it won't change the versions of any
-already-acquired dependencies unless that's necessary to get the new
-dependency.
-
-## Removing a dependency
-
-If a dependency is removed from the pubspec and then `pub get` is run, it will
-remove the dependency from the `packages` directory, thus making it
-unavailable for importing. Any transitive dependencies of the removed dependency
-will also be removed, as long as no remaining immediate dependencies also depend
-on them. Removing a dependency will never change the versions of any
-already-acquired dependencies.
-
-## Linked `packages` directories
-
-Every [entrypoint](glossary.html#entrypoint) in a package needs to be next to a
-`packages` directory in order for it to import packages acquired by Pub.
-However, it's not convenient to put every entrypoint at the top level of the
-package alongside the main `packages` directory. You may have example scripts or
-tests that you want to be able to run from subdirectories.
-
-`pub get` solves this issue by creating additional `packages` directories
-that link to the main `packages` directory at the root of your package. It
-assumes your package is laid out according to the [package layout
-guide](package-layout.html), and creates a linked `packages` directory in
-`bin/`, `test/`, and `example/`, as well as their subdirectories.
-
-## The system package cache
-
-Dependencies are not physically stored in the `packages` directory that pub
-creates. Dependencies downloaded over the internet, such as those from Git and
-[pub.dartlang.org](http://pub.dartlang.org), are stored in a system-wide cache
-and linked to from the `packages` directory. This means that if multiple
-packages use the same version of the same dependency, it will only need to be
-downloaded and stored locally once. It also means that it's safe to delete the
-`packages` directory without worrying about re-downloading packages.
-
-By default, the system package cache is located in the `.pub-cache` subdirectory
-of your home directory. However, it may be configured by setting the `PUB_CACHE`
-environment variable before running Pub.
-
-## Getting while offline
-
-If you don't have network access, you can still run `pub get`. Since pub
-downloads packages to a central cache shared by all packages on your system, it
-can often find previous-downloaded packages there without needing to hit the
-network.
-
-However, by default, pub will always try to go online when you get if you
-have any hosted dependencies so that it can see if newer versions of them are
-available. If you don't want it to do that, pass the `--offline` flag when
-running pub. In this mode, it will only look in your local package cache and
-try to find a set of versions that work with your package from what's already
-available.
-
-Keep in mind that pub *will* generate a lockfile after it does this. If the
-only version of some dependency in your cache happens to be old, this will lock
-your app to that version. The next time you are online, you will likely want to
-run [`pub upgrade`](pub-upgrade.html) to upgrade to a later version.
View
91 app/doc/pub-lish.markdown
@@ -1,91 +0,0 @@
----
-title: "Command: Publish"
----
-
- $ pub publish [--dry-run] [--force] [--server <url>]
-
-This command publishes your package on
-[pub.dartlang.org](http://pub.dartlang.org) for anyone to download and depend
-on. For example, if your package is named transmogrify, it will be listed on
-`http://pub.dartlang.org/packages/transmogify`, and users can depend on it in
-their pubspecs and get it via [pub get](pub-get.html) using something
-like:
-
-{% highlight dart %}
-dependencies:
- transmogrify: ">= 1.0.0 < 2.0.0"
-{% endhighlight %}
-
-When publishing a package, it's important to follow the [pubspec
-format](pubspec.html) and [package layout conventions](package-layout.html).
-Some of these are required in order for others to be able to use your package.
-Others are suggestions to help make it easier for users to understand and work
-with your package. In both cases, pub will try to help you by pointing out what
-changes will help make your package play nicer with the Dart ecosystem. There
-are a few additional requirements for uploading a package:
-
-* You must include a license file (named `LICENSE`, `COPYING`, or some
- variation) that contains an [open-source license](http://opensource.org/). We
- recommend the [BSD license](http://opensource.org/licenses/BSD-2-Clause),
- which is used by Dart itself. You must also have the legal right to
- redistribute anything that you upload as part of your package.
-
-* Your package must be less than ten megabytes large after gzip compression. If
- it's too large, consider splitting it into multiple packages, or cutting down
- on the number of included resources or examples.
-
-* Your package should only have hosted dependencies. Git dependencies are
- allowed but strongly discouraged; not everyone using Dart has Git installed,
- and Git dependencies don't support version resolution as well as hosted
- dependencies do.
-
-Be aware that the email address associated with your Google account will be
-displayed on [pub.dartlang.org](http://pub.dartlang.org) along with any packages
-you upload.
-
-## What files are published?
-
-**All files** in your package will be included in the published package, with
-the following exceptions:
-
-* Any `packages` directories.
-* Your package's [lockfile](glossary.html#lockfile).
-* If you're using Git, any files ignored by your `.gitignore` file.
-* If you aren't using Git, all "hidden" files (that is, files whose names begin
- with `.`).
-
-If there are other files you don't want to include, be sure to delete them (or
-add them to `.gitignore`) before running `pub publish`.
-
-To be on the safe side, `pub publish` will list all files it's going to publish
-for you to look over before it actually uploads your package.
-
-## Options
-
-### `--dry-run` or `-n`
-
-With this, pub goes through the validation process but does not actually upload
-the package. This is useful if you want to see if your package meets all of the
-publishing requirements before you're ready to actually go public.
-
-### `--force` or `-f`
-
-With this, pub does not ask for confirmation before publishing. Normally, it
-shows you the package contents and asks for you to confirm the upload.
-
-If there are any errors in your package, it is not uploaded and this exits with
-an error. If there are warnings, it *will* be uploaded. If you want to ensure
-your package has no warnings before uploading, either don't use `--force`, or
-use `--dry-run` first.
-
-### `--server`
-
-If you pass `--server` followed by a URL, it will attempt to publish the
-package to that server. It assumes the server supports the same HTTP API that
-[pub.dartlang.org][pubsite] uses.
-
-This can be useful if you're running your own local package server for testing.
-The main pub server is itself open source and available [here][pub repo].
-
-[pubsite]: http://pub.dartlang.org
-[pub repo]: https://github.com/dart-lang/pub-dartlang
View
65 app/doc/pub-serve.markdown
@@ -1,65 +0,0 @@
----
-title: "Command: Serve"
----
-
- $ pub serve [--port <number>]
-
-This command starts up a _development server_, or _dev server_,
-for your Dart web app. The dev server is an HTTP server on localhost
-that serves up your web app's [assets](glossary.html#asset).
-
-Start the dev server from the directory that contains your web app's
-`pubspec.yaml` file:
-
- $ cd ~/dart/helloworld
- $ pub serve
- Serving helloworld on http://localhost:8080
-
-The dev server doesn't just serve up assets, it produces them by running
-[transformers](glossary.html#transformer). A transformer converts input
-assets (such as Dart files or Polymer-formatted HTML) into output assets
-(such as JavaScript and HTML).
-
-These output assets aren't in the file system; they exist only in the dev
-server. When you're ready to deploy, generate output files by running
-[`pub build`](pub-build.html).
-
-Pub automatically includes a dart2js transformer that compiles your Dart code
-to JavaScript. With this, you can change some Dart code, refresh your
-non-Dartium browser, and immediately see the changes.
-
-See [Assets and Transformers](assets-and-transformers.html) for
-information on:
-
-* Where in your package to put assets.
-* What URLs to use when referring to assets.
-* How to use `pubspec.yaml` to specify which transformers run, and in
- what order.
-
-## Options
-
-### `--port`
-
-By default the dev server uses `http://localhost:8080`. To change the port
-number, use the `--port` option:
-
- $ pub serve --port 9080
- Serving helloworld on http://localhost:9080
-
-### `--mode=<mode>`
-
-Specifies a transformation mode. Typical values are "debug" and "release", but
-any word is allowed. Transformers may use this to change how they behave.
-
-If set to "release" pub will generate minified JavaScript using dart2js.
-Otherwise, it generates it unminified. Also, in release mode, Pub will not
-include any source .dart files in the resulting build output since they have
-been compiled to JavaScript. In any other mode, the raw Dart files will be
-included.
-
-If omitted, it defaults to "debug".
-
-## What about Dart Editor's server?
-
-Dart Editor has its own dev server. We plan to unify it with the
-pub dev server soon.
View
76 app/doc/pub-upgrade.markdown
@@ -1,76 +0,0 @@
----
-title: "Command: Upgrade"
----
-
- $ pub upgrade [PACKAGE]
-
-Without any additional arguments, `pub upgrade` gets the latest versions of
-all the dependencies listed in the [`pubspec.yaml`](pubspec.html) file in the
-current working directory, as well as their [transitive
-dependencies](glossary.html#transitive-dependencies), to the `packages`
-directory located next to the pubspec. For example:
-
- $ pub upgrade
- Dependencies upgraded!
-
-When `pub upgrade` upgrades dependency versions, it writes a
-[lockfile](glossary.html#lockfile) to ensure that future [`pub
-get`s](pub-get.html) will use the same versions of those dependencies.
-Application packages should check in the lockfile to source control; this
-ensures the application will use the exact same versions of all dependencies for
-all developers and when deployed to production. Library packages should not
-check in the lockfile, though, since they're expected to work with a range of
-dependency versions.
-
-If a lockfile already exists, `pub upgrade` will ignore it and generate a new
-one from scratch using the latest versions of all dependencies. This is the
-primary difference between `pub upgrade` and `pub get`, which always tries to
-get the dependency versions specified in the existing lockfile.
-
-## Upgrading specific dependencies
-
-It's possible to tell `pub upgrade` to upgrade specific dependencies to the
-latest version while leaving the rest of the dependencies alone as much as
-possible. For example:
-
- $ pub upgrade unittest args
- Dependencies upgraded!
-
-Upgrading a dependency upgrades its transitive dependencies to their latest
-versions as well. Usually, no other dependencies are updated; they stay at the
-versions that are locked in the lockfile. However, if the requested upgrades
-cause incompatibilities with these locked versions, they will be selectively
-unlocked until a compatible set of versions is found.
-
-## Getting a new dependency
-
-If a dependency is added to the pubspec before `pub upgrade` is run, it will
-get the new dependency and any of its transitive dependencies and place them in
-the `packages` directory. This is the same behavior as `pub get`.
-
-## Removing a dependency
-
-If a dependency is removed from the pubspec before `pub upgrade` is run, it
-will remove the dependency from the `packages` directory, thus making it
-unavailable for importing. Any transitive dependencies of the removed dependency
-will also be removed, as long as no remaining immediate dependencies also depend
-on them. This is the same behavior as `pub get`.
-
-## Upgrading while offline
-
-If you don't have network access, you can still run `pub upgrade`. Since pub
-downloads packages to a central cache shared by all packages on your system, it
-can often find previously-downloaded packages there without needing to hit the
-network.
-
-However, by default, pub will always try to go online when you upgrade if you
-have any hosted dependencies so that it can see if newer versions of them are
-available. If you don't want it to do that, pass the `--offline` flag when
-running pub. In this mode, it will only look in your local package cache and
-try to find a set of versions that work with your package from what's already
-available.
-
-Keep in mind that pub *will* generate a lockfile after it does this. If the
-only version of some dependency in your cache happens to be old, this will lock
-your app to that version. The next time you are online, you will likely want to
-run `pub upgrade` again to upgrade to a later version.
View
30 app/doc/pub-uploader.markdown
@@ -1,30 +0,0 @@
----
-title: "Command: Uploader"
----
-
- $ pub uploader [options] {add/remove} <email>
-
-This command allows [uploaders](glossary.html#uploader) of a package on
-[pub.dartlang.org](http://pub.dartlang.org) to add or remove other uploaders for
-that package. It has two sub-commands, `add` and `remove`, that take the email
-address of the person to add/remove as an uploader. For example:
-
- ~/code/transmogrify$ pub uploader add nweiz@google.com
- 'nweiz@google.com' added as an uploader for package 'transmogrify'.
-
- ~/code/transmogrify$ pub uploader remove nweiz@google.com
- 'nweiz@google.com' is no longer an uploader for package 'transmogrify'.
-
-If a package has only one uploader, that uploader can't be removed. You may
-remove yourself as an uploader (as long as there are other uploaders), but you
-won't be able to re-add yourself again afterwards.
-
-By default, the package in the current working directory will have its
-uploaders modified. You can also pass the `--package` flag to choose a
-package by name. For example:
-
- $ pub uploader --package=transmogrify add nweiz@google.com
- 'nweiz@google.com' added as an uploader for package 'transmogrify'.
-
-Note that uploaders are identified by their Google accounts, so use a Gmail or
-Google Apps email address for any new uploaders.
View
184 app/doc/pubspec.markdown
@@ -1,184 +0,0 @@
----
-title: "Pubspec Format"
----
-
-1. [Name](#name)
-1. [Version](#version)
-1. [Description](#description)
-1. [Author/Authors](#authorauthors)
-1. [Homepage](#homepage)
-1. [Documentation](#documentation)
-1. [Dependencies](#dependencies)
-1. [SDK constraints](#sdk-constraints)
-{:.toc}
-
-Every pub package needs some metadata so it can specify its
-[dependencies](glossary.html#dependency). Pub packages that are shared with
-others also need to provide some other information so users can discover them.
-Pub stores this in a file named `pubspec.yaml`, which (naturally) is written in
-the [YAML](http://www.yaml.org/) language.
-
-At the top level are a series of fields. The currently supported ones are:
-
-<dl class="dl-horizontal">
- <dt>Name</dt>
- <dd>Required for every package.</dd>
- <dt>Version</dt>
- <dd>Required for packages that will be hosted on pub.dartlang.org.</dd>
- <dt>Description</dt>
- <dd>Required for packages that will be hosted on pub.dartlang.org.</dd>
- <dt>Author/Authors</dt>
- <dd>Optional.</dd>
- <dt>Homepage</dt>
- <dd>Optional.</dd>
- <dt>Documentation</dt>
- <dd>Optional.</dd>
- <dt>Dependencies</dt>
- <dd>Can be omitted if your package has no dependencies.</dd>
- <dt>Dev dependencies</dt>
- <dd>Can be omitted if your package has no dev dependencies.</dd>
-</dl>
-
-All other fields will be ignored. A simple but complete pubspec looks something
-like this:
-
-{% highlight yaml %}
-name: newtify
-version: 1.2.3
-description: >
- Have you been turned into a newt? Would you like to be? This
- package can help: it has all of the newt-transmogrification
- functionality you've been looking for.
-author: Nathan Weizenbaum <nweiz@google.com>
-homepage: http://newtify.dartlang.org
-documentation: http://docs.newtify.com
-dependencies:
- efts: '>=2.0.4 <3.0.0'
- transmogrify: '>=0.4.0'
-dev_dependencies:
- unittest: '>=0.6.0'
-{% endhighlight %}
-
-## Name
-
-Every package needs a name. When your stellar code gets props on
-the world stage, this is what they'll be hollering. Also, it's how other
-packages will refer to yours, and how it will appear here, should you publish
-it.
-
-It should be all lowercase, with underscores to separate words,
-`just_like_this`. Stick with basic Latin letters and Arabic digits:
-`[a-z0-9_]` and ensure that it's a valid Dart identifier (i.e. doesn't start
-with digits and isn't a reserved word).
-
-Try to pick a name that is clear, terse, and not already in use. A quick search
-[here](/packages) to make sure nothing else is using your name can save you
-heartache later.
-
-## Version
-
-Every package has a version. A version number is required to host your package
-here, but can be omitted for local-only packages. If you omit it, your package
-is implicitly versioned `0.0.0`.
-
-No one really gets excited about versioning, but it's a necessary evil for
-reusing code while letting it evolve quickly. A version number is three numbers
-separated by dots, like `0.2.43`. It can also optionally have a build
-(`+hotfix.oopsie`) or pre-release (`-alpha.12`) suffix.
-
-Each time you publish your package, you will publish it at a specific version.
-Once that's been done, consider it hermetically sealed: you can't touch it
-anymore. To make more changes, you'll need a new version.
-
-When you select a version, follow [semantic versioning][]. When you do, the
-clouds will part and sunshine will pour into your soul. If you don't, prepare
-yourself for hordes of angry users.
-
-[semantic versioning]: http://semver.org
-
-## Description
-
-This is optional for your own personal packages, but if you intend to share
-your package with the world (and you should because, let's be honest with
-ourselves, it's a thing of beauty) you must provide a description. This should
-be relatively short&mdash;a few sentences, maybe a whole paragraph&mdash;and
-tells a casual reader what they might want to know about your package.
-
-Think of the description as the sales pitch for your package. Users will see it
-when they [browse for packages](/packages). It should be simple plain text:
-no markdown or HTML. That's what your README is for.
-
-## Author/Authors
-
-You're encouraged to use these fields to describe the author(s) of your package
-and provide contact information. `author` should be used if your package has a
-single author, while `authors` should be used with a YAML list if more than one
-person wrote the package. Each author can either be a single name (e.g. `Nathan
-Weizenbaum`) or a name and an email address (e.g. `Nathan Weizenbaum
-<nweiz@google.com>`). For example:
-
-{% highlight yaml %}
-authors:
-- Nathan Weizenbaum <nweiz@google.com>
-- Bob Nystrom <rnystrom@google.com>
-{% endhighlight %}
-
-If anyone uploads your package here, we will show this email address so make
-sure you're OK with that.
-
-## Homepage
-
-This should be a URL pointing to the website for your package. For
-[hosted packages](#hosted-packages), this URL will be linked from the
-package's page. While this is technically optional *please do* provide one. It
-helps users understand where your package is coming from. If nothing else, you
-can always use the URL where you host the source code:
-[GitHub](http://github.com), [code.google.com](http://code.google.com/),
-whatever.
-
-## Documentation
-
-Some packages may have a site that hosts documentation separate from the main
-homepage. If your package has that, you can also add a `documentation:` field
-with that URL. If provided, a link to it will be shown on your package's page.
-
-## Dependencies
-
-<div class="learn-more">
- <a href="/doc/dependencies.html">
- Learn more about dependencies &rarr;
- </a>
-</div>
-
-Finally, the pubspec's *raison d'être*: [dependencies](glossary.html#dependency). Here,
-you list each package that your package needs in order to work.
-
-There are two separate sections. Dependencies under `dependencies:` are
-"regular" dependencies. They are packages that anyone using your package will
-also need. Dependencies under `dev_dependencies` are
-[dev dependencies](glossary.html#dev-dependency). These are packages that are
-only needed in the development of your package itself.
-
-## SDK constraints
-
-A package can indicate which versions of its dependencies it supports, but there
-is also another implicit dependency all packages have: the Dart SDK itself.
-Since the Dart platform evolves over time, a package may only work with certain
-versions of it.
-
-A package can specify that using an *SDK constraint*. This goes inside a
-separate top-level "environment" field in the pubspec and uses the same
-[version constraint](dependencies.html#version-constraints) syntax as
-dependencies. For example, this constraint says that this package works with any
-Dart SDK from 0.3.4 or later:
-
-{% highlight yaml %}
-environment:
- sdk: ">=0.3.4"
-{% endhighlight %}
-
-Pub will try to find the latest version of a package whose SDK constraint works
-with the version of the Dart SDK that you have installed.
-
-[pubsite]: http://pub.dartlang.org
-[semantic versioning]: http://semver.org/
View
379 app/doc/versioning.markdown
@@ -1,379 +0,0 @@
----
-title: "Versioning Philosophy"
----
-
-1. [A name and a number](#a-name-and-a-number)
-1. [Shared dependencies and unshared libraries](#shared-dependencies-and-unshared-libraries)
-1. [Version lock](#version-lock)
-1. [Version constraints](#version-constraints)
-1. [Semantic versions](#semantic-versions)
-1. [Constraint solving](#constraint-solving)
-1. [Constraint context](#constraint-context)
-1. [Lockfiles](#lockfiles)
-1. [When things go wrong](#when-things-go-wrong)
-1. [Summary](#summary)
-{:.toc}
-
-One of pub's main jobs is helping you work with versioning. Here, I'll
-explain a bit about the history of versioning and pub's approach to it.
-Consider this to be advanced information. If you want a better picture of *why*
-pub was designed the way it was, read on. If you just want to *use* pub, the
-[other docs](index.html) will serve you better.
-
-Modern software development, especially web development, leans heavily on
-reusing lots and lots of existing code. That includes code *you* wrote in the
-past, but also stuff from third-parties, everything from big frameworks to tiny
-little utility libraries. It's not uncommon for an application to depend on
-dozens of different packages and libraries.
-
-It's hard to understate how awesome this is. When you see stories of tiny web
-startups building a site in a few weeks that gets millions of users, the
-only reason they can pull that off is because the open source community has
-laid a feast of software at their feet.
-
-But there's still no such thing as a free lunch. There's a challenge to code
-reuse, especially reusing code you don't maintain. When your app uses tons of
-code being developed by other people, what happens when they change it? They
-don't want to break your app, and you certainly don't either.
-
-## A name and a number
-
-We solve this by *versioning*. When you depend on some piece of outside code,
-you don't just say "My app uses `widgets`." You say, "My app uses
-`widgets 2.0.5`." That combination of name and version number uniquely
-identifies an *immutable* chunk of code. The people hacking on `widgets` can
-make all of the changes they want, but they promise to not touch any already
-released versions. They can put out `2.0.6` or `3.0.0` and it won't affect you
-one whit because the version you use is unchanged.
-
-When you *do* want to get those changes, you can always point your app to a
-newer version of `widgets` and you don't have to coordinate with those
-developers to do it. So, problem solved, right?
-
-## Shared dependencies and unshared libraries
-
-Well, no. Depending on specific versions works fine when your dependency *graph*
-is really just a dependency *tree*. If your app depends on a bunch of stuff, and
-those things in turn have their own dependencies and so on, that all works fine
-as long as none of those dependencies *overlap*.
-
-But let's consider an example:
-
- myapp
- / \
- / \
- widgets templates
- \ /
- \ /
- collections
-
-So your app uses `widgets` and `templates`, and *both* of those use
-`collections`. This is called a **shared dependency**. Now what happens when
-`widgets` wants to use `collections 2.3.5` and `templates` wants
-`collections 2.3.7`? What if they don't agree on a version?
-
-One option is to just let the app use both
-versions of `collections`. It will have two copies of the library at different
-versions and `widgets` and `templates` will each get the one they want.
-
-This is what [npm][] does for node.js. Would it work for Dart? Consider this
-scenario:
-
- 1. `collections` defines some `Dictionary` class.
- 2. `widgets` gets an instance of it from its copy of `collections` (`2.3.5`).
- It then passes it up to `myapp`.
- 3. `myapp` sends the dictionary over to `templates`.
- 4. That in turn sends it down to *its* version of `collections` (`2.3.7`).
- 5. The method that takes it has a `Dictionary` type annotation for that object.
-
-As far as Dart is concerned, `collections 2.3.5` and `collections 2.3.7` are
-entirely unrelated libraries. If you take an instance of class `Dictionary` from
-one and pass it to a method in the other, that's a completely different
-`Dictionary` type. That means it will fail to match a `Dictionary` type
-annotation in the receiving library. Oops.
-
-Because of this (and because of the headaches of trying to debug an app that
-has multiple versions of things with the same name), we've decided npm's model
-isn't a good fit.
-
-[npm]: https://npmjs.org/
-
-## Version lock
-
-Instead, when you depend on a package, your app will only use a single copy of
-that package. When you have a shared dependency, everything that depends on it
-has to agree on which version to use. If they don't, you get an error.
-
-That doesn't actually solve your problem though. When you *do* get that error,
-you need to be able to resolve it. So let's say you've gotten yourself into
-that situation in the above example. You want to use `widgets` and `templates`,
-but they are using different versions of `collections`. What do you do?
-
-The answer is to try to upgrade one of those. `templates` wants
-`collections 2.3.7`. Is there a later version of `widgets` that you can upgrade
-to that works with that version?
-
-In many cases, the answer will be "no". Look at it from the perspective of the
-people developing `widgets`. They want to put out a new version with new changes
-to *their* code, and they want as many people to be able to upgrade to it it as
-possible. If they stick to their *current* version of `collections` then anyone
-who is using the current version `widgets` will be able to drop in this new one
-too.
-
-If they were to upgrade *their* dependency on `collections` then everyone who
-upgrades `widgets` would have to as well, *whether they want to or not.* That's
-painful, so you end up with a disincentive to upgrade dependencies. That's
-called **version lock**: everyone wants to move their dependencies forward, but
-no one can take the first step because it forces everyone else to as well.
-
-## Version constraints
-
-To solve version lock, we loosen the constraints that packages place on their
-dependencies. If `widgets` and `templates` can both indicate a *range* of
-versions for `collections` that they will work with, then that gives us enough
-wiggle room to move our dependencies forward to newer versions. As long as there
-is overlap in their ranges, we can still find a single version that makes them
-both happy.
-
-This is the model that [bundler](http://gembundler.com/) follows, and is pub's
-model too. When you add a dependency in your pubspec, you can specify a *range*
-of versions that you can accept. If the pubspec for `widgets` looked like this:
-