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> |