% General Overview
% John Gabriele

Clojure is a language implemented in Java and also in Clojure
itself. The language implementation (compiler and runtime) is
distributed as a *jar file* (see below) and runs on the Java virtual
machine ("JVM"). Your Clojure programs will be compiled by the Clojure
implementation into JVM bytecode and then run on the JVM (see below
for explanations of Java-related terms).

> The compiling and running just described is all neatly handled for
> you by a standard tool, described later.

Clojure comes with a "REPL" --- a "read/eval/print loop". This is an
interactive prompt (like the Python prompt) where you can type in and
run some Clojure code and see what it does and what it returns
(evaluates to).

Clojure source code filenames end in ".clj".

For more about what Clojure is, see <http://clojure.org/>.



Some Info About Java
====================

Since Clojure runs on the
[JVM](http://en.wikipedia.org/wiki/Java_Virtual_Machine), makes use of
the Java platform, and can interoperate so easily with
[Java](http://en.wikipedia.org/wiki/Java_%28programming_language%29),
it helps to know a little about Java.

> **Note:** The rest of this section is just optional extra background
> info.

Here are explanations of some terms and also a few other morsels of
useful background information:

  * *Java* source code gets compiled to
    "[bytecode](http://en.wikipedia.org/wiki/Java_bytecode)" by a
    compiler program usually named "`javac`" (which you won't need to
    use directly while working with Clojure).

  * The JVM (started by executing the `java` command) runs
    bytecode. It doesn't matter where the bytecode came from; it
    could've been compiled from Java source, or Clojure source, or
    some other language.

  * Bytecode is stored in ".class" files. You generally won't see
    these when working with Clojure. `java` runs the bytecode in
    .class files.

  * By default, `java` doesn't know where to find .class files which
    aren't part of the Java standard class library. It maintains a
    list of places to look called the "classpath". To tell `java` to
    add a location to its classpath, you would use the
    `-cp path/to/classfile/dir` option on the command line (or
    less-commonly, you'd set an environment variable). Happily, the
    standard Clojure project management tool (discussed later) takes
    care of dealing with the `java` command and the classpath so you
    don't have to.

    *(Note: this brief guide doesn't cover how to use Java code in your
    Clojure projects, except to provide a link to [additional
    info](libs-management-and-use.html#various-java-libraries).)*

  * For distribution purposes, one or more .class files for a given
    library or application are typically packed together into a ".jar"
    archive file. Jar files are not unlike "tar" or "zip" files, and
    can contain other files besides .class files. (The Clojure
    implementation is distributed as clojure.jar.)

  * Just like you can tell `java` additional directories where it can
    find .class files (using the `-cp path/to/classfile/dir` option),
    you can also tell it to find them packed inside a jar file: `-cp
    path/to/jarfile.jar`.

  * If a jar file contains a .class file with a "main" function, and if
    that jar file *also* contains a special bit of metadata indicating
    which .class file that is, then the jar can be run by the JVM as a
    standalone program like so: `java -jar path/to/my-cool-app.jar`

    > So:
    >   * `-cp path/to/jarfile.jar` is for telling `java` to find
    >     classfiles in jarfile.jar, and
    >   * `-jar path/to/jarfile.jar` is for
    >     telling `java` to *run* jarfile.jar.

  * Usage of the `jar` command is somewhat similar to the familiar
    `tar` command.

  * Some desktop operating systems may let you just double-click on
    jar files to run them.

  * Java comes with a rather large standard library (known as the Java
    Class Library), all of which is easily accessible from Clojure.

  * There are many other 3rd-party Java libraries available as well,
    and these are also easily accessible from Clojure.

  * Java is readily available for most platforms. On Debian-based
    GNU/Linux distributions it may already be installed
    ("openjdk-8-jre").  On MS Windows you need to download an
    installer from <http://www.java.com/>. On Mac OS X, either it's
    already installed (try `java -version` to see) or else you need to
    download an installer from Apple.

  * When installing Java, you can either install just the runtime
    environment (openjdk-8-jre), or else the whole development kit
    (openjdk-8-jdk). Running your Clojure programs only requires the
    runtime/jre.

Regarding the Java language itself, it's is your garden-variety,
statically-typed, imperative, semi-colon curly-braces object-oriented
language. You've got classes, and can instantiate objects from those
classes. Functions (Java calls them "methods") can be defined *only*
inside classes. There are functions you can call via a class (where
the class just acts as a namespace for the function), and there are
functions you can call on behalf of an object (which often modifies
its state).

There are [*many* Java tutorials out
there](http://duckduckgo.com/?q=java+tutorial).

Personally, for learning Java, I like the "Core Java" book by
Horstmann & Cornell.