.\" 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-USING" "7" "Oct 29, 2021" "0.13." "YCM" .SH NAME ycm-using \- Using YCM in your project .SH HOW TO USE YCM IN YOUR PROJECT .sp In order to use YCM in your project, your software will have to depend on CMake 3.12 or later. Therefore your \fBCMakeLists.txt\fP file should include a \fBcmake_minimum_required()\fP call to set the \fBCMAKE_MINIMUM_REQUIRED_VERSION\fP and the relative CMake policies. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cmake_minimum_required(VERSION 3.12) .ft P .fi .UNINDENT .UNINDENT .sp Now you have to set variables that control which components are enabled (all the following variables should be set before calling \fBfind_package(YCM)\fP, it is not possible to change their value later): .sp By default, YCM makes available some modules from CMake, that received bugfix, enhancement, or simply are not available in all the supported versions. If you want you can disable this behaviour by setting the :variable\(gaYCM_USE_CMAKE_\(ga and \fBYCM_USE_CMAKE_NEXT\fP variables to \fBOFF\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # set(YCM_USE_CMAKE_3_13 OFF) # Disable modules from CMake 3.13 # set(YCM_USE_CMAKE_3_14 OFF) # Disable modules from CMake 3.14 # set(YCM_USE_CMAKE_3_15 OFF) # Disable modules from CMake 3.15 # set(YCM_USE_CMAKE_NEXT OFF) # Disable modules from CMake git repository .ft P .fi .UNINDENT .UNINDENT .sp These options, are turned on by default, but they can be turned off if they are not needed. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fBYCM_USE_CMAKE_\fP, \fBYCM_USE_CMAKE_NEXT\fP\&. .UNINDENT .UNINDENT .sp YCM contains also some CMake modules with unmerged patches. These are turned off by default, but can be enabled using the \fBYCM_USE_CMAKE_PROPOSED\fP variable. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C set(YCM_USE_CMAKE_PROPOSED ON) # Enables unmerged patches to CMake modules .ft P .fi .UNINDENT .UNINDENT .sp These options, is turned on by default, but it can be turned off if needed. At the moment, it is recommended to turn it on for YCM superbuilds. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fBYCM_USE_CMAKE_PROPOSED\fP\&. .UNINDENT .UNINDENT .sp All the \fBYCM_USE_CMAKE_\fP options can be disabled simultaneously by setting the \fBYCM_USE_CMAKE\fP variable to \fBOFF\fP\&. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fBYCM_USE_CMAKE\fP\&. .UNINDENT .UNINDENT .sp YCM makes available a few 3rd party modules. These modules can have licenses that are not the same as YCM license. If you are using these module, you should check each license to ensure that it is compatible with your code. If you want to disable all 3rd party modules you can set the \fBYCM_USE_3RDPARTY\fP variable to \fBOFF\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # set(YCM_USE_3RDPARTY OFF) # Disable 3rd party modules .ft P .fi .UNINDENT .UNINDENT .sp Also this option is turned on by default, but it can be turned off if it is not needed. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fBYCM_USE_3RDPARTY\fP .UNINDENT .UNINDENT .sp Finally, YCM makes available a few modules that are considered deprecated. \fBYCM_USE_DEPRECATED\fP variable. Please note that these modules are deprecated for a reason, therefore they are not supported, might contain bugs, and could be removed in future releases. They are still available to support old code, but it is strongly recommended to avoid them in new code. If you want to disable the deprecated modules, you can set the \fBYCM_USE_DEPRECATED\fP to \fBOFF\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # set(YCM_USE_DEPRECATED OFF) # Disable deprecated modules .ft P .fi .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fBYCM_USE_DEPRECATED\fP .UNINDENT .UNINDENT .sp YCM can be both a hard dependency or a soft dependency in your project. In the first case, your package will not build if the YCM package is not installed, in the second case, if it is not installed, it will be downloaded and built during the configure phase of your project. .SS Using YCM as a Hard Dependency .sp In order to make it a hard dependency, you can just use it like any other package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Find YCM find_package(YCM [version] REQUIRED) .ft P .fi .UNINDENT .UNINDENT .sp This is the recommended mode to use it when you just want to use YCM modules, because in this way you will not need a network connection when building the package. .SS Using YCM as Soft Dependency .sp In order to make it a soft dependency, you will need to get the files \fBtools/YCMBootstrap.cmake\fP and \fBmodules/IncludeUrl.cmake\fP from the YCM sources (see \fBycm\-installing(7)\fP for instructions on how to download YCM) and copy them inside your project tree: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd mkdir cmake cp /tools/YCMBootstrap.cmake cmake cp modules/IncludeUrl.cmake cmake .ft P .fi .UNINDENT .UNINDENT .sp These files must be in a folder included in \fBCMAKE_MODULE_PATH\fP for your project: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake") .ft P .fi .UNINDENT .UNINDENT .sp Now you can include \fBYCMBootstrap.cmake\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Uncomment the next line to specify a tag or a version. # set(YCM_TAG [tag, branch, or commit hash]) # Bootstrap YCM include(YCMBootstrap) .ft P .fi .UNINDENT .UNINDENT .sp This is the suggested method when you build a superbuild. Downloading all your project would require a network connection anyway, therefore you will need to install. .sp In both cases, you can use YCM modules right after this declaration. .SH COPYRIGHT Copyright 2012-2021 Istituto Italiano di Tecnologia (IIT) .\" Generated by docutils manpage writer. .