JKQtPlotter/doc/dox/buildinstructions_cmake.dox

/*!


\page page_buildinstructions_CMAKE Build using CMake

\tableofcontents

\section page_buildinstructions_CMAKE_RUN Running a Build with CMake

The preferred way to build JKQTPlotter is using <a href="https://cmake.org/">CMake</a> (at least using version 3.23). You can find a detailed explanation of CMake at https://cliutils.gitlab.io/modern-cmake/. The CMake-build is defined in `CMakeLists.txt` files, found in many of the directories of the code repository. Especially in the root directory and the two subdirectories <code> ./lib/  </code> and <code> ./examples/  </code> .

You can build JKQTPlotter (and also the examples) by either opening the file <a href="https://github.com/jkriege2/JKQtPlotter/blob/master/CMakeLists.txt">CMakeLists.txt</a> in QTCreator (which has CMake integration), or by calling \c CMake by hand. How to do this depends on your local system und build environment. 


\subsection page_buildinstructions_CMAKE_MAKEFILE Generic Configuring&Building 

The first step is to configure the bild,using: 

\code{.sh}
    $ mkdir build
    $ cd build
    $ cmake -G "<GENERATOR>" "-DCMAKE_PREFIX_PATH=<path_to_your_qt_sources>" "-DCMAKE_BUILD_TYPE=Debug" ..
\endcode
This configures the CMake build. The Parameter \c <GENERATOR> tells CMake, which build-file generator  to use (e.g. use <code>MinGW Makefiles</code> for MinGW Makefiles on Windows or <code>Unix Makefiles</code> on Unix, see <a href="https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html">https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html</a> for a list of available generators). For single-configuration generators (e.g. <code>Unix Makefiles</code>, ..., as opposed to multi-config, like \c Ninja, \c XCode or <code>Visual Studio</code>) you will have to explicitly set the build type using \c -DCMAKE_BUILD_TYPE=Debug (note, you can choose any other allowed build type instead of \c Debug, as e.g. \c Release or \c RelWithDepInfo ). The parameter \c <path_to_your_qt_sources> should be the path to your Qt installation. You can also add (separated by semicolon) paths to other libraries that JKQTPlotter should use, e.g. <a href="https://cimg.eu/">CImg</a> or <a href="https://cimg.eu/">OpenCV</a>. JKQTPlotter does not have any neccessary dependencies,  apart from Qt5 or 6, but it contains binding code to somme popular 3rd party libraries (as e.g. CImmg or OpenCV). Also see \ref page_buildinstructions_CMAKE_CONFIG  for a listing of additional configuration options for JKQTPlotter. You might e.g. want to set \c CMAKE_INSTALL_PREFIX to a path in which you want to install the build results. This also has to be done at this stage.

Of course you can also perform this step in the <a href="https://cmake.org/cmake/help/latest/manual/cmake-gui.1.html">CMake GUI</a> or <a href="https://cmake.org/cmake/help/latest/manual/ccmake.1.html">ccmake</a>.

Now you can build the library using:
\code{.sh}
    $ cmake --build . --config "Debug"
\endcode
Here we explicitly build the configuration \c Debug ... you can also build other configurations here, as e.g. \c Release . The final build will put all of these side-by-side into the install directory, sou can can generate a multi-configuration installation. When linking to JKQTBuilder, the matching condfiguration´should be selected automatically!

\subsection page_buildinstructions_CMAKE_VSTUDIO Configuring&Building with Visual Studio/MSVC

For Visual Studio / Visual C++ the build looks similar, but you will have to select one of the <a href="https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#id14"><code>Visula Studio ...</code> generators</a>, e.g. :

\code{.sh}
    $ mkdir build
    $ cd build
    $ cmake -G "Visual Studio 16 2019 Win64" "-DCMAKE_PREFIX_PATH=<path_to_your_qt_sources>"  ..
\endcode

Where \c \<path_to_your_qt_sources\> could be e.g. \c C:/Qt/6.5.0/msvc2019_64 . This call results in a Visual Studio solution \c build/JKQTPlotter.sln that you can load and compile from the Visual Studio IDE. Alternatively you can also build the solution directly calling:
\code{.sh}
    $ cmake --build . --config "Debug"
\endcode
Again we explicitly build the configuration \c Debug ... you can also build other configurations here, as e.g. \c Release . The final build will put all of these side-by-side into the install directory, sou can can generate a multi-configuration installation. When linking to JKQTBuilder, the matching condfiguration´should be selected automatically!

\subsection page_buildinstructions_CMAKE_CONFIG Configuring a Build with CMake

The CMake build system offers several configuration variables that you may set/change to modify the outcome of the build (in the examples above, \c CMAKE_PREFIX_PATH is already used, you may set the following options in the same way:
  - \c CMAKE_INSTALL_PREFIX : Install directory for the library
  - \c CMAKE_PREFIX_PATH : add the path to your Qt installatrion to this variable, so the \c find_package(Qt5...) commands find the libraries you want to use
  - \c BUILD_SHARED_LIBS : Build as shared library (default: \c ON ), if this is \c OFF the library will be built as a static library
  - \c JKQtPlotter_BUILD_INCLUDE_XITS_FONTS : Include XITS fonts as resources in library (default: \c ON )
  - \c JKQtPlotter_BUILD_INCLUDE_FIRAMATH_FONTS : Include Fira Math fonts as resources in library (default: \c ON )
  - \c JKQtPlotter_BUILD_FORCE_NO_PRINTER_SUPPORT : switches off print-support (when set to \c ON ), even if the current platform supports it (default: \c OFF )
  - \c JKQtPlotter_BUILD_DECORATE_LIBNAMES_WITH_BUILDTYPE : If set, the build-type is appended to the library name (default: \c ON )
  - \c JKQtPlotter_BUILD_WITH_PRECOMPILED_HEADERS : If set, the build uses precompiled headers to speed up (a bit) (default: \c ON )
  - \c JKQtPlotter_ENABLED_CXX20 : Build using C++20 (requires a compiler that supports this! (default: \c OFF )
  - \c JKQtPlotter_BUILD_WITH_TIMING_INFO_OUTPUT : If enabled (\c ON ), additional tiing code is activated (and built into the library), which outputs timming information for several functions of the library into \c qDebug() . This is intended for development putposes only, NOT for productive builds!  (default: \c OFF )
  - \c JKQtPlotter_BUILD_EXAMPLES : Build examples (default: \c ON )
  - \c JKQtPlotter_BUILD_TOOLS : Build tools (default: \c ON )
  - \c JKQtPlotter_BUILD_TESTS : Build unit-tests (default: \c ON )
  - \c JKQtPlotter_BUILD_LIB_JKQTMATH : Build sub-library JKQTMath (default: \c ON )
  - \c JKQtPlotter_BUILD_LIB_JKQTMATHTEXT : Build sub-library JKQTMathText (default: \c ON )
  - DEPRECATED: \c JKQtPlotter_BUILD_LIB_JKQTFASTPLOTTER : Build sub-library JKQTFastPlotter (default: \c ON ) ... Note: This option may change to default=OFF in future ... and may be removed thereafter!
  - \c JKQtPlotter_BUILD_LIB_JKQTPLOTTER : Build sub-library JKQTPlotter (default: \c ON )
.

\subsection page_buildinstructions_CMAKE_INSTALL Installing with CMake

Finally, after a successful build, you can install the binaries, headers etc. into a directory, given by the CMake option \c CMAKE_INSTALL_PREFIX . Simply run:
\code{.sh}
    $ cmake --build . --config "Debug" --target install
\endcode
or:
\code{.sh}
    $ cmake --install . --config "Debug"
\endcode
in your build directory. Again we explicitly build the configuration \c Debug ... you can also build other configurations here, as e.g. \c Release . The final build will put all of these side-by-side into the install directory, sou can can generate a multi-configuration installation. When linking to JKQTBuilder, the matching condfiguration´should be selected automatically!

You will end up with an install directory that constains subdirectories, such as \c lib/ , \c include/ or \c bin/ . Thesecontain the build results. The next section \ref page_buildinstructions_CMAKE_USAGE describes how to use such an installation to link against JKQTPlotter.


\section page_buildinstructions_CMAKE_USAGE Using a CMake Build

After building and installing JKQTPlotter you have all files that you need inside the instal directory:
  - \c \<CMAKE_INSTALL_PREFIX\>/include  contains all required header files
  - \c \<CMAKE_INSTALL_PREFIX\>/bin  contains the shared libraries, examples, tools
  - \c \<CMAKE_INSTALL_PREFIX\>/lib  contains the link libraries
  - \c \<CMAKE_INSTALL_PREFIX\>/lib/cmake/JKQTPlotterX/  contains files necessary for CMake's \c find_package() to work
.

The build/install above generates several CMake targets that can be used to link against JKQTPlotter (or one of its sub libraries). The generated targets are (note that the Qt-version number appears the target names!!!):
  - \c JKQTPlotter6::JKQTPlotter6 / \c JKQTPlotter5::JKQTPlotter5 : the main plotting library, containing JKQTPlottter and JKQTBasePlotter
  - \c JKQTPlotter6::JKQTMathText6 / \c JKQTPlotter5::JKQTMathText5 : the LaTeX rendering library containing JKQTMathText
  - \c JKQTPlotter6::JKQTCommmon6 / \c JKQTPlotter5::JKQTCommon5 : basic tools and facilities for the other libraries
  - \c JKQTPlotter6::JKQTMath6 / \c JKQTPlotter5::JKQTMath5 : additional mathematical algorithms to be used with JKQTPlotter (e.g. a statistics library with histograming, KDE or regression)
  - DEPRECATED: \c JKQTPlotter6::JKQTFastPlotter6 / \c JKQTPlotter5::JKQTFastPlotter5 : an alternative plotting library with less features, but which is supposed to be fast,conatins JKQTFastPlotter

You can find an example project that uses a complete cmake-build here: \ref JKQTCMakeLinkExample (online: <a href="https://github.com/jkriege2/JKQtPlotter/blob/master/examples/cmake_link_example"><code>examples/cmake_link_example</code></a>).

Here is the \c CMakeLists.txt from that directory:

\code{.cmake}
# set minimum required CMake-Version
cmake_minimum_required(VERSION 3.23)

# set Project name
project(simpletest_cmake LANGUAGES CXX)

# some basic configurations
set(CMAKE_AUTOMOC ON)
set(CMAKE_INCLUDE_CURRENT_DIR ON)

# Configure project for usage of Qt5/Qt6
find_package(QT NAMES Qt6 Qt5 COMPONENTS Core Gui Widgets PrintSupport Svg Xml OpenGl REQUIRED)
find_package(Qt${QT_VERSION_MAJOR} COMPONENTS Core Gui Widgets PrintSupport Svg Xml OpenGL REQUIRED)


# include JKQTPlotter
find_package(JKQTPlotter${QT_VERSION_MAJOR} REQUIRED)

# For Visual Studio, we need to set some additional compiler options
if(MSVC)
    add_compile_options(/EHsc)
    # To enable M_PI, M_E,...
    add_definitions(/D_USE_MATH_DEFINES)
    # To Prevent Errors with min() and max()
    add_definitions(/DNOMINMAX)
    # To fix error: C2338: va_start argument must not
    # have reference type and must not be parenthesized
    add_definitions(/D_CRT_NO_VA_START_VALIDATION)
endif()

# add the example executable 
add_executable(${PROJECT_NAME} WIN32 simpletest.cpp)
# ... link against Qt5/6 and JKQTPlotterLib
#    (you could use JKQTPlotterSharedLib if you don't want to link againast the 
#     static version, but against the shared/DLL version).
target_link_libraries(${PROJECT_NAME} Qt${QT_VERSION_MAJOR}::Core Qt${QT_VERSION_MAJOR}::Widgets Qt${QT_VERSION_MAJOR}::Gui Qt${QT_VERSION_MAJOR}::PrintSupport Qt${QT_VERSION_MAJOR}::Svg Qt${QT_VERSION_MAJOR}::Xml)
# ... link against JKQTPlotter: As the Targets contain the Qt-Version-Number in their names, we can
#     link against 'JKQTPlotter${QT_VERSION_MAJOR}::JKQTPlotter${QT_VERSION_MAJOR}' and it works
#     for Qt5 AND Qt6 ...
#     if you have a speific Qt-Version, you can also write e.g. 'JKQTPlotter6::JKQTPlotter6'
target_link_libraries(${PROJECT_NAME} JKQTPlotter${QT_VERSION_MAJOR}::JKQTPlotter${QT_VERSION_MAJOR})


# Installation
install(TARGETS ${PROJECT_NAME} RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
\endcode

As you can see this cooks down to first finding the library, using 
\code{.cmake}
find_package(JKQTPlotter${QT_VERSION_MAJOR} REQUIRED)
\endcode
and then linking against the appropriate target from the list above:
\code{.cmake}
target_link_libraries(${PROJECT_NAME} JKQTPlotter${QT_VERSION_MAJOR}::JKQTPlotter${QT_VERSION_MAJOR})
\endcode
If you don't need to be Qt-version agnostic, you can simply write:
\code{.cmake}
find_package(JKQTPlotter6 REQUIRED)
target_link_libraries(${PROJECT_NAME} JKQTPlotter6::JKQTPlotter6)
\endcode


To build this example, you first need to make a subdirectory `build` inside the example directory <code>examples/cmake_link_example</code> and then call CMake form that subdirectory:
\code{.sh}
    $ mkdir build
    $ cd build
    $ cmake .. -G "<GENERATOR>" "-DCMAKE_PREFIX_PATH=<path_to_your_qt_sources>;<JKQTPLOTTER_INSTALL_DIR>"
\endcode
Again choose any CMake \c <GENERATOR> that is appropriate for your use-case. Replace \c <path_to_your_qt_sources> by the path of your Qt installation and \c <JKQTPLOTTER_INSTALL_DIR> by the \c CMAKE_INSTALL_PREFIX of your JKQTPlotter Build (see above).

Then you can again build the example either using the generated builf files (e.g. a Visual Studio solution), or by running
\code{.sh}
    $ cmake --build . --config "Debug" --target install
\endcode


\section page_buildinstructions_CMAKE_FETCHCONTENT Using JKQTPlotter with CMake's FetchContent-API

In addition to the method described above (i.e. build and install the library and then use it), you can also use JKQTPlotter via CMake's <a href="https://cmake.org/cmake/help/latest/module/FetchContent.html">FetchContent-API</a>. Also have a look at <a href="https://www.foonathan.net/2022/06/cmake-fetchcontent/">this blog post</a> for a detailed explanation. Also see \ref JKQTCMakeFetchContentExample for a detailed example.

For this method, you need to add these lines to your CMake project:
\code{.cmake}
include(FetchContent) # once in the project to include the module
# ... now declare JKQTPlotter5/6
FetchContent_Declare(JKQTPlotter${QT_VERSION_MAJOR}
                     GIT_REPOSITORY https://github.com/jkriege2/JKQtPlotter.git
                     # GIT_TAG        v5.0.0)
# ... finally make JKQTPlotter5/6 available
FetchContent_MakeAvailable(JKQTPlotter${QT_VERSION_MAJOR})
\endcode

These declare JKQTPlotter and make it available in your project. Afterwards you should be able to link against it, using
\code{.cmake}
target_link_libraries(${PROJECT_NAME} JKQTPlotter${QT_VERSION_MAJOR}::JKQTPlotter${QT_VERSION_MAJOR})
\endcode

*/