ghūl compiler

This is the compiler for the ghūl programming language. It is a self-hosting compiler: the compiler itself is written entirely in ghūl.

Prerequisites

The compiler requires the .NET 10 SDK. The SDK includes the .NET 10 runtime that the compiler tool itself runs on, and will fetch reference packs for any target framework you build against on demand.

Target

The compiler produces standard .NET assemblies and packages targeting .NET 10 by default. Earlier target frameworks work too — set <TargetFramework>net8.0</TargetFramework> (or similar) in your .ghulproj and pin ghul.runtime to a net8.0-compatible release (e.g. 3.0.19), since the 4.x line is net10.0-only.

Getting the compiler

There are a few different ways to get the compiler

Use a ghūl .NET project template

If you initialize your project using one of the ghūl .NET project templates, the template will add the compiler to your project folder as a local .NET tool - just run dotnet tool restore to restore it.

Clone the ghūl GitHub repository template

If you create a new GitHub repo from the ghūl repository template, then the compiler will be pre-configured as a local .NET tool in your project folder - run dotnet tool restore to restore it.

Install the compiler as a local or global .NET tool

You can manually install the compiler from the ghūl compiler .NET tool package

Using the compiler

Project file

The compiler expects to be driven by MSBuild using a .ghulproj project file. See the ghūl test project for a real-world example, or use one of the project templates to get started.

Source files

You'll need some ghūl source files. By convention ghūl source files have the extension .ghul, and the standard MSBuild targets will include **/*.ghul when building.

Building and running

Once you have a project file and some ghūl source files, you can use the normal .NET SDK commands to build, pack, and run your project:

dotnet build

dotnet pack

dotnet run

Runtime dependencies for ghūl applications

Applications written in ghūl require the .NET runtime matching whatever target framework you built for — the .NET 10 runtime by default, or e.g. the .NET 8 runtime if you targeted net8.0.

Development environment

Visual Studio Code

Visual Studio Code will give you rich language support via the ghūl VSCode language extension.

Dev container

Any dev container image with the .NET 10 SDK will do — for example mcr.microsoft.com/devcontainers/dotnet:10.0. Pin ghul.compiler in your project's local .NET tool manifest and the compiler will be restored automatically when the container starts. A minimal worked example is in this gist.

Basic ghūl language tutorial

For a short ghūl programming language tutorial and reference, see GHUL.md in this repository. For more ghūl language details, see the the ghūl programming language website

Gotchas

The ghūl language is sufficiently expressive and the compiler is stable enough for the compiler itself to be written in ghūl. Like any compiler it has bugs — issue reports are welcome.