doc: extend build.md documentation

CONTRIBUTING.md

@@ -147,7 +147,8 @@ Use the following command to run tests selected by a build configuration:
 
 To modify the coverage, use the
 [`ONEDNN_TEST_SET`](https://uxlfoundation.github.io/oneDNN/dev_guide_build_options.html#onednn-test-set)
-build option.
+build option. More information with examples can be found in [build guide](https://uxlfoundation.github.io/oneDNN/dev_guide_build.html#validate-the-build).
+Before submitting any code, it is advised to run the `NIGHTLY` test set.
 
 More details on how to run benchdnn can be found in
 [benchdnn documentation](tests/benchdnn/doc/benchdnn_general_info.md#running-tests).

doc/build/build.md

@@ -12,12 +12,31 @@ git clone https://github.com/uxlfoundation/oneDNN.git
 
 ## Build the Library
 
+### Set up the environment for the compiler
+
 Ensure that all [software dependencies](https://github.com/uxlfoundation/oneDNN#requirements-for-building-from-source)
 are in place and have at least the minimal supported version.
 
-The oneDNN build system is based on CMake. Use
+### Generate the build system
 
-- `CMAKE_INSTALL_PREFIX` to control the library installation location,
+The oneDNN build system is based on [CMake](https://cmake.org/cmake/help/latest/manual/cmake.1.html). Use the following command to generate a build system:
+~~~sh
+cmake -B <path-to-build> [-S <path-to-source>] [<options>]
+~~~
+In most cases, both `-B` and `-S` options are skipped with the assumption that
+`<path-to-build>` is the current folder and `<path-to-source>` is the one
+higher in the tree:
+~~~sh
+cd <path-to-onednn-source>
+mkdir -p build ; cd build
+cmake .. [<options>]
+~~~
+The following are a few useful options defined by CMake:
+
+- `G` to specify build system generator (e.g. `"Visual Studio 17 2022"`,
+  `Ninja`, `"Unix Makefiles"`).
+
+- `CMAKE_INSTALL_PREFIX` to control the library installation location.
 
 - `CMAKE_BUILD_TYPE` to select between build type (`Release`, `Debug`,
   `RelWithDebInfo`).
@@ -26,7 +45,16 @@ The oneDNN build system is based on CMake. Use
   dependencies located at non-standard locations.
 
 See @ref dev_guide_build_options for detailed description of build-time
-configuration options.
+configuration options defined by oneDNN.
+
+### Build the library
+
+CMake provides a unified method for building a project, independent of the
+generator or operating system used:
+~~~sh
+cmake --build <path-to-build> [<options>]
+~~~
+Full list of options can be found [here](https://cmake.org/cmake/help/latest/manual/cmake.1.html#build-a-project).
 
 ### Linux/macOS
 
@@ -34,48 +62,57 @@ configuration options.
 
 - Set up the environment for the compiler
 
-- Configure CMake and generate makefiles
 ~~~sh
-mkdir -p build
+# Uncomment the following lines to build with GCC
-cd build
+# export CC=gcc
+# export CXX=g++
 
 # Uncomment the following lines to build with Clang
 # export CC=clang
 # export CXX=clang++
 
-# Uncomment the following lines to build with Intel oneAPI DPC++/C++ Compiler
+# Uncomment the following lines to build with Intel oneAPI DPC++/C++ Compiler (x64 only)
 # export CC=icx
 # export CXX=icpx
-cmake .. <extra build options>
+~~~
+
+- Generate the build system
+
+~~~sh
+mkdir -p build ; cd build
+cmake ..
 ~~~
 
 - Build the library
+
 ~~~sh
-make -j$(nproc)
+# Some generators, like Unix Makefiles, might default to single-threaded
+# compilation. Parallelization can be controlled with:
+cmake --build . --parallel $(nproc)
 ~~~
 
 #### Intel oneAPI DPC++/C++ Compiler with SYCL runtime
 
-- Set up the environment for Intel oneAPI DPC++/C++ Compiler
+- Set up the environment for the compiler
-  using the `setvars.sh` script. The command below assumes you installed to the
+
-  default folder. If you customized the installation folder, setvars.sh (Linux/macOS)
+Intel oneAPI DPC++/C++ Compiler uses the `setvars.sh` script to set all
-  is in your custom folder:
+required variables. The command below assumes you installed to the default
+folder. If you customized the installation folder, `setvars.sh` (Linux/macOS)
+is in your custom folder.
 ~~~sh
 source /opt/intel/oneapi/setvars.sh
-~~~
-
-- Configure CMake and generate makefiles
-~~~sh
-mkdir -p build
-cd build
 
+# Set Intel oneAPI DPC++/C++ Compiler as default C and C++ compilers
 export CC=icx
 export CXX=icpx
+~~~
 
-cmake .. \
+- Generate the build system
-          -DDNNL_CPU_RUNTIME=SYCL \
+
-          -DDNNL_GPU_RUNTIME=SYCL \
+~~~sh
-          <extra build options>
+mkdir -p build ; cd build
+cmake .. -DDNNL_CPU_RUNTIME=SYCL \
+         -DDNNL_GPU_RUNTIME=SYCL
 ~~~
 
 @note Open-source version of oneAPI DPC++ Compiler does not have the icx driver,
@@ -85,59 +122,87 @@ environment variable of the same name to specify path to the OpenCL runtime if
 it is installed in a custom location.
 
 - Build the library
+
 ~~~sh
-make -j$(nproc)
+cmake --build . --parallel $(nproc)
 ~~~
 
 #### GCC targeting AArch64 on x64 host
 
 - Set up the environment for the compiler
 
-- Configure CMake and generate makefiles
 ~~~sh
 export CC=aarch64-linux-gnu-gcc
 export CXX=aarch64-linux-gnu-g++
-cmake .. \
+~~~
-          -DCMAKE_SYSTEM_NAME=Linux \
+
-          -DCMAKE_SYSTEM_PROCESSOR=AARCH64 \
+- Generate the build system
-          -DCMAKE_LIBRARY_PATH=/usr/aarch64-linux-gnu/lib \
+
-          <extra build options>
+~~~sh
+mkdir -p build ; cd build
+cmake .. -DCMAKE_SYSTEM_NAME=Linux \
+         -DCMAKE_SYSTEM_PROCESSOR=AARCH64 \
+         -DCMAKE_LIBRARY_PATH=/usr/aarch64-linux-gnu/lib
 ~~~
 
 - Build the library
+
 ~~~sh
-make -j$(nproc)
+cmake --build . --parallel $(nproc)
 ~~~
 
 #### GCC with Arm Compute Library (ACL) on AArch64 host
 
 - Set up the environment for the compiler
 
-- Configure CMake and generate makefiles
+Download [Arm Compute Library](https://github.com/ARM-software/ComputeLibrary)
+or build it from source and set `ACL_ROOT_DIR` to directory where it is
+installed.
+
 ~~~sh
-export ACL_ROOT_DIR=<path/to/Compute Library>
+export ACL_ROOT_DIR=<path/to/ComputeLibrary>
-cmake .. \
+export CC=gcc
-          -DDNNL_AARCH64_USE_ACL=ON \
+export CXX=g++
-          <extra build options>
+~~~
+
+- Generate the build system
+
+~~~sh
+mkdir -p build ; cd build
+cmake .. -DDNNL_AARCH64_USE_ACL=ON
 ~~~
 
 - Build the library
+
 ~~~sh
-make -j$(nproc)
+cmake --build . --parallel $(nproc)
 ~~~
 
 ### Windows
 
 #### Microsoft Visual C++ Compiler
 
-- Generate a Microsoft Visual Studio solution
+- Set up the environment for the compiler
+
+Microsoft Visual Studio uses the `VsDevCmd.bat` script to set all
+required variables. The command below assumes you installed to the default
+folder. If you customized the installation folder, `VsDevCmd.bat` is in your
+custom folder.
+~~~bat
+"C:\Program Files\Microsoft Visual Studio\2022\Professional\Common7\Tools\VsDevCmd.bat" -startdir=none -arch=x64 -host_arch=x64
+~~~
+or open `x64 Native Tools Command Prompt` from start menu instead.
+
+- Generate the build system
+
 ~~~bat
 mkdir build
 cd build
-cmake -G "Visual Studio 16 2019" ..
+cmake .. -G "Visual Studio 17 2022"
 ~~~
 
 - Build the library
+
 ~~~bat
 cmake --build . --config=Release
 ~~~
@@ -155,26 +220,30 @@ Microsoft Visual Studio IDE.
 
 #### Intel oneAPI DPC++/C++ Compiler with SYCL Runtime
 
-- Set up the environment for Intel oneAPI DPC++/C++ Compiler
+- Set up the environment for the compiler
-  using the `setvars.bat` script. The command below assumes you installed to the
+
-  default folder. If you customized the installation folder, setvars.bat
+Intel oneAPI DPC++/C++ Compiler uses the `setvars.bat` script to set all
-  is in your custom folder:
+required variables. The command below assumes you installed to the default
+folder. If you customized the installation folder, `setvars.bat` is in your
+custom folder.
 ~~~bat
 "C:\Program Files (x86)\Intel\oneAPI\setvars.bat"
-~~~
-or open `Intel oneAPI Commmand Prompt` instead.
 
-- Configure CMake and generate Ninja project
+:: Set Intel oneAPI DPC++/C++ Compiler as default C and C++ compilers
+set CC=icx
+set CXX=icx
+~~~
+or open `Intel oneAPI Commmand Prompt` from start menu instead.
+
+- Generate the build system
+
 ~~~bat
 mkdir build
 cd build
 
-:: Set C and C++ compilers
+cmake .. -G Ninja ^
-set CC=icx
+         -DDNNL_CPU_RUNTIME=SYCL ^
-set CXX=icx
+         -DDNNL_GPU_RUNTIME=SYCL
-cmake .. -G Ninja -DDNNL_CPU_RUNTIME=SYCL ^
-                  -DDNNL_GPU_RUNTIME=SYCL ^
-                  <extra build options>
 ~~~
 
 @warning Intel oneAPI DPC++/C++ Compiler on Windows requires CMake v3.23 or later.
@@ -189,16 +258,35 @@ environment variable of the same name to specify path to the OpenCL runtime if
 it is installed in a custom location.
 
 - Build the library
+
 ~~~bat
 cmake --build .
 ~~~
 
 ## Validate the Build
 
-If the library is built for the host system, you can run unit tests using:
+After building the library, you can run a predefined test set using:
 ~~~sh
 ctest
 ~~~
+The [`ONEDNN_TEST_SET`](https://uxlfoundation.github.io/oneDNN/dev_guide_build_options.html#onednn-test-set)
+build option set during the build configuration determines determines the scope
+and depth of the test set. Useful values are `SMOKE` (smallest set), `CI`
+(default), and `NIGHTLY` (most comprehensive). The test set can be reconfigured
+after the entire project has been built, and only the missing tests will be
+compiled.
+~~~sh
+cmake .. -DONEDNN_TEST_SET=NIGHTLY
+cmake --build .
+ctest
+~~~
+ctest supports filtering the test set by using the `-R` option. For example,
+to run only the GPU tests, use:
+~~~sh
+ctest -R gpu
+~~~
+Another useful option is `--output-on-failure`, which will print verbose output
+in case a test fails. Full set of options can be found [here](https://cmake.org/cmake/help/latest/manual/ctest.1.html).
 
 ## Build documentation