🎯 导读：库（Library）是 C++ 工程化的基石。本文用 🎭 生活比喻、📊 对比表格 和 💻 完整代码，带你彻底搞懂静态库 vs 动态库的区别，以及 Windows 下那个让无数人头疼的「导出宏」FITKAppFrameworkAPI 到底是什么。读完你就能独立搭建一个带库的跨平台项目！

🏛️ 前言：为什么要用「库」？

想象你在开一家🍔汉堡店，每个汉堡都需要「酱料」：

• ❌ 不用库：每做一个汉堡，都从头熬一锅酱 —— 重复劳动，代码爆炸
• ✅ 使用库：熬一大桶酱（库），所有汉堡直接取用 —— 复用、解耦、好维护

「库」就是把可复用的代码打包，供多个程序共享。而库又分两大门派：静态库（焊死在身上）和动态库（即插即用）。下面我们逐一拆解 👇

📑 目录

1. 静态库 (Static Library)
2. 动态库 (Dynamic Library)
3. Windows 与 Linux 的差异
4. 导出/导入宏（FITKAppFrameworkAPI）
5. qmake (.pro) 配置库
6. CMake 配置库
7. 综合实战：从零搭建带库的项目

🧱 一、静态库 (Static Library)

一句话：把库的代码「复制」进最终的 exe 里，从此合为一体。

🎭 生动比喻：把家具焊死在房子里 🏠

静态库就像装修时把🛋️沙发、🪑桌子焊死在地板上。房子（exe）搬到哪，家具就跟到哪，不依赖外部 —— 但房子也因此变得又大又重，想换张桌子就得砸地板重装。

🔍 是什么

• 🔗 编译时直接把库代码复制进可执行文件（exe）
• 🪟 Windows 后缀：.lib
• 🐧 Linux 后缀：.a（archive，归档文件）
• 📦 最终 exe 较大，但不依赖任何额外文件

✅ 优点

❌ 缺点

🔌 二、动态库 (Dynamic Library / Shared Library)

一句话：库单独存放，exe 运行时才去「找」它、加载它。

🎭 生动比喻：可插拔的家用电器 🔋

动态库就像🔌可插拔的电器：电视、冰箱单独摆放，需要时插上电源（运行时加载）即可。换电器只需拔插头（替换 dll），不用动房子；多个房间还能共用一台中央空调（多个 exe 共享一份 dll）。

🔍 是什么

• 📝 编译时只生成「引用信息」，运行时才真正加载
• 🪟 Windows 后缀：.dll ＋ 配套的 .lib（导入库）
• 🐧 Linux 后缀：.so（shared object）
• 🎈 最终 exe 很小，但必须随身携带 dll/so

🪟 Windows 动态库的特殊之处

在 Windows 上，编译一个 dll 会同时吐出两个文件：

💡 这里的 .lib 只是 dll 的「门牌号 🏷️」，告诉链接器「函数住在哪个 dll 里」，本身不是真正的代码。

所以在本项目（FastCAE-APPStructural）的场景中：

• 📁 FITK_Kernel/ 每个子目录都编译成一个 .dll
• 📁 同时在 output/bin 下生成对应的 .lib（导入库）
• 🎯 可执行文件 StructuralApp.exe 链接这些 .lib，运行时再加载对应的 .dll

✅ 优点

❌ 缺点

🏗️ 在本项目中的体现

本项目的库全部编译为动态库（SHARED / DLL），每个子项目一个 dll：

1
2
3
4
5
6

FITKCore.dll          + FITKCore.lib        (导入库)
FITKAppFramework.dll  + FITKAppFramework.lib
GUIFrame.dll          + GUIFrame.lib
FITKWidget.dll        + FITKWidget.lib
...
StructuralApp.exe                           (最终可执行文件)

🌍 三、Windows 与 Linux 的差异

🔑 最关键的区别：符号导出

这是本项目大量使用 FITKAppFrameworkAPI 这类宏的根本原因 ——

⚠️ Windows 下，dll 必须明确声明哪些类/函数要「导出」给外界，否则外部程序根本访问不到！

✅ Linux 下，.so 默认所有符号都可见，所以 Q_DECL_EXPORT 在 Linux 下通常是个空宏。

💡 一句话总结：FITKAppFrameworkAPI、GUIFRAMEAPI、GUIWIDGETAPI 等宏，本质上是为 Windows 的 __declspec(dllexport/dllimport) 服务的跨平台封装。

🏷️ 四、导出/导入宏（FITKAppFrameworkAPI 这类宏）

🎭 生动比喻：海关的「报关单」📋

把 dll 想象成一个国家🏴。里面的类和函数是「商品」，外面的程序想买（调用），必须先报关导出。FITKAppFrameworkAPI 就是贴在商品上的「报关单」：

• 📤 出口方（编译库本身）：盖「EXPORT」章 → 允许出关
• 📥 进口方（使用库的人）：盖「IMPORT」章 → 表明这是进口货

同一个宏，靠一个「开关」自动在 EXPORT / IMPORT 之间切换。

4.1 🧩 宏如何定义

本项目每创建一个动态库，就配一个 XXXAPI.h 头文件。例如：

FITKAppFrameworkAPI.h：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

#ifndef _FITKAPPFRAMEWORK_API_H_
#define _FITKAPPFRAMEWORK_API_H_

#include <QtCore/QtGlobal>

// 🔑 如果 FITKAppFramework_API 被定义（=正在编译该库本身）→ 导出
// 否则（=别人引用该库）→ 导入
#if defined(FITKAppFramework_API)
#define FITKAppFrameworkAPI Q_DECL_EXPORT
#else
#define FITKAppFrameworkAPI Q_DECL_IMPORT
#endif

#endif

其中：

• 📤 Q_DECL_EXPORT → Windows 下展开为 __declspec(dllexport)，Linux 下为空
• 📥 Q_DECL_IMPORT → Windows 下展开为 __declspec(dllimport)，Linux 下为空

4.2 🎚️ 何时定义，何时不定义

这个「开关」由构建系统控制：

4.3 🛠️ 如何在类上使用

1
2
3
4
5
6
7
8
9
10
11

// FITK_Kernel/FITKAppFramework/FITKClassA.h
#include "FITKAppFrameworkAPI.h"

class FITKAppFrameworkAPI FITKClassA : public QObject  // 👈 宏贴在 class 和类名之间
{
    Q_OBJECT
public:
    FITKClassA();
    void doSomething();
    int getValue() const;
};

这个宏告诉编译器：

• 📤 编译该库时：FITKClassA 的所有成员函数对 dll 外部可见
• 📥 使用该库时：调用其成员函数走 dll 导入（编译器生成更高效的调用代码）

4.4 📇 本项目中所有宏速查

4.5 💥 如果忘记加宏会怎样？

在 Windows 上编译 dll 时，如果类前忘了加导出宏：

1
2

// ❌ 忘写 FITKAppFrameworkAPI
class FITKClassA : public QObject { ... };

• 🟡 编译 dll 时：能编译通过，但 FITKClassA 的符号全部不导出
• 🔴 链接 exe 时：链接器爆出经典错误 👇

1
2

LNK2019: unresolved external symbol
"public: __cdecl FITKClassA::FITKClassA(void)"

😱 找不到这个类！ 这是 Windows C++ 开发最常见的坑之一，看到 LNK2019 先检查导出宏是不是漏了。

🔧 五、qmake (.pro) 中配置库

5.1 📤 创建动态库（lib 项目）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

# FITK_Kernel/FITKAppFramework/FITKAppFramework.pro

TEMPLATE  = lib               # 🎯 编译为库（dll/so）
CONFIG   += c++11
CONFIG   += qt                # 使用 Qt
TARGET    = FITKAppFramework  # 输出的库名
QT       += core widgets gui network

# ⭐ 关键：声明「正在编译该库本身」→ 触发 Q_DECL_EXPORT
DEFINES  += FITKAppFramework_API

win32 {
    # 🪟 Windows 下输出到 output/bin
    Release:DESTDIR = ../../output/bin
    Debug:DESTDIR   = ../../output/bin_d
    # 链接依赖的其他库
    Release:LIBS += -L../../output/bin   -lFITKCore -lDbgHelp
    Debug:LIBS   += -L../../output/bin_d -lFITKCore -lDbgHelp
}
unix {
    # 🐧 Linux 下的配置
    DESTDIR = ../../output/lib
    LIBS   += -L../../output/lib -lFITKCore
}

SOURCES += \
    FITKClassA.cpp \
    ...

HEADERS += \
    FITKAppFrameworkAPI.h \
    FITKClassA.h \
    ...

⭐ DEFINES += FITKAppFramework_API 就是上一节说的那个「开关」，编译该库时把宏切到导出模式。

5.2 🎯 创建可执行文件（app 项目）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

# StructuralApp/StructuralApp.pro

TEMPLATE  = app           # 🎯 编译为可执行文件
TARGET    = StructuralApp # 输出的 exe 名

win32 {
    Release:DESTDIR = ../output/bin
    Debug:DESTDIR   = ../output/bin_d
}

# ⭐ 链接其他库：告诉链接器去哪里找导入库
# -L 添加库搜索路径
# -l 指定要链接的库名（不含 lib 前缀和 .lib 后缀）
Release:LIBS += \
    -L../output/bin \
    -lFITKAppFramework \
    -lFITKCore \
    -lGUIFrame \
    -lGUIWidget

Debug:LIBS += \
    -L../output/bin_d \
    -lFITKAppFramework \
    -lFITKCore \
    -lGUIFrame \
    -lGUIWidget

SOURCES += main.cpp ...

📌 注意：app 项目这里不定义 FITKAppFramework_API，所以宏自动切到 Q_DECL_IMPORT（导入模式）。

5.3 🧰 链接第三方库

1
2
3
4
5
6
7
8
9
10
11
12

# GUIFrame/GUIFrame.pro

# 链接系统或第三方库
Release:LIBS += \
    # 链接 Tools/Win64/SARibbon 下的 SARibbonBar 库
    -L$$PWD/../Tools/Win64/SARibbon/lib/ -lSARibbonBar \
    # 链接 VTK 库
    -L$$PWD/../Tools/Win64/VTK/lib/ -lvtkCommonCore-9.0

# 添加头文件搜索路径（让 #include 能找到头文件）
INCLUDEPATH += \
    $$PWD/../Tools/Win64/SARibbon/include

5.4 📖 qmake 链接语法总结

🏭 六、CMake (CMakeLists.txt) 中配置库

6.1 📤 创建动态库

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

# FITK_Kernel/FITKAppFramework/CMakeLists.txt

# 项目名
project(FITKAppFramework VERSION 1.0.7 LANGUAGES CXX)

# ⭐ 创建动态库（SHARED = dll/so）
add_library(${PROJECT_NAME} SHARED)

# 添加源文件
target_sources(${PROJECT_NAME}
    PRIVATE
        FITKClassA.cpp
    PUBLIC
        FITKAppFrameworkAPI.h
        FITKClassA.h
)

# ⭐ 关键：定义导出宏（等同于 qmake 的 DEFINES += FITKAppFramework_API）
# PRIVATE 表示只在编译该库时有效，对外部不可见 👈 这点很重要！
target_compile_definitions(${PROJECT_NAME}
    PRIVATE
        FITKAppFramework_API
)

# 链接依赖的 Qt 库
target_link_libraries(${PROJECT_NAME}
    PUBLIC Qt5::Core Qt5::Widgets Qt5::Gui Qt5::Network
)

# 链接到项目内的其他库
target_link_libraries(${PROJECT_NAME} PUBLIC FITKCore)

# 设置输出目录
set_target_properties(${PROJECT_NAME} PROPERTIES
    RUNTIME_OUTPUT_DIRECTORY_RELEASE "${CMAKE_SOURCE_DIR}/output/bin"
    RUNTIME_OUTPUT_DIRECTORY_DEBUG   "${CMAKE_SOURCE_DIR}/output/bin_d"
)

💡 为什么导出宏要用 PRIVATE？ 因为它只在「编译这个库自己」时才该是导出模式。如果写成 PUBLIC，会传染给所有链接它的 exe/库，导致它们也以为自己在「导出」，宏就失效了！

6.2 🎯 创建可执行文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# StructuralApp/CMakeLists.txt

project(StructuralApp VERSION 1.0.0 LANGUAGES CXX)

# ⭐ 创建可执行文件
add_executable(${PROJECT_NAME})

target_sources(${PROJECT_NAME}
    PRIVATE
        main.cpp
)

# 链接 Qt 和第三方库
target_link_libraries(${PROJECT_NAME}
    PUBLIC
        Qt5::Core Qt5::Widgets Qt5::Gui
        VTK::VTK
)

# 链接项目内的各个库
target_link_libraries(${PROJECT_NAME}
    PUBLIC
        FITKAppFramework
        FITKCore
        GUIFrame
        GUIWidget
)

6.3 🌉 本项目的跨平台链接宏

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# 本项目通用的链接宏，自动处理 Win/Linux 差异
macro(link_fitk_library target_name lib_name)
    if(WIN32)
        # 🪟 Windows 下链接 .lib（导入库）
        target_link_libraries(${target_name}
            PUBLIC
                debug     "${OUTPUT_DIR_DEBUG}/${lib_name}.lib"
                optimized "${OUTPUT_DIR_RELEASE}/${lib_name}.lib"
        )
    elseif(UNIX)
        # 🐧 Linux 下链接 .so
        target_link_libraries(${target_name}
            PUBLIC
                debug     "${OUTPUT_DIR_DEBUG}/lib${lib_name}.so"
                optimized "${OUTPUT_DIR_RELEASE}/lib${lib_name}.so"
        )
    endif()
    # ⭐ 确保编译 target_name 之前，lib_name 已经编译完成
    if(TARGET ${lib_name})
        add_dependencies(${target_name} ${lib_name})
    endif()
endmacro()

6.4 📖 CMake 链接语法总结

🚀 七、综合实战：从零搭建一个带库的项目

🎬 场景

我们要做一个数学工具箱：

• 📦 一个动态库 MathTools（提供 add() 和 multiply()）
• 🎯 一个可执行文件 MyApp（调用 MathTools）

📂 目录结构

1
2
3
4
5
6
7
8
9
10

MyProject/
├── CMakeLists.txt          # 顶层 CMake
├── MyApp.pro               # 顶层 qmake（可选）
├── MathTools/
│   ├── CMakeLists.txt
│   ├── MathToolsAPI.h      # 🏷️ 导出宏定义
│   └── MathTools.h         # 库的接口
└── MyApp/
    ├── CMakeLists.txt
    └── main.cpp

7.1 1️⃣ 定义导出宏

1
2
3
4
5
6
7
8
9
10
11
12
13

// MathTools/MathToolsAPI.h
#ifndef MATHTOOLS_API_H_
#define MATHTOOLS_API_H_

#include <QtCore/QtGlobal>

#if defined(MathTools_API)
#define MATHTOOLSAPI Q_DECL_EXPORT
#else
#define MATHTOOLSAPI Q_DECL_IMPORT
#endif

#endif

7.2 2️⃣ 实现库

1
2
3
4
5
6
7
8
9

// MathTools/MathTools.h
#include "MathToolsAPI.h"

class MATHTOOLSAPI MathTools   // 👈 别忘了贴导出宏！
{
public:
    static int add(int a, int b);
    static int multiply(int a, int b);
};

1
2
3
4
5

// MathTools/MathTools.cpp
#include "MathTools.h"

int MathTools::add(int a, int b)      { return a + b; }
int MathTools::multiply(int a, int b) { return a * b; }

7.3a 🏭 用 CMake 构建

1
2
3
4
5
6
7
8
9

# 顶层 CMakeLists.txt
cmake_minimum_required(VERSION 3.16)
project(MyProject VERSION 1.0.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_AUTOMOC ON)

add_subdirectory(MathTools)
add_subdirectory(MyApp)

1
2
3
4
5
6
7
8
9
10
11
12
13

# MathTools/CMakeLists.txt
project(MathTools)

add_library(${PROJECT_NAME} SHARED)

target_sources(${PROJECT_NAME}
    PRIVATE MathTools.cpp
    PUBLIC  MathToolsAPI.h MathTools.h
)

target_compile_definitions(${PROJECT_NAME}
    PRIVATE MathTools_API   # ⭐ 编译该库时定义 → 触发 Q_DECL_EXPORT
)

1
2
3
4
5
6
7
8
9
10
11

# MyApp/CMakeLists.txt
project(MyApp)

add_executable(${PROJECT_NAME})
target_sources(${PROJECT_NAME} PRIVATE main.cpp)

# ⭐ 链接到 MathTools 库
target_link_libraries(${PROJECT_NAME} PRIVATE MathTools)

# 自动添加头文件搜索路径（因为 MathTools 的 .h 设为 PUBLIC）
target_include_directories(${PROJECT_NAME} PRIVATE ../MathTools)

7.3b 🔧 用 qmake 构建

1
2
3
4
5
6
7
8
9
10
11
12
13

# MathTools/MathTools.pro
TEMPLATE  = lib
CONFIG   += c++17
TARGET    = MathTools
QT       += core

DEFINES  += MathTools_API      # ⭐ 编译该库时定义此宏

SOURCES  += MathTools.cpp
HEADERS  += MathToolsAPI.h MathTools.h

win32:DESTDIR = ../output
unix:DESTDIR  = ../output

1
2
3
4
5
6
7
8
9
10
11
12
13

# MyApp/MyApp.pro
TEMPLATE  = app
TARGET    = MyApp
QT       += core

win32:DESTDIR = ../output
unix:DESTDIR  = ../output

INCLUDEPATH += ../MathTools    # 让 #include 能找到 MathTools.h

LIBS += -L../output -lMathTools

SOURCES += main.cpp

7.4 4️⃣ 使用库

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// MyApp/main.cpp
#include <QDebug>
#include "MathTools.h"  // 来自 MathTools 库

int main(int argc, char *argv[])
{
    int sum     = MathTools::add(3, 4);
    int product = MathTools::multiply(3, 4);

    qDebug() << "3 + 4 =" << sum;      // 7
    qDebug() << "3 * 4 =" << product;  // 12

    return 0;
}

7.5 🪟 Windows 下运行注意事项

编译成功后，output/ 目录下会有：

1
2
3
4

output/
├── MathTools.dll       # 🟢 动态库（运行时必需）
├── MathTools.lib       # 🔵 导入库（编译时已用，运行时不需要）
└── MyApp.exe           # 🎯 可执行文件

运行 MyApp.exe 时，若提示「找不到 MathTools.dll」，说明 exe 找不到 dll。

解决方案（三选一）：

1. ✅ 把 dll 放到 exe 同目录（最常见、最推荐）
2. 🛣️ 把 dll 所在目录加入 PATH 环境变量
3. ⚠️ 把 dll 丢进系统目录 C:\Windows\System32（不推荐，污染系统）

📌 本项目采用方案 1：所有 dll 统一输出到 output/bin/，exe 也放这里。

7.6 🐧 Linux 下运行注意事项

1
2
3

output/
├── libMathTools.so     # 🟢 动态库
└── MyApp               # 🎯 可执行文件

运行前要告诉系统去哪里找 so：

1
2

export LD_LIBRARY_PATH=/path/to/output:$LD_LIBRARY_PATH
./MyApp

或者编译时直接指定 rpath（推荐，免去每次设环境变量）：

1
2
3
4

# 在 CMake 中添加
set_target_properties(MyApp PROPERTIES
    INSTALL_RPATH "${CMAKE_SOURCE_DIR}/output"
)

🎓 总结

🧠 记忆口诀

静态焊死，动态可插 🔌
Windows 要报关（导出宏），Linux 全自由 🗽
编译靠 .lib，运行靠 .dll —— 一个门牌号，一个真房子 🏷️🏠

📝 本文结合 FastCAE-APPStructural 项目实战，用 🎭 生活比喻、📊 对比表格、💻 完整代码，帮你彻底吃透 C++ 动态库与静态库。希望对你有所帮助！ 🚀