Setup
These dependencies are needed to get Athens up and running. To install them, follow the instructions in the links.
- 1.
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
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.
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.
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+candctrl+shift+j(ctrl+alt+c ctrl+alt+jin Windows 10) to jack into a repl session. - 2.Pick shadow-cljs.
- 3.Select
:mainand:rendererprofile for shadow-cljs to watch. - 4.Select the
:rendererbuild to connect to. - 5.In another terminal tab, run
npx electron .
- TODO vim-iced
- TODO conjure
- [X] 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.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
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 ClojureThe 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:
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.
Last modified 1yr ago