xic-clj

A rewrite of xic (Cornell compilers project) in clojure, as a comparison with the original Java implementation.

development

just will compile java source files and start a repl (equiv. to just dev and just repl).

To invoke the compiler command-line during local development, use:

$ just xic [options] <source-files>

Run just xic --help to see all command-line options.

This command is different from ./xic [options] <source-files>. Running just xic will invoke clojure dynamically in the local environment via clj after executing the compilation step to ensure that java source files are available to the local clojure environment. Running ./xic will attempt to invoke the executable jar which is the output of the full build. This script is primarily intended to be used by test harness, which is described below.

testing

$ just e2e

E2E tests utilize the test harness provided by the course staff for the original project. This test harness is configured to look for entry points xic-build to build the compiler and xic to invoke it. Thus these files are thin wrappers over the tasks defined in the Justfile. E2E testing operates on the fully built uberjar as opposed to the local clojure dev environment.

deployment

just build produces an uberjar inside of the build/ directory which can be run via java -jar.

default readme content (outdated)

██████╗ ██████╗  █████╗  ██████╗████████╗██╗ ██████╗ █████╗ ██╗     ██╗     ██╗
██╔══██╗██╔══██╗██╔══██╗██╔════╝╚══██╔══╝██║██╔════╝██╔══██╗██║     ██║     ██║
██████╔╝██████╔╝███████║██║        ██║   ██║██║     ███████║██║     ██║     ██║
██╔═══╝ ██╔══██╗██╔══██║██║        ██║   ██║██║     ██╔══██║██║     ██║     ██║
██║     ██║  ██║██║  ██║╚██████╗   ██║   ██║╚██████╗██║  ██║███████╗███████╗██║
╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝   ╚═╝   ╚═╝ ╚═════╝╚═╝  ╚═╝╚══════╝╚══════╝╚═╝

Project Status

TODO: add status badges for https://github.com/David/{{scm/repo}} workflows and issues

TODO: Provide a meaningful description of the project

Project created with deps-new and the practicalli/application template

Run the service

Run the service (clojure.main)

clojure -M:run/app

Run the greet function (clojure.exec), optionally passing a :name key and value as arguments

clojure -X:run/greet :team-name '"team name"'

Development

Practicalli workflow overview:

• start a REPL process in a Terminal
• open the project in a Clojure Editor and connected to the REPL
• write code and evaluate expressions in the editor using the source code files

Practicalli Clojure CLI Config should be used with this project to support all aliases used.

This project uses make tasks to run the Clojure tests, kaocha test runner and package the service into an uberjar. The Makefile uses clojure commands and arguments which can be used directly if not using make.

make command in a terminal will list all the tasks available

make

Run Clojure REPL

Start the REPL with the Practicalli REPL Reloaded aliases to include the custom user namespace (dev/user.clj) which provides additional tools for development (Portal data inspector, hotload libraries, namespace reload)

make repl

The local nREPL server port will be printed, along with a help menu showing the REPL Reloaded tools available.

Evaluate the dudelson.xic-clj namespace and a mulog publisher will start, sending pretty printed events to the console. Evaluate (mulog-publisher) to stop the mulog publisher.

Call the -main function with or without an argument, or call the greet function directly passing an optional key and value pair.

(namespace/refresh) will reload any changed namespaces in the Clojure project.

Clojure Editor

If a REPL has been run from a terminal, use the editor *connect- feature.

Otherwise, use the :dev/reloaded alias from Practicalli Clojure CLI Config to starting a REPL process from within a Clojure editor.

Unit tests

Run unit tests of the service using the kaocha test runner

make test

If additional libraries are required to support tests, add them to the :test/env alias definition in deps.edn

make test-watch will run tests on file save, stopping the current test run on the first failing test. Tests will continue to be watched until Ctrl-c is pressed.

Format Code

Check the code format before pushing commits to a shared repository, using cljstyle to check the Clojure format, MegaLinter to check format of all other files and kaocha test runner to test the Clojure code.

Before running the pre-commit-check

• install cljstyle{target=_blank}
• MegaLinter runs in a Docker container, so ensure Docker is running

make pre-commit-check

Run cljstyle only

• make format-check runs cljstyle and and prints a report if there are errors
• make format-fix updates all files if there are errors (check the changes made via git diff)

Run MegaLinter only

• make lint runs all configured linters in .github/config/megalinter.yaml
• make lint-fix as above and applies fixes

Run Kaocha test runner only

• make test runs all unit tests in the project, stopping at first failing test
• make test-watch detect file changes and run all unit tests in the project, stopping at first failing test

Deployment

Build an uberjar to deploy the service as a jar file

make build-uberjar

• make build-config displays the tools.build configuration
• make build-clean deletes the build assets (target directory)

make docker-build

• make docker-down shuts down all services started with docker-build
• make docker-build-clean

Or build and run the service via the multi-stage Dockerfile configuration as part of a CI workflow.

License

Copyright © 2024 David

Creative Commons Attribution Share-Alike 4.0 International