Configure Targets

After creating an empty project, we will get the following basic configuration file.

xmake.lua

add_rules("mode.debug", "mode.release")

target("test")
    set_kind("binary")
    add_files("src/*.cpp")

Among them, mode.release is the default compilation mode rule, which will automatically add some common optimization compilation options for the target build, such as: -O2, and so on.

We can also switch to mode.debug debugging mode through xmake f -m debug, which will automatically configure some debugging options, such as: -g, and so on.

Of course, we can also configure them completely by ourselves without using the mode rules.

xmake.lua

target("test")
set_kind("binary")
add_files("src/*.cpp")

Configure macro definition

We can add a macro definition option to the target program through add_defines, for example:

xmake.lua

target("test")
    set_kind("binary")
    add_files("src/*.cpp")
    add_defines("DEBUG")

In the test target scope, we configure a macro definition compilation option -DDEBUG for it, which will only take effect on the test target.

We can also use the xmake -v command to quickly verify whether the added configuration is effective.

[ 23%]: cache compiling.release src/main.cpp
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang -c -Q
unused-arguments -target x86_64-apple-macos15.2 -isysroot /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX15.2.sdk -fvisibility=hidden -fvisibility-inline
s-hidden -O3 -DNDEBUG -o build/.objs/test/macosx/x86_64/release/src/main.cpp.o src/main.cpp

As you can see, -DDEBUG has been added to the clang compilation command.

Configure multiple targets at the same time

If you want multiple compilation targets to take effect at the same time, we can move them to the global root scope.

xmake.lua

add_defines("DEBUG")

target("foo")
    set_kind("binary")
    add_files("src/*.cpp")

target("bar")
    set_kind("binary")
    add_files("src/*.cpp")

At this time, both foo and bar target programs will have the -DDEBUG compilation option.

The configuration of the root scope will affect the current xmake.lua configuration file and the target programs in all sub-xmake.lua files (that is, the sub-directory configuration introduced by includes).

xmake.lua

add_defines("DEBUG")

target("foo")
    set_kind("binary")
    add_files("src/*.cpp")

includes("bar")

bar/xmake.lua

target("bar")
    set_kind("binary")
    add_files("src/*.cpp")

If the bar target is in the bar/xmake.lua sub-configuration file, it will also be effective.

NOTE

However, the root scope configuration in the sub-file cannot affect the target in the same level or parent configuration file.

xmake.lua

target("foo")
    set_kind("binary")
    add_files("src/*.cpp")

includes("bar")

bar/xmake.lua

add_defines("DEBUG")

target("bar")
    set_kind("binary")
    add_files("src/*.cpp")

target("zoo")
    set_kind("binary")
    add_files("src/*.cpp")

Here, although add_defines is configured in the root scope, it only affects the bar and zoo targets, and cannot affect the foo target.

In other words, the scope of influence of the root scope is in a tree structure, and it takes effect layer by layer.

Configure optimization options

mode.release will automatically introduce some optimization options, and we can also configure them ourselves through the set_optimize interface.

For example:

set_optimize("faster")

It will configure the -O2 compilation option for the target.

NOTE

Different compilers have different optimization options, and xmake will automatically map to the most appropriate compilation option.

For more details, please refer to the document: set_optimize.

Configure header file search directory

add_includedirs("/tmp")

It will add the -I/tmp compilation option to the compiler's command line.

For more details, please refer to the document: add_includedirs.

Configure link library search directory

add_linkdirs("/tmp")

It will add the -L/tmp link option to the linker command line.

For more details, please refer to the document: add_linkdirs.

Configure link library

add_links("foo")

It will add the -lfoo link option to the linker command line, which usually needs to be used with add_linkdirs.

add_links("foo")
add_linkdirs("/tmp")

For more details, please refer to the document: add_links.

Configure system link library

add_links is usually used to link user-generated libraries, while add_syslinks can add system libraries without the need for an additional add_linkdirs.

And its link order is relatively late (after user libraries).

add_links("foo")
add_syslinks("pthread", "dl")

If links and syslinks are configured at the same time, the link order is as follows:

-lfoo -lpthread -ldl

Configure original compilation options

The add_defines and other interfaces mentioned above are all abstract APIs. Since most compilers support them, Xmake abstracts them to make them more convenient for users to use and provide better cross-platform and cross-compiler support.

However, we can also add specific compilation options for C++ code through the add_cxxflags interface, such as:

add_cxflags("-DDEBUG")

It is equivalent to add_defines("DEBUG"), but add_defines is more general and applicable to all compilers, while add_cxxflags("-DDEBUG") may only be applicable to a few compilers, because not all compilers define macros through -D.

In addition, we can also add compilation options for C code through the add_cflags interface, and add_cxflags to add compilation options for C/C++ code at the same time.

For more details, please refer to the documentation:

• add_cflags
• add_cxflags
• add_cxxflags

Target Type Configuration

Setting Target Types

You can set different target types through set_kind():

target("app")
    set_kind("binary")      -- executable program
    add_files("src/*.cpp")

target("lib")
    set_kind("static")      -- static library
    add_files("src/*.cpp")

target("dll")
    set_kind("shared")      -- dynamic library
    add_files("src/*.cpp")

target("obj")
    set_kind("object")      -- object file collection
    add_files("src/*.cpp")

target("header")
    set_kind("headeronly")  -- header-only library
    add_headerfiles("include/*.h")

Target Type Description

Type	Description	Output Files
binary	Executable program	app.exe, app
static	Static library	libapp.a, app.lib
shared	Dynamic library	libapp.so, app.dll
object	Object file collection	*.o, *.obj
headeronly	Header-only library	No compilation output
phony	Virtual target	No output, only for dependency management

Virtual Targets (phony)

Virtual targets don't generate actual files, they're only used for managing dependencies:

target("test1")
    set_kind("binary")
    add_files("src/test1.cpp")

target("test2")
    set_kind("binary")
    add_files("src/test2.cpp")

target("all-tests")
    set_kind("phony")
    add_deps("test1", "test2")

Executing xmake build all-tests will build both test1 and test2.

Configure target dependency

We can configure the dependency between two target programs through the add_deps interface.

This is usually used in scenarios where an executable program depends on a static library (or dynamic library), for example:

target("foo")
    set_kind("static")
    add_files("src/foo.cpp")

target("test")
    set_kind("binary")
    add_deps("foo")
    add_files("src/main.cpp")

Since the dependency between test and foo library programs is configured through add_deps, when we compile test, the foo dependency library will be automatically compiled and automatically linked to it, without the need for additional add_links and add_linkdirs configurations.

For more information about dependency configuration, please refer to the document: add_deps.

Target File Configuration

Adding Source Files

target("app")
    add_files("src/*.cpp")           -- add all cpp files
    add_files("src/*.c")             -- add all c files
    add_files("src/*.asm")           -- add assembly files
    add_files("src/*.m")             -- add Objective-C files
    add_files("src/*.mm")            -- add Objective-C++ files

Excluding Specific Files

target("app")
    add_files("src/*.cpp", {exclude = "src/test.cpp"})  -- exclude test files

Adding Header Files

target("header-lib")
    set_kind("headeronly")
    add_headerfiles("include/*.h")           -- add header files
    add_headerfiles("include/*.hpp")         -- add C++ header files
    add_headerfiles("include/*.h", {install = false})  -- non-installable header files

Adding Install Files

target("app")
    add_installfiles("assets/*.png", {prefixdir = "share/app"})  -- install resource files
    add_installfiles("config/*.conf", {prefixdir = "etc"})       -- install config files

Target Property Configuration

Setting Target Filename

target("app")
    set_basename("myapp")  -- generated filename will be myapp.exe

Setting Target Directory

target("app")
    set_targetdir("bin")   -- output to bin directory

Setting Install Directory

target("app")
    set_installdir("bin")  -- install to bin directory

Setting Version Information

target("app")
    set_version("1.0.0")   -- set version number

Target Visibility Configuration

Setting Symbol Visibility

target("lib")
    set_kind("shared")
    set_symbols("hidden")  -- hide symbols, reduce export table size

Setting Visibility Level

target("lib")
    set_kind("shared")
    set_visibility("hidden")  -- set default visibility to hidden

Target Optimization Configuration

Setting Optimization Level

target("app")
    set_optimize("fast")        -- fast optimization
    set_optimize("faster")      -- faster optimization
    set_optimize("fastest")     -- fastest optimization
    set_optimize("smallest")    -- size optimization
    set_optimize("none")        -- no optimization

Setting Debug Information

target("app")
    set_symbols("debug")     -- add debug symbols
    set_strip("debug")       -- strip debug symbols during linking
    set_strip("all")         -- strip all symbols during linking

Target Language Configuration

Setting Language Standards

target("app")
    set_languages("c++17")   -- set C++ standard
    set_languages("c11")     -- set C standard

Setting Language Features

target("app")
    set_languages("c++17", "c11")  -- support both C++17 and C11

Target Platform Configuration

Setting Target Platform

target("app")
    set_plat("android")      -- set to Android platform
    set_arch("arm64-v8a")    -- set to ARM64 architecture

Conditional Configuration

target("app")
    if is_plat("windows") then
        add_defines("WIN32")
        add_links("user32")
    elseif is_plat("linux") then
        add_defines("LINUX")
        add_links("pthread")
    end

Target Option Configuration

Associating Options

option("enable_gui")
    set_default(false)
    set_description("Enable GUI support")

target("app")
    set_options("enable_gui")  -- associate option

Conditional Options

target("app")
    if has_config("enable_gui") then
        add_defines("GUI_ENABLED")
        add_links("gtk+-3.0")
    end

Target Rule Configuration

Adding Build Rules

target("app")
    add_rules("mode.debug", "mode.release")  -- add debug and release modes
    add_rules("qt.widgetapp")                -- add Qt application rule
    add_rules("wdk.driver")                  -- add WDK driver rule

Custom Rules

rule("myrule")
    set_extensions(".my")
    on_build_file(function (target, sourcefile, opt)
        -- custom build logic
    end)

target("app")
    add_rules("myrule")  -- apply custom rule

Target Runtime Configuration

Setting Runtime Library

target("app")
    set_runtimes("MT")      -- static runtime (MSVC)
    set_runtimes("MD")      -- dynamic runtime (MSVC)

Setting Runtime Path

target("app")
    set_runtimes("MD")
    add_rpathdirs("$ORIGIN")  -- set relative path lookup

Target Toolchain Configuration

Setting Toolchain

target("app")
    set_toolset("clang")    -- use Clang toolchain
    set_toolset("gcc")      -- use GCC toolchain
    set_toolset("msvc")     -- use MSVC toolchain

Setting Compiler

target("app")
    set_toolset("cc", "clang")   -- set C compiler
    set_toolset("cxx", "clang++") -- set C++ compiler

Target Group Configuration

Setting Target Groups

target("app")
    set_group("apps")       -- set group to apps

target("lib")
    set_group("libs")       -- set group to libs

target("test")
    set_group("tests")      -- set group to tests

Target Default Configuration

Setting Default Targets

target("app")
    set_default(true)       -- set as default build target

target("test")
    set_default(false)      -- not set as default build target

Enabling/Disabling Targets

target("app")
    set_enabled(true)       -- enable target

target("old")
    set_enabled(false)      -- disable target

More Information

• Complete API documentation: Project Target API
• Target instance interfaces: Target Instance API
• Built-in rules reference: Built-in Rules