Truetime 2.0在MATLAB中的安装与MEX编译配置指南

简介：Truetime 2.0 中文使用说明文档面向在 MATLAB 环境下学习网络化运动控制与资源调度仿真的师生、工程人员，帮助其理解工具箱的安装配置、模块组成和仿真实验流程。压缩包内仅有 1 个 docx 文件，约 402KB，内容集中、查阅方便；正文涵盖工具箱路径与环境配置、Kernel 等模块说明、仿真实验环境，以及 MATLAB 路径设置、mex 编译器和运动控制中的最大误差优先调度、优先级反馈控制等知识点。文中还归纳了 Truetime 快速模拟、灵活配置、多仿真环境等特点，便于读者建立模块关系与配置思路，在搭建实验、排查环境问题和验证调度方案时作为参考。目前已有 1593 人学习，适合具备 MATLAB 基础并希望系统入门 Truetime 2.0 的读者。

1. Truetime 2.0 装在 MATLAB 里：先看清路径和编译器这两道坎

上周接到一台机器，MATLAB 一开就报Undefined function 'truetime'，可 toolbox 目录里 truetime-2.0 明明躺得好好的。追到最后是两个小动作没做：init_truetime.m没复制进 local，路径改完也没真正保存。truetime MATLAB 运动控制这套组合，卡人的地方从来不是调度算法本身，而是“装进去”和“编译过”这两步——解压位置、setpath、环境变量、GCC 版本、make_truetime，任何一环错位，报错都长得差不多，全是看不懂的那一句。下面按我实际装过一遍的顺序走：先列版本与系统前提，再落到每处路径和编译参数，然后是出错怎么救，最后给能自查的验证手段。适合刚拿到 truetime-2.0 beta 1、想在 R2017b 上把它跑起来的人。

2. 装前把环境列清：MATLAB 版本、位数与编译器三件套

2.1 版本对照：R2017b 是验证过的组合，换新版先留退路

truetime-2.0 beta 1 这个年代的工具箱，本质是两坨东西：一坨是.m文件写的模块封装，另一坨是kernel目录下要靠 mex 编译成 MEX 文件的 C/C++ 源码。前者跟 MATLAB 版本基本无关，后者强依赖编译器接口。原文作者在 R2017b 上跑通了，这条组合是有据可查的，我一般也照这个基准走，不去赌。

版本差异主要落在两处。一是mex -setup的交互形式，老版本是纯 C 编译器选择，较新的 MATLAB（R2018a 之后）把 C 和 C++ 分开了，选完 C 还得再确认 C++，漏一步后面 make 就找不到编译器配置。二是编译器版本门槛，MATLAB 每个版本都有一张“支持的 GCC 列表”，TDM-GCC 5.1.0 在 R2017b 上是被认的，装到更新的 MATLAB 上，可能因为内核接口或 C++ 标准的原因编译不过。

提示：如果你的 MATLAB 比 R2017b 新不少，别在原环境上直接改。装第二个 MATLAB 或者先做一次 toolbox 目录备份，是装这类老工具箱最便宜的保险。

2.2 系统位数与权限：64 位 MATLAB 只能配 64 位编译器

这是最容易忽略、又最容易被误判成“工具箱坏了”的一条。原文环境是 win7 64 位，装的也是tdm64-gcc-5.1.0-2.exe，注意那个64——它和 MATLAB 必须是同一个位数。32 位 MATLAB 配 64 位 GCC，编译阶段不会立刻报错，而是在链接那一步抛出莫名其妙的符号找不到，你会以为是源码问题，其实是位数问题。

查位数不用猜，MATLAB 命令窗口里一条就够：

% 查看本机 MATLAB 的位数与版本，决定装 32 位还是 64 位 GCC computer('arch') % 返回 win64 或 win32 version % 返回版本号字符串，例如 9.3.0.713579

computer('arch')返回win64就装 64 位 GCC，返回win32就装 32 位，没有中间地带。version拿到的号段对应 R20xxx，记下来，后面挑编译器版本时要用。

权限方面，往MATLAB安装目录\toolbox里复制文件、往toolbox\local里写startup.m，这两个位置默认都在 Program Files 下，普通用户没有写权限。常见做法是安装 MATLAB 时就用管理员账户，或者复制文件那一步临时以管理员身份启动资源管理器。血泪经验是：复制“看起来成功了”，其实被系统重定向到了虚拟存储，MATLAB 根本看不到。

2.3 目录规划：toolbox 下的落点与备份

放置位置原文说得很明确，解压后整个truetime-2.0文件夹复制进 MATLAB 安装目录的toolbox下。我一般会把路径写成这种形式，方便后面所有步骤统一引用：

# 假设 MATLAB 装在 D 盘，统一用变量记，避免后面手打路径出错 MATLAB_ROOT="D:/Program Files/MATLAB/R2017b" TT_ROOT="$MATLAB_ROOT/toolbox/truetime-2.0" echo "$TT_ROOT/kernel" # 后面 setpath 要加的路径 echo "$MATLAB_ROOT/toolbox/local" # init_truetime.m 的落点

把这两个路径先 echo 出来确认存在，再往下走。路径里带空格是常态，Program Files就是，所以在任何脚本、环境变量、mex配置里都不要漏引号，这是后面一堆“找不到文件”报错的源头。

备份做在动手之前：把toolbox/local整个目录复制一份改名成local_bak。这个目录里放着startup.m、matlabrc.m、pathdef.m这些启动期关键文件，改坏了 MATLAB 直接起不来，而它恰恰是最没存在感、最容易被随手覆盖的目录。

3. 落盘与认路：解压到 toolbox、setpath 与 init_truetime 的四步配置

3.1 解压与放置：先看清 truetime-2.0 的目录结构

下载回来的压缩包解压之后，别急着整包往里拖，先花一分钟看结构。truetime-2.0 下面通常有三类东西：kernel目录（核心源码和init_truetime.m）、若干示例或模块目录、以及顶层的一些说明文件。kernel是这次安装真正要打交道的地方，其余目录属于“放着备用”。

复制动作本身很简单，关键是“复制到哪”和“复制完核对什么”：

# 1) 复制到 toolbox 下 cp -r ./truetime-2.0 "$MATLAB_ROOT/toolbox/" # 2) 核对关键文件是否到位，缺一个后面就会卡住 ls "$TT_ROOT/kernel/init_truetime.m" ls "$TT_ROOT/kernel/"*.m | head -20

第一条命令完成后，$TT_ROOT应该能列出内容。第二条是在确认init_truetime.m确实存在——这个文件在第 3.4 步要被单独复制走，是整套配置里最容易漏的一环。如果解压出来的目录名带版本号后缀，比如truetime-2.0-beta1，要么改名成truetime-2.0，要么后面所有路径都跟着改，两种都行，但不能一半用新名一半用旧名。

注意：不要图省事直接把kernel里的.m文件全拷到 MATLAB 根目录下。工具箱靠目录结构区分模块，摊平之后同名函数会互相覆盖，而且是静默覆盖，出问题时极难定位。

3.2 setpath：Kernel 路径怎么加，四个文件要不要全包含

setpath 的目标只有一个：让 MATLAB 在任意当前目录下都能找到 kernel 里的函数。操作入口是主页选项卡里的“设置路径”，或者命令窗口直接敲pathtool。

加什么，原文给了取舍：最好把 kernel 下那 4 个与 truetime-2.0 相关的路径都包含进去，也可以只加 kernel 这一层，出错再补。我按后一种起手，因为路径少的时候排查清晰：

% 添加 kernel 路径并立即生效（不做 savepath，先验证本次会话） addpath('D:\Program Files\MATLAB\R2017b\toolbox\truetime-2.0\kernel'); % 确认路径确实进去了 path % 确认关键函数可见，返回路径就说明找得到 which init_truetime

addpath只对当前会话生效，关掉 MATLAB 就没了，这正是我们想要的：先验证，再决定要不要持久化。which init_truetime返回一个完整路径，说明路径加对了；返回not found，说明路径层级加错，常见是把kernel的上一层加进去了。

验证通过之后，在设置路径对话框里点“保存”，或者命令行savepath。保存这个动作背后是把路径写进pathdef.m，如果这个文件在 Program Files 下且当前没有写权限，会弹一个保存失败但很多人顺手点掉的提示——这就是第 5 章第一个坑的由来。

3.3 启动脚本：startup.m 与 matlabrc.m 到底改哪个

原文给了两条路：改toolbox\local\startupsav.m，或者在startup.m里改，作者说效果一样。这句话是对的，两者都是 MATLAB 启动时执行的用户级脚本，区别在于触发顺序和用途。matlabrc.m是系统级启动脚本，MATLAB 每次启动必跑；startup.m是用户级，跑在matlabrc.m之后，专门留给用户放自己的初始化内容。我一般只碰startup.m，因为系统级那个是黑匣子，改坏了连 MATLAB 都进不去。

在startup.m里放什么，一行就够：

% startup.m —— 每次 MATLAB 启动时自动执行 % 把 truetime kernel 加入搜索路径，避免每次手动 addpath addpath('D:\Program Files\MATLAB\R2017b\toolbox\truetime-2.0\kernel'); % 如果还有额外模块目录，按同样格式继续 addpath

内容就这么多。addpath写在启动脚本里，等于把第 3.2 步的手工动作固化成习惯动作，好处是不依赖pathdef.m的写权限，坏处是路径写死，MATLAB 换安装位置就得跟着改。原文还提到把matlabrc.m打开后不做任何修改直接另存为matlab.mat放到同目录，这个动作的作用是留下一个可回退的副本，属于后悔药性质的准备，不是必需步骤，但顺手做了没坏处。

提示：startup.m里不要塞太多东西。放过多的 addpath、format、cd，一旦某行报错，后面所有行都不执行，表现出来就是“工具箱时灵时不灵”，排查成本极高。

3.4 init_truetime.m 复制到 local：一步不做，truetime 命令就找不到

这是整套配置里最不起眼、也最容易漏的一步。把kernel目录下的init_truetime.m复制到MATLAB安装目录\toolbox\local下；这个函数负责工具箱的初始化登记，只有它在 local 里，MATLAB 启动时才会把 truetime 那套东西挂上去。

% 在 MATLAB 命令窗口里做，比在资源管理器里拖更可控 src = 'D:\Program Files\MATLAB\R2017b\toolbox\truetime-2.0\kernel\init_truetime.m'; dst = 'D:\Program Files\MATLAB\R2017b\toolbox\local\init_truetime.m'; copyfile(src, dst); % 立即确认目标文件真的落盘了 exist(dst, 'file') % 返回 2 表示存在

exist(dst,'file')返回 2 才算成功，返回 0 就是没复制过去，多半是权限问题。这一步做完，第 3.2 步的路径、第 3.3 步的启动脚本、这一步的初始化文件，三者合起来构成“MATLAB 能找到 truetime”的完整条件，缺任何一环，命令窗口里敲truetime都是那句Undefined function。

4. 环境变量与 GCC：让 make_truetime 一路编译到 successful

4.1 新建系统环境变量：win7 与 win10 的入口差异

环境变量这步原文写得比较细，win7 下是“计算机右键 → 属性 → 高级 → 环境变量 → 系统变量 → 新建”。入口在 win10 上换了位置，但落点是同一个地方：系统变量，不是上面的用户变量。

变量内容指向 truetime 的 kernel 目录，或者按你手上文档给的变量名和值填——这一步的具体变量名不要自己发明，照文档抄，抄错一个字母，make_truetime编译时就是一句“找不到头文件”。

# 想在命令行里先验证变量是否生效（新开一个命令行窗口才看得到系统变量） echo %TRUETIME% # 或者用 set 过滤，看是否已经出现在系统变量列表里 set | findstr /I truetime

echo出来是空行，说明变量没生效，先别急着往下编译。两类常见原因：一是加在了用户变量区，只对当前登录用户有效，换账户或某些启动方式下读不到；二是加完没重启电脑，系统变量在已打开的进程里不会自动刷新。原文明确写了“以上操作完成，重启电脑”，这不是客套话，是必须做的动作。

注意：改环境变量之前，把原来那几行值拍照或者复制到记事本。变量名记错、值里多一个空格、路径里用了反斜杠之类的翻车，事后想恢复原样都没依据。

4.2 TDM-GCC 5.1.0 的安装与 mex -setup 的选择项

原文里最有价值的一句是“网上的编译器一直不成功，最后下载了 tdm64-gcc-5.1.0-2.exe”。这说明挑编译器版本这件事在这套工具箱上有实际门槛，随便找一个 MinGW 装上就行的想法，在这里大概率要还债。

安装 TDM-GCC 时注意三件事：装 64 位版本（对应 64 位 MATLAB）；安装路径不要带空格和中文；勾选把bin目录加入 PATH。最后这条决定了 MATLAB 能不能找到gcc。装完开一个新命令窗口验证：

# 确认 gcc 在 PATH 里，且版本是 5.1.0 gcc --version # 确认 g++ 也在，mex 编译 C++ 源码时要用 g++ --version

两条都能打印出版本号，再去 MATLAB 里跑编译器配置：

% 配置默认编译器，R2017b 的交互是列出检测到的编译器后选编号 mex -setup % 如果上一条没列出目标编译器，显式指定 C++ 再试一次 mex -setup C++

选择的时候注意：mex -setup只选 C 是不够的，truetime 的 kernel 源码里有 C++ 内容，必须把 C++ 的编译器也指定上，否则make_truetime会在编译某个.cpp时直接停住。如果列表里压根没出现 TDM-GCC，常见做法是把MINGWROOT环境变量指到 GCC 的安装根目录，再重开 MATLAB 重试——这也是系统变量，同样要重启或者至少重开 MATLAB 才认。

4.3 make_truetime 的编译输出：哪些警告可以放过

编译器配好之后，命令窗口里敲make_truetime，这是整套流程的收口动作。它会遍历 kernel 目录下的源码，逐个调 mex 编译成 MEX 文件。输出会刷很长一串，判断标准就一个：最后有没有出现successful。

% 编译工具箱，输出较长，重点看最后一行的结果 make_truetime

过程中出现警告先不用管，原文也这么讲。要区分的是警告和错误的差别：警告通常是源码里的旧式写法、未使用变量、隐式类型转换，编译产物照样生成；真正的错误会中断，并且明确写出是哪个文件、哪一行。我一般会先扫一遍输出里有没有error字样，再看结尾。如果刷屏太快没看清，把命令窗口内容导出成文本再翻。

编译成功之后，MEX 文件会落在 kernel 目录里，扩展名是.mexw64（64 位 Windows）。可以去目录里核对一眼，文件数量和源码规模大致对得上，说明确实是全量编过，而不是中途断掉却混在警告里被忽略。

5. 避坑与排查：五个让 truetime 装完打不开的坑

5.1 路径保存了，重启 MATLAB 又丢了

现象：addpath之后which init_truetime能返回路径，关掉 MATLAB 重开，再敲truetime又是未定义。

原因：路径保存写的是toolbox\local\pathdef.m，这个文件在 Program Files 下，当前账户没有写权限，保存动作静默失败。设置路径对话框会弹提示，但很多人顺手点掉。

解决：用管理员身份启动一次 MATLAB，重新addpath并savepath；更稳的做法是干脆不依赖pathdef.m，把addpath写进startup.m，每次启动自动加，绕开权限问题。

5.2 mex -setup 找不到编译器

现象：mex -setup列出“未找到支持的编译器”，或者列表里只有系统自带的那个，没有 TDM-GCC。

原因：三种可能——GCC 的bin没进 PATH；MATLAB 是在装 GCC 之前启动的，进程里没有新 PATH；位数不匹配，64 位 MATLAB 只有 32 位 GCC 可用。

解决：先在新命令行里gcc --version确认 PATH 通了，再完全退出 MATLAB 重开（不是关命令窗口，是退出进程）；位数问题用computer('arch')对一遍；还不行就把MINGWROOT指到安装根目录后重试。

5.3 位数不匹配：mex 编译到一半报链接错误

现象：make_truetime前几个文件编得挺顺，突然在某一行报一堆找不到符号、无法解析的外部符号之类的链接错误。

原因：编译器位数和 MATLAB 位数不一致。32 位 MATLAB 配 64 位 GCC 时，编译阶段能过，链接阶段才暴露，报错内容和源码完全对不上，特别容易误判成源码损坏。

解决：computer('arch')确认位数，卸掉不匹配的编译器，装对应位数的 TDM-GCC，重新mex -setup，然后清掉已经生成的中间产物再跑一次make_truetime，别在半成品上重编。

5.4 环境变量加成了用户变量

现象：自己的账户下make_truetime正常，换一个账户登录或者以管理员身份运行时，编译报找不到头文件。

原因：变量加在了“用户变量”区，只对当前登录用户生效。原文那两张图强调的“系统变量中新建”就是这个意思。

解决：把用户变量区里那几条删掉，在系统变量区重建同样的名称和值，重启电脑。删之前先确认系统变量里没有同名项，两处同名时用户变量优先级更高，会出现“改了系统变量却不生效”的假象。

5.5 matlabrc.m 改坏之后 MATLAB 起不来

现象：改完matlabrc.m保存，再启动 MATLAB 直接报错退出，或者卡在启动画面。

原因：matlabrc.m是系统级启动脚本，里面任何语法错误都会让启动流程中断。原文里“打开不做任何修改直接另存”的写法，就是为了留副本。

解决：用备份的local_bak覆盖回去；没有备份的话，从 MATLAB 安装介质里找同名文件恢复。恢复之后再启动，进命令窗口确认startup.m还在，再按第 3.3 步把addpath重新加回来。从那以后我改这个文件之前都先复制一份改名带日期，体积不大，救场的时候真管用。

6. 装完怎么验证：三条自检命令加一次最小仿真

配置跑完到“能用了”之间，还差一次确认。我习惯按顺序敲三条命令，一条比一条更接近真实使用场景，出问题也能立刻定位到是哪一层。

% 第一条：初始化函数是否可见（对应 init_truetime.m 那步） which init_truetime % 第二条：工具箱入口是否可见（对应路径与启动脚本那步） which truetime % 第三条：MEX 产物是否已生成（对应 make_truetime 那步） ls('D:\Program Files\MATLAB\R2017b\toolbox\truetime-2.0\kernel\*.mexw64')

三条依次对应第 3 章和第 4 章的三个落点。第一条not found说明init_truetime.m没进 local；第二条not found但第一条正常，说明路径没保存住或者启动脚本没生效；前两条都正常、第三条列不出文件，说明make_truetime没真正编完。这三条命中的位置各不相同，比直接看一句Undefined function有用得多。

三条都过之后，命令窗口里输入truetime，会弹出工具箱的工作窗口，到这一步才算装完。想再稳一点，跑一个最小仿真把 kernel 走一遍，而不是只打开界面就看一眼：

% 新建一个脚本，跑一次最小内核初始化，确认 MEX 与 kernel 能协同 ttInitKernel('prioFP'); % 初始化内核，指定固定优先级调度 myTask = ttCreateTask('demoTask', 1, 0.010); % 建一个 10ms 周期的示例任务 ttStartTask(myTask); % 启动任务，观察命令窗口有无异常

这三行的作用是让 kernel 真正被调用一次：ttInitKernel走的是 MEX 里的初始化逻辑，ttCreateTask验证任务对象能不能建起来，ttStartTask触发一次调度。跑完不报错，命令窗口没有奇怪的句柄错误，说明源码编译、路径、初始化三块拼上了。参数按你手上的示例改，周期和时间单位以模块说明为准，别照抄数字。

一个具体技巧：验证完成后，把toolbox\local下的startup.m、pathdef.m、init_truetime.m三个文件单独打包存一份，连同这次的 GCC 安装包放在同一个目录里。下次换机器或者重装 MATLAB，直接覆盖过去，能省掉从 setpath 到make_truetime的整轮返工。

从那以后我每次装这类老工具箱，都强制走一遍 self-check：which两条、MEX 产物一条、最小仿真一次，全部过了才动手做正经项目。跳过这一步省下的十分钟，后面往往要用一整个下午去还。希望帮到你。

本文还有配套的精品资源，点击获取