refcol: rework cmake build logic for the ITT reference collector

.github/workflows/main.yml

@@ -12,6 +12,10 @@ env:
 permissions:
   contents: read
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   c_build:
     name: Check upstream C library
@@ -73,8 +77,8 @@ jobs:
       run: python buildall.py --refcol ${{ runner.os == 'Windows' && '--cmake_gen ninja' || '' }}
     - name: Build smoke test
       run: |
-        cmake ${{ matrix.build_dir }} -DITT_API_REFCOL_SMOKE_TESTS=ON
-        cmake --build ${{ matrix.build_dir }} --target refcol_smoke_test
+        cmake ${{ matrix.build_dir }} -DITT_API_REFERENCE_COLLECTOR=ON -DITT_API_REFCOL_SMOKE_TESTS=ON
+        cmake --build ${{ matrix.build_dir }} --target refcol_smoke_test --config Release
     - name: Run smoke test
       run: python src/ittnotify_refcol/tests/run_smoke_test.py --lib ${{ matrix.lib }} --exe ${{ matrix.exe }}
 

docs/src/ref_collector.rst

@@ -14,20 +14,25 @@ full library path to the `INTEL_LIBITTNOTIFY64` environment variable.
 Building
 --------
 
-Use CMake from the repository root, enabling the ``ITT_API_REFERENCE_COLLECTOR`` option:
+There are two ways to build the ITT API reference collector shared library.
+
+**Standalone** — run this single CMake build command from the
+``src/ittnotify_refcol`` directory (the library is written into the ``./build``
+directory):
 
 .. code-block:: console
 
-    cmake -B <build_dir> -DITT_API_REFERENCE_COLLECTOR=ON
-    cmake --build <build_dir>
+    cmake -B build && cmake --build build --config Release
 
-Alternatively, use the provided ``buildall.py`` script:
+**From the ittapi repository** — use the ``buildall.py`` script in the
+repository root (the library is written into the ``build_linux/bin`` or
+``build_win/bin`` directory):
 
 .. code-block:: console
 
     python buildall.py --refcol
 
-The shared library is placed in the ``bin/`` subdirectory of the build directory:
+Resulting library name:
 
 .. list-table::
    :header-rows: 1
@@ -43,29 +48,31 @@ The shared library is placed in the ``bin/`` subdirectory of the build directory
 Usage
 -----
 
+Point the ``INTEL_LIBITTNOTIFY64`` environment variable to the full path of the
+library you built above (adjust the path to your build directory).
 
 **On Linux**
 
 
 .. code-block:: bash
 
-    export INTEL_LIBITTNOTIFY64=<build_dir>/bin/libittnotify_refcol.so
+    export INTEL_LIBITTNOTIFY64=<build_dir>/libittnotify_refcol.so
 
 
 **On FreeBSD**
 
 
 .. code-block:: bash
 
-    setenv INTEL_LIBITTNOTIFY64 <build_dir>/bin/libittnotify_refcol.so
+    setenv INTEL_LIBITTNOTIFY64 <build_dir>/libittnotify_refcol.so
 
 
 **On Windows**
 
 
 .. code-block:: bat
 
-    set INTEL_LIBITTNOTIFY64=<build_dir>\bin\libittnotify_refcol.dll
+    set INTEL_LIBITTNOTIFY64=<build_dir>\libittnotify_refcol.dll
 
 
 Log File Location

src/ittnotify_refcol/.gitignore

@@ -1,2 +1,5 @@
 *.o
 *.so
+*.dll
+*.lib
+build/

src/ittnotify_refcol/CMakeLists.txt

@@ -3,37 +3,66 @@
 #  SPDX-License-Identifier: (BSD-3-Clause OR GPL-2.0-only)
 #
 
-add_library(ittnotify_refcol SHARED itt_refcol_impl.c)
+# This CMake file builds ITT API reference collector shared library in two ways:
+#
+# 1. As part of the ittapi repository, pulled in by the root CMakeLists.txt
+#    via add_subdirectory() when -DITT_API_REFERENCE_COLLECTOR=ON.
+#
+# 2. Standalone, with a single one-line build command:
+#    cmake -B build && cmake --build build --config Release
 
-target_include_directories(ittnotify_refcol
-    PUBLIC $<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/include>
-    PRIVATE ${CMAKE_SOURCE_DIR}/src/ittnotify
-)
+cmake_minimum_required(VERSION 3.10)
+
+project(ittnotify_refcol C)
+
+if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
+    set(ITT_REFCOL_STANDALONE ON)
+else()
+    set(ITT_REFCOL_STANDALONE OFF)
+endif()
+
+set(ITT_REFCOL_INCLUDE_DIR   "${CMAKE_CURRENT_SOURCE_DIR}/../../include")
+set(ITT_REFCOL_ITTNOTIFY_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../ittnotify")
+
+add_library(ittnotify_refcol SHARED itt_refcol_impl.c)
 
-target_link_libraries(ittnotify_refcol PRIVATE ${CMAKE_DL_LIBS})
 set_target_properties(ittnotify_refcol PROPERTIES
     LINKER_LANGUAGE C
-    RUNTIME_OUTPUT_DIRECTORY ${LIBRARY_OUTPUT_PATH}
-    ARCHIVE_OUTPUT_DIRECTORY ${LIBRARY_OUTPUT_PATH})
+    POSITION_INDEPENDENT_CODE ON
+    OUTPUT_NAME ittnotify_refcol)
+
+target_include_directories(ittnotify_refcol PRIVATE
+    ${ITT_REFCOL_INCLUDE_DIR}
+    ${ITT_REFCOL_ITTNOTIFY_DIR})
+
+target_link_libraries(ittnotify_refcol PRIVATE ${CMAKE_DL_LIBS})
 
 if(WIN32)
     target_compile_definitions(ittnotify_refcol PRIVATE _CRT_SECURE_NO_WARNINGS)
     set_target_properties(ittnotify_refcol PROPERTIES
         OUTPUT_NAME libittnotify_refcol
         PREFIX ""
         WINDOWS_EXPORT_ALL_SYMBOLS ON)
+endif()
+
+if(DEFINED LIBRARY_OUTPUT_PATH AND NOT ITT_REFCOL_STANDALONE)
+    set(ITT_REFCOL_OUTPUT_DIR "${LIBRARY_OUTPUT_PATH}")
 else()
-    set_target_properties(ittnotify_refcol PROPERTIES OUTPUT_NAME ittnotify_refcol)
+    set(ITT_REFCOL_OUTPUT_DIR "${CMAKE_BINARY_DIR}")
 endif()
 
+set_target_properties(ittnotify_refcol PROPERTIES
+    RUNTIME_OUTPUT_DIRECTORY "${ITT_REFCOL_OUTPUT_DIR}"
+    LIBRARY_OUTPUT_DIRECTORY "${ITT_REFCOL_OUTPUT_DIR}"
+    ARCHIVE_OUTPUT_DIRECTORY "${ITT_REFCOL_OUTPUT_DIR}")
+
 option(ITT_API_REFCOL_SMOKE_TESTS "Build reference collector smoke tests" OFF)
-if(ITT_API_REFCOL_SMOKE_TESTS)
+if(ITT_API_REFCOL_SMOKE_TESTS AND NOT ITT_REFCOL_STANDALONE)
     add_executable(refcol_smoke_test tests/smoke_test.c)
-    target_include_directories(refcol_smoke_test
-        PRIVATE ${CMAKE_SOURCE_DIR}/include
-                ${CMAKE_SOURCE_DIR}/src/ittnotify
-    )
+    target_include_directories(refcol_smoke_test PRIVATE
+        ${ITT_REFCOL_INCLUDE_DIR}
+        ${ITT_REFCOL_ITTNOTIFY_DIR})
     target_link_libraries(refcol_smoke_test PRIVATE ittnotify ${CMAKE_DL_LIBS})
     set_target_properties(refcol_smoke_test PROPERTIES
-        RUNTIME_OUTPUT_DIRECTORY ${LIBRARY_OUTPUT_PATH})
+        RUNTIME_OUTPUT_DIRECTORY "${ITT_REFCOL_OUTPUT_DIR}")
 endif()

src/ittnotify_refcol/README.md

@@ -8,21 +8,23 @@ full library path to the `INTEL_LIBITTNOTIFY64` environment variable.
 
 ## Building
 
-Use CMake from the repository root, enabling the `ITT_API_REFERENCE_COLLECTOR` option:
+There are two ways to build the ITT API reference collector shared library.
 
-```
-cmake -B <build_dir> -DITT_API_REFERENCE_COLLECTOR=ON
-cmake --build <build_dir>
+**Standalone** — run this single CMake build command from this directory
+(the library is written into the `./build` directory):
+
+```bash
+cmake -B build && cmake --build build --config Release
 ```
 
-The shared library is placed in the `bin/` subdirectory of the CMake build
-directory. Alternatively, use the provided `buildall.py` script:
+**From the ittapi repository** — use the `buildall.py` script in the repository root
+(the library is written into the `build_linux/bin` or `build_win/bin` directory):
 
-```
+```bash
 python buildall.py --refcol
 ```
 
-The shared library is placed in the `bin/` subdirectory of the CMake build directory:
+Resulting library name:
 
 | Platform | Library name                   |
 |----------|--------------------------------|
@@ -31,22 +33,25 @@ The shared library is placed in the `bin/` subdirectory of the CMake build direc
 
 ## Usage
 
+Point the `INTEL_LIBITTNOTIFY64` environment variable to the full path of the
+library you built above (adjust the path to your build directory).
+
 **On Linux**
 
 ```
-export INTEL_LIBITTNOTIFY64=<build_dir>/bin/libittnotify_refcol.so
+export INTEL_LIBITTNOTIFY64=<build_dir>/libittnotify_refcol.so
 ```
 
 **On FreeBSD**
 
 ```
-setenv INTEL_LIBITTNOTIFY64 <build_dir>/bin/libittnotify_refcol.so
+setenv INTEL_LIBITTNOTIFY64 <build_dir>/libittnotify_refcol.so
 ```
 
 **On Windows**
 
 ```
-set INTEL_LIBITTNOTIFY64=<build_dir>\bin\libittnotify_refcol.dll
+set INTEL_LIBITTNOTIFY64=<build_dir>\libittnotify_refcol.dll
 ```
 
 By default, log files are saved in the system temporary directory. To change