.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "YCM-BUILD-SYSTEM-SUPPORT" "7" "Nov 05, 2023" "0.13." "YCM"
.SH NAME
ycm-build-system-support \- YCM Build System Support
.SH YCM BUILD SYSTEM SUPPORT
.sp
YCM offers a few macros and Find scripts that can be used in your build system.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fI\%Generic Modules\fP that add functionalities to CMake that might
be useful in your project.
.IP \(bu 2
\fI\%Find Package Modules\fP, that help in finding software on the
system.
.IP \(bu 2
\fI\%Packaging Helper Modules\fP, that are useful to simplify the
generation of a package that can be used by other packages.
.IP \(bu 2
Support for new CMake features in older CMake versions.
.IP \(bu 2
Support for new features in CMake before these are actually
released.
.IP \(bu 2
Support for 3rd party CMake modules.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
You can find for using YCM in your project in \fI\%ycm\-using(7)\fP\&.
.UNINDENT
.UNINDENT
.sp
YCM also offers functionalities to make a superbuild. Documentation for this can
be found elsewhere.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fI\%YCM Superbuild\fP
.UNINDENT
.UNINDENT
.SH A PRACTICAL EXAMPLE
.sp
Suppose you have created a package that contains a library, called
\fBTemplatePkg\fP\&. You want to package this library, providing versioning,
installation rules for header as well as binary files and cmake files for
finding and using the library within other projects.
.sp
This is the code you need to add to your CMakeLists.txt:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
cmake_minimum_required(VERSION 3.12)
project(TemplatePkg
        LANGUAGES CXX
        VERSION 0.0.1)

include(GNUInstallDirs)

# Set the output dir for binaries
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_INSTALL_BINDIR})
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR})
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR})

# find and use YCM
find_package(YCM REQUIRED)

# Set a few
set(${PROJECT_NAME}_BUILD_LIBDIR ${CMAKE_INSTALL_LIBDIR})
set(${PROJECT_NAME}_BUILD_BINDIR ${CMAKE_INSTALL_BINDIR})
set(${PROJECT_NAME}_BUILD_INCLUDEDIR ${CMAKE_SOURCE_DIR}/src)

set(${PROJECT_NAME}_INSTALL_LIBDIR ${CMAKE_INSTALL_LIBDIR})
set(${PROJECT_NAME}_INSTALL_BINDIR ${CMAKE_INSTALL_BINDIR})
set(${PROJECT_NAME}_INSTALL_INCLUDEDIR ${CMAKE_INSTALL_INCLUDEDIR})

# add sources
add_subdirectory(src)
.EE
.UNINDENT
.UNINDENT
.sp
So far nothing special. We have declared our library, added source codes and
included YCM.
.sp
We now need to instruct CMake to install the library and generate \fBCMake\fP
(\fBFindTemplatePkg.cmake\fP) have also been generated so that \fBTemplatePkg\fP can
be found using \fBCMake\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# include macro for installing packaging files and invoke it
include(InstallBasicPackageFiles)
install_basic_package_files(TemplatePkg
                            VARS_PREFIX ${PROJECT_NAME}
                            VERSION ${${PROJECT_NAME}_VERSION}
                            COMPATIBILITY SameMajorVersion
                            NO_CHECK_REQUIRED_COMPONENTS_MACRO)
.EE
.UNINDENT
.UNINDENT
.sp
This function generates all the configuration files required for other packages
to locate and use the library compiled by \fBTemplatePkg\fP and adds the required
installation rules for these files.
.sp
Finally we add uninstall rules:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
include(AddUninstallTarget)
.EE
.UNINDENT
.UNINDENT
.sp
Now you can compile the package by simply doing:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
mkdir build
cd build
cmake ..
make
make install
.EE
.UNINDENT
.UNINDENT
.sp
This will install your package using \fB/usr/local/\fP as installation prefix.
You can change the prefix by changing the
\fBCMAKE_INSTALL_PREFIX\fP variable, for
example
.INDENT 0.0
.INDENT 3.5
.sp
.EX
cmake \-DCMAKE_INSTALL_PREFIX:PATH=/opt/ycm ..
.EE
.UNINDENT
.UNINDENT
.sp
If you check inside the build directory or \fB<prefix>/lib\fP you should see that
\fBmake install\fP has built the project and installed header files and the
library correctly. The file \fBTemplatePkgConfig.cmake\fP should be in
\fB<prefix>/lib/cmake/TemplatePkg/\fP\&.
This file will be found by other packages when they call:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
find_package(TemplatePkg)
.EE
.UNINDENT
.UNINDENT
.sp
Example code can be downloaded from \fI\%TemplatePkg\fP repository.
.SH COPYRIGHT
Copyright 2012-2021 Istituto Italiano di Tecnologia (IIT)
.\" Generated by docutils manpage writer.
.