77 lines
3.9 KiB
Markdown
77 lines
3.9 KiB
Markdown
# Installing
|
|
|
|
Install commands cause a file or target to be "installed" into the install tree when you `make install`. Your basic target install command looks like this:
|
|
|
|
```cmake
|
|
install(TARGETS MyLib
|
|
EXPORT MyLibTargets
|
|
LIBRARY DESTINATION lib
|
|
ARCHIVE DESTINATION lib
|
|
RUNTIME DESTINATION bin
|
|
INCLUDES DESTINATION include
|
|
)
|
|
```
|
|
|
|
The various destinations are only needed if you have a library, static library, or program to install. The includes destination is special; since a target does not install includes. It only sets the includes destination on the exported target (which is often already set by `target_include_directories`, so check the MyLibTargets file and make sure you don't have the include directory included twice if you want clean cmake files).
|
|
|
|
It's usually a good idea to give CMake access to the version, so that `find_package` can have a version specified. That looks like this:
|
|
|
|
```cmake
|
|
include(CMakePackageConfigHelpers)
|
|
write_basic_package_version_file(
|
|
MyLibConfigVersion.cmake
|
|
VERSION ${PACKAGE_VERSION}
|
|
COMPATIBILITY AnyNewerVersion
|
|
)
|
|
```
|
|
|
|
You have two choices next. You need to make a `MyLibConfig.cmake`, but you can do it either by exporting your targets directly to it, or by writing it by hand, then including the targets file. The later option is what you'll need if you have any dependencies, even just OpenMP, so I'll illustrate that method.
|
|
|
|
First, make an install targets file (very similar to the one you made in the build directory):
|
|
|
|
```cmake
|
|
install(EXPORT MyLibTargets
|
|
FILE MyLibTargets.cmake
|
|
NAMESPACE MyLib::
|
|
DESTINATION lib/cmake/MyLib
|
|
)
|
|
```
|
|
|
|
This file will take the targets you exported and put them in a file. If you have no dependencies, just use `MyLibConfig.cmake` instead of `MyLibTargets.cmake` here. Then write a custom `MyLibConfig.cmake` file in your source tree somewhere. If you want to capture configure time variables, you can use a `.in` file, and you will want to use the `@var@` syntax. The contents that look like this:
|
|
|
|
```cmake
|
|
include(CMakeFindDependencyMacro)
|
|
|
|
# Capturing values from configure (optional)
|
|
set(my-config-var @my-config-var@)
|
|
|
|
# Same syntax as find_package
|
|
find_dependency(MYDEP REQUIRED)
|
|
|
|
# Any extra setup
|
|
|
|
# Add the targets file
|
|
include("${CMAKE_CURRENT_LIST_DIR}/MyLibTargets.cmake")
|
|
```
|
|
|
|
Now, you can use configure file (if you used a `.in` file) and then install the resulting file.
|
|
Since we've made a `ConfigVersion` file, this is a good place to install it too.
|
|
|
|
```cmake
|
|
configure_file(MyLibConfig.cmake.in MyLibConfig.cmake @ONLY)
|
|
install(FILES "${CMAKE_CURRENT_BINARY_DIR}/MyLibConfig.cmake"
|
|
"${CMAKE_CURRENT_BINARY_DIR}/MyLibConfigVersion.cmake"
|
|
DESTINATION lib/cmake/MyLib
|
|
)
|
|
```
|
|
|
|
That's it! Now once you install a package, there will be files in `lib/cmake/MyLib` that CMake will search for (specifically, `MyLibConfig.cmake` and `MyLibConfigVersion.cmake`), and the targets file that config uses should be there as well.
|
|
|
|
When CMake searches for a package, it will look in the current install prefix and several standard places. You can also add this to your search path manually, including `MyLib_PATH`, and CMake gives the user nice help output if the configure file is not found.
|
|
|
|
The [CMakePackageConfigHelpers](https://cmake.org/cmake/help/latest/module/CMakePackageConfigHelpers.html) module mentioned above has additional tools to help write a more relocatable `Config.cmake` file.
|
|
Refer to the CMake documentation on [configure_package_config_file](https://cmake.org/cmake/help/latest/module/CMakePackageConfigHelpers.html#command:configure_package_config_file) (used instead of `configure_file`) and the `@PACKAGE_INIT@` substitution string to get
|
|
|
|
- a set of automatically defined `PACKAGE_<var>` variables (for relative path versions of `<var>`) and
|
|
- a `set_and_check()` alternative to `set()` to automatically check for path existence.
|