.. _installation:

Installing the ASN.1 Compiler
=============================

This section covers how to install the `asn1c` compiler required to generate C source files from ASN.1 specifications.
These sources are later compiled into Python extension modules using the CMake-based build system.

The `asn1c` compiler is not bundled with your Python package — it must be installed separately before you can build
extensions with :cmake:command:`asn1c_add_extension()`.

Requirements
------------

**General Notes**

- A **64-bit build system** is strongly recommended for optimal performance.
- You will need a **working C99 compiler** to build the compiler itself (e.g., GCC 4.x or later, Clang 3.4 or later).
- The code generated by `asn1c` is **C90-compatible** and can be compiled with both C and C++ compilers.

**Build Dependencies**

The following packages are required to build the `asn1c` compiler from source:

- ``automake`` **1.15** or newer
- ``libtool`` (latest stable version recommended)
- ``bison`` **2.x** (note: `asn1c` requires *exactly* the 2.x branch; 3.x is not supported)
- ``flex``

**To compile code generated by `asn1c`**:

- **C:** Any C compiler with C90 support (GCC or Clang recommended)
- **C++:** A compiler supporting at least C++11 (e.g., GCC 4.8+, Clang 3.3+, MSVC 2015+)


Downloading the Source
----------------------

You can obtain `asn1c` from its Git repository or from a release tarball.

**Clone the repository**:

.. code-block:: bash

    git clone https://github.com/MatrixEditor/asn1c-bindings.git
    cd asn1c

**Or download a release**:

.. code-block:: bash

    wget https://github.com/MatrixEditor/asn1c-bindings/archive/refs/tags/v0.X.XX.tar.gz
    tar -xf v0.X.XX.tar.gz
    cd asn1c-bindings-0.X.XX

Configuration
-------------

Run the following commands to prepare the build system and configure:

**Default settings**:

.. code-block:: bash

    test -f configure || autoreconf -iv
    ./configure
    make

.. note::
  `asn1c` supports a variety of configuration flags:

  +------------------------+---------------------------------------------------+
  | Option                 | Description                                       |
  +------------------------+---------------------------------------------------+
  | --enable-ASN_DEBUG     | Enable debug logging during `make check`          |
  +------------------------+---------------------------------------------------+
  | --enable-code-coverage | Enable code coverage support                      |
  +------------------------+---------------------------------------------------+
  | --enable-Werror        | Treat all compiler warnings as errors             |
  +------------------------+---------------------------------------------------+
  | --enable-test-Werror   | Treat warnings in test builds as errors           |
  +------------------------+---------------------------------------------------+
  | --enable-test-32bit    | Enable tests for 32-bit compatibility             |
  +------------------------+---------------------------------------------------+
  | --disable-test-ubsan   | Disable Undefined Behavior Sanitizer for tests    |
  +------------------------+---------------------------------------------------+
  | --disable-test-asan    | Disable Address Sanitizer for tests               |
  +------------------------+---------------------------------------------------+
  | --enable-test-fuzzer   | Enable LLVM LibFuzzer for randomized testing      |
  +------------------------+---------------------------------------------------+

  For the full list, run:

  .. code-block:: bash

      ./configure --help

Build
-----

Compile the libraries and the compiler:

.. code-block:: bash

    make

.. tip::
  You may add ``-j$(nproc)`` to speed up compilation on multi-core systems.

Installation
------------

Install into the system's standard location:

.. code-block:: bash

    sudo make install

**Custom installation location**:

.. code-block:: bash

    ./configure --prefix=$HOME/.local
    make
    make install

If you install to a non-standard prefix, ensure the compiler is available on your ``PATH``:

.. code-block:: bash

    export PATH="$HOME/.local/bin:$PATH"


Next Steps
----------

Once `asn1c` is installed, you can use it together with the `asn1c-bindings` CMake package
to generate and build Python extension modules directly from `.asn` files.
See :ref:`build_system` for a complete guide.