What install command does in cmake?

Question

I couldn't understand the CMake documentation for install. I have a sample cmake file, where an executable is generated by

add_executable(${PROJECT_NAME}_node src/filename.cpp)

Then later installed by the following command

install(TARGETS ${PROJECT_NAME}_node ${PROJECT_NAME}   
ARCHIVE DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION}   
LIBRARY DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION}   
RUNTIME DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION} )

This CMake is from ROS so catkin is there. The overall question remains the same. Does someone know, why do we need to install TARGETS/ FILES?

Grisaille

How else would you use them? – Archon

add_executable() command already created executable. I can just run it simply. – Grisaille

install does what it kind of implies, in which it will install whatever targets you specify (in this case ${PROJECT_NAME}_node and ${PROJECT_NAME} to the destinations you've specified for each target configuration (ARCHIVE, LIBRARY, and RUNTIME). – Steffens

@Steffens Install as I understand, just copies build files from specific place to a place where it could be accessible to other application. am I right ? – Grisaille

It will put executable files, libraries, config files, and resource files in the expected places where your code should be looking for them. if your code runs in the build directory, then that's likely a bug. – Archon

To put it in English: Let's say your project has a prefix: C:/MyProject - Inside your project you have your source files and respective CMakeLists.txt file under C:/MyProject/src. When you specify your install() command like above, it will basically move everything you need to run your application into their respective folders where your executable expects them to be. For example, your .exe and .dll's will go into your C:/MyProjects/bin folder. .libs go installed in the C:/MyProjects/lib folder, etc. You specify that destination after the keyword DESTINATION. – Steffens

It's purpose is to separate all of the files to run your application into a directory structure of everything it actually needs in order to run. For example, if you were planning to give someone a copy of your application, you don't want them to have a copy of your build folder -- Because that has a ton of files that the end-user does not need to run the application (and in some cases could allow your program to be debugged by others -- which you don't want). – Steffens

thanks a lot @Steffens I understood now. – Grisaille

Answer 1

You don't need to use the INSTALL function of catkin.

INSTALL function will just copy your final BINARY,LIBRARY,etc to a safer place (ex. main ros package space located at /opt/ros/<your-version>/share,lib,include) to keep the build workspace less crowded and to keep files safe in case your workspace got corrupted.

Monarchy

Answer 2

You have to think of your folder structures as an "Interface". Then there's three interfaces:

1. source interface
2. build interface
3. install interface

Each interface has a different folder structure with different files in it. The install interface is just the folder structure you get by installing with cmake. Essentially, it takes all your relevant files lying around in your build folder and creates a nice folder structure which other projects can use.

Typically, in an out-of-source build (what is best practice), your source interface will be a subfolder of your project root, e.g. src or source. You then typically configure, generate and build your lib to a directory build which lives right next to src so that your project structure looks like this:

source and build interfaces:

project_root
├── CMakeLists.txt
├── src
│   └── CMakeLists.txt
├── build
│   └── CMakeCache.txt
...

So that covers the source and build interfaces. But what about the install interface? Answer: The install interface goes wherever the user wants it to go to. The location is specified by CMAKE_INSTALL_PREFIX. You can override it by specifying the --prefix argument

cmake --install . --prefix "/where/I/want/it/to/go"

This would create the install interface according to the install()-rules you declared in your CMakeLists.txt. For example if using a default layout using GNUInstallDirs (highly recommended even for windows), this would create a folder structure under /where/I/want/it/to/go/project_root like so:

install interface:

project_root
├── bin
│   └── executables
├── sbin
│   └── sysadmin executables
├── lib
│   ├── compiled libraries (*.so (unix) or *.dll (windows))
│   └── library archive files (*.lib (windows))
├── libexec
│   └── executables not directly invoked by user
├── include
│   └── header files
├── doc
│   └── documentation

You can see that almost all of the nonsense that we used for developing has vanished and we're left with a pure directory that contains mostly precompiled stuff that other apps can use. You would use the install interface of a project B if your project depends on B and you know that it's going to be installed on windows or linux platforms. The install interface is typically not of much use when developing for embedded systems that only run minimal operating systems or none at all, in this case you would build your whole app using the source interface of project B by including it in your project and add it using add_subdirectory()

Haskins

Very good explaination! Thank you – Paralyse

Answer 3

INSTALL is useful in, at least, two scenarios:

• You download some package's source code, generate the binaries, which you want to use in your system. You can INSTALL them under /usr/bin, for example

• You compile some library which you'll use from another product. It will gather the required files (header files, libraries...), and just those, and put them in a known place, no matter where the library compilation expects them.

You could just copy them, but relying on CMake allows the process to be expressed at a higher level.

Purveyance

Answer 4

It simply installs built binaries on the local system.

---

If a tool like bash or git has to be installed from sources (e.g. to use its latest version), build it then install it to use.

Building and installing from sources (from private build directory into public system directory) is a normal way if local system does not have required tool, or its package does not exists, or the packaged version is old, or some customization is needed.

Peccant