Getting started: setup and workflow

Prerequisites

The Skir compiler requires Node.js to be installed.

Setting up a project

Initialize a project

From your project directory, run:

npx skir init

This command creates:

• skir.yml: the Skir configuration file
• skir-src/hello_world.skir: an example .skir file

Configure code generation

The skir.yml file controls how Skir generates code for your project. Here's an example:

# skir.yml

generators:
  - mod: skir-cc-gen
    outDir: ./app/src/skirout
    config:
      writeGoogleTestHeaders: true
  - mod: skir-typescript-gen
    outDir: ./frontend/skirout
    config: {}

All paths are relative to the directory containing skir.yml (the root directory).

Every generator entry has the following properties:

• mod: Identifies the code generator to run (e.g., skir-python-gen for Python).
• outDir: The output directory for generated source code (e.g., ./src/skirout). The directory must be named skirout. If you specify an array of strings, the generator will write to multiple output directories, which is useful when you have multiple sub-projects in the same language.
• config: Generator-specific configuration. Use {} for default settings.

Output directory location

Typically, you should place the skirout directory at the root of your sub-project's source tree. However, placement varies by ecosystem to ensure idiomatic results:

• TypeScript: It's often more convenient to place skirout adjacent to the src directory.
• Java / Kotlin / Python: Place the directory inside your top-level package (e.g., src/main/java/com/myproject/skirout). This ensures generated package names (like com.myproject.skirout.*) follow standard naming conventions.

Multiple generators can write to the same output directory, which means this directory will contain source files in different languages.

Core workflow

Run Skir code generation before compiling your language-specific source code.

npx skir gen

This command transpiles your .skir files into the target languages specified in your configuration. This creates or updates your skirout directories containing the generated source code.

For a more seamless experience, consider using watch mode:

npx skir gen --watch

The compiler will monitor your source directory and automatically regenerate code whenever you modify a .skir file.

{
  "scripts": {
    "prebuild": "skir gen",
    "build": "tsc"
  }
}

Formatting .skir files

Use npx skir format to format all .skir files in your project.

Continuous integration (GitHub)

We recommend adding skirout to .gitignore and running Skir code generation in your GitHub workflow. GitHub's hosted runners (Ubuntu, Windows, and macOS) come with Node.js and npx pre-installed, so you only need to add one step:

- name: Run Skir codegen
  run: npx skir gen

If you have a formatting check step, it may fail on Skir-generated code. You can either run the formatting check before Skir codegen, or configure your formatter to skip skirout directories.

Consider adding these optional steps for stricter validation:

- name: Run Skir format checker
  run: npx skir format --ci

- name: Ensure Skir snapshot up-to-date
  run: npx skir snapshot --ci

The first step ensures .skir files are properly formatted. The second step verifies that you ran npx skir snapshot before committing. See the Schema evolution & compatibility guide for more information about the snapshot command.

IDE support

The official VS Code extension for Skir provides syntax highlighting, auto-formatting, validation, jump-to-definition, and other language features.