Setup

Running Athens Locally

Video version of this for Mac.

These dependencies are needed to get Athens up and running. To install them, follow the instructions in the links.

1. Java 11 and Leiningen (Leiningen installs Clojure)

2. Node 12 and Yarn

If you want to use Windows Subsystem for Linux (WSL), try this tutorial.

After you've got these dependencies, clone the Git repository to your hard drive:

git clone https://github.com/athensresearch/athens.git

Then cd athens/ and run the following commands.

Pull JavaScript dependencies:

yarn

Pull Java dependencies and build, then start a local HTTP server for Athens:

lein dev

In another terminal, run:

yarn run electron .

Another window should open automatically. That's your Athens!

Now make sure you can run code in a REPL and that you know how to use re-frame-10x.

Running in Docker

Docker doesn't work perfectly well anymore, because we are using Electron. Electron requires access to local resources such as resources/index.html.

If you run yarn run electron . from your local system, but are running Athens from within Docker, it won't work. Furthermore, if you run yarn run electron . from within your Docker system, the GUI won't popup on your local system. The workaround would be to sync the resources/ files from Docker to a local folder.

The following command runs Athens in a docker container, but does not provide a workaround to actually run Electron.

docker build -t athens .
docker run -it -p 3000:3000 -p 8777:8777 -p 9630:9630 athens

Storybook React Components

We are mainly using or are in the process of migrating to React JS components for our frontend, so contributions to our client can be more accessible. Please see up to date docs about Storybook here.

Connecting your REPL

The REPL is one of the core features of Clojure. REPL-driven programming can make you code faster, with less tests and bugs. This video demonstrates this.

• Make sure you can run Athens locally before proceeding with this section.

• Refer to shadow-cljs editor integration docs for more details.

• nREPL port is 8777, as defined in shadow-cljs.edn.

Cursive

https://www.loom.com/share/a2cc5f36f8814704948a57e8277c04e9

CIDER

Video tutorial

Calva

Editor - Visual Studio Code
Calva plugin: v2.0.126 Built on: 2020-07-09
OS - Windows 10, MacOS Catalina v10.15.6

1. In VS Code, run ctrl+shift+c and ctrl+shift+j (ctrl+alt+c ctrl+alt+j in Windows 10) to jack into a repl session.

2. Pick shadow-cljs.

3. Select :main and :renderer profile for shadow-cljs to watch.

4. Select the :renderer build to connect to.

5. In another terminal tab, run npx electron .

Vim Plugins

• TODO vim-iced

• TODO conjure

• [X] TODO fireplace

Fireplace

Fireplace is a popular Clojure(script) development plugin for Vim (and Neovim) text editor. It's main dependency is the cider-nrepl which already included as a development dependency.

Assume you already executed the commands described above in different terminal sessions and have the Athens instance running. And of course assume you installed vim-fireplace plugin too.

lein dev # in one terminal, running nrepl server on port 8777
yarn run electron . # another terminal running the Athens app itself

Now open any Clojure file in Vim. This will load vim-fireplace plugin and necessary commands. First, we need to connect Clojure (not Clojurescript yet) runtime;

:FireplaceConnect 8777

Clojure part is done. Now to connect Clojurescript runtime with vim-fireplace;

:Piggieback :renderer

To test your development environment you can try to evaluate some Clojurescript and see the results on Athens running in electron;

:CljsEval (js/alert "hello!")

You supposed to see an alert on electron app saying "hello!" and your Vim instance would be blocked until you acknowledge the alert message.

If all goes well, now you can see documentation of symbols (binding: K), go to definition (binding: [ C-d) and so fort. See :help fireplace for more information.

Conjure

Conjure is an interactive environment for evaluating code within your running program for Neovim. Installing Conjure

Its main dependency is the cider-nrepl. Create the following file at ~/.shadow-cljs/config.edn to add the dependency:

{:dependencies
 [[cider/cider-nrepl "0.26.0"]]}
;; this version may be out of date, check whichever is available

See shadow-cljs docs for more info.

Now that we're set up, lets start the development environment;

lein dev # in one terminal, running nrepl server on port 8777
yarn run electron . # another terminal running the Athens app itself

Open any Clojurescript file in Neovim. Conjure will connect automatically to the leiningen nrepl server and you should see a temporary floating buffer in the top right corner of your editor showing a successful connection.

To get that buffer back and to keep it open in a horizontal split:

:ConjureLogSplit

To connect to the Clojurescript runtime;

:ConjureShadowSelect renderer

In the log buffer you should see;

; --------------------------------------------------------------------------------
; shadow-cljs (select): renderer
; (out) To quit, type: :cljs/quit
[:selected :renderer]

To test your development environment you can try to evaluate some Clojurescript and see the results on Athens running in electron;

:ConjureEval (js/alert "hello!")

You should see an alert in the electron app saying "hello!". All further evaluations will be blocked until you acknowledge the alert message.

Congratulations, you're connected!

To learn more about how to evaluate things with Conjure, please refer to :help conjure, :help conjure-client-clojure-nrepl and :ConjureSchool (an interactive tutorial). See also: [Conjures quickstart guide to Clojurescript](https://github.com/Olical/conjure/wiki/Quick-start:-ClojureScript-(shadow-cljs)) and Clojure

Using re-frame-10x

The right sidebar has re-frame-10x developer tools. You can toggle it open and close with ctrl-h, but you must not be focused on a block (ctrl-h has a specific action in some operating systems).

Once you have 10x open, you can hover over blocks' bullets to see some of their datascript data.

By default, 10x is closed everytime Athens starts. Sometimes you want 10x to be open immediately on start. To do, comment out the two lines of JavaScript code in index.html, where localStorage sets 10x to be closed by default.

Running CI Scripts Locally

After each submitted PR to Athens, GitHub Actions runs the continuous integration workflow declared in .github/workflows/build.yml. This workflow runs scripts from script/ to test, lint, and build Athens. You can see these workflows in practice in the Actions tab.

However, it's a lot faster if you run these tests locally, so you don't have to submit a PR each time to make sure the workflow succeeds. You may need to install additional dependencies, though.

Testing

No additional installation is needed. Just run this:

lein test

The output will look something like this:

$ lein test

Testing athens.block-test

Testing athens.parser-test

Testing athens.patterns-test

Ran 4 tests containing 16 assertions.
0 failures, 0 errors.

Linting

We are linting Clojure code using clj-kondo. Our clj-kondo configuration is in .clj-kondo/config.edn.

For this linting to work, you will need to install clj-kondo. Instructions are in clj-kondo’s installation guide.

To see the problems reported by clj-kondo, run script/lint. Example run:

$ script/lint
linting took 257ms, errors: 0, warnings: 0

Your editor may also be able to integrate with clj-kondo’s output. For example, if you use Calva for VS Code, then clj-kondo’s messages are reported in the Problems panel.

Clojure Styling

To format your code or check that your code is formatted correctly, you will need to use cljstyle. Instructions for installing it are in cljstyle’s README.

To check if your Clojure code is formatted correctly, run cljstyle check. If there is no output and the return code is zero, you’re good. You can also run script/style, but currently it only works if you’re running Linux.

To reformat all your Clojure files in place, run cljstyle fix.

Unused Variable Checking

To set this up, first make sure that a global clojure binary is installed. You won’t necessarily have a clojure binary installed just because you installed Leiningen.

Next, just run script/carve. The first time you run it it will download Carve as a dependency, which takes about a minute and outputs lots of messages. On subsequent runs script/carve won’t output anything unless an unused variable was found.

Git and GitHub Style Guide

Commits

Follow guidelines from Conventional Commits. Specifically, begin each commit with one of the following types:

build:
ci:
chore:
docs:
feat:
fix:
perf:
refactor:
revert:
style:
test:

See some real examples in our commit history.

Issues

Please create issues using our templates. However, you will almost certainly get feedback and help faster in our Discord!

Pull Requests

If your PR is related to other issue(s), reference it by issue number. You can close issues smoothly with GitHub keywords:

close #1
fix #2
resolve #2

This repo only allows those with merge permissions to "Squash and Merge" PRs. This makes reverts easier if they are needed.

Developer Resources

• download Sample Athens Databases from our google drive