| Index: app/views/doc/index.html
|
| diff --git a/app/views/doc/index.html b/app/views/doc/index.html
|
| deleted file mode 100644
|
| index 74a5fb23954cae52d52ab88114360a53f4bd225b..0000000000000000000000000000000000000000
|
| --- a/app/views/doc/index.html
|
| +++ /dev/null
|
| @@ -1,298 +0,0 @@
|
| -<ol class="toc">
|
| - <li><a href="#installing-and-configuring-pub">Installing and configuring pub</a></li>
|
| - <li><a href="#creating-a-package">Creating a package</a></li>
|
| - <li><a href="#adding-a-dependency">Adding a dependency</a></li>
|
| - <li><a href="#getting-dependencies">Getting dependencies</a></li>
|
| - <li><a href="#importing-code-from-a-dependency">Importing code from a dependency</a></li>
|
| - <li><a href="#upgrading-a-dependency">Upgrading a dependency</a></li>
|
| - <li><a href="#publishing-a-package">Publishing a package</a></li>
|
| -</ol>
|
| -
|
| -<p><em>Pub</em> 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.</p>
|
| -
|
| -<p>To <strong>find</strong> a package that’s on pub.dartlang.org,
|
| -use the Search box at the top right of this page.</p>
|
| -
|
| -<p>To <strong>use</strong> a package that’s on pub.dartlang.org:</p>
|
| -
|
| -<ol>
|
| - <li>
|
| - <p>Create a <code>pubspec.yaml</code> file
|
| -(if one doesn’t already exist)
|
| -and list the package as dependency.
|
| -For example, to use the <a href="/packages/web_ui">web_ui</a> package
|
| -in an app, put this in a top-level file named <code>pubspec.yaml</code>:</p>
|
| -
|
| - <pre><code> name: my_app
|
| - dependencies:
|
| - web_ui: any
|
| -</code></pre>
|
| - </li>
|
| - <li>
|
| - <p>Run <code>pub get</code>, either on the command line
|
| -or through the Dart Editor menu: Tools > Pub Get.</p>
|
| - </li>
|
| - <li>
|
| - <p>Import one or more libraries from the package:</p>
|
| -
|
| - <pre><code> import 'package:web_ui/web_ui.dart';
|
| -</code></pre>
|
| - </li>
|
| -</ol>
|
| -
|
| -<p>For details and pointers to more documentation, read on.</p>
|
| -
|
| -<h2 id="installing-and-configuring-pub">Installing and configuring pub</h2>
|
| -
|
| -<p>Pub is in the <a href="http://www.dartlang.org/docs/sdk/">Dart SDK</a>,
|
| -which you can download by itself or as part of
|
| -<a href="http://www.dartlang.org/docs/editor/">Dart Editor</a>.
|
| -You can use pub through
|
| -<a href="http://www.dartlang.org/docs/editor/">Dart Editor</a>, or through the
|
| -<code>pub</code> command-line app, which lives inside the <code>bin</code> directory of the Dart SDK.</p>
|
| -
|
| -<p>To use pub and other tools on the command line,
|
| -you might want to add the SDK’s <code>bin</code> directory to your system path.
|
| -For example, on Mac and Linux:</p>
|
| -
|
| -<pre><code>export PATH=$PATH:<path to sdk>/bin
|
| -</code></pre>
|
| -
|
| -<p>Here, <code><path to sdk></code> is the absolute path
|
| -to the main directory of the SDK. For example,
|
| -if you install Dart Editor in
|
| -<code>/home/me/dart</code>, then add this to your PATH:</p>
|
| -
|
| -<pre><code>/home/me/dart/dart-sdk/bin
|
| -</code></pre>
|
| -
|
| -<p>On Windows, you can set the system PATH environment variable through the
|
| -Control Panel. A quick
|
| -<a href="https://www.google.com/search?q=windows+set+environment+variable">search</a>
|
| -should find the instructions for your version of Windows.</p>
|
| -
|
| -<h2 id="creating-a-package">Creating a package</h2>
|
| -
|
| -<div class="learn-more">
|
| - <a href="/doc/package-layout.html">
|
| - Learn more about packages →
|
| - </a>
|
| -</div>
|
| -
|
| -<p>A <strong>package</strong> 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.</p>
|
| -
|
| -<p>While everything is a package in pub, there are two flavors of packages that are
|
| -used slightly differently in practice. A <a href="glossary.html#library-package"><strong>library
|
| -package</strong></a> 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 <a href="glossary.html#application-package"><strong>application
|
| -package</strong></a> only <em>consumes</em> packages but
|
| -doesn’t itself get reused. In other words, library packages will be used as
|
| -dependencies, but application packages won’t.</p>
|
| -
|
| -<p>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”.</p>
|
| -
|
| -<div class="learn-more">
|
| - <a href="/doc/pubspec.html">
|
| - Learn more about pubspecs →
|
| - </a>
|
| -</div>
|
| -
|
| -<p>To turn your app into an application package so it can use other packages, you
|
| -just need to give it a <strong>pubspec</strong>. This file is written using the
|
| -<a href="http://yaml.org">YAML language</a> and is named <code>pubspec.yaml</code>. The simplest
|
| -possible pubspec just contains the name of the package. Save the pubspec file as
|
| -<code>pubspec.yaml</code> in the root directory of your app.</p>
|
| -
|
| -<p>Behold, the simplest possible <code>pubspec.yaml</code>:</p>
|
| -
|
| -<div class="highlight"><pre><code class="yaml"><span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">my_app</span>
|
| -</code></pre></div>
|
| -
|
| -<p>Now <code>my_app</code> is a pub package!</p>
|
| -
|
| -<h2 id="adding-a-dependency">Adding a dependency</h2>
|
| -
|
| -<div class="learn-more">
|
| - <a href="/doc/dependencies.html">
|
| - Learn more about dependencies →
|
| - </a>
|
| -</div>
|
| -
|
| -<p>One of pub’s main jobs is managing <strong>dependencies</strong>. 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 <code>transmogrify</code> package.</p>
|
| -
|
| -<p>You specify your package’s dependencies in the pubspec file immediately after
|
| -your package name. For example:</p>
|
| -
|
| -<div class="highlight"><pre><code class="yaml"><span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">my_app</span>
|
| -<span class="l-Scalar-Plain">dependencies</span><span class="p-Indicator">:</span>
|
| - <span class="l-Scalar-Plain">transmogrify</span><span class="p-Indicator">:</span>
|
| -</code></pre></div>
|
| -
|
| -<p>Here, we are declaring a dependency on the (fictional) <code>transmogrify</code> package.</p>
|
| -
|
| -<h2 id="getting-dependencies">Getting dependencies</h2>
|
| -
|
| -<div class="learn-more">
|
| - <a href="/doc/pub-get.html">
|
| - Learn more about <tt>pub get</tt> →
|
| - </a>
|
| -</div>
|
| -
|
| -<p>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:</p>
|
| -
|
| -<pre><code>$ cd path/to/your_app
|
| -$ pub get
|
| -</code></pre>
|
| -
|
| -<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>
|
| -
|
| -<p>When you do this, pub will create a <code>packages</code> directory in the same directory
|
| -as <code>pubspec.yaml</code>. In there, it will place each package that your package
|
| -depends on (these are called your <strong>immediate dependencies</strong>). It will also
|
| -look at all of those packages and get everything <em>they</em> depend on, recursively
|
| -(these are your <strong>transitive dependencies</strong>).</p>
|
| -
|
| -<p>When this is done, you will have a <code>packages</code> directory that contains every
|
| -single package your program needs in order to run.</p>
|
| -
|
| -<h2 id="importing-code-from-a-dependency">Importing code from a dependency</h2>
|
| -
|
| -<p>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
|
| -<code>package:</code> scheme:</p>
|
| -
|
| -<div class="highlight"><pre><code class="dart"><span class="k">import</span> <span class="s1">'package:transmogrify/transmogrify.dart'</span><span class="p">;</span>
|
| -</code></pre></div>
|
| -
|
| -<p>This looks inside the <code>transmogrify</code> package for a top-level file named
|
| -<code>transmogrify.dart</code>. 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.</p>
|
| -
|
| -<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>
|
| -
|
| -<p>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:</p>
|
| -
|
| -<pre><code>transmogrify/
|
| - lib/
|
| - transmogrify.dart
|
| - parser.dart
|
| - test/
|
| - parser/
|
| - parser_test.dart
|
| -</code></pre>
|
| -
|
| -<p>The <code>parser_test</code> file <em>could</em> import <code>parser.dart</code> like this:</p>
|
| -
|
| -<div class="highlight"><pre><code class="dart"><span class="k">import</span> <span class="s1">'../../lib/parser.dart'</span><span class="p">;</span>
|
| -</code></pre></div>
|
| -
|
| -<p>But that’s a pretty nasty relative path. If <code>parser_test.dart</code> is ever moved
|
| -up or down a directory, that path will break and you’ll have to fix the code.
|
| -Instead, you can do:</p>
|
| -
|
| -<div class="highlight"><pre><code class="dart"><span class="k">import</span> <span class="s1">'package:transmogrify/parser.dart'</span><span class="p">;</span>
|
| -</code></pre></div>
|
| -
|
| -<p>This way, the import can always get to <code>parser.dart</code> regardless of where the
|
| -importing file is.</p>
|
| -
|
| -<!-- 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"> </i>
|
| - </a>
|
| -</div>
|
| --->
|
| -
|
| -<h2 id="upgrading-a-dependency">Upgrading a dependency</h2>
|
| -
|
| -<div class="learn-more">
|
| - <a href="/doc/pub-upgrade.html">
|
| - Learn more about <tt>pub upgrade</tt> →
|
| - </a>
|
| -</div>
|
| -
|
| -<p>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 <em>always</em> use that version by creating a <strong>lockfile</strong>.
|
| -This is a file named <code>pubspec.lock</code> that pub creates and stores next to your
|
| -pubspec. It lists the specific versions of each dependency (immediate and
|
| -transitive) that your package uses.</p>
|
| -
|
| -<p>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.</p>
|
| -
|
| -<p>When you are ready to upgrade your dependencies to the latest versions, do:</p>
|
| -
|
| -<pre><code>$ pub upgrade
|
| -</code></pre>
|
| -
|
| -<p>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:</p>
|
| -
|
| -<pre><code>$ pub upgrade transmogrify
|
| -</code></pre>
|
| -
|
| -<p>This upgrades <code>transmogrify</code> to the latest version but leaves everything else
|
| -the same.</p>
|
| -
|
| -<h2 id="publishing-a-package">Publishing a package</h2>
|
| -
|
| -<div class="learn-more">
|
| - <a href="/doc/pub-lish.html">
|
| - Learn more about <tt>pub publish</tt> →
|
| - </a>
|
| -</div>
|
| -
|
| -<p>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:</p>
|
| -
|
| -<pre><code>$ pub publish
|
| -</code></pre>
|
| -
|
| -<p>Pub will check to make sure that your package follows the <a href="pubspec.html">pubspec
|
| -format</a> and <a href="package-layout.html">package layout conventions</a>, and
|
| -then upload your package to <a href="http://pub.dartlang.org">pub.dartlang.org</a>. 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 <code>transmogrify</code>,
|
| -then they can write:</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="s">">=</span><span class="nv"> </span><span class="s">1.0.0</span><span class="nv"> </span><span class="s"><</span><span class="nv"> </span><span class="s">2.0.0"</span>
|
| -</code></pre></div>
|
| -
|
| -<p>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.</p>
|
|
|