Skip to content

Setup a local development environment

This has been tested on Ubuntu 20 and 24 systems, and Ubuntu 22 under Windows Subsystem for Linux with Windows Server 2022.

It is recommended to use VSCode with the Scala Metals extension to be able to do live step by step debugging on the scala code. Also, the repository contains a .vscode folder with the recommended settings for the project, in particular a launch.json file that allows you to debug the C++ code generated by the compiler using the debug_tests.cpp file in the tests/ folder.

Install Kaitai compiler

We won't be using the official Kaitai compiler because we will be building our own, but it is the easiest way to get all the runtime libraries.

See the Kaitai docs, at the moment:

curl -LO https://github.com/kaitai-io/kaitai_struct_compiler/releases/download/0.10/kaitai-struct-compiler_0.10_all.deb
sudo apt-get install ./kaitai-struct-compiler_0.10_all.deb

Install Java

The default Java in Ubuntu 24 is Java 21, that does not work. You need to install Java 17, which is in the default repositories:

sudo apt install openjdk-17-jdk

also make sure there are no other versions of Java installed:

sudo apt remove openjdk-21*

Install SBT

Follow the instructions at https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Linux.html#Ubuntu+and+other+Debian-based+distributions to install SBT.

Setup the Python environment

Checkout the repository:

git clone https://github.com/det-lab/kaitai_struct_awkward_runtime

Create a virtual environment and install the package:

sudo apt install python3-venv
python3 -m venv .env
pip install -e .

Run the tests

source .env/bin/activate
make test

See the documentation in the Makefile to understand each step in the process.

Test the build step of a single file

When working on the compiler it is useful to force compilation of a single test case, this assumes that you are using an IDE which is already taking care of building local/bin/awkward-kaitai-build:

source .env/bin/activate
export testcase=simple_enum
make compile_test