From 3a9cd2614e05b7d59febd4bcf7ce76a607bc2939 Mon Sep 17 00:00:00 2001
From: Omar Padron <omar.padron@kitware.com>
Date: Tue, 27 Feb 2018 03:36:14 -0500
Subject: Docker-Based Developer Resource (#5871)

* add docker-based development resources

* incorporate feedback from @ax3l

* fix docs/improve ssh handling

* experiment with custom prompt

* add arch/fix missing core_compilers key

* add centos/minor tweaks

* make prompt experiment optional

* workaround problem with latest fedora docker image

* add docker documentation page to index toc

* try another documentation fix

* switch arch linux base to base/archlinux

* update the git urls in the Dockerfiles

* add opensuse

* switch CUSTOM_PROMPT variable to simply "PROMPT"
---
 lib/spack/docs/docker_for_developers.rst | 39 ++++++++++++++++++++++++++++++++
 lib/spack/docs/index.rst                 |  1 +
 lib/spack/docs/workflows.rst             | 22 ++++++++++++++++++
 3 files changed, 62 insertions(+)
 create mode 100644 lib/spack/docs/docker_for_developers.rst

(limited to 'lib')

diff --git a/lib/spack/docs/docker_for_developers.rst b/lib/spack/docs/docker_for_developers.rst
new file mode 100644
index 0000000000..cb08b7503e
--- /dev/null
+++ b/lib/spack/docs/docker_for_developers.rst
@@ -0,0 +1,39 @@
+.. _docker_for_developers:
+
+=====================
+Docker for Developers
+=====================
+
+This guide is intended for people who want to use our prepared docker
+environments to work on developing Spack or working on spack packages. It is
+meant to serve as the companion documentation for the :ref:`packaging-guide`.
+
+--------
+Overview
+--------
+
+To get started, all you need is the latest version of ``docker`` and
+``docker-compose``.
+
+.. code-block:: console
+
+    $ cd share/spack/docker
+    $ docker-compose run --rm ubuntu
+
+This command should drop you into an interactive shell where you can run spack
+within an isolated docker container running ubuntu.  The copy of spack being
+used should be tied to the working copy of your cloned git repo, so any changes
+you make should be immediately reflected in the running docker container.  Feel
+free to add or modify any packages or to hack on spack, itself.  Your contained
+copy of spack should immediately reflect all changes.
+
+To work within a container running a different linux distro, change the "ubuntu"
+argument to any one of the services listed under the ``docker-compose.yml``
+file.
+
+.. code-block:: console
+
+    $ docker-compose config --services
+    fedora
+    ubuntu
+    $ docker-compose run --rm fedora
diff --git a/lib/spack/docs/index.rst b/lib/spack/docs/index.rst
index 2ca737bb72..ea80e2c21e 100644
--- a/lib/spack/docs/index.rst
+++ b/lib/spack/docs/index.rst
@@ -74,6 +74,7 @@ or refer to the full manual below.
    contribution_guide
    packaging_guide
    developer_guide
+   docker_for_developers
    Spack API Docs <spack>
    LLNL API Docs <llnl>
 
diff --git a/lib/spack/docs/workflows.rst b/lib/spack/docs/workflows.rst
index 4c674f92e4..0d8ffb7a14 100644
--- a/lib/spack/docs/workflows.rst
+++ b/lib/spack/docs/workflows.rst
@@ -1254,6 +1254,28 @@ Just use the `docker bootstraping mechanism <http://singularity.lbl.gov/quicksta
    %runscript
    exec /bin/bash -l
 
+""""""""""""""""""""""
+Docker for Development
+""""""""""""""""""""""
+
+For examples of how we use docker in development, see
+:ref:`docker_for_developers`.
+
+"""""""""""""""""""""""""
+Docker on Windows and OSX
+"""""""""""""""""""""""""
+
+On Mac OS and Windows, docker runs on a hypervisor that is not allocated much
+memory by default, and some spack packages may fail to build due to lack of
+memory. To work around this issue, consider configuring your docker installation
+to use more of your host memory. In some cases, you can also ease the memory
+pressure on parallel builds by limiting the parallelism in your config.yaml.
+
+.. code-block:: yaml
+
+   config:
+     build_jobs: 2
+
 ------------------
 Upstream Bug Fixes
 ------------------
-- 
cgit v1.2.3-70-g09d2