BuildBinTarget¶

Operations to fully create and configure a C++ binary target. It greatly simplifies the most common process of creating an executable or library, by wrapping calls to CMake functions in higher-level functions. However, for more complex cases, you will need to use CMake's native commands. It requires CMake 3.20 or newer.

Synopsis¶

build_bin_target(CREATE <target-name> <STATIC|SHARED|HEADER|EXEC>)
build_bin_target(CONFIGURE_SETTINGS <target-name> [...])
build_bin_target(ADD_SOURCES <target-name> [...])
build_bin_target(ADD_PRECOMPILED_HEADER <target-name> HEADER_FILE <file-path>)
build_bin_target(ADD_INCLUDE_DIRECTORIES <target-name> INCLUDE_DIRECTORIES <directory-path>...)

Usage¶

build_bin_target(CREATE <target-name> <STATIC|SHARED|HEADER|EXEC>)¶

Create a binary target named <target-name> and add it to the current CMake project, according to the specified binary type: STATIC, SHARED , HEADER, EXEC.

Example usage:

build_bin_target(CREATE "my_static_lib" STATIC)
build_bin_target(CREATE "my_shared_lib" SHARED)

build_bin_target(CONFIGURE_SETTINGS <target-name> [...])¶

Configure settings for an existing binary target:

build_bin_target(CONFIGURE_SETTINGS <target-name>
                [COMPILER_FEATURES <feature>...]
                [COMPILE_DEFINITIONS <definition>...]
                [COMPILE_OPTIONS <option>...]
                [LINK_OPTIONS <option>...])

This command updates compile and link settings of a previously created target <target-name>. The following configuration options are supported:

COMPILER_FEATURES: Add required compiler features (e.g., cxx_std_20, cxx_lambda).
COMPILE_DEFINITIONS: Add preprocessor definitions (e.g., MY_DEFINE or MY_DEFINE=42).
COMPILE_OPTIONS: Add compiler command-line options (e.g., -Wall, /W4).
LINK_OPTIONS: Add linker command-line options (e.g., -s, /INCREMENTAL:NO).

The target is also assigned to a default folder for improved IDE integration. All options are optional and may appear in any order. If a section is missing, it is simply ignored without warning.

This command is intended for targets that have been previously created using build_bin_target(CREATE).

Example usage:

build_bin_target(CREATE "my_static_lib" STATIC)
build_bin_target(CONFIGURE_SETTINGS "my_static_lib"
  COMPILER_FEATURES "cxx_std_20"
  COMPILE_DEFINITIONS "MY_DEFINE"
  COMPILE_OPTIONS "-Wall" "-Wextra"
  LINK_OPTIONS "-s"
)

build_bin_target(ADD_SOURCES <target-name> [...])¶

Add source and header files to an existing binary target:

build_bin_target(ADD_SOURCES <target-name>
                SOURCE_FILES <file-path>...
                PRIVATE_HEADER_FILES <file-path>...
                PUBLIC_HEADER_FILES <file-path>...)

Assigns implementation and header files to the given binary target <target-name> with PRIVATE visibility:

SOURCE_FILES: A list of source files (e.g., .cpp, .c) typically located in the src/ directory.
PRIVATE_HEADER_FILES: A list of private headers (e.g., .h) typically located in the src/ directory.
PUBLIC_HEADER_FILES: A list of public headers, usually found in an include/ directory.

It also defines a logical grouping of source files in IDEs (e.g., Visual Studio) using source_group(), based on the project's source tree.

This command is intended for targets that have been previously created using build_bin_target(CREATE), and is typically used in conjunction with directory(COLLECT_SOURCES_BY_POLICY) to get the required files.

Example usage:

build_bin_target(CREATE "my_static_lib" STATIC)
build_bin_target(ADD_SOURCES "my_static_lib"
  SOURCE_FILES "src/main.cpp" "src/util.cpp" "src/source_1.cpp"
  PRIVATE_HEADER_FILES "src/util.h" "src/source_1.h"
  PUBLIC_HEADER_FILES "include/lib_1.h" "include/lib_2.h"
)

# Full example
build_bin_target(CREATE "my_static_lib" STATIC)
build_bin_target(CONFIGURE_SETTINGS "my_static_lib"
  COMPILER_FEATURES "cxx_std_20"
  COMPILE_DEFINITIONS "MY_DEFINE"
  COMPILE_OPTIONS "-Wall" "-Wextra"
  LINK_OPTIONS "-s"
)
directory(COLLECT_SOURCES_BY_POLICY
  PUBLIC_HEADERS_SEPARATED on "${CMAKE_SOURCE_DIR}/include/mylib"
  SRC_DIR "${CMAKE_SOURCE_DIR}/src"
  SRC_SOURCE_FILES sources
  PUBLIC_HEADER_DIR public_headers_dir
  PUBLIC_HEADER_FILES public_headers
  PRIVATE_HEADER_DIR private_headers_dir
  PRIVATE_HEADER_FILES private_headers
)
build_bin_target(ADD_SOURCES "my_static_lib"
  SOURCE_FILES "${sources}"
  PRIVATE_HEADER_FILES "${private_headers}"
  PUBLIC_HEADER_FILES "${public_headers}"
)

build_bin_target(ADD_PRECOMPILED_HEADER <target-name> HEADER_FILE <file-path>)¶

Add a precompiled header file (PCH) <file_path> to an existing binary target <target_name> with PRIVATE visibility.

This command is intended for targets that have been previously created using build_bin_target(CREATE).

Example usage:

build_bin_target(CREATE "my_static_lib" STATIC)
build_bin_target(ADD_PRECOMPILED_HEADER "my_static_lib"
  HEADER_FILE "src/header_pch.h")

# Full example
build_bin_target(CREATE "my_static_lib" STATIC)
build_bin_target(CONFIGURE_SETTINGS "my_static_lib"
  COMPILER_FEATURES "cxx_std_20"
  COMPILE_DEFINITIONS "MY_DEFINE"
  COMPILE_OPTIONS "-Wall" "-Wextra"
  LINK_OPTIONS "-s"
)
directory(COLLECT_SOURCES_BY_POLICY
  PUBLIC_HEADERS_SEPARATED on "${CMAKE_SOURCE_DIR}/include/mylib"
  SRC_DIR "${CMAKE_SOURCE_DIR}/src"
  SRC_SOURCE_FILES sources
  PUBLIC_HEADER_DIR public_headers_dir
  PUBLIC_HEADER_FILES public_headers
  PRIVATE_HEADER_DIR private_headers_dir
  PRIVATE_HEADER_FILES private_headers
)
build_bin_target(ADD_SOURCES "my_static_lib"
  SOURCE_FILES "${sources}"
  PRIVATE_HEADER_FILES "${private_headers}"
  PUBLIC_HEADER_FILES "${public_headers}"
)
build_bin_target(ADD_PRECOMPILED_HEADER "my_static_lib"
  HEADER_FILE "src/header_pch.h")

build_bin_target(ADD_INCLUDE_DIRECTORIES <target-name> INCLUDE_DIRECTORIES <directory-path>...)¶

Add include directories to an existing binary target <target_name> with PRIVATE visibility.

This command is intended for targets that have been previously created using build_bin_target(CREATE), and is typically used in conjunction with directory(COLLECT_SOURCES_BY_POLICY) to get the required files.

Example usage:

build_bin_target(CREATE "my_static_lib" STATIC)
build_bin_target(ADD_INCLUDE_DIRECTORIES "my_static_lib"
  INCLUDE_DIRECTORIES "include")

# Full example
build_bin_target(CREATE "my_static_lib" STATIC)
build_bin_target(CONFIGURE_SETTINGS "my_static_lib"
  COMPILER_FEATURES "cxx_std_20"
  COMPILE_DEFINITIONS "MY_DEFINE"
  COMPILE_OPTIONS "-Wall" "-Wextra"
  LINK_OPTIONS "-s"
)
directory(COLLECT_SOURCES_BY_POLICY
  PUBLIC_HEADERS_SEPARATED on "${CMAKE_SOURCE_DIR}/include/mylib"
  SRC_DIR "${CMAKE_SOURCE_DIR}/src"
  SRC_SOURCE_FILES sources
  PUBLIC_HEADER_DIR public_headers_dir
  PUBLIC_HEADER_FILES public_headers
  PRIVATE_HEADER_DIR private_headers_dir
  PRIVATE_HEADER_FILES private_headers
)
build_bin_target(ADD_SOURCES "my_static_lib"
  SOURCE_FILES "${sources}"
  PRIVATE_HEADER_FILES "${private_headers}"
  PUBLIC_HEADER_FILES "${public_headers}"
)
build_bin_target(ADD_PRECOMPILED_HEADER "my_static_lib"
  HEADER_FILE "src/header_pch.h")
build_bin_target(ADD_INCLUDE_DIRECTORIES "my_static_lib"
  INCLUDE_DIRECTORIES "$<$<BOOL:${private_headers_dir}>:${private_headers_dir}>" "${public_headers_dir}")

BuildBinTarget¶

Synopsis¶

Usage¶

Table of Contents

Previous topic

Next topic

This Page