Skip to content

Commit

Permalink
Design goal getting started experience (zero-one-group#177)
Browse files Browse the repository at this point in the history
* First draft on getting started

* Proofread design goals - getting started

* Added *.cast
  • Loading branch information
anthony-khong authored Aug 28, 2020
1 parent a2298a8 commit 9620f0c
Show file tree
Hide file tree
Showing 2 changed files with 20 additions and 1 deletion.
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
.geni-stdout
.nrepl-history
*.cast

*.DS_Store*
.clj-kondo/.cache
Expand Down
20 changes: 19 additions & 1 deletion docs/design_goals.md
Original file line number Diff line number Diff line change
Expand Up @@ -242,4 +242,22 @@ This also works the other way. For example, the RDD `.mapToPair` method requires
(.mapToPair rdd (fn [x] (Tuple2. x 1))
```

## Easy Getting-Started Story
## Easy Getting-Started Experience

Getting started with Geni should be easy not only for seasoned Clojure developers, but also for someone new to the language, who is perhaps just trying out the library. Speaking from personal experience, as a beginner to Clojure, having to install [Leiningen](https://leiningen.org/) or [Clojure CLI](https://clojure.org/guides/deps_and_cli) can be a turn off and an unnecessary barrier to entry - not to mention the [Emacs-Cider](https://www.braveclojure.com/basic-emacs/) combo that appears in many Clojure tutorials.

Geni's getting-started journey draws a lot from [borkdude](https://github.com/borkdude)'s work. In particular, [clj-kondo](https://github.com/borkdude/clj-kondo/blob/master/doc/install.md#installation-script-macos-and-linux) can be installed as a standalone application with three lines of Bash or a simple `brew install`. We can also install and run a [babashka](https://github.com/borkdude/babashka#quickstart) script in three lines of Bash. To achieve a similar effect, Geni is released not only as a Clojure library, but also as a command-line app that auto-downloads the latest Geni uberjar and defaults to a REPL (with an nREPL server) with all of the Geni namespaces required. However, instead of a standalone executable, it still requires `java`. Concretely, after running the [three-liner](https://github.com/zero-one-group/geni#install-geni) to install the Geni CLI, we can run a minimal application that prints the Spark session as follows:

```bash
$ echo "(clojure.pprint/pprint (g/spark-conf @spark))\n exit" | geni
```

For Leiningen users, there is also a lein template that creates a Geni application that runs a Spark ML example. For example:

```bash
$ lein new geni geni-app && cd geni-app && lein run
```

The template comes with `core.clj` that contains an example of a very simple application that uses the library and `core_test.clj` that unit-tests the Spark machinery running underneath.

## Other Nice-To-Haves

0 comments on commit 9620f0c

Please sign in to comment.