tooling

The ghūl compiler is a .NET tool, and ghūl projects are ordinary .NET SDK projects. This means most of the tooling you already use for .NET applies directly, with a language extension on top for editing.

the compiler

The compiler is published as the ghul.compiler .NET tool. Once installed it is invoked as dotnet ghul-compiler.

You don't usually run the compiler by hand. ghūl projects are built with MSBuild through a .ghulproj project file, and the ghul.runtime package supplies the MSBuild targets that drive the compiler for you. See creating a project below for setting one up.

The compiler is normally installed as a local .NET tool, pinned per project in .config/dotnet-tools.json, so everyone building the project uses the same compiler version. dotnet tool restore restores it.

building and running

Because a ghūl project is a normal .NET SDK project, the standard dotnet commands all work:

dotnet build   # compile the project
dotnet run     # build and run an executable project
dotnet pack    # produce a NuGet package
dotnet test    # run a test project

A ghūl project can reference NuGet packages, produce libraries or executables, and be packed and published exactly like a C# project.

diagnostics

Every warning has a slug, shown in its message. A slug can be silenced with @suppress("<slug>") on a declaration, a whole file, or the project, or re-levelled on the compiler command line: --warn-as-hint <slug,…> downgrades matching warnings to editor-only hints that never appear in a batch build, and --warn-as-info <slug,…> downgrades them to informational diagnostics that still show in a build. Suppression wins over a demotion.

the Visual Studio Code extension

The ghūl language extension provides rich language support while you edit:

• errors and warnings reported as you type
• code completion
• hover information
• go to definition and find references
• rename
• signature help
• source code formatting

Behind the scenes the extension runs the ghūl compiler in its analysis mode: the compiler stays resident, maintains an up-to-date analysis of your project, and updates it as you edit, reporting diagnostics back into the editor.

On large projects the extension updates this analysis in two stages: a quick partial pass over the file you are editing, followed by a full pass once you pause. This is usually invisible, though it does mean a diagnostic can occasionally appear or disappear a moment after an edit.

other editors

The extension's language support lives in a standalone Language Server Protocol server with no dependency on the VS Code API. It ships as the ghul-language-server archive attached to every ghul-vsce release, and it speaks stdio by default, so any editor with an LSP client can drive it - it has been tested with Micro, for example. Download the .tgz from the latest release, install it with npm install, and point your editor's LSP client at the ghul-language-server launcher it provides.

dev containers

The ghūl repository template and the examples repo both ship a .devcontainer configured to use a standard .NET 10 dev container image - for example mcr.microsoft.com/devcontainers/dotnet:10.0. Open the project in VS Code with the Dev Containers extension, or in a GitHub Codespace, and dotnet tool restore will install the compiler from the local tool manifest. Any image with the .NET 10 SDK and dotnet on the PATH will work.

creating a project

from a project template

The ghul.templates package adds ghūl project templates to the .NET SDK:

dotnet new install ghul.templates

Once installed, dotnet new can scaffold a ghūl project pre-configured with a .ghulproj, the compiler pinned as a local tool, and a starting source file.

from the repository template

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

from scratch

The compiler expects to be driven by MSBuild using a .ghulproj project file. See the ghūl test project for a real-world example.

Directory.Build.props

<Project>
  <PropertyGroup>
    <Version>0.1.0-alpha.1</Version>
  </PropertyGroup>

  <ItemGroup>
    <!--
      ghul.runtime provides MSBuild targets required to drive the 
      ghul compiler
     -->
    <PackageReference Include="ghul.runtime" Version="9.0.0" />
  </ItemGroup>
</Project>

example.ghulproj

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>

    <GhulCompiler>dotnet ghul-compiler</GhulCompiler>
  </PropertyGroup>

  <ItemGroup>
    <GhulSources Include="src/**/*.ghul" />
  </ItemGroup>
</Project>

By convention ghūl source files have the extension .ghul, and the ghul.runtime provided MSBuild targets will include **/*.ghul when building.

To pin the compiler as a local tool in the project folder, so everyone building the project gets the same compiler:

dotnet new tool-manifest
dotnet tool install --local ghul.compiler --version 28.0.1

The compiler can also be installed globally instead, from the ghūl compiler .NET tool package:

dotnet tool install --global ghul.compiler

runtime dependencies for ghūl applications

Applications written in ghūl require the .NET 10 runtime.