| Qore Programming Language - C/C++ Library 1.0.8

Using Qore with CMake Build System

# Using Qore and CMake

Qore comes with its own CMake support files.

The basic step for Qore inclusion in the CMake project is to put following line into `CMakeLists.txt` project configuration.

find_package(Qore)

# Build Type Handling

CMake allows to set various `CMAKE_BUILD_TYPE` build types. Qore package sets `CMAKE_BUILD_TYPE` to `debug` if it's not defined on input.

Qore files are located in `CMAKE_PREFIX/lib`[LIB_SUFFIX]/cmake/Qore directory.

# FIND_PACKAGE Arguments

find_package(<package> [version] [EXACT] [QUIET] [MODULE]
[REQUIRED] [[COMPONENTS] [components...]]
[OPTIONAL_COMPONENTS components...])

Argument | Description
--- | ---
`package` | `Qore`
`version` | A required version of Qore
`EXACT` | The `EXACT` option requests that the version be matched exactly.
`QUIET` | The `QUIET` option disables messages if the package cannot be found
`REQUIRED` | The `REQUIRED` option stops processing with an error message if the package cannot be found.
`COMPONENTS` | Unused for Qore
`OPTIONAL_COMPONENTS` | Unused for Qore

## CMake Qore Variables

Variable | Description
--- | ---
`QORE_FOUND` | Set if the system has Qore installed
`QORE_INCLUDE_DIR` | Path to Qore include files
`QORE_INCLUDE_DIRS` | CMake standard alias for QORE_INCLUDE_DIR
`QORE_LIBRARY` | Qore library location and name used for linking
`QORE_LIBRARIES` | CMake standard alias for QORE_LIBRARY
`QORE_MODULES_DIR` | Location of Qore binary modules
`QORE_API_VERSION` | Qore binary module API version
`QORE_EXECUTABLE` | Qore language interpret binary location, including executable name
`QORE_QPP_EXECUTABLE` | Qore QPP binary location, including executable name
`QORE_BUILD_TYPE_LWR` | A lower-cased `CMAKE_BUILD_TYPE` value

## Compiler Defines

`find_package(Qore)` sets some compiler defines automatically.

Variable | Description
--- | ---
`DEBUG` | Set if is the `CMAKE_BUILD_TYPE` set as debug
`NDEBUG` | Set if is the `CMAKE_BUILD_TYPE` set as anything alse as debug

There are more variables set when is the Qore Binary Modules Support for CMake functionality in use

# Qore Binary Modules Support for CMake

There are some helper macros for Developing Qore Modules located in `QoreMacros.cmake` file. Macros expect the module source code in following structure:

- docs (directory)
  - Doxyfile.in (template for real Doxyfile).
- cmake (directory)
  - cmake_uninstall.cmake.in (template for make uninstall)
- CMakeLists.txt (core cmake configuration)

Location of rest of files including source code is irrelevant. If there are no `Doxyfile.in` or `cmake_uninstall.cmake.in` present the appropriate make target will not be created (make docs/make uninstall).

See Qore Binary Module Example for real use.

- QORE_WRAP_QPP
- QORE_BINARY_MODULE
- QORE_DIST
- QORE_CONFIG_INFO

## QORE_WRAP_QPP

qore_wrap_qpp(out_files_list in_files_list)

This macro generated C++ files and documentation headers from Qore Preprocessor (QPP). It takes files from `in_files_list` for processing and it sets `out_files_list` with values of new C++ files stored in `CMAKE_BINARY_DIR`.

## QORE_BINARY_MODULE

qore_binary_module(target_name module_version [library1 [library2 [...]]])

This macro sets environment for building binary modules.

Arguments:

- `target_name` = a base name of the module, the same as specified in `add_libary`
- `module_version` = a string with version used in compiler defines later
- optional libraries = none, one, or many libraries to link with the module

Macro results:

- `PACKAGE_VERSION` define is set to `module_version` value
- `QORE_INCLUDE_DIR` and `CMAKE_BINARY_DIR` are appended to `include_directories`
- module `target_name` is set to use proper API and filename mask
- module is ready to be installed to `QORE_MODULES_DIR`
- `make` `uninstall` target is created when possible
- `make` `docs` target is created when posiible

make docs notes

Macro calls `find_package(Doxygen)` in this case. If there is Doxygen tool found and if is the

## QORE_DIST

qore_dist(version)

This macro creates `make` `dist` target to create distributable tarballs in TBZ2 format

## QORE_CONFIG_INFO

qore_config_info()

This macro prints configuration label, text lines with information about architecture, build type, compiler flags, etc.

## Qore Binary Module Example

cmake_minimum_required(VERSION 2.8.3)
project(qore-magic-module)
set (VERSION_MAJOR 0)
set (VERSION_MINOR 0)
set (VERSION_PATCH 1)
# storage of custom FindLibMagic.cmake
set(CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/cmake )
# find Qore library and build environment
find_package (Qore REQUIRED)
# find mandatory library
find_package(LibMagic REQUIRED)
# additional includes
include_directories( ${CMAKE_SOURCE_DIR}/src )
include_directories( ${LIBMAGIC_INCLUDE_DIR} )
# module source code - C and C++
set(CPP_SRC
src/qoremagic.cpp
src/magic-module.cpp
)
# module source code - QPP files
set(QPP_SRC
src/magic.qpp
)
# create C++ from QPP
qore_wrap_qpp(QPP_SOURCES ${QPP_SRC})
# setup the module
SET (module_name "magic")
add_library(${module_name} SHARED ${CPP_SRC} ${QPP_SOURCES})
# module will use name 'magic', version '0.0.1', and it will be linked with content of LIBMAGIC_LIBRARY by FindLibMagic.cmake
qore_binary_module(${module_name} "${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_PATCH}" ${LIBMAGIC_LIBRARY})
# create 'make dist'
qore_dist("${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_PATCH}")
# print final information
qore_config_info()