聊构建工具聊到第25篇今天终于轮到咱们国产选手里的门面担当——xmake。之前我在好几篇文章里都用过它但一直没有正经把“安装卸载install”这条线单独拎出来聊。很多人一提起xmake就只知道它构建快、Lua脚本配置简单却忽略了最基础的安装卸载环节其实藏着不少坑。这篇文章就把“装xmake本体”和“用xmake install装工程产物”这两件事彻底讲透适合被CMake折磨过、想换工具链的C/C开发者也适合刚入坑不知道怎么卸载干净的新手。1. 国产构建工具之王为什么要从安装卸载讲起1.1 xmake是怎么一步步变成“国产之光”的xmake的作者是国人开发者ruki项目从2016年前后开始对外开源到现在已经走过了很长的路。它最核心的设计理念是用Lua脚本描述项目的构建规则代替传统Makefile那一套繁琐的文本格式。你有没有见过那种动辄几百行的CMakeLists.txt变量膨胀、条件分支交错读起来比看老代码还痛苦。xmake的xmake.lua脚本通常只有十几行比如一个最简单的C程序target(hello) set_kind(binary) add_files(src/*.c)就这么三行就能完成一个可执行文件的描述。它自动帮你处理编译器探测、头文件目录、链接参数这些底层琐事不用像CMake那样include_directories、target_link_libraries写一大堆。更别说它原生支持跨平台Windows、Linux、macOS、Android、iOS甚至嵌入式Linux都能跑同一套脚本这放到几年前是想都不敢想的。它火起来不只是因为“简单”而是因为“快”。xmake的构建调度几乎是用C重写的增量编译速度快到离谱在大型项目里明显能感受到和make、ninja的差距。现在很多活跃的开源项目、企业内部的C工程、游戏引擎和中间件团队都在往xmake上迁移社区的中文文档也很齐全这一点对国内开发者极其友好。1.2 install这个词在xmake里有两层含义“安装卸载install”这个标题其实是双关。第一层含义是把xmake工具本身装到你的系统里也就是我们说的“装xmake本体”第二层含义是xmake这个工具提供了一系列和安装卸载相关的命令比如xmake install、xmake uninstall这些命令把构建出来的产物安装到系统目录或者反过来清理掉。这两件事很多新手会搞混。比如你刚装了xmake就跑去敲xmake install结果它给你装了一堆“构建好的项目文件”而不是升级xmake本身——这就是踩了概念的坑。我见过不止一个同事在群里问“为什么我xmake install之后版本没变”其实他根本不该用这条命令而是应该用xmake update来升级本体。反过来说你明明配好了xmake环境但xmake install装完之后发现/usr/local/bin下根本没有可执行文件这也是没搞懂install的目标选择逻辑。这篇文章的核心目标就是帮你把这两层含义彻底分开每一步都讲清楚到底在操作哪个对象。这样无论是日常使用、CI流水线里自动化部署还是写带安装逻辑的开源项目都不会再被绊住。1.3 这篇不是基础教学而是避坑手册网上关于xmake的教程不少但大多数都在讲怎么建工程、怎么写xmake.lua真正把安装卸载这个环节讲细的几乎没有。我写这篇的定位很直接不是带你从零学xmake基础语法而是把安装、卸载、install命令相关的坑全部摊开。每个操作我都会给出实际命令、输出观察点、常见报错以及我自己的处理经验。所以在往下看之前你可以先确认一下自己的状态如果你已经装了xmake但从来没注意过安装目录和卸载方式那第二部分和第四部分对你的帮助最大如果你在写自己的项目想加上安装规则第三部分的参数详解可以直接抄如果你在Windows上被各种权限、杀毒、PATH问题折磨过第五部分的速查表建议先看。2. 先把xmake本体装好安装方式取舍2.1 一行脚本安装curl和PowerShell两套官方最推荐的方式是一键脚本安装。在Linux和macOS上你只需要在终端执行curl -fsSL https://xmake.io/get.sh | bash这个脚本会检测你的系统架构、操作系统类型然后把最新的xmake二进制包下载到用户目录默认放在~/.xmake下面同时自动修改你的shell配置文件比如.bashrc、.zshrc把可执行路径加进PATH。整个过程是无交互的脚本执行完以后新开一个终端窗口就能用xmake --version检查。Windows上的做法也类似用PowerShell执行Invoke-Expression (Invoke-WebRequest https://xmake.io/psget.text -UseBasicParsing).Content它会帮你在用户目录里布置好xmake并写入当前用户的PATH。这个方式对Windows用户很省心不需要你手动去下载安装包也不用关心MSVC、MinGW的路径配置脚本都会尝试自动检测。我个人的经验是这个一键脚本只适合“干净环境”。如果你的环境里存在代理、公司内网隔离、或者是老旧的服务器系统脚本可能会下载超时。遇到这种情况不要硬试直接换包管理器安装效率高得多。2.2 包管理器安装winget、brew、apt各有各的脾气如果你平时开发机已经习惯用包管理器管理软件那xmake基本都已经进仓库了。我用过比较顺的几个组合列一下Windows下可以用winget install xmake。这和你平时用winget install jqlang.jq或者其他命令行工具是一个套路装完自动加入PATH免去手动配置的麻烦。如果你更习惯scoop或chocolatey仓库里也都有。macOS下最无脑的是brew install xmake依赖很少安装过程一般不会出错升级也方便brew upgrade xmake一条命令搞定。Debian/Ubuntu系列官方维护了PPA源需要手动添加一下再apt install xmake具体以官方文档当前的源地址为准。CentOS/RHEL/Fedora这类rpm系环境可以通过yum/dnf搜索xmake找到对应版本后再安装。Arch Linux用户直接用pacman -S xmake属于社区源里维护得比较好的包。包管理器安装最大的优点是“好卸载”。不管什么系统包管理器都会记录文件的安装清单卸载时候一条命令就能清干净这对有洁癖的人特别友好。它的缺点是版本更新会滞后某些发行版的仓库里放的版本可能不是最新的如果你需要用新版本的特性还是得走官方脚本或者源码编译。2.3 源码编译自举进阶玩家才需要最后一种方式是源码编译安装。xmake这个项目的构建方式很有意思它自身是C写的但它的构建系统就是用xmake自己实现的也就是说它要“自己构建自己”。在仓库根目录通常会有一个自举用的Makefile流程大致是git clone https://github.com/xmake-io/xmake.git cd xmake make -f Makefile sudo make install第一次执行make -f Makefile的时候系统里还没有xmake所以这个Makefile会临时编译一个最小的bootstrap版本然后再用这个最小版本去完整编译整个xmake工程最终把可执行文件安装到/usr/local下。这种安装方式适合三类人第一类是想要体验最新开发版功能的人官方脚本和包管理器给的通常都是稳定版第二类是公司内网无法直连官方下载服务器的场景你在有网的机器上把源码包拷进去离线也能编译第三类是喜欢研究构建系统本身的人xmake源码里很多构建细节是值得学习的。但要泼一盆冷水源码编译需要你提前装好C编译器Windows上要有Visual Studio的MSVCLinux上要有gcc/clangmacOS上要有Xcode Command Line Tools。而且编译过程中如果缺第三方库你还得手动处理依赖复杂度明显比前两种方式高一个台阶。不是特别需要不建议日常使用走这条路。2.4 四种方式怎么选一张表说清楚我把上面几种安装方式从适用场景、优点、缺点三个维度整理成了对照表方便你在实际环境中快速决策安装方式适用场景优点缺点官方一键脚本个人开发机、临时环境版本新、无交互、跨平台可能受网络限制卸载需手动处理包管理器安装日常开发主力环境安装卸载简单版本管理统一版本可能滞后于最新版源码编译安装离线环境、想尝鲜最新版可定制、可离线、能深入理解项目依赖前置编译器耗时较长Windows下PowerShell脚本Windows桌面环境自动配置PATH无需手工部分公司安全策略会阻止脚本执行我个人在常态开发环境里推荐包管理器在CI或临时容器里推荐官方脚本在需要测试新功能的时候再单独开一个源码编译的副本。四者并不互斥完全可以按项目需求灵活切换。3. 拆解xmake install构建产物如何被装进系统3.1 install和build、config之间的顺序关系很多人以为xmake install就是把当前目录下的源代码“安装”一下这个理解错得很离谱。实际上xmake的完整工作流是配置、编译、安装三部曲xmake f或xmake config负责配置项目比如选择编译模式、指定架构、设置安装目录。xmake纯命令负责编译生成目标文件、可执行文件、库文件。xmake install负责把编译出的最终产物拷贝到目标安装目录并处理权限、文件结构、库路径等细节。所以install是在编译完成之后才进行的操作。如果你直接在一个从没构建过的干净项目里执行xmake installxmake会先自动完成配置和编译再执行安装逻辑它不会去装一堆不相关的系统依赖。这里和pip install这种“下载远程包再安装”的模型完全不是一回事也和你用npm install拉取依赖包的语义不一样。搞懂了这个顺序很多后面遇到的“灵异问题”其实都能自己解释通。3.2 install的关键参数逐个解释xmake install最常用的参数是--installdir用来指定安装根目录。如果不指定默认的行为是往系统目录里装Linux和macOS上通常是/usr/localWindows上一般是用户程序目录或者当前用户AppData下的特定路径。不过具体默认值会受xmake版本和系统环境的影响所以你要是想把东西装到固定位置最好还是显式写清楚。xmake install --installdir/opt/myapp这个命令会构建当前工程然后把产物安装到/opt/myapp目录下。xmake会根据你target的set_kind类型自动决定文件放哪binary类型放/opt/myapp/binshared类型放/opt/myapp/libheader文件放/opt/myapp/include。这种布局和Linux系统FHS标准是一致的省心。如果你只想安装某一个特定的target而不是整个工程可以用--target参数xmake install --targetdemo比如项目里同时有多个可执行文件和库文件但你只想把其中某个命令行工具装到系统里那就直接指定名字其他不相关的target不会被碰。还有一个值得留意的参数是安装模式。如果你的工程在debug模式下编译那xmake install默认安装的就是debug版本这往往不是你真正要扔到系统里的东西。正式发布前一般要先构建release版本xmake f -m release xmake install通过xmake f -m release把配置切成release再重新构建安装得到的就是优化过的发布版产物。3.3 实操演示安装一个小工具到指定目录我拿一个真实例子走一遍完整流程。假设你写了个命令行小工具叫fop源码结构如下src/ main.c xmake.luaxmake.lua定义如下target(fop) set_kind(binary) add_files(src/*.c)然后你执行xmake f --installdir/usr/local xmake xmake install第一次执行xmake f --installdir/usr/local把安装目录预设好接着xmake完成编译最后xmake install会把fop这个可执行文件放到/usr/local/bin/fop。你直接在终端里输fop就能运行。这里有个细节xmake install在安装前会检查目标文件是不是已经存在如果存在会询问你是否覆盖这在交互式终端里会卡住。如果你在CI脚本里执行xmake install建议加一个参数跳过询问xmake install -y-y参数在自动化环境里几乎是必须的否则流水线会一直等在那里直到超时。如果你的项目里还构建了动态库和头文件比如target(foo) set_kind(shared) add_files(src/foo.c) add_headers(src/*.h)那xmake install执行完系统的/usr/local/include下会多出头文件/usr/local/lib下会多出libfoo.so或libfoo.dll。链接时可以通过-lfoo找到它这个行为很接近Linux下用make install安装开源库的手感。3.4 进阶利用install完成打包发布如果只是自己用xmake install装到本地就够了。但如果你要发布一个开源库、工具或商业软件给别人用直接把文件塞进别人的系统目录显然不合适。这种场景需要用打包方式。xmake内置了xmake package它会把构建产物和指定的文件打包成可再发行的压缩包常见格式包括zip、tar.gz、甚至deb、rpm等系统包具体取决于你的版本和配置。实际使用中我会在xmake.lua里加一些配置把包管理器需要的元信息填进去然后统一用xmake package生成发布包。发布包的内部结构和xmake install安装后的布局完全一致这样你在本地测试时用xmake install验证对外发布时用xmake package两边的行为是统一的踩坑成本最低。这一点我强烈建议做库的开发者不要跳过很多人在本地xmake install没问题发出去却被人反馈头文件路径不对、动态库找不到大概率就是在安装布局上没有提前用xmake install --installdir模拟过用户的安装环境。4. 卸得干净xmake uninstall与残留清理4.1 xmake uninstall的正确打开方式有安装就有卸载xmake uninstall就是xmake install的反向操作。它会找出之前通过xmake install安装到系统目录里的文件把它们从对应位置删掉。使用方式很简单和install一脉相承xmake uninstall默认卸载当前工程安装的全部目标。如果只想卸载某个特定的targetxmake uninstall --targetdemo卸载的时候需要注意一个关键点xmake会记录安装文件清单它依赖之前xmake install留下的记录来精确清理文件。所以如果你手动删除过安装目录、移动过项目的.xmake缓存目录或者换过--installdir那卸载时可能匹配不上历史记录导致部分文件清不掉。这种情况我只能推荐一个土办法把安装目录整个删掉或者对照xmake install -v的输出手动清理残留。4.2 卸载xmake本体包管理器、update --uninstall、手动清理前面讲的xmake uninstall只是卸载某个项目的构建产物它不会动xmake工具本身。那么如果你要彻底不用xmake了怎么把本体清干净这里有三种路径第一种如果你当初是用包管理器装的xmake那卸载非常干净。比如brew uninstall xmake、apt remove xmake、winget uninstall xmake包管理器会自动把安装在系统目录里的xmake相关文件删掉。这是我推荐包管理器安装的最重要原因真正的一键清洁。第二种如果你是用官方脚本装的xmake自己提供了反安装功能。执行xmake update --uninstall这个命令会尝试把安装在用户目录下的xmake本体文件全部移除。它会检查当前正在运行的xmake进程如果终端里还开着xmake相关会话可能会提示你先关闭。实测下来大部分情况下是能清干净的。第三种是纯手动清理适用于脚本卸载失败或者装得太乱的场景。你需要检查三个位置用户目录下的~/.xmake文件夹这是xmake的配置、插件、缓存大本营。PATH里指向xmake可执行文件的路径比如/usr/local/bin/xmake或~/.xmake/bin。shell配置文件里的xmake路径注入行比如.bashrc或.zshrc里的export PATH$HOME/.xmake/bin:$PATH这种。这三处清完基本就没有残留了。4.3 环境变量、配置文件与项目缓存有时候你并不是要卸载xmake只是运行环境出了莫名其妙的问题那大概率是残留配置在捣乱。Widnows上我遇到过和你onedrive无法登录无法卸载无法安装类似的场景程序本身没坏但配置文件、缓存、路径引用互相打架导致装哪个版本都报错。xmake也有类似的情况。xmake在用户目录下有一个~/.xmake目录里面保存了全局配置、插件缓存、最近访问的项目列表、编译器缓存等。如果你升级xmake之后出现行为异常先别急着卸载重装试试把这个目录里的缓存子目录清理一下或者直接改名备份整个~/.xmake让xmake重新生成一份。很多时候问题就解决了。对于单个项目xmake会在项目根目录生成一个.xmake隐藏目录里面是当前项目的编译配置缓存。你切换编译器或者改了系统环境后重新构建报错常见原因就是这个缓存没有刷新。这时候执行xmake f -c把配置缓存清掉再重新配置或者干脆把项目里的.xmake文件夹删掉从头配置一次。这一点和“MySQL完全卸载重装”之后的清爽感是同一个道理很多问题不是软件坏了而是旧的缓存文件还在干扰新逻辑。5. 安装卸载高频问题排查速查5.1 command not foundPATH没有生效装完xmake之后敲命令终端提示xmake: command not found这应该是遇到最多的问题。原因几乎都是PATH没有包含xmake的可执行文件路径。Linux和macOS上官方脚本会写.bashrc或.zshrc但如果你当前终端是安装前打开的环境变量还没刷新需要手动执行source ~/.bashrc或者干脆新开一个终端窗口。Windows上则要检查当前PowerShell会话是否加载了新PATH或者你是否需要重启终端、甚至重启编辑器。更隐蔽的情况是多个版本混装导致命令指向了错误路径。比如你用包管理器装过旧版又用官方脚本装了新版两个可执行文件同时存在PATH里顺序靠前的那个盖住了另一个。这个时候用which xmakeLinux/macOS或Get-Command xmakeWindows查一下实际命中路径再把不用的版本清掉就好。5.2 权限不足与sudo的坑在Linux或macOS上执行xmake install往系统目录安装时很可能碰到Permission denied。原因很简单你没有权限往/usr/local/bin、/usr/local/lib这些系统目录里写文件。新手第一反应是加sudosudo xmake install这招能用但我不建议你养成这种习惯。一来sudo安装会把文件的属主变成root后续你没用sudo跑程序时可能遇到读写权限问题二来如果你在CI流水线里用sudo装构建产物会给整个构建过程引入安全隐患。更好的做法是用--installdir指定用户有权限的目录xmake install --installdir$HOME/.local然后把$HOME/.local/bin加到PATH里效果和装到系统目录几乎一致还能避免一堆权限烦恼。5.3 网络慢、镜像源、超时xmake相关的下载主要有两类第一类是安装xmake本体时从官网拉二进制第二类是构建项目时通过xmake require拉取第三方依赖包。两类如果网络环境不佳都会卡在下载阶段。我在国内某些网络环境下用官方脚本安装xmake经常卡到怀疑人生这和你用wsl --install太慢、npm install报错、pip install连不上源是一类问题。xmake本身支持配置镜像源和代理推荐在下载依赖包时换成国内可访问的镜像仓库具体地址在官方文档里有更新网上也有不少开发者整理过可用源。遇到超时不要反复重试先看看当前的源地址是什么再决定换不换。这里多说一句无论你是用xmake还是其他工具所有install类操作出问题时优先怀疑网络和镜像源别急着重装系统。5.4 Windows环境下脚本执行策略与杀毒软件干扰Windows上的坑和Linux完全不是一个画风。官方PowerShell一键安装脚本要求当前会话允许执行远程脚本如果你在执行时看到类似“禁止运行脚本”的报错多半是PowerShell执行策略限制。我在写自动化脚本时习惯用Set-ExecutionPolicy -Scope CurrentUser RemoteSigned把当前用户的执行策略放宽到允许本地脚本和合法签名的远程脚本然后再跑官方安装命令。需要注意的是这个操作会改变系统安全级别你需要在信任官方脚本来源的前提下操作。另外Windows Defender和其他杀毒软件偶尔会把新下载的xmake二进制视为可疑文件毕竟它来自网络且会修改PATH。如果你安装完成后提示“找不到文件”先去隔离区看看是不是被杀软误处理了。遇到过几个“程序安装和卸载疑难解答器”都解决不了的问题最后发现就是杀毒软件在中间捣乱。5.5 “没有规则可制作目标install”是怎么来的用惯了make的人第一次接触xmake时脑子里还带着Makefile的惯性以前编译安装都是make make install于是到了xmake项目里也去找install这个目标。如果你在Makefile项目里敲make install提示“没有规则可制作目标install”那是这个项目的Makefile里压根没写install规则。这个错误和xmake没有任何关系反而是理解xmake“install是内置命令”这个概念的最好对照。xmake并不依赖Makefile它本身就是一套完整的构建描述系统。xmake install是xmake自己的内部命令不需要你的项目里额外定义什么目标。你只要在xmake.lua里写清楚target的信息install命令能自动推断该装什么、装哪里。习惯了这种思维你自然不会再被“没有规则可制作目标install”这种报错困扰。6. 一些值得养成的安装卸载习惯最后分享几个这些年用xmake攒下来的习惯。第一正式项目和CI流水线里安装目录永远显式指定别依赖默认值。默认值在不同xmake版本、不同系统之间可能变化显式写出来才能保证行为一致。第二卸载之前先回顾一下自己当初是怎么装的。包管理器装的用包管理器卸脚本装的用xmake update --uninstall卸对应的清理路径完全不同硬混着用反而会留下残留。第三遇到诡异问题清理缓存永远是第一试错方案别急着重装。xmake在安装卸载这块的设计其实已经比CMake、Makefile时代的体验好很多了至少它提供了uninstall这个反操作入口而很多老工具装完了就只能靠人肉清理。把这套流程理顺日常开发里你会少很多头疼的时候。
