Skip to content

Switch to VSCode, Calva, deps.edn for easier getting started #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Mar 4, 2024
Merged

Switch to VSCode, Calva, deps.edn for easier getting started #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d5c2c13
Move to tools.deps i.e. deps.edn
kirankulkarni Nov 22, 2023
72b3331
Remove the dev alias and add all dependencies to default
kirankulkarni Nov 23, 2023
328a583
Add VSCode + Calva section in README.md
kirankulkarni Nov 23, 2023
36dce54
Update - Simplify setup instructions
Nov 24, 2023
3bdb016
Add calva generated directories to gitignore
0niket Nov 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,3 +14,7 @@ profiles.clj
.idea
.m2-for-inclojure
*.iml
.lsp
.cpcache
.clj-kondo
.calva
171 changes: 72 additions & 99 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,14 @@
- [Introduction](#introduction)
- [Intended usage](#intended-usage)
- [Contributions](#contributions)
- [Workshop Goals](#workshop-goals)
- [Workshop Anti-Goals](#workshop-anti-goals)
- [Introduction](#introduction)
- [Intended usage](#intended-usage)
- [Contributions](#contributions)
- [Workshop Goals](#workshop-goals)
- [Workshop Anti-Goals](#workshop-anti-goals)
- [Suggested learning mindset](#suggested-learning-mindset)
- [Setup Instructions](#setup-instructions)
- [Course Design Philosophy](#course-design-philosophy)
- [Credits](#credits)
- [Copyright and License](#copyright-and-license)


# Introduction

This workshop aims to get your brain and fingers accustomed to just enough of
Expand All @@ -20,7 +19,7 @@ In other words, "What could one do with just a _little_ bit of Clojure?".
## What is Clojure?

Clojure is an interactive functional programming language that can run on many platforms
like the [JVM](https://clojure.org/about/jvm_hosted), [.NET CLR](https://clojure.org/about/clojureclr), [Javascript](https://clojurescript.org/) (browsers, nodeJS, React Native), as [native binaries](https://github.com/BrunoBonacci/graalvm-clojure) via Graalvm, and even as [shell scripts](https://babashka.org/)!
like the [JVM](https://clojure.org/about/jvm_hosted), [.NET CLR](https://clojure.org/about/clojureclr), [Javascript](https://clojurescript.org/) (browsers, nodeJS, React Native), as [native binaries](https://github.com/BrunoBonacci/graalvm-clojure) via Graalvm, and even as [shell scripts](https://babashka.org/)!

It is [used by software teams worldwide](https://clojure.org/community/success_stories#) to deliver
high-value software systems at giant companies like Apple, Walmart, to "decacorns"
Expand All @@ -32,125 +31,99 @@ of [creative makers](http://radar.oreilly.com/2015/05/creative-computing-with-cl
A small but vibrant [global community](https://clojure.org/community/user_groups) is [busy building amazing things](https://github.com/trending/clojure?since=monthly) with the language.

## Intended usage
- Support a 1-day guided workshop for programmers new to Clojure (not absolute programming beginners).
- Also function as at-home learning material for said programmers.
- The `master` branch is heavily commented, for at-home use
- A `solutions` branch will be available, as a companion to `master`.
But don't peek at it in advance!
- You may see a `workshop-code` branch. Ignore it. It is meant only for
workshop use, and is subject to deletion/re-creation.
- Incidentally, if you landed here while searching for Hirokuni Kim's
"[Clojure By Example](https://kimh.github.io/clojure-by-example/)", well, follow the link!

- Support a 1-day guided workshop for programmers new to Clojure (not absolute programming beginners).
- Also function as at-home learning material for said programmers.
- The `master` branch is heavily commented, for at-home use
- A `solutions` branch will be available, as a companion to `master`.
But don't peek at it in advance!
- You may see a `workshop-code` branch. Ignore it. It is meant only for
workshop use, and is subject to deletion/re-creation.
- Incidentally, if you landed here while searching for Hirokuni Kim's
"[Clojure By Example](https://kimh.github.io/clojure-by-example/)", well, follow the link!

## Contributions
- If you find bugs or errors, please send a PR (but please
don't change the course structure or pedagogy).

- If you find bugs or errors, please send a PR (but please
don't change the course structure or pedagogy).

## Workshop Goals
- Acquire a "feel" of Clojure, for further self-study/exploration.
- Learn how Clojurists usually think with Clojure to solve problems.
- See how it's not so hard to do surprisingly powerful things with a
mere handful of "primitive" functions, data structures, and ideas.
- Get you started with a good development setup and workflow that will
serve you well if (when) you continue to program with Clojure, as a
hobby, or at work!

- Acquire a "feel" of Clojure, for further self-study/exploration.
- Learn how Clojurists usually think with Clojure to solve problems.
- See how it's not so hard to do surprisingly powerful things with a
mere handful of "primitive" functions, data structures, and ideas.
- Get you started with a good development setup and workflow that will
serve you well if (when) you continue to program with Clojure, as a
hobby, or at work!

## Workshop Anti-Goals
- Try to explain Functional Programming theory or Clojure's innards.
(Many free and paid tutorials and books do so very well.)
- Try to fully cover Clojure primitives/features. (That's homework!)
- Devolve into language wars, editor wars, syntax wars, type wars...
(Life's too short, people.)
- Focus too much on tooling or operational things. (At least not
while there's fun to be had!)

- Try to explain Functional Programming theory or Clojure's innards.
(Many free and paid tutorials and books do so very well.)
- Try to fully cover Clojure primitives/features. (That's homework!)
- Devolve into language wars, editor wars, syntax wars, type wars...
(Life's too short, people.)
- Focus too much on tooling or operational things. (At least not
while there's fun to be had!)

# Suggested learning mindset
- Think of this as an exercise in "constrained creativity".
- Ignore details, achieve much with as little know-how as possible.
- Focus on what things do; not what they are, or why they are.
- Inform your _intuition for doing things_, and then use that to
dive deeper into all the juicy details at your own pace, later.

Take what is useful, discard the rest.
- Think of this as an exercise in "constrained creativity".
- Ignore details, achieve much with as little know-how as possible.
- Focus on what things do; not what they are, or why they are.
- Inform your _intuition for doing things_, and then use that to
dive deeper into all the juicy details at your own pace, later.

Take what is useful, discard the rest.

# Setup Instructions

It's a liiitle bit of work. But not too bad.

Just do the following one by one, and you should be fine.

## IntelliJ + Cursive IDE

We support IntelliJ + Cursive IDE in the classroom for this workshop. We suggest you use this setup, unless of course, you have already configured your favourite editor for Clojure development. We've listed alternate starter kits below (VSCode, Vim, Emacs, Atom), *but* please avoid [bikeshedding](http://catb.org/jargon/html/B/bikeshedding.html) editors. Just complete the workshop first!

- Download and Install [IntelliJ Community Edition](https://www.jetbrains.com/idea/download/)
- Install and configure the Cursive plugin for IntelliJ by following the [official Cursive user guide](https://cursive-ide.com/userguide/).

Once installed:
## VSCode + Calva

- Launch IntelliJ and select "Import Project" from the opening splash screen.
- OR use IntelliJ's file menu to open this project via File > New > Project From Existing Sources
- Select this project's main directory; click OK
- The "Import Project" dialog box should open
- Select Leiningen under "Import project from external model"; click Next
- Click Next again in the following screen that shows "Root Directory"; wait for it...
- Again, click Next in the screen that says "Select Leiningen projects to import"
- And again, click Next in the "Please select project SDK" screen (ensure you select JDK version 1.8 or higher)
- Click "Finish", and wait for IntelliJ to set up the project
- Under `Run...` click on `Run...` and then select `REPL for clojure-by-example` (or whatever your project name happens to be).
- A right pane should open, with a REPL session.
- Now, open the `ex00..` file under the `src` folder
- Use the menu under Tools > REPL to (a) Switch to the file's "namespace", and then (b) load the file into the REPL
- Scroll down a little, till you see `(+ 1 2)`.
- Place your cursor after the closing parenthesis `)`, then right-click to open the context menu, and click on REPL > "Send '(+ 1 2)' to the REPL.
- You should see '(+ 1 2)' appear in the REPL window, followed by `3`. This means you successfully evaluated an expression in the REPL.
- Now you may start from the top of ex00 and work through the material in each "ex" file
- Important: For every exercise file, remember to first switch to the file's namespace, and load the file in the REPL (use the menu under Tools > REPL)

Also keep the Cursive user guide handy, in case you need editor help, as you solve the workshop material. In particular, the [Paredit guide](https://cursive-ide.com/userguide/paredit.html) may be useful, if you stumble when editing Clojure code.

## (Optional) Java and Leiningen
Being a JVM hosted language, Clojure requires Java to run. For the workshop, we also use a Clojure build tool called Leiningen.
If you're using IntelliJ + Cursive for the workshop, you won't need to install Java or Leiningen separately, since Intellij will come with a JDK and Cursive will download Leiningen when you import the project.
So just follow the IntelliJ + Cursive setup guide and you'll be good to go for the workshop.

If you're working on a production project however, it's useful to have both Java and Leiningen separately installed.

### Java
We support VSCode + Calva IDE in the classroom for this workshop. We suggest you use this setup, unless of course, you have already configured your favourite editor for Clojure development. We've listed alternate starter kits below (VSCode, Vim, Emacs, Atom), _but_ please avoid [bikeshedding](http://catb.org/jargon/html/B/bikeshedding.html) editors. Just complete the workshop first!

- Download and Install [VSCode](https://code.visualstudio.com/)
- Open VSCode and complete the initialization process.
- Open the "Extensions" Tab and search for "Calva", Install the "Calva: Clojure & ClojureScript Interactive Programming" extension
- Alternatively you can visit the [Calva page](https://marketplace.visualstudio.com/items?itemName=betterthantomorrow.calva) to install it
- You need Java Installed
- Run `java -version` in your terminal.
- If Java is not installed, please [download and install Java from here](https://adoptopenjdk.net/). Any version should do.
- Once you are done, `java -version` should show you a Java version.

Notes:
- We have not tested this project with Java 7.

Once installed:

### Leiningen
- Clone the repository on your machine
- In VSCode Use File > Open Folder... and open the cloned folder
- Notice that Calva activates
- Open the [Command Pallete](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) in VSCode using `⇧⌘P` on Mac or `Ctrl+Shift+P` on other systems
- Type "Calva: Start Project REPL" and choose "Calva: Start a Project REPL and Connect (aka Jack-In)" from the list
- Select `deps.edn` when prompted for Project type. We are using [tools.deps](https://clojure.org/guides/deps_and_cli) for managing the project. You don't need to worry about it's details for this workshop
- VSCode will create a new pane called 'output.calva-repl' and you will see `clj꞉user꞉>` prompt in that screen
- You have a working REPL now!

Follow [Leiningen setup instructions here](https://leiningen.org/).
- Keep the [Paredit guide](https://calva.io/paredit/) handy, editing code will require some understanding of paredit.

## Alternative Starter Kits:
### Java

If you can't use IntelliJ for some reason, you may try one of these. Although we haven't tested with these setups, the workshop material should work fine.
You'll also have to install Leiningen and Java separately.
- Run `java -version` in your terminal.
- If Java is not installed, please [download and install Java from here](https://adoptopenjdk.net/). Any version should do.
- Once you are done, `java -version` should show you a Java version.

- [VSCode + Calva](https://calva.io/) has become a fantastic Clojure IDE!
- A [snazzy setup with Atom](https://medium.com/@jacekschae/slick-clojure-editor-setup-with-atom-a3c1b528b722).
- [Vim + vim-fireplace](https://thoughtbot.com/blog/writing-clojure-in-vim) and other goodies that make Clojure/Lisp hacking fun in Vim.
- Brave Clojure walks you through [a basic Emacs setup for learning Clojure](https://www.braveclojure.com/basic-emacs/).
Notes:

- We have not tested this project with Java 7.

## Your favourite editor:

You may find instructions for your favourite editor at one of these pages. But there are only so many choices. Ultimately, you must pick your poison and run with it:

- ["Clojure Tools" at clojure.org](https://clojure.org/community/tools)
- ["Essentials" at clojure-doc.org](http://clojure-doc.org/articles/content.html#essentials)
- [Christopher Bui says...](https://web.archive.org/web/20181223213500/https://cb.codes/what-editor-ide-to-use-for-clojure/)

- ["Clojure Tools" at clojure.org](https://clojure.org/community/tools)
- ["Essentials" at clojure-doc.org](http://clojure-doc.org/articles/content.html#essentials)
- [Christopher Bui says...](https://web.archive.org/web/20181223213500/https://cb.codes/what-editor-ide-to-use-for-clojure/)

# Course Design Philosophy

Expand All @@ -167,14 +140,14 @@ satisfies and empowers us deeply.
So, may you stay small and achieve important things.

Live long, and prosper.
\\\\//_

\\\\//\_

# Credits
- [clj-pune](https://github.com/clj-pune) people, especially [kapilreddy](https://github.com/kapilreddy), and [jaju](https://github.com/jaju) for critique while making ["pratham"](https://github.com/clj-pune/pratham), the precursor to this project.
- [adityaathalye](https://github.com/adityaathalye), [jysandy](https://github.com/jysandy), and [kapilreddy](https://github.com/kapilreddy) for course design, code reviews, critique, commits, and being the core teaching staff at the first edition of this workshop at IN/Clojure 2018.
- All the workshop participants, and the many Clojurists who generously donated their time to make it successful.
- [inclojure-org](https://github.com/inclojure-org) for being the umbrella under which this work happened.

- [clj-pune](https://github.com/clj-pune) people, especially [kapilreddy](https://github.com/kapilreddy), and [jaju](https://github.com/jaju) for critique while making ["pratham"](https://github.com/clj-pune/pratham), the precursor to this project.
- [adityaathalye](https://github.com/adityaathalye), [jysandy](https://github.com/jysandy), and [kapilreddy](https://github.com/kapilreddy) for course design, code reviews, critique, commits, and being the core teaching staff at the first edition of this workshop at IN/Clojure 2018.
- All the workshop participants, and the many Clojurists who generously donated their time to make it successful.
- [inclojure-org](https://github.com/inclojure-org) for being the umbrella under which this work happened.

## Copyright and License

Expand Down
5 changes: 5 additions & 0 deletions deps.edn
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{:paths ["src" "resources"],
:deps {org.clojure/clojure {:mvn/version "1.10.0"}
org.clojure/data.json {:mvn/version "0.2.6"}
enlive/enlive {:mvn/version "1.1.6"}
rewrite-clj/rewrite-clj {:mvn/version "0.6.1"}}}
11 changes: 0 additions & 11 deletions project.clj
View file
Open in desktop

This file was deleted.