Repository: spack/spack

Issue:
Document Common Compiler Setups
Add information to the documentation.  Common setups that need documentation so far are:
1. GNU compilers
1. Intel compilers
1. PGI compilers
1. Mixed compilers (particularly Clang+GNU on Macintosh)

@adamjstewart:

> Documenation issue:
> There currently isn't much documentation on setting up compilers. You may have noticed on GitHub and the Google Group that a lot of people are having problems getting the Intel compilers to work with Spack. There are dozens of suggested workaround, and I've been meaning to add documentation for these. I would like an entire section on compilers, with specific instructions for each compiler. It could include instructions on installing PGI with Spack (see #558), workarounds for setting up Intel (see https://groups.google.com/forum/#!topic/spack/NxyNTAZyMQg), and instructions for setting up mixed compilers.



Discussion:
I've been collecting notes on this. Here is what I have so far:

The Spack documentation is a little lacking on setting up compilers. In particular, the Intel compilers have been causing everyone headaches. A dedicated section on Compilers should be added to http://software.llnl.gov/spack/index.html

Here are some links to discussions on how to get certain compilers working:

**GCC**
Relatively problem free, unless you are on OS X

**Intel**
Barely works. Have to source environment variables. Need to add support for sourcing scripts when using compilers.
https://groups.google.com/forum/#!topic/spack/NxyNTAZyMQg
https://github.com/LLNL/spack/pull/451

**PGI**
Still some bugs to work out, but promising. Some packages like libpciaccess simply can't be built with PGI. I've been submitting bug reports in an attempt to fix this.
https://github.com/LLNL/spack/pull/558
https://github.com/LLNL/spack/pull/493
https://github.com/LLNL/spack/issues/518
https://github.com/LLNL/spack/issues/553
https://groups.google.com/forum/#!topic/spack/7xmKGBZ-jRg

**NAG**
A good example of the steps for adding support for a brand new compiler. Still need to add module every time for license environment variable.
https://github.com/LLNL/spack/pull/350
https://groups.google.com/forum/#!topic/spack/PWI2ntNUxm0
https://groups.google.com/forum/#!topic/spack/_oOT-ceoxIM

See #846 for information on clang + gfortran on Mac.


Resolving patch:
diff --git a/lib/spack/spack/directives.py b/lib/spack/spack/directives.py
--- a/lib/spack/spack/directives.py
+++ b/lib/spack/spack/directives.py
@@ -212,7 +212,10 @@ def _depends_on(pkg, spec, when=None, type=None):
 
 @directive(('dependencies', '_deptypes'))
 def depends_on(pkg, spec, when=None, type=None):
-    """Creates a dict of deps with specs defining when they apply."""
+    """Creates a dict of deps with specs defining when they apply.
+    This directive is to be used inside a Package definition to declare
+    that the package requires other packages to be built first.
+    @see The section "Dependency specs" in the Spack Packaging Guide."""
     _depends_on(pkg, spec, when=when, type=type)
 
 
diff --git a/lib/spack/spack/package.py b/lib/spack/spack/package.py
--- a/lib/spack/spack/package.py
+++ b/lib/spack/spack/package.py
@@ -482,8 +482,13 @@ def nearest_url(self, version):
 
     # TODO: move this out of here and into some URL extrapolation module?
     def url_for_version(self, version):
-        """
-        Returns a URL that you can download a new version of this package from.
+        """Returns a URL from which the specified version of this package
+        may be downloaded.
+
+        version: class Version
+            The version for which a URL is sought.
+
+        See Class Version (version.py)
         """
         if not isinstance(version, Version):
             version = Version(version)


Test patch: