Dependency Tokens

ot_add_dependency(<Target> <TOKEN> ...) 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).

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_<NAME>_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:

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.

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.

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 Runtime library).

System and special tokens

Token	Effect
`OSLibs`	Links the standard Windows system libraries: `userenv`, `ws2_32`, `advapi32`, `shell32`, `bcrypt`, `secur32`, `pdh`, `odbc32`.
`WINLIB:<name>`	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:

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: <TOKEN>_INC (or per config <TOKEN>_INCD / <TOKEN>_INCR)
link dirs: <TOKEN>_LIBPATHD / <TOKEN>_LIBPATHR
link libs: <TOKEN>_LIBD / <TOKEN>_LIBR (or a single <TOKEN>_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 <TOKEN>_LIBPATHD or <TOKEN>_LIBPATHR is set. A <TOKEN>_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.