What is the intended use case of the install command line option?

What is the intended use case of the cmake --install command line option (or the older install target)?

I am wondering because it seems extremely cumbersome and hard to customize compared to CPack. The documentation states: CMake provides a command-line signature to install an already-generated project binary tree

I interpreted this to mean: Installing a project or library, from the command line, for power users/developers. So that without needed a package I can simply clone, build, and install a program/library.

If this is close to the intended use case, it seems like I should be able to operate on the COMPONENTS property as a variable and in similar ways as I can within CPack with cpack_add_component() and cpack_add_component_group().

I love the ability to have hierarchical projects in CMake, with many layers of depth. But now that I am trying to make a top level library/project installable all those libraries are adding components to my top level install ALL command. CPack allows me to filter and group the components (I am assuming all install commands create nice component names), but cmake --install becomes almost useless (IMO).

Which version of CMake are you using?
From the doc: https://cmake.org/cmake/help/v3.16/manual/cmake.1.html#install-a-project
it seems you can already specify the component you want to install on the commande line?

Did you try to launch: cmake --install without any option in order to display help?

cmake --install is intended to replace make install/ninja install while letting you do more advanced things like installing certain components or configurations (in the case of a multi-config generator like Visual Studio or the new multi-config Ninja generator.)

I am aware of the different options available for the install option currently. I am asking what it’s intended purpose is because it seems unusable for the use case I imagine, and I assume that I am wrong. I guess I am feeling out a feature request here.

consider my current application. I have a hierarchical project structure like this:


I am assuming here that all sub-projects are nice and assign their install components as dev/runtime. Red projects are implementation details while green projects contribute to the public interface of MyLib. In my actual project there are a few more layers but LibC is something like microsoft-gsl and thier gsl::span is in the interface of MyLib. LibD is a wonky internal library that nobody would ever want to install into their system but is required for the internal workings of this larger library.

Given this project if I run cmake --install . then ALL 10 components are installed to the system. In reality a developer would only want
cmake --install . --component MyLib_dev --component MyLib_runtime --component libC_dev --component libC_runtime
(can we even have multiple component commands?)

Now consider if MyLib is actually MyApp and LibA is a shared library (forgive me for not redrawing). Then what we actually want to install is cmake --install . --component MyApp_runtime --component libA_runtime

This makes the cmake --install command hard to use correctly, and easy to use incorrectly. It seems like a useful feature would be commands similar to the cpack commands but for wrangling components for the install command. consider cpack_add_component() and it’s ability to add dependencies to a component. Consider the following hypothetical commands, where I am really just stealing CPack syntax

        DEPENDS MyLib_runtime libC_dev
        INSTALL_TYPES developer

then simply running cmake --install . --component developer or maybe `cmake --install . --type developer’.

Install components are not equivalent to targets. Install components are defined using the COMPONENT keyword of the install command.

Instead of the hypothetical commands, you can use the following existing one:

  COMPONENT developer
  EXCLUDE_FROM_ALL  # excluded from a full installation

All the names listed in the diagram are install components, and so can not be grouped by listing them in an install( TARGETS .. ) command.

Each cmake project/folder creates it’s install components. But then the “top” cmake file is stuck with those decisions?

Targets compose very nicely with PUBLIC, PRIVATE, and INTERFACE properties. CPack allows us group, hide, and create dependencies between components. The install command seems very underdeveloped in comparison. As a library/application author I want more control over the install experience of people downloading my library/application. I want to make it as simple and straightforward as possible for people to consume and install my project.

Unless I am not understanding the purpose of cmake --install . ?