Update & Deployment

This procedure describes how to update Arcadia's compiler or Clojure core source tree without introducing regressions. The compiler implementation and Clojure core source tree on the unity branch of this repository are the canonical ones, and the files that end up in Arcadia itself should be perceived as derived artifacts. Changes to the Clojure source tree in the Arcadia repository are ephemeral and will not survive a compiler update.

Set up

You will need the msbuild and make commands. msbuild is installed with Mono, and make is installed with your platform's standard compiler tools.

To get started, clone the arcadia/clojure-clr repository locally and check out the unity branch.

$ git clone https://github.com/arcadia-unity/clojure-clr.git
$ cd clojure-clr
$ git checkout unity

Building

After making changes to the C# implementation of the compiler or the Clojure source, you will have to rebuild the compiler. The ClojureCLR compiler is a network of interrelated C# projects that do not build correctly for Unity by default, so trying to build from e.g. your IDE will not work. The unity branch of our fork maintains a Makefile as a replacement.

You will need internet access the clojure.spec submodules. They are pulled from the master branches of arcadia-unity/clr.spec.alpha and arcadia-unity/clr.core.specs.alpha. The Makefile handles this automatically and no additional action is required.

The default target of the Makefile will build the whole compiler

$ make
Microsoft (R) Build Engine version 15.1.8.0 ( Wed Sep  5 19:29:56 UTC 2018) for Mono
Copyright (C) Microsoft Corporation. All rights reserved.

Build started 12/7/2018 12:37:38 PM.
Project "/home/nasser/projects/clojure-clr/arcadia.proj" on node 1 (default targets).
Project "/home/nasser/projects/clojure-clr/arcadia.proj" (1) is building "/home/nasser/projects/clojure-clr/Clojure/ClojureCLR.sln" (2) on node 1 (default targets).
ValidateSolutionConfiguration:
... many lines omitted for brevity ...
    6 Warning(s)
    0 Error(s)

Time Elapsed 00:00:13.71

A number of warnings is normal, but there should be zero errors. The compiled .dll files can be found in bin/4.0/Release and the final Clojure source tree can be found in bin/4.0/Release/clojure

Testing Locally

bin/4.0/Release/Clojure.Main.exe and bin/4.0/Release/Clojure.Compile.exe can be used for quick local tests or analysis with e.g. illness

$ mono bin/4.0/Release/Clojure.Main.exe
Clojure 1.10.0-master-SNAPSHOT
user=> 

$ cat foo.clj
(ns foo)

(defn a-function [a b c]
  (+ a b (* b c)))
$ mono bin/4.0/Release/Clojure.Compile.exe foo
Compiling foo to .8 -- 6 milliseconds.
$ illness foo.clj.dll bin/4.0/Release/
Illness 0.1.6855.21652
Ramsey Nasser, Jan 2016

Listening on http://localhost:2718/

Deploying into Arcadia

Updating Arcadia's Clojure installation involves a few things:

1. Replace all the *clj.dll files in Arcadia's Infrastructure folder with the *.clj.dll files from the compiler's bin/4.0/Release
2. Replace all the Microsoft*.dll files in Arcadia's Infrastructure folder with the Microsoft*.dll files from the compiler's bin/4.0/Release
3. Replace all the Clojure.dll files in Arcadia's Infrastructure folder with the Clojure.dll files from the compiler's bin/4.0/Release
4. Replace Arcadia's Source/clojure folder with the compiler's bin/4.0/Release/clojure folder

The unity branch has a deploy script that automates this. It expects a single argument, the path to the Arcadia repository to deploy to (i.e. the Arcadia folder under Assets in a Unity project).

$ ./deploy.sh /path/to/arcadia
deployed to /path/to/arcadia

Committing

Once a change is confirmed working and ready to be finalized, it must be committed into both the Compiler and Arcadia repositories.

1. Commit and push any changes to the compiler on the unity branch. Make a note of the commit hash.
2. Deploy the compiler files into Arcadia as described above. In the Arcadia repository, commit the changes to the Infrastructure and Source/clojure folders as a separate commit using the following commit message template:

<describe changes>

Brings in compiler built from arcadia-unity/clojure-clr@<compiler commit hash>

This connects the compiler's history to Arcadia's history and makes tracking down bugs down the line more reasonable.

Updating spec

Because of the circular dependency between the language and the spec library, updating spec must be treated differently. The canonical spec sources are in https://github.com/arcadia-unity/clr.spec.alpha and https://github.com/arcadia-unity/clr.core.specs.alpha and everything else is ephemeral.

To update spec

1. Commit and push changes to the appropriate canonical spec repository on the master branch
2. Run git submodule update in the compiler repository to pull in your changes
3. Commit the updated submodules in the compiler repository
4. Rebuild and redeploy the compiler as above
5. Make sure not to commit spec sources to the compiler source tree