# ASN.1 SDK

ASN.1 SDK is a command-line toolkit for compiling ASN.1 projects into generated source code and runtime metadata for supported target languages.

The SDK reads an `asn1.avn` project file, parses ASN.1 modules from the configured source directory, and runs the enabled compiler plugins. Supported compiler targets include Java, C, C++, C#, and Go when the corresponding plugin and license are present.

## Requirements

- Java 17 or later
- A valid ASN Lab license key for each compiler target you use
- Target-language build tools when you build generated code, such as a JDK, CMake/C compiler, C++ compiler, .NET SDK, or Go toolchain

## Installation

Unpack the SDK archive produced by ASN Lab. The distribution contains:

```text
bin/
  asndt.sh
  asndt.bat
lib/
  core/
  plugins/
README.md
LICENSE
```

Use `bin/asndt` on Linux/macOS or `bin/asndt.bat` on Windows:

```bash
bin/asndt
```

On Windows:

```bat
bin\asndt.bat
```

## Activate A License

Run the interactive license manager:

```bash
bin/asndt license
```

Choose **Activate license**, select the compiler, and paste the license key supplied by ASN Lab. The SDK stores activated licenses in the current user's profile:

- Linux/macOS: `~/.asnsdk/license.avn`
- Windows: `%APPDATA%\asnsdk\license.avn`

License keys are confidential. Do not commit, publish, share, or transfer them outside the licensed user or licensed entity.

## Create A Project

Create a new ASN.1 project skeleton:

```bash
bin/asndt create MyProject
```

This creates:

```text
MyProject/
  asn1.avn
  src/
  build/
```

Place ASN.1 source files under `src/`, then edit `asn1.avn` to choose the compiler targets and generation options you need.

## Project Configuration

A minimal project can look like this:

```asn1
{
    name "MyProject",
    version "0.1.0",
    description "Example ASN.1 project",
    source "src",
    output "build",
    compilers {
        {
            id "asnjc",
            language "java",
            options {
                output-folder "java"
            }
        },
        {
            id "asncpp",
            language "c++",
            options {
                output-folder "c++",
                cpp-standard cpp17,
                using-module-name-as-namespace TRUE
            }
        }
    }
}
```

Common top-level fields:

- `name`: Project name used by the build.
- `version`: Project version.
- `description`: Human-readable project description.
- `source`: Directory containing `.asn` files, relative to the project directory.
- `output`: Directory for generated output, relative to the project directory.
- `options`: Shared compiler options, such as generated naming templates.
- `compilers`: Enabled compiler targets and target-specific options.
- `dependencies`: Optional dependent ASN.1 projects.
- `scripts`: Optional project scripts.

Compiler entries are SEQUENCE OF elements, each with an `id` field identifying the compiler plugin and a `language` field for the target language, plus an `options` block for target-specific configuration.

## Compile A Project

Compile a project by passing the project directory:

```bash
bin/asndt compile /path/to/project
```

The SDK loads the project file at `<path>/asn1.avn`, finds enabled compiler plugins, validates the configured licenses, parses the ASN.1 source modules, and writes generated files under the configured `output` directory.

For example, with `output "build"` and `java.output-folder "java"`, Java output is written under the project's build directory:

```text
<project>/build/java/
```

## Clean A Project

Remove all generated output from a project without recompiling:

```bash
bin/asndt clean /path/to/project
```

The SDK reads the project file at `<path>/asn1.avn`, resolves the configured `output` directory, and deletes it entirely. This is useful before recompilation to ensure no stale generated files remain, or when the license server is unreachable and a full `compile` cannot run.

## Generated Code

Generated code is intended to be built into your application with the matching
ASN.1 runtime library for the target language. The generated types and metadata
support ASN.1 encoding and decoding according to the capabilities of the
selected compiler plugin and runtime.

Generated source code and metadata are subject to the ASN Lab license
agreement:

- Do not disclose generated source code except as permitted by your license.
- Do not redistribute runtime libraries except as permitted by your license.
- Keep license keys confidential. Do not embed them in source code,
  configuration files, or version control.


## Shared Compiler Options

The `options` block in `asn1.avn` accepts:

| Field             | Type              | Description |
|-------------------|-------------------|-------------|
| `naming-template` | SEQUENCE OF string | Templates used to name anonymous types. Available variables: `${memberName}`, `${parentName}`, `${moduleName}`. The first template that produces a unique name is used. |

## Supported Encoding Rules

| Encoding Rule              | Constant | Description |
|----------------------------|----------|-------------|
| Basic Encoding Rules       | BER (0)  | Tag-Length-Value encoding. Flexible, widely used. |
| Canonical Encoding Rules   | CER (1)  | BER with restrictions for canonical form. |
| Distinguished Encoding     | DER (2)  | BER with restrictions for unique encoding. |
| Unaligned Packed Encoding  | UPER (3) | Packed, bit-level encoding without octet alignment. |
| Aligned Packed Encoding    | APER (4) | Packed, bit-level encoding with octet alignment. |
| Octet Encoding Rules       | OER (8)  | Octet-aligned encoding optimized for speed. |
| XML Encoding Rules         | XER (16) | XML-based encoding. |
| JSON Encoding Rules        | JER (32) | JSON-based encoding. |

Availability of each encoding rule depends on the target language runtime.

## Compiler Guides

Each target language has a dedicated compiler guide with the full option
reference and language-specific mapping details:

- [Java Compiler Guide](doc/java-compiler-guide.md)
- [C Compiler Guide](doc/c-compiler-guide.md)
- [C++ Compiler Guide](doc/cpp-compiler-guide.md)
- [C# Compiler Guide](doc/csharp-compiler-guide.md)
- [Go Compiler Guide](doc/go-compiler-guide.md)
