Clojure.MSBuild.TestAdapter 0.0.9

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.9" />
    <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) AOT-compiles the Clojure code in two layers, using the host: MyApp.dll --clj-mode build-libs and MyApp.dll --clj-mode build.
   • The library layer (obj/.../clj-lib/) holds everything that is not project code: clojure.core and the standard library, NuGet Clojure libraries, git dependencies and the Clojure.MSBuild tooling. ClojureCLR ships all of these as source and compiles them at every process start, which costs about 12 seconds before the first line of your code runs, so the build compiles them once. The layer is rebuilt only when the dependencies (project.assets.json), the generated entry namespace, deps.edn or Clojure.MSBuild itself change, or after dotnet clean. It is filled by loading your main namespace and your test namespaces, so it also covers test-only libraries.
   • The build layer (obj/.../clj-out/) holds your own namespaces and is recompiled on every build: clojure.msbuild.entry, the main namespace with everything it requires that is not already in the library layer, and ClojureNamespacesToCompile. A dependency that is loaded from source here is moved to the library layer afterwards. 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 in project code fails the build; a library that cannot be precompiled is reported as a warning and loaded from source at runtime instead.
4. Both layers 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 from precompiled code in a couple of seconds, and .cljr sources are not needed at runtime.

The part of the library layer that depends only on the Clojure and Clojure.MSBuild versions (clojure.core, the standard library, the tooling) is shared between projects through ~/.clojure-msbuild/lib-cache/, so the first build of a new project only compiles its own dependencies. Set ClojureLibCacheDir to move the cache or ClojureLibCache to false to keep everything inside the project. The minimal API template's Dockerfile mounts the cache.

Every build re-runs the build layer, because the SDK copies the C# host to bin/ again on each build. The previous build layer is removed first, dotnet clean removes both layers, 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-libs <lib-dir> <main-ns> <project-dirs> <shared-dir>, build <namespaces> <dir> <lib-dir> <project-dirs>.

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