.. _target CMake API Reference: API Reference ============= The public functions provided by ``OTProject.cmake``. Square brackets denote optional arguments. ```` is the project/target name passed to ``project()``. Initialize ---------- ``ot_initialize_lib( [EXPORT_MACRO])`` Creates the object library ``_core`` from ``src/`` and ``include/``, applies the C++20 standard, the default runtime, the Debug/Release definitions and ``_USRDLL``, and sets the dll-export macro (default ``OPENTWIN_EXPORTS``). Use for libraries and services. ``ot_initialize_bin( [EXPORT_MACRO])`` Like ``ot_initialize_lib`` but marks the target as an application. The export macro is optional. Use for executables. ``ot_initialize_bin_python( [EXPORT_MACRO])`` Like ``ot_initialize_bin`` but forces the ``/MD`` runtime in every configuration and defines ``_RELEASEDEBUG`` (Debug) / ``NDEBUG`` (Release) instead of ``_DEBUG``, so the target links the release ``python311.lib``. Use only for binaries that embed CPython. Dependencies ------------ ``ot_add_dependency( ...)`` Records dependency tokens on ``_core``. Resolved at finalize. See :ref:`Dependency tokens`. May be called multiple times; tokens accumulate. Finalize -------- ``ot_finalize_lib()`` Creates the shared library ```` from the core objects, exposes ``include/`` as a ``PUBLIC`` include directory, applies all recorded dependencies and the requested subsystem, and enables ``AUTOMOC`` if any ``Qt*`` token is present. For a target in ``Services/`` it also writes the Visual Studio ``launch.vs.json`` (see ``ot_service_debug_launch``). ``ot_finalize_bin( [OUTPUT_NAME])`` Creates the executable ```` from the core objects. ``WIN32_EXECUTABLE`` is set according to the subsystem (Release GUI vs console). Pass ``OUTPUT_NAME`` to give the produced ``.exe`` a different file name. Applies dependencies, subsystem and ``AUTOMOC`` as for ``ot_finalize_lib``. Tests ----- ``ot_add_test()`` If ``BUILD_TESTING`` is on and ``tests/CMakeLists.txt`` exists, adds the ``tests`` subdirectory. Safe to call when no tests exist (it just logs a status message). ``ot_initialize_test( )`` Called inside ``tests/CMakeLists.txt``. Builds ```` from ``tests/src/*.cpp`` plus the compiled ``_core`` objects, inherits the main target's export macro, dependencies and runtime library, links the gtest library and registers the test with CTest. Compile options and definitions ------------------------------- ``ot_add_compile_definitions( ...)`` Adds private preprocessor definitions to the core target. ``ot_add_compile_options( ...)`` Adds raw compile options to the core target. A bare numeric argument is treated as a warning to disable and becomes ``/wd``. ``ot_disable_warnings( ...)`` Convenience wrapper that suppresses warnings by numeric ID. Non-numeric arguments produce an author warning (use ``ot_add_compile_options`` for flags). Subsystem --------- ``ot_set_subsystem( CONSOLE|WINDOWS)`` Sets the linker subsystem for the final binary (applied on finalize). ``CONSOLE`` keeps a ``main()`` entry point and console window; ``WINDOWS`` produces a windowed application. ``ot_set_subsystem_for_config( CONSOLE|WINDOWS)`` Overrides the subsystem for a single configuration (``Debug``, ``Release``, ``RelWithDebInfo`` or ``MinSizeRel``). Configuration-specific overrides take precedence over ``ot_set_subsystem``. Runtime library --------------- ``ot_set_runtime_static_release()`` Links the static CRT (``/MT``) in Release while keeping ``/MDd`` in Debug. For stand-alone command line tools that ship as a single self-contained executable. Never use it for libraries, services, or Python targets. Resources and deployment ------------------------ ``ot_add_qt_resources()`` Globs ``*.qrc`` under the project and enables ``AUTORCC``. ``ot_add_resources()`` Globs ``*.rc`` and ``*.ico`` under the project into the target. ``ot_deploy_app_configuration()`` Adds a post-build step copying ``qt.conf`` (if present) next to the binary. Debug launch (Visual Studio F5) ------------------------------- ``ot_service_debug_launch( ARGS ...)`` Declares the arguments Visual Studio passes to the service loader (after the service DLL path) when the service is launched with F5. ``@NAME@`` tokens are emitted as ``${env.NAME}`` and resolved by Visual Studio at debug time. Most services do not need this; see :ref:`Debugging services in Visual Studio`. ``ot_bin_debug_launch( [PATH ] [ARGS ...])`` Generates a Visual Studio ``launch.vs.json`` so an **executable** target can be debugged with F5 (the executable counterpart of ``ot_service_debug_launch``, which targets DLL services). Call it from the binary's own ``CMakeLists.txt`` after ``ot_finalize_bin`` - it is an explicit per-target call, never automatic, so the launch config is generated only where it is requested. ``PATH`` is the debug-time DLL search PATH in Visual Studio ``${env.VAR}`` syntax; pass it as a bracket argument ``[[...]]`` so ``${env.VAR}`` and single backslashes are taken literally (they are JSON-escaped internally). ``PATH`` defaults to the inherited ``${env.PATH}`` and ``ARGS`` defaults to none. Mainly used for an ``ot_initialize_bin_python`` target, which is built ``/MD`` and must therefore debug against the **release** OT DLLs (``${env.OT_ALL_DLLR}``) plus release python - never the ``/MDd`` debug DLLs, which would CRT- / ``_ITERATOR_DEBUG_LEVEL``-mismatch and crash. ``ot_tool_bin_debug_launch( [ARGSD ...] [ARGSR ...] [PATHD ] [PATHR ])`` Generates the ``launch.vs.json`` for a tool executable, with separate arguments and ``PATH`` for Debug and Release. ``@NAME@`` tokens work as in ``ot_service_debug_launch``. ``PATHD`` and ``PATHR`` default to the inherited ``PATH``. Call it after ``ot_finalize_bin``. ``ot_tool_debug_launch( [ARGSD ...] [ARGSR ...] [PATHD ] [PATHR ])`` Like ``ot_tool_bin_debug_launch``, but for a DLL outside ``Services/`` that runs in ``open_twin.exe`` (for example ``OToolkit``). The DLL path is passed as first argument. ``PATHD`` and ``PATHR`` default to ``OT_ALL_DLLD`` or ``OT_ALL_DLLR`` plus the inherited ``PATH``. Call it after ``ot_finalize_lib``. All four launch functions are Visual Studio only and do nothing with other compilers. Each one writes the whole ``launch.vs.json``, so a project uses only one of them. Examples: :ref:`Debugging in Visual Studio`. Qt -- ``ot_bin_use_release_qt()`` Makes the Debug configuration link the release Qt libraries. For targets that run the release runtime in Debug (``ot_initialize_bin_python``). Call it after ``ot_finalize_bin``, when the Qt targets exist. Visual Studio only. Internal helpers ---------------- Functions prefixed with ``_ot_`` (for example ``_ot_initialize_target``, ``_ot_apply_dep_to_core``, ``_ot_apply_dep_to_final``, ``_ot_get_ot_root_envvar``) are implementation details of the meta system. Do not call them from a project ``CMakeLists.txt``. A new dependency normally needs no change here: a third party library is added through its environment variables, an OpenTwin library through a matching variable name (see :ref:`Dependency tokens`).