311 lines
8.8 KiB
TeX
311 lines
8.8 KiB
TeX
\subsection{The CMake processing steps}
|
||
|
||
% --------------------------------------------------------------------
|
||
|
||
\begin{frame}[containsverbatim]
|
||
\frametitle{Projects and targets}
|
||
|
||
\begin{center}
|
||
\huge Defining what to build
|
||
\end{center}
|
||
\end{frame}
|
||
|
||
% --------------------------------------------------------------------
|
||
|
||
\begin{frame}[containsverbatim]
|
||
\frametitle{The CMake Process}
|
||
|
||
\begin{columns}
|
||
\begin{column}{0.425\textwidth}
|
||
CMake has two main steps:
|
||
\begin{itemize}
|
||
\item Configure step.
|
||
\item Generate step.
|
||
\end{itemize}
|
||
\end{column}
|
||
|
||
\begin{column}{0.575\textwidth}
|
||
\begin{figure}
|
||
\centering
|
||
\includegraphics[width=.8\textwidth,keepaspectratio]{images/cmake-simple-flowchart.png}
|
||
\caption*{\tiny 2017 © Jeff Preshing \url{http://preshing.com/20170511/how-to-build-a-cmake-based-project/}}
|
||
\end{figure}
|
||
\end{column}
|
||
\end{columns}
|
||
\end{frame}
|
||
|
||
% --------------------------------------------------------------------
|
||
|
||
\begin{frame}[containsverbatim]
|
||
\frametitle{$1^{st}$ step - Configuration}
|
||
|
||
In the \emph{configure} step CMake processes all the input given to
|
||
it, via \texttt{CMakeLists.txt}, and creates an internal
|
||
representation of the build to be performed. \texttt{CMakeCache.txt}
|
||
is generated at this step.
|
||
|
||
\vspace{1em}
|
||
|
||
The end of this step is expressed by \texttt{"Configuring done"}
|
||
message from CMake.
|
||
\end{frame}
|
||
|
||
% --------------------------------------------------------------------
|
||
|
||
\begin{frame}[containsverbatim]
|
||
\frametitle{$2^{nd}$ step - Generation}
|
||
|
||
In the \emph{generate} step CMake will produce native build tool
|
||
files e.g. Visual Studio solution files, XCode project files, Ninja
|
||
build files etc.
|
||
|
||
\vspace{1em}
|
||
|
||
The end of this step is expressed by \texttt{"Generating done"}
|
||
message from CMake.
|
||
\end{frame}
|
||
|
||
% --------------------------------------------------------------------
|
||
|
||
\subsection{About targets}
|
||
|
||
\begin{frame}
|
||
\frametitle{Targets and dependency propagation}
|
||
|
||
\begin{center}
|
||
\huge Targets and their dependencies
|
||
\end{center}
|
||
\end{frame}
|
||
|
||
% --------------------------------------------------------------------
|
||
|
||
\begin{frame}[containsverbatim]
|
||
\frametitle{Targets}
|
||
|
||
A CMake-based buildsystem is organized as a set of high-level
|
||
logical \emph{targets}.
|
||
|
||
\vspace{1em}
|
||
|
||
Each target either corresponds to an executable or library, or is a custom
|
||
target containing custom commands.
|
||
|
||
\vspace{1em}
|
||
|
||
\begin{codebox}{CMake}{}
|
||
add_library(archive archive.cpp zip.cpp lzma.cpp)
|
||
add_executable(zipapp zipapp.cpp)
|
||
target_link_libraries(zipapp archive)
|
||
\end{codebox}
|
||
|
||
\end{frame}
|
||
|
||
% --------------------------------------------------------------------
|
||
|
||
\begin{frame}[containsverbatim]
|
||
\frametitle{Custom Target and Dependencies}
|
||
|
||
Example with custom targets:
|
||
|
||
\vspace{1em}
|
||
|
||
\begin{codebox}{CMake}{}
|
||
add_custom_command(OUTPUT output.file
|
||
COMMAND generator
|
||
--in ${CMAKE_CURRENT_SOURCE_DIR}/input.file
|
||
--out output.file
|
||
DEPENDS input.file
|
||
COMMENT "This is an example invocation of a generator"
|
||
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
|
||
|
||
add_custom_target(my-target
|
||
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/output.file)
|
||
\end{codebox}
|
||
\end{frame}
|
||
|
||
\begin{frame}[containsverbatim]
|
||
\frametitle{Transitive Usage Requirements}
|
||
|
||
The usage requirements of a target can transitively propagate to
|
||
dependents.
|
||
|
||
\vspace{1em}
|
||
|
||
The {\code{target\_link\_libraries()}} command has
|
||
\texttt{PRIVATE}, \texttt{INTERFACE}, and \texttt{PUBLIC} keywords
|
||
to control the propagation.
|
||
\end{frame}
|
||
|
||
% --------------------------------------------------------------------
|
||
|
||
\begin{frame}[containsverbatim]
|
||
\frametitle{Transitive Usage Requirements}
|
||
|
||
A dependency should be specified in a use of
|
||
{\code{target\_link\_libraries()}} with the:
|
||
|
||
\begin{itemize}
|
||
\item \texttt{PRIVATE} keyword, if it is used \emph{only} by the
|
||
implementation of a library, and not in its public header files.
|
||
\item \texttt{PUBLIC} keyword, if a dependency is additionally
|
||
used in the header files of a library (e.g. any header
|
||
inclusion).
|
||
\item \texttt{INTERFACE} keyword, if is \emph{not} used by the
|
||
implementation of a library, but only by its public header
|
||
files.
|
||
\end{itemize}
|
||
\end{frame}
|
||
|
||
% --------------------------------------------------------------------
|
||
|
||
\begin{frame}[containsverbatim]
|
||
\frametitle{Transitive Usage Requirements – Example}
|
||
|
||
\begin{codebox}{CMake}{}
|
||
add_library(liba a.cpp)
|
||
target_compile_definitions(liba INTERFACE USING_LIB_A)
|
||
|
||
add_library(libb b.cpp)
|
||
target_compile_definitions(libb INTERFACE USING_LIB_B)
|
||
|
||
add_library(libc c.cpp)
|
||
target_link_libraries(libc PUBLIC liba PRIVATE libb)
|
||
# libc is compiled with -DUSING_LIB_A and -DUSING_LIB_B
|
||
|
||
add_executable(app main.cpp)
|
||
target_link_libraries(app libc)
|
||
# app is compiled with -DUSING_LIB_A
|
||
\end{codebox}
|
||
\end{frame}
|
||
|
||
% --------------------------------------------------------------------
|
||
|
||
\begin{frame}[containsverbatim]
|
||
\frametitle{Targets – Modifier functions}
|
||
|
||
You should use the following functions to control your targets:
|
||
|
||
\begin{itemize}
|
||
\item {\code{target\_include\_directories()}} – adds directories to
|
||
the include search path.
|
||
\item {\code{target\_compile\_definitions()}} – adds pre-processor
|
||
definitions.
|
||
\item {\code{target\_compile\_options()}} – adds compiler options
|
||
(\texttt{-Wall, /bigobj}).
|
||
\item {\code{target\_compile\_features()}} – adds necessary compiler
|
||
features (\texttt{cxx\_constexpr, cxx\_variadic\_templates}).
|
||
\item {\code{target\_sources()}} – adds more source files to the
|
||
target.
|
||
\item {\code{target\_link\_libraries()}} – add library dependency.
|
||
\end{itemize}
|
||
\end{frame}
|
||
|
||
% --------------------------------------------------------------------
|
||
|
||
\subsection{Preparing for packaging}
|
||
|
||
\begin{frame}
|
||
\frametitle{Locating packages}
|
||
|
||
\begin{center}
|
||
\huge Preparing the project for packaging
|
||
\end{center}
|
||
\end{frame}
|
||
|
||
% --------------------------------------------------------------------
|
||
|
||
\begin{frame}[containsverbatim]
|
||
\frametitle{CMake packages}
|
||
Packages provide dependency information to CMake.
|
||
|
||
\vspace{1em}
|
||
|
||
Packages are found with the {\code{find\_package()}} command.
|
||
|
||
\vspace{1em}
|
||
|
||
The result of using {\code{find\_package()}} is either a set of
|
||
\texttt{IMPORTED} targets, or a set of variables
|
||
e.g. \texttt{<package>\_FOUND}, \texttt{<package>\_INCLUDE\_DIRS},
|
||
\texttt{<package>\_LIBRARIES}.
|
||
\end{frame}
|
||
|
||
% --------------------------------------------------------------------
|
||
|
||
\begin{frame}[containsverbatim]
|
||
\frametitle{Packages – Example}
|
||
CMake provides direct support for two forms of packages:
|
||
\begin{itemize}
|
||
\item \texttt{CONFIG}-file packages (the new way).
|
||
\item Find-\texttt{MODULE} packages (prioritized for backwards-compat).
|
||
\end{itemize}
|
||
|
||
\begin{codebox}{CMake}{}
|
||
# CMake provides a Boost find-module
|
||
find_package(Boost 1.60.0 MODULE REQUIRED)
|
||
|
||
# Qt Project provides a Qt5 package config file.
|
||
find_package(Qt5Core 5.9.0 CONFIG REQUIRED
|
||
COMPONENTS Widgets)
|
||
|
||
# Use pkg-config via the LibXml2 find-module
|
||
find_package(LibXml2 MODULE REQUIRED)
|
||
\end{codebox}
|
||
\end{frame}
|
||
|
||
% --------------------------------------------------------------------
|
||
|
||
\begin{frame}[containsverbatim]
|
||
\frametitle{Packages – Config-file}
|
||
|
||
A config-file package the recommended CMake package type.
|
||
|
||
\vspace{1em}
|
||
|
||
The config-file package consists of a set of files provided by
|
||
upstreams for downstreams to use.
|
||
|
||
\vspace{1em}
|
||
|
||
The Qt Project doesn't use CMake as their own build system, but
|
||
they do provide a config-file package for CMake users.
|
||
\end{frame}
|
||
|
||
% --------------------------------------------------------------------
|
||
|
||
\begin{frame}[containsverbatim]
|
||
\frametitle{Packages -- Find-module}
|
||
|
||
A find-module is needed when the upstream is not built with CMake,
|
||
or is not CMake-aware enough to otherwise provide a package
|
||
configuration file.
|
||
|
||
\vspace{1em}
|
||
|
||
The find-module is a file with a set of rules for finding the
|
||
required pieces of a dependency, primarily header files and
|
||
libraries e.g. \texttt{FindBoost.cmake}.
|
||
\end{frame}
|
||
|
||
% --------------------------------------------------------------------
|
||
|
||
\begin{frame}[containsverbatim]
|
||
\frametitle{Packages – Config-file continued}
|
||
|
||
A config-file package can be used in two ways:
|
||
\begin{itemize}
|
||
\item to find a configured project that is already part of the
|
||
build.
|
||
\item to import an installed package.
|
||
\end{itemize}
|
||
|
||
\vspace{1em}
|
||
|
||
The process of creating a config-file package using CMake commands
|
||
({\code{configure\_package\_config\_file()}},
|
||
{\code{write\_basic\_package\_version\_file()}}, {\code{install()}},
|
||
{\code{export()}}) is quite verbose, and error prone.
|
||
\end{frame}
|
||
|
||
% --------------------------------------------------------------------
|