TBOOX

Quick Start


Note: This documents is only a mirror, if you want to see newest documents please goto: http://xmake.io/#/home/

xmake

travis-ci appveyor-ci Coverage Github All Releases AUR votes
license Gitter Telegram Bearychat QQ Donate

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

  1. Download xmake windows installer from Releases
  2. 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:

  1. Download xmake .deb install package from Releases
  2. 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

asciicast

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:

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

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

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

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
$ 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 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]

Content