doc: streamline build.md

[spalicki]

No description provided.

[ranukund]

As mentioned in the chat to Stefan, there are certain structural issues.

• Do we need to set the environment variables for GCC/Clang when generating the build system? I think we still need to retain that information.

• The grouping under the Genrate the build section seems to be a bit off. We begin with OS (linux/Windows), then we have compiler specific, then we have a cross compilation scenario. I think being consistent will help here. For example,

Linux/macOS
Compiler 1
Compiler 2
Compiler 1 with AARch
Compiler 1 with ACL on AArch64
Windows
Compiler 1
Compiler 2

• We could think of Build Options being the reference page and move the options defined by Cmake in there and have a link from the build from source guide wherever relevant.

[ranukund]

I understand we want to streamline the build instructions and keep it clean and avoid clutter as much as possible. We can perhaps move the options defined by CMake in the Build options page. Does the following work? Any thoughts? @spalicki . should we keep pursuing this option or go back to the other PR 3380?

Build from Source {#dev_guide_build}

Prerequisites
Ensure that all software dependencies
are in place and have at least the minimal supported version.

Step 1. Download the Source Code

Download oneDNN source code
or clone the repository.

git clone https://github.com/uxlfoundation/oneDNN.git
cd oneDNN

Step 2: Generate the build system

Build on Linux/macOS

Use GCC/Clang/Intel DPC++ Compiler

1. Set up the environment for the compiler

   # Uncomment the following lines to build with GCC
   # 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 (x64 only)
   # export CC=icx
   # export CXX=icpx

2. Generate the build system

   mkdir -p build ; cd build
   cmake ..

   If you want to customize the CMake buildsystem, refer to the CMake options on the Build Options.

Use Intel oneAPI DPC++/C++ Compiler with SYCL runtime

1. Set up the environment for the compiler

   Intel oneAPI DPC++/C++ Compiler uses the setvars.sh script to set all the
   required variables. The command below assumes you installed the compiler to the default
   folder. If you customized the installation folder, setvars.sh (Linux/macOS)
   is in your custom folder.

   source /opt/intel/oneapi/setvars.sh
   
   # Set Intel oneAPI DPC++/C++ Compiler as default C and C++ compilers
   export CC=icx
   export CXX=icpx

2. Generate the build system

   mkdir -p build ; cd build
   cmake .. -DONEDNN_CPU_RUNTIME=SYCL \
         -DONEDNN_GPU_RUNTIME=SYCL

See @ref dev_guide_build_options for detailed description of build-time
configuration options defined by oneDNN.
@note Open-source version of oneAPI DPC++ Compiler does not have the icx driver,
use clang/clang++ instead. Open-source version of oneAPI DPC++ Compiler may not
contain OpenCL runtime. In this case, you can use OPENCLROOT CMake option or
environment variable of the same name to specify path to the OpenCL runtime if
it is installed in a custom location.

Use GCC targeting AArch64 on x64 host

1. Set up the environment for the compiler

   export CC=aarch64-linux-gnu-gcc
   export CXX=aarch64-linux-gnu-g++

2. Generate the build system

   mkdir -p build ; cd build
   cmake .. -DCMAKE_SYSTEM_NAME=Linux \
         -DCMAKE_SYSTEM_PROCESSOR=AARCH64 \
         -DCMAKE_LIBRARY_PATH=/usr/aarch64-linux-gnu/lib

Use GCC with Arm Compute Library (ACL) on AArch64 host

1. Set up the environment for the compiler

   Download Arm Compute Library
   or build it from source and set ACL_ROOT_DIR to directory where it is
   installed.

   export ACL_ROOT_DIR=<path/to/ComputeLibrary>
   export CC=gcc
   export CXX=g++

2. Generate the build system

   mkdir -p build ; cd build
   cmake .. -DONEDNN_AARCH64_USE_ACL=ON

   See @ref dev_guide_build_options for detailed description of build-time
   configuration options defined by oneDNN.

Build on Windows

Use Microsoft Visual C++ Compiler

1. 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.

   "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.

2. Generate the build system

   mkdir build
   cd build
   cmake .. -G "Visual Studio 17 2022"

Use Intel oneAPI DPC++/C++ Compiler with SYCL Runtime

1. Set up the environment for the compiler

   Intel oneAPI DPC++/C++ Compiler uses the setvars.bat script to set all
   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.

   "C:\Program Files (x86)\Intel\oneAPI\setvars.bat"
   :: 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.

2. Generate the build system

   mkdir build
   cd build
   
   cmake .. -G Ninja ^
         -DONEDNN_CPU_RUNTIME=SYCL ^
         -DONEDNN_GPU_RUNTIME=SYCL

   @warning Intel oneAPI DPC++/C++ Compiler on Windows requires CMake v3.23 or later.

   @warning Intel oneAPI DPC++/C++ Compiler does not support CMake's Microsoft Visual
   Studio generator.

   @note Open-source version of oneAPI DPC++ Compiler does not have the icx driver,
   use clang/clang++ instead. Open-source version of oneAPI DPC++ Compiler may not
   contain OpenCL runtime. In this case, you can use OPENCLROOT CMake option or
   environment variable of the same name to specify path to the OpenCL runtime if
   it is installed in a custom location.

Step 3. Build the Library

Linux

cmake --build . --parallel $(nproc)

macOS

cmake --build . --parallel $(sysctl -n hw.ncpu)

Windows

cmake --build . --config=Release --parallel %NUMBER_OF_PROCESSORS%

@note Currently, the oneDNN build system has limited support for multi-config
generators. Build configuration is based on the CMAKE_BUILD_TYPE option
(Release by default), and CMake must be rerun from scratch every time
the build type changes to apply the new build configuration. You can choose
a specific build type with the --config option (the solution file supports
both Debug and Release builds), but it must refer to the same build type
(Release, Debug, etc.) as selected with the CMAKE_BUILD_TYPE option.

@note If Intel oneAPI DPC++/C++ Compiler is used the --config=Release can
be skipped.

@note You can also open oneDNN.sln to build the project directly from the
Microsoft Visual Studio IDE.

Validate the Build

After building the library, you can run a predefined test set using:

ctest

The ONEDNN_TEST_SET
build option set during the build configuration 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.

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:

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.

@warning
When using the /opt/intel/oneapi/setvars.sh script from the Intel oneAPI toolkit,
LD_LIBRARY_PATH is set to include the oneDNN library path from the installation.
Make sure the correct oneDNN library is present in
LD_LIBRARY_PATH by setting it explicitly if needed.

Step 4. (Optional) Build Documentation

1. Install the requirements

   conda env create -f ../doc/environment.yml
   conda activate onednn-doc

2. Build the documentation

   cmake --build . --target doc

Step 5. Install the Library

Install the library, headers, and documentation.

@note
The install directory is specified by the CMAKE_INSTALL_PREFIX
CMake variable. When installing in the default directory, the following command
needs to be run with administrative privileges using sudo on Linux/Mac or a
command prompt run as administrator on Windows.

cmake --build . --target install