快速开始

2000-02-22 ruki 更多博文 » 博客 » GitHub »

xmake 文档 快速开始

原文链接 https://waruqi.github.io/docs/xmake/quickstart/
注:以下为加速网络访问所做的原文缓存,经过重新格式化,可能存在格式方面的问题,或偶有遗漏信息,请以原文为准。


  • content {:toc}

注:此处为镜像文档,最新在线文档请看:http://xmake.io/#/zh/

xmake

一个基于Lua的轻量级跨平台自动构建工具

简介

XMake是一个基于Lua的轻量级跨平台自动构建工具,支持在各种主流平台上构建项目

xmake的目标是开发者更加关注于项目本身开发,简化项目的描述和构建,并且提供平台无关性,使得一次编写,随处构建

它跟cmake、automake、premake有点类似,但是机制不同,它默认不会去生成IDE相关的工程文件,采用直接编译,并且更加的方便易用 采用lua的工程描述语法更简洁直观,支持在大部分常用平台上进行构建,以及交叉编译

并且xmake提供了创建、配置、编译、打包、安装、卸载、运行等一些actions,使得开发和构建更加的方便和流程化。

不仅如此,它还提供了许多更加高级的特性,例如插件扩展、脚本宏记录、批量打包、自动文档生成等等。。

安装

Master版本

使用curl
bash <(curl -fsSL https://raw.githubusercontent.com/tboox/xmake/master/scripts/get.sh)
使用wget
bash <(wget https://raw.githubusercontent.com/tboox/xmake/master/scripts/get.sh -O -)
使用powershell
Invoke-Expression (Invoke-Webrequest 'https://raw.githubusercontent.com/tboox/xmake/master/scripts/get.ps1' -UseBasicParsing).Content

Windows

  1. Releases 上下载windows安装包
  2. 运行安装程序 xmake-[version].exe

MacOS

$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
$ brew install xmake

或者:

  1. Releases 上下载pkg安装包
  2. 双击运行

或者安装master版本:

# 使用homebrew安装master版本
$ brew install xmake --HEAD

# 或者直接调用shell下载安装
$ bash <(curl -fsSL https://raw.githubusercontent.com/tboox/xmake/master/scripts/get.sh)

Linux

在archlinux上安装:

$ yaourt xmake

在ubuntu上安装:

$ sudo add-apt-repository ppa:tboox/xmake
$ sudo apt-get update
$ sudo apt-get install xmake

或者手动添加包源:

deb http://ppa.launchpad.net/tboox/xmake/ubuntu yakkety main 
deb-src http://ppa.launchpad.net/tboox/xmake/ubuntu yakkety main 

然后执行:

$ sudo apt-get update
$ sudo apt-get install xmake

或者下载deb包来安装:

  1. Releases 上下载deb安装包
  2. 运行: dpkg -i xmake-xxxx.deb

redhat/centos上安装:

  1. Releases 上下载rpm安装包
  2. 运行: yum install xmake-xxx.rpm --nogpgcheck

编译安装

通过脚本编译安装:

$ git clone https://github.com/tboox/xmake.git
$ cd ./xmake
$ ./scripts/get.sh __local__

仅仅安装和更新xmake的lua脚本:

$ ./scripts/get.sh __local__ __install_only__

卸载:

$ ./scripts/get.sh __uninstall__

通过make进行编译安装:

$ make build; sudo make install

安装到其他指定目录:

$ sudo make install prefix=/usr/local

卸载:

$ sudo make uninstall

快速开始

asciicast

创建工程

创建一个名叫helloc控制台工程:

$ xmake create -l c -P ./hello

执行完后,将会生成一个简单工程结构:

hello
├── src
│   └── main.c
└── xmake.lua

其中xmake.lua是工程描述文件,内容非常简单,告诉xmake添加src目录下的所有.c源文件:

target("hello")
    set_kind("binary")
    add_files("src/*.c") 

目前支持的语言如下:

  • c/c++
  • objc/c++
  • asm
  • swift
  • dlang
  • golang
  • rust

如果你想了解更多参数选项,请运行: xmake create --help

构建工程

$ xmake

运行程序

$ xmake run hello

调试程序

$ xmake run -d hello 

xmake将会使用系统自带的调试器去加载程序运行,目前支持:lldb, gdb, windbg, vsjitdebugger, ollydbg 等各种调试器。

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

你也可以使用简写的命令行选项,例如: xmake r 或者 xmake run

工程实例

可执行程序

target("test")
    set_kind("binary")
    add_files("src/*c")

静态库程序

target("library")
    set_kind("static")
    add_files("src/library/*.c")

target("test")
    set_kind("binary")
    add_files("src/*c")
    add_deps("library")

通过add_deps将一个静态库自动链接到test可执行程序。

动态库程序

target("library")
    set_kind("shared")
    add_files("src/library/*.c")

target("test")
    set_kind("binary")
    add_files("src/*c")
    add_deps("library")

通过add_deps将一个动态库自动链接到test可执行程序。

配置

通过xmake f|config配置命令,设置构建前的相关配置信息,详细参数选项,请运行: xmake f --help

你可以使用命令行缩写来简化输入,也可以使用全名,例如: xmake f 或者 xmake config. xmake f -p linux 或者 xmake config --plat=linux.

目标平台

主机平台
$ xmake

xmake将会自动探测当前主机平台,默认自动生成对应的目标程序。

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

如果要手动指定ndk中具体某个工具链,而不是使用默认检测的配置,可以通过--toolchains来设置,例如:

$ 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

--toolchains主要用于设置选择编译工具的具体bin目录,这个的使用跟交叉编译中的--toolchains的行为是一致的。

如果手动设置了toolchains的bin目录,没有通过检测,可以看下是否--arch=参数没有匹配对。

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
交叉编译

linux平台的交叉编译:

$ xmake f -p linux --sdk=/usr/local/arm-linux-gcc/ [--toolchains=/sdk/bin] [--cross=arm-linux-]
$ xmake

其他平台的交叉编译:

$ xmake f -p cross --sdk=/usr/local/arm-xxx-gcc/ [--toolchains=/sdk/bin] [--cross=arm-linux-]
$ xmake

如果不关心实际的平台名,只想交叉编译,可以直接用上面的命令,如果需要通过is_plat("myplat")判断自己的平台逻辑,则:

$ xmake f -p myplat --sdk=/usr/local/arm-xxx-gcc/ [--toolchains=/sdk/bin] [--cross=arm-linux-]
$ xmake

其中:

参数名 描述
--sdk 设置交叉工具链的sdk根目录
--toolchains 设置工具链bin目录
--cross 设置交叉工具链工具前缀
--as 设置asm汇编器
--cc 设置c编译器
--cxx 设置c++编译器
--mm 设置objc编译器
--mxx 设置objc++编译器
--sc 设置swift编译器
--gc 设置golang编译器
--dc 设置dlang编译器
--rc 设置rust编译器
--ld 设置c/c++/objc/asm链接器
--sh 设置c/c++/objc/asm共享库链接器
--ar 设置c/c++/objc/asm静态库归档器
--sc-ld 设置swift链接器
--sc-sh 设置swift共享库链接器
--gc-ld 设置golang链接器
--gc-ar 设置golang静态库归档器
--dc-ld 设置dlang链接器
--dc-sh 设置dlang共享库链接器
--dc-ar 设置dlang静态库归档器
--rc-ld 设置rust链接器
--rc-sh 设置rust共享库链接器
--rc-ar 设置rust静态库归档器
--asflags 设置asm汇编编译选项
--cflags 设置c编译选项
--cxflags 设置c/c++编译选项
--cxxflags 设置c++编译选项
--mflags 设置objc编译选项
--mxflags 设置objc/c++编译选项
--mxxflags 设置objc++编译选项
--scflags 设置swift编译选项
--gcflags 设置golang编译选项
--dcflags 设置dlang编译选项
--rcflags 设置rust编译选项
--ldflags 设置链接选项
--shflags 设置共享库链接选项
--arflags 设置静态库归档选项

如果你想要了解更多参数选项,请运行: xmake f --help

--sdk
  • 设置交叉工具链的sdk根目录

大部分情况下,都不需要配置很复杂的toolchains前缀,例如:arm-linux- 什么的

只要这个工具链的sdk目录满足如下结构(大部分的交叉工具链都是这个结构):

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

那么,使用xmake进行交叉编译的时候,只需要进行如下配置和编译:

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

这个时候,xmake会去自动探测,gcc等编译器的前缀名:arm-linux-,并且编译的时候,也会自动加上链接库头文件的搜索选项,例如:

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

这些都是xmake自动处理的,不需要手动配置他们。。

--toolchains
  • 设置工具链bin目录

对于不规则工具链目录结构,靠单纯地--sdk选项设置,没法完全检测通过的情况下,可以通过这个选项继续附加设置工具链的bin目录位置。

例如:一些特殊的交叉工具链的,编译器bin目录,并不在 /home/toolchains_sdkdir/bin 这个位置,而是独立到了 /usr/opt/bin

$ xmake f -p linux --sdk=/home/toolchains_sdkdir --toolchains=/usr/opt/bin
$ xmake
--cross
  • 设置交叉工具链工具前缀

aarch64-linux-android-这种,通常如果你配置了--sdk或者--toolchains的情况下,xmake会去自动检测的,不需要自己手动设置。

但是对于一些极特殊的工具链,一个目录下同时有多个cross前缀的工具bin混在一起的情况,你需要手动设置这个配置,来区分到底需要选用哪个bin。

例如,toolchains的bin目录下同时存在两个不同的编译器:

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

我们现在想要选用armv7的版本,则配置如下:

$ xmake f -p linux --sdk=/usr/toolsdk --toolchains=/opt/bin --cross=armv7-linux-
--as
  • 设置asm汇编器

如果还要继续细分选择编译器,则继续追加相关编译器选项,例如:

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

如果存在AS环境变量的话,会优先使用当前环境变量中指定的值。

如果指定的编译器名不是那些xmake内置可识别的名字(带有gcc, clang等字样),那么编译器工具检测就会失败。 这个时候我们可以通过:xmake f --as=gcc@/home/xxx/asmips.exe 设置ccmips.exe编译器作为类gcc的使用方式来编译。 也就是说,在指定编译器为asmips.exe的同时,告诉xmake,它跟gcc用法和参数选项基本相同。

--cc
  • 设置c编译器

如果还要继续细分选择编译器,则继续追加相关编译器选项,例如:

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

如果存在CC环境变量的话,会优先使用当前环境变量中指定的值。

如果指定的编译器名不是那些xmake内置可识别的名字(带有gcc, clang等字样),那么编译器工具检测就会失败。 这个时候我们可以通过:xmake f --cc=gcc@/home/xxx/ccmips.exe 设置ccmips.exe编译器作为类gcc的使用方式来编译。 也就是说,在指定编译器为ccmips.exe的同时,告诉xmake,它跟gcc用法和参数选项基本相同。

--cxx
  • 设置c++编译器

如果还要继续细分选择编译器,则继续追加相关编译器选项,例如:

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

如果存在CXX环境变量的话,会优先使用当前环境变量中指定的值。

如果指定的编译器名不是那些xmake内置可识别的名字(带有gcc, clang等字样),那么编译器工具检测就会失败。 这个时候我们可以通过:xmake f --cxx=clang++@/home/xxx/c++mips.exe 设置c++mips.exe编译器作为类clang++的使用方式来编译。 也就是说,在指定编译器为c++mips.exe的同时,告诉xmake,它跟clang++用法和参数选项基本相同。

--ld
  • 设置c/c++/objc/asm链接器

如果还要继续细分选择链接器,则继续追加相关编译器选项,例如:

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

如果存在LD环境变量的话,会优先使用当前环境变量中指定的值。

如果指定的编译器名不是那些xmake内置可识别的名字(带有gcc, clang等字样),那么链接器工具检测就会失败。 这个时候我们可以通过:xmake f --ld=g++@/home/xxx/c++mips.exe 设置c++mips.exe链接器作为类g++的使用方式来编译。 也就是说,在指定链接器为c++mips.exe的同时,告诉xmake,它跟g++用法和参数选项基本相同。

--sh
  • 设置c/c++/objc/asm共享库链接器
$ xmake f -p linux --sdk=/user/toolsdk --sh=armv7-linux-clang++

如果存在SH环境变量的话,会优先使用当前环境变量中指定的值。

如果指定的编译器名不是那些xmake内置可识别的名字(带有gcc, clang等字样),那么链接器工具检测就会失败。 这个时候我们可以通过:xmake f --sh=g++@/home/xxx/c++mips.exe 设置c++mips.exe链接器作为类g++的使用方式来编译。 也就是说,在指定链接器为c++mips.exe的同时,告诉xmake,它跟g++用法和参数选项基本相同。

--ar
  • 设置c/c++/objc/asm静态库归档器
$ xmake f -p linux --sdk=/user/toolsdk --ar=armv7-linux-ar

如果存在AR环境变量的话,会优先使用当前环境变量中指定的值。

如果指定的编译器名不是那些xmake内置可识别的名字(带有ar等字样),那么链接器工具检测就会失败。 这个时候我们可以通过:xmake f --ar=ar@/home/xxx/armips.exe 设置armips.exe链接器作为类ar的使用方式来编译。 也就是说,在指定链接器为armips.exe的同时,告诉xmake,它跟ar用法和参数选项基本相同。

全局配置

我们也可以将一些常用配置保存到全局配置中,来简化频繁地输入:

例如:

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

现在,我们重新配置和编译android程序:

$ xmake f -p android
$ xmake

以后,就不需要每次重复配置--ndk=参数了。

每个命令都有其简写,例如: xmake g 或者 xmake global.

清除配置

有时候,配置出了问题编译不过,或者需要重新检测各种依赖库和接口,可以加上-c参数,清除缓存的配置,强制重新检测和配置

$ xmake f -c
$ xmake

或者:

$ xmake f -p iphoneos -c
$ xmake

问答

怎样获取更多参数选项信息?

获取主菜单的帮助信息,里面有所有action和plugin的列表描述。

$ xmake [-h|--help]

获取配置菜单的帮助信息,里面有所有配置选项的描述信息,以及支持平台、架构列表。

$ xmake f [-h|--help]

获取action和plugin命令菜单的帮助信息,里面有所有内置命令和插件任务的参数使用信息。

$ xmake [action|plugin] [-h|--help]

例如,获取run命令的参数信息:

$ xmake run --help

怎样实现静默构建,不输出任何信息?

$ xmake [-q|--quiet]

如果xmake运行失败了怎么办?

可以先尝试清除下配置,重新构建下:

$ xmake f -c
$ xmake

如果还是失败了,请加上 -v 或者 --verbose 选项重新执行xmake后,获取更加详细的输出信息

例如:

$ xmake [-v|--verbose] 

并且可以加上 --backtrace 选项获取出错时的xmake的调试栈信息, 然后你可以提交这些信息到issues.

$ xmake -v --backtrace

怎样看实时编译警告信息?

为了避免刷屏,在构建时候,默认是不实时输出警告信息的,如果想要看的话可以加上-w选项启用编译警告输出就行了。

$ xmake [-w|--warning] 

怎样基于源码自动生成xmake.lua

如果你想临时写一两个测试代码、或者手上有一些移植过来的零散源码想要快速编译运行,可以不用专门xmake.lua,直接运行:

$ xmake

xmake会自动扫描分析当前的源码目录,识别程序结构和类型,生成一个xmake.lua,并且会尝试直接构建它。

如果编译成功,可以直接运行:

$ xmake run

当然,如果仅仅只是想要生成xmake.lua,默认不去构建,可以执行:

$ xmake f -y

更多相关介绍,请参考文章:xmake新增智能代码扫描编译模式,无需手写任何make文件

支持项目

xmake项目属于个人开源项目,它的发展需要您的帮助,如果您愿意支持xmake项目的开发,欢迎为其捐赠,支持它的发展。 🙏 [支持此项目]

赞助项目

通过赞助支持此项目,您的logo和网站链接将显示在这里。[赞助此项目]