Skip to content

doc: streamline build.md #3395

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

doc: streamline build.md #3395

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
224 changes: 52 additions & 172 deletions doc/build/build.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,152 +8,100 @@ or clone [the repository](https://github.com/uxlfoundation/oneDNN.git).

~~~sh
git clone https://github.com/uxlfoundation/oneDNN.git
cd oneDNN
Copy link
Contributor

@ranukund ranukund Jun 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

~~~

## Build the Library

### Set up the environment for the compiler
## Generate the build system
Copy link
Contributor

@ranukund ranukund Jun 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


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.

### Generate the build system

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`).

- `CMAKE_PREFIX_PATH` to specify directories to be searched for the
dependencies located at non-standard locations.

See @ref dev_guide_build_options for detailed description of build-time
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

#### GCC, Clang, or Intel oneAPI DPC++/C++ Compiler

- Set up the environment for the compiler

~~~sh
# 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
~~~

- Generate the build system

~~~sh
mkdir -p build ; cd build
cmake ..
~~~

- Build the library
### Windows

~~~sh
# Some generators, like Unix Makefiles, might default to single-threaded
# compilation. Parallelization can be controlled with:
cmake --build . --parallel $(nproc)
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.

#### Intel oneAPI DPC++/C++ Compiler with SYCL runtime
~~~bat
mkdir build
cd build
cmake .. -G "Visual Studio 17 2022"
~~~

- Set up the environment for the compiler
### Intel oneAPI DPC++/C++ Compiler with SYCL runtime

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

#### Linux
~~~sh
source /opt/intel/oneapi/setvars.sh

# Set Intel oneAPI DPC++/C++ Compiler as default C and C++ compilers
export CC=icx
export CXX=icpx
~~~

- Generate the build system

~~~sh
mkdir -p build ; cd build
cmake .. -DDNNL_CPU_RUNTIME=SYCL \
-DDNNL_GPU_RUNTIME=SYCL
~~~

#### Windows
~~~bat
"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

mkdir build
cd build
cmake .. -G Ninja ^
-DDNNL_CPU_RUNTIME=SYCL ^
-DDNNL_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.

- Build the library

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

#### GCC targeting AArch64 on x64 host

- Set up the environment for the compiler
### GCC targeting AArch64 on x64 host

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

- Generate the build system

~~~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
cmake --build . --parallel $(nproc)
~~~

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

- Set up the environment for the compiler
### GCC with Arm Compute Library (ACL) on AArch64 host

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
Expand All @@ -163,48 +111,29 @@ installed.
export ACL_ROOT_DIR=<path/to/ComputeLibrary>
export CC=gcc
export CXX=g++
~~~

- Generate the build system

~~~sh
mkdir -p build ; cd build
cmake .. -DDNNL_AARCH64_USE_ACL=ON
~~~

- Build the library
## Build the Library

### Linux

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

### Windows

#### Microsoft Visual C++ Compiler

- 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
### macOS

~~~bat
mkdir build
cd build
cmake .. -G "Visual Studio 17 2022"
~~~sh
cmake --build . --parallel $(sysctl -n hw.ncpu)
~~~

- Build the library
### Windows

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

@note Currently, the oneDNN build system has limited support for multi-config
Expand All @@ -215,53 +144,11 @@ cmake --build . --config=Release
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 You can also open `oneDNN.sln` to build the project from the
Microsoft Visual Studio IDE.

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

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

- Generate the build system

~~~bat
mkdir build
cd build

cmake .. -G Ninja ^
-DDNNL_CPU_RUNTIME=SYCL ^
-DDNNL_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.

- Build the library

~~~bat
cmake --build .
~~~
@note You can also open `oneDNN.sln` to build the project directly from the
Microsoft Visual Studio IDE.

## Validate the Build

Expand All @@ -280,13 +167,6 @@ 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).

@warning
When using the `/opt/intel/oneapi/setvars.sh` script from the Intel oneAPI Toolkit,
Expand Down