什么是REUSE

使用 pkg-config

pkg-config 是一个在源代码编译时查询已安装的库的使用接口的计算机工具软件。pkg-config原本是设计用于Linux的，但现在在各个版本的BSD、windows、Mac OS X和Solaris上都有着可用的版本。

它输出已安装的库的相关信息，包括：

C/C++编译器需要的输入参数
链接器需要的输入参数
已安装软件包的版本信息

使用 cmake 生成 .pc 文件

一个比较规范的 foo.pc.in 如下：

prefix=@CMAKE_INSTALL_PREFIX@
exec_prefix=${prefix}
libdir=@CMAKE_INSTALL_FULL_LIBDIR@
includedir=@CMAKE_INSTALL_FULL_INCLUDEDIR@/libimageviewer

Name: foo
Description: foo is a demo lib
Version: @PROJECT_VERSION@
Libs: -L${libdir} -lfoo
Cflags: -I${includedir}
Requires: Qt5Core Qt5Gui Qt5Widgets

这里的 Name 是显示的名称，文件名才是搜索用，显示名一般不要全部大写。

Requires：设置 foo 的依赖，这里有2个条件：

必须是传播的构建依赖，即某软件构建依赖 foo，构建环境必须有 bar 才可以编译
必须是提供 .pc 文件的依赖

另外不要忘记加 -L 参数（链接库地址），-I 参数（头文件地址）。

其中路径问题（libdir/includedir）这里再强调一下，不规范做法：

prefix=/usr
exec_prefix=${prefix}
libdir=${prefix}/lib
includedir=${prefix}/include/foo

这种是硬编码路径，可移植性非常差。

prefix=@CMAKE_INSTALL_PREFIX@
exec_prefix=${prefix}
libdir=${prefix}/lib
includedir=${prefix}/include/foo

相比上种方法，prefix 使用 cmake 变量，可以应对 prefix 不是 /usr 的情况了。

prefix=@CMAKE_INSTALL_PREFIX@
exec_prefix=${prefix}
libdir=${prefix}/@CMAKE_INSTALL_LIBDIR@
includedir=${prefix}/@CMAKE_INSTALL_INCLUDEDIR@/foo

相比上种方法，lib/include 目录使用 GNUInstallDirs 变量代替，灵活度更高。

但是，这种并非最好的，因为（1）GNUInstallDirs 有特殊的拼接规则，如 PREFIX=/，LIBDIR=lib，应该拼接成 /usr/include 而非 /include。（2）CMAKE_INSTALL_LIBDIR 虽然默认是相对路径，但允许被直接设置成绝对路径。

写在 .pc.in 只能简单拼接，无法判断特殊情况，最好由 cmake 进行拼接。GNUInstallDirs 提供 FULL 版本变量（本文第一个示例）就是智能拼接出来的，建议使用。当然，基于此自行设置变量也可以： set (INCLUDE_INSTALL_DIR "${CMAKE_INSTALL_FULL_INCLUDEDIR}/libdtk-${CMAKE_PROJECT_VERSION}/DCore")。

使用 qmake 生成 pkgcconfig 文件

CONFIG += create_prl create_pc
# 生成 .pc 文件需要 .prl 中间文件，如果不需要可以使用 no_install_prl

QMAKE_PKGCONFIG_NAME = foo
QMAKE_PKGCONFIG_DESCRIPTION = foo is demo
QMAKE_PKGCONFIG_INCDIR = $${HEADERDIR}
QMAKE_PKGCONFIG_LIBDIR = $${LIBDIR}
QMAKE_PKGCONFIG_DESTDIR = pkgconfig

其中的 HEADERDIR，LIBDIR 是需要在 .pro 文件中设置的安装路径。

cmake 使用 pkg-config

不要混淆 find_package 和 pkg_check_modules

cmake 导入

find_package(PkgConfig REQUIRED) # 导入此模块才可以使用 pkg_check_modules
pkg_check_modules(DtkCore REQUIRED dtkcore)
message("${DtkCore_VERSION}")
message("${DtkCore_LIBRARIES}") # 对应 -l 参数
message("${DtkCore_LIBRARY_DIRS}") # 对应 -L 参数
message("${DtkCore_INCLUDE_DIRS}") # 对应 -I 参数

pkg_check_modules(Dtk REQUIRED dtkcore dtkgui dtkwidget)
message("${Dtk_LIBRARIES}")
message("${Dtk_LIBRARY_DIRS}")
message("${Dtk_INCLUDE_DIRS}")

参考资料

https://cmake.org/cmake/help/latest/module/FindPkgConfig.html

qmake 使用 pkg-config

CONFIG += link_pkgconfig
PKGCONFIG += foo

规范设置编译参数 🔗

https://modern-cmake-cn.github.io/Modern-CMake-zh_CN/chapters/features/small.html

CMake 中有许多关于编译器和链接器的设置。当你需要添加一些特殊的需求，你应该首先检查 CMake 是否支持这个需求，如果支持的话，你就可以不用关心编译器的版本，一切交给 CMake 来做即可。更棒的是，你可以在 CMakeLists.txt 表明你的意图，而不是通过开启一系列标志 (flag) 。

优化参数(-O0/-O1/-O2/-O3/-Ofast/-Os) 和 debug 参数（-g）

CMAKE_BUILD_TYPE 包括 Debug, Release, RelWithDebInfo 和 MinSizeRe 4 个选项

它们对应参数是（不同编译平台可能有少许区别）：

Release: -O3 -DNDEBUG
Debug: -O0 -g
RelWithDebInfo: -O2 -g -DNDEBUG
MinSizeRel: -Os -DNDEBUG

这些参数可以通过 CMAKE_CXX_FLAGS_DEBUG，CMAKE_CXX_FLAGS_RELEASE… 查看，并不直接体现在 CMAKE_CXX_FLAGS 中。

CMAKE_BUILD_TYPE 的默认值不是Release，也不属于上面4种，而是空值，即不附加任何参数。

全局（或非debug模式）设置 -O3：

建议改为将 CMAKE_BUILD_TYPE 设置默认 Release

https://github.com/ros-infrastructure/bloom/issues/327

Release 模式加 O3, Debug 模式加 -g 等等

不用加，这些都是无用功

Release 模式加 -g

如果软件发行版本需要 debug 符号，请用 RelWithDebInfo 模式

Debug 加 -O3

高级别的优化会严重影响 debug 调试，可以改用 -Og，它允许不影响调试的优化

同时有 -O1 -O3

-O0/-O1/-O2/-O3/-Ofast 开启的优化参数前依次递增，是完全的子集关系，不是多多益善的。 -Os 是在 -O2 的基础上，尽可能优化程序大小。

Release 模式使用 -Ofast 或其他优化级别。

最好是 string(REPLACE "-O3" "-Ofast" CMAKE_CXX_FLAGS_RELEASE ${CMAKE_CXX_FLAGS_RELEASE})，这样就没有原来的-O3了如果是是降低优化基本，则必须这样替换。

参考资料：

https://stackoverflow.com/questions/48754619/what-are-cmake-build-type-debug-release-relwithdebinfo-and-minsizerel

de

参考修改：

https://github.com/linuxdeepin/dtkcore/pull/114

c++标准版本 (比如 -std=c++11)

直接使用 set(CMAKE_CXX_STANDARD 11)

部分项目设置了 CMAKE_CXX_STANDARD 为 14/17, 又加了参数 -std=c++11，这是冲突的，请检查。比如： https://github.com/linuxdeepin/deepin-movie-reborn/blob/0a08e29e78c4f35f787b999d857f696f804f8641/CMakeLists.txt#L18

Hardening

DEB_BUILD_HARDENING_FORMAT (gcc/g++ -Wformat -Wformat-security -Werror=format-security) DEB_BUILD_HARDENING_FORTIFY (gcc/g++ -D_FORTIFY_SOURCE=2) DEB_BUILD_HARDENING_STACKPROTECTOR (gcc/g++ -fstack-protector-strong) DEB_BUILD_HARDENING_PIE (gcc/g++ -fPIE -pie) DEB_BUILD_HARDENING_RELRO (ld -z relro) DEB_BUILD_HARDENING_BINDNOW (ld -z now)

as-need 参数

已知 as-need 参数 break 了 mold 连接器，可用 as-needed 代替。相关：https://github.com/linuxdeepin/developer-center/issues/3345

dl 库

如果你需要链接到 dl 库，在 Linux 上可以使用 -ldl 标志，不过在 CMake 中只需要在 target_link_libraries 命令中使用内置的 CMake 变量 ${CMAKE_DL_LIBS} 。这里不需要模组或者使用 find_package 来寻找它。（这个命令包含了调用 dlopen 与 dlclose 的一切依赖）

程序间优化(Interprocedural optimization)

INTERPROCEDURAL_OPTIMIZATION，最有名的是 链接时间优化 以及 -flto 标志，这在最新的 CMake 版本中可用。你可以通过变量 CMAKE_INTERPROCEDURAL_OPTIMIZATION（ CMake 3.9+ 可用）或对目标指定 INTERPROCEDURAL_OPTIMIZATION 属性来打开它。在 CMake 3.8 中添加了对 GCC 及 Clang 的支持。如果你设置了 cmake_minimum_required(VERSION 3.9) 或者更高的版本（参考 CMP0069），当在编译器不支持 INTERPROCEDURAL_OPTIMIZATION 时，通过变量或属性启用该优化会产生报错。你可以使用内置模块 CheckIPOSupported 中的 check_ipo_supported() 来检查编译器是否支持 IPO 。下面是基于 CMake 3.9 的一个例子：

include(CheckIPOSupported)
check_ipo_supported(RESULT result)
if(result)
  set_target_properties(foo PROPERTIES INTERPROCEDURAL_OPTIMIZATION TRUE)
endif()

位置无关的代码

在 g++ 中，对编译生成动态库是 -fPIC/-fpic，对生成可执行文件是 -fPIE/-fpie。

如果要把静态库链接到动态库，这一选项是必须的。其他情况也建议开启，可以防范一些内存攻击。

在 cmake 中，对于动态库（SHARED and MODULE library），这一选项是默认开启的。对于静态库，在 cmake 3.14 版本之后（CMP0083 新标准），默认值是 POSITION_INDEPENDENT_CODE，而该值默认为假。

可以通过 set(POSITION_INDEPENDENT_CODE True) 让静态库默认增加 “-fpic” 编译。

最好通过 set_property 设置此选项：set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)，foo 为对应静态库或者可执行程序。

此外，推荐使用 check_pie_supported()，检查一下编译器是否支持。

参考资料：

-lpthread

POSIX thread 是基于 C/C++ 的标准线程库。在 cmake 3.1 以上的版本提供了 FindThreads 模块，如果设置 THREADS_PREFER_PTHREAD_FLAG 变量，会优先使用 pthread。

set(THREADS_PREFER_PTHREAD_FLAG ON)
find_package(Threads REQUIRED)
target_link_libraries(my_app PRIVATE Threads::Threads)

参考文档：

设置时不要覆盖之前的选项

错误示例：set(CMAKE_CXX_FLAGS “-Wall”) 正确示例：set(CMAKE_CXX_FLAGS “${CMAKE_CXX_FLAGS} -Wall”)

如果确实有覆盖的要求，请在源码注释说明，因为一般出现覆盖 flag 很可能是失误。

判断架构

遗留代码有使用 dpkg-architecture 判断的，改用 CMAKE_SYSTEM_PROCESSOR。

dpkg-architecture 是 debian 系特有的，并不通用。除了 deb 安装器等不考虑像其他发行版移植的应用，不要在 CMakeList 里使用 dpkg 系列命令。

https://github.com/linuxdeepin/dde-dock/pull/681

CMAKE_L_FLAGS

部分项目使用了 CMAKE_L_FLAGS，这不是 cmake 标准的变量，这是想用 CMAKE_EXE_LINKER_FLAGS ？

glib-compile-schemas

gsettings schemas 安装后需要编译一下（一般目录是 /usr/share/glib-2.0/schemas）才能使用，这个应该是安装后进行的，用对应目录所有 gschema.xml 再编译出一个 gschemas.compiled 文件。

像下面这样在 CMakeList.txt 编译是不需要的： install(CODE "execute_process(COMMAND glib-compile-schemas ${CMAKE_INSTALL_PREFIX}/share/glib-2.0/schemas)") 相关修改

尽可能避免使用 hardcode 路径 🔗

可执行程序

判断某个可执行程序是否存在

不推荐做法：根据硬编码路径判断某个文件是否存在。比如判断 QFile().exists(/usr/bin/Foo)。

推荐做法：根据 PATH 寻找可执行文件, 一般不需要自行读取 PATH，比如 QT 可以使用：

Exist = !QStandardPaths::findExecutable("Foo").isEmpty();

比如 glib 可以使用 find_program_in_path。

修改示例：

执行某个可执行程序

同样，推荐用 PATH 寻找，尽量不使用绝对路径。

Qt 的 QProcess 会自动处理 PATH 环境变量，因此 QProcess::execute("/usr/bin/touch", QStringList() << sessionCacheFile) 可以直接改成 QProcess::execute("touch", QStringList() << sessionCacheFile)。

修改示例：

https://github.com/linuxdeepin/deepin-downloader/pull/27

动态库路径

尽量不要硬编码 /urs/lib

qt 应用可以使用 QLibraryInfo::location(QLibraryInfo::LibrariesPath)

头文件

绝对不要有 #include </usr/include/xxx.h> 这种代码，c/c++ 头文件会自动在 /usr/include 里寻找，直接使用 #include <xxx.h> 。

此外，如果库提供了 pkg-config 文件，提供的 -I 参数会指定头文件位置，如果提供 Config.cmake （cmake用）文件，一般会提供 Foo_INCLUDE_DIR 变量，如果提供 .pri （qmake 用）文件，由 QT.foo.includes 提供头文件位置。xxx.h 是相对提供的路径寻找。

对于没有提供任何开发文件的库，也可以使用 cmake 提供的 CheckIncludeFile 模块寻找头文件。

应用数据（/use/share）

/usr/share，一般保存与架构无关的只读数据。此目录同样不应该硬编码，在 XDG 规范中，这种数据的目录使用环境变量 XDG_DATA_DIRS 设置，如果读不到对应环境变量再去读取 /usr/local/share:/usr/share。

使用 qt 的应用该类型硬编码路径应该使用 QStandardPaths 或者 libqtxdg 代替。

参考：XDG Base Directory

在此目录寻找某文件，推荐使用 QStandardPaths::standardLocations 参考修改：

https://github.com/0xd34df00d/leechcraft/commit/32bf44704e156eaf6ada672e18febf64d9fd279f

/usr/share/applications

直接使用 QStandardPaths::standardLocations(QStandardPaths::ApplicationsLocation)

/usr/share/AppName

读取本应用数据，qt 软件可以使用 QStandardPaths::standardLocations(QStandardPaths::AppLocalDataLocation)

导入翻译

部分应用导入翻译使用了 /usr/share 示例, 应该改为使用 QStandardPaths::standardLocations(QStandardPaths::GenericDataLocation), 此外使用了 dtk 的应用是直接用 DApplication 的 loadTranslator 导入翻译。

Shebangs

#!/bin/bash -> #!/usr/bin/env bash
#!/usr/bin/python -> #!/usr/bin/env python

并非所有系统都有 /bin 目录和 /usr/bin 目录，比如 NixOS 和 GNU Guix 操作系统。 env 可以根据环境变量 $PATH 寻找可执行程序（如 bash），比硬编码路径更加灵活，可以提高可移植性。

不过并非所有脚本都适合使用 env, 有 2 种情况：

对安全性要求高的脚本（如以 root 权限运行），硬编码可以避免通过相关 PATH 让 bash 指向恶意程序。
带有参数的 Shebangs 头，如 #!/usr/bin/perl -w 不能改成 #!/usr/bin/env perl -w

对除此之外的大部分的 Shebangs 脚本来说，使用 env 是更好的方案。

参考资料：

在 GNU/Linux 中使用 GNUInstallDirs 优化 cmake 安装路径 🔗

使用 GNUInstallDirs.cmake模块

在指定安装路径时，应当使用变量而非写死安装目录，以便于在不完全符合 FHS 的系统上安装，提高程序的可移植性。对于使用何种变量， GUN 提出了适用于 unix 系统的 GNU标准安装目录，GNU/Linux 上使用的就是这套标准的变体。cmake 官方提供了 GNUInstallDirs 模块，定义了一组标准的变量，用于安装不同类型文件到规范指定的目录中。

要使用这个模块，在 CMakeLists.txt 添加一行 include(GNUInstallDirs) 即可导入。如果你发现 CMAKE_INSTALL_XXXX 的值为空，大概率是缺少这一行。注意导入模块需要放在使用变量之前。

前缀值 CMAKE_INSTALL_PREFIX

CMAKE_INSTALL_PREFIX（后面简称 PREFIX）是一个非常特殊的变量，在 CMakeLists.txt 中所有的相对路径都会默认把 PREFIX 作为前缀进行拼接，组成绝对路径。这一变量是 cmake 基础变量，不导入 GNUInstallDirs 模块也会存在。

举一个例子，假如之前要把文件安装进 /usr/share 目录

install(FILES ${QM_FILES} DESTINATION  /usr/share/deepin-calculator/translations)

如果设置了 PREFIX=/usr，只需要改成相对路径 share，cmake 会自动拼接成 /usr/share

install(FILES ${QM_FILES} DESTINATION  share/deepin-calculator/translations)

这样写，如果安装前缀改变，比如改成 /usr/local，只需要修改 CMAKE_INSTALL_PREFIX，而不用改 CMakeLists.txt 源码。

目前 CMAKE_INSTALL_PREFIX 按 GNU 的标准默认值是 /usr/local。而在 dde 的项目中，一般期望前缀值是 /usr。我们当然可以通过 cmake -DCMAKE_INSTALL_PREFIX=/usr 来修改 PREFIX，但最好在项目中添加下面 3 行修改一下 PREFIX 的默认值：

if (CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
    set(CMAKE_INSTALL_PREFIX /usr)
endif ()

这里容易犯两种错误：

没有检查 CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT 就直接 set：这会导致用户传入的参数失效，相当于硬编码了路径。
使用 if (NOT DEFINE CMAKE_INSTALL_PREFIX ) 判断用户是否传参了 PREFIX：实际上 PREFIX 无论什么情况都是有定义的，只能使用 CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT 判断是否是默认值。

对 CMAKE_INSTALL_PREFIX 的配置会对子目录生效，在 cmake 3.14 之前，先应用安装规则再处理 add_subdirectory，而 3.14 及后续版本，会按照声明的顺序运行所有安装规则/add_subdirectory，因此，除非你想给子目录单独配置，上述的设置应写在 add_subdirectory 的前面。见 CMP0082。

GNUInstallDirs 变量

在 GNUInstallDirs 中，定义了一些 GNU 标准安装目录的变量，提供给定类型文件的安装路径。这些值可以传递给对应 install() 命令的 DESTINATION 选项。它们通常是相对于安装前缀（PREFIX）的相对路径，以便于以可重定位的方式将其拼接为绝对路径。当然，它们也允许赋值为绝对路径。

CMAKE_INSTALL_XXXX

CMAKE_INSTALL_BINDIR 用户可执行程序（ bin ）
CMAKE_INSTALL_SBINDIR 系统管理员可执行程序（ sbin ）
CMAKE_INSTALL_LIBEXECDIR 可执行库文件（ libexec ）
CMAKE_INSTALL_SYSCONFDIR 单机只读数据/read-only single-machine data（ etc ）
CMAKE_INSTALL_SHAREDSTATEDIR 架构无关的可修改数据/modifiable architecture-independent data （ com ）
CMAKE_INSTALL_LOCALSTATEDIR 单机可修改数据/modifiable single-machine data（ var ）
CMAKE_INSTALL_RUNSTATEDIR 3.9版中加入：运行时可修改数据（ LOCALSTATEDIR/run ）
CMAKE_INSTALL_LIBDIR 目标代码库/object code libraries （ lib 或 lib64 ）（在 Debian 上当 PREFIX 是 /usr 时，LIBDIR 也可能是 lib/<multiarch-tuple> ）
CMAKE_INSTALL_INCLUDEDIR C语言头文件（ include ）
CMAKE_INSTALL_OLDINCLUDEDIR non-gcc 的C语言头文件（ /usr/include ）
CMAKE_INSTALL_DATAROOTDIR 与架构无关的只读数据根目录（ share ）
CMAKE_INSTALL_DATADIR 与架构无关的只读数据（ DATAROOTDIR ）
CMAKE_INSTALL_INFODIR info 文档（ DATAROOTDIR/info ）
CMAKE_INSTALL_LOCALEDIR 与语言相关的数据/locale-dependent data（ DATAROOTDIR/locale ）
CMAKE_INSTALL_MANDIR man 文档（ DATAROOTDIR/man ）
CMAKE_INSTALL_DOCDIR 文档根目录（ DATAROOTDIR/doc/PROJECT_NAME ）

需要注意的是 DATAROOTDIR 是 DATADIR，LOCALEDIR，MANDIR 和 DOCDIR 共同前缀，不应该在 install 中直接使用 DATAROOTDIR 作为参数，而是应该使用 DATADIR 代替。类似 /usr/share/man 的路径应该用 MANDIR 代替，而不是 DATADIR/man。

CMAKE_INSTALL_FULL_XXXX

CMAKE_INSTALL_BINDIR 推荐用相对路径，但也可以使用绝对路径，有些时候我们需要绝对路径（比如生成 pkgconfig 文件时），直接加 PREFIX 拼接并不好（因为 BINDIR 可能已经是绝对路径了），这时，我们可以直接使用 CMAKE_INSTALL_FULL_BINDIR，这是由 GNUInstallDirs 模块提供，自动从 BINDIR 计算出的绝对路径。如果 BINDIR 是绝对路径，直接相等。如果 BINDIR 是相对路径，则等于 BINDIR 按照一定规则与 PREFIX 拼接而成的值。

用例： https://github.com/linuxdeepin/dde-dock/pull/556

当然，install 是没有必要用 CMAKE_INSTALL_FULL_XXXX 的（当然用也可以），因为它会自动判断，并拼接相对路径。

前缀拼接的特殊情况

GNUInstallDirs 前缀拼接存在一些特殊情况需要注意：

1. CMAKE_INSTALL_PREFIX=/

除了 SYSCONFDIR, LOCALSTATEDIR 和 RUNSTATEDIR 正常拼接外, 其他值都会增加一个 usr/ 前缀。比如 INCLUDEDIR 默认值 include ，变成 usr/include, 最终拼接成 /usr/include。

这里自动增加 usr 是符合 GNU 目录标准的，因为这些路径是符号链接。
~ ❯❯❯ readlink /lib
usr/lib
~ ❯❯❯ readlink /bin
usr/bin

2. CMAKE_INSTALL_PREFIX=/usr

SYSCONFDIR, LOCALSTATEDIR 和 RUNSTATEDIR 拼接时只拼接 “/”。比如, SYSCONFDIR 默认值 etc 会拼接成 /etc。

3. CMAKE_INSTALL_PREFIX=/opt/…

SYSCONFDIR, LOCALSTATEDIR 和 RUNSTATEDIR 会向后拼接。比如， SYSCONFDIR 会变成 /etc/opt/….

参考文档

Sunday, August 14, 2022

DDE-Control-Center 自启动管理插件成果展示 🔗

dde 自启动管理插件开发小组博客 6:00 am