Clojure.MSBuild 0.0.8

Clojure.MSBuild

MSBuild integration for ClojureCLR. Build, test, and run Clojure on .NET with standard dotnet commands. No non-dotnet tools needed.

dotnet build AOT-compiles your namespaces and produces a standalone assembly whose entry point is a gen-class Main calling your -main. No C# in your project, no .cljr files needed at runtime.

Requirements

• .NET 11.0 SDK, 11.0.100-rc.1 or later
• Clojure CLR 1.12.6 or later

Quick Start with templates

dotnet new install Clojure.MSBuild.Templates
dotnet new clojure-clr-minimal-api -n orders --root-namespace constructly.se
cd orders
dotnet build
dotnet test
dotnet run

--root-namespace sets the root of the generated Clojure namespaces (constructly.se.server, constructly.se.routes, ...). It defaults to the project name in lower case (-n my-api gives my-api.server in src/my_api/). The templates live in templates/ and scripts/smoke-templates.sh generates, builds, tests and runs both.

Quick Start by hand

1. Create a project

dotnet new console -n MyApp
cd MyApp
rm Program.cs

The project must not contain C# sources: dotnet build replaces the project assembly with the compiled Clojure entry point (see How the build works).

2. Add packages

dotnet add package Clojure.MSBuild
dotnet add package Clojure --version 1.12.6

3. Update your .csproj

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net11.0</TargetFramework>
    <EnablePreviewFeatures>true</EnablePreviewFeatures>
    <ClojureMainNamespace>app</ClojureMainNamespace>
    <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Clojure.MSBuild" Version="0.0.8" />
    <PackageReference Include="Clojure" Version="1.12.6" />
  </ItemGroup>

  <ItemGroup>
    
    <Content Include="src/**/*.cljr" CopyToOutputDirectory="PreserveNewest" />
  </ItemGroup>

</Project>

4. Write your app

Create src/app.cljr:

(ns app)

(defn -main [& args]
  (println "Hello from ClojureCLR!"))

5. Build and run it

dotnet build
dotnet run

dotnet build compiles app (and every namespace it requires) to .dll files next to MyApp.dll, and MyApp.dll itself is the compiled entry point: a class named after the assembly with a static Main generated by gen-class that calls app/-main. dotnet MyApp.dll, ./MyApp and dotnet publish all use it.

How the build works

dotnet build runs the normal .NET SDK build plus one extra target, ClojureBuild:

1. GenerateClojureEntryPoint (before CoreCompile) writes two files into obj/: a tiny C# host, and the Clojure namespace clojure.msbuild.entry, which contains (:gen-class :name MyApp :main true) and a config map (main namespace, source directories, ClojureGitDep items). Its -main hands over to the packaged clojure.msbuild.bootstrap namespace, which sets CLOJURE_LOAD_PATH, pre-loads the assemblies next to the application, resolves git dependencies for tooling runs, and then either runs the --clj-mode tool or requires your main namespace and calls its -main.
2. The SDK compiles the C# host into MyApp.dll and copies it, the NuGet assemblies, MyApp.deps.json and MyApp.runtimeconfig.json to bin/. The host is a complete runnable application with all references, which is what makes step 3 possible.
3. ClojureBuild (after Build) runs MyApp.dll --clj-mode build, which AOT-compiles clojure.msbuild.entry, bootstrap, gitlibs and tool, your main namespace with everything it requires (git dependencies included), and ClojureNamespacesToCompile. Each namespace becomes a <namespace>.cljr.dll; gen-class emits MyApp.exe, an assembly named after the project with the entry point MyApp.Main. A compile error fails the build.
4. The compiled assemblies are copied to bin/ and MyApp.exe is copied over MyApp.dll. From then on dotnet run, dotnet MyApp.dll, the MyApp apphost and dotnet publish start at the gen-class Main, and .cljr sources are not needed at runtime.

Every build re-runs step 3, because the SDK copies the C# host to bin/ again on each build. The assemblies from the previous build are removed first, dotnet clean removes them, and dotnet publish publishes the compiled files instead of the C# host.

MyApp.dll --clj-mode <mode> is the tooling protocol used by the MSBuild targets and the test adapter: repl, nrepl, script <file>, test, test-vars <ns/name ...>, build <namespaces> <dir>.

Because the project assembly is replaced, the project cannot contain C# sources of its own and AssemblyName must be a valid .NET type name (letters, digits, _ and .; the templates take care of that). Put C# in a class library and reference it, or set ClojureEntryPoint to csharp to keep a generated C# Main as the entry point; Clojure is still AOT-compiled and the tooling works the same way.

Clojure Git Dependencies

Add Clojure libraries from git directly in your .csproj — no deps.edn needed:

<ItemGroup>
  
  <PackageReference Include="Clojure" Version="1.12.6" />
  <PackageReference Include="Microsoft.Data.Sqlite" Version="11.0.0-rc.1.26425.128" />

  
  <ClojureGitDep Include="io.github.clojure/clr.data.json" Tag="v2.5.1" Sha="f84cb88" />
  <ClojureGitDep Include="com.github.seancorfield/honeysql" Tag="v2.7.1368" Sha="b8332fc" />
</ItemGroup>

Repos are cloned to ~/.gitlibs (cached, compatible with cljr) when the build and tooling run; the compiled application contains the dependency namespaces and does not need git at runtime. Supports io.github, com.github, io.gitlab, and ht.sr prefixes for auto URL resolution. You can also specify a full URL:

<ClojureGitDep Include="my/lib" Tag="v1.0" Sha="abc123" Url="https://example.com/repo.git" />

A deps.edn file is also supported if you prefer the Clojure convention. Both sources merge.

Testing

Add the test adapter package:

dotnet add package Clojure.MSBuild.TestAdapter
dotnet add package Microsoft.NET.Test.Sdk

Add test content to your .csproj:

<Content Include="test/**/*.cljr" CopyToOutputDirectory="PreserveNewest" />

Create test files with the _test.cljr suffix in a test/ directory:

(ns app-test
  (:require [clojure.test :refer [deftest is testing]]))

(deftest test-addition
  (testing "math works"
    (is (= 4 (+ 2 2)))))

Run tests:

dotnet test

Every deftest and defspec is discovered and reported individually, with the first failing assertion as the failure message, so dotnet test --filter and IDE test explorers work as with any other .NET test project.

REPL

dotnet msbuild /t:clj-repl

nREPL

dotnet add package clojure.tools.nrepl --prerelease
dotnet msbuild /t:clj-nrepl

Connects on port 1667. Use Calva, CIDER, or any nREPL client.

Run a Script

dotnet msbuild /t:clj-run -p:File=path/to/script.cljr

AOT Compilation

The main namespace and everything it requires are compiled on every build. To compile additional namespaces (for example ones with their own gen-class), list them:

<PropertyGroup>
  <ClojureNamespacesToCompile>my.lib;my.utils</ClojureNamespacesToCompile>
</PropertyGroup>

Note: (t/await (f ...)) on a call to a Clojure ^:async function needs the call's static Task<T> type. Tag the call site, or attach the tag to the var (a return tag on a ^:async defn is not kept on the var):

(alter-meta! #'execute! assoc :tag (symbol "System.Threading.Tasks.Task`1[System.Object]"))

Configuration

Examples

• templates/content/minimal-api — the minimal API template: SQLite, HoneySQL, clojure.spec, OpenTelemetry, Docker, end-to-end tests
• templates/content/console — the console template
• examples/minimal-api — smaller ASP.NET web API with HoneySQL, async ADO.NET, integration tests
• examples/csharp-interop — Bidirectional C#/Clojure interop in one project (ClojureEntryPoint=csharp)

Releasing

scripts/pack.sh packs Clojure.MSBuild, Clojure.MSBuild.TestAdapter and Clojure.MSBuild.Templates into packages/; scripts/smoke-templates.sh verifies the templates end to end against freshly packed packages; NUGET_API_KEY=... scripts/release.sh packs and pushes all three to nuget.org.

License

MIT