From 23f3f1adfe01f7b1301959e7e54584724679c7b3 Mon Sep 17 00:00:00 2001
From: Todd Gamblin <tgamblin@llnl.gov>
Date: Fri, 18 Mar 2016 13:32:37 -0700
Subject: [PATCH 1/2] Make InstallError and ExternalPackageError visiible in
 packages.

---
 lib/spack/spack/__init__.py | 8 ++++++--
 lib/spack/spack/package.py  | 4 ++++
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/lib/spack/spack/__init__.py b/lib/spack/spack/__init__.py
index 0ba42bbbfcd..aee11f061f3 100644
--- a/lib/spack/spack/__init__.py
+++ b/lib/spack/spack/__init__.py
@@ -189,5 +189,9 @@
 from spack.util.executable import *
 __all__ += spack.util.executable.__all__
 
-from spack.package import install_dependency_symlinks, flatten_dependencies, DependencyConflictError
-__all__ += ['install_dependency_symlinks', 'flatten_dependencies', 'DependencyConflictError']
+from spack.package import \
+    install_dependency_symlinks, flatten_dependencies, DependencyConflictError, \
+    InstallError, ExternalPackageError
+__all__ += [
+    'install_dependency_symlinks', 'flatten_dependencies', 'DependencyConflictError',
+    'InstallError', 'ExternalPackageError']
diff --git a/lib/spack/spack/package.py b/lib/spack/spack/package.py
index b488e4c49db..dafad0b184a 100644
--- a/lib/spack/spack/package.py
+++ b/lib/spack/spack/package.py
@@ -1351,6 +1351,10 @@ def __init__(self, message, long_msg=None):
         super(InstallError, self).__init__(message, long_msg)
 
 
+class ExternalPackageError(InstallError):
+    """Raised by install() when a package is only for external use."""
+
+
 class PackageStillNeededError(InstallError):
     """Raised when package is still needed by another on uninstall."""
     def __init__(self, spec, dependents):

From e9126baaabbfaa5e12641b3d44a5c5fd49e43ca3 Mon Sep 17 00:00:00 2001
From: Todd Gamblin <tgamblin@llnl.gov>
Date: Fri, 18 Mar 2016 13:42:45 -0700
Subject: [PATCH 2/2] Add docs for InstallError.

---
 lib/spack/docs/packaging_guide.rst | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst
index c1077e44977..519c0da2329 100644
--- a/lib/spack/docs/packaging_guide.rst
+++ b/lib/spack/docs/packaging_guide.rst
@@ -1844,6 +1844,20 @@ dedicated process.
 
 .. _prefix-objects:
 
+
+Failing the build
+----------------------
+
+Sometimes you don't want a package to successfully install unless some
+condition is true.  You can explicitly cause the build to fail from
+``install()`` by raising an ``InstallError``, for example:
+
+.. code-block:: python
+
+   if spec.architecture.startswith('darwin'):
+       raise InstallError('This package does not build on Mac OS X!')
+
+
 Prefix objects
 ----------------------