Merge topic 'doc-test-layout'

1c547152 Tests: Document test directory layout in a README.rst
4e3483c0 Help/dev: Update source code guide to cover source tree layout

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !967

Help/dev/source.rst

@@ -58,3 +58,50 @@ need to be handled with care:
   When assigning the result of ``.size()`` on a container for example,
   the result should be assigned to ``size_t`` not to ``std::size_t``,
   ``unsigned int`` or similar types.
+
+Source Tree Layout
+==================
+
+The CMake source tree is organized as follows.
+
+* ``Auxiliary/``:
+  Shell and editor integration files.
+
+* ``Help/``:
+  Documentation.
+
+  * ``Help/dev/``:
+    Developer documentation.
+
+  * ``Help/release/dev/``:
+    Release note snippets for development since last release.
+
+* ``Licenses/``:
+  License files for third-party libraries in binary distributions.
+
+* ``Modules/``:
+  CMake language modules installed with CMake.
+
+* ``Packaging/``:
+  Files used for packaging CMake itself for distribution.
+
+* ``Source/``:
+  Source code of CMake itself.
+
+* ``Templates/``:
+  Files distributed with CMake as implementation details for generators,
+  packagers, etc.
+
+* ``Tests/``:
+  The test suite.  See `Tests/README.rst`_.
+
+* ``Utilities/``:
+  Scripts, third-party source code.
+
+  * ``Utilities/Sphinx/``:
+    Sphinx configuration to build CMake user documentation.
+
+  * ``Utilities/Release/``:
+    Scripts used to package CMake itself for distribution on ``cmake.org``.
+
+.. _`Tests/README.rst`: ../../Tests/README.rst

Tests/README

@@ -1,39 +0,0 @@
-If you think about adding a new testcase then here is a small checklist you
-can run through to find a proper place for it. Go through the list from the
-beginning and stop once you find something that matches your tests needs,
-i.e. if you will test a module and only need the configure mode use the
-instructions from section 2, not 3.
-
-1. Your testcase can run in CMake script mode, i.e. "cmake -P something"
-
-Put your test in Tests/CMakeTests/ directory as a .cmake.in file. It will be
-put into the test binary directory by configure_file(... @ONLY) and run from
-there. Use the AddCMakeTest() macro in Tests/CMakeTests/CMakeLists.txt to add
-your test to the test runs.
-
-2. Your test needs CMake to run in configure mode, but will not build anything
-
-This includes tests that will build something using try_compile() and friends,
-but nothing that expects add_executable(), add_library(), or add_test() to run.
-
-If the test configures the project only once and it must succeed then put it
-into the Tests/CMakeOnly/ directory.  Create a subdirectory named like your
-test and write the CMakeLists.txt you need into that subdirectory. Use the
-add_CMakeOnly_test() macro from Tests/CMakeOnly/CMakeLists.txt to add your
-test to the test runs.
-
-If the test configures the project with multiple variations and verifies
-success or failure each time then put it into the Tests/RunCMake/ directory.
-Read the instructions in Tests/RunCMake/CMakeLists.txt to add a test.
-
-3. If you are testing something from the Modules directory
-
-Put your test in the Tests/Modules/ directory. Create a subdirectory there
-named after your test. Use the ADD_TEST_MACRO macro from Tests/CMakeLists.txt
-to add your test to the test run. If you have put your stuff in
-Tests/Modules/Foo then you call it using ADD_TEST_MACRO(Module.Foo Foo).
-
-4. You are doing other stuff.
-
-Find a good place ;) In doubt mail to cmake-developers@cmake.org and ask for
-advise.

Tests/README.rst

@@ -0,0 +1,31 @@
+CMake Tests Directory
+*********************
+
+This directory contains the CMake test suite.
+See also the `CMake Source Code Guide`_.
+
+.. _`CMake Source Code Guide`: ../Help/dev/source.rst
+
+Many tests exist as immediate subdirectories, but some tests
+are organized as follows.
+
+* ``CMakeLib/``:
+  Source code, used for tests, that links to the ``CMakeLib`` library
+  defined over in ``Source/``.
+
+* ``CMakeOnly/``:
+  Deprecated.  Tests that run CMake to generate a project but not build it.
+  Superseded by ``Tests/RunCMake/``.
+
+* ``Find*/``:
+  Tests for specific find modules that can only be run on machines with
+  the corresponding packages installed.  They are enabled in
+  ``CMakeLists.txt`` by undocumented options used on CI builds.
+
+* ``Module/``:
+  Tests for specific CMake modules.
+
+* ``RunCMake/``:
+  Tests that run CMake and/or other tools while precisely checking
+  their return code and stdout/stderr content.  Useful for testing
+  error cases and diagnostic output.