跳到主要内容

安装和使用包示例：SQLite

说明

本旧示例使用经典模式（Classic mode），但大多数开发者更适合使用清单模式（Manifest mode）。如需了解如何迁移到清单模式，请参考《清单模式：CMake 示例》。

步骤 1：安装​

首先，我们需要确认 SQLite 在 kmpkg 端口库中的名称。运行 search 命令并查看输出：

PS D:\src\kmpkg> .\kmpkg search sqlite
libodb-sqlite        2.4.0            为 ODB ORM 库提供 Sqlite 支持
sqlite3              3.32.1           SQLite 是一个实现了自包含、无服务器、零配置、事务性 SQL 数据库引擎的软件库...

如果未找到你需要的库，请在以下地址提交 issue：
    https://github.com/kumose/kmpkg/issues

从结果中可以看到，该端口的名称是 sqlite3。你也可以直接运行 search 命令（不带参数）查看所有可用包。

安装操作只需执行 install 命令：

PS D:\src\kmpkg> .\kmpkg install sqlite3
Computing installation plan...
The following packages will be built and installed:
    sqlite3[core]:x86-windows
Starting package 1/1: sqlite3:x86-windows
Building package sqlite3[core]:x86-windows...
-- Downloading https://sqlite.org/2020/sqlite-amalgamation-3320100.zip...
-- Extracting source C:/src/kmpkg/downloads/sqlite-amalgamation-3320100.zip
-- Applying patch fix-arm-uwp.patch
-- Using source at C:/src/kmpkg/buildtrees/sqlite3/src/3320100-15aeda126a.clean
-- Configuring x86-windows
-- Building x86-windows-dbg
-- Building x86-windows-rel
-- Performing post-build validation
-- Performing post-build validation done
Building package sqlite3[core]:x86-windows... done
Installing package sqlite3[core]:x86-windows...
Installing package sqlite3[core]:x86-windows... done
Elapsed time for package sqlite3:x86-windows: 12 s

Total elapsed time: 12.04 s

The package sqlite3:x86-windows provides CMake targets:

    find_package(unofficial-sqlite3 CONFIG REQUIRED)
    target_link_libraries(main PRIVATE unofficial::sqlite3::sqlite3))

运行 list 命令可验证 sqlite3 是否已成功安装到 x86 Windows 桌面平台：

PS D:\src\kmpkg> .\kmpkg list
sqlite3:x86-windows         3.32.1           SQLite 是一个实现了自包含、无服务器、零配置、事务性 SQL 数据库引擎的软件库...

若要为其他架构/平台（如通用 Windows 平台 UWP、x64 桌面）安装，可在包名后添加 <目标三元组> 后缀：

PS D:\src\kmpkg> .\kmpkg install sqlite3:x86-uwp zlib:x64-windows

运行 .\kmpkg help triplet 可查看所有支持的目标三元组。

步骤 2：使用​

VS/MSBuild 项目（用户级全局集成）​

了解更多关于在 MSBuild 中使用 kmpkg 的信息

使用 kmpkg 最推荐、最高效的方式是用户级全局集成，该方式可让所有项目都能使用已安装的库。首次在某台机器上使用全局集成时，会提示获取管理员权限；后续使用无需再次授权，且集成配置基于每个用户独立生效。

PS D:\src\kmpkg> .\kmpkg integrate install
Applied user-wide integration for this kmpkg root.

All C++ projects can now #include any installed libraries.
Linking will be handled automatically.
Installing new libraries will make them instantly available.
说明

你需要重启 Visual Studio 或执行一次构建操作，以更新智能提示（intellisense）。

完成集成后，只需在 Visual Studio 中通过「文件 -> 新建项目」创建项目，已安装的库就会自动可用。对于 SQLite，你可以尝试其 C/C++ 示例代码。

若要移除当前用户的全局集成，可运行 .\kmpkg integrate remove。

CMake（工具链文件）​

了解更多关于在 CMake 中使用 kmpkg 的信息

在 CMake 中使用已安装库的最佳方式是通过工具链文件 scripts\buildsystems\kmpkg.cmake。只需在 CMake 命令行中添加该文件路径：

-DCMAKE_TOOLCHAIN_FILE=D:\src\kmpkg\scripts\buildsystems\kmpkg.cmake。

若你通过 Visual Studio 的「打开文件夹」功能使用 CMake，可在 CMakeSettings.json 的每个配置中添加「variables」节来定义 CMAKE_TOOLCHAIN_FILE：

{
  "configurations": [{
    "name": "x86-Debug",
    "generator": "Visual Studio 15 2017",
    "configurationType" : "Debug",
    "buildRoot":  "${env.LOCALAPPDATA}\\CMakeBuild\\${workspaceHash}\\build\\${name}",
    "cmakeCommandArgs": "",
    "buildCommandArgs": "-m -v:minimal",
    "variables": [{
      "name": "CMAKE_TOOLCHAIN_FILE",
      "value": "D:\\src\\kmpkg\\scripts\\buildsystems\\kmpkg.cmake"
    }]
  }]
}
说明

可能需要删除每个修改后配置的 CMake 缓存文件夹，以强制完全重新生成。在CMake菜单下的Cache (<配置名称>)中，可找到Delete Cache Folders选项。

接下来创建一个简单的 CMake 项目（包含主文件）：

# CMakeLists.txt
cmake_minimum_required(VERSION 3.0)
project(test)

find_package(unofficial-sqlite3 CONFIG REQUIRED)

add_executable(main main.cpp)

target_link_libraries(main PRIVATE unofficial::sqlite3::sqlite3)
// main.cpp
#include <sqlite3.h>
#include <stdio.h>

int main()
{
    printf("%s\n", sqlite3_libversion());
    return 0;
}

然后按常规 CMake 方式构建项目：

PS D:\src\cmake-test> mkdir build 
PS D:\src\cmake-test> cd build
PS D:\src\cmake-test\build> cmake .. "-DCMAKE_TOOLCHAIN_FILE=D:\src\kmpkg\scripts\buildsystems\kmpkg.cmake"
    // 此处省略 CMake 输出 //
-- Build files have been written to: D:/src/cmake-test/build
PS D:\src\cmake-test\build> cmake --build .
    // 此处省略 MSBuild 输出 //
Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:02.38
PS D:\src\cmake-test\build> .\Debug\main.exe
3.15.0
说明

针对 x86-windows 平台构建时，对应的 sqlite3.dll 会自动复制到输出文件夹。你需要将该 DLL 与应用程序一起分发。

处理无原生 CMake 支持的库​

与其他平台不同，kmpkg 默认不会自动将 include\ 目录添加到编译命令中。若你使用的库未提供 CMake 集成，需通过 find_path() 和 find_library() 显式查找文件并手动添加：

# 查找并使用 catch 库
find_path(CATCH_INCLUDE_DIR catch.hpp)
target_include_directories(main PRIVATE ${CATCH_INCLUDE_DIR})

# 查找并使用 azure-storage-cpp 库
find_path(WASTORAGE_INCLUDE_DIR was/blob.h)
find_library(WASTORAGE_LIBRARY wastorage)
target_include_directories(main PRIVATE ${WASTORAGE_INCLUDE_DIR})
target_link_libraries(main PRIVATE ${WASTORAGE_LIBRARY})