<!--
  Copyright (c) 2009-2026 ASN Lab
  All rights reserved.
-->

# ASN.1 C++ Compiler Guide

The ASN.1 C++ Compiler (`asncpp`) generates C++ source code from ASN.1
modules. Generated types are C++ classes/structs and work with the C++ runtime
library for encoding and decoding.

## Compiler Options

| Field                               | Type    | Default          | Description |
|-------------------------------------|---------|------------------|-------------|
| `output-folder`                     | string  | `"c++"`          | Output directory for generated C++ sources. |
| `mapping.integer`                   | ENUM    | `automatic`      | See [Integer Mapping](#integer-mapping). |
| `mapping.real`                      | ENUM    | `automatic`      | `automatic`, `float`, `double`. |
| `mapping.choice`                    | ENUM    | `union`          | `union` (C++ union), `variant` (std::variant, requires C++17). |
| `mapping.size-of-int`               | INTEGER | 4                | Size in bytes of `int` on the target platform. |
| `mapping.size-of-long`              | INTEGER | 8                | Size in bytes of `long` on the target platform. |
| `mapping.size-of-xlong`             | INTEGER | 8                | Size in bytes of `long long` on the target platform. |
| `using-module-name-as-namespace`    | BOOLEAN | TRUE             | Wrap generated types in a namespace named after the module. |
| `namespace`                         | string  | `""`             | Additional namespace prefix. |
| `cpp-standard`                      | ENUM    | `cpp03`          | `cpp03` or `cpp17`. Affects `variant` choice mapping and C++17 features. |
| `nullable-member`                   | ENUM    | `shared-pointer` | See [Nullable Member Mapping](#nullable-member-mapping). |
| `precompiled-header`                | string  | `""`             | Path to a precompiled header to include. |
| `generate.copy-constructor`         | BOOLEAN | FALSE           | Generate copy constructors. |
| `generate.clone`                    | BOOLEAN | FALSE           | Generate `clone()` methods. |
| `generate.frees`                    | BOOLEAN | TRUE            | Generate destructors / free functions. |
| `generate.equals`                   | BOOLEAN | FALSE           | Generate `operator==`. |
| `generate.prints`                   | BOOLEAN | FALSE           | Generate `operator<<` stream output. |

## Integer Mapping

Controls how ASN.1 INTEGER is mapped to C++ integer types:

| Option        | C++ type |
|---------------|----------|
| `automatic`   | Smallest of `int`/`long`/`long long` that fits the constraint range, or a big-int class when unconstrained. |
| `int32`       | `int32_t`. |
| `int64`       | `int64_t`. |
| `big-integer` | Big-int class. |

## Real Mapping

| Option      | C++ type |
|-------------|----------|
| `automatic` | `double`. |
| `float`     | `float`. |
| `double`    | `double`. |

## Choice Mapping

| Option    | Description |
|-----------|-------------|
| `union`   | A C++ `union` of the alternative types. Available in all C++ standards. |
| `variant` | `std::variant<T...>`. Requires C++17 (`cpp-standard cpp17`). |

## Nullable Member Mapping

Controls how OPTIONAL fields are represented in generated C++ types:

| Option            | C++ type for OPTIONAL fields |
|-------------------|------------------------------|
| `raw-pointer`     | Raw pointer (`T*`). Caller manages lifetime. |
| `unique-pointer`  | `std::unique_ptr<T>`. |
| `shared-pointer`  | `std::shared_ptr<T>`. |

## Project Configuration Example

```asn1
compilers {
    {
        language "c++",
        options {
            output-folder "c++",
            mapping {
                integer automatic,
                real automatic,
                choice union
            },
            using-module-name-as-namespace TRUE,
            cpp-standard cpp17,
            nullable-member shared-pointer,
            generate {
                copy-constructor FALSE,
                clone FALSE,
                frees TRUE,
                equals FALSE,
                prints FALSE
            }
        }
    }
}
```

## Runtime Integration

Include the generated `.cpp` and `.h` files in your build and link against the
C++ runtime library. The generated types provide `encode` and `decode` methods
that accept an encoding rule constant (BER, DER, UPER, APER, OER, XER, JER).

## Generated Output

With `output "build"` and `cpp.output-folder "c++"`, output is written under
`build/c++/`. Each ASN.1 module produces a header file and an implementation
file inside a namespace derived from the module name.
