[CMake] Explanation of the CMake INSTALL and EXPORT Commands

[Matthew Woehlke]

On 2013-04-03 16:16, Saad Khattak wrote:
> I am having a hard time understanding some commands in CMake which by the
> looks of it are vital for proper project deployment. One of the commands is
> INSTALL and the other is EXPORT.

There are two forms of EXPORT, and I am not certain which one you are 
referring to. There is the command EXPORT, and there is the EXPORT named 
argument to the INSTALL command. They are similar in that they both deal 
with generating target export files, but the command version is used to 
generate such for build trees, while the named argument version applies 
to install trees.

If you never use your software downstream from a build directory, you 
can safely ignore the command version.

> 1) Why do I need to install my library/executable? When I build my
> libraries and they are put in their library output paths, what is the point
> of INSTALL?

INSTALL is used to implement 'make install' (or equivalent), and also 
packaging. If you are only ever using your software from a source build, 
you can probably ignore it. If you ever want to deploy your software, 
however, I would strongly encourage having an install process.

Installing makes a software package generally available to users of the 
system, by installing its components into a well-known prefix (e.g. 
/usr, /usr/local, /opt/MySoft). It is often much more convenient to use 
an installed software package rather than stuff in a build directory, as 
installed binaries tend to be in e.g. PATH, whereas build directories 
may not be readable by all users.

Please don't teach your build to write its build objects directly into 
e.g. /usr/local/bin :-).

> 2) Once I do install targets and/or programs, are they available to other
> projects that are not in the same CMakeLists build?

Yes. They are available just from build directories also, but you will 
need to manually tell CMake where to find build directories. (Per above, 
installed packages can be found automatically if they are installed to 
standard (well known) locations... keeping in mind that you can choose 
to install to any location you like, e.g. in your home directory.)

(If you are using exported targets - and you should - then you will need 
to use the EXPORT command to create a build-directory exported targets 
file. Getting this right is a little more complicated than install 
exports, but saves needing to install the package every time your 
downstream needs an updated version.)

> 3) Suppose I have 2 completely separate projects (i.e. they have completely
> separate CMakeLists that are not 'talking' to each other) - Project A
> builds some libraries which Project B now needs to use. Does Project A
> 'install' the libraries and are now those libraries are available system
> wide?

If Project A is installed (to a standard location), then it is available 
system wide, yes. However you should still use find_package(A) rather 
than relying on e.g. target_link_libraries(B A) so that your build will 
work for users that do not have A in a standard location.

If A is built by CMake, your install should generate exports so that 
users of A do not need a find module. (Also, then you *can* - and should 
- do target_link_libraries(B A), because 'A' will be an imported target, 
i.e. will 'look like' it was build as part of B.)

> 4) Project A can build 32 bit and 64 bit libraries. How does INSTALL (or
> EXPORT? Like I said earlier, I am very confused here...) know which library
> it is 'installing'? And then how does Project B 32 bit know to link with
> Project A 32 bit libraries and same with 64-bit?

Hmm... I'm not all that familiar with multi-arch bits, but I *think* how 
this is supposed to work is that when B does find_package(A), it will 
look in either lib or lib64 depending on whether or not it is being 
built in 64-bit mode. So as long as your find_package picks the right 
AConfig.cmake, all will be well (it should by default if A is installed 
to a standard location, and/or if necessary you can force where to find 
its config).

Generally speaking, you should either have two separate builds of A in 
32- and 64-bit mode that can be installed in parallel, or else A should 
produce 32- and 64-bit libraries with different names. (I would 
recommend the former, since that is how most software works and is less 
likely to give you headaches getting it to work. Also because getting 
CMake to build both 32- and 64-bit binaries in the same build is going 
to be harder than just having separate 32- and 64-bit builds.)

Hope that helps.

-- 
Matthew