如果你搜到这个标题大概率已经在用或准备评估AWTK这套跨平台GUI框架。AWTK全称Toolkit AnyWhere是一套用C语言实现的开源GUI引擎日常主要出现在工业控制、智能硬件、车载仪表这些领域但从开发效率来说最舒服的起步方式反而是在Windows上先把环境装好、把示例跑起来。这篇文章我就把Windows开发环境的完整安装过程拆开讲清楚需要装哪些软件、每一步为什么要装、首次编译怎么跑通第一个Demo以及我在实际配置中遇到过的各种坑。我假设你目前的系统是Windows 10或Windows 11也默认你有一定的命令行操作基础。整个流程走完大概需要半小时到一小时视网速和下载速度而定。如果你之前完全没有接触过AWTK这套环境搭好之后你可以直接在PC上做界面开发、跑交互逻辑后续再考虑往嵌入式平台移植这也是官方推荐的开发路径。1. 先理顺思路AWTK Windows开发环境里都有哪些组件1.1 AWTK到底是什么为什么它的环境这么“杂”AWTK最核心的价值是“一套UI代码多平台运行”。它提供了完整的控件库、字体渲染、图片解码、动画系统、事件循环还支持多语言切换和主题定制。你只需要写上层界面逻辑底层的绘制和系统交互由框架帮你适配。正因为要跨平台它的工程结构天生就比那些只跑单片机的GUI方案复杂一点环境自然也不是“装一个IDE点一下运行”那么简单。在Windows上搭开发环境本质上是凑齐一整套工具链拉代码要Git编译要C/C编译器构建要SCons窗口显示可能要用SDL2如果你还想可视化拖控件那就再加一个AWTK Designer。这些组件各管一摊装的时候顺序有讲究但单个都不复杂。1.2 为什么优先在Windows上模拟运行而不是直接在开发板上调很多人一开始想的是“反正最终跑在嵌入式设备上干脆直接在板子上开发”。但实际做过一两个项目你就会发现在开发板上迭代UI的效率低得让人抓狂编译要交叉工具链烧写要连接调试器看效果要接屏幕出了问题还没办法直接在PC上打断点。AWTK恰好支持宿主模式也就是说在Windows上编译出来的程序可以生成一个普通窗口程序用鼠标模拟触摸直接预览UI效果。这种开发模式的好处非常明显。改一行代码、重新编译、看效果整个过程都在本机完成几分钟就能迭代好几个版本。等界面和交互逻辑基本稳定了再切换到目标平台的交叉编译这时候大部分问题都集中在平台适配层而不是UI逻辑本身。所以我个人的观点是不管你的最终目标是什么第一步都值得在Windows上把环境跑通。1.3 工具链怎么选MinGW还是MSVCWindows下的C/C编译器选择直接决定了你后面顺利还是折腾。我实际试过两条路一条是MinGW-w64加SCons另一条是Visual Studio的MSVC工具链加SCons最终长期留下来的是MinGW-w64。为什么推荐MinGW核心原因是AWTK的构建脚本和文档大量围绕GCC系工具链来写你用MinGW遇到问题的时候网上搜到的解决方案基本能直接抄。MSVC当然也能编译但它对“命令行的各种习惯”和GCC差异很大一旦报错很多提示信息你还要先去查MSVC的规则绕一圈回来问题可能还没解决。另外你如果打算之后接触Linux或者各种嵌入式交叉编译环境GCC系的命令习惯是通用的提前熟悉没坏处。这里给一个简单的选型参考我的推荐是普通开发者直接选MinGW。工具链优点缺点适合人群MinGW-w64 SCons命令和GCC一致、跨平台复用性好、社区资料多某些调试玩法不如MSVC顺手大多数普通开发者MSVC SConsWindows原生、集成开发体验好命令行习惯与Linux差异大习惯Visual Studio的工程师另外我也看到有人用WSL里装Linux工具链来编译AWTK这方法可行但图形程序在WSL里显示窗口要额外配置初学阶段没必要主动增加复杂度。本机Windows加MinGW是综合成本最低的路径。1.4 环境搭建的整体流程概览先给自己一个整体地图后面操作就不会乱。整个安装流程可以分成这几个阶段安装Git for Windows负责拉取AWTK源码和后续更新。安装Python并安装SCons负责执行构建脚本。安装MinGW-w64提供GCC编译器和相关工具。克隆AWTK和示例仓库执行首次编译运行Demo验证环境。可选安装AWTK Designer做可视化界面设计。编写你自己的最小工程验证整个开发链路能闭环。前四步是必须的第五第六步属于开发阶段的事但也建议提前了解。2. 环境准备一次性安装好Git、Python、SCons和编译器2.1 安装Git for Windows配置基础身份信息Git在这里面的角色是源码管理工具但装它不只是为了用GitHub。AWTK的版本更新比较频繁你需要用git命令拉取最新代码、切换分支、对比改动这些操作都离不开Git。安装Git for Windows过程基本是下一步下一步需要注意的地方就一个在“Adjusting your PATH environment”这一步选择“Git from the command line and also from 3rd-party software”。这样你打开CMD或PowerShell就能直接用git命令不用额外配置环境变量。装完后打开新的终端先顺手配置用户名和邮箱git config --global user.name yourname git config --global user.email youexample.com这步看起来和AWTK无关但后面一旦你要提交修改或者尝试官方分支没有身份信息会多出很多提示。2.2 安装Python和SCons构建系统的核心AWTK默认的构建工具不是CMake也不是Makefile而是SCons。SCons是一个用Python实现的软件构建工具它的配置文件写得比Makefile直观跨平台能力也更好。所以必须先装Python再用pip装SCons。Python安装包从官网下载最新的64位版本即可。安装的时候务必要勾选“Add python.exe to PATH”不勾的话后面你打开终端输入python会提示找不到命令。安装完成后重新开一个终端窗口确认一下环境python --version pip --version看到版本号输出就说明Python环境正常。接下来安装SConspip install scons安装完再验证scons --version如果你之前电脑上装过Anaconda或者其他Python发行版这里要特别注意当前终端实际使用的是哪一个Python。我之前就遇到过pip安装到了A环境但终端默认的scons来自B环境结果折腾了很久。最简单的处理方式是把系统Python的路径排在PATH最前面或者在终端里用python -m SCons的形式调用。2.3 安装MinGW-w64准备GCC编译工具链MinGW-w64是Windows平台上的GCC编译器这是真正干活的部分。AWTK的C源码要靠它编译成可执行文件。下载MinGW-w64时建议选择x86_64架构的版本具体的发行包名称不同可能略有差异安装时记得勾选“add to PATH”或者安装后手动把bin目录加进系统PATH。装完同样用终端验证gcc --version g --version两条命令都能输出版本号就说明编译工具正常。这里有一个很容易犯的错有些精简版MinGW只带了gcc不带g但AWTK的一些组件或者第三方库在Windows上会用C编译所以尽量选完整的发行版。另外如果你机器上还装了MSYS2、草莓Perl或者其他带GCC的软件要注意PATH里编译器别混用不同版本的GCC混在一起scons经常分不清该用哪一个就会报一些奇怪的错。2.4 SDL2要不要提前装什么时候装AWTK在Windows上跑窗口模式时底层默认会通过SDL2来做窗口创建、输入事件和图形渲染。那么问题来了装SDK的时候要不要把SDL2也提前装好我的建议是先不用急等第一次scons编译看它缺什么再补什么。AWTK的构建系统对可选依赖的处理比较灵活有些场景下SDL2头文件缺失并不会阻止编译只是运行的时候找不到dll。你先尝试默认编译如果编译过程报“找不到SDL.h”这类错误再去下载SDL2的Windows开发包把解压后的include和lib路径指给它。如果你不想折腾也可以直接按官方README文档中的Windows章节把列出的依赖都安装齐全。我的经验是少装一点依赖反而能避免不必要的版本冲突尤其是SDL2的版本和编译器位数不匹配的时候排查起来很烦。2.5 编辑器选择VSCode足够胜任AWTK官方没有强制指定IDEVisual Studio、VSCode、Clion都行。我自己的习惯是VSCode加C/C扩展加Python扩展足够应付绝大多数场景。VSCode的好处是轻量、打开快、终端集成好编译命令直接在终端里敲看到报错还能点击跳转到文件对应行。如果你本来就习惯Visual Studio用VS也没问题只是构建命令记得在“开发者命令提示符”里执行原理是一样的。到了这一步环境依赖已经准备齐了。下面进入真正让人兴奋的部分拉源码、编译、看Demo跑起来。3. 实操走起拉取源码、编译并运行第一个演示程序3.1 克隆awtk和awtk-examples两个仓库打开终端进入你打算存放工程的目录。我个人习惯建一个干净的工作目录比如说C:\work然后把所有和AWTK相关的内容都放在里面。执行下面的命令git clone https://github.com/zlgopen/awtk.git git clone https://github.com/zlgopen/awtk-examples.git第一个仓库是AWTK的核心引擎里面包含了src源码、demos示例、tools工具脚本第二个仓库是官方整理的各种场景示例适合拿来参考学习。克隆完成后简单看一下目录结构你会发现在awtk根目录下有一个SConstruct文件这个就是SCons的构建入口。这里我强烈建议工程路径一定要是纯英文。第一次搭环境时如果遇到特别诡异的编译错误先怀疑路径问题。Windows下的中文目录名对很多基于Python的工具链不友好特别是某些编码处理不完善的第三方库会直接让编译失败。3.2 首次编译执行scons命令等待编译完成把终端切换到awtk目录cd awtk scons如果你是第一次编译这个过程会持续几分钟因为要把整个引擎和所有Demo都编一遍。期间终端会刷出一大堆编译日志看到“Compiling ...”开头的行属于正常现象不用担心。编译成功的标志是日志末尾出现类似这样的输出scons: done building targets.看到这一行就说明已经生成可执行文件了。产物默认放在build/bin目录下Windows下文件名带.exe后缀。你可以在文件管理器里打开这个目录看看能看到很多Demo程序和AWTK自带的工具。如果编译中途报错先不要慌。绝大多数情况是你前面某个环境变量没配好最常见的三种提示scons不是内部或外部命令说明scons没进PATH检查Python的Scripts目录。提示找不到gcc或g说明MinGW没进PATH。提示找不到某个头文件则可能是依赖缺失后面我再细说排查思路。3.3 运行第一个Demo确认开发环境完全打通编译完成后直接运行一个最简单的Demobuild\bin\demo1.exe如果一切正常你会看到屏幕上弹出一个AWTK窗口里面有按钮、进度条、文本控件还可以用鼠标点击交互。第一次看到这个窗口从自己手底下编译出来基本就代表你的Windows开发环境完整打通了。有一个高频问题双击或者命令行运行exe时弹窗提示“找不到SDL2.dll”。这是因为你的系统里还没装SDL2运行时。解决办法也简单把SDL2的dll复制到build\bin目录里或者把SDL2的bin目录加入PATH再重新运行就正常了。这个dll文件在前面编译阶段不一定需要但运行时基本绕不开。还有一个表现是窗口闪一下就没了这种情况十有八九也是运行时依赖缺失。你可以先打开CMD在命令行里运行exe通常会在终端里打印出具体的错误信息比双击黑屏有用得多。3.4 安装AWTK Designer拖拽生成界面如果你只是想快速体验AWTK走到上一步其实就够了。但要做真正项目开发我建议再装一个AWTK Designer这是AWTK官方提供的可视化UI设计工具用起来类似Qt Designer。从官方渠道下载安装包装好后打开新建工程选择应用类型和屏幕分辨率然后在画布上拖控件、调属性、设置文本和图片完成后可以导出工程。导出的工程结构是标准的AWTK应用工程你可以在导出项目里看到UI文件、资源文件和代码骨架用scons命令就能直接编译。我的个人工作流通常是先在Designer里把界面布局搭好导到工程里然后在代码里写按钮点击、列表更新、页面切换这些逻辑。这样界面和逻辑分离后面改样式也不会影响到业务代码。3.5 如何从Demo过渡到自己的最小工程环境跑通后很多人会迫不及待地想写自己的界面。这时候不建议从零开始手写工程结构最好复制一个最简的示例在这个基础上改。最简单的做法是进入awtk-examples目录找一个比较简单的项目复制一份到自己的工作目录里然后改三个地方工程名、启动窗口、业务逻辑。AWTK应用的入口逻辑大体上是一个固定模板。核心流程是初始化引擎、加载UI资源、进入主事件循环。代码骨架大概是这样一个感觉#include awtk.h static ret_t on_btn_click(void *ctx, event_t *e) { widget_t *win (widget_t *)ctx; widget_t *label widget_lookup(win, label, TRUE); widget_set_text_utf8(label, you clicked me); return RET_OK; } ret_t app_init(void) { widget_t *win window_open(main); widget_child_on(win, btn, EVT_CLICK, on_btn_click, win); return RET_OK; } ret_t app_exit(void) { return RET_OK; }这里我只写了一个逻辑示意具体API在不同版本里可能有差异但整体结构是相通的。第一次做小工程时先跑通一个只有按钮和文本的窗口再慢慢加控件和样式比直接抄一个大项目要稳得多。3.6 常用构建命令汇总开发过程中你会反复用到scons这里把几个常用的构建命令整理出来# 默认编译当前平台 scons # 清理编译产物 scons -c # 只编译特定目标 scons demos # 指定线程数编译加快速度 scons -j 8 # 启用调试信息 scons WITH_DEBUG1这些命令在不同的项目里大同小异具体参数可以看工程里的SConstruct配置。偶尔需要全量重编的时候先scons -c再scons比手动删除build目录更彻底。4. 避坑实录编译和运行阶段最常见的故障排查4.1 编译报错先看这三处解决八成问题编译期报错最让人头疼但有规律可循。我自己的排查顺序永远是固定的第一看PATH。凡是提示“command not found”“not recognized as an internal or external command”这类信息基本就是scons或gcc没被找到。回到终端输入where scons和where gcc看你能不能看到实际的路径。第二看当前目录。编译AWTK时终端必须在awtk根目录下也就是能看到SConstruct文件的那一层。很多人直接在源码子目录里执行scons报错自然没完没了。第三看路径和权限。工程目录带中文的、放在C盘Program Files下的、被杀毒软件锁定的都会出各种诡异的编译错误。建议放在纯英文、无空格的目录下比如C:\work\awtk。4.2 运行闪退和黑屏的问题大概率出在SDL2身上编译通过但运行不起来问题多数集中在运行时依赖上。最常见的错误就是找不到SDL2.dll这个前面说过把dll放到exe旁边就能解决。如果dll都在但窗口黑屏那通常是SDL2创建渲染窗口失败和显卡驱动、系统缩放比例有关。可以先换一个Demo试试如果所有Demo都黑屏更新显卡驱动然后在exe属性里调整高DPI缩放设置。还有一个低级但容易犯的错误直接双击运行exe出问题后看不到任何输出。正确做法是在CMD或PowerShell里运行这样窗口没弹出来时终端会打印出错信息定位问题快得多。4.3 中文用户名导致的各种奇怪问题如果你的Windows用户名是中文比如C:\Users\张三那么在编译AWTK时可能会遇到一些莫名其妙的错误。这是因为某些工具链在处理非ASCII路径时编码不一致出现乱码进而导致文件找不到或解析失败。这个问题最省心的解法是新建一个英文管理员账户在英文账户下编译运行。如果不想换账户可以试试把环境变量TEMP和TMP指到纯英文路径比如C:\tmp这样能缓解一部分问题。但我见过太多人在这上面浪费时间最后还是新建账户才彻底解决。如果你遇到的就是这类问题别犹豫直接换账户最快。4.4 杀毒软件把编译产物当病毒处理编译出的exe被Windows Defender或者第三方杀毒软件拦截甚至直接删除这种现象在GCC工具链下并不少见。原因不是程序有毒而是MinGW生成的exe特征和一些常见病毒很像杀毒软件容易误报。处理办法是把你的工程目录加入杀毒软件的白名单包括build目录。千万不要因为嫌麻烦直接关掉杀毒万一真有问题就得不偿失了。把源码和编译产物放进白名单以后这个问题基本就不会再出现。4.5 从开发环境走向目标平台时的几条经验Windows环境跑通只是第一步最终你大概率还是要做平台移植。AWTK的优势恰好在这里它的平台抽象层做得比较清晰你在Windows上写的界面逻辑换成Linux、RTOS甚至裸机环境时大部分代码不用改只需要适配平台层。我的建议是从最开始写业务代码时就要注意分层。不要在一个文件里把界面绘制、数据处理、平台调用全混在一起。把UI逻辑和业务逻辑拆开后续移植时你会感谢当时的自己。另外一个很实用的习惯是经常把代码同步到Git里不要因为“只是本地改动”就跳过提交。开发环境搭建过程里反复重装、清理都很正常有版本管理兜底心里踏实很多。我在实际项目里体会最深的一点是环境安装这件事第一次总是被各种细节绊住但只要完整走过一遍后面再做其他平台的环境配置速度会快很多。AWTK的构建思路、资源打包流程、代码结构都是统一的Windows这道坎迈过去以后你的开发效率才能真正起来。
AWTK Windows开发环境搭建教程：从零到运行第一个Demo
如果你搜到这个标题大概率已经在用或准备评估AWTK这套跨平台GUI框架。AWTK全称Toolkit AnyWhere是一套用C语言实现的开源GUI引擎日常主要出现在工业控制、智能硬件、车载仪表这些领域但从开发效率来说最舒服的起步方式反而是在Windows上先把环境装好、把示例跑起来。这篇文章我就把Windows开发环境的完整安装过程拆开讲清楚需要装哪些软件、每一步为什么要装、首次编译怎么跑通第一个Demo以及我在实际配置中遇到过的各种坑。我假设你目前的系统是Windows 10或Windows 11也默认你有一定的命令行操作基础。整个流程走完大概需要半小时到一小时视网速和下载速度而定。如果你之前完全没有接触过AWTK这套环境搭好之后你可以直接在PC上做界面开发、跑交互逻辑后续再考虑往嵌入式平台移植这也是官方推荐的开发路径。1. 先理顺思路AWTK Windows开发环境里都有哪些组件1.1 AWTK到底是什么为什么它的环境这么“杂”AWTK最核心的价值是“一套UI代码多平台运行”。它提供了完整的控件库、字体渲染、图片解码、动画系统、事件循环还支持多语言切换和主题定制。你只需要写上层界面逻辑底层的绘制和系统交互由框架帮你适配。正因为要跨平台它的工程结构天生就比那些只跑单片机的GUI方案复杂一点环境自然也不是“装一个IDE点一下运行”那么简单。在Windows上搭开发环境本质上是凑齐一整套工具链拉代码要Git编译要C/C编译器构建要SCons窗口显示可能要用SDL2如果你还想可视化拖控件那就再加一个AWTK Designer。这些组件各管一摊装的时候顺序有讲究但单个都不复杂。1.2 为什么优先在Windows上模拟运行而不是直接在开发板上调很多人一开始想的是“反正最终跑在嵌入式设备上干脆直接在板子上开发”。但实际做过一两个项目你就会发现在开发板上迭代UI的效率低得让人抓狂编译要交叉工具链烧写要连接调试器看效果要接屏幕出了问题还没办法直接在PC上打断点。AWTK恰好支持宿主模式也就是说在Windows上编译出来的程序可以生成一个普通窗口程序用鼠标模拟触摸直接预览UI效果。这种开发模式的好处非常明显。改一行代码、重新编译、看效果整个过程都在本机完成几分钟就能迭代好几个版本。等界面和交互逻辑基本稳定了再切换到目标平台的交叉编译这时候大部分问题都集中在平台适配层而不是UI逻辑本身。所以我个人的观点是不管你的最终目标是什么第一步都值得在Windows上把环境跑通。1.3 工具链怎么选MinGW还是MSVCWindows下的C/C编译器选择直接决定了你后面顺利还是折腾。我实际试过两条路一条是MinGW-w64加SCons另一条是Visual Studio的MSVC工具链加SCons最终长期留下来的是MinGW-w64。为什么推荐MinGW核心原因是AWTK的构建脚本和文档大量围绕GCC系工具链来写你用MinGW遇到问题的时候网上搜到的解决方案基本能直接抄。MSVC当然也能编译但它对“命令行的各种习惯”和GCC差异很大一旦报错很多提示信息你还要先去查MSVC的规则绕一圈回来问题可能还没解决。另外你如果打算之后接触Linux或者各种嵌入式交叉编译环境GCC系的命令习惯是通用的提前熟悉没坏处。这里给一个简单的选型参考我的推荐是普通开发者直接选MinGW。工具链优点缺点适合人群MinGW-w64 SCons命令和GCC一致、跨平台复用性好、社区资料多某些调试玩法不如MSVC顺手大多数普通开发者MSVC SConsWindows原生、集成开发体验好命令行习惯与Linux差异大习惯Visual Studio的工程师另外我也看到有人用WSL里装Linux工具链来编译AWTK这方法可行但图形程序在WSL里显示窗口要额外配置初学阶段没必要主动增加复杂度。本机Windows加MinGW是综合成本最低的路径。1.4 环境搭建的整体流程概览先给自己一个整体地图后面操作就不会乱。整个安装流程可以分成这几个阶段安装Git for Windows负责拉取AWTK源码和后续更新。安装Python并安装SCons负责执行构建脚本。安装MinGW-w64提供GCC编译器和相关工具。克隆AWTK和示例仓库执行首次编译运行Demo验证环境。可选安装AWTK Designer做可视化界面设计。编写你自己的最小工程验证整个开发链路能闭环。前四步是必须的第五第六步属于开发阶段的事但也建议提前了解。2. 环境准备一次性安装好Git、Python、SCons和编译器2.1 安装Git for Windows配置基础身份信息Git在这里面的角色是源码管理工具但装它不只是为了用GitHub。AWTK的版本更新比较频繁你需要用git命令拉取最新代码、切换分支、对比改动这些操作都离不开Git。安装Git for Windows过程基本是下一步下一步需要注意的地方就一个在“Adjusting your PATH environment”这一步选择“Git from the command line and also from 3rd-party software”。这样你打开CMD或PowerShell就能直接用git命令不用额外配置环境变量。装完后打开新的终端先顺手配置用户名和邮箱git config --global user.name yourname git config --global user.email youexample.com这步看起来和AWTK无关但后面一旦你要提交修改或者尝试官方分支没有身份信息会多出很多提示。2.2 安装Python和SCons构建系统的核心AWTK默认的构建工具不是CMake也不是Makefile而是SCons。SCons是一个用Python实现的软件构建工具它的配置文件写得比Makefile直观跨平台能力也更好。所以必须先装Python再用pip装SCons。Python安装包从官网下载最新的64位版本即可。安装的时候务必要勾选“Add python.exe to PATH”不勾的话后面你打开终端输入python会提示找不到命令。安装完成后重新开一个终端窗口确认一下环境python --version pip --version看到版本号输出就说明Python环境正常。接下来安装SConspip install scons安装完再验证scons --version如果你之前电脑上装过Anaconda或者其他Python发行版这里要特别注意当前终端实际使用的是哪一个Python。我之前就遇到过pip安装到了A环境但终端默认的scons来自B环境结果折腾了很久。最简单的处理方式是把系统Python的路径排在PATH最前面或者在终端里用python -m SCons的形式调用。2.3 安装MinGW-w64准备GCC编译工具链MinGW-w64是Windows平台上的GCC编译器这是真正干活的部分。AWTK的C源码要靠它编译成可执行文件。下载MinGW-w64时建议选择x86_64架构的版本具体的发行包名称不同可能略有差异安装时记得勾选“add to PATH”或者安装后手动把bin目录加进系统PATH。装完同样用终端验证gcc --version g --version两条命令都能输出版本号就说明编译工具正常。这里有一个很容易犯的错有些精简版MinGW只带了gcc不带g但AWTK的一些组件或者第三方库在Windows上会用C编译所以尽量选完整的发行版。另外如果你机器上还装了MSYS2、草莓Perl或者其他带GCC的软件要注意PATH里编译器别混用不同版本的GCC混在一起scons经常分不清该用哪一个就会报一些奇怪的错。2.4 SDL2要不要提前装什么时候装AWTK在Windows上跑窗口模式时底层默认会通过SDL2来做窗口创建、输入事件和图形渲染。那么问题来了装SDK的时候要不要把SDL2也提前装好我的建议是先不用急等第一次scons编译看它缺什么再补什么。AWTK的构建系统对可选依赖的处理比较灵活有些场景下SDL2头文件缺失并不会阻止编译只是运行的时候找不到dll。你先尝试默认编译如果编译过程报“找不到SDL.h”这类错误再去下载SDL2的Windows开发包把解压后的include和lib路径指给它。如果你不想折腾也可以直接按官方README文档中的Windows章节把列出的依赖都安装齐全。我的经验是少装一点依赖反而能避免不必要的版本冲突尤其是SDL2的版本和编译器位数不匹配的时候排查起来很烦。2.5 编辑器选择VSCode足够胜任AWTK官方没有强制指定IDEVisual Studio、VSCode、Clion都行。我自己的习惯是VSCode加C/C扩展加Python扩展足够应付绝大多数场景。VSCode的好处是轻量、打开快、终端集成好编译命令直接在终端里敲看到报错还能点击跳转到文件对应行。如果你本来就习惯Visual Studio用VS也没问题只是构建命令记得在“开发者命令提示符”里执行原理是一样的。到了这一步环境依赖已经准备齐了。下面进入真正让人兴奋的部分拉源码、编译、看Demo跑起来。3. 实操走起拉取源码、编译并运行第一个演示程序3.1 克隆awtk和awtk-examples两个仓库打开终端进入你打算存放工程的目录。我个人习惯建一个干净的工作目录比如说C:\work然后把所有和AWTK相关的内容都放在里面。执行下面的命令git clone https://github.com/zlgopen/awtk.git git clone https://github.com/zlgopen/awtk-examples.git第一个仓库是AWTK的核心引擎里面包含了src源码、demos示例、tools工具脚本第二个仓库是官方整理的各种场景示例适合拿来参考学习。克隆完成后简单看一下目录结构你会发现在awtk根目录下有一个SConstruct文件这个就是SCons的构建入口。这里我强烈建议工程路径一定要是纯英文。第一次搭环境时如果遇到特别诡异的编译错误先怀疑路径问题。Windows下的中文目录名对很多基于Python的工具链不友好特别是某些编码处理不完善的第三方库会直接让编译失败。3.2 首次编译执行scons命令等待编译完成把终端切换到awtk目录cd awtk scons如果你是第一次编译这个过程会持续几分钟因为要把整个引擎和所有Demo都编一遍。期间终端会刷出一大堆编译日志看到“Compiling ...”开头的行属于正常现象不用担心。编译成功的标志是日志末尾出现类似这样的输出scons: done building targets.看到这一行就说明已经生成可执行文件了。产物默认放在build/bin目录下Windows下文件名带.exe后缀。你可以在文件管理器里打开这个目录看看能看到很多Demo程序和AWTK自带的工具。如果编译中途报错先不要慌。绝大多数情况是你前面某个环境变量没配好最常见的三种提示scons不是内部或外部命令说明scons没进PATH检查Python的Scripts目录。提示找不到gcc或g说明MinGW没进PATH。提示找不到某个头文件则可能是依赖缺失后面我再细说排查思路。3.3 运行第一个Demo确认开发环境完全打通编译完成后直接运行一个最简单的Demobuild\bin\demo1.exe如果一切正常你会看到屏幕上弹出一个AWTK窗口里面有按钮、进度条、文本控件还可以用鼠标点击交互。第一次看到这个窗口从自己手底下编译出来基本就代表你的Windows开发环境完整打通了。有一个高频问题双击或者命令行运行exe时弹窗提示“找不到SDL2.dll”。这是因为你的系统里还没装SDL2运行时。解决办法也简单把SDL2的dll复制到build\bin目录里或者把SDL2的bin目录加入PATH再重新运行就正常了。这个dll文件在前面编译阶段不一定需要但运行时基本绕不开。还有一个表现是窗口闪一下就没了这种情况十有八九也是运行时依赖缺失。你可以先打开CMD在命令行里运行exe通常会在终端里打印出具体的错误信息比双击黑屏有用得多。3.4 安装AWTK Designer拖拽生成界面如果你只是想快速体验AWTK走到上一步其实就够了。但要做真正项目开发我建议再装一个AWTK Designer这是AWTK官方提供的可视化UI设计工具用起来类似Qt Designer。从官方渠道下载安装包装好后打开新建工程选择应用类型和屏幕分辨率然后在画布上拖控件、调属性、设置文本和图片完成后可以导出工程。导出的工程结构是标准的AWTK应用工程你可以在导出项目里看到UI文件、资源文件和代码骨架用scons命令就能直接编译。我的个人工作流通常是先在Designer里把界面布局搭好导到工程里然后在代码里写按钮点击、列表更新、页面切换这些逻辑。这样界面和逻辑分离后面改样式也不会影响到业务代码。3.5 如何从Demo过渡到自己的最小工程环境跑通后很多人会迫不及待地想写自己的界面。这时候不建议从零开始手写工程结构最好复制一个最简的示例在这个基础上改。最简单的做法是进入awtk-examples目录找一个比较简单的项目复制一份到自己的工作目录里然后改三个地方工程名、启动窗口、业务逻辑。AWTK应用的入口逻辑大体上是一个固定模板。核心流程是初始化引擎、加载UI资源、进入主事件循环。代码骨架大概是这样一个感觉#include awtk.h static ret_t on_btn_click(void *ctx, event_t *e) { widget_t *win (widget_t *)ctx; widget_t *label widget_lookup(win, label, TRUE); widget_set_text_utf8(label, you clicked me); return RET_OK; } ret_t app_init(void) { widget_t *win window_open(main); widget_child_on(win, btn, EVT_CLICK, on_btn_click, win); return RET_OK; } ret_t app_exit(void) { return RET_OK; }这里我只写了一个逻辑示意具体API在不同版本里可能有差异但整体结构是相通的。第一次做小工程时先跑通一个只有按钮和文本的窗口再慢慢加控件和样式比直接抄一个大项目要稳得多。3.6 常用构建命令汇总开发过程中你会反复用到scons这里把几个常用的构建命令整理出来# 默认编译当前平台 scons # 清理编译产物 scons -c # 只编译特定目标 scons demos # 指定线程数编译加快速度 scons -j 8 # 启用调试信息 scons WITH_DEBUG1这些命令在不同的项目里大同小异具体参数可以看工程里的SConstruct配置。偶尔需要全量重编的时候先scons -c再scons比手动删除build目录更彻底。4. 避坑实录编译和运行阶段最常见的故障排查4.1 编译报错先看这三处解决八成问题编译期报错最让人头疼但有规律可循。我自己的排查顺序永远是固定的第一看PATH。凡是提示“command not found”“not recognized as an internal or external command”这类信息基本就是scons或gcc没被找到。回到终端输入where scons和where gcc看你能不能看到实际的路径。第二看当前目录。编译AWTK时终端必须在awtk根目录下也就是能看到SConstruct文件的那一层。很多人直接在源码子目录里执行scons报错自然没完没了。第三看路径和权限。工程目录带中文的、放在C盘Program Files下的、被杀毒软件锁定的都会出各种诡异的编译错误。建议放在纯英文、无空格的目录下比如C:\work\awtk。4.2 运行闪退和黑屏的问题大概率出在SDL2身上编译通过但运行不起来问题多数集中在运行时依赖上。最常见的错误就是找不到SDL2.dll这个前面说过把dll放到exe旁边就能解决。如果dll都在但窗口黑屏那通常是SDL2创建渲染窗口失败和显卡驱动、系统缩放比例有关。可以先换一个Demo试试如果所有Demo都黑屏更新显卡驱动然后在exe属性里调整高DPI缩放设置。还有一个低级但容易犯的错误直接双击运行exe出问题后看不到任何输出。正确做法是在CMD或PowerShell里运行这样窗口没弹出来时终端会打印出错信息定位问题快得多。4.3 中文用户名导致的各种奇怪问题如果你的Windows用户名是中文比如C:\Users\张三那么在编译AWTK时可能会遇到一些莫名其妙的错误。这是因为某些工具链在处理非ASCII路径时编码不一致出现乱码进而导致文件找不到或解析失败。这个问题最省心的解法是新建一个英文管理员账户在英文账户下编译运行。如果不想换账户可以试试把环境变量TEMP和TMP指到纯英文路径比如C:\tmp这样能缓解一部分问题。但我见过太多人在这上面浪费时间最后还是新建账户才彻底解决。如果你遇到的就是这类问题别犹豫直接换账户最快。4.4 杀毒软件把编译产物当病毒处理编译出的exe被Windows Defender或者第三方杀毒软件拦截甚至直接删除这种现象在GCC工具链下并不少见。原因不是程序有毒而是MinGW生成的exe特征和一些常见病毒很像杀毒软件容易误报。处理办法是把你的工程目录加入杀毒软件的白名单包括build目录。千万不要因为嫌麻烦直接关掉杀毒万一真有问题就得不偿失了。把源码和编译产物放进白名单以后这个问题基本就不会再出现。4.5 从开发环境走向目标平台时的几条经验Windows环境跑通只是第一步最终你大概率还是要做平台移植。AWTK的优势恰好在这里它的平台抽象层做得比较清晰你在Windows上写的界面逻辑换成Linux、RTOS甚至裸机环境时大部分代码不用改只需要适配平台层。我的建议是从最开始写业务代码时就要注意分层。不要在一个文件里把界面绘制、数据处理、平台调用全混在一起。把UI逻辑和业务逻辑拆开后续移植时你会感谢当时的自己。另外一个很实用的习惯是经常把代码同步到Git里不要因为“只是本地改动”就跳过提交。开发环境搭建过程里反复重装、清理都很正常有版本管理兜底心里踏实很多。我在实际项目里体会最深的一点是环境安装这件事第一次总是被各种细节绊住但只要完整走过一遍后面再做其他平台的环境配置速度会快很多。AWTK的构建思路、资源打包流程、代码结构都是统一的Windows这道坎迈过去以后你的开发效率才能真正起来。
