https://github.com/dudelson/xic-clj
Rewrite of CS4120 compiler project in Clojure
https://github.com/dudelson/xic-clj
Last synced: about 1 year ago
JSON representation
Rewrite of CS4120 compiler project in Clojure
- Host: GitHub
- URL: https://github.com/dudelson/xic-clj
- Owner: dudelson
- Created: 2024-12-17T04:18:10.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-12-18T01:38:45.000Z (over 1 year ago)
- Last Synced: 2025-05-03T04:40:03.182Z (about 1 year ago)
- Language: Clojure
- Size: 3.55 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# xic-clj
A rewrite of xic ([Cornell compilers project](https://www.cs.cornell.edu/courses/cs4120/2018sp/)) 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] `
Run `just xic --help` to see all command-line options.
This command is different from `./xic [options] `. 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)
```none
██████╗ ██████╗ █████╗ ██████╗████████╗██╗ ██████╗ █████╗ ██╗ ██╗ ██╗
██╔══██╗██╔══██╗██╔══██╗██╔════╝╚══██╔══╝██║██╔════╝██╔══██╗██║ ██║ ██║
██████╔╝██████╔╝███████║██║ ██║ ██║██║ ███████║██║ ██║ ██║
██╔═══╝ ██╔══██╗██╔══██║██║ ██║ ██║██║ ██╔══██║██║ ██║ ██║
██║ ██║ ██║██║ ██║╚██████╗ ██║ ██║╚██████╗██║ ██║███████╗███████╗██║
╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═╝╚══════╝╚══════╝╚═╝
```
## Project Status
TODO: add status badges for }} workflows and issues
TODO: Provide a meaningful description of the project
Project created with [deps-new](https://github.com/seancorfield/deps-new) and the [practicalli/application template](https://github.com/practicalli/project-templates)
## Run the service
Run the service (clojure.main)
```shell
clojure -M:run/app
```
Run the greet function (clojure.exec), optionally passing a `:name` key and value as arguments
```shell
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](https://practical.li/clojure/clojure-cli/practicalli-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
```shell
make
```
### Run Clojure REPL
Start the REPL with the [Practicalli REPL Reloaded](https://practical.li/clojure/clojure-cli/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)
```shell
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
```shell
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](https://github.com/greglook/cljstyle/releases){target=_blank}
- MegaLinter runs in a Docker container, so ensure Docker is running
```shell
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
```shell
make build-uberjar
```
- `make build-config` displays the tools.build configuration
- `make build-clean` deletes the build assets (`target` directory)
```shell
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](http://creativecommons.org/licenses/by-sa/4.0/")