# Building, linking and deploying NCReport

NCReport is built with **qmake only**. There are no CMakeLists.txt and no CMake package files; CMake projects link the
prebuilt libraries with `find_library()` (below). C++17 is required.

Guide: [Integrating NCReport into desktop applications](https://docs.ncreport.org/ncreport/2.36/api/desktop.html),
[Using NCReport on Android](https://docs.ncreport.org/ncreport/2.36/api/android.html),
[Installing NCReport](https://docs.ncreport.org/ncreport/2.36/basics/install.html).

## Which package does the user have?

| Package | What it contains | Notes |
| --- | --- | --- |
| Evaluation (binary) | Prebuilt libraries, headers, Designer, demos | Prints an "EVALUATION VERSION" label on every page. Use the compiler and Qt version the package was built for. |
| Commercial binary | The same without the label | From the customer portal |
| Source (Standard, Enterprise) | Full source of the engine, Designer and tools | Build it with your own compiler and Qt |

Ask which one, and which Qt version and compiler, before writing build files. A binary package only works with the
same Qt major/minor version and compiler (MSVC and MinGW are not interchangeable, nor are debug and release on MSVC).

## Building from source

```sh
mkdir build-release && cd build-release
qmake -r ../NCReport2.x.x/ncreport.pro      # Windows: add WINDOWS_INSTALL_PATH=D:/NCReport for make install
make -j8                                    # Windows: nmake release, jom, or mingw32-make release
make install                                # optional
```

Results: libraries in `<build>/lib`, applications (Designer, console client, tester) in `<build>/bin`, and the
generated header `<build>/include/ncreport_config.h`.

Build options are set in `src/config.pri` (or in `src/custom_config.pri`, which overrides it). Do not invent others:

| Variable | Default | Useful values |
| --- | --- | --- |
| `BUILD_MODES` | `jsengine` | `jsengine` (QJSEngine scripts; always on with Qt 6), `nopixmap`, `translate_labels`, `debug_verbose` |
| `DISABLED_FEATURES` | `none` | `sql`, `svg`, `table_view`, `print_dialog`, `qprinter`, `desktop`, `cursor`, `script` (QtScript; forced with Qt 6), `zint` |
| `EXTENSIONS` | `designer runner consoleapp barcode preview` | `markdown`, `highcharts`, `webengine`, `barcodetempfile`, `demos`, `designerlib` |

- Without barcodes: `EXTENSIONS -= barcode` **and** `DISABLED_FEATURES += zint`. Removing only `barcode` still builds and links Zint.
- Without QPrintSupport: `DISABLED_FEATURES += qprinter` **and** `EXTENSIONS -= preview`.
- A Qt 5 build needs the QtScript module unless `DISABLED_FEATURES += script`.
- There is no QtCharts dependency; the chart item is the opt-in `highcharts` extension (needs Qt WebEngine).

Qt modules used by the engine: Core, Gui, Widgets, Xml, Network, Svg, Sql, Qml, and PrintSupport for printing, QPrinter
PDF and the preview.

## Library names

| Platform | Release | Debug | Zint (separate shared library since 2.27) |
| --- | --- | --- | --- |
| Linux | `libNCReport.so.2` (`-lNCReport`) | `libNCReportd.so.2` (`-lNCReportd`) | `libzint.so.2` / `libzintd.so.2` |
| Windows | `NCReport2.dll` / `NCReport2.lib` (`-lNCReport2`) | `NCReportd2.dll` (`-lNCReportd2`) | `zint2.dll` / `zintd2.dll` |
| macOS | `NCReport.framework` (`-framework NCReport`) | `NCReportd.framework` | `libzint.2.dylib` / `libzintd.2.dylib` |
| Android | `libNCReport_<abi>.so` | `libNCReportd_<abi>.so` | `libzint_<abi>.so` |

The old debug name `NCReportDebug2` and the old header folder `includes/` belong to old releases. Don't use them for
2.27 or later, even though some old examples still do.

## Linking an application

Include the headers without a directory prefix: `#include "ncreport.h"`, `#include "ncreportpreviewwindow.h"`.
The application needs no define: `NCREPORTSHARED_EXPORT` is an import declaration unless `NCREPORT_LIBRARY` is set.

Add `<build>/include` (the folder holding `ncreport_config.h`) to the include path. It records the build options that
change the public headers. If it is missing (older engine builds), define the matching options yourself, above all
`NCR_PREVIEW_MODULE`: without it the preview functions of `NCReport` are not declared.

### qmake

```qmake
QT += core gui widgets printsupport
CONFIG += c++17

NCREPORT_SRC     = /path/to/NCReport2.x.x/src      # source package; installed headers work too
NCREPORT_BUILD   = /path/to/build-release
NCREPORT_LIBPATH = $$NCREPORT_BUILD/lib

INCLUDEPATH += $$NCREPORT_SRC/ncreport $$NCREPORT_SRC/ncreport/preview $$NCREPORT_BUILD/include

CONFIG(debug, debug|release): D = d
win32 {
    LIBS += -L$$NCREPORT_LIBPATH -lNCReport$${D}2 -lzint$${D}2
} else:macx {
    LIBS += -F$$NCREPORT_LIBPATH -framework NCReport$${D} -L$$NCREPORT_LIBPATH -lzint$${D}
    QMAKE_RPATHDIR += $$NCREPORT_LIBPATH
} else:unix {
    LIBS += -L$$NCREPORT_LIBPATH -lNCReport$${D} -lzint$${D}
    QMAKE_RPATHDIR += $$NCREPORT_LIBPATH
}
```

With installed headers (`make install`, or a binary package) use a single include directory instead, e.g.
`/usr/local/NCReport/include` or `C:/NCReport/include`.

### CMake

```cmake
cmake_minimum_required(VERSION 3.16)
project(myapp LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_AUTOMOC ON)
find_package(Qt6 REQUIRED COMPONENTS Widgets PrintSupport)

set(NCREPORT_SRC   "" CACHE PATH "src directory of the NCReport source package")
set(NCREPORT_BUILD "" CACHE PATH "build directory of the NCReport engine")

# Debug build: NAMES NCReportd NCReportd2 and zintd zintd2
find_library(NCREPORT_LIBRARY NAMES NCReport NCReport2 PATHS ${NCREPORT_BUILD}/lib NO_DEFAULT_PATH REQUIRED)
find_library(ZINT_LIBRARY NAMES zint zint2 PATHS ${NCREPORT_BUILD}/lib NO_DEFAULT_PATH REQUIRED)

add_executable(myapp main.cpp)
target_include_directories(myapp PRIVATE
    ${NCREPORT_SRC}/ncreport ${NCREPORT_SRC}/ncreport/preview ${NCREPORT_BUILD}/include)
target_link_libraries(myapp PRIVATE ${NCREPORT_LIBRARY} ${ZINT_LIBRARY} Qt6::Widgets Qt6::PrintSupport)
```

### Direct source integration

The engine source can also be compiled into the application (recommended for Android and static builds). Define
`NCREPORT_DIRECT_INTEGRATION`; it empties the export macro and ignores `ncreport_config.h`, so set the feature defines
yourself (`NCREPORT_USE_QJSENGINE NCREPORT_NO_QTSCRIPT NCR_PREVIEW_MODULE BARCODE_INTEGRATION`, plus
`ZINT_NO_PNG ZINTLIB_LIBRARY` for the Zint sources). Keep `ncreport/` next to `3rdparty/zintlib/`; the barcode item
includes Zint by relative path. Follow the guide's "Direct source integration" section exactly; with qmake it
includes `ncreport/ncreport.pri`, never `config.pri`.

## Deploying the application

Ship the engine and Zint together; the engine finds Zint next to itself.

- **Windows:** copy `NCReport2.dll` and `zint2.dll` next to the exe, then
  `windeployqt --release deploy\myapp.exe deploy\NCReport2.dll` (passing the engine DLL makes windeployqt include
  Svg, Sql and Qml). Add `--compiler-runtime` for the MSVC runtime.
- **Linux:** put `libNCReport.so.2*` and `libzint.so.2*` in e.g. `<app>/lib` and give the application an rpath
  (`QMAKE_RPATHDIR += $ORIGIN/lib`, or `patchelf --set-rpath '$ORIGIN/lib' myapp`), or use `LD_LIBRARY_PATH`.
- **macOS:** `macdeployqt MyApp.app -libpath=<build>/lib`. If the framework or libzint is not copied, copy both into
  `Contents/Frameworks` and add `@executable_path/../Frameworks` as rpath (`install_name_tool -add_rpath`). Sign
  inside-out.
- **Android:** list the libraries in `ANDROID_EXTRA_LIBS` (qmake) or `QT_ANDROID_EXTRA_LIBS` (CMake). There is no
  QPrinter: use `runReportToPdfWriter()`, image, SVG, HTML or text output. Put reports in a `.qrc` and register fonts
  with `QFontDatabase::addApplicationFont()`.

Also ship:

- the **Qt SQL driver plugin** (`sqldrivers/qsqlite`, `qsqlmysql`, `qsqlpsql`, …) for each database the reports use,
  together with the database client library it needs;
- the printsupport and imageformats plugins (the deploy tools normally add them);
- the translations `ncreport_<lang>.qm`, if the preview UI should be translated (see below).

## Translations

The engine never installs a translator itself. To translate the preview window and dialogs, the application loads
`ncreport_<lang>.qm` (shipped in `i18n/`: cs, de, en, es, fr, hu, pl, ru, zh_CN) with its own `QTranslator`.
Report content languages are separate: `report->setCurrentLanguage("de")`, see the template reference.
