Cmake命令之project介绍

• 命令格式

  project(<PROJECT-NAME> [<language-name>...])
  或
  project(<PROJECT-NAME>
  [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
  [DESCRIPTION <project-description-string>]
  [HOMEPAGE_URL <url-string>]
  [LANGUAGES <language-name>...])

  project命令用于指定cmake工程的名称，实际上，它还可以指定cmake工程的版本号（VERSION关键字）、简短的描述（DESCRIPTION关键字）、主页URL（HOMEPAGE_URL关键字）和编译工程使用的语言（LANGUAGES关键字）。

• 命令解析

  下面根据关键字逐一解析project的用法。
  1. 基本用法：指定工程名称。

  # CMakeLists.txt
  cmake_minimum_required (VERSION 3.10.2)
  project (mytest)
  

    这样就指定了当前的工程名称为mytest。实际上在调用project命令指定当前工程名字的同时，cmake内部会为如下变量赋值：

  • PROJECT_NAME：将当前工程的名称赋值给PROJECT_NAME，对于本例子，就是${PROJECT_NAME}=mytest。
  • PROJECT_SOURCE_DIR：当前工程的源码路径。
  • <PROJECT-NAME>_SOURCE_DIR：指定工程的源码路径，这个变量和PROJECT_SOURCE_DIR的区别就是，<PROJECT-NAME>_SOURCE_DIR跟具体的工程名字关联起来，若<PROJECT-NAME>就是当前工程，则该变量和PROJECT_SOURCE_DIR相等。
  • PROJECT_BINARY_DIR：当前工程的二进制路径。
  • <PROJECT-NAME>_BINARY_DIR：指定工程的二进制路径，这个变量和PROJECT_BINARY_DIR的区别就是，<PROJECT-NAME>_BINARY_DIR跟具体的工程名字关联起来，若<PROJECT-NAME>就是当前工程，则该变量和PROJECT_BINARY_DIR相等。
  • CMAKE_PROJECT_NAME：顶层工程的名称。例如当前调用的CMakeLists.txt位于顶层目录（可以理解为使用cmake命令首次调用的那个CMakeLists.txt），那么工程名还会赋值给CMAKE_PROJECT_NAME。

    在举例之前，我们先做如下约定：假设我们顶层目录为test/，也就是cmake .命令是在该目录下进行调用。并且test/目录下有一个子目录，我们命名为sub_test。在test/目录和test/sub_test/目录下各建立一个CMakeLists.txt。在test/下的CMakeLists.txt文件即使顶层的文件。

  # test/CMakeLists.txt
  cmake_minimum_required (VERSION 3.10.2)
  set (TOP_PROJECT_NAME "mytest") # 定义了变量TOP_PROJECT_NAME为"mytest"
  project (${TOP_PROJECT_NAME}) 
  
  message (">>> top PROJECT_NAME: ${PROJECT_NAME}")
  message (">>> top PROJECT_SOURCE_DIR: ${PROJECT_SOURCE_DIR}")
  message (">>> top <PROJECT_NAME>_SOURCE_DIR: ${${TOP_PROJECT_NAME}_SOURCE_DIR}") 
  message (">>> top PROJECT_BINARY_DIR: ${PROJECT_BINARY_DIR}")
  message (">>> top <PROJECT_NAME>_BINARY_DIR: ${${TOP_PROJECT_NAME}_BINARY_DIR}")
  message (">>> top CMAKE_PROJECT_NAME: ${CMAKE_PROJECT_NAME}")
  
  add_subdirectory (sub_test) # 调用sub_test下的CMakeList.txt进行构建
  

  # test/sub_test/CMakeLists.txt
  cmake_minimum_required (VERSION 3.10.2)
  set (SUB_LEVEL_PROJECT_NAME "mysubtest") # 定义了变量SUB_LEVEL_PROJECT_NAME为"mysubtest"
  project (${SUB_LEVEL_PROJECT_NAME}) 
  
  message (">>>>>> sub PROJECT_NAME: ${PROJECT_NAME}")
  message (">>>>>> sub PROJECT_SOURCE_DIR: ${PROJECT_SOURCE_DIR}")
  message (">>>>>> sub <PROJECT_NAME>_SOURCE_DIR: ${${SUB_LEVEL_PROJECT_NAME}_SOURCE_DIR}") 
  message (">>>>>> sub <PROJECT_NAME>_SOURCE_DIR(top level): ${${TOP_PROJECT_NAME}_SOURCE_DIR}") 
  message (">>>>>> sub PROJECT_BINARY_DIR: ${PROJECT_BINARY_DIR}")
  message (">>>>>> sub <PROJECT_NAME>_BINARY_DIR: ${${SUB_LEVEL_PROJECT_NAME}_BINARY_DIR}")
  message (">>>>>> sub <PROJECT_NAME>_BINARY_DIR(top level): ${${TOP_PROJECT_NAME}_BINARY_DIR}")
  message (">>>>>> sub CMAKE_PROJECT_NAME: ${CMAKE_PROJECT_NAME}")
  

  在test/下执行cmake .，输出如下：

  >>> top PROJECT_NAME: mytest
  >>> top PROJECT_SOURCE_DIR: test/
  >>> top <PROJECT_NAME>_SOURCE_DIR: test/
  >>> top PROJECT_BINARY_DIR: test/ 
  >>> top <PROJECT_NAME>_BINARY_DIR: test/
  >>> top CMAKE_PROJECT_NAME: mytest
  >>>>>> sub PROJECT_NAME: mysubtest
  >>>>>> sub PROJECT_SOURCE_DIR: test/sub_test
  >>>>>> sub <PROJECT_NAME>_SOURCE_DIR: test/sub_test
  >>>>>> sub <PROJECT_NAME>_SOURCE_DIR(top level): test/
  >>>>>> sub PROJECT_BINARY_DIR: test/sub_test
  >>>>>> sub <PROJECT_NAME>_BINARY_DIR: test/sub_test
  >>>>>> sub <PROJECT_NAME>_BINARY_DIR(top level): test/
  >>>>>> sub CMAKE_PROJECT_NAME: mytest
  

    因此可以看成带CMAKE前缀的变量只属于顶层的CMakeLists.txt工程，带<PROJECT_NAME>为指定（特定）工程名的变量，其余的即为当前正在构建的工程变量，下面在讲到project其他选项时也遵循该规则。

  2. VERSION选项：指定工程的版本号。
    指定工程的版本号，格式为VERSION <version>，其中<version>为非负整数组成的一个点分版本号格式<major>[.<minor>[.<patch>[.<tweak>]]],例如1.2.3.4。基本用法如下：

    # CMakeLists.txt
    cmake_minimum_required (VERSION 3.10.2)
    project (mytest VERSION 1.2.3.4)
  

  同样，当project命令使用了VERSION选项，如下变量会被相应的赋值：

  • PROJECT_VERSION
  • <PROJECT-NAME>_VERSION
  • PROJECT_VERSION_MAJOR
  • <PROJECT-NAME>_VERSION_MAJOR
  • PROJECT_VERSION_MINOR
  • <PROJECT-NAME>_VERSION_MINOR
  • PROJECT_VERSION_PATCH
  • <PROJECT-NAME>_VERSION_PATCH
  • PROJECT_VERSION_TWEAK
  • <PROJECT-NAME>_VERSION_TWEAK
  • CMAKE_PROJECT_VERSION

    上述带<PROJECT_NAME>的变量存储的是指定工程名下版本号，不带的表示当前正在调用的工程的版本号。XXX_MAJOR、XXX_MINOR、XXX_PATCH、XXX_TWEAK分别与点分版本号<major>[.<minor>[.<patch>[.<tweak>]]]对应。当然，如果CMakeLists.txt位于顶层目录，CMAKE_PROJECT_VERSION存储的是顶层CMakeLists.txt中project命令指定的版本号，不会随着调用工程的变化而变化。这些变量的使用与1中的工程名变量没什么区别，可以仿照将上述变量打印出来看下，此处就不在赘述。

  3. DESCRIPTION选项：对工程的文本描述。
    格式为DESCRIPTION <project-description-string>，其中<project-description-string>是一段描述，不建议太长。基本用法如下：

    # CMakeLists.txt
    cmake_minimum_required (VERSION 3.10.2)
    project (mytest DESCRIPTION “This is mytest project.”)
  

    同样调用该选项的会对如下变量赋值，方式与前面的工程名和版本号类似，特别的，当CMakeLists.txt位于顶层目录，CMAKE_PROJECT_DESCRIPTION存储的是顶层CMakeLists.txt中project命令指定的工程描述，不会随着调用工程的变化而变化。

  • PROJECT_DESCRIPTION
  • <PROJECT-NAME>_DESCRIPTION
  • CMAKE_PROJECT_DESCRIPTION

  4. HOMEPAGE_URL选项：指定工程的主页URL。
    基本用法如下：

    # CMakeLists.txt
    cmake_minimum_required (VERSION 3.10.2)
    project (mytest HOMEPAGE_URL “https://www.XXX(示例).com”)
  

    同样调用该选项的会对如下变量赋值，方式与前面的工程名和版本号类似，特别的，当CMakeLists.txt位于顶层目录，CMAKE_PROJECT_HOMEPAGE_URL存储的是顶层CMakeLists.txt中project命令指定的工程主页URL，不会随着调用工程的变化而变化。

  • PROJECT_HOMEPAGE_URL
  • <PROJECT-NAME>_HOMEPAGE_URL
  • CMAKE_PROJECT_HOMEPAGE_URL

  5. LANGUAGES选项：选择构建工程需要的编程语言。
    该选项可以有两种调用方式：一种是直接跟在工程名后面，可以省略LANGUAGES关键字；另一种是跟在其他关键字（例如VERSION）后面，LANGUAGES关键字不能省略。

  # CMakeLists.txt
  cmake_minimum_required (VERSION 3.10.2)
  project (mytest “CXX”)
  

  # CMakeLists.txt
  cmake_minimum_required (VERSION 3.10.2)
  project (mytest VERSION 1.2.3.4 LANGUAGES “CXX”)
  

    该选项支持的语言包括C、CXX（例如C++）、CUDA、OBJC（例如Objective-C）、OBJCXX、Fortran、ASM。如果没有指定LANGUAGES选项，默认使用的是C和CXX。如果使用LANGUAGES NONE、或仅仅列出LANGUAGES关键字却没有指定具体的语言，那么表示不支持任何语言。如果需要使能ASM，把它放在列表的最后以便cmake能够检查其他语言（例如C语言）能否工作在汇编下。
    该命令的实质是cmake会使用LANGUAGES后的语言选项来检查CMAKE_XXX_COMPILER指定的编译器是否存在，以便工程能正确的被构建。
    例如：

  # CMakeLists.txt
  cmake_minimum_required (VERSION 3.10.2)
  project (mytest LANGUAGES “CPP”)
  

    会提示

  No CMAKE_CPP_COMPILER could be found.
  

• 更多细节

  1. project命令并非必不可少，如果没有调用project命令，cmake仍然会生成一个默认的工程名“Project”，以及工程名对应的变量（例如PROJECT_NAME、CMAKE_PROJECT_NAME、PROJECT_SOURCE_DIR、<PROJECT_NAME>_SOURCE_DIR、PROJECT_BINARY_DIR、<PROJECT_NAME>_BINARY_DIR等）。但是VERSION、DESCRIPTION、HOMEPAGE_URL等选项对应的变量不会被赋值（LANGUAGES例外，即使不指定，默认语言为C和CXX）。
  2. project命令需要放置在其他命令调用之前，在cmake_minimum_required（参考https://www.jianshu.com/p/7535bff0e894
     ）命令之后。
  3. 如果多次调用project命令，那么CMAKE_PROJECT_NAME、CMAKE_PROJECT_VERSION、CMAKE_PROJECT_DESCRIPTION、CMAKE_PROJECT_HOMEPAGE_URL等变量是以最近一次调用的project命令为准，例如：

  # test/CMakeLists.txt
  cmake_minimum_required (VERSION 3.10.2)
  project (mytest)
  message (">>> top CMAKE_PROJECT_NAME: ${CMAKE_PROJECT_NAME}"
  project (mytest1)
  add_subdirectory (sub_test) # 调用sub_test下的CMakeList.txt进行构建
  project (mytest2)
  message (">>> top CMAKE_PROJECT_NAME: ${CMAKE_PROJECT_NAME}"
  

  # test/sub_test/CMakeLists.txt
  cmake_minimum_required (VERSION 3.10.2)
  project (mysubtest)
  message (">>>>>> sub CMAKE_PROJECT_NAME: ${CMAKE_PROJECT_NAME}"
  

  输出为：

  >>> top CMAKE_PROJECT_NAME: mytest
  >>>>>> sub CMAKE_PROJECT_NAME: mytest1
  >>> top CMAKE_PROJECT_NAME: mytest2
  

附录：参考资料

1. https://cmake.org/cmake/help/latest/command/project.html
2. https://cmake.org/cmake/help/latest/variable/CMAKE_PROJECT_NAME.html#variable:CMAKE_PROJECT_NAME
3. https://cmake.org/cmake/help/latest/variable/CMAKE_PROJECT_VERSION.html#variable:CMAKE_PROJECT_VERSION