CMake Tutorial(9)_ 选择静态或动态库
这是本系列的第十篇。
上一篇我们学习了如何将测试提交到测试白板CDash上。
这一篇我们学习比较重要也比较常用的内容:选择静态或动态库。
关于静态或动态库的使用方法这里就不再赘述了,相信有C++编译基础的同学都应该比较清楚。
那么我们就来进入干货内容的学习吧~
本章导读
第九步 选择静态或动态库
In this section we will show how the
BUILD_SHARED_LIBS
variable can be used to control the default behavior ofadd_library()
, and allow control over how libraries without an explicit type (STATIC
,SHARED
,MODULE
orOBJECT
) are built.
在本章,我们将要展示如何使用 BUILD_SHARED_LIBS
变量来控制 add_library()
的默认行为,以及在没有显式给定类型(STATIC
, SHARED
, MODULE
或 OBJECT
)时,如何控制各种库的编译生成。
To accomplish this we need to add
BUILD_SHARED_LIBS
to the top-levelCMakeLists.txt
. We use theoption()
command as it allows users to optionally select if the value should beON
orOFF
.
为了实现这个功能我们需要将 BUILD_SHARED_LIBS
添加到顶层的CMakeLists.txt
文件中。我们使用option()
命令, 这样可以允许用户在ON
和OFF
之间切换选择。
Next we are going to refactor
MathFunctions
to become a real library that encapsulates usingmysqrt
orsqrt
, instead of requiring the calling code to do this logic. This will also mean thatUSE_MYMATH
will not control buildingMathFunctions
, but instead will control the behavior of this library.
接下来我们将重构MathFunctions
以使它变成一个封装有mysqrt
或sqrt
的真正的库,而不是逻辑上还需要调用的源代码。这将意味着USE_MYMATH
不再控制编译MathFunctions
,而是控制库的行为。
The first step is to update the starting section of the top-level
CMakeLists.txt
to look like:
第一步是如下更新顶层的CMakeLists.txt
的开始章节:
cmake_minimum_required(VERSION 3.10)
# set the project name and version
project(Tutorial VERSION 1.0)
# specify the C++ standard
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED True)
# control where the static and shared libraries are built so that on windows
# we don't need to tinker with the path to run the executable
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
# configure a header file to pass the version number only
configure_file(TutorialConfig.h.in TutorialConfig.h)
# add the MathFunctions library
add_subdirectory(MathFunctions)
# add the executable
add_executable(Tutorial tutorial.cxx)
target_link_libraries(Tutorial PUBLIC MathFunctions)
小白按:添加完这段代码后,顶层的CMakeLists.txt
变成了以下这样:
cmake_minimum_required(VERSION 3.10)
# set the project name and version
project(Tutorial VERSION 1.0)
# specify the C++ standard
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED True)
# control where the static and shared libraries are built so that on windows
# we don't need to tinker with the path to run the executable
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
# configure a header file to pass the version number only
configure_file(TutorialConfig.h.in TutorialConfig.h)
# add the MathFunctions library
add_subdirectory(MathFunctions)
# add the executable
add_executable(Tutorial tutorial.cxx)
target_link_libraries(Tutorial PUBLIC MathFunctions)
# add the binary tree to the search path for include files
# so that we will find TutorialConfig.h
target_include_directories(Tutorial PUBLIC
"${PROJECT_BINARY_DIR}"
)
# add the install targets
install(TARGETS Tutorial DESTINATION bin)
install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h"
DESTINATION include
)
# enable testing
include(CTest)
# does the application run
add_test(NAME Runs COMMAND Tutorial 25)
# does the usage message work?
add_test(NAME Usage COMMAND Tutorial)
set_tests_properties(Usage
PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number"
)
# define a function to simplify adding tests
function(do_test target arg result)
add_test(NAME Comp${arg} COMMAND ${target} ${arg})
set_tests_properties(Comp${arg}
PROPERTIES PASS_REGULAR_EXPRESSION ${result}
)
endfunction()
# do a bunch of result based tests
do_test(Tutorial 4 "4 is 2")
do_test(Tutorial 9 "9 is 3")
do_test(Tutorial 5 "5 is 2.236")
do_test(Tutorial 7 "7 is 2.645")
do_test(Tutorial 25 "25 is 5")
do_test(Tutorial -25 "-25 is (-nan|nan|0)")
do_test(Tutorial 0.0001 "0.0001 is 0.01")
include(InstallRequiredSystemLibraries)
set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")
set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}")
set(CPACK_SOURCE_GENERATOR "TGZ")
include(CPack)
Now that we have made
MathFunctions
always be used, we will need to update the logic of that library. So, inMathFunctions/CMakeLists.txt
we need to create a SqrtLibrary that will conditionally be built and installed whenUSE_MYMATH
is enabled. Now, since this is a tutorial, we are going to explicitly require that SqrtLibrary is built statically.
这样我们已经让MathFunctions
能够一直被使用,接下来我们需要更新子库的逻辑。所以,在MathFunctions/CMakeLists.txt
我们需要创建一个条件编译的平方根库,当USE_MYMATH
被使能时就进行编译和安装。现在,因为这是一个教程,我们将会显式地要求平方根库被编译为静态库。
The end result is that
MathFunctions/CMakeLists.txt
should look like:
最终的结果是,MathFunctions/CMakeLists.txt
应该像以下这样:
MathFunctions/CMakeLists.txt
# add the library that runs
add_library(MathFunctions MathFunctions.cxx)
# state that anybody linking to us needs to include the current source dir
# to find MathFunctions.h, while we don't.
target_include_directories(MathFunctions
INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
)
# should we use our own math functions
option(USE_MYMATH "Use tutorial provided math implementation" ON)
if(USE_MYMATH)
target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH")
# first we add the executable that generates the table
add_executable(MakeTable MakeTable.cxx)
# add the command to generate the source code
add_custom_command(
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h
COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h
DEPENDS MakeTable
)
# library that just does sqrt
add_library(SqrtLibrary STATIC
mysqrt.cxx
${CMAKE_CURRENT_BINARY_DIR}/Table.h
)
# state that we depend on our binary dir to find Table.h
target_include_directories(SqrtLibrary PRIVATE
${CMAKE_CURRENT_BINARY_DIR}
)
target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
endif()
# define the symbol stating we are using the declspec(dllexport) when
# building on windows
target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
# install rules
set(installable_libs MathFunctions)
if(TARGET SqrtLibrary)
list(APPEND installable_libs SqrtLibrary)
endif()
install(TARGETS ${installable_libs} DESTINATION lib)
install(FILES MathFunctions.h DESTINATION include)
小白按: 教程难得是给出了全部的代码,小白这里就不加赘述了,以上代码就是完整版。
Next, update
MathFunctions/mysqrt.cxx
to use themathfunctions
anddetail
namespaces:
接下来,更新MathFunctions/mysqrt.cxx
来使用mathfunctions
以及detail
这两个命名空间:
MathFunctions/mysqrt.cxx
#include <iostream>
#include "MathFunctions.h"
// include the generated table
#include "Table.h"
namespace mathfunctions {
namespace detail {
// a hack square root calculation using simple operations
double mysqrt(double x)
{
if (x <= 0) {
return 0;
}
// use the table to help find an initial value
double result = x;
if (x >= 1 && x < 10) {
std::cout << "Use the table to help find an initial value " << std::endl;
result = sqrtTable[static_cast<int>(x)];
}
// do ten iterations
for (int i = 0; i < 10; ++i) {
if (result <= 0) {
result = 0.1;
}
double delta = x - (result * result);
result = result + 0.5 * delta / result;
std::cout << "Computing sqrt of " << x << " to be " << result << std::endl;
}
return result;
}
}
}
We also need to make some changes in
tutorial.cxx
, so that it no longer usesUSE_MYMATH
:
- Always include
MathFunctions.h
- Always use
mathfunctions::sqrt
- Don’t include
cmath
我们也需要在tutorial.cxx
文件中做一些修改,这样它不再使用USE_MYMATH
:
- 始终包含
MathFunctions.h
- 始终使用
mathfunctions::sqrt
- 不要包含
cmath
小白按: 这里修改完成后的tutorial.cxx如下所示:
// A simple program that computes the square root of a number
#include <iostream>
#include <string>
#include "TutorialConfig.h"
// should we include the MathFunctions header?
#ifdef USE_MYMATH
# include "MathFunctions.h"
#endif
int main(int argc, char* argv[])
{
if (argc < 2) {
// report version
std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
<< Tutorial_VERSION_MINOR << std::endl;
std::cout << "Usage: " << argv[0] << " number" << std::endl;
return 1;
}
// convert input to double
const double inputValue = std::stod(argv[1]);
const double outputValue = mathfunctions::sqrt(inputValue);
std::cout << "The square root of " << inputValue << " is " << outputValue
<< std::endl;
return 0;
}
Finally, update
MathFunctions/MathFunctions.h
to use dll export defines:
最后,更新MathFunctions/MathFunctions.h
来使用dll导出定义:
MathFunctions/MathFunctions.h
#if defined(_WIN32)
# if defined(EXPORTING_MYMATH)
# define DECLSPEC __declspec(dllexport)
# else
# define DECLSPEC __declspec(dllimport)
# endif
#else // non windows
# define DECLSPEC
#endif
namespace mathfunctions {
double DECLSPEC sqrt(double x);
}
At this point, if you build everything, you may notice that linking fails as we are combining a static library without position independent code with a library that has position independent code. The solution to this is to explicitly set the
POSITION_INDEPENDENT_CODE
target property of SqrtLibrary to beTrue
no matter the build type.‘’
在这里,如果你编译好了所有的代码,你可能会注意到链接会失败,因为我们正在将没有位置无关代码的静态库与具有位置无关代码的库组合在一起。此问题的解决方案是将 Sqrt 库的 POSITION_INDEPENDENT_CODE
目标属性显式设置为 True
,无论生成类型如何。即如下所示:
MathFunctions/CMakeLists.txt
# state that SqrtLibrary need PIC when the default is shared libraries
set_target_properties(SqrtLibrary PROPERTIES
POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS}
)
target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
小白按: 小白在没有添加以上段落时发生了错误,添加以上段落后则没有问题
添加完以上段落后完整的MathFunctions/CMakeLists.txt
为
# add the library that runs
add_library(MathFunctions MathFunctions.cxx)
# state that anybody linking to us needs to include the current source dir
# to find MathFunctions.h, while we don't.
target_include_directories(MathFunctions
INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
)
# should we use our own math functions
option(USE_MYMATH "Use tutorial provided math implementation" ON)
if(USE_MYMATH)
target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH")
# first we add the executable that generates the table
add_executable(MakeTable MakeTable.cxx)
# add the command to generate the source code
add_custom_command(
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h
COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h
DEPENDS MakeTable
)
# library that just does sqrt
add_library(SqrtLibrary STATIC
mysqrt.cxx
${CMAKE_CURRENT_BINARY_DIR}/Table.h
)
# state that we depend on our binary dir to find Table.h
target_include_directories(SqrtLibrary PRIVATE
${CMAKE_CURRENT_BINARY_DIR}
)
# state that SqrtLibrary need PIC when the default is shared libraries
set_target_properties(SqrtLibrary PROPERTIES
POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS}
)
target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
endif()
# define the symbol stating we are using the declspec(dllexport) when
# building on windows
target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
# install rules
set(installable_libs MathFunctions)
if(TARGET SqrtLibrary)
list(APPEND installable_libs SqrtLibrary)
endif()
install(TARGETS ${installable_libs} DESTINATION lib)
install(FILES MathFunctions.h DESTINATION include)
Exercise: We modified
MathFunctions.h
to use dll export defines. Using CMake documentation can you find a helper module to simplify this?
小练习: 我们修改了MathFunctions.h
来使用dll导出定义。通过CMake文档你是否能够找到一个帮助模块来简化这里的操作?
小白按: 这里恕小白水平有限,尝试了一下(整整折腾了一天),没有成功,感觉连题目本身也没有完全理解透彻。这道题意思是说不修改MathFunctions.h的情况下,只通过CMake文件来简化吗?小白感觉理解错了,之前查到一个install(EXPORT)
的用法,但一直没有编译通过。不知道各位聪明的读者朋友有没有对这个问题的见解?欢迎在评论区回复。小白感激不尽~
下一篇我们学习添加生成器表达式。
【水平所限,错漏难免,创作不易,轻喷勿骂】