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.
- Java 11 and Leiningen (Leiningen installs Clojure)
- 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.
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
You should deploy your version of Athens and Devcards if you are making UI-releated pull requests to Athens. This will allow developers and designers to interact with your code, which is essential for reviewing UI changes.
Athens Devcards can be found at https://athensresearch.github.io/athens/cards.html.
We've setup GitHub Actions so that each time you commit to your fork on GitHub, GitHub Actions automatically lints, tests, and styles your code.
If these scripts pass, GitHub builds your code and then deploys it to https://YOUR_GITHUB.github.io/athens/ and https://YOUR_GITHUB.github.io/athens/cards.html.
To begin doing automated deploys, just make sure your Actions are enabled at https://github.com/YOUR_GITHUB/athens/actions. Then start pushing code!
To build and deploy Athens and Devcards from your local development environment:
- Build your JavaScript bundle(s) with either
lein dev,lein devcards, orlein compile. - Run
lein gh-pages. - Open http:///github.io/athens/ and http:///github.io/athens/cards.html. Sometimes this takes a minute to be updated.
Notes:
- If you want to compile Athens and Devcards one time without hot-reloading, run
lein compile. - If you are actively developing Athens and not Devcards, run
lein devto hot-reload the Athens application. - If you are actively developing DevCards and not Athens, run
lein devcardsto hot-reload Devcards. - If you want to build Athens and Devcards, because you are testing a component on DevCards and Athens at the same time, you should run
lein devandlein devcardsin two terminals. - If both builds are running, it doesn't matter which port you go to (i.e.
3000or3001), because both HTTP servers can serve assets. - More docs should be written in the future on how to connect a REPL to either build, depending on your text editor.
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.
https://www.loom.com/share/a2cc5f36f8814704948a57e8277c04e9
Editor - Visual Studio Code
Calva plugin: v2.0.126 Built on: 2020-07-09
OS - Windows 10, MacOS Catalina v10.15.6
-
In VS Code, run
ctrl+shift+candctrl+shift+j(ctrl+alt+c ctrl+alt+jin Windows 10) to jack into a repl session. -
Pick shadow-cljs.
-
Select
:mainand:rendererprofile for shadow-cljs to watch. -
Select the
:rendererbuild to connect to. -
In another terminal tab, run
npx electron .
- TODO vim-iced
- TODO conjure
- TODO 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.
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.
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.
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.
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.
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.
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.
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.
Please create issues using our templates. However, you will almost certainly get feedback and help faster in our Discord!
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.