---
name: ncreport
description: Use when writing, reviewing or debugging code that uses NCReport, the Qt/C++ report engine by GrassBits (NCReport class, runReportToPdfWriter, preview, NCReportDataSource, addItemModel, addParameter), when creating or editing NCReport report templates (.ncr XML: data sources, fields, groups, variables, $D{}/$P{}/$V{} expressions), when linking or deploying NCReport with qmake or CMake, or when using NCReport Designer, the NCReport command line client or the REST API server. Holds the verified API names, the template format, build recipes and known pitfalls.
---

# Working with NCReport

NCReport is a report engine library for Qt/C++ (Qt 6 and Qt 5.15) with a visual designer. An application loads a
**report template** (XML, usually `.ncr`, made in NCReport Designer), feeds it data (SQL, Qt item models, string
lists, parameters or a custom data source) and renders it to a preview, a printer, PDF, SVG, images, HTML, Excel
HTML or text. This skill covers NCReport 2.36.

## The rules that prevent most mistakes

1. **Don't guess names.** Before using a C++ class, method, signal or enum value, find it in
   [references/api-index.md](references/api-index.md), generated from the headers; for template elements and
   attributes, in [references/templates.md](references/templates.md). If a name isn't there, it doesn't exist.
   Agents commonly invent `runReportToPDF`, `runReportToExcel` and `groupExp="$D{col}"`; none of them work.
2. **Run methods return `void`. Check `hasError()` after every run** and show `lastErrorMsg()`.
3. **A `QApplication` must exist**, even for PDF generation in a console program or on a server.
4. **Templates fail silently.** The reader ignores unknown elements and attributes, so a typo produces an empty
   field, not an error. Use the names in [templates.md](references/templates.md) and preview the result.
5. **Prefer `runReportToPdfWriter()` for PDF** and `runReportToModernPreview(0, QString(), parent)` for an
   on-screen preview in new code.
6. **Data goes in before the run**: parameters, item models, string lists and custom data sources are resolved when
   the template is read at the start of the run, and NCReport does not own models or views.
7. **Find out the setup first**: NCReport version, Qt version, compiler, and whether the user has an evaluation
   package, a commercial binary package or the source code. Library names and include paths depend on it.

## The smallest working program

```cpp
#include <QApplication>
#include <QDebug>
#include "ncreport.h"

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    NCReport report;
    report.setReportFile("reports/orders.ncr");
    report.addParameter("year", 2026);              // $P{year} in the template
    report.runReportToPdfWriter("orders.pdf");

    if (report.hasError()) {
        qCritical() << "Report error:" << report.lastErrorMsg();
        return 1;
    }
    return 0;
}
```

Link: `-lNCReport -lzint` on Linux, `-lNCReport2 -lzint2` on Windows, `-framework NCReport -lzint` on macOS
(debug: `NCReportd`, `NCReportd2`, `zintd`). Include paths: `src/ncreport`, `src/ncreport/preview` and
`<build>/include`, or the single installed `include` folder. Details in
[build-and-deploy.md](references/build-and-deploy.md).

## How a template fits together

```text
NCReport (root)
├─ options              page size, orientation, margins, default font, doublePass …
├─ datasources          <datasource id="orders" type="sql|txt|xml|list|model|custom">
├─ variables            <variable funcType="sum" scope="group">amount</variable>
├─ scripts              named scripts, used as $S{id}
├─ pageheader / pagefooter / reportheader / reportfooter     items directly inside
└─ details
   └─ detail datasource="orders"     one band per data row
      ├─ items                       the row's items
      └─ groups / group groupExp="customer"
         ├─ groupheader              items directly inside
         └─ groupfooter
```

In texts and scripts: `$D{ds.column}` data, `$P{name}` parameter, `$V{name}` variable or system variable
(`pageno`, `pagecount`, `date`), `<% script %>` (escaped as `&lt;% … %&gt;` in XML).

## Read next: pick by what you are doing

| Task | Read |
| --- | --- |
| Calling the engine from C++: sources, outputs, preview, parameters, models, custom data sources, batch, signals | [references/api.md](references/api.md) |
| Checking that a class, method, signal or enum value exists, and its exact signature (search it, don't read it whole) | [references/api-index.md](references/api-index.md) |
| Writing or editing a `.ncr` template: structure, data sources, fields, expressions, variables, groups | [references/templates.md](references/templates.md) |
| qmake or CMake setup, library names, building from source, deploying on Windows, Linux, macOS, Android | [references/build-and-deploy.md](references/build-and-deploy.md) |
| NCReport Designer, the `NCReport` command line client, the Tester, the REST API server | [references/tools.md](references/tools.md) |
| An error message or wrong output | [references/troubleshooting.md](references/troubleshooting.md) |

For anything not covered here, read the matching chapter of
[NCReport — The Definitive Guide](https://docs.ncreport.org/ncreport/2.36/index.html) (cross tables, charts, zones,
labels, text document mode, sub-reports, table of contents, translations, conditional formatting).

## When the docs, examples and headers disagree

The API index lists NCReport 2.36. The headers of the user's installed NCReport are the final word: when the user
has another version, or the index and the user's compiler disagree, search the headers. Do this last, after the
index and the reference files:

```sh
grep -rn "runReportTo" /path/to/NCReport/include      # or src/ncreport in the source package
```

Some old examples and demos still use names that no longer work: `NCReportDebug2` (now `NCReportd2`), an
`includes/` folder, `runReportToPDF`, `NCReportPreviewWidget` and `setReportSource(NCReportSource::File)`. Don't
copy them.

## Before you call it done

- The code checks `hasError()` after each run and reports `lastErrorMsg()`.
- Every `$D{}`, `$P{}` and `$V{}` name in the template matches a column, an `addParameter()` call or a variable,
  case included; every `modelID`/`listID`/custom data source id matches the C++ side.
- Template XML is well formed (`xmllint --noout file.ncr`) and scripts and comparisons in it are escaped.
- The report was actually run once (the user's app, the `NCReport` command line client, or the Designer's preview),
  and the output was looked at.
- Deployment ships the engine library, Zint, the Qt SQL driver plugin the reports use, and the fonts they name.
- Never put database passwords in templates checked into version control: use `connection="internal"` and open the
  connection in the application.

Licensing questions (editions, source code, redistribution): https://ncreport.org/license-information/ and
https://ncreport.org/faq/. Support for licensed customers: https://support.grassbits.com/.
