Blech is a language for developing reactive, real-time critical embedded software. This open source project implements a compiler which translates Blech to C. More information can be found on the Blech homepage.

The software is not ready for production use. It has neither been developed nor tested for a specific use case. However, the license conditions of the applicable Open Source licenses allow you to adapt the software to your needs. Before using it in a safety relevant setting, make sure that the software fulfills your requirements and adjust it according to any applicable safety standards (e.g. ISO 26262).

Clone the project using

git clone https://github.com/blech-lang/blech

To build the project, you need .Net installed. Go to the Microsoft Download .NET page and follow the instructions to install .Net 6.0 LTS available for your operating system.

Navigate to the folder where you have checked out the Blech project. It should contain the file Blech.sln. Now you have choices:

• For a simple debug build run

  dotnet build
  

  This creates ./src/blechc/bin/Debug/net6.0/blechc.dll. Use the dotnet command to start the compiler like so

  dotnet ./src/blechc/bin/Debug/net6.0/blechc.dll
  

• For a release build additionally use the -c Release option.

• Finally, for a release build, which is operating system dependent, you need to run dotnet publish with a specific runtime identifier like so

  dotnet publish -c Release -r win-x64 --self-contained
  

  For Linux use something like linux-x64 or linux-arm64, for MacOS osx-x64 for Intel or osx-arm64 for Apple silicon. See the .NET RID Catalog for details.

  This creates a folder named with your chosen runtime id, e.g. ./src/blechc/bin/Release/net6.0/win-x64/publish which contains all files needed for execution. The folder as a whole can be moved arbitrarily. Inside the folder invoke the binary.

  blechc
  

  to run the Blech compiler.

  For MacOS you might need to enable the execution of binaries from the terminal. Goto Security & Privacy -> Developer Tools and allow Terminal.app to execute binaries.

In order to run the unit tests execute

dotnet test

This includes parser, name resolution, type checking and causality checking tests. If you use VisualStudio 2017 or later, you can open the solution file and build the project from within VisualStudio. You can also run the unit tests provided you have installed the NUnit3 Test Adapter plugin.

Code generation, however, is tested separately outside this framework. There are several subfolders for codegeneration tests. In ./test/blechc invoke

dotnet run -- programs tmp/programs

to run the tests for general programs.

This (upon first invocation) will interactively create a config file, and then compile every file in codegeneration to C, compile that to an executable, run it, and compare the resulting trace with the specified trace. In this way we ensure that changes to our backend do not change the behaviour of the generated files.

The batch script testCodegenerationAll.bat automates this testing process on Windows. It ensures that the program is executed from the Developer Command Prompt, that generated files from previous runs are deleted and calls the test framework on every folder.

The shell scipt testCodegnerationAll.sh does the same for MacOS and Linux.

Assuming you have a binary of the Blech Compiler blechc for your operating system, or you have built the Blech project yourself from sources, this sections tells you how to use it.

If the blechc binary is in your $PATH, you can invoke the compiler by simply writing

blechc

on the command line interface. If you do not have a standalone (publish) build and want to use your local Debug (or Release) build, use the dotnet command to start the compiler from your blech working directory.

dotnet <path-to>/blech/src/blechc/bin/Debug/net6.0/blechc.dll

From here on out we assume blechc to be a synonym for either call above

Typical invocations:

• blechc someBlechFile.blc
  

  Translates someBlechFile.blc to C code silently. You will only see output on the command line if there are problems with the translation. This will generate a file blech.c in the same folder which contains a runnable program. It runs in a main loop and calls the entry point activity of someBlechFile.blc 60 times. Furthermore in the subfolder ./blech two files are generated someBlechFile.c and someBlechFile.h. They contain the C code and interface declarations respectively.

• blechc -v d someBlechFile.blc
  

  Does the same as above but prints out textual representations of intermediate compilation results including: typed syntax tree, control flow graphs and block graphs for activities, C code.

• blechc --dry-run someBlechFile.blc
  

  Run through all compilation phases but do not write any C files. This is useful to check for problems without actually touching anything on the file system.

The compiler can generate a test program with trace output using the following options:

blechc --app --trace someBlechFile.c

By default this produces a main program in blech.c which can be used as a first test. To compile this code you need to include Blech specific C header files. These are located in <path-to>/blech/src/blechc/include. On Windows C compilation may look like this.

mingw32-cc.exe -I. -I<path-to>/blech/src/blechc/include blech.c

Note that the current folder . is explicitly added as a path to be included.

The resulting executable will run the program for 60 reactions and print the variable evaluations after every reaction in JSON format.

To include the generated C code in your own project inspect blech.c for details. In particular, make sure you call the init function on initial startup and then tick with every reaction. For programmers familiar with Arduino these correspond to the setup and loop functions.

The Blech compiler is open-sourced under the Apache-2.0 license. See the LICENSE file for details.

For a list of other open source components included in the Blech compiler, see the file 3rd-party-licenses.txt.