cmake install package

cmake install

introduce

cmake official website : https://cmake.org/
cmake download address :
https://cmake.org/files/
https://github.com/Kitware/CMake/releases
https://github.com/SFUMECJF/cmake- examples-Chinese

When using cmake, the most common steps are:

mkdir build && cd build
cmake ..
make
make install

The install command is used to define installation rules. The installed content can include target binaries, dynamic libraries, static libraries, files, directories, scripts, etc.

install(TARGETS <target>... [...])
install({
    
    FILES | PROGRAMS} <file>... [...])
install(DIRECTORY <dir>... [...])
install(SCRIPT <file> [...])
install(CODE <code> [...])
install(EXPORT <export-name> [...])

A very useful variable CMAKE_INSTALL_PREFIX is also used to specify the relative address prefix when cmake install. Usage such as:

cmake -DCMAKE_INSTALL_PREFIX=/usr ..


DESTINATION 定义了安装的路径，如果路径以/开头，那么指的是绝对路径，这时候
CMAKE_INSTALL_PREFIX 其实就无效了。如果你希望使用 CMAKE_INSTALL_PREFIX 来
定义安装路径，就要写成相对路径，即不要以/开头，那么安装后的路径就是
${CMAKE_INSTALL_PREFIX}/<DESTINATION 定义的路径

在CMake中，采用 CMAKE_INSTALL_PREFIX来指定文件的安装位置，Linux下默认是/usr/local；Windows的默认值为 c:/Program Files/${PROJECT_NAME}

Install command introduction

Installation of target files

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

in parametersTARGETIt can be many kinds of target files, the most common one is throughADD_EXECUTABLEorADD_LIBRARYThe defined target file, i.e.Executable binary, dynamic library, static library：

Target file	content	Installation directory variables	Default installation folder
ARCHIVE	static library	${CMAKE_INSTALL_LIBDIR}	lib
LIBRARY	dynamic library	${CMAKE_INSTALL_LIBDIR}	lib
RUNTIME	Executable binary file	${CMAKE_INSTALL_BINDIR}	bin
PUBLIC_HEADER	PUBLIC header files associated with the library	${CMAKE_INSTALL_INCLUDEDIR}	include
PRIVATE_HEADER	PRIVATE header files associated with the library	${CMAKE_INSTALL_INCLUDEDIR}	include

In order to comply with the general default installation path, if the DESTINATION parameter is set , it is recommended to configure the folder under the installation directory variable.

For example:

INSTALL(TARGETS myrun mylib mystaticlib
        RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
        LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
        ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
)

The above example will install: the executable binary myrun to $CMAK{E}_{I}NSTAL{L}_{B}INDIR\ast \ast Directory,dynamiclibrarylibmylib.so\; isinstalledto\ast \ast$ {CMAKE_INSTALL_LIBDIR}, the static library libmystaticlib.a is installed to${CMAKE_INSTALL_LIBDIR}directory.
The meaning of some other parameters:

• DESTINATION : SpecificationDirectory on disk where files are to be installed；
• PERMISSIONS : SpecificationInstallation file permissions。有效权限是OWNER_READ，OWNER_WRITE，OWNER_EXECUTE，GROUP_READ，GROUP_WRITE，GROUP_EXECUTE，WORLD_READ，WORLD_WRITE，WORLD_EXECUTE，SETUID和SETGID；
• CONFIGURATIONS : Specify installation rulesList of applicable build configurations (DEBUG or RELEASE, etc.);
• EXCLUDE_FROM_ALL : Specifies that the file is excluded from the complete installation and installed only as part of a component-specific installation;
• OPTIONAL : Specifying is not an error if the file to be installed does not exist.
  pay attentionCONFIGURATIONSparameters, the value specified by this option applies only to the options listed after this option: for example, to set separate installation paths for debug and release configurations, do the following:

install(TARGETS target
        CONFIGURATIONS Debug
        RUNTIME DESTINATION Debug/bin)
        install(TARGETS target
        CONFIGURATIONS Release
        RUNTIME DESTINATION Release/bin)

In other words, the DESTINATION installation paths of the DEBUG and RELEASE versions are different, so DESTINATION must be behind CONFIGUATIONS .

Installation of ordinary files

install(<FILES|PROGRAMS> files...
        TYPE <type> | DESTINATION <dir>
        [PERMISSIONS permissions...]
        [CONFIGURATIONS [Debug|Release|...]]
        [COMPONENT <component>]
        [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])

FILES|PROGRAMS ifFile names given by relative paths will be interpreted relative to the current source directory. in,FILES is an ordinary text file，PROGRAMS refers to executable programs that are not target files (such as script files)。

If the PERMISSIONS parameter is not provided, by default ,ordinary text filewill have OWNER_WRITE, OWNER_READ, GROUP_READ and WORLD_READ permissions, which is 644 permissions; whileNon-object file executable programWill have OWNER_EXECUTE, GROUP_EXECUTE, and WORLD_EXECUTE, which is 755 permissions.

Among them, cmake also provides default installation paths for different TYPEs, as shown in the following table:

TYPE type	Installation directory variables	Default installation folder
BIN	${CMAKE_INSTALL_BINDIR}	bin
SBIN	${CMAKE_INSTALL_SBINDIR}	sbin
LIB	${CMAKE_INSTALL_LIBDIR}	lib
INCLUDE	${CMAKE_INSTALL_INCLUDEDIR}	include
SYSCONF	${CMAKE_INSTALL_SYSCONFDIR}	etc
SHAREDSTATE	${CMAKE_INSTALL_SHARESTATEDIR}	com
LOCALSTATE	${CMAKE_INSTALL_LOCALSTATEDIR}	was
RUNSTATE	${CMAKE_INSTALL_RUNSTATEDIR}	/run
DATA	${CMAKE_INSTALL_DATADIR}
INFO	${CMAKE_INSTALL_INFODIR}	/info
LOCALE	${CMAKE_INSTALL_LOCALEDIR}	/locale
MAN	${CMAKE_INSTALL_MANDIR}	/man
DOC	${CMAKE_INSTALL_DOCDIR}	/doc

Note that some types of built-in defaults use the DATAROOT directory as a prefix, with the CMAKE_INSTALL_DATAROOTDIR variable value as content.

The meaning of some other parameters:

• DESTINATION : SpecificationDirectory on disk where files are to be installed；
• PERMISSIONS : SpecificationInstallation file permissions。有效权限是OWNER_READ，OWNER_WRITE，OWNER_EXECUTE，GROUP_READ，GROUP_WRITE，GROUP_EXECUTE，WORLD_READ，WORLD_WRITE，WORLD_EXECUTE，SETUID和SETGID；
• CONFIGURATIONS : Specify installation rulesList of applicable build configurations (DEBUG or RELEASE, etc.);
• EXCLUDE_FROM_ALL : Specifies that the file is excluded from the complete installation and installed only as part of a component-specific installation;
• OPTIONAL : Specifying is not an error if the file to be installed does not exist.
• RENAME : Specifies the name of the installed file, which may be different from the original file. Renaming is only allowed if the command installed a single file.

Directory installation

install(DIRECTORY dirs...
        TYPE <type> | DESTINATION <dir>
        [FILE_PERMISSIONS permissions...]
        [DIRECTORY_PERMISSIONS permissions...]
        [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
        [CONFIGURATIONS [Debug|Release|...]]
        [COMPONENT <component>] [EXCLUDE_FROM_ALL]
        [FILES_MATCHING]
        [[PATTERN <pattern> | REGEX <regex>]
        [EXCLUDE] [PERMISSIONS permissions...]] [...])

This command willThe contents of one or more directories are installed to a given destination. The directory structure is copied one by one to the target location.. The last component of each directory name is appended to the target directory, but this can be avoided by using a trailing slash, which leaves the last component blank. What does it mean?

for example,If DIRECTORY is followed by abc, it means that the abc directory will be installed in the target path. abc/ means that the contents of the abc directory will be installed in the target path, but the abc directory itself will not be installed.. That is, if the directory name does not end with /, then this directory will be installed as abc in the target path. If the directory name ends with /, it means that the contents of this directory will be installed to the target path, but not the directory itself.

FILE_PERMISSIONSandDIRECTORY_PERMISSIONSOptions specify permissions on files and directories in the target. If USE_SOURCE_PERMISSIONS is specified and FILE_PERMISSIONS is not specified, file permissions are copied from the source directory structure.If permissions are not specified, files will be given the default permissions specified in the FILES form of the command (644 permissions), and directories will be given the default permissions specified in the PROGRAMS form of the command (755 permissions)。

can usePATTERN or REGEX options to control the installation of directories at fine granularity, you can specify a wildcard pattern or regular expression to match directories or files encountered in the input directory. PATTERN will only match the full filename, while REGEX will match any part of the filename, but it can simulate PATTERN behavior using / and $.

Certain parameters following a PATTERN or REGEX expression apply only to files or directories that satisfy the expression. For example: EXCLUDE option will skip matching files or directories. The PERMISSIONS option will override the permission settings for matching files or directories.

For example:

INSTALL(DIRECTORY icons scripts/ DESTINATION share/myproj
        PATTERN "CVS" EXCLUDE
        PATTERN "scripts/*"
        PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
        GROUP_EXECUTE GROUP_READ)

The execution result of the command is: install the icons directory to share/myproj, and install the contents of scripts/ to share/myproj. Neither directory contains a subdirectory named CVS. The specified permissions for the scripts/* files are OWNER_EXECUTE, OWNER_WRITE, OWNER_READ, GROUP_EXECUTE, GROUP_READ.

Running the script during installation

Sometimes you need to print some statements or execute some cmake instructions during the installation process:

install([[SCRIPT <file>] [CODE <code>]]
[COMPONENT <component>] [EXCLUDE_FROM_ALL] [...])

The SCRIPT parameter will be called during the installation process givenCMake script file(i.e. .cmake script file), if the script file name is a relative path, it will be interpreted relative to the current source directory. The CODE parameter will call the given CMake code during installation. Specify the code as a single parameter within a double-quoted string.
For example:

install(CODE "MESSAGE(\"Sample install message.\")")

The command will execute the cmake code and print statements during the installation process.

cmake -dcmake_install_prefix=/usr

Specify the installation path as /usr

The installation path prefix specifies:

The install directory is /usr/local. If you want to change the install directory, there are three ways.

Specify when command line cmake

    cmake  -DCMAKE_INSTALL_PREFIX = /usr/local/

set command specifies

    set(CMAKE_INSTALL_PREFIX ${CMAKE_BINARY_DIR})