This is a mirror page, please see the original page:

https://xmake.io/#/guide/configuration

Set compilation configuration before building project with command xmake f|config.

And if you want to known more options, please run: xmake f --help


You can use short or long command option, for example:

xmake f or xmake config.

xmake f -p linux or xmake config --plat=linux.

Target Platforms

Current Host

$ xmake


XMake will detect the current host platform automatically and build project.

Linux

$ xmake f -p linux [-a i386|x86_64]
$ xmake

Android

$ xmake f -p android --ndk=~/files/android-ndk-r10e/ [-a armeabi-v7a|arm64-v8a]
$ xmake

If you want to set the other android toolchains, you can use --bin option.

For example:

$ xmake f -p android --ndk=~/files/android-ndk-r10e/ -a arm64-v8a --bin=~/files/android-ndk-r10e/toolchains/aarch64-linux-android-4.9/prebuilt/darwin-x86_64/bin

The --bin option is used to set bin directory of toolchains.


Please attempt to set --arch= option if it had failed to check compiler.

iPhoneOS

$ xmake f -p iphoneos [-a armv7|armv7s|arm64|i386|x86_64]
$ xmake

Windows

$ xmake f -p windows [-a x86|x64]
$ xmake

Mingw

$ xmake f -p mingw --sdk=/usr/local/i386-mingw32-4.3.0/ [-a i386|x86_64]
$ xmake

Apple WatchOS

$ xmake f -p watchos [-a i386|armv7k]
$ xmake

Cross Compilation

Generally, if we need to compile and generate object files that can be run on other devices in the current pc environment, we need to compile and generate them through the corresponding cross-compilation tool chain, such as compiling linux programs on win/macos, or Compile object files of other embedded devices, etc.

The usual cross-compilation tool chain is based on gcc/clang, and most of them have a structure similar to the following:

/home/toolchains_sdkdir
   - bin
       - arm-linux-armeabi-gcc
       - arm-linux-armeabi-ld
       - ...
   - lib
       - libxxx.a
   - include
       - xxx.h

Each toolchain has a corresponding include/lib directory, which is used to place some system libraries and header files, such as libc, stdc++, etc., and a series of tools for compiling the tool chain are placed under the bin directory. E.g:

arm-linux-armeabi-ar
arm-linux-armeabi-as
arm-linux-armeabi-c++
arm-linux-armeabi-cpp
arm-linux-armeabi-g++
arm-linux-armeabi-gcc
arm-linux-armeabi-ld
arm-linux-armeabi-nm
arm-linux-armeabi-strip

The arm-linux-armeabi- prefix is cross, which is used to mark the target platform and architecture, and is mainly used to distinguish it from the host's own gcc/clang.

The gcc/g++ inside is the c/c++ compiler, which can also be used as a linker. When linking, it will internally call ld to link, and automatically add some c++ libraries.
Cpp is a preprocessor, as is an assembler, ar is used to generate a static library, and strip is used to crop out some symbol information, making the target program smaller. nm is used to view the list of exported symbols.

Automatic detection and compilation

If our cross-compilation tool chain is the above structure, xmake will automatically detect and identify the structure of the SDK, extract the cross and include/lib path location, users usually do not need to do additional parameter settings, just configure the SDK The root directory can be compiled, for example:

$ xmake f -p cross --sdk=/home/toolchains_sdkdir
$ xmake

Among them, -p cross is used to specify that the current platform is a cross-compilation platform, and --sdk= is used to specify the root directory of the cross toolchain.

Note: We can also specify the -p linux platform to configure cross compilation, the effect is the same, the only difference is that the name of the linux platform is additionally identified, which is convenient for xmake.lua to determine the platform byis_plat ("linux") .

At this time, xmake will automatically detect the prefix name cross of gcc and other compilers: arm-linux-armeabi-, and when compiling, it will also automatically add search options forlink library and header files :

-I/home/toolchains_sdkdir/include 
-L/home/toolchains_sdkdir/lib

These are handled automatically by xmake, there is no need to configure them manually.

Manually configure and compile

If the above automatic detection fails to completely compile for some tool chains, you need to manually set some configuration parameters related to cross compilation to adjust to these special tool chains. I will explain how to configure them one by one.

Set toolchain bin directory

For the irregular tool chain directory structure, by simply setting the --sdk option, it is impossible to completely detect the passing situation Next, you can continue to set the location of the bin directory of the toolchain through this option.

For example: for some special cross toolchains, the compiler bin directory is not in the /home/toolchains_sdkdir/bin position, but is instead in /usr/opt/bin

At this time, we can add the parameter setting of the bin directory on the basis of setting the sdk parameter to adjust the bin directory of the tool chain.

$ xmake f -p linux --sdk=/home/toolchains_sdkdir --bin=/usr/opt/bin
$ xmake

Set tool prefix for cross toolchain

Like aarch64-linux-android-, usually if you configure --sdk or --bin, xmake will automatically detect it, you don't need to set it manually.

But for some very special tool chains, if there are multiple cross prefix tool bins in a directory at the same time, you need to manually set this configuration to distinguish which bin you need to choose.

For example, there are two different compilers in the bin directory of toolchains:

/opt/bin
  - armv7-linux-gcc 
  - aarch64-linux-gcc

We now want to choose the armv7 version, then we can append --cross= to configure the compiler tool prefix name, for example:

$ xmake f -p linux --sdk=/usr/toolsdk --bin=/opt/bin --cross=armv7-linux-

Set the c/c++ compiler

If you want to continue to subdivide and select compilers, continue to add relevant compiler options, for example:

$ xmake f -p linux --sdk=/user/toolsdk --cc=armv7-linux-clang --cxx=armv7-linux-clang++

Of course, we can also specify the full path of the compiler.

--cc is used to specify the name of the c compiler, and --cxx is used to specify the name of the c++ compiler.

Note: If the cc/cxx environment variable exists, the value specified in the current environment variable will be used first.

If the specified compiler name is not a name recognized by xmake (with gcc, clang, etc.), then the compiler tool detection will fail.

At this time we can pass:

xmake f --cxx=clang++@/home/xxx/c++mips.exe

Set the c ++ mips.exe compiler as the clang ++-like way to compile.

That is to say, while specifying the compiler as c++mips.exe, tell xmake that it is basically the same as clang ++ usage and parameter options.

Set the c/c++ linker

If you want to continue to subdivide and select the linker, continue to add related linker options, for example:

$ xmake f -p linux --sdk=/user/toolsdk --ld=armv7-linux-clang++ --sh=armv7-linux-clang++ --ar=armv7-linux-ar

ld specifies the executable program linker, sh specifies the shared library program linker, and ar specifies the archiver that generates the static library.

Note: If there are ld/sh/ar environment variables, the value specified in the current environment variable will be used first.

Set header file and library search directory

If there are additional other include/lib directories in the SDK that are not in the standard structure, resulting in cross compilation can not find the library and header files, then we can append the search path through --includedirs and--linkdirs, and then Add additional link libraries via --links.

$ xmake f -p linux --sdk=/usr/toolsdk --includedirs=/usr/toolsdk/xxx/include --linkdirs=/usr/toolsdk/xxx/lib --links=pthread

Note: If you want to specify multiple search directories, you can use : or ; to separate, which is the path separator of different host platforms, use : under linux / macos, and ; under win.

Set compile and link options

We can also configure some additional compilation and linking options through --cflags,--cxxflags, --ldflags, --shflags and --arflags according to the actual situation.

e.g:

$ xmake f -p linux --sdk=/usr/toolsdk --cflags="-DTEST -I/xxx/xxx" --ldflags="-lpthread"

Project description settings

set_toolchains

This sets up different tool chains for a specific target individually. Unlike set_toolset, this interface is an overall switch for a complete tool chain, such as cc/ld/sh and a series of tool sets.

This is also a recommended practice, because most compiler tool chains like gcc/clang, the compiler and the linker are used together. To cut it, you have to cut it as a whole. Separate and scattered switch settings will be cumbersome.

For example, we switch the test target to two tool chains of clang+yasm:

target("test")
    set_kind("binary")
    add_files("src/*.c")
    set_toolchains("clang", "yasm")

set_toolset

If you feel that it is more complicated to configure through the command line each time, some configurations can be pre-configured in xmake.lua to simplify the command configuration. For example, the specification of the compiler can be set individually for each target through set_toolset.

target("test")
    set_kind("binary")
    set_toolset("cxx", "clang")
    set_toolset("ld", "clang++")

Force the compiler and linker of the test target to use the clang compiler, or specify the compiler name or path in the cross-compilation tool chain.

set_config

We can also set the default value of each configuration parameter in the xmake f/config command through set_config. This is a global api and will take effect for each target.

set_config("cflags", "-DTEST")
set_config("sdk", "/home/xxx/tooksdk")
set_config("cc", "gcc")
set_config("ld", "g++")

However, we can still use xmake f --name = value` to modify the default configuration in xmake.lua.

Custom build platform

If the target program has a corresponding platform to be specified after a cross tool chain is compiled, and it needs to be configured in xmake.lua according to different cross compilation platforms, and some additional compilation parameters need to be configured, then the -p cross setting above Can not meet the demand.

In fact, the -p/-plat= parameter can also be set to other custom values. You only need to maintain the corresponding relationship with is_plat. All non-built-in platform names will default to cross-compilation mode, for example:

$ xmake f -p myplat --sdk=/usr/local/arm-xxx-gcc/
$ xmake

We passed in the myplat custom platform name as the current cross-toolchain compilation platform, and then we set the corresponding settings for this platform in xmake.lua:

if is_plat("myplat") then
    add_defines("TEST")
end

In this way, xmake can be easily extended to deal with various compilation platforms, users can extend their own support for freebsd, netbsd, sunos and other cross-compiling platforms.

I excerpted a cross-compilation configuration written before porting libuv, and intuitively feel:

-- for gragonfly/freebsd/netbsd/openbsd platform
if is_plat("gragonfly", "freebsd", "netbsd", "openbsd") then
    add_files("src/unix/bsd-ifaddrs.c")
    add_files("src/unix/freebsd.c")
    add_files("src/unix/kqueue.c")
    add_files("src/unix/posix-hrtime.c")
    add_headerfiles("(include/uv-bsd.h)")
end 

-- for sunos platform
if is_plat("sunos") then
    add_files("src/unix/no-proctitle.c")
    add_files("src/unix/sunos.c")
    add_defines("__EXTENSIONS_", "_XOPEN_SOURCE=600")
    add_headerfiles("(include/uv-sunos.h)")
end

Then, we can switch these platforms to compile:

$ xmake f -p [gragonfly|freebsd|netbsd|openbsd|sunos] --sdk=/home/arm-xxx-gcc/
$ xmake

In addition, the built-in Linux platform also supports cross-compilation. If you do n’t want to configure other platform names, you can cross-compile as the linux platform.

$ xmake f -p linux --sdk=/usr/local/arm-xxx-gcc/
$ xmake

As long as the --sdk= and other parameters are set, the cross-compilation mode of the Linux platform will be enabled.

Toolchain configuration

!> This feature requires v2.3.4 or later to support

The above describes the general cross-compilation toolchain configuration. If some specific toolchains need to be imported into additional scenarios such as --ldflags/--includedirs, it is more cumbersome
Therefore, xmake also has some common tool chains built-in, which can save the complicated configuration process of cross-compilation tool chain, and only need to execute:

$ xmake f --toolchain=gnu-rm --sdk=/xxx/
$ xmake

You can quickly switch the designated cross-compilation tool chain. If this tool chain needs to add some specific flags settings, it will be automatically set up to simplify configuration.

Among them, gnu-rm is the built-in GNU Arm Embedded Toolchain.

For example, we can also quickly switch from the entire gcc tool chain to the clang or llvm tool chain, no longer need to make xmake f --cc=clang --cxx=clang --ld=clang++ one by one.

$ xmake f --toolchain=clang
$ xmake

or

$ xmake f --toolchain=llvm --sdk=/xxx/llvm
$ xmake

The specific tool chains supported by xmake can be viewed with the following command:

$ xmake show -l toolchains
xcode         Xcode IDE
vs            VisualStudio IDE
yasm          The Yasm Modular Assembler
clang         A C language family frontend for LLVM
go            Go Programming Language Compiler
dlang         D Programming Language Compiler
sdcc          Small Device C Compiler
cuda          CUDA Toolkit
ndk           Android NDK
rust          Rust Programming Language Compiler
llvm          A collection of modular and reusable compiler and toolchain technologies
cross         Common cross compilation toolchain
nasm          NASM Assembler
gcc           GNU Compiler Collection
mingw         Minimalist GNU for Windows
gnu-rm        GNU Arm Embedded Toolchain
envs          Environment variables toolchain
fasm          Flat Assembler

Custom toolchain

In addition, we can also customize the toolchain in xmake.lua, and then specify the switch through xmake f --toolchain=myclang, for example:

toolchain("myclang")
    set_kind("standalone")
    set_toolset("cc", "clang")
    set_toolset("cxx", "clang", "clang++")
    set_toolset("ld", "clang++", "clang")
    set_toolset("sh", "clang++", "clang")
    set_toolset("ar", "ar")
    set_toolset("ex", "ar")
    set_toolset("strip", "strip")
    set_toolset("mm", "clang")
    set_toolset("mxx", "clang", "clang++")
    set_toolset("as", "clang")

    - ...

For details about this piece, you can go to the Custom Toolchain.

For more details, please see: #780

MingW Toolchain

Compiling with the mingw toolchain is actually cross-compilation, but because this is more commonly used, xmake specifically adds a mingw platform to quickly handle compilation using the mingw toolchain.

Therefore, xmake's toolchain detection for mingw will be more perfect. Under macos, basically even the sdk path does not need to be configured, and can be directly detected, only need to switch to the mingw platform to compile.

$ xmake f -p mingw
$ xmake -v
configure
{
    ld = /usr/local/opt/mingw-w64/bin/x86_64-w64-mingw32-g++
    ndk_stdcxx = true
    plat = mingw
    mingw = /usr/local/opt/mingw-w64
    buildir = build
    arch = x86_64
    xcode = /Applications/Xcode.app
    mode = release
    cxx = /usr/local/opt/mingw-w64/bin/x86_64-w64-mingw32-gcc
    cross = x86_64-w64-mingw32-
    theme = default
    kind = static
    ccache = true
    host = macosx
    clean = true
    bin = /usr/local/opt/mingw-w64/bin
}
[  0%]: ccache compiling.release src/main.cpp
/usr/local/bin/ccache /usr/local/opt/mingw-w64/bin/x86_64-w64-mingw32-gcc -c -fvisibility=hidden -O3 -m64 -o build/.objs/test/mingw/x86_64/release/src/main.cpp.obj src/main.cpp
[100%]: linking.release test.exe
/usr/local/opt/mingw-w64/bin/x86_64-w64-mingw32-g++ -o build/mingw/x86_64/release/test.exe build/.objs/test/mingw/x86_64/release/src/main.cpp.obj -s -fvisibility=hidden -m64
build ok!

Here we have added the -v parameter and looked at the detailed compile commands and detected mingw toolchain configuration values, where cross is automatically detected as:x86_64-w64-mingw32-, and the bin directory is also automatically detected , As well as compilers and linkers.

Although it is not possible to automatically detect the sdk path on linux/win, we can also manually specify the sdk path. It should be noted that xmake specifically provides a --mingw = parameter for mingw to specify the tool chain root of mingw The directory has the same effect as --sdk =, but it can be set as a global configuration.

$ xmake g --mingw=/home/mingwsdk
$ xmake f -p mingw
$ xmake

After setting the --mingw root directory to the global configuration through thexmake g/global command, after each compilation and switching of the compilation platform, there is no need to specify an additional mingw toolchain path, which is convenient for use.

In addition, the usage of other tool chain configuration parameters is the same as that described above. For example, --cross,--bin=, etc. can be adjusted according to the actual needs of the environment. Own mingw tool chain.

LLVM Toolchain

The tool chain of llvm is relatively standard, only need to set the sdk configuration path to use:

$ xmake f -p cross --toolchain=llvm --sdk="C:\Program Files\LLVM"
$ xmake

GNU-RM Toolchain

toolchain downlaod url: https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads#

$ xmake f -p cross --toolchain=gnu-rm --sdk=/xxx/cc-arm-none-eabi-9-2019-q4-major
$ xmake

Common Cross-compilation configuration

Configuration Option Description
--sdk Set the sdk root directory of toolchains
--bin Set the bin directory of toolchains
--cross Set the prefix of compilation tools
--as Set asm assembler
--cc Set c compiler
--cxx Set c++ compiler
--mm Set objc compiler
--mxx Set objc++ compiler
--sc Set swift compiler
--gc Set golang compiler
--dc Set dlang compiler
--rc Set rust compiler
--cu Set cuda compiler
--ld Set c/c++/objc/asm linker
--sh Set c/c++/objc/asm shared library linker
--ar Set c/c++/objc/asm static library archiver
--scld Set swift linker
--scsh Set swift shared library linker
--gcld Set golang linker
--gcar Set golang static library archiver
--dcld Set dlang linker
--dcsh Set dlang shared library linker
--dcar Set dlang static library archiver
--rcld Set rust linker
--rcsh Set rust shared library linker
--rcar Set rust static library archiver
--cu-ccbin Set cuda host compiler
--culd Set cuda linker
--asflags Set asm assembler option
--cflags Set c compiler option
--cxflags Set c/c++ compiler option
--cxxflags Set c++ compiler option
--mflags Set objc compiler option
--mxflags Set objc/c++ compiler option
--mxxflags Set objc++ compiler option
--scflags Set swift compiler option
--gcflags Set golang compiler option
--dcflags Set dlang compiler option
--rcflags Set rust compiler option
--cuflags Set cuda compiler option
--ldflags Set linker option
--shflags Set shared library linker option
--arflags Set static library archiver option


if you want to known more options, please run: xmake f --help

--sdk

xmake provides a convenient and flexible cross-compiling support.
In most cases, we need not to configure complex toolchains prefix, for example: arm-linux-

As long as this toolchains meet the following directory structure:

/home/toolchains_sdkdir
   - bin
       - arm-linux-gcc
       - arm-linux-ld
       - ...
   - lib
       - libxxx.a
   - include
       - xxx.h

Then,we can only configure the sdk directory and build it.

$ xmake f -p linux --sdk=/home/toolchains_sdkdir
$ xmake

xmake will detect the prefix: arm-linux- and add the include and library search directory automatically.

-I/home/toolchains_sdkdir/include -L/home/toolchains_sdkdir/lib

--bin

We need set it manually if the toolchains /bin directory is in other places, for example:

$ xmake f -p linux --sdk=/home/toolchains_sdkdir --bin=/usr/opt/bin
$ xmake


Before v2.2.1 version, this parameter name is --toolchains, exists more ambiguous, so we changed to --bin= to set the bin directory.

--cross

For example, under the same toolchains directory at the same time, there are two different compilers:

/opt/bin
 - armv7-linux-gcc
 - aarch64-linux-gcc

If we want to use the armv7-linux-gcc compiler, we can run the following command:

$ xmake f -p linux --sdk=/usr/toolsdk --bin=/opt/bin --cross=armv7-linux-

--as

$ xmake f -p linux --sdk=/user/toolsdk --as=armv7-linux-as

If the 'AS' environment variable exists, it will use the values specified in the current environment variables.


We can set a unknown compiler as like-gcc/clang compiler, .e.g xmake f --as=gcc@/home/xxx/asmips.exe

--cc

$ xmake f -p linux --sdk=/user/toolsdk --cc=armv7-linux-clang

If the 'CC' environment variable exists, it will use the values specified in the current environment variables.


We can set a unknown compiler as like-gcc/clang compiler, .e.g xmake f --cc=gcc@/home/xxx/ccmips.exe

--cxx

$ xmake f -p linux --sdk=/user/toolsdk --cxx=armv7-linux-clang++

If the 'CXX' environment variable exists, it will use the values specified in the current environment variables.


We can set a unknown compiler as like-gcc/clang compiler, .e.g xmake f --cxx=g++@/home/xxx/c++mips.exe

--ld

$ xmake f -p linux --sdk=/user/toolsdk --ld=armv7-linux-clang++

If the 'LD' environment variable exists, it will use the values specified in the current environment variables.


We can set a unknown compiler as like-gcc/clang linker, .e.g xmake f --ld=g++@/home/xxx/c++mips.exe

--sh

$ xmake f -p linux --sdk=/user/toolsdk --sh=armv7-linux-clang++

If the 'SH' environment variable exists, it will use the values specified in the current environment variables.


We can set a unknown compiler as like-gcc/clang linker, .e.g xmake f --sh=g++@/home/xxx/c++mips.exe

--ar

$ xmake f -p linux --sdk=/user/toolsdk --ar=armv7-linux-ar

If the 'AR' environment variable exists, it will use the values specified in the current environment variables.


We can set a unknown compiler as like-ar archiver, .e.g xmake f --ar=ar@/home/xxx/armips.exe

Global Configuration

You can save to the global configuration for simplfying operation.

For example:

$ xmake g --ndk=~/files/android-ndk-r10e/

Now, we config and build project for android again.

$ xmake f -p android
$ xmake


You can use short or long command option, for example: xmake g or xmake global.

Clean Configuration

We can clean all cached configuration and re-configure project.

$ xmake f -c
$ xmake

or

$ xmake f -p iphoneos -c
$ xmake