40 Development
How to set up a development environment, run tests, author notebooks, and release new versions.
REPL Setup
Start an nREPL server with the :dev alias, which adds notebooks, tests, Clay, and related dependencies to the classpath. One way to start the server is the following:
clojure -M:dev -m nrepl.cmdlineConnect to the REPL from your editor (Calva, CIDER, Cursive, or another) using the port printed to the console (also written to .nrepl-port).
Namespace Structure
The source is split by pipeline stage (see Architecture). In the diagram, an arrow runs from a namespace to a namespace it requires, and the dashed arrow points to a namespace that is loaded the first time it is needed. The diagram leaves out helper namespaces such as impl/text.clj and impl/rowid.clj.
impl/pose.clj holds the pose operations: resolve-tree (merges mappings, data and options from the root down to every leaf), elaborate (writes in what the draft chooses), expand-facet-nodes (a facet over columns as cells), fit-layers (the cells of a composite, or of a facet over columns, that draw each layer), shared-axis-groups (which cells share an axis), and leaf->draft (the leaf flattening that the public pj/pose->draft calls).
impl/compositor.clj handles composite framing layout, composite-pose->draft, and composite-draft->plan β pure data-side, no membrane dependency.
impl/plan.clj holds the leaf-plan computation (domains, ticks, legends, layout) that the public pj/draft->plan calls.
impl/layout.clj sizes the canvas: the room the axes, titles and legends take, and the size of each panel. impl/frames.clj turns a plan into the rectangles each panel occupies on the canvas, which pj/frames returns.
impl/membrane.clj defines the PlotjeMembrane record, the value of the membrane stage.
impl/resolve.clj defines the Plan, CompositePlan, LeafDraft, CompositeDraft, PlanLayer, and LayerType records, and holds resolve-draft-layer (single draft layer resolution, column type inference, grouping).
The impl/ directory holds data with no Membrane dependency, except impl/membrane.clj, whose PlotjeMembrane is a Membrane component by definition. The render/ directory uses Membrane for drawing and for SVG and raster conversion; render/bufimg.clj, the raster backend, is loaded the first time a :bufimg or :png plot is rendered. render/composite.clj carries the composite plan->membrane defmethod and the membrane drawables for composite framing (title, strip labels, shared legend).
Running Tests
The test suite runs via cognitect test-runner:
./run_tests.shThis is equivalent to:
clojure -M:dev:test -m cognitect.test-runnerThere are two kinds of tests:
Hand-written tests in
test/scicloj/plotje/β unit tests for core logic (pose resolution, plan resolution, rendering, and more)Generated tests in
test/plotje_book/β produced from notebooks every time Clay renders notebooks using Clayβs test generation. Everykind/test-lastform in a notebook becomes an assertion in the corresponding*_generated_test.cljfile.
Regenerating Tests
After editing a notebook, you may regenerate its test file by rendering it:
(require '[dev :as dev])
(dev/make-gfm! "plotje_book/relationships.clj")This updates test/plotje_book/relationships_generated_test.clj. The generated test files are checked into version control.
To regenerate all notebooks at once:
(require 'dev)
(dev/make-gfm!) ; in Github Flavored Markdown format
;; or:
(dev/make-book!) ; as an HTML bookBuilding the Book
The full HTML book is rendered through Clay and Quarto:
(require '[dev :as dev])
(dev/make-book!)Chapter ordering is defined in notebooks/chapters.edn. The output goes to the docs/ directory and is published to scicloj.github.io/plotje.
Generating the README
The README.md is generated from notebooks/readme.clj using Clayβs GFM (GitHub-Flavored Markdown) output. The notebook contains live code examples that produce SVG plots, so the README always shows current output.
(require '[dev :as dev])
(dev/make-readme!)This produces:
README.mdat the repository rootreadme_files/*.svgβ rendered plot images referenced by the README
The bookβs index.clj reads README.md and copies readme_files/ into notebooks/ so that the bookβs front page shows the same images. Run make-readme! before make-book! when the README content changes.
Building a JAR
The build uses tools.build with deps-deploy:
clojure -T:build ci # run tests + build JAR
clojure -T:build ci :snapshot true # build snapshot JARThe JAR is written to target/.
Deploying to Clojars
Two convenience scripts handle the full build-and-deploy workflow:
./release.sh # test + build + deploy release
./snapshot.sh # test + build + deploy snapshotBoth run tests first, then build the JAR, then deploy to Clojars. Deployment requires CLOJARS_USERNAME and CLOJARS_PASSWORD environment variables (or a ~/.m2/settings.xml with credentials).
Continuous Integration
GitHub Actions runs the test suite on every push and pull request to main (see .github/workflows/tests.yml). The workflow uses Java 21 (Temurin) and the latest Clojure CLI.