阅读 apiextractor 的CMakeList.txt文件

拖了近一个月了，终于有信心尝试看看 apiextractor-0.10.0 的 CMakeList.txt 了 。简单整理一下，作为学习笔记，备忘。

走马观花

include(icecc.cmake)

包含一个文件，其内容比较简单（如果找到分布式编译器icecc，则使用它）

project(apiextractor)
cmake_minimum_required(VERSION 2.6)
find_package(Qt4 4.5.0 REQUIRED)
find_package(LibXml2 2.6.32)
find_package(LibXslt 1.1.19)

常规内容，依赖 Qt4(必须)，LibXml2，LibXslt3个软件包

option(DISABLE_DOCSTRINGS "Disable documentation extraction." FALSE)
option(BUILD_TESTS "Build tests." TRUE)
option(INSTALL_TESTS "Install tests" FALSE)
option(ENABLE_VERSION_SUFFIX "Used to use current version in suffix to generated files. This is used to allow multiples versions installed simultaneous." FALSE)

4个选项

if (NOT DISABLE_DOCSTRINGS)
    if (NOT LIBXSLT_FOUND OR NOT LIBXML2_FOUND)
        set(DISABLE_DOCSTRINGS TRUE)
        message(WARNING "libxslt and/or libxml not found, disabling support to doc strings!")
    endif()
endif()

如果没有禁用DOCSTRINGS，但是没有找到LibXml2和LibXslt，同样禁用

if(MSVC)
    set(CMAKE_CXX_FLAGS "/Zc:wchar_t- /GR /EHsc /DWIN32 /D_WINDOWS /D_SCL_SECURE_NO_WARNINGS")
elseif(CMAKE_HOST_UNIX)
    option(ENABLE_GCC_OPTIMIZATION "Enable specific GCC flags to optimize library size and performance. Only available on Release Mode" 0)
    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -fvisibility=hidden")
    set(CMAKE_CXX_FLAGS_DEBUG "-g")
    if(ENABLE_GCC_OPTIMIZATION)
        set(CMAKE_BUILD_TYPE Release)
        set(CMAKE_CXX_FLAGS_RELEASE "-DNDEBUG -Os -Wno-strict-aliasing -Wl,-O1")
        if (NOT CMAKE_HOST_APPLE)
            set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wl,--hash-style=gnu")
        endif()
    endif()
    if(NOT CMAKE_HOST_APPLE)
        set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -Wl,--version-script,${CMAKE_CURRENT_SOURCE_DIR}/symbols.filter")
    endif()
endif()

为MSVC、UNIX等分别设置一些选项

if(NOT CMAKE_BUILD_TYPE)
    set(CMAKE_BUILD_TYPE Release)
endif()

如果没有设置构建类型，则使用Release

if(BUILD_TESTS)
    set(LIBRARY_OUTPUT_PATH ${CMAKE_BINARY_DIR}/tests)
endif ()

如果需要构建测试程序，则设置库文件输出目录为 tests子目录

set(apiextractor_MAJOR_VERSION 0)
set(apiextractor_MINOR_VERSION 10)
set(apiextractor_MICRO_VERSION 0)
set(apiextractor_VERSION "${apiextractor_MAJOR_VERSION}.${apiextractor_MINOR_VERSION}.${apiextractor_MICRO_VERSION}")
configure_file(apiextractorversion.h.in ${CMAKE_CURRENT_BINARY_DIR}/apiextractorversion.h @ONLY)
set(apiextractor_SOVERSION ${apiextractor_MAJOR_VERSION}.${apiextractor_MINOR_VERSION})

设置版本号，并使用配置文件(只替代@VAR@这样的变量)

set(QT_USE_QTCORE 1)
set(QT_USE_QTXML 1)
include(${QT_USE_FILE})
add_definitions(${QT_DEFINITIONS})
add_definitions(-DQT_PLUGIN)
add_definitions(-DQT_SHARED)
add_definitions(-DRXX_ALLOCATOR_INIT_0)

Qt的常规设置

if(ENABLE_VERSION_SUFFIX)
    set(apiextractor_SUFFIX "-${apiextractor_MAJOR_VERSION}.${apiextractor_MINOR_VERSION}")
else()
    set(apiextractor_SUFFIX "")
endif()

控制是否需要后缀

set(apiextractor_SRC
apiextractor.cpp
abstractmetabuilder.cpp
#omit ...
)
if (NOT DISABLE_DOCSTRINGS)
    set(apiextractor_SRC
        ${apiextractor_SRC}
        docparser.cpp
        doxygenparser.cpp
        qtdocparser.cpp
    )
    set(APIEXTRACTOR_EXTRA_INCLUDES ${LIBXSLT_INCLUDE_DIR} ${LIBXML2_INCLUDE_DIR})
    set(APIEXTRACTOR_EXTRA_LIBRARIES ${LIBXSLT_LIBRARIES} ${LIBXML2_LIBRARIES})
else()
    set(APIEXTRACTOR_EXTRA_INCLUDES "")
    set(APIEXTRACTOR_EXTRA_LIBRARIES "")
endif()

将源文件名存入变量 apiextractor_SRC，如果启用了DOCSTRINGS，则设置LibXslt和LibXml2的头文件路径和库

set(LIB_INSTALL_DIR "${CMAKE_INSTALL_PREFIX}/lib${LIB_SUFFIX}" CACHE PATH "The subdirectory relative to the install prefix where libraries will be installed (default is /lib${LIB_SUFFIX})" FORCE)

设置一个变量，稍后作为库文件安装路径

qt4_add_resources(apiextractor_RCCS_SRC generator.qrc)
qt4_automoc(apiextractor_SRC)

Qt 常规设置，注意qt4_automoc 根据源文件中的#include "xxx.moc"来确定处理相应的头文件

include_directories(${CMAKE_CURRENT_SOURCE_DIR}
                    ${CMAKE_CURRENT_BINARY_DIR}
                    ${CMAKE_CURRENT_SOURCE_DIR}/parser
                    ${CMAKE_CURRENT_SOURCE_DIR}/parser/rpp
                    ${QT_INCLUDE_DIR}
                    ${APIEXTRACTOR_EXTRA_INCLUDES}
                    )

add_library(apiextractor SHARED ${apiextractor_SRC} ${apiextractor_RCCS_SRC})
target_link_libraries(apiextractor ${APIEXTRACTOR_EXTRA_LIBRARIES} ${QT_QTCORE_LIBRARY} ${QT_QTXMLPATTERNS_LIBRARY} ${QT_QTXML_LIBRARY})
set_target_properties(apiextractor PROPERTIES VERSION ${apiextractor_VERSION}
                                              SOVERSION ${apiextractor_SOVERSION}
                                              OUTPUT_NAME "apiextractor${apiextractor_SUFFIX}"
                                              DEFINE_SYMBOL APIEXTRACTOR_EXPORTS)

设置头文件目录，添加库文件目标，设置目标属性(注意DEFINE_SYMBOL)

# uninstall target
configure_file("${CMAKE_CURRENT_SOURCE_DIR}/cmake_uninstall.cmake" "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake" IMMEDIATE @ONLY)
add_custom_target(uninstall "${CMAKE_COMMAND}" -P "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake")

set(ARCHIVE_NAME ${CMAKE_PROJECT_NAME}-${apiextractor_VERSION})
add_custom_target(dist
    COMMAND mkdir -p "${CMAKE_BINARY_DIR}/${ARCHIVE_NAME}" &&
            git log > "${CMAKE_BINARY_DIR}/${ARCHIVE_NAME}/ChangeLog" &&
            git archive --prefix=${ARCHIVE_NAME}/ HEAD --format=tar --output="${CMAKE_BINARY_DIR}/${ARCHIVE_NAME}.tar" &&
            tar -C "${CMAKE_BINARY_DIR}" --owner=root --group=root -r "${ARCHIVE_NAME}/ChangeLog" -f "${CMAKE_BINARY_DIR}/${ARCHIVE_NAME}.tar" &&
            bzip2 -f9 "${CMAKE_BINARY_DIR}/${ARCHIVE_NAME}.tar" &&
            echo "Source package created at ${CMAKE_BINARY_DIR}/${ARCHIVE_NAME}.tar.bz2./n"
    WORKING_DIRECTORY ${CMAKE_SOURCE_DIR})

两个自定义的目标 uninstall 和 dist

set(root_HEADERS
apiextractormacros.h
abstractmetalang.h
apiextractor.h
graph.h
reporthandler.h
typesystem.h
fileout.h
docparser.h
qtdocparser.h
include.h
typedatabase.h
)

将文件放于变量 root_HEADERS，稍后会用在install中。（这些文件最终会被安装）

if (BUILD_TESTS)
    enable_testing()
    add_subdirectory(tests)
endif()

控制单元测试的启用

add_subdirectory(data)
add_subdirectory(doc)

前者生成ApiExtractorConfig.cmake等文件，后者生成文档

install(FILES ${root_HEADERS} DESTINATION include/apiextractor${apiextractor_SUFFIX})
install(TARGETS apiextractor EXPORT apiextractor
                             LIBRARY DESTINATION "${LIB_INSTALL_DIR}"
                             ARCHIVE DESTINATION "${LIB_INSTALL_DIR}"
                             RUNTIME DESTINATION bin)

需要安装的文件，及安装到的路径

知识点备忘

• 布尔真：1, ON, YES, TRUE, Y, 非零数
• 布尔假：0, OFF, NO, FALSE, N, IGNORE, "", 后缀为'-NOTFOUND'的

option()

option(<option_variable> "describing" [initial value])

为用户提供ON/OFF选项，初始值没有指定的话，采用OFF

set_target_properties()

set_target_properties(target1 target2 ...  PROPERTIES prop1 value1 prop2 value2 ...)

• DEFINE_SYMBOL在生成动态库，定义编译预处理器符号。如果没有指定，默认是 target_EXPORTS

• VERSION与SOVERSION分别是构建版本号 和 api 版本号

• PREFIX与SUFFIX分别是前缀(比如lib)和后缀(比如.so)

• IMPORT_PREFIX与IMPORT_SUFFIX导入库的前缀和后缀

• OUTPUT_NAME

install(TARGETS...)

install(TARGETS targets... [EXPORT <export-name>]
          [[ARCHIVE|LIBRARY|RUNTIME|FRAMEWORK|BUNDLE|
            PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
           [DESTINATION <dir>]
           [PERMISSIONS permissions...]
           [CONFIGURATIONS [Debug|Release|...]]
           [COMPONENT <component>]
           [OPTIONAL] [NAMELINK_ONLY|NAMELINK_SKIP]
          ] [...])

• EXPORT 必须出现在 RUNTIME, LIBRARY, ARCHIVE 之前。配合下面的 install(EXPORT) 使用

install(EXPORT...)

install(EXPORT <export-name> DESTINATION <dir>
          [NAMESPACE <namespace>] [FILE <name>.cmake]
          [PERMISSIONS permissions...]
          [CONFIGURATIONS [Debug|Release|...]]
          [COMPONENT <component>])

• 有助于外部的工程使用本工程构建和安装的目标。