Getting Started

Installation

Note: Inlein has been developed and tested out on Linux, and although this should technically work fine on Windows, there may be some issues. If you experience problems with running this on Windows, please search for windows issues in the issue tracker. Any help to fix those issues is highly appreciated, and adding extra information about how to install on Windows and run on this wiki as well is very welcome.

Inlein is a small executable JAR that you download from the release pages on GitHub. To run the executable, you need Java JDK version 7 or later, and preferably a stable Internet connection. The link to the current inlein program is https://github.com/hyPiRion/inlein/releases/download/0.1.0/inlein, which you have to download and place somewhere (For example in your Downloads directory).

Installing on OS X/Linux

To be able to run Inlein from the command line and from scripts, it's preferable to place the inlein program on your path. I prefer to place them in ~/bin, and to do that, you can generally do

cp ~/Downloads/inlein ~/bin/inlein
# or wherever you downloaded inlein
chmod +x ~/bin/inlein
# to make it executable

If you're unsure if you have ~/bin on your PATH, read the section below before you perform the commands shown above.

Placing ~/bin on your PATH

If you're unsure if you have ~/bin on your path, you can open up a terminal and type in

echo $PATH | sed s/:/\\n/g

If you see /home/[your-username]/bin on a line, then you have ~/bin placed on your path. Otherwise you may have to add it yourself.

Some versions of the Bash initialisation file (~/.bashrc) script checks if ~/bin is a directory, and adds it to the path if it exists. So you can try to do mkdir ~/bin and open up a new terminal to see if ~/bin is now added onto your path.

If it is not on your path, you must add the following line to the end of your initialisation file ~/.bashrc (or if you're using zsh, ~/.zshrc):

PATH="$PATH:$HOME/bin"

Now ~/bin will be placed on your path.

First Usage

Now that you have placed inlein on your path, you should be able to call inlein with no parameters. If everything turns out well, you should see something like this:

inlein is a tool to handle Clojure scripts with dependencies

Usage: inlein [--run] file [args...]
       (to run a clojure script)
   or  inlein --task [args...]
       (to run an inlein task)

Several tasks are available:
--deps               Retrieves the dependencies for a script
--help               Prints this banner, or extended information about a task.
--ping               Pings the inlein server, if it runs.
--restart-daemon     Restarts the inlein daemon
--run                Runs a clojure script with dependencies
--sh-cmd             Prints the shell command a clojure script with dependencies will use
--shutdown-daemon    Shuts off the Inlein daemon
--start-daemon       Starts the inlein daemon
--upgrade            Upgrades to the specified inlein version, or latest
--version            Prints the currently running Inlein version.

You can see some mentions of a daemon here: Inlein is split into a client and a background process (daemon) to make startup time for scripts fast. You shouldn't generally have to worry about the daemon, the inlein client will automatically start it up for you and connect to it.

When you have installed inlein for the first time, the daemon will not be available. The inlein client will thus have to download the daemon and start it up, which makes the first boot a bit slow. You can manually do this by typing inlein --start-daemon, but you can skip this step without any issues.

$ inlein --start-daemon
Downloading https://github.com/hyPiRion/inlein/releases/download/0.1.0/inlein-daemon-0.1.0-standalone.jar...
Inlein daemon is now running

Usage

Now that we've installed inlein, we can start using it for Clojure scripting.

Inlein is implemented by "inlining" the necessary parts from a Leiningen project.clj file, to get the dependencies up and running. As such, an inlein-compliant Clojure script needs to start with something like this:

'{:dependencies [[org.clojure/clojure "1.8.0"]]}

Note the ' at the beginning: This is placed there so that when the script is actually ran, the inlein parameters are only parsed, but not evaluated.

A minimal inlein script will look something like this:

'{:dependencies [[org.clojure/clojure "1.8.0"]]}

(println "hello world!")

If you place this into the file hello.clj and then run inlein hello.clj, you should see

hello world!

in your terminal.

shebang

Note: Shebanging will not work on Windows. Whenever you see any occurences of ./script.clj my args, you should mentally replace it to inlein script.clj my args.

If you're like me and prefer to not call inlein before a script, you can add in a shebang (#!) line at the very beginning of your script like so:

#!/usr/bin/env inlein

'{:dependencies [[org.clojure/clojure "1.8.0"]]}

(println "hello world!")

Then make it executable via chmod +x hello.clj. You should now be able to call ./hello.clj, and it should print out hello world! just like the call inlein hello.clj.

jvm-opts

You've probably noticed that the script use quite a bit of time to start up. It's an unfortunate side effect of the Clojure implementation, and inlein attempts to start the script as fast as possible by utilising JVM options. To override the defaults, we can set :jvm-opts outselves (the empty vector, [], unsets the defaults):

#!/usr/bin/env inlein

'{:dependencies [[org.clojure/clojure "1.8.0"]]
  :jvm-opts []}

(println "hello world!")

If you try to run the script again, you should notice that it starts up considerably slower. Time both with time ./hello.clj to check the difference!

For scripts that aren't compute-heavy, the default JVM options should be fine. You can also look at Faster to see how to speed up startup times even more (or overall time, depending on your needs).

Dependencies

We haven't actually seen how you add and use dependencies in inlein; fortunately it's not hard at all, you just add the dependencies to the :dependencies key in the inlein map.

Let's make a small program that reads in JSON to EDN as an example. We will use cheshire to parse JSON from stdin (*in*), and prn to print Clojure data as EDN to stdout:

#!/usr/bin/env inlein

'{:dependencies [[org.clojure/clojure "1.8.0"]
                 [cheshire "5.5.0"]]}

(require '[cheshire.core :refer [parsed-seq]])

(doseq [data (parsed-seq *in*)]
  (prn data))

To use a dependency, you use require just like you use it in the ns macro, but with the arguments quoted.

Notice that Clojure is a dependency too, just like cheshire. If you want to upgrade or downgrade the Clojure version, you just change the version number. You can even use other Clojure-implementations, like Jaunt.

Command Line Arguments

Command line arguments in a Clojure script is stored in the *command-line-args* variable:

#!/usr/bin/env inlein

'{:dependencies [[org.clojure/clojure "1.8.0"]]}

(prn *command-line-args*)

The command line args will be nil if there are no arguments provided, otherwise it will be a sequence of the strings passed in. If we call the script above cli-args.clj, then ./cli-args.clj 1 2 3 will print out ("1" "2" "3") and ./cli-args.clj will print out nil.

If you want to do sophisticated command line argument parsing, you should take a look at tools.cli.

$0

Inlein does not do much magic to command line arguments, but there is one notable exception: It will place the name of the script (one usually known as $0 in shell scripting) as the JVM system property $0. To retrieve it, you just have to call (System/getProperty "$0"):

#!/usr/bin/env inlein

'{:dependencies [[org.clojure/clojure "1.8.0"]]}

(println (System/getProperty "$0"))

Peeking at the actual Java command

If you want to look at what the Java command actually looks like, you can run the command inlein --sh-cmd script.clj. This will print out the Java command that will be run if you run inlein script.clj/./script.clj on Linux (not Windows).

Generally you don't want to use this for anything but for debugging. However, in some situations, such as for customised repls, this may be a useful command. See "Trampolining" for some interesting hacks you can use if the inlein client itself gives you some limitations.

Upgrading Inlein

Upgrading inlein is as easy as calling inlein --upgrade. If you want to downgrade or upgrade to a specific version, then you provide the specific version you would like to upgrade or downgrade to: inlein --upgrade 0.1.0. Note that, although the command is called --upgrade, you can also go from e.g. version 0.2.0 to 0.1.0.