appendix_b.html

<section data-type="appendix" id="appendix_environment">
<h1>Setting Up Your ClojureScript Environment</h1>

  <section data-type="sect1">
  <h1>Setting Up ClojureScript</h1>

  <p>ClojureScript is a dialect of Clojure that compiles to JavaScript. Clojure is a Lisp dialect that runs on the Java Virtual Machine. So, in order to use JavaScript, you need Java and Clojure.</p>

    <section data-type="sect2" id="getting-java">
    <h2>Getting Java</h2>
    <p>
    You can test to see if Java is already installed on your computer by opening a command window (on Windows) or a terminal window (on Mac OSX or Linux) and type <code>java&#160;-version</code> at the command line. If you get some output describing a version of Java, such as the following, you have Java installed.
    </p>

    <pre>java version "1.8.0_40"
    Java(TM) SE Runtime Environment (build 1.8.0_40-b26)
    Java HotSpot(TM) 64-Bit Server VM (build 25.40-b25, mixed mode)</pre>

    <p>
    If you get an error message, then you need to install Java. You may either use <a href="http://openjdk.java.net/">OpenJDK</a> or
    <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Oracle’s Java Development Kit</a>.  Follow the download and installation instructons you find there.
    </p>
    </section>
    
    <section data-type="sect2" id="getting-clojure">
    <h2>Getting Clojure and ClojureScript</h2>
    <p>
    If you want to get started quickly with ClojureScript, I recommend that you follow the instructions at the aptly named <a href="https://github.com/clojure/clojurescript/wiki/Quick-Start">ClojureScript Quick Start page.</a>  From that page, you can download a <em>jar</em> file that has “the ClojureScript compiler and the bundled REPLs without an overly complicated command line interface.”
    </p>
    </section>

    <section data-type="sect2" id="create-project">
    <h2>Creating a ClojureScript Project</h2>    
    <p>
    Again, using the instructions at the Quick Start page, I created a project named <em>sample-project</em>. (I am sick and tired of “Hello, world!” so I did something slightly different.)
    </p>

    <p>Here is the file structure of the directory, with files organized by category rather than alphabetical order. Notice that the project name <em>sample-project</em> has a hyphen in it, but when used in a directory name, you replace the hyphen with an underscore: <em>sample_project</em>.
    </p>

<pre>sample_project
├── cljs.jar
├── src
│   └── sample_project
│       └── core.cljs
├── index.html
├── build.clj
├── release.clj
├── repl.clj
└── watch.clj</pre>

  <p>
  The <em>cljs.jar</em> file contains ClojureScript, downloaded from the link at the Quick Start page.
  </p>
  </section>

    <section data-type="sect2">
    <h2>ClojureScript File <em>src/sample_project/core.cljs</em></h2>
    <p>
      This is the ClojureScript file for the project; it simply prints to the console.
    </p>
<pre data-type="programlisting" data-code-language="clojure">;; remove the :require and defonce when building the release version

(ns sample-project.core
  (:require [clojure.browser.repl :as repl]))

(defonce conn
  (repl/connect "http://localhost:9000/repl")) 

(enable-console-print!)

(println "It works!")</pre>
    </section>

    <section data-type="sect2">
    <h2>File <em>index.html</em></h2>
    <p>
      This file has a bit more than the Quick Start file: the addition of the <code>&lt;meta&gt;</code> element avoids a warning in the web console, and the <code>&lt;title&gt;</code> element lets you distinguish projects from one another if you have multiple browser tabs open.
    </p>

<pre data-type="programlisting" data-code-language="html">&lt;!DOCTYPE html&gt;
&lt;html&gt;
    &lt;head&gt;
        &lt;title&gt;sample-project&lt;/title&gt;
        &lt;meta http-equiv="Content-Type" content="text/html; charset=utf-8" /&gt;
    &lt;/head&gt;
    &lt;body&gt;
        &lt;script type="text/javascript" src="out/main.js"&gt;&lt;/script&gt;
    &lt;/body&gt;
&lt;/html&gt;</pre>
  </section>

  <section data-type="sect2">
  <h2>File <em>build.clj</em></h2>
  <p>
    Builds an un-optimized version of the project. Run with the command
  </p>

<pre data-type="programlisting" data-code-language="clojure">(require 'cljs.build.api)

(cljs.build.api/build "src"
  {:main 'sample-project.core
   :output-to "out/main.js"})</pre>
    </section>

    <section data-type="sect2">
    <h2>File <em>release.clj</em></h2>
    <p>
      Builds an optimized version of the project.
    </p>

<pre data-type="programlisting" data-code-language="clojure">((require 'cljs.build.api)

(cljs.build.api/build "src"
  {:output-to "out/main.js"
   :optimizations :advanced})

(System/exit 0)</pre>
    </section>

    <section data-type="sect2">
    <h2>File <em>repl.clj</em></h2>
    <p>
    Builds an unoptimized version of the project and launches a browser REPL.
    On Linux and MacOSX, make sure you have <code>rlwrap</code> installed.
    </p>

<pre data-type="programlisting" data-code-language="clojure">(require 'cljs.repl)
(require 'cljs.build.api)
(require 'cljs.repl.browser)

(cljs.build.api/build "src"
  {:main 'sample-project.core
   :output-to "out/main.js"
   :verbose true})

(cljs.repl/repl (cljs.repl.browser/repl-env)
  :watch "src"
  :output-dir "out")</pre>
    </section>

    <section data-type="sect2">
    <h2>File <em>watch.clj</em></h2>
    <p>
    This program watches the <em>src</em> directory and recompiles when any file in that directory changes.
    </p>
    <pre data-type="programlisting" data-code-language="clojure">(require 'cljs.build.api)

(cljs.build.api/watch "src"
  {:main 'sample-project.core
   :output-to "out/main.js"})</pre>
    </section>

    <section data-type="sect2" id="text-editor">
    <h2>Getting A Text Editor</h2>
    <p>
    You can use any text editor you like to create your ClojureScript programs. The <a href="http://www.gnu.org/software/emacs/">emacs</a> editor seems to be quite popular, with <a href="http://www.vim.org/">vim</a> another popular choice. Yes, both have plugins for support of Clojure (<a href="https://github.com/clojure-emacs/cider">CIDER</a> for emacs; <a href="https://github.com/tpope/vim-fireplace">Fireplace</a> for vim). No, I will not get involved in the theological battle between these two editors. If you are in search of an IDE (Integrated Development Environment), you have a number of choices there as well:
    </p>
    
    <ul>
      <li><a href="https://www.jetbrains.com/idea/">IntelliJ IDEA</a> with the <a href="https://cursiveclojure.com/">Cursive</a> plugin</li>
      <li><a href="http://lighttable.com/">Light Table</a></li>
      <li><a href="https://sekao.net/nightcode/">Nightcode</a></li>
      <li><a href="">Eclipse</a> with the <a href="https://github.com/laurentpetit/ccw/wiki/GoogleCodeHome">Counterclockwise</a> plugin for Clojure</li>
    </ul>
    </section>
</section>
</section>