ghūl programming language

# getting started

Examples: if you just want to see some ghūl code examples and maybe experiment with writing some ghūl, then start with the ghūl examples repository (opens new window). The examples project is ready to open in a devcontainer, or a GitHub Codespace.

# prerequisites

The ghūl programming language compiler requires the .NET 8.0 SDK (opens new window)

# target

The compiler produces standard .NET assemblies and packages targeting .NET 8.0

# getting the ghūl 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 (opens new window), 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 (opens new window), then the compiler will be pre-configured as a local .NET tool in your project folder - run dotnet tool restore to restore it.

# use the ghūl development container image

The compiler is pre-installed globally in the ghūl development container (opens new window)

# install the compiler as a local or global .NET tool

You can manually install the compiler from the ghūl compiler .NET tool package (opens new window)

# using the compiler

# project file

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

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="1.3.3" />
  </ItemGroup>
</Project>

example.ghulproj

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

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

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

# source files

You'll need some ghūl source files. By convention ghūl source files have the extension .ghul, and the ghul.runtime provided 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 8.0 (opens new window) runtime

# development environment

# Visual Studio Code

Visual Studio Code (opens new window) will give you rich language support via the ghūl VSCode language extension (opens new window).

# other editors

The ghūl language extension implementation (opens new window) is currently tightly coupled to the Visual Studio Code extension API. However under the hood it is using the Language Server Protocol (opens new window) so could be extended to support other clients. Feel free to submit a PR.

← language basics →