bazel: add debug/sanitizer configs and expand build documentation

.bazelrc

@@ -110,3 +110,122 @@ build:dpc-private \
 
 test:dpc-private \
     --test_tag_filters="dpc,-public"
+
+
+# Configuration: 'release-dpc'
+# Build release artifacts including DPC++ libs.
+# The //:release target automatically builds all ISA variants when
+# --cpu is unset (auto). Use --cpu=<isa> to restrict for CI speed.
+#   bazel build //:release                       # CPU only, all ISAs
+#   bazel build //:release --config=release-dpc  # with DPC++ libs
+#   bazel build //:release --cpu=avx2            # CI: avx2 only
+build:release-dpc \
+    --release_dpc=true
+
+
+# Configuration: 'dev'
+# Fast local development build — compiles only for the host machine's
+# highest ISA (auto-detected). Use this to speed up iterative builds.
+# NOT suitable for release/packaging.
+#   bazel build //cpp/oneapi/dal:tests --config=dev
+build:dev \
+    --cpu=auto
+
+
+# =============================================================================
+# Debug and Sanitizer Configurations
+# Equivalent to Make REQDBG / REQSAN options
+# =============================================================================
+
+# Configuration: 'dbg'
+# Debug build with assertions enabled.
+# Equivalent to Make: REQDBG=1
+# Adds: -g debug symbols, -DDEBUG_ASSERT, -DONEDAL_ENABLE_ASSERT
+#   bazel build //:release --config=dbg
+#   bazel test //cpp/oneapi/dal:tests --config=dbg
+common:dbg \
+    --compilation_mode=dbg \
+    --enable_assert=True
+
+# Configuration: 'dbg-symbols'
+# Debug symbols only — no assertion checking, no -O0.
+# Equivalent to Make: REQDBG=symbols
+# Adds -g to the default opt build; preserves -O2/-O3 optimization.
+#   bazel build //:release --config=dbg-symbols
+common:dbg-symbols \
+    --copt=-g \
+    --cxxopt=-g
+
+
+# Configuration: 'asan'
+# AddressSanitizer build.
+# Equivalent to Make: REQSAN=address
+# Note: combine with --config=dbg for best results (Make recommendation).
+#   bazel test //cpp/oneapi/dal:tests --config=asan --config=dbg
+common:asan \
+    --copt=-fsanitize=address \
+    --copt=-fno-omit-frame-pointer \
+    --linkopt=-fsanitize=address \
+    --config=dbg-symbols
+
+# Configuration: 'asan-static'
+# AddressSanitizer with static libasan linkage.
+# Equivalent to Make: REQSAN=static
+common:asan-static \
+    --copt=-fsanitize=address \
+    --copt=-fno-omit-frame-pointer \
+    --linkopt=-fsanitize=address \
+    --linkopt=-static-libasan \
+    --config=dbg-symbols
+
+
+# Configuration: 'tsan'
+# ThreadSanitizer build.
+# Equivalent to Make: REQSAN=thread
+#   bazel test //cpp/oneapi/dal:tests --config=tsan
+common:tsan \
+    --copt=-fsanitize=thread \
+    --copt=-fno-omit-frame-pointer \
+    --linkopt=-fsanitize=thread \
+    --config=dbg-symbols
+
+
+# Configuration: 'ubsan'
+# UndefinedBehaviorSanitizer build.
+# Equivalent to Make: REQSAN=undefined
+#   bazel test //cpp/oneapi/dal:tests --config=ubsan
+common:ubsan \
+    --copt=-fsanitize=undefined \
+    --copt=-fno-omit-frame-pointer \
+    --linkopt=-fsanitize=undefined \
+    --config=dbg-symbols
+
+
+# =============================================================================
+# Custom flags
+# For injecting arbitrary compiler/linker flags (equivalent to Make COPT/CXXFLAGS):
+#   bazel build //:release --copt=-march=native
+#   bazel build //:release --copt=-O2
+#   bazel build //:release --linkopt=-Wl,--as-needed
+# Or persist in user-local ~/.bazelrc:
+#   build --copt=-your-flag
+# =============================================================================
+
+# Configuration: 'msan'
+# MemorySanitizer build.
+# Note: Requires Clang or ICPX. GCC does not support MSan.
+#   bazel test //cpp/oneapi/dal:tests --config=msan
+common:msan \
+    --copt=-fsanitize=memory \
+    --copt=-fsanitize-memory-track-origins \
+    --copt=-fno-omit-frame-pointer \
+    --linkopt=-fsanitize=memory \
+    --config=dbg-symbols
+
+# Configuration: 'type'
+# Type sanitizer build.
+common:type \
+    --copt=-fsanitize=type \
+    --copt=-fno-omit-frame-pointer \
+    --linkopt=-fsanitize=type \
+    --config=dbg-symbols

dev/bazel/README.md

@@ -373,3 +373,160 @@ dal_test_suite(
 
 ## What is missing in this guide
 - How to get make-like release structure
+
+## Debug and Sanitizer Builds
+
+### Debug build with assertions
+
+Equivalent to Make `REQDBG=1` — adds debug symbols, enables `DEBUG_ASSERT`
+and `ONEDAL_ENABLE_ASSERT`:
+
+```sh
+bazel build //:release --config=dbg
+bazel test //cpp/oneapi/dal:tests --config=dbg
+```
+
+### Debug symbols only (no assertion checks)
+
+Equivalent to Make `REQDBG=symbols`:
+
+```sh
+bazel build //:release --config=dbg-symbols
+```
+
+> Note: The `libonedal_dpc.so` library does not support debug mode due to
+> excessive debug information causing long link times. Use the static library
+> variant for DPC++ debugging.
+
+### AddressSanitizer (ASan)
+
+Equivalent to Make `REQSAN=address`. Sanitizers do not automatically enable assertions or unoptimized debug builds. It is highly recommended to combine them with `--config=dbg` (for full debug + assertions) or `--enable_assert=True`:
+
+```sh
+bazel test //cpp/oneapi/dal:tests --config=asan --config=dbg
+```
+
+For static libasan linkage (equivalent to Make `REQSAN=static`):
+
+```sh
+bazel test //cpp/oneapi/dal:tests --config=asan-static --config=dbg
+```
+
+### ThreadSanitizer (TSan)
+
+Equivalent to Make `REQSAN=thread`:
+
+```sh
+bazel test //cpp/oneapi/dal:tests --config=tsan
+```
+
+### UndefinedBehaviorSanitizer (UBSan)
+
+Equivalent to Make `REQSAN=undefined`:
+
+```sh
+bazel test //cpp/oneapi/dal:tests --config=ubsan
+```
+
+### MemorySanitizer (MSan)
+
+Requires Clang or ICPX. GCC does not support MSan.
+The `msan` config enables `-fsanitize-memory-track-origins` for better origin diagnostics.
+If your toolchain requires lld for MSan/TSan linking, add:
+
+```sh
+bazel test //cpp/oneapi/dal:tests --config=msan --linkopt=-fuse-ld=lld
+```
+
+### Type Sanitizer
+
+```sh
+bazel test //cpp/oneapi/dal:tests --config=type
+```
+
+
+---
+
+## Release Build
+
+Build the full release artifact (all ISA variants: sse2, sse42, avx2, avx512):
+
+```sh
+bazel build //:release
+```
+
+The `//:release` target automatically compiles all ISA variants when `--cpu`
+is left at its default value (`auto`). If `--cpu` is set explicitly — e.g. in
+a personal `~/.bazelrc` or passed in CI — the transition respects that value.
+To restrict ISA coverage (e.g., for faster CI):
+
+```sh
+bazel build //:release --cpu=avx2
+```
+
+To include DPC++ libraries:
+
+```sh
+bazel build //:release --config=release-dpc
+```
+
+---
+
+### Standard Library Assertions
+
+To enable C++ standard library assertions (e.g., `std::vector` bounds checking), inject the preprocessor macro via `--cxxopt` (C++-only flag):
+
+```sh
+bazel test //cpp/oneapi/dal:tests --config=dbg --cxxopt=-D_GLIBCXX_DEBUG
+```
+
+---
+
+## Custom Compiler and Linker Flags
+
+Equivalent to Make `COPT` / `CXXFLAGS`. Use `--copt` for C and C++ flags, `--cxxopt` for C++-only flags, and `--linkopt` for linker flags:
+
+```sh
+# Architecture/optimization flags (C and C++)
+bazel build //:release --copt=-march=native
+
+# Override optimization level (C and C++)
+bazel build //:release --copt=-O2
+
+# C++-only preprocessor/language flags
+bazel build //:release --cxxopt=-std=c++17
+
+# Add a linker flag
+bazel build //:release --linkopt=-Wl,--as-needed
+```
+
+To make flags permanent for your local environment, add them to `~/.bazelrc`:
+
+```
+# ~/.bazelrc (user-local, not committed)
+build --copt=-your-c-and-cxx-flag
+build --cxxopt=-your-cxx-only-flag
+build --linkopt=-your-link-flag
+```
+
+---
+
+## Make → Bazel Flag Reference
+
+| Make option | Bazel equivalent | Notes |
+|---|---|---|
+| `REQDBG=1` | `--config=dbg` | Debug symbols + assertions |
+| `REQDBG=symbols` | `--config=dbg-symbols` | Debug symbols only |
+| `REQSAN=address` | `--config=asan` | AddressSanitizer |
+| `REQSAN=static` | `--config=asan-static` | ASan with static libasan |
+| `REQSAN=thread` | `--config=tsan` | ThreadSanitizer |
+| `REQSAN=undefined` | `--config=ubsan` | UBSan |
+| | `--config=msan` | MemorySanitizer (Clang/ICPX only) |
+| | `--config=type` | Type Sanitizer |
+| `COMPILER=gnu` | `CC=gcc bazel build ...` | Override compiler via `CC` env |
+| `OPTFLAG=O2` | `--copt=-O2` | Override optimization level |
+| `COPT=-flag` | `--copt=-flag` (C+C++) / `--cxxopt=-flag` (C++ only) | Arbitrary compiler flag |
+| `--cpu=<isa>` (Make `PLAT`) | `--cpu=<isa>` | ISA selection |
+| (Make default all ISAs) | `bazel build //:release` | Transition forces all ISAs |
+| (CI: single ISA) | `--cpu=avx2` | Override for CI speed |
+