AB
AiBoss
Tutorials

Tbox

Tutorials

用 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,需要显示下载进度时再按接口签名补上。
  • 平台与架构组合、版本号、发布产物命名等易变信息,以官网当前信息为准。