Skip to content
This repository

Minor tutorial improvements #807

Merged
merged 1 commit into from over 1 year ago

2 participants

Michael Klishin Phil Hagelberg
Michael Klishin
Collaborator

For @technomancy to review.

Phil Hagelberg technomancy merged commit fd759e6 into from October 06, 2012
Phil Hagelberg technomancy closed this October 06, 2012
Phil Hagelberg
Owner

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Showing 1 unique commit by 1 author.

Oct 07, 2012
Michael Klishin Minor tutorial improvements c5de124
This page is out of date. Refresh to see the latest.

Showing 1 changed file with 82 additions and 11 deletions. Show diff stats Hide diff stats

  1. 93  doc/TUTORIAL.md
93  doc/TUTORIAL.md
Source Rendered
... ...
@@ -1,15 +1,64 @@
1 1
 # Tutorial
2 2
 
  3
+## What is Leiningen
  4
+
  5
+Leiningen is a tool for automating Clojure projects without setting your hair on fire.
  6
+
  7
+Leiningen makes it easy to
  8
+
  9
+ * Manage dependencies for your project
  10
+ * Run tests
  11
+ * Access the REPL without worrying about adding dependencies to classpath
  12
+ * Compile Java sources (if any)
  13
+ * Run the app
  14
+ * Compile and package projects for deployment
  15
+ * Publish libraries to repositories such as [Clojars](http://clojars.org)
  16
+ * Write custom automation tasks in Clojure
  17
+
  18
+If you come from the Java world, Leiningen is "Maven meets Ant without the pain". For Ruby and Python
  19
+folks, Leiningen combines RubyGems/Bundler/Rake and pip/Fabric in a single tool.
  20
+
  21
+
  22
+## What This Tutorial Covers
  23
+
  24
+This tutorial will briefly cover project structure, dependency management, running tests,
  25
+the REPL and topics related to deployment.
  26
+
3 27
 For those of you new to the JVM who have never touched Ant or Maven in
4 28
 anger: don't panic. Leiningen is designed with you in mind. This
5 29
 tutorial will help you get started and explain Leiningen's take on
6 30
 project automation and JVM-land dependency management.
7 31
 
  32
+
  33
+## Getting Help
  34
+
8 35
 Also keep in mind that Leiningen ships with fairly comprehensive help;
9 36
 `lein help` gives a list of tasks while `lein help task` provides
10 37
 details. Further documentation such as the readme, sample
11 38
 configuration, and even this tutorial are also provided.
12 39
 
  40
+
  41
+## Leiningen Projects
  42
+
  43
+Leiningen works with *projects*. A project is a group of Clojure (and, possibly, Java)
  44
+source files with a bit of metadata about them. The metadata is stored in a file named
  45
+`project.clj` (by convention) in the repository root. `project.clj` is how you tell
  46
+Leiningen about things like
  47
+
  48
+ * Project name
  49
+ * Project description
  50
+ * What libraries the project depends on
  51
+ * What Clojure version to use
  52
+ * Where to find source files
  53
+ * What's the main namespace of the app
  54
+
  55
+and more.
  56
+
  57
+Most Leiningen tasks only make sense in the context of a project. Some (for example, `lein repl`)
  58
+can also work globally, from any directory.
  59
+
  60
+Next lets take a look at how projects are created.
  61
+
13 62
 ## Creating a Project
14 63
 
15 64
 We'll assume you've got Leiningen installed as per the
@@ -32,11 +81,18 @@ Generating a new project is easy:
32 81
         `-- my_stuff
33 82
             `-- core_test.clj
34 83
 
  84
+### Directory Layout
  85
+
35 86
 Here we've got your project's README, a `src/` directory containing the
36 87
 code, a `test/` directory, and a `project.clj` file which describes your
37 88
 project to Leiningen. The `src/my_stuff/core.clj` file corresponds to
38 89
 the `my-stuff.core` namespace.
39 90
 
  91
+Even though most pure Clojure projects never need to customize directory layout,
  92
+it is possible with Leiningen.
  93
+
  94
+### Filename-to-Namespace Mapping Convention
  95
+
40 96
 Note that we use `my-stuff.core` instead of just `my-stuff` since
41 97
 single-segment namespaces are discouraged in Clojure. Also note that
42 98
 namespaces with dashes in the name will have the corresponding file
@@ -68,21 +124,25 @@ Unlike most languages, it's easy to swap out any version of Clojure.
68 124
 
69 125
 ## Dependencies
70 126
 
71  
-By default, Leiningen projects download dependencies from
72  
-[Clojars](http://clojars.org) and [Central](http://search.maven.org).
73  
-Clojars is the Clojure community's centralized jar repository, while
74  
-Central is for the wider JVM community.
  127
+### Overview
  128
+
  129
+Clojure is a hosted language and Clojure libraries are distributed the same
  130
+way as in other JVM languages: as JARs.
75 131
 
76  
-Libraries for the JVM are packaged up as .jar files, which are
77  
-basically just .zip files with a little extra JVM-specific metadata.
78  
-They usually contain .class files (JVM bytecode) and .clj source
  132
+JARs (`.jar` files) are basically just `.zip` files with a little extra JVM-specific
  133
+metadata. They usually contain `.class` files (JVM bytecode) and `.clj` source
79 134
 files, but they can also contain other things like config
80  
-files.
  135
+files, JavaScript files or text files with static data.
  136
+
  137
+Published JVM libraries have *identifiers* (artifact group, artifact id) and
  138
+*versions*.
  139
+
  140
+### Artifact IDs, Groups and Versions
81 141
 
82 142
 You can [search Clojars](http://clojars.org/search?q=clj-http) using its
83 143
 web interface. On the page for `clj-http` it shows this:
84 144
 
85  
-    [clj-http "0.4.1"]
  145
+    [clj-http "0.5.5"]
86 146
 
87 147
 There are two different ways of specifying a dependency on the latest
88 148
 stable version of the `clj-http` library, one in Leiningen format
@@ -92,7 +152,7 @@ though you'll need to learn to read it for Java libraries from
92 152
 directly into the `:dependencies` vector in `project.clj`.
93 153
 
94 154
 Within the vector, "clj-http" is referred to as the "artifact id".
95  
-"0.4.1" is the version. Some libraries will also have "group ids",
  155
+"0.5.5" is the version. Some libraries will also have "group ids",
96 156
 which are displayed like this:
97 157
 
98 158
     [com.cedarsoft.utils.legacy/hibernate "1.3.4"]
@@ -104,6 +164,8 @@ you can omit the group-id. If there is a library that's part of a
104 164
 larger group (such as `ring-jetty-adapter` being part of the `ring`
105 165
 project), the group-id is often the same across all the sub-projects.
106 166
 
  167
+### Snapshot Versions
  168
+
107 169
 Sometimes versions will end in "-SNAPSHOT". This means that it is not
108 170
 an official release but a development build. Relying on snapshot
109 171
 dependencies is discouraged but is sometimes necessary if you need bug
@@ -122,6 +184,15 @@ just a convention. There is no guarantee they will match up at all, so
122 184
 consult the library's documentation before writing your `:require`
123 185
 and `:import` clauses.
124 186
 
  187
+### Repositories
  188
+
  189
+Dependencies are stored in *repositories*. If you are familiar with CPAN, PyPi, rubygems.org
  190
+or NPM, it's the same thing. Leiningen reuses existing JVM repositories infrastructure. There
  191
+are several popular open source repositories. Leiningen by default will use two of them: [clojars.org](http://clojars.org)
  192
+and [Maven Central](http://search.maven.org/).
  193
+
  194
+Clojars is the Clojure community's centralized jar repository, while Central is for the wider JVM community.
  195
+
125 196
 You can add third-party repositories by setting the `:repositories` key
126 197
 in project.clj. See the
127 198
 [sample.project.clj](https://github.com/technomancy/leiningen/blob/preview/sample.project.clj).
@@ -253,7 +324,7 @@ included from the project template:
253 324
 
254 325
 Once we fill it in the test suite will become more useful. Sometimes
255 326
 if you've got a large test suite you'll want to run just one or two
256  
-namespaces at a time; `lein test my.test.stuff` will do that.. You
  327
+namespaces at a time; `lein test my.test.stuff` will do that. You
257 328
 also might want to break up your tests using test selectors; see `lein
258 329
 help test` for more details.
259 330
 
Commit_comment_tip

Tip: You can add notes to lines in a file. Hover to the left of a line to make a note

Something went wrong with that request. Please try again.