oscms-codecs-api

This repository defines an abstract API to ASN.1 CODECs, whether generated by an open source or proprietary transpiler, or hand written. It also provides:

• some generic functionality for ASN.1 common concepts (such as an OCTET STRING or SEQUENCE OF) which can be used throughout the stack;
• a rudimentary logging abstraction;
• generic memory management functions for performing tracked allocations; and
• generic functions for releasing resources within API-defined data structures.

At present, the API is restricted to only those entities sent or received by the OpenSCMS server. Thus, for an SPDU which is only ever sent by the server, there will be an encode function but no matching decode function.

Table of Contents

• Development
  • Installing Dependencies
  • Using Docker
  • Getting the Code
  • Building the code
  • Running Unit Tests
  • Running Valgrind
• Contributing
• License

Development

We assume a debian-based development environment, ideally Ubuntu 24.04 or newer.

Installing Dependencies

This library has no external dependencies. However, you will need a set of tools

sudo apt-get -qy install \
    build-essential \
    clang-format-18 \
    cmake \
    cppcheck \
    curl \
    git \
    gzip \
    valgrind \
    wget

Using Docker

Alternatively, you can use the docker file provided in the oscms-ci-docker repository. This is the image used for all CI jobs for the C-language repositories during the initial development.

Clone the repository and build the image as follows

git clone git@github.com:OpenSCMS/oscms-ci-docker.git
cd oscms-ci-docker
docker build -t oscms-ci-docker . -f openscms-ci.dockerfile

Now change to the directory where you cloned this repository and run the container thus

docker run -ti --rm --volume $PWD:/WORK --user $(id -u):$(id -g) \
       oscms-ci-docker

This will place you in a bash shell within the container, with your cloned source available at /WORK. Your user inside the container will have the same group and user id as on your host, so any changes you make will have the correct permissions.

It should also be possible to use this image as a VS Code development container. The development team has not used it in this way, so if it doesn't work ... contributions are welcome.

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-codecs-api.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

The project also makes use of the Cmake Helpers project

Building the code

All C code is built using CMake and the CMake scripts will enforce out-of-source builds.

After cloning, create a build directory. We usually use BUILD directly in the repository root (it's included in the .gitignore), but feel free to put it anywhere convenient.

Change to your build directory and configure and build as follows

cmake .. # Or the path to your repository root
make

This will compile and link a Debug build and include all unit tests.

All CMake scripts support a common set of options and command line definitions.

Option	Default	Description
BUILD_TESTS	On	Enables or disables the building of the unit tests
CMAKE_BUILD_TYPE	Debug	Defines the build type. Acceptable values are Debug or Release. This primarily affects debug symbols and optimization levels.
EXTRA_MEMCHECK_OPTIONS	empty	Allows the specification of additional arguments to valgrind
RUN_CPPCHECK	On	Enables or disables running cppcheck on all code during the build.
SKIP_INSTALL	Off	If set to On, suppresses generation of any install targets

Running Unit Tests

After building the code (with BUILD_TESTS set to On) from the build directory, simply enter

make test

Alternatively, you can run them directly with ctest

ctest <options>

Which allows you to do things like select specific tests. See the CTest documentation for details.

Running Valgrind

From the build directory, run CTest with the memcheck option

ctest -T memcheck

By default the following valgrind options will be specified (in addition to those injected by CMake itself)

--tool=memcheck --leak-check=full --num-callers=50 --show-reachable=yes

You can specify additional options when configuring using the EXTRA_MEMCHECK_OPTIONS variable. For example, to generate suppressions in the log files and track the origin of allocations

cmake .. \
      -DEXTRA_MEMCHECK_OPTIONS="--gen-suppressions=yes --track-origins=yes"

The log files will appear in the Testing/Temporary directory with names of the form MemoryChecker.<#>.log where # is the test number. The complete set of results will be in a log file with # being the total number of tests.

Contributing

Contributions are welcome. Please see the CONTRIBUTING file for details, including the Code of Conduct and C Style Guide.

License

This project is licensed under the Apache-2.0 License. See the LICENSE file for details.