Add plan debugging documentation.

Fixed a small bug in hab-plan-build where "whereami" doesn't work due
to a typo.
Moved "build packages" under the create topic; it's really a subset of
that.

Signed-off-by: Julian C. Dunn <[email protected]>

Pull request: #768
Approved by: fnichol

components/plan-build/bin/hab-plan-build.sh

@@ -1089,8 +1089,8 @@ attach() {
     case "$cmd" in
       vars) (set -o posix; set);;
       whereami*|\@*)
-        __attach_whereami "$(echo $cmd \
-          | awk '{if (NF == 2) print $2; else print "10"}')"
+        _attach_whereami "$(echo $cmd \
+         | awk '{if (NF == 2) print $2; else print "10"}')"
         ;;
       exit|quit) ;;
       exit-program|quit-program) exit $?;;

www/data/docs_sidebar.yml

@@ -36,10 +36,12 @@ sidebar_links:
       link: "/docs/create-plans/"
     - title: Add configuration
       link: "/docs/create-packages-configure/"
-    - title: Binary-only packages
+    - title: Build packages
+      link: "/docs/create-packages-build/"
+    - title: Debug plans
+      link: "/docs/create-packages-debugging/"
+    - title: Create binary-only packages
       link: "/docs/create-packages-binary-only"
-  - title: Build packages
-    link: "/docs/build-packages-overview/"
   - title: Run packages <span>&plus;</span>
     link: "/docs/run-packages-overview/"
     sub_links:

www/source/docs/create-packages-binary-only.html.md

@@ -83,3 +83,9 @@ If you have many files you need to fix, or the binary package automatically gene
        ln -sv $(pkg_path_for coreutils)/bin/env /usr/bin/env
 
 This is a last resort as it breaks the dependency isolation guarantees of Habitat.
+
+<hr>
+<ul class="main-content--link-nav">
+  <li>Continue to the next topic</li>
+  <li><a href="/docs/run-packages-overview">Run packages</a></li>
+</ul>

www/source/docs/build-packages-overview.html.md → www/source/docs/create-packages-build.html.md

@@ -71,5 +71,5 @@ For information on the contents of an installed package, see [Package contents](
 <hr>
 <ul class="main-content--link-nav">
   <li>Continue to the next topic</li>
-  <li><a href="/docs/run-packages-overview">Run packages</a></li>
+  <li><a href="/docs/create-packages-debugging">Debug plans</a></li>
 </ul>

www/source/docs/create-packages-configure.html.md

@@ -127,5 +127,5 @@ For an example of how to templatize a configuration file and add it to your plan
 <hr>
 <ul class="main-content--link-nav">
   <li>Continue to the next topic</li>
-  <li><a href="/docs/create-packages-binary-only">Binary-only packages</a></li>
+  <li><a href="/docs/create-packages-build">Build packages</a></li>
 </ul>

www/source/docs/create-packages-debugging.html.md

@@ -0,0 +1,74 @@
+---
+title: Debugging Plans
+---
+
+# Debugging Plans
+
+While working on plans, you may wish to stop the build and inspect the environment at any point during a phase (e.g. `do_download`, `do_build`). Habitat provides an `attach` function for use in your plan that functions like a debugging breakpoint and provides an easy <acronym title="Read, Evaluation, Print Loop">REPL</acronym> at that point.
+
+To use `attach`, insert it into your plan at the point where you would like to use it, e.g.
+
+       do_build() {
+         attach
+         make
+       }
+
+Now, perform a [build](/docs/create-packages-build) -- we recommend using an interactive studio so you do not need to set up the environment from scratch for every build.
+
+       $ hab studio enter
+       $ build yourapp
+
+The build system will proceed until the point where the `attach` function is invoked, and then drop you into a limited shell:
+
+~~~
+### Attaching to debugging session
+
+From: /src/plans/yourapp/plan.sh @ line 15 :
+
+    5: pkg_maintainer="The Habitat Maintainers <[email protected]>"
+    6: pkg_source=http://download.yourapp.io/releases/${pkg_name}-${pkg_version}.tar.gz
+    7: pkg_shasum=c2a791c4ea3bb7268795c45c6321fa5abcc24457178373e6a6e3be6372737f23
+    8: pkg_bin_dirs=(bin)
+    9: pkg_build_deps=(core/make core/gcc)
+    10: pkg_deps=(core/glibc)
+    11: pkg_expose=(3000)
+    12:
+    13: do_build() {
+ => 14:   attach
+    15:   make
+    16: }
+
+[1] yourapp(do_build)>
+~~~
+
+You can use basic Linux commands like `ls` in this environment. You can also use the `help` command the Habitat build system provides in this context to see what other functions can help you debug the plan.
+
+~~~
+[1] yourapp(do_build)> help
+Help
+  help          Show a list of command or information about a specific command.
+
+Context
+  whereami      Show the code surrounding the current context
+                (add a number to increase the lines of context).
+
+Environment
+  vars          Prints all the environment variables that are currently in scope.
+
+Navigating
+  exit          Pop to the previous context.
+  exit-program  End the /hab/pkgs/core/hab-plan-build/0.6.0/20160604180818/bin/hab-plan-build program.
+
+Aliases
+  @             Alias for `whereami`.
+  quit          Alias for `exit`.
+  quit-program  Alias for `exit-program`.
+~~~
+
+Type `quit` when you are done with the debugger, and the remainder of the build will continue. If you wish to abort the build entirely, type `quit-program`.
+
+<hr>
+<ul class="main-content--link-nav">
+  <li>Continue to the next topic</li>
+  <li><a href="/docs/create-packages-binary-only">Create binary-only packages</a></li>
+</ul>

www/source/docs/create-plans.html.md.erb

@@ -177,7 +177,7 @@ If your service does not require custom behavior during the lifecycle of the run
 
 And, as mentioned above, you can use any of the [runtime configuration settings](/docs/plan-syntax#runtime-configuration-settings), either defined by you in your config file, or defined by Habitat.
 
-Once you are done writing your plan, use the studio to [build your package](/docs/build-packages-overview).
+Once you are done writing your plan, use the studio to [build your package](/docs/create-packages-build).
 
 <hr>
 <ul class="main-content--link-nav">

www/source/docs/index.html.md

@@ -10,8 +10,7 @@ The Habitat documentation is broken out into the following sections:
 
 - [Tutorials](/tutorials): Location for our getting started and advanced tutorials. Currently, only the getting started tutorial is available. You should start here if you are new to Habitat.
 - [Concepts](/docs/concepts-overview): Describes the major components of Habitat and how they work.
-- [Create packages](/docs/create-packages-overview): Learn how to create a plan, what all of the plan settings are, and how to configure a package.
-- [Build packages](/docs/build-packages-overview): Learn how to sign and build a package, and understand what a package actually contains.
+- [Create packages](/docs/create-packages-overview): Learn how to create a plan, what all of the plan settings are, how to configure a package, and how to build packages.
 - [Run packages](/docs/run-packages-overview): Learn how to run a package natively as well as through an external runtime format, such as a Docker or rkt container.
 
 ## Getting Habitat

www/source/docs/overview.html.md

@@ -11,8 +11,7 @@ The Habitat documentation is broken out into the following sections:
 
 - [Tutorials](/tutorials): Location for our getting started and advanced tutorials. Currently, only the getting started tutorial is available. You should start here if you are new to Habitat.
 - [Concepts](/docs/concepts-overview): Describes the major components of Habitat and how they work.
-- [Create packages](/docs/create-packages-overview): Learn how to create a plan, what all of the plan settings are, and how to configure a package.
-- [Build packages](/docs/build-packages-overview): Learn how to sign and build a package, and understand what a package actually contains.
+- [Create packages](/docs/create-packages-overview): Learn how to create a plan, what all of the plan settings are, how to configure a package, and how to build packages.
 - [Run packages](/docs/run-packages-overview): Learn how to run a package natively as well as through an external runtime format, such as a Docker or rkt container.
 
 ## Where to begin

www/source/docs/run-packages-overview.html.md

@@ -10,7 +10,7 @@ Habitat packages are run under the Habitat supervisor. You can also export the s
 
 Packages can be tested in the interactive studio environment or natively on a host machine running Linux. To run packages directly:
 
-1. [Build your package](/docs/build-packages-overview) inside an interactive studio. Do not exit the studio after it is built.
+1. [Build your package](/docs/create-packages-build) inside an interactive studio. Do not exit the studio after it is built.
 2. To start your service, type `hab start yourorigin/yourname`, substituting the name and origin of the package you built in step 1. Your service should now be running.
 
 If your host machine is running Linux, do the following to run your packages:
@@ -46,7 +46,7 @@ You can create a Docker container image for any package by performing the follow
 
 1. Ensure you have a Docker daemon running on your host system. The exporter shares the Docker socket (`unix:///var/run/docker.sock`) into the studio.
 2. Create an interactive studio with the `hab studio enter` command.
-3. Install or [build](/docs/build-packages-overview) the Habitat package from which you want to create a Docker container image, for example:
+3. Install or [build](/docs/create-packages-build) the Habitat package from which you want to create a Docker container image, for example:
 
        hab pkg install yourorigin/yourpackage
 
@@ -61,7 +61,7 @@ You can create a Docker container image for any package by performing the follow
 You can create an Application Container Image (ACI) for any package by performing the following steps:
 
 1. Create an interactive studio in any directory with the `hab studio enter` command.
-2. Install or [build](/docs/build-packages-overview) the Habitat package from which you want to create an ACI, for example:
+2. Install or [build](/docs/create-packages-build) the Habitat package from which you want to create an ACI, for example:
 
        hab pkg install yourorigin/yourpackage