oscms-asn1c-generated

This repository contains source files for codecs generated by ASN1C. These are used in a

This OpenSCMS project uses a fork of the open source ASN1C transpiler found at https://github.com/mouse07410/asn1c, and forks of the IEEE 1609.2.1 ASN1.C source files found as submodules within this project.

The transpiler is used to generate a set of C source files which are then wrapped to produce a concrete implementation of the API defined in the oscms-codecs-api repository for use in the OpenSCMS server.

Table of Contents

• Getting the Code
• Note on the transpiler and patching the generated code
• How to create or update the source files using Docker
• How to create or update the source files using a locally installed copy of ASN1C
  • Transpiler Dependencies
  • Compile the ASN1C transpiler
  • Transpile the ASN files into C source code
• Perform a test compile of the generated code
• Copyright and License Information

Getting the Code

The Open SCMS stack makes heavy use of submodules. Therefore, the clone command should ensure it pulls down all sub modules as follows.

git clone --recurse-submodules git@github.com:OpenSCMS/oscms-asn1c-codecs.git

Obviously, replace the URL with your own if you are cloning a fork.

Due to the use of relative submodule paths, if you are going to fork one repository you will need to fork them all. The alternative is for you to modify the paths in .gitmodules, but DO NOT commit these changes. Such a pull request will not be accepted.

The list of repositories, and their relative submodule dependencies is as follows

• OpenSCMS
  • oscms-codecs-bridge
    • oscms-asn1c-codecs
      • oscms-codecs-api
      • oscms-asn1c-generated
        • etsi_ts103097-asn
        • ieee1609dot2dot1-asn

Note on the transpiler and patching the generated code

The raw generated source files will NOT compile cleanly with -Werror and, in fact, contain some bugs (notably dealing with constraints on unsigned 64 bit values).

To work around this, a series of patches need to be applied. These live under the files/patches directory and are applied automatically when either the patch or transpile-and-patch targets of the Makefile are applied.

Thankfully, the upstream ASN.1 sources change very rarely. However, if it is necessary to regenerated the source, the patches may fail to apply and need to be updated.

In order to minimize the size of patch files (usually when an editor such as VSCode auto-applies formatting during modification of the original code), changes should be made in the oscms_asn1c_generated directory and the patch files generated from there.

We don't use git to generate or apply the patches. Instead, we simply use the diff and patch commands with the patch files in unified format. So the process is

• Edit the file in the oscms_asn1c_generated directory
• Perform a test compilation with make test-compile
• Ideally, build oscms-asn1c-codecs using the modified code and run all tests.
• Generate the patch file with:

   diff -u formatted_source/<FILENAME> oscms_asn1c_generated \
        >files/patch/<FILENAME>.patch

• Run git add . to stage the patch file and manually changed code.
• Run make patch to empty oscms_asn1c_generated and reapply the patch files.
• Run git status to ensure that applying the patches regenerated your changes correctly.
• Commit the staged changes.

How to create or update the source files using Docker

To avoid installing the transpiler (and it's dependencies) locally, a Docker image is provided which can be used to perform the actual transpilation. This is made available via a Makefile

The following commands will create the image and then run it, producing the code under the raw_source, formatted_source, and oscms_asn1c_generated directories (all of which should then be committed).

make transpiler-image
make docker-transpile

How to create or update the source files using a locally installed copy of ASN1C

You must use the version of the transpiler included as a submodule under the asn1c directory. This version is currently guaranteed to successfully interpret the ASN.1 syntax used by the IEEE source files.

Transpiler Dependencies

First, ensure you have all the transpiler's dependencies installed (assuming you already have compilers etc)

apt-get update -qy
apt-get -qy install \
    build-essential \
    automake \
    autotools-dev \
    libtool \
    bison \
    flex

Compile the ASN1C transpiler

cd asn1c
test -f configure || autoreconf -iv
./configure
sudo make install

Do not attempt to relocate the installation via the --prefix option for the configure command. If you do, the transpiler will fail to find it's skeletons directory and the generated sources will be incomplete.

Transpile the ASN files into C source code

make transpile-and-patch

The above script will:

• populate the folder raw_source with the output C source files.
• apply clang-format to the generated files and place the output in the formatted_source directory
• apply patches to the formatted source and place the final set of files into the oscms_asn1c_generated directory.

Perform a test compile of the generated code

The Makefile includes a target for performing a test compilation of the code generated by the transpiler.

make test-compile

Copyright and License Information

All original files in this repository are licensed under the Apache-2.0 license.

All generated files, in the following directories

• raw_source
• formatted_source
• oscms_asn1c_generated

are licensed under the BSD license, as used in the ASN1C compiler.

See the LICENSE and LICENSE-ASN1C files for details.