KS project consists of several subprojects, each of which has its own repository:

  • compiler — everything starts here, this is the core of the project that everything uses

  • tests — used to prove that compiler behaves as expected and there are no regressions introduced by the changes

  • runtimes, one per each target language — used by the code generated by a compiler

  • documentation — keeps users informed about the language and all new features

  • console visualizer and tools: ksv, ksdump

Technically, one can download and work with each of these subprojects individually, but most people just download everything by checking out our main umbrella project that includes (almost) everything:

git clone --recursive https://github.com/kaitai-io/kaitai_struct.git

Note the --recursive option, which would download all the submodules. If you forgot it and cloned without it, you can still do it manually after cloning:

git submodule update --init --recursive


KS compiler is written in Scala language and thus uses SBT for building. It can be compiled in one of 2 ways, each of which can be packaged in one of several ways:

  • generating Java .class files, to be run in JVM

    • not packaged, ready to be ran from a build dir (so called "stage build")

    • packaged as universal (.zip) package

    • packaged as Debian (.deb) package

    • packaged as Windows (.msi) installer package

  • generating JavaScript .js file, to be run either inside a browser or in node.js environment

    • not packaged, used as a source JS file on a website

    • packaged as npm package


To build the compiler, one generally needs just these two things:

  • Java Runtime Environment (JRE)

  • Scala Build Tool (sbt)

For Debian/Ubuntu, this should be enough to download every prerequisite (JRE is pulled automatically by sbt):

echo "deb https://dl.bintray.com/sbt/debian /" | sudo tee -a /etc/apt/sources.list.d/sbt.list
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 2EE0EA64E40A89B84B2DF73499E82A75642AC823
sudo apt-get update
sudo apt-get install sbt

Manual installation:

You don’t need whole Java Development Kit (JDK), unless you want to test & develop for Java target — just JRE is enough for KS compiler.

All other dependencies (including Scala runtimes, compilers, etc) required for the compiler are downloaded and installed by sbt automatically. It shouldn’t really matter even which version of sbt you use for bootstrap, as sbt will pull relevant sbt update packages automatically as well.

Building for JVM

We use sbt-native-packager to build deployable formats. Note that in order to perform the following builds, one must be in the kaitai_struct/compiler directory.

Building an universal (.zip) package

  1. sbt compilerJVM/universal:packageBin

  2. Get result in jvm/target/universal/kaitai-struct-compiler-*.zip

Building Debian package

  1. Install prerequisites: sudo -i apt-get install dpkg dpkg-sig dpkg-dev lintian fakeroot

  2. sbt compilerJVM/debian:packageBin

  3. Get result in jvm/target/kaitai-struct-compiler_*_all.deb

Building Windows package

  1. Install WIX

  2. sbt compilerJVM/windows:packageBin

  3. Get result in jvm/target/windows/kaitai-struct-compiler.msi

  4. Rename to add version to kaitai-struct-compiler-$VERSION.msi

Building for JavaScript platform

Building to JavaScript platform is done using a Scala.js project. Note that it uses a somewhat different set of dependencies, as they must actually be JavaScript libraries, not Java jars.

  1. Run sbt fastOptJS

  2. Get result in js/target/scala-2.11/kaitai-struct-compiler-fastopt.js

  3. Use this JavaScript file on a website

Publishing a new version

  1. Choose a new version number (WIX imposes harsh requirements for version to look like x.x.x.x) and update it in build.sbt, version := …​, commit

  2. Prepare an entry in RELEASE_NOTES.md, commit

  3. Create version tag:

    • git tag $VERSION

    • git push --tags

  4. Update [main repository](https://github.com/kaitai-io/kaitai_struct)

  5. Create new version at:

  6. Upload:

  7. Publish them all








  • Pump version in kaitaistruct.py, seek version =

  • python3 setup.py sdist upload

    • (use python3 setup.py sdist upload -r pypitest to publish to testing server)

  • Check that new version appears at https://pypi.python.org/pypi/kaitaistruct/$VERSION

  • git tag $VERSION

  • git push --tags



  • Pump version in lib/kaitai/struct/struct.rb, seek `VERSION = `

  • gem build kaitai-struct.gemspec

  • Test gem (i.e. by installing it to a live system)

  • gem push kaitai-struct-$VERSION.gem

  • git tag $VERSION

  • git push --tags

Adding new language

Overall routine for adding new language is described in Adding support for new target language.

After addition, don’t forget to update lists of languages: