Browse files

Document the new stuff:

- The "documentation" field in the pubspec.
- SDK constraints.
- pub lish --force
- pub lish --dry-run
- Path dependencies.
  • Loading branch information...
1 parent be6eb90 commit 7b300ae6162f79c4ce71f27c2d784bd8fc94835f @munificent munificent committed Feb 13, 2013
View
7 app/doc/glossary.markdown
@@ -84,6 +84,13 @@ The lockfile is generated automatically for you by pub when you run
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. It is specified using normal [version constraint](#version-constraint)
@nex3
Dart member
nex3 added a note Feb 14, 2013

"It" -> "An SDK constraint"

@munificent
Dart member

Done.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+syntax, but in a special "environment" section
+[in the pubspec](pubspec.html#sdk-constraints).
+
### Source
A kind of place that pub can download and install packages from. A source isn't
View
18 app/doc/pub-lish.markdown
@@ -69,3 +69,21 @@ 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, though.
[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
+
+## 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.
View
104 app/doc/pubspec.markdown
@@ -7,12 +7,15 @@ title: "Pubspec Format"
1. [Description](#description)
1. [Author/Authors](#authorauthors)
1. [Homepage](#homepage)
+1. [Documentation](#documentation)
1. [Dependencies](#dependencies)
1. [Dependency sources](#dependency-sources)
1. [Hosted packages](#hosted-packages)
- 1. [SDK packages](#sdk-packages)
1. [Git packages](#git-packages)
+ 1. [Path packages](#path-packages)
+ 1. [SDK packages](#sdk-packages)
1. [Version constraints](#version-constraints)
+1. [SDK constraints](#sdk-constraints)
{:.toc}
Every pub package needs some metadata so it can specify its
@@ -34,6 +37,8 @@ At the top level are a series of fields. The currently supported ones are:
<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>
</dl>
@@ -50,6 +55,7 @@ description: >
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'
@@ -132,6 +138,13 @@ 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 separate site that hosts documentation separate from
@nex3
Dart member
nex3 added a note Feb 14, 2013

Remove the first "separate"

@munificent
Dart member

Done.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+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
Finally, the pubspec's *raison d'être*:
@@ -230,20 +243,6 @@ dependencies:
version: '>=0.4.0 <1.0.0'
{% endhighlight %}
-### SDK packages
-
-Some packages are a built-in part of the Dart SDK. These are the "batteries
-included" packages that you get for free when you install Dart.
-
-{% highlight yaml %}
-dependencies:
- i18n:
- sdk: i18n
-{% endhighlight %}
-
-The `sdk` here says this package should be found in the installed Dart SDK, and
-"i18n" is the name of the package to use.
-
### Git packages
Sometimes you live on the bleeding edge and you need to use stuff that hasn't
@@ -279,6 +278,60 @@ 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" local
+version of that package. That way changes in one package are instantly picked up
+by the one that depends on it.
+
+To handle that, pub supports *path dependencies*. These let you depend on a
+package on your local file system.
+
+{% highlight yaml %}
+dependencies:
+ transmogrify:
+ path: /Users/me/transmogrify
+{% endhighlight %}
+
+This says the root directory for `transmogrify` is at `/Users/me/transmogrify`.
+When you use this, pub will generate a symlink directly to the referenced
+directory. This means 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.
+
+Path dependencies are very 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.
+
+<aside class="alert alert-warning">
+Currently only absolute paths can be used for path dependencies.
+</aside>
+
+### SDK packages
+
+Some packages are a built-in part of the Dart SDK. These are the "batteries
+included" packages that you get for free when you install Dart.
@nex3
Dart member
nex3 added a note Feb 14, 2013

Should we add some language here to indicate that these will be removed at some point?

@munificent
Dart member

I don't think so. I think we'll communicate that on the main list. Most people are using the hosted versions now anyway, so it shouldn't be a huge change.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+
+{% highlight yaml %}
+dependencies:
+ i18n:
+ sdk: i18n
+{% endhighlight %}
+
+The `sdk` here says this package should be found in the installed Dart SDK, and
+"i18n" is the name of the package to use.
+
## Version constraints
If your package is an application, you don't usually need to specify [version
@@ -353,5 +406,26 @@ constraint starts with that.
</aside>
+## 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. 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 %}
+
+When you install a package that doesn't work with your installed Dart SDK, pub
+will show you an error message and ask you to resolve it. You can usually fix
+this by upgrading to the latest Dart SDK, or locking to an older version of that
+dependency that does work with your SDK.
+
[pubsite]: http://pub.dartlang.org
[semantic versioning]: http://semver.org/
View
8 app/static/style.css
@@ -4984,6 +4984,14 @@ body {
padding-top: 60px;
}
+code {
+ white-space: nowrap;
+}
+
+pre code {
+ white-space: inherit;
+}
+
a.permalink {
margin-left: 0.5em;
display: none;
View
7 app/views/doc/glossary.html
@@ -80,6 +80,13 @@ <h3 id="lockfile">Lockfile</h3>
package is an application package, you will typically check this into source
control. For library packages, you usually won&rsquo;t.</p>
+<h3 id="sdk-constraint">SDK Constraint</h3>
+
+<p>The declared versions of the Dart SDK itself that a package declares that it
+supports. It is specified using normal <a href="#version-constraint">version constraint</a>
+syntax, but in a special &ldquo;environment&rdquo; section
+<a href="pubspec.html#sdk-constraints">in the pubspec</a>.</p>
+
<h3 id="source">Source</h3>
<p>A kind of place that pub can download and install packages from. A source isn&rsquo;t
View
2 app/views/doc/package-layout.html
@@ -113,7 +113,7 @@ <h2 id="readme">README</h2>
package. This is the perfect place to introduce people to your code.</p>
<p>If your README ends in <code>.md</code>, <code>.markdown</code>, or <code>.mdown</code>, it will be parsed as
-<a href="http://daringfireball.net/projects/markdown/">Markdown</a> so you can make it as fancy nicely formatted as you like.</p>
+<a href="http://daringfireball.net/projects/markdown/">Markdown</a> so you can make it as fancy as you like.</p>
<h2 id="public-libraries">Public libraries</h2>
View
17 app/views/doc/pub-lish.html
@@ -73,3 +73,20 @@ <h2 id="deleting-a-published-package">Deleting a published package</h2>
issue</a> and the Pub authors will take down your package. You&rsquo;ll
need to use a different version when you re-upload it, though.</p>
+<h2 id="options">Options</h2>
+
+<h3 id="dry-run-or--n"><code>--dry-run</code> or <code>-n</code></h3>
+
+<p>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&rsquo;re ready to actually go public.</p>
+
+<h3 id="force-or--f"><code>--force</code> or <code>-f</code></h3>
+
+<p>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.</p>
+
+<p>If there are any errors in your package, it is not uploaded and this exits with
+an error. If there are warnings, it <em>will</em> be uploaded. If you want to ensure
+your package has no warnings before uploading, either don&rsquo;t use <code>--force</code>, or
+use <code>--dry-run</code> first.</p>
View
106 app/views/doc/pubspec.html
@@ -4,15 +4,18 @@
<li><a href="#description">Description</a></li>
<li><a href="#authorauthors">Author/Authors</a></li>
<li><a href="#homepage">Homepage</a></li>
+ <li><a href="#documentation">Documentation</a></li>
<li><a href="#dependencies">Dependencies</a></li>
<li><a href="#dependency-sources">Dependency sources</a>
<ol>
<li><a href="#hosted-packages">Hosted packages</a></li>
- <li><a href="#sdk-packages">SDK packages</a></li>
<li><a href="#git-packages">Git packages</a></li>
+ <li><a href="#path-packages">Path packages</a></li>
+ <li><a href="#sdk-packages">SDK packages</a></li>
</ol>
</li>
<li><a href="#version-constraints">Version constraints</a></li>
+ <li><a href="#sdk-constraints">SDK constraints</a></li>
</ol>
<p>Every pub package needs some metadata so it can specify its
@@ -34,6 +37,8 @@
<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>
</dl>
@@ -49,6 +54,7 @@
<span class="no">functionality you&#39;ve been looking for.</span>
<span class="l-Scalar-Plain">author</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Nathan Weizenbaum &lt;nweiz@google.com&gt;</span>
<span class="l-Scalar-Plain">homepage</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">http://newtify.dartlang.org</span>
+<span class="l-Scalar-Plain">documentation</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">http://docs.newtify.com</span>
<span class="l-Scalar-Plain">dependencies</span><span class="p-Indicator">:</span>
<span class="l-Scalar-Plain">efts</span><span class="p-Indicator">:</span> <span class="s">&#39;&gt;=2.0.4</span><span class="nv"> </span><span class="s">&lt;3.0.0&#39;</span>
<span class="l-Scalar-Plain">transmogrify</span><span class="p-Indicator">:</span> <span class="s">&#39;&gt;=0.4.0&#39;</span>
@@ -130,6 +136,13 @@ <h2 id="homepage">Homepage</h2>
<a href="http://github.com">GitHub</a>, <a href="http://code.google.com/">code.google.com</a>,
whatever.</p>
+<h2 id="documentation">Documentation</h2>
+
+<p>Some packages may have a separate 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&rsquo;s
+page.</p>
+
<h2 id="dependencies">Dependencies</h2>
<p>Finally, the pubspec&rsquo;s <em>raison d&rsquo;être</em>:
@@ -228,20 +241,6 @@ <h3 id="hosted-packages">Hosted packages</h3>
</code></pre>
</div>
-<h3 id="sdk-packages">SDK packages</h3>
-
-<p>Some packages are a built-in part of the Dart SDK. These are the &ldquo;batteries
-included&rdquo; packages that you get for free when you install Dart.</p>
-
-<div class="highlight"><pre><code class="yaml"><span class="l-Scalar-Plain">dependencies</span><span class="p-Indicator">:</span>
- <span class="l-Scalar-Plain">i18n</span><span class="p-Indicator">:</span>
- <span class="l-Scalar-Plain">sdk</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">i18n</span>
-</code></pre>
-</div>
-
-<p>The <code>sdk</code> here says this package should be found in the installed Dart SDK, and
-&ldquo;i18n&rdquo; is the name of the package to use.</p>
-
<h3 id="git-packages">Git packages</h3>
<p>Sometimes you live on the bleeding edge and you need to use stuff that hasn&rsquo;t
@@ -273,6 +272,62 @@ <h3 id="git-packages">Git packages</h3>
<p>The ref can be anything that Git allows to <a href="http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#naming-commits">identify a commit</a>.</p>
+<h3 id="path-packages">Path packages</h3>
+
+<p>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 &ldquo;live&rdquo; local
+version of that package. That way changes in one package are instantly picked up
+by the one that depends on it.</p>
+
+<p>To handle that, pub supports <em>path dependencies</em>. These let you depend on a
+package on your local file system.</p>
+
+<div class="highlight"><pre><code class="yaml"><span class="l-Scalar-Plain">dependencies</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">transmogrify</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">path</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">/Users/me/transmogrify</span>
+</code></pre>
+</div>
+
+<p>This says the root directory for <code>transmogrify</code> is at <code>/Users/me/transmogrify</code>.
+When you use this, pub will generate a symlink directly to the referenced
+directory. This means any changes you make to the dependent package will be seen
+immediately. You don&rsquo;t need to run pub every time you change the dependent
+package.</p>
+
+<p>Path dependencies are very useful for local development, but do not play nice
+with sharing code with the outside world. It&rsquo;s not like everyone can get to
+your file system, after all. Because of this, you cannot upload a package to
+<a href="http://pub.dartlang.org">pub.dartlang.org</a> if it has any path dependencies in its pubspec.</p>
+
+<p>Instead, the typical workflow is:</p>
+
+<ol>
+ <li>Edit your pubspec locally to use a path dependency.</li>
+ <li>Hack on the main package and the package it depends on.</li>
+ <li>Once they&rsquo;re both in a happy place, publish the dependent package.</li>
+ <li>Then change your pubspec to point to the now hosted version of its dependent.</li>
+ <li>Now you can publish your main package too if you want.</li>
+</ol>
+
+<aside class="alert alert-warning">
+Currently only absolute paths can be used for path dependencies.
+</aside>
+
+<h3 id="sdk-packages">SDK packages</h3>
+
+<p>Some packages are a built-in part of the Dart SDK. These are the &ldquo;batteries
+included&rdquo; packages that you get for free when you install Dart.</p>
+
+<div class="highlight"><pre><code class="yaml"><span class="l-Scalar-Plain">dependencies</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">i18n</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">sdk</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">i18n</span>
+</code></pre>
+</div>
+
+<p>The <code>sdk</code> here says this package should be found in the installed Dart SDK, and
+&ldquo;i18n&rdquo; is the name of the package to use.</p>
+
<h2 id="version-constraints">Version constraints</h2>
<p>If your package is an application, you don&rsquo;t usually need to specify <a href="glossary.html#version-constraint">version
@@ -347,3 +402,24 @@ <h2 id="version-constraints">Version constraints</h2>
</aside>
+<h2 id="sdk-constraints">SDK constraints</h2>
+
+<p>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.</p>
+
+<p>A package can specify that using an <em>SDK constraint</em>. This goes inside a
+separate top-level &ldquo;environment&rdquo; field in the pubspec. For example, this
+constraint says that this package works with any Dart SDK from 0.3.4 or later:</p>
+
+<div class="highlight"><pre><code class="yaml"><span class="l-Scalar-Plain">environment</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">sdk</span><span class="p-Indicator">:</span> <span class="s">&quot;&gt;=0.3.4&quot;</span>
+</code></pre>
+</div>
+
+<p>When you install a package that doesn&rsquo;t work with your installed Dart SDK, pub
+will show you an error message and ask you to resolve it. You can usually fix
+this by upgrading to the latest Dart SDK, or locking to an older version of that
+dependency that does work with your SDK.</p>
+
View
9 css/sass/style.scss
@@ -25,6 +25,15 @@ body {
padding-top: 60px;
}
+// Don't word wrap inline code.
+code {
+ white-space: nowrap;
+}
+
+pre code {
+ white-space: inherit;
+}
+
a.permalink {
margin-left: 0.5em;
display: none;

0 comments on commit 7b300ae

Please sign in to comment.