Rename cmake options with prefix OTELCPP_

.github/copilot-instructions.md

@@ -212,13 +212,13 @@ code.coverage                   # Build with coverage analysis
 Key options you can pass to `cmake ..`:
 
 ```bash
--DWITH_EXAMPLES=ON           # Build examples (default ON)
--DWITH_PROMETHEUS=ON         # Enable Prometheus exporter
--DWITH_ZIPKIN=ON            # Enable Zipkin exporter
--DWITH_OTLP_GRPC=ON         # Enable OTLP gRPC exporter
--DWITH_OTLP_HTTP=ON         # Enable OTLP HTTP exporter
--DBUILD_TESTING=ON          # Build tests (default ON)
--DCMAKE_BUILD_TYPE=Debug    # Debug build
+-DOTELCPP_WITH_EXAMPLES=ON       # Build examples (default ON)
+-DOTELCPP_WITH_PROMETHEUS=ON     # Enable Prometheus exporter
+-DOTELCPP_WITH_ZIPKIN=ON         # Enable Zipkin exporter
+-DOTELCPP_WITH_OTLP_GRPC=ON      # Enable OTLP gRPC exporter
+-DOTELCPP_WITH_OTLP_HTTP=ON      # Enable OTLP HTTP exporter
+-DOTELCPP_BUILD_TESTING=ON       # Build tests (default ON)
+-DCMAKE_BUILD_TYPE=Debug         # Debug build
 ```
 
 ## Timing Expectations

.github/workflows/ci.yml

@@ -75,6 +75,44 @@ jobs:
       run: |
         ./ci/do_ci.sh cmake.api_only.test
 
+  cmake_legacy_options_test:
+    name: CMake legacy option names compatibility test
+    runs-on: ubuntu-24.04
+    env:
+      CXX_STANDARD: '17'
+    steps:
+    - name: Harden the runner (Audit all outbound calls)
+      uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+      with:
+        egress-policy: audit
+
+    - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      with:
+        submodules: 'recursive'
+    - name: setup
+      run: |
+        sudo -E ./ci/setup_ci_environment.sh
+        sudo -E apt-get install -y zlib1g-dev libcurl4-openssl-dev
+    - name: install dependencies
+      run: |
+        sudo -E ./ci/install_thirdparty.sh --install-dir /usr/local --tags-file ./install/cmake/third_party_stable --packages "zlib;abseil;protobuf;grpc;ryml"
+    - name: run cmake legacy options test
+      run: |
+        ./ci/do_ci.sh cmake.legacy_options.test
+
+  cmake_msvc_legacy_options_test:
+    name: CMake msvc legacy option names compatibility test
+    runs-on: windows-latest
+    steps:
+    - name: Harden the runner (Audit all outbound calls)
+      uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+      with:
+        egress-policy: audit
+
+    - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+    - name: run cmake legacy options test
+      run: ./ci/do_ci.ps1 cmake.legacy_options.test
+
   cmake_fetch_content_test:
     name: CMake FetchContent usage with opentelemetry-cpp
     runs-on: ubuntu-24.04

.github/workflows/codeql-analysis.yml

@@ -67,7 +67,7 @@ jobs:
         mkdir -p $HOME/build && cd $HOME/build
         cmake -G Ninja \
               -C ${GITHUB_WORKSPACE}/test_common/cmake/all-options-abiv2-preview.cmake \
-              -DWITH_OPENTRACING=OFF \
+              -DOTELCPP_WITH_OPENTRACING=OFF \
               "${GITHUB_WORKSPACE}"
         cmake --build . --parallel
     - name: Perform CodeQL Analysis

CHANGELOG.md

@@ -18,6 +18,9 @@ Increment the:
 * [CODE HEALTH] Fix more clang tidy warnings (member initialization)
   [#4270](https://github.com/open-telemetry/opentelemetry-cpp/pull/4270)
 
+* [CMAKE] Rename cmake options with prefix `OTELCPP_`
+  [#4268](https://github.com/open-telemetry/opentelemetry-cpp/pull/4268)
+
 * docs: update supported development platforms
   [#4260](https://github.com/open-telemetry/opentelemetry-cpp/pull/4260)
 
@@ -43,6 +46,37 @@ Increment the:
 
 Breaking changes:
 
+* [CMAKE] Rename cmake options with prefix `OTELCPP_`
+  [#4268](https://github.com/open-telemetry/opentelemetry-cpp/pull/4268)
+  * All CMake build options were renamed with the `OTELCPP_` prefix to avoid
+    name collisions with user and third-party project variables:
+    * `WITH_*` options are renamed to `OTELCPP_WITH_*`, for example
+      `WITH_OTLP_HTTP` becomes `OTELCPP_WITH_OTLP_HTTP`
+    * `BUILD_TESTING` becomes `OTELCPP_BUILD_TESTING`. Unlike the other renamed
+      options, `BUILD_TESTING` is not treated as a deprecated alias:
+      * When opentelemetry-cpp is the top-level project, `BUILD_TESTING` sets
+        the default value of `OTELCPP_BUILD_TESTING`.
+      * When opentelemetry-cpp is a subproject, the parent project's
+        `BUILD_TESTING` no longer controls opentelemetry-cpp tests, which
+        default to `OFF`.
+      * Set `OTELCPP_BUILD_TESTING` explicitly to enable or disable
+        opentelemetry-cpp tests in either top-level or subproject builds.
+    * `BUILD_W3CTRACECONTEXT_TEST` becomes
+      `OTELCPP_BUILD_W3CTRACECONTEXT_TEST`
+    * `BUILD_PACKAGE` becomes `OTELCPP_BUILD_PACKAGE`
+    * `TARBALL` becomes `OTELCPP_TARBALL`
+    * `OPENTELEMETRY_BUILD_DLL` becomes `OTELCPP_BUILD_DLL`
+    * `OPENTELEMETRY_INSTALL` becomes `OTELCPP_INSTALL`
+    * `OPENTELEMETRY_SKIP_DYNAMIC_LOADING_TESTS` becomes
+      `OTELCPP_SKIP_DYNAMIC_LOADING_TESTS`
+    * `OPENTELEMETRY_EXTERNAL_COMPONENT_PATH` becomes
+      `OTELCPP_EXTERNAL_COMPONENT_PATH`
+  * The other legacy option names are still accepted but deprecated: a
+    deprecation warning is emitted at configure time, and the `OTELCPP_` name
+    takes precedence when both names are set.
+  * Please update build scripts and CI configurations to use the new option
+    names.
+
 * [METRICS SDK] Rename Base2 Exponential Histogram Aggregation config field
   [#4253](https://github.com/open-telemetry/opentelemetry-cpp/pull/4253)
   * The public configuration member `max_buckets_` was renamed to `max_size_` to