updating documentation for CTest

Author: alberto-scolari

README.md

@@ -62,7 +62,11 @@ To compile ALP, you need the following tools:
 2. LibNUMA development headers
 3. POSIX threads development headers
 4. [CMake](https://cmake.org/download/) version 3.13 or higher, with GNU Make
-(CMake's default build tool on UNIX systems) or any other supported build tool.
+  (CMake's default build tool on UNIX systems) or any other supported build
+   tool
+5. [Python3](https://www.python.org/) for the testing and (optionally) coverage
+   infrastructure; if your distribution does not provide it, you may download
+   [pre-built binaries](https://github.com/indygreg/python-build-standalone/releases)
 
 ## Linking and run-time
 The ALP libraries link against the following libraries:
@@ -100,7 +104,8 @@ For generating the code documentations:
 
 ## Code coverage
 
-For code/test coverage, a native implementation is available using the CMake infrastructure, using `gcovr` and `gcov`/`lcov`.
+For code/test coverage, a native implementation is available using the CMake
+infrastructure, using `gcovr` and `gcov`/`lcov`.
 
 
 # Very quick start
@@ -230,6 +235,8 @@ and lists technical papers.
 - [Development in ALP](#development-in-alp)
 - [Acknowledgements](#acknowledgements)
 - [Citing ALP, ALP/GraphBLAS, and ALP/Pregel](#citing-alp-alpgraphblas-and-alppregel)
+  - [ALP and ALP/GraphBLAS](#alp-and-alpgraphblas)
+  - [ALP/Pregel](#alppregel)
 
 
 # Configuration

docs/Build_and_test_infra.md

@@ -22,7 +22,7 @@ limitations under the License.
     - [Direct Generation via `cmake`](#direct-generation-via-cmake)
     - [CMake Build Options, Types and Flags](#cmake-build-options-types-and-flags)
   - [Naming conventions for targets](#naming-conventions-for-targets)
-  - [Adding a new test](#adding-a-new-test)
+  - [Adding a new test executable](#adding-a-new-test-executable)
   - [Adding a new backend](#adding-a-new-backend)
     - [1. Add the related project options](#1-add-the-related-project-options)
     - [2. Add the backend-specific variables](#2-add-the-backend-specific-variables)
@@ -154,7 +154,7 @@ As from above, a convenient way to start even for a custom build is from the
 the building command and start from there with the custom options.
 For example:
 
-```cmake
+```bash
 mkdir build_release
 cd build_release
 cmake -DCMAKE_INSTALL_PREFIX=/path/to/install/dir -DCMAKE_BUILD_TYPE=Release \
@@ -339,7 +339,7 @@ Other targets:
 standard tools are available, they are compiled into a PDF found at
 `<ALP/GraphBLAS root>/docs/code/latex/refman.pdf`.
 
-## Adding a new test
+## Adding a new test executable
 
 Test sources are split in categories, whose purpose is explained in the [Testing
 Infrastructure](#the-testing-infrastructure) section.
@@ -371,7 +371,8 @@ the test source files (at least one is required)
 * `BACKENDS reference reference_omp bsp1d hybrid` is the list of all backends
 the test should be compiled against (at least one is required); for each
 backend, an executable target is created following the naming conventions in
-[Naming conventions for targets](#naming-conventions-for-targets)
+[Naming conventions for targets](#naming-conventions-for-targets); also `none`
+is possible as backend name, meaning no backend is actually linked
 * `ADDITIONAL_LINK_LIBRARIES test_utils` (optional) lists additional libraries
 to link (the backend library is linked by default)
 * `COMPILE_DEFINITIONS MY_TEST_KEY=VALUE ANOTHER_TEST_DEFINITION` (optional)
@@ -396,14 +397,6 @@ Each script is sub-divided in several sections depending on the backend that is
 assumed to run and on relevant options: hence, you should place your test
 invocation in the relevant section.
 
-Furthermore, you can achieve more control over the test target generation, i.e.,
-the building of tests, by using the function `add_grb_tests_with_category`, also
-defined in [cmake/AddGRBTests.cmake](../cmake/AddGRBTests.cmake), which requires
-to specify dependencies manually (thus, building against multiple backends needs
-correspondingly multiple calls of the same function) and is therefore used only
-in special cases.
-
-
 ## Adding a new backend
 
 Adding a new backend requires multiple changes to the building infrastructure,
@@ -515,7 +508,7 @@ by default when compiling executables, for example
 4. the variable `ALL_BACKENDS` lists all possible backends (even if not enabled)
 to detect potential configuration errors: therefore, you should always add the
 new backend to this variable; on the contrary, the variable `AVAILABLE_BACKENDS`
-lists only the backends actually available in the building infrastructure, 
+lists only the backends actually available in the building infrastructure,
 depending on the user's inputs; you may add your backend with something like
 
     ```cmake
@@ -525,8 +518,8 @@ depending on the user's inputs; you may add your backend with something like
     ```
 
 5. the variable `AVAILABLE_TEST_BACKENDS` lists all backends that were enabled
-and for which tests are built; usually it is a subset of `AVAILABLE_BACKENDS`, 
-which also contains backends pulled in as dependencies of user-chosen backends; 
+and for which tests are built; usually it is a subset of `AVAILABLE_BACKENDS`,
+which also contains backends pulled in as dependencies of user-chosen backends;
 for example, if the user enables only the hyperdags backend, the reference
 backend is also listed in `AVAILABLE_BACKENDS`, while `AVAILABLE_TEST_BACKENDS`
 lists only hyperdags.
@@ -876,7 +869,8 @@ The coverage infrastructure prescribes additional dependencies:
   -- though the first method is preferable as it provides a more up-to-date
   version) and clearly requires
 * [Python3](https://www.python.org/), available in most Linux distributions
-  (e.g., `apt-get install python3`) or as [pre-built binary](https://github.com/indygreg/python-build-standalone/releases)
+  (e.g., `apt-get install python3`) or as
+  [pre-built binary](https://github.com/indygreg/python-build-standalone/releases)
   for many OSs and architectures
   (e.g., https://github.com/indygreg/python-build-standalone/releases/download/20230116/cpython-3.11.1+20230116-x86_64_v4-unknown-linux-gnu-install_only.tar.gz)
 

docs/README.md

@@ -22,6 +22,7 @@ limitations under the License.
 
 * the [Development Guidelines](Development.md) to read about ALP/GraphBLAS'
 development philosophy and work with its codebase
+* the [directory structure of the project](Directory_structure.md)
 * the
 [guide to the Building and Testing Infrastructure](Build_and_test_infra.md)
 * the
@@ -30,4 +31,4 @@ development philosophy and work with its codebase
 infrastructure (`make docs`) and available in the subdirectory `code`
 * the
 [guide to use ALP/GraphBLAS in your own project](Use_ALPGraphBLAS_in_your_own_project.md)
-* the [directory structure of the project](Directory_structure.md)
+* technical details for the [Nonblocking backend](Nonblocking_backend.md).