DOC, BUILD: make build_src more discoverable

3 files changed, 21 insertions, 3 deletions

diff --git a/doc/DISTUTILS.rst.txt b/doc/DISTUTILS.rst.txt
index eadde63f8..bcef82500 100644
--- a/doc/DISTUTILS.rst.txt
+++ b/doc/DISTUTILS.rst.txt
@@ -243,7 +243,7 @@ in writing setup scripts:
   after processing all source generators, no extension module will
   be built. This is the recommended way to conditionally define
   extension modules. Source generator functions are called by the
-  ``build_src`` command of ``numpy.distutils``.
+  ``build_src`` sub-command of ``numpy.distutils``.
 
   For example, here is a typical source generator function::
 
diff --git a/doc/source/dev/development_environment.rst b/doc/source/dev/development_environment.rst
index ce571926e..9d618cc9f 100644
--- a/doc/source/dev/development_environment.rst
+++ b/doc/source/dev/development_environment.rst
@@ -96,6 +96,11 @@ installs a ``.egg-link`` file into your site-packages as well as adjusts the
 Other build options
 -------------------
 
+Build options can be discovered by running any of::
+
+    $ python setup.py --help
+    $ python setup.py --help-commands
+
 It's possible to do a parallel build with ``numpy.distutils`` with the ``-j`` option;
 see :ref:`parallel-builds` for more details.
 
@@ -106,6 +111,16 @@ source tree is to use::
     $ export PYTHONPATH=/some/owned/folder/lib/python3.4/site-packages
 
 
+NumPy uses a series of tests to probe the compiler and libc libraries for
+funtions. The results are stored in ``_numpyconfig.h`` and ``config.h`` files
+using ``HAVE_XXX`` definitions. These tests are run during the ``build_src``
+phase of the ``_multiarray_umath`` module in the ``generate_config_h`` and
+``generate_numpyconfig_h`` functions. Since the output of these calls includes
+many compiler warnings and errors, by default it is run quietly. If you wish
+to see this output, you can run the ``build_src`` stage verbosely::
+
+    $ python build build_src -v
+
 Using virtualenvs
 -----------------
 
diff --git a/setup.py b/setup.py
index 640105ed0..f778d7409 100755
--- a/setup.py
+++ b/setup.py
@@ -215,6 +215,7 @@ class concat_license_files():
 
 
 from distutils.command.sdist import sdist
+from numpy.distutils.command.build_src import build_src
 class sdist_checked(sdist):
     """ check submodules on sdist to prevent incomplete tarballs """
     def run(self):
@@ -263,7 +264,7 @@ def parse_setuppy_commands():
     # below and not standalone.  Hence they're not added to good_commands.
     good_commands = ('develop', 'sdist', 'build', 'build_ext', 'build_py',
                      'build_clib', 'build_scripts', 'bdist_wheel', 'bdist_rpm',
-                     'bdist_wininst', 'bdist_msi', 'bdist_mpkg')
+                     'bdist_wininst', 'bdist_msi', 'bdist_mpkg', 'build_src')
 
     for command in good_commands:
         if command in args:
@@ -403,7 +404,9 @@ def setup_package():
         classifiers=[_f for _f in CLASSIFIERS.split('\n') if _f],
         platforms = ["Windows", "Linux", "Solaris", "Mac OS-X", "Unix"],
         test_suite='nose.collector',
-        cmdclass={"sdist": sdist_checked},
+        cmdclass={"sdist": sdist_checked,
+                  "build_src": build_src,
+                 },
         python_requires='>=3.5',
         zip_safe=False,
         entry_points={