JKQtPlotter/doc/dox/buildinstructions.dox

/*!

\page page_buildinstructions Build Instructions

This page explains how to build JKQTPlotter and to use the results in your own Projects.

\tableofcontents

\section page_buildinstructions_CMAKE Build using CMake

\subsection page_buildinstructions_CMAKE_RUN Running a Build with CMake

The preferred way to build JKQTPlotter is using <a href="https://cmake.org/">CMake</a>. 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/  \endcode and \code ./examples/  \endcode .

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. 


\subsubsection page_buildinstructions_CMAKE_MAKEFILE Building with MinGW/GNU/... Makefiles

You can use (MinGW) Makefiles by calling:

\code{.sh}
    $ mkdir build
    $ cd build
    $ cmake .. -G "MinGW Makefiles" "-DCMAKE_PREFIX_PATH=<path_to_your_qt_sources>"
    $ cmake --build . --config "Debug"
    $ cmake --build . --config "Debug" --target install
\endcode

\subsubsection page_buildinstructions_CMAKE_VSTUDIO Building with Visual Studio

For Visual Studio it could look like this:
\code{.sh}
    $ mkdir build
    $ cd build
    $ cmake .. -G "Visual Studio 15 2017 Win64" "-DCMAKE_PREFIX_PATH=<path_to_your_qt_sources>"
\endcode
Where \code <path_to_your_qt_sources>  \endcode could be e.g. \code C:/development/Qt5/5.12.0/msvc2017_64  \endcode . 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
Afterwards you can install the library by
\code{.sh}
    $ cmake --build . --config "Debug" --target install
\endcode

\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:
  - \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 JKQtPlotter_BUILD_SHARED_LIBS : Build as shared library (default: \c ON )
  - \c JKQtPlotter_BUILD_STATIC_LIBS : Build as static library (default: \c ON )
  - \c JKQtPlotter_BUILD_INCLUDE_XITS_FONTS : Include XITS 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_BUILD_EXAMPLES : Build examples (default: \c ON )
  - \c CMAKE_INSTALL_PREFIX : Install directory for the library
.




\subsection page_buildinstructions_CMAKE_USAGE Using a built, generated with CMake

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

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">https://github.com/jkriege2/JKQtPlotter/blob/master/examples/cmake_link_example</a>).

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

\code
	# set minimum required CMake-Version
	cmake_minimum_required(VERSION 3.10)

	# set Project name
	set(EXAMPLE_NAME simpletest)
	set(EXENAME jkqtptest_${EXAMPLE_NAME})
	project(${EXAMPLE_NAME} LANGUAGES CXX)

	# some basic configurations
	set(CMAKE_AUTOMOC ON)
	set(CMAKE_INCLUDE_CURRENT_DIR ON)
	set(CMAKE_CXX_STANDARD 11)
	#set(CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS ON)

	# Configure project for usage of Qt5
	find_package(Qt5 COMPONENTS Core Gui Widgets PrintSupport Svg Xml OpenGl REQUIRED)
	# Configure project for usage of Qt6
	#find_package(Qt6 COMPONENTS Core Gui Widgets PrintSupport Svg Xml OpenGl OpenGLWidgets REQUIRED)

	# include JKQTPlotter
	find_package(JKQTCommonLib REQUIRED)
	find_package(JKQTMathTextLib REQUIRED)
	find_package(JKQTPlotterLib 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(${EXENAME} WIN32 simpletest.cpp)
	# ... link against Qt5 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(${EXENAME} Qt5::Core Qt5::Widgets Qt5::Gui Qt5::PrintSupport Qt5::Svg Qt5::Xml JKQTPlotterLib)

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



To build this example, you first need to make a subdirectory `build` and then call CMake form that subdirectory:
\code.sh
    $ mkdir build
    $ cd build
    $ cmake .. -G "<GENERATOR>" "-DCMAKE_PREFIX_PATH=<path_to_your_qt_sources> -DCMAKE_MODULE_PATH=<path_to_lib/cmake_dir_of_JKQTPLOTTER>"
\endcode
The you can use the generated makefiles (e.g. load them in an editor, or build them jsing \c make ). In the last line above, you need to specify two directories:
  - \code <path_to_your_qt_sources>  \endcode points to you Qt installation
  - \code <path_to_lib/cmake_dir_of_JKQTPLOTTER>  \endcode points to the directory containing the \c XYZ.cmake -files from the JKQTPlotter build. Typically this is \code <JKQTPLOTTER_INSTALL_DIR>/lib/cmake \endcode , where \code <JKQTPLOTTER_INSTALL_DIR> \endcode is the directory into which you installed JKQTPlotter.
.

\section page_buildinstructions_QMAKE Build using QMake

\subsection page_buildinstructions_QMAKEINCLUDE QMake Include Project

If you want to simply include the JKQTPlotter Source code into your projects, without build a shared or static library and linking against it, you can use one of  these QMake-Include files:
  - <a href="https://github.com/jkriege2/JKQtPlotter/blob/master/lib/jkqtplotter.pri">lib/jkqtplotter.pri</a> includes the complete library (JKQTPlotter, JKQTFastPlotter, JKQTMathText)
  - <a href="https://github.com/jkriege2/JKQtPlotter/blob/master/lib/jkqtmathtext.pri">lib/jkqtmathtext.pri</a> includes only JKQTMathText
  - <a href="https://github.com/jkriege2/JKQtPlotter/blob/master/lib/jkqtfastplotter.pri">lib/jkqtfastplotter.pri</a> includes only JKQTFastPlotter
.

In your QMake-projects it is then sufficient to add a line like:
\code{.qmake}
  include(<PATHTOJKQTPLOTTERDIR>/lib/jkqtplotter.pri)
\endcode

\subsection page_buildinstructions_QMAKESTATIC QMake Static Library

There are several `.PRO`-files, that can be used to build the full library, or a limited subsets of it as static link library:
  - <a href="https://github.com/jkriege2/JKQtPlotter/blob/master/qmake/staticlib/jkqtplotterlib/jkqtplotterlib.pro">qmake/staticlib/jkqtplotterlib/jkqtplotterlib.pro</a> builds the complete library (JKQTPlotter, JKQTFastPlotter, JKQTMathText) as static link library
  - <a href="https://github.com/jkriege2/JKQtPlotter/blob/master/qmake/staticlib/jkqtmathtextlib/jkqtmathtextlib.pro">qmake/staticlib/jkqtmathtextlib/jkqtmathtextlib.pro</a> builds only JKQTMathText as static link library
  - <a href="https://github.com/jkriege2/JKQtPlotter/blob/master/qmake/staticlib/jkqtfastplotterlib/jkqtfastplotterlib.pro">qmake/staticlib/jkqtfastplotterlib/jkqtfastplotterlib.pro</a> builds only JKQTFastPlotter as static link library
.
They will produce a static link library that you can include into your projects, e.g. with the following QMake-snippet:

\code{.qmake}
# include JKQTPlotter library
DEPENDPATH += \
              <PATHTOJKQTPLOTTERDIR>/lib \
              <PATHTOJKQTPLOTTERDIR>/qmake/staticlib/jkqtplotterlib
INCLUDEPATH += <PATHTOJKQTPLOTTERDIR>/lib
CONFIG (debug, debug|release) {
    DEPENDPATH += <PATHTOJKQTPLOTTERDIR>/qmake/staticlib/jkqtplotterlib/debug
    LIBS += -L<PATHTOJKQTPLOTTERDIR>/qmake/staticlib/jkqtplotterlib/debug -ljkqtplotterlib_debug
} else {
    DEPENDPATH += <PATHTOJKQTPLOTTERDIR>/qmake/staticlib/jkqtplotterlib/release
    LIBS += -L<PATHTOJKQTPLOTTERDIR>/qmake/staticlib/jkqtplotterlib/release -ljkqtplotterlib
}
\endcode

This snippet assumes that you built the libraries with the provided \code .PRO  \endcode -files. You can also add a second \code .PRO  \endcode -file to your projects, which integrates both as subdirs. Such files are used for all examples in this project. Here is an example:
\code{.qmake}
TEMPLATE = subdirs

# the (static library version) of JKQTPlotter
jkqtplotterlib_static.file = ../../qmake/staticlib/jkqtplotterlib/jkqtplotterlib.pro

# your project file, with declared dependencies on jkqtplotterlib_static
test_styling.file=$$PWD/test_styling.pro
test_styling.depends = jkqtplotterlib_static

# add the two entries to SUBDIRS
SUBDIRS +=  jkqtplotterlib_static test_styling
\endcode



\subsection page_buildinstructions_QMAKEDYNAMIC QMake Dynamic Library

There are several `.PRO`-files, that can be used to build the full library, or a limited subsets of it as shred library:
  - <a href="https://github.com/jkriege2/JKQtPlotter/blob/master/qmake/sharedlib/jkqtplotterlib/jkqtplotterlib.pro">qmake/sharedlib/jkqtplotterlib/jkqtplotterlib.pro</a> builds the complete library (JKQTPlotter, JKQTFastPlotter, JKQTMathText) as shared library
  - <a href="https://github.com/jkriege2/JKQtPlotter/blob/master/qmake/sharedlib/jkqtmathtextlib/jkqtmathtextlib.pro">qmake/sharedlib/jkqtmathtextlib/jkqtmathtextlib.pro</a> builds only JKQTMathText as shared library
  - <a href="https://github.com/jkriege2/JKQtPlotter/blob/master/qmake/sharedlib/jkqtfastplotterlib/jkqtfastplotterlib.pro">qmake/sharedlib/jkqtfastplotterlib/jkqtfastplotterlib.pro</a> builds only JKQTFastPlotter as shared library
.
They will produce a dynamic link library that you can include into your projects, e.g. with the following QMake-snippet:

\code{.qmake}
# include JKQTPlotter library
DEPENDPATH += \
              <PATHTOJKQTPLOTTERDIR>/lib \
              <PATHTOJKQTPLOTTERDIR>/qmake/sharedlib/jkqtplotterlib
INCLUDEPATH += <PATHTOJKQTPLOTTERDIR>/lib
DEFINES += JKQTCOMMON_LIB_IN_DLL JKQTFASTPLOTTER_LIB_IN_DLL JKQTMATHTEXT_LIB_IN_DLL JKQTPLOTTER_LIB_IN_DLL
CONFIG (debug, debug|release) {
    # ensure that DLLs are copied to the output directory
    install_jkqtplotter_dll.files = <PATHTOJKQTPLOTTERDIR>/qmake/sharedlib/jkqtplotterlib/debug/jkqtplotterlib_debug.*
    install_jkqtplotter_dll.path = $$OUT_PWD
    INSTALLS += install_jkqtplotter_dll
    # link agains DLLs
    DEPENDPATH += <PATHTOJKQTPLOTTERDIR>/qmake/sharedlib/jkqtplotterlib/debug
    LIBS += -L<PATHTOJKQTPLOTTERDIR>/qmake/sharedlib/jkqtplotterlib/debug -ljkqtplotterlib_debug
} else {
    # ensure that DLLs are copied to the output directory
    install_jkqtplotter_dll.files = <PATHTOJKQTPLOTTERDIR>/qmake/sharedlib/jkqtplotterlib/release/jkqtplotterlib.*
    install_jkqtplotter_dll.path = $$OUT_PWD
    INSTALLS += install_jkqtplotter_dll
    # link agains DLLs
    DEPENDPATH += <PATHTOJKQTPLOTTERDIR>/qmake/sharedlib/jkqtplotterlib/release
    LIBS += -L<PATHTOJKQTPLOTTERDIR>/qmake/sharedlib/jkqtplotterlib/release -ljkqtplotterlib
}
\endcode

This snippet assumes that you built the libraries with the provided `.PRO`-files. You can also add a second `.pro`-file to your projects, which integrates both as subdirs. Such files are used for all examples in this project. Here is an example:
\code{.qmake}
TEMPLATE = subdirs

# the (shared library version) of JKQTPlotter
jkqtplotterlib_shared.file = ../../qmake/sharedlib/jkqtplotterlib.pro

# your project file, with declared dependencies on jkqtplotterlib_shared
test_styling.file=$$PWD/test_styling.pro
test_styling.depends = jkqtplotterlib_shared

# add the two entries to SUBDIRS
SUBDIRS +=  jkqtplotterlib_shared test_styling
\endcode

\note You will have to run a deployment step `make install` before running your executable, so the shared libararies are actually copied to the output directory (see `INSTALLS + ...` above).



\subsection page_buildinstructions_QMAKEQTCREATOR QMake in QTCreator

You can load the file \c JKQtPlotterBuildAllExamples.pro in te base directory of the project directly in QtCreator and use it to build the library and the examples.




*/