CMake中add_library的使用

Posted 2022-12-15 fengbingchun

      CMake中的add_library命令用于使用指定的源文件向项目(project)中添加库，其格式如下：

add_library(<name> [STATIC | SHARED | MODULE]
            [EXCLUDE_FROM_ALL]
            [<source>...]) # Normal Libraries
add_library(<name> OBJECT [<source>...]) # Object Libraries
add_library(<name> INTERFACE) # Interface Libraries
add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL]) # 3.19 version, Interface Libraries
add_library(<name> <type> IMPORTED [GLOBAL]) # Imported Libraries
add_library(<name> ALIAS <target>) # Alias Libraries

      1.Normal Libraries：添加一个名为<name>的库目标(library target)，从命令调用中列出的源文件构建。<name>对应于逻辑目标名称，并且在项目中必须是全局唯一(globally unique)的。构建的库的实际文件名是基于本机平台(native platform)的约定构建的(例如lib<name>.a或<name>.lib).
      add_library的源参数可以使用语法为$<...>的"generator expressions".
      如果后面使用target_sources命令添加源文件，则可以省略它们。
      可以给出STATIC,SHARED或MODULE来指定要创建的库的类型。STATIC库是链接其它目标时使用的目标文件存档(archive of object file).SHARED库是动态链接的，并在运行时加载。MODULE库是未链接到其它目标但可以在运行时使用类似dlopen的功能动态加载的插件。如果没有明确给出类型，则根据变量BUILD_SHARED_LIBS的当前值是否为ON，来决定类型是STATIC还是SHARED。对于SHARED和MODULE库，POSITION_INDEPENDENT_CODE目标属性自动设置为ON。可以使用FRAMEWORK目标属性标记SHARED库以创建macOS Framework。
      可以使用FRAMEWORK目标属性标记STATIC库以创建static Framework。
      如果库不导出任何符号，则不得将其声明为SHARED库。例如，不导出非托管符号(exports no unmanaged symbols)的Windows资源DLL需要是MODULE库。CMake期望SHARED库在Windows上始终具有关联的导入库(import library).
      默认情况下，库文件将在与调用命令的源树目录对应的构建树目录中创建(the library file will be created in the build tree directory corresponding to the source tree directory in which the command was invoked)。可通过ARCHIVE_OUTPUT_DIRECTORY, LIBRARY_OUTPUT_DIRECTORY和RUNTIME_OUTPUT_DIRECTORY目标属性更改此位置。可通过OUTPUT_NAME目标属性更改最终文件名的<name>。
      如果给定了EXCLUDE_FROM_ALL，则将在创建的目标上设置相应的属性。

include_directories($CMAKE_CURRENT_SOURCE_DIR/include)

add_library(add_static STATIC $CMAKE_CURRENT_SOURCE_DIR/source/add.cpp) # 将会在build目录下生成libadd_static.a
if(TARGET add_static)
    message("target: static library add") # print
endif()

add_library(add_shared SHARED $CMAKE_CURRENT_SOURCE_DIR/source/add.cpp) # 将会在build目录下生成libadd_shared.so
if(TARGET add_shared)
    message("target: shared library add") # print
endif()

add_library(add_module MODULE $CMAKE_CURRENT_SOURCE_DIR/source/add.cpp) # 将会在build目录下生成libadd_module.so
if(TARGET add_module)
    message("target: module library add") # print
endif()

      2.Object Libraries：创建对象库(Object Library).对象库编译源文件，但不会将其存档或链接到库中。相反，由add_library命令或add_executable命令创建的其它目标可以使用$<TARGET_OBJECTS:objlib>形式的表达式作为源来引用对象，其中objlib是对象库名称。
      可以使用target_link_libraries命令链接对象库。

include_directories($CMAKE_CURRENT_SOURCE_DIR/include)
add_library(add_object OBJECT $CMAKE_CURRENT_SOURCE_DIR/source/add.cpp) # 在build目录下不会有add_object文件生成
if(TARGET add_object)
    message("target: object library add") # print
endif()

      3.Interface Libraries：创建接口库(Interface Library).INTERFACE库目标不编译源代码，也不在磁盘上生成库文件。但是，它可能设置了属性，并且可以安装和导出。通常，使用以下命令在接口目标上填充INTERFACE_*属性：然后它像任何其它目标一样被用作target_link_libraries命令的参数

set_property(),
target_link_libraries(INTERFACE),
target_link_options(INTERFACE),
target_include_directories(INTERFACE),
target_compile_options(INTERFACE),
target_compile_definitions(INTERFACE),
target_sources(INTERFACE),

      使用上述签名创建的接口库本身没有源文件，并且不作为目标包含在生成的构建系统中。
      接口库可以具有PUBLIC_HEADER和PRIVATE_HEADER属性。可以使用install(TARGETS)命令安装由这些属性指定的headers。
      3.19版本中，可以使用源文件创建接口库。源文件可以直接在add_library调用中列出，也可以稍后通过使用PRIVATE或PUBLIC关机键调用target_sources添加。
      如果接口库有源文件(即设置了SOURCES目标属性)或头文件集(即设置了HEADER_SETS目标属性)，它将作为构建目标出现在生成的构建系统中，就像add_custom_target命令。它不编译任何源代码，但包含由add_custom_command命令创建的自定义命令的构建规则。
      注意：在大多数出现INTERFACE关键字的命令签名中，其后列出的项仅成为该目标使用要求的一部分，而不是目标自身设置的一部分。但是在add_library的签名中，INTERFACE关键字仅指库类型。在add_library调用中列出的源是接口库的PRIVATE，不会出现在其INTERFACE_SOURCES目标属性中。

add_library(add_interface INTERFACE) # 在build目录下不会有add_interface文件生成
if(TARGET add_interface)
    message("target: interface library add") # print
endif()

      4.Imported Libraries：创建一个名为<name>的IMPORTED库目标。不会生成任何规则来构建它，并且IMPORTED目标属性为True。目标名称在创建它的目录及其下的目录中具有作用域(has scope)，但是GLOBAL选项扩展了可见性。它可以像项目中构建的任何目标一样被引用。IMPORTED库可用于方便地从target_link_libraries等命令中引用。通过设置名称以IMPORTED_和INTERFACE_开头的属性来指定有关导入库的详细信息。
      <type>必须是以下之一：
      (1).STATIC, SHARED, MODULE, UNKNOWN:引用位于项目外部的库文件。IMPORTED_LOCATION目标属性(或其每个配置变量)指定磁盘上主库文件(main library)的位置：
      对于大多数非Windows平台上的SHARED库，主库文件是链接器和动态加载器使用的.so或.dylib文件。
      对于Windows上的SHARED库，IMPORTED_IMPLIB目标属性(或其每个配置变量IMPORTED_IMPLIB_<CONFIG>)指定DLL导入库文件(.lib或.dll.a)在磁盘上的位置。IMPORTED_LOCATION是.dll运行时库的位置。
      可以在INTERFACE_*属性中指定其它使用要求。
      UNKNOWN库类型通常仅用于Find Modules的实现。它允许使用导入库的路径(通常使用find_library命令找到)，而不必知道它是什么类型的库。这在Windows上特别有用，静态库和DLL导入库具有相同的文件扩展名。
      (2).OBJECT:引用位于项目外部的目标文件。IMPORTED_OBJECTS目标属性(或其每个配置变量IMPORTED_OBJECTS_<CONFIG>)指定目标文件在磁盘上的位置。可以在INTERFACE_*属性中指定其它使用要求。
      (3).INTERFACE:不引用磁盘上的任何库或目标文件，但可以在INTERFACE_*属性中指定使用要求。

add_library(add_imported SHARED IMPORTED) # 在build目录下不会有add_imported文件生成
if(TARGET add_imported)
    message("target: imported library add") # print
endif()

      5.Alias Libraries：创建一个别名目标(Alias Target),以便<name>可用于在后续的命令中引用<target>。<name>不会作为make目标出现在所生成的构建系统中。<target>可能不是ALIAS。
      An ALIAS can target a GLOBAL Imported Target.
      An ALIAS can target a non-GLOBAL Imported Target.这种别名的作用域是创建它的目录和子目录。ALIAS_GLOBAL目标属性可以用来检查别名是不是全局的。
      ALIAS目标可以用作可链接的目标，也可以用作从中读取属性的目标。也可以使用常规的if(TARGET)子命令测试它们是否存在。<name>不能用来修改<target>的属性，即，它不能用作set_property, set_target_properties，target_link_libraries等命令的操作数。ALIAS目标不能被安装或导出。

include_directories($CMAKE_CURRENT_SOURCE_DIR/include)
add_library(add_alias $CMAKE_CURRENT_SOURCE_DIR/source/subtraction.cpp)
add_library(yyyy ALIAS add_alias)
if(TARGET yyyy)
    message("target: yyyy") # print
endif()
if(TARGET add_alias)
    message("target: add_alias") # print
endif()

      执行测试代码需要多个文件：

      build.sh内容如下：

#! /bin/bash

# supported input parameters(cmake commands)
params=(function macro cmake_parse_arguments \\
		find_library find_path find_file find_program find_package \\
		cmake_policy cmake_minimum_required project include \\
		string list set foreach message option if while return \\
		math file configure_file \\
		include_directories add_executable add_library target_link_libraries install)

usage()

	echo "Error: $0 needs to have an input parameter"

	echo "supported input parameters:"
	for param in $params[@]; do
		echo "  $0 $param"
	done

	exit -1


if [ $# != 1 ]; then
	usage
fi

flag=0
for param in $params[@]; do
	if [ $1 == $param ]; then
		flag=1
		break
	fi
done

if [ $flag == 0 ]; then
	echo "Error: parameter \\"$1\\" is not supported"
	usage
	exit -1
fi

if [[ ! -d "build" ]]; then
	mkdir build
	cd build
else
	cd build
fi

echo "==== test $1 ===="

# test_set.cmake: cmake -DTEST_CMAKE_FEATURE=$1 --log-level=verbose ..
# test_option.cmake: cmake -DTEST_CMAKE_FEATURE=$1 -DBUILD_PYTORCH=ON ..
cmake -DTEST_CMAKE_FEATURE=$1 ..
# It can be executed directly on the terminal, no need to execute build.sh, for example: cmake -P test_set.cmake
make
# make install # only used in cmake files with install command

      CMakeLists.txt内容如下：

cmake_minimum_required(VERSION 3.22)
project(cmake_feature_usage)

message("#### current cmake version: $CMAKE_MAJOR_VERSION.$CMAKE_MINOR_VERSION.$CMAKE_PATCH_VERSION")
include(test_$TEST_CMAKE_FEATURE.cmake)
message("==== test finish ====")

      test_add_library.cmake内容为上面的所有测试代码段。

      另外还包括三个目录：include,source,samples,它们都是非常简单的实现，仅用于测试，如下：

        可能的执行结果如下图所示:

      GitHub： https://github.com/fengbingchun/Linux_Code_Test