
Tbox
用 Tbox 编译静态库并在 C 程序中完成初始化与文件下载
面向 C 开发者的 Tbox 实操教程:从 make r 编译安装、按平台与架构找到头文件和调试/发布库,到设置 CFLAGS 与 LDFLAGS 区分调试模式,再到编写 tb_init 初始化、打印日志、用 stream 与 transfer 完成同步和异步下载的完整示例。
Tbox 是一个用 C 语言编写的跨平台基础库,把内存管理、字符串、容器、流、网络传输、协程等常用能力打包成一套统一的接口。它解决的是「每开一个新 C 项目都要重新造一遍基础轮子」的问题:你只需要链接一个库、包含一个 tbox.h,就能直接使用流式下载、日志输出、内存池等设施。这篇教程面向已经会写 C、准备把 Tbox 引入自己工程的开发者,讲清楚三件事:怎么编译出可用的库文件、怎么在编译和链接阶段正确区分调试与发布模式、以及怎么写出一个能跑通初始化、日志、同步下载与异步批量下载的最小程序。想先了解这个库的整体定位,可以看站内的 Tbox 条目。
需要先说明版本差异:不同大版本的编译与使用方式并不相同,较早的 1.4.x 及以下版本走的是 make r 生成预编译库、再手工配置头文件与库路径的路线;1.5.x 及以上版本的使用方式已经变化,应当以对应版本的编译说明为准。下面全部内容围绕「编译出预编译库并手工链接」这条路线展开,这也是最容易在链接阶段踩坑的一条路线。
准备工作
环境与工具链
- 一个可用的 C 编译器。素材中的示例覆盖两类:Linux 下的 gcc 工具链,以及 MSVC(Windows 下的微软编译器)。
- 如果使用 MinGW 在 Windows 上编译,链接阶段还需要额外链接对应的
libgcc.a,这一点在后面的链接参数里会单独说明。 - 一个终端或命令行环境,用来执行
make与编译命令。 - 素材没有给出具体的版本号要求、依赖库清单或磁盘占用,这些信息请以项目官网当前说明为准。
先确认你的版本分支
动手之前先确认自己拿到的是哪个版本分支,因为两条路线的操作完全不同:
- 1.5.x 及以上:使用方式请参考该版本对应的「编译和使用」说明,不要照搬下面 1.4.x 的目录结构与链接参数。
- 1.4.x 及以下:按本文后续步骤执行,用
make r编译安装,然后手工指定头文件目录与库文件目录。
版本号、支持的平台与架构组合会随发布变化,具体以官网当前信息为准。
操作步骤
第一步:编译并安装,生成库文件
在 1.4.x 及以下版本中,执行带 r 目标的 make 即可完成编译安装:
make r
执行完成后,会在源码树下的 pre 目录中按「平台 / 架构」两级目录生成头文件与库文件。默认的输出位置是:
- 头文件目录:
./tbox/pre/inc/$(PLAT)/$(ARCH)/ - 库文件目录:
./tbox/pre/lib/$(PLAT)/$(ARCH)/
其中 $(PLAT) 是平台标识,$(ARCH) 是架构标识。如果你希望把产物装到别处,可以在编译时通过 PREFIX 指定安装前缀:
make f PREFIX=/xxx
此时输出位置变为:
- 头文件目录:
/xxx/inc/$(PLAT)/$(ARCH)/ - 库文件目录:
/xxx/lib/$(PLAT)/$(ARCH)/
注意 PREFIX 只改变根目录,后面的 inc、lib 以及平台、架构层级仍然保留,写编译参数时要按这个完整路径来。
第二步:按平台与架构找到对应的文件
生成的文件名带有调试与发布的区分,命名规则是「调试库带 d 后缀、发布库带 r 后缀」。以两个常见组合为例。
Linux x64:
- 头文件目录:
./tbox/pre/inc/linux/x64/tbox - 调试库文件:
./tbox/pre/lib/linux/x64/libtboxd.a - 发布库文件:
./tbox/pre/lib/linux/x64/libtboxr.a
MSVC x86:
- 头文件目录:
./tbox/pre/inc/msvc/x86/tbox - 调试库文件:
./tbox/pre/lib/msvc/x86/tboxd.lib - 发布库文件:
./tbox/pre/lib/msvc/x86/tboxr.lib
可以看到 Linux 下是 .a 静态库、文件名带 lib 前缀;MSVC 下是 .lib 导入/静态库、文件名不带前缀。头文件目录的末级是 tbox,也就是说你在代码里写 #include "tbox/tbox.h" 时,包含路径应当指向 tbox 的上一级目录。
第三步:设置编译选项,区分调试与发布
Tbox 用宏来区分两种模式,编译时必须显式设置,否则调试相关的接口行为会与预期不符:
- 调试模式:在
CFLAGS中加入-D__tb_debug__。 - 发布模式:不定义该宏。
这个宏直接决定了后面示例里 tb_trace_d 这类调试输出是否生效——调试模式下会打印,发布模式下不会。
第四步:设置链接选项
链接参数必须与上一步选择的模式保持一致:调试模式链接 d 库,发布模式链接 r 库。混用会导致符号找不到或行为异常。
Linux,调试模式:
-L./tbox/pre/lib/linux/x64/ -ltboxd
Linux,发布模式:
-L./tbox/pre/lib/linux/x64/ -ltboxr
MSVC,调试模式:
-LIBPATH:.\tbox\pre\lib/msvc\x86 tboxd.lib
MSVC,发布模式:
-LIBPATH:.\tbox\pre\lib/msvc\x86 tboxr.lib
如果使用 MinGW 编译,除了上面的库之外,还需要额外链接对应的 libgcc.a,否则可能报出与运行时支持相关的未定义符号。
第五步:在代码中初始化与退出
包含头文件只需要一行,tbox.h 会级联包含所有子模块的头文件:
#include "tbox/tbox.h"
程序入口处调用 tb_init 完成初始化,退出前调用 tb_exit 释放资源。初始化函数有三个参数:
priv:平台相关的私有数据。目前只有 Android 需要传入JNIEnv*,其他平台传tb_null即可。data:内存池使用的数据地址。默认直接使用系统内存,所以传tb_null。size:内存池的大小。使用系统内存时传0。
如果你希望整个库的内存都从一块外部连续内存里分配,可以把 data 和 size 换成自己申请的那块内存及其长度,例如 tb_init(tb_null, malloc(10 * 1024 * 1024), 10 * 1024 * 1024)。这种做法适合需要精确控制内存占用的场景,但要注意这块内存的生命周期必须覆盖整个库的使用期。
第六步:使用日志输出
初始化之后就可以直接调用日志接口,素材中给出了三个常用级别:
tb_trace_i:普通信息输出。tb_trace_d:调试信息,仅在定义了__tb_debug__的调试模式下显示。tb_trace_e:错误信息输出。
这三个接口的用法一致,都是直接传入格式化字符串。
第七步:用流做单文件下载
流(stream)是 Tbox 里处理输入输出的统一抽象。从 URL 初始化一个流,再把流的数据转存到本地文件,就完成了一次下载:
tb_stream_ref_t stream = tb_stream_init_from_url("");
if (stream)
{
tb_transfer_done_stream_to_url(stream, "/home/file/index.html", 0, tb_null, tb_null);
tb_stream_exit(stream);
}
这里要注意两点:tb_stream_init_from_url 可能返回空值,所以必须判空后再使用;用完流之后要调用 tb_stream_exit 释放。转存函数的后几个参数用于设置进度回调,示例中不需要进度反馈,因此传 tb_null。
第八步:用传输接口做阻塞式下载
如果不需要自己管理流对象,可以直接调用传输接口,一步完成「从 URL 到本地文件」:
tb_transfer_done_url_to_url("", "/home/file/index.html", 0, tb_null, tb_null);
这是阻塞模式,函数返回时下载已经结束。同样,末尾两个 tb_null 是进度回调的位置。
第九步:用传输池做并发下载
需要同时下载多个文件时,把任务提交给传输池即可,不必自己开线程:
tb_transfer_pool_done(tb_transfer_pool(), "", "/home/file/index0.html", 0, 0, tb_null, tb_null);
tb_transfer_pool_done(tb_transfer_pool(), "", "/home/file/index2.html", 0, 0, tb_null, tb_null);
tb_transfer_pool_done(tb_transfer_pool(), "", "/home/file/index3.html", 0, 0, tb_null, tb_null);
tb_transfer_pool_done(tb_transfer_pool(), "", "/home/file/index4.html", 0, 0, tb_null, tb_null);
tb_transfer_pool() 返回全局传输池实例,直接作为第一个参数传入。相比单文件接口,这里多了一个参数位,用于控制任务相关的选项,示例中传 0。多个任务提交后由池统一调度执行。
一个完整示例
下面把前面的步骤串成一个可以直接编译运行的最小程序。它完成五件事:初始化库、打印三种级别的日志、用流下载一个文件、用阻塞接口下载一个文件、提交四个并发下载任务,最后退出。
// 只需要包含 tbox.h 就行了,它会级联包含所有头文件
#include "tbox/tbox.h"
int main(int argc, char** argv)
{
/* 初始化 tbox 库
*
* @param priv 平台所需要的私有数据,目前针对 android,需要传入 JNIEnv* env,
* 其他平台默认传 tb_null
* @param data 设置内存池需要的数据地址,默认直接使用系统内存,所以传 tb_null 就行了
* @param size 设置内存池需要的数据大小
*/
if (!tb_init(tb_null, tb_null, 0)) return 0;
// 使用外部连续内存作为整个库的内存使用
// tb_init(tb_null, malloc(10 * 1024 * 1024), 10 * 1024 * 1024);
// 打印信息
tb_trace_i("hello tbox");
// 打印调试信息,仅仅在调试模式下显示
tb_trace_d("hello tbox");
// 打印错误信息
tb_trace_e("hello tbox");
// 初始化流
tb_stream_ref_t stream = tb_stream_init_from_url("");
if (stream)
{
// 保存流数据到文件
tb_transfer_done_stream_to_url(stream, "/home/file/index.html", 0, tb_null, tb_null);
// 退出流
tb_stream_exit(stream);
}
// 阻塞模式:下载 http 文件,后面几个参数用于设置进度回调,这里不使用
tb_transfer_done_url_to_url("", "/home/file/index.html", 0, tb_null, tb_null);
// 异步模式: 添加四个 http 下载任务,并执行,后面几个参数用于设置进度回调,这里不使用
tb_transfer_pool_done(tb_transfer_pool(), "", "/home/file/index0.html", 0, 0, tb_null, tb_null);
tb_transfer_pool_done(tb_transfer_pool(), "", "/home/file/index2.html", 0, 0, tb_null, tb_null);
tb_transfer_pool_done(tb_transfer_pool(), "", "/home/file/index3.html", 0, 0, tb_null, tb_null);
tb_transfer_pool_done(tb_transfer_pool(), "", "/home/file/index4.html", 0, 0, tb_null, tb_null);
// ...
// 退出 tbox 库
tb_exit();
return 0;
}
把上面的代码保存为 main.c,在 Linux x64 上以调试模式编译链接,命令形如:
gcc main.c -I./tbox/pre/inc/linux/x64 -D__tb_debug__ -L./tbox/pre/lib/linux/x64/ -ltboxd -o demo
发布模式则去掉 -D__tb_debug__,并把 -ltboxd 换成 -ltboxr。运行 ./demo 后,应当能看到三条日志输出,其中 tb_trace_d 那条只在调试模式下出现。
示例中的 URL 参数是空字符串,实际使用时替换成真实的下载地址;本地保存路径也要换成你机器上存在且可写的目录,示例里的 /home/file/ 只是占位。
注意事项
- 版本分支不要混用。 1.5.x 及以上版本的使用方式与本文描述的预编译库路线不同,照搬目录结构和链接参数会找不到文件。先确认版本,再决定按哪套说明操作。
- 调试库与发布库必须与宏定义配套。 定义了
__tb_debug__就链接d库,没定义就链接r库。两者交叉搭配是链接阶段最常见的错误来源。 - MinGW 需要额外链接
libgcc.a。 只加 Tbox 自身的库在 MinGW 下可能链接不完整。 - 流对象必须判空并释放。
tb_stream_init_from_url失败时返回空值,直接使用会出问题;成功获取的流用完要调用tb_stream_exit。 - 初始化失败要提前返回。
tb_init返回假值时说明初始化没有成功,此时不应继续调用其他接口。 - 自定义内存池要注意生命周期。 把外部内存交给
tb_init之后,这块内存在tb_exit之前都不能释放或挪作他用。 - Android 平台需要传
JNIEnv*。 这是priv参数唯一需要非空值的场景,其他平台传tb_null。 - 进度回调参数可以留空。 示例中所有回调位置都传
tb_null,需要显示下载进度时再按接口签名补上。 - 平台与架构组合、版本号、发布产物命名等易变信息,以官网当前信息为准。