Quick Start
Note: This documents is only a mirror, if you want to see newest documents please goto: http://xmake.io/#/home/
xmake
A cross-platform build utility based on Lua
Introduction
xmake is a cross-platform build utility based on lua.
The project focuses on making development and building easier and provides many features (.e.g package, install, plugin, macro, action, option, task …), so that any developer can quickly pick it up and enjoy the productivity boost when developing and building project.
Installation
Master
via curl
bash <(curl -fsSL https://raw.githubusercontent.com/tboox/xmake/master/scripts/get.sh)
via wget
bash <(wget https://raw.githubusercontent.com/tboox/xmake/master/scripts/get.sh -O -)
via powershell
Invoke-Expression (Invoke-Webrequest 'https://raw.githubusercontent.com/tboox/xmake/master/scripts/get.ps1' -UseBasicParsing).Content
Windows
- Download xmake windows installer from Releases
- Run xmake-[version].exe
MacOS
$ brew install xmake
Linux
On Archlinux:
$ yaourt xmake
On Ubuntu:
$ sudo add-apt-repository ppa:tboox/xmake
$ sudo apt update
$ sudo apt install xmake
Or add xmake package source manually:
deb http://ppa.launchpad.net/tboox/xmake/ubuntu yakkety main
deb-src http://ppa.launchpad.net/tboox/xmake/ubuntu yakkety main
Then we run:
$ sudo apt update
$ sudo apt install xmake
Or download deb package to install it:
- Download xmake
.debinstall package from Releases - Run
dpkg -i xmake-xxxx.deb
Compilation
Compile and install:
$ git clone https://github.com/xmake-io/xmake.git
$ cd ./xmake
$ ./scripts/get.sh __local__
Only install and update lua scripts:
$ ./scripts/get.sh __local__ __install_only__
Uninstall:
$ ./scripts/get.sh __uninstall__
Or compile and install via make:
$ make build; sudo make install
Install to other given directory:
$ sudo make install prefix=/usr/local
Uninstall:
$ sudo make uninstall
Quick Start
Create Project
$ xmake create -l c -P ./hello
And xmake will generate some files for c language project:
hello
├── src
│ └── main.c
└── xmake.lua
It is a simple console program only for printing hello xmake!
The content of xmake.lua is very simple:
target("hello")
set_kind("binary")
add_files("src/*.c")
Support languages:
- c/c++
- objc/c++
- asm
- swift
- dlang
- golang
- rust
If you want to known more options, please run: `xmake create --help`
Build Project
$ xmake
Run Program
$ xmake run hello
Debug Program
$ xmake run -d hello
It will start the debugger (.e.g lldb, gdb, windbg, vsjitdebugger, ollydbg ..) to load our program.
[lldb]$target create "build/hello"
Current executable set to 'build/hello' (x86_64).
[lldb]$b main
Breakpoint 1: where = hello`main, address = 0x0000000100000f50
[lldb]$r
Process 7509 launched: '/private/tmp/hello/build/hello' (x86_64)
Process 7509 stopped
* thread #1: tid = 0x435a2, 0x0000000100000f50 hello`main, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1
frame #0: 0x0000000100000f50 hello`main
hello`main:
-> 0x100000f50 <+0>: pushq %rbp
0x100000f51 <+1>: movq %rsp, %rbp
0x100000f54 <+4>: leaq 0x2b(%rip), %rdi ; "hello world!"
0x100000f5b <+11>: callq 0x100000f64 ; symbol stub for: puts
[lldb]$
You can also use short command option, for exmaple: `xmake r` or `xmake run`
Project Examples
Executable Program
target("test")
set_kind("binary")
add_files("src/*c")
Static Library Program
target("library")
set_kind("static")
add_files("src/library/*.c")
target("test")
set_kind("binary")
add_files("src/*c")
add_deps("library")
We use add_deps to link a static library to test target.
Share Library Program
target("library")
set_kind("shared")
add_files("src/library/*.c")
target("test")
set_kind("binary")
add_files("src/*c")
add_deps("library")
We use add_deps to link a share library to test target.
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 exmaple:
`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 armv5te|armv6|armv7-a|armv8-a|arm64-v8a]
$ xmake
If you want to set the other android toolchains, you can use –toolchains option.
For example:
$ xmake f -p android --ndk=~/files/android-ndk-r10e/ -a arm64-v8a --toolchains=~/files/android-ndk-r10e/toolchains/aarch64-linux-android-4.9/prebuilt/darwin-x86_64/bin
The –toolchains 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
For linux platform:
$ xmake f -p linux --sdk=/usr/local/arm-linux-gcc/ [--toolchains=/sdk/bin] [--cross=arm-linux-]
$ xmake
Fro other cross platform:
$ xmake f -p cross --sdk=/usr/local/arm-xxx-gcc/ [--toolchains=/sdk/bin] [--cross=arm-linux-]
$ xmake
For custem cross platform (is_plat("myplat")):
$ xmake f -p myplat --sdk=/usr/local/arm-xxx-gcc/ [--toolchains=/sdk/bin] [--cross=arm-linux-]
$ xmake
| Configuration Option | Description |
|---|---|
| –sdk | Set the sdk root directory of toolchains |
| –toolchains | 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 |
| –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 |
| –sc-ld | Set swift linker |
| –sc-sh | Set swift shared library linker |
| –gc-ld | Set golang linker |
| –gc-ar | Set golang static library archiver |
| –dc-ld | Set dlang linker |
| –dc-sh | Set dlang shared library linker |
| –dc-ar | Set dlang static library archiver |
| –rc-ld | Set rust linker |
| –rc-sh | Set rust shared library linker |
| –rc-ar | Set rust static library archiver |
| –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 |
| –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
- Set the sdk root directory of toolchains
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
–toolchains
- Set the
bindirectory of toolchains
We need set it manually if the toolchains /bin directory is in other places, for example:
$ xmake f -p linux --sdk=/home/toolchains_sdkdir --toolchains=/usr/opt/bin
$ xmake
–cross
- Set the prefix of compilation tools
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 --toolchains=/opt/bin --cross=armv7-linux-
–as
- Set
asmassembler
$ 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
- Set c compiler
$ 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
- Set
c++compiler
$ 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
- Set
c/c++/objc/asmlinker
$ 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
- Set
c/c++/objc/asmshared library linker
$ 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
- Set
c/c++/objc/asmstatic library archiver
$ 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 exmaple: `xmake g` or `xmake global`.
Clean Configuration
We can clean all cached configuration and re-configure projecct.
$ xmake f -c
$ xmake
or
$ xmake f -p iphoneos -c
$ xmake
FAQ
How to get verbose command-line arguments info?
Get the help info of the main command.
$ xmake [-h|--help]
Get the help info of the configuration command.
$ xmake f [-h|--help]
Get the help info of the givent action or plugin command.
$ xmake [action|plugin] [-h|--help]
For example:
$ xmake run --help
How to suppress all output info?
$ xmake [-q|--quiet]
How to do if xmake fails?
Please attempt to clean configuration and rebuild it first.
$ xmake f -c
$ xmake
If it fails again, please add -v or --verbose options to get more verbose info.
For exmaple:
$ xmake [-v|--verbose]
And add --backtrace to get the verbose backtrace info, then you can submit these infos to issues.
$ xmake -v --backtrace
How to see verbose compiling warnings?
$ xmake [-w|--warning]
How to scan source code and generate xmake.lua automaticlly
You only need run the following command:
$ xmake
xmake will scan all source code in current directory and build it automaticlly.
And we can run it directly.
$ xmake run
If we only want to generate xmake.lua file, we can run:
$ xmake f -y
If you want to known more information please see Scan source codes and build project without makefile
Backers
Thank you to all our backers! 🙏 [Become a backer]
Sponsors
Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]
