Clojure.MSBuild 0.0.10

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 danger.se
cd orders
dotnet build
dotnet test
dotnet run

--root-namespace sets the root of the generated Clojure namespaces (danger.se.server, danger.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.10" />
    <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: clojure.msbuild.entry, the main namespace with everything it requires that is not already in the library layer, and ClojureNamespacesToCompile. It is incremental: when no Clojure source, the project file or the library layer changed, the step is skipped, and otherwise only the namespaces whose source changed are compiled again, together with the namespaces that require them (read from their ns forms, since macros, inlined functions, protocols and record types are compiled into the caller). Everything else loads from the previous build's assemblies. 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.

The library layer and the Clojure runtime (Clojure.dll) are also compiled to native code with crossgen2 (ReadyToRun). ClojureCLR emits IL, and loading clojure.core alone makes the runtime JIT-compile about 5000 methods, so without it every process (the build, the tests, the REPL, the application) spends about two seconds in the JIT before it starts; with it the runtime is up in about 0.6 s. The images still contain the IL, so they run anywhere, and the native code is only used on the platform that built it. crossgen2 is downloaded from NuGet (microsoft.netcore.app.crossgen2.<rid>, matching the target framework) the first time the library layer is built; without it (offline) the layer stays IL and a warning says so. An assembly crossgen2 cannot compile stays IL (crossgen2 11.0 RC crashes on proxy classes of TextWriter, so clojure.core-print and clojure.repl are JIT-compiled). Set ClojureReadyToRun to false to turn it off.

A build with no changes only copies the layers into bin/ (the SDK copies the C# host there on every build). dotnet clean removes both layers, and dotnet publish publishes the compiled files, and the ReadyToRun Clojure.dll, 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 [port], script <file>, test [ns ns/name ...], test-vars <ns/name ...>, test-watch [dirs], build-libs <lib-dir> <main-ns> <project-dirs> <shared-dir> <crossgen2> <Clojure.dll>, build <namespaces> <dir> <lib-dir> <project-dirs>. dotnet run -- --clj-mode test-watch works as well as the MSBuild targets.

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 in test/**/*_test.cljr (.cljc, .clj) is discovered and reported individually, so dotnet test --filter and IDE test explorers work as with any other .NET test project. A failed test shows every failing assertion with its testing context, expected and actual value; an error shows the exception, its ex-data and stack trace; both point at the test's source line. What a test prints is attached to its result, and a test namespace that does not compile fails its tests with the compiler error.

Without VSTest, the tests run faster and print clojure.test's report:

dotnet msbuild /t:clj-test
dotnet msbuild /t:clj-test -p:ClojureTests="app-test app-test/test-addition"

Watch mode runs the tests, then keeps the process running and, whenever you save a file, reloads the namespaces that changed and the ones that depend on them, and runs only the tests that depend on the change (a test file on its own reruns in milliseconds):

dotnet run -- --clj-mode test-watch
# or
dotnet msbuild /t:clj-test-watch

REPL

dotnet msbuild /t:clj-repl

nREPL

dotnet add package clojure.tools.nrepl --prerelease
dotnet msbuild /t:clj-nrepl
# or
dotnet run -- --clj-mode nrepl

The server listens on 127.0.0.1 and ::1, port 1667 (-p:ClojureNReplPort=7888 picks another, 0 any free one; if 1667 is taken a free port is used), and writes the port to .nrepl-port in the project directory, where Calva, CIDER and other clients look for it. The file is removed when the server stops (Ctrl-C). The server is precompiled into the library layer, so it is up in about two seconds.

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 when they change. 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)
• examples/orleans-actors-ants-demo — Microsoft Orleans actors from Clojure with a GenServer-style defactor DSL: the ant colony simulation
• examples/orleans-bank-demo — a bank on Orleans and PostgreSQL that survives kill -9 of its silos: accounts as append-only journals with the balance at any moment in one index lookup, transfers as sagas driven by reminders, and a deterministic simulation of the cluster as a property test

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