.. _target CMake Dependency Tokens: Dependency Tokens ================= ``ot_add_dependency( ...)`` is where you list the project dependencies to build. Each token is a short name that the build system turns into the right include directories (on the ``_core`` object library) and the right link directories and link libraries (on the final target). .. code-block:: cmake ot_add_dependency(MyTarget OTCore OTCommunication # OpenTwin libraries QtWidgets # Qt RJSON CURL MONGO_C # third party OSLibs # OS system libraries ) Order does not matter. A token that is not recognised produces a warning at configure time, so typos are easy to spot. OpenTwin library tokens ----------------------- Any token that names an OpenTwin library (``OTCore``, ``OTSystem``, ``OTCommunication``, ``OTGui``, ``OTGuiAPI``, ``OTWidgets``, ``OTServiceFoundation``, ``OTModelAPI``, ``OTModelEntities``, ``OTDataStorage``, ``OTBlockEntities``, ``OToolkitAPI`` and so on) is resolved through its ``OT__ROOT`` environment variable. The build system adds the library's include directory to your core target and links its import library to the final target, picking the correct paths per configuration. Most names follow a simple rule: ``OTFooBar`` maps to ``OT_FOO_BAR_ROOT``. If that variable does not exist, the same name without the extra ``_`` is tried, so ``OTGuiAPI`` finds ``OT_GUIAPI_ROOT``. A few older names are mapped by hand: .. list-table:: :header-rows: 1 :widths: 40 60 * - Token - Environment variable * - ``OTServiceFoundation`` - ``OT_FOUNDATION_ROOT`` * - ``OTDataStorage`` - ``OT_DATASTORAGE_ROOT`` * - ``OTModelEntities`` - ``OT_MODELENTITIES_ROOT`` * - ``OTCADEntities`` - ``OT_CADMODELENTITIES_ROOT`` * - ``OTRubberband`` - ``OT_RUBBERBANDAPI_ROOT`` * - ``OToolkitAPI`` - ``OT_OTOOLKITAPI_ROOT`` * - ``OToolkit`` - ``OT_OTOOLKIT_ROOT`` * - ``UICore`` - ``OT_UICORE_ROOT`` * - ``OTFMC`` - ``OT_FILE_MANAGER_CONNECTOR_ROOT`` For a new OpenTwin library, name its variable in ``SetupEnvironment.py`` after one of the two rules, so the token works without any change to the build system: ``OTFooBar`` as ``OT_FOO_BAR_ROOT`` or ``OT_FOOBAR_ROOT``. .. note:: This will be revised in the upcoming Environment setup changes via Python in the future. Qt tokens --------- Qt tokens create the imported ``Qt6::*`` targets on demand and link them. As soon as one ``Qt*`` token is present, ``AUTOMOC`` is turned on for you at finalize. .. list-table:: :header-rows: 1 :widths: 30 70 * - Token - Links * - ``QtCore`` - ``Qt6::Core`` * - ``QtGui`` - ``Qt6::Gui`` * - ``QtWidgets`` - ``Qt6::Widgets`` (Core, Gui, Widgets) * - ``QtNetwork`` - ``Qt6::Network`` * - ``QtWebSockets`` - ``Qt6::WebSockets`` * - ``QtOpenGLWidgets`` - ``Qt6::OpenGLWidgets`` * - ``QtEntryPoint`` - ``Qt6::EntryPoint``, the ``WinMain`` shim. Only needed for a Qt GUI executable built on the ``WINDOWS`` subsystem. * - ``QtFull`` - Core, Gui, Widgets, Network, Svg, Xml, OpenGLWidgets, SvgWidgets, Qml, WebSockets Qt resource (``.qrc``) files are handled by ``ot_add_qt_resources(T)``, which turns on ``AUTORCC``. Third party tokens ------------------ These map to the vendored third party headers and libraries through their own environment variables. Header only tokens add an include directory; the rest add both include and link information. .. list-table:: :header-rows: 1 :widths: 25 55 20 * - Token - Library - Kind * - ``RJSON`` - RapidJSON - header only * - ``BASE64`` - base64, compiled into the target - source * - ``TINYXML2`` - TinyXML-2, compiled into the target - source * - ``EXPREVAL`` - tinyexpr, compiled into the target (C) - source * - ``EARCUT`` - earcut polygon triangulation - header only * - ``CURL`` - libcurl - lib * - ``MONGO_C`` - MongoDB C driver - lib * - ``MONGO_CXX`` - MongoDB C++ driver - lib * - ``MONGO_BOOST`` - Boost headers used by the Mongo C++ driver - header only * - ``BOOST`` - Boost - lib * - ``BOOST_FILESYSTEM`` - Boost.Filesystem - lib * - ``ADS`` - Qt Advanced Docking System - lib * - ``QWT`` - Qwt plotting - lib * - ``OSG`` - OpenSceneGraph - lib * - ``OCCT`` - OpenCASCADE - lib * - ``VTK`` - VTK - lib * - ``EMBREE`` - Embree - lib * - ``GMP`` - GMP - lib * - ``GMSH`` - Gmsh - lib * - ``NGSPICE`` - ngspice - lib * - ``PYTHON`` - CPython 3.11 - lib * - ``PYTHON_LEGACY`` - Legacy CPython include and numpy paths - include Use the ``PYTHON`` token together with ``ot_initialize_bin_python`` (see :ref:`Runtime library`). System and special tokens ------------------------- .. list-table:: :header-rows: 1 :widths: 30 70 * - Token - Effect * - ``OSLibs`` - Links the standard Windows system libraries: ``userenv``, ``ws2_32``, ``advapi32``, ``shell32``, ``bcrypt``, ``secur32``, ``pdh``, ``odbc32``. * - ``WINLIB:`` - Links a single Windows system library, for example ``WINLIB:Crypt32``. The ``.lib`` suffix is optional; the linker adds it. On other platforms the token is accepted and ignored. * - ``OTEncryptionKey`` - Adds the encryption key include directory only. For example, ``OTSystem`` needs the Windows crypto library for single sign on: .. code-block:: cmake ot_add_dependency(OTSystem OSLibs WINLIB:Crypt32 ) Fallbacks ---------------- If a token is none of the above, the build system looks for a matching set of environment variables and wires it up generically: * include: ``_INC`` (or per config ``_INCD`` / ``_INCR``) * link dirs: ``_LIBPATHD`` / ``_LIBPATHR`` * link libs: ``_LIBD`` / ``_LIBR`` (or a single ``_LIB``) So a new third party library, headers and libraries, is added just by defining those variables in the ThirdParty ``SetupEnvironment.py`` and using the token. Nothing in ``Scripts/CMake`` has to change. Many tokens in daily use work exactly this way: ``CURL``, ``MONGO_C``, ``MONGO_CXX``, ``BOOST``, and ``ZLIB``, ``QT_TT``, ``MDFLIB`` and ``EXPAT``, which have no entry in the tables above. The link part is only used when ``_LIBPATHD`` or ``_LIBPATHR`` is set. A ``_LIB`` without a lib path is not linked. A header only library without a lib path still gets its include directories, but configure prints the warning "Unknown dependency token" for it. The build works, the warning can be ignored.