Global API

What find_package(qmsetup) brings on its own, before any module is imported. Paths, versions, target configuration and the Qt helpers are here.

qm_import

Include modules of this library.

qm_import(<module...>)

The suffix may be left off or written out, and a module under a subdirectory is named through it, as private/CompilerOptions.

A module that has been renamed answers to what it used to be called as well, with a deprecation warning naming the new one. cmake/private/ModuleAliases.cmake is the list of those.

qm_import_all

Include all modules of this library.

qm_import_all()

qm_find_package

Find third-party packages by including scripts in find-modules.

qm_find_package(<module...>)

qm_parse_version

Parse version and create seq vars with specified prefix.

qm_parse_version(<prefix> <version>)

qm_crop_version

Get shorter version number.

qm_crop_version(<VAR> <version> <count>)

qm_paths_equal

Tell if the given paths are same in canonical form.

qm_paths_equal(<VAR> <path1> <path2>)

qm_set_value

Set a variable to the first of several that holds something, or to a default.

qm_set_value(<key> [<variable>...] <default>)

<key>

the variable to set, in the caller’s scope

<variable>

the name of a variable to try rather than its value. They are tried in the order given and the first that if() calls true is taken, so a variable that is unset, empty or OFF falls through to the next.

<default>

a value rather than a name, taken where none of the variables answered

qm_set_value(_version FUNC_VERSION PROJECT_VERSION "0.0.0.0")

Naming no variable at all is allowed, and comes to set(<key> <default>).

qm_skip_automoc

Skip CMAKE_AUTOMOC for sources files or ones in directories.

qm_skip_automoc(<file/dir...> [RECURSIVE])

A directory stands for the sources directly in it. RECURSIVE takes what is under them as well.

A name that is neither a file nor a directory is passed over rather than being an error, so that a caller may name something optional.

note A source file property belongs to the directory it was set in, so this has to be called where the target using those sources is defined.

qm_find_qt

Find Qt libraries. Don’t wrap it in any functions.

qm_find_qt(<modules...> [QUIET] [REQUIRED] [EXACT])

QUIET and REQUIRED are passed on to find_package and may be given together, which is what find_package itself allows. With neither given, REQUIRED is what is meant.

qm_link_qt

Link Qt libraries. Don’t wrap it in any functions.

qm_link_qt(<target> <scope> <modules...>)

qm_include_qt_private

Include Qt private header directories. Don’t wrap it in any functions.

qm_include_qt_private(<target> <scope> <modules...>)

qm_configure_target

Helper to set or append all kinds of attributes to a target. Don’t wrap it in any functions.

qm_configure_target(<target>
    [SOURCES           <files>]

    [LINKS             <libs>]
    [LINKS_INTERFACE   <libs>]
    [LINKS_PRIVATE     <libs>]

    [INCLUDE           <dirs>]
    [INCLUDE_INTERFACE <dirs>]
    [INCLUDE_PRIVATE   <dirs>]

    [LINKDIR           <dirs>]
    [LINKDIR_INTERFACE <dirs>]
    [LINKDIR_PRIVATE   <dirs>]

    [DEFINES           <defs>]
    [DEFINES_INTERFACE <defs>]
    [DEFINES_PRIVATE   <defs>]

    [FEATURES           <features>]
    [FEATURES_INTERFACE <features>]
    [FEATURES_PRIVATE   <features>]

    [CCFLAGS           <flags>]
    [CCFLAGS_INTERFACE <flags>]
    [CCFLAGS_PUBLIC    <flags>]

    [LDFLAGS           <flags>]
    [LDFLAGS_INTERFACE <flags>]
    [LDFLAGS_PUBLIC    <flags>]

    [QT_LINKS            <modules>]
    [QT_LINKS_INTERFACE  <modules>]
    [QT_LINKS_PRIVATE    <modules>]

    [QT_INCLUDE_PRIVATE  <modules>]

    [SKIP_AUTOMOC   <dir/file...>]
)

INCLUDE/LINKDIR: dir/* will be expanded to all subdirectories dir/** will be expanded to all descendent directories recursively

Scopes: for LINKS, INCLUDE, LINKDIR, DEFINES and FEATURES the bare name is public, and the _INTERFACE and _PRIVATE forms are the other two.

CCFLAGS and LDFLAGS go the other way. The bare name is private, and public is spelt CCFLAGS_PUBLIC and LDFLAGS_PUBLIC. A compiler or linker flag is usually about how this target is built rather than about how to use it, so private is the answer wanted nearly every time and is what the short spelling gives. Worth knowing, since it is the one place here where the bare name does not mean public.

qm_export_defines

Helper to define export macros.

qm_export_defines(<target>
    [PREFIX     <prefix>]
    [STATIC     <token>]
    [LIBRARY    <token>]
)

qm_add_win_rc

Attach windows RC file to a target.

qm_add_win_rc(<target>
    [NAME           name]
    [VERSION        version]
    [DESCRIPTION    desc]
    [COPYRIGHT      copyright]
    [ICON           ico]
    [OUTPUT_DIR     dir]
)

qm_add_win_rc_enhanced

Attach windows RC file to a target, enhanced edition.

qm_add_win_rc_enhanced(<target>
    [NAME              name]
    [VERSION           version]
    [DESCRIPTION       description]
    [COPYRIGHT         copyright]
    [COMMENTS          comments]
    [COMPANY           company]
    [INTERNAL_NAME     internal name]
    [TRADEMARK         trademark]
    [ORIGINAL_FILENAME original filename]
    [ICONS             icon file paths]
    [OUTPUT_DIR        dir]
)

qm_add_win_manifest

Attach windows manifest file to a target.

qm_add_win_manifest(<target>
    [NAME           name]
    [VERSION        version]
    [DESCRIPTION    desc]
    [OUTPUT_DIR     dir]
    [UTF8]
    [ADMIN]
)

qm_add_mac_bundle

Add Mac bundle info.

qm_add_mac_bundle(<target>
    [NAME           <name>]
    [VERSION        <version>]
    [DESCRIPTION    <desc>]
    [COPYRIGHT      <copyright>]
    [ICON           <file>]
    [INFO_PLIST     <file>]
)

qm_create_win_shortcut

Generate Windows shortcut after building target.

qm_create_win_shortcut(<target> <dir>
    [OUTPUT_NAME <name>]
)

qm_collect_targets

Collect targets of given types recursively in a directory.

qm_collect_targets(<list> [DIRECTORY directory]
                          [EXECUTABLE] [SHARED]
                          [STATIC] [INTERFACE] [UTILITY])

If one or more types are specified, return targets matching the types. If no type is specified, return all targets.

qm_get_subdirs

Get subdirectories’ names or paths.

qm_get_subdirs(<list>
    [DIRECTORY dir]
    [EXCLUDE names...]
    [REGEX_INCLUDE exps...]
    [REGEX_EXCLUDE exps...]
    [RELATIVE path]
    [ABSOLUTE]
)

If DIRECTORY is not specified, consider CMAKE_CURRENT_SOURCE_DIR. If RELATIVE is specified, return paths evaluated as a relative path to it. If ABSOLUTE is specified, return absolute paths. If neither of them is specified, return names.

A directory is kept where it matches any of the REGEX_INCLUDE expressions, and dropped where it matches any of the REGEX_EXCLUDE ones. Two names cannot both be true of one directory, so asking for two of them and getting what matches both would be asking for nothing.

qm_basic_install

Basic template to install a CMake project.

qm_basic_install(
    [NAME <name>]
    [VERSION <version>]
    [COMPATIBILITY <compatibility>]
    [INSTALL_DIR <dir>]
    [CONFIG_TEMPLATE <file>]
    [NAMESPACE <namespace>]
    [EXPORT <sets...>]

    [WRITE_VERSION_OPTIONS <options...>]
    [WRITE_CONFIG_OPTIONS <options...>]
)

Include GNUInstallDirs, CMakePackageConfigHelpers before calling this function.

qm_include_recursive

Recursively include directories in a target.

qm_include_recursive(<target> <scope> <dir...>)

Every directory under each one named becomes an include directory, with no filtering, so a tree carrying a .git or a build directory contributes those too. Name the directories that hold headers rather than the root of a checkout.

qm_get_executable_location

Get the location of an imported executable target.

qm_get_executable_location(<target> <var>)

Reads IMPORTED_LOCATION and the four configuration specific spellings of it, in that order, and takes the first that answers. A target built by this project has none of them, so this is for the ones a find_package brought, and it stops with an error rather than returning empty.

Where this page comes from

The comments in cmake/QMSetupAPI.cmake, which is what to change.