Introduction to Leiningen for Clojure – Leiningen for Clojure简介

最后修改: 2019年 2月 18日

中文/混合/英文(键盘快捷键：t)

1. Introduction

1.介绍

Leiningen is a modern build system for our Clojure projects. It’s also written and configured entirely in Clojure.

Leiningen是一个现代化的构建系统，用于我们的Clojure项目。它也是完全用Clojure编写和配置的。

It works similarly to Maven, giving us a declarative configuration that describes our project, without needing to configure exact steps to be executed.

它的工作原理与Maven类似，给我们一个描述项目的声明性配置，而不需要配置确切的执行步骤。

Let’s jump in and see how to get started with Leiningen for building our Clojure projects.

让我们跳进去，看看如何使用Leiningen来构建我们的Clojure项目。

2. Installing Leiningen

2.安装Leiningen

Leiningen is available as a standalone download, as well as from a large number of package managers for different systems.

Leiningen可以单独下载，也可以从大量用于不同系统的软件包管理器中获得。

Standalone downloads are available for Windows as well as for Linux and Mac. In all cases, download the file, make it executable if necessary, and then it’s ready to use.

独立下载可用于Windows，以及Linux和Mac。在所有情况下，下载文件，如有必要使其可执行，然后就可以使用了。

The first time the script is run it will download the rest of the Leiningen application, and then this will be cached from this point forward:

第一次运行脚本时，它将下载Leiningen应用程序的其余部分，然后这将从这一点开始缓存。

$ ./lein
Downloading Leiningen to /Users/user/.lein/self-installs/leiningen-2.8.3-standalone.jar now...
.....
Leiningen is a tool for working with Clojure projects.

Several tasks are available:
.....

Run `lein help $TASK` for details.

.....

3. Creating a New Project

3.创建一个新的项目

Once Leiningen is installed, we can use it to create a new project by invoking lein new.

一旦Leiningen被安装，我们可以通过调用lein new来创建一个新的项目。

This creates a project using a particular template from a set of options:

这将使用一组选项中的特定模板创建一个项目。

  • app – Used to create an application
  • default – Used to create a general project structure, typically for libraries
  • plugin – Used to create a Leiningen Plugin
  • template – Used to create new Leiningen templates for future projects

For example, to create a new application called “my-project” we would execute:

例如，要创建一个名为 “my-project “的新应用程序，我们将执行。

$ ./lein new app my-project
Generating a project called my-project based on the 'app' template.

This gives us a project containing:

这给了我们一个包含的项目。

  • A build definition – project.clj
  • A source directory – src – including an initial source file – src/my_project/core.clj
  • A test directory – test – including an initial test file – test/my_project/core_test.clj
  • Some additional documentation files – README.md, LICENSE, CHANGELOG.md and doc/intro.md

Looking inside our build definition, we’ll see that it tells us what to build, but not how to build it:

查看我们的构建定义，我们会发现它告诉我们要构建什么，但没有告诉我们如何构建：。

(defproject my-project "0.1.0-SNAPSHOT"
  :description "FIXME: write description"
  :url "http://example.com/FIXME"
  :license {:name "EPL-2.0 OR GPL-2.0-or-later WITH Classpath-exception-2.0"
            :url "https://www.eclipse.org/legal/epl-2.0/"}
  :dependencies [[org.clojure/clojure "1.9.0"]]
  :main ^:skip-aot my-project.core
  :target-path "target/%s"
  :profiles {:uberjar {:aot :all}})

This tells us:

这告诉我们。

  • The details of the project consisting of the project name, version, description, homepage and license details.
  • The main namespace to use when executing the application
  • The list of dependencies
  • The target path to build the output into
  • A profile for building an uberjar

Note that the main source namespace is my-project.core, and is found in the file my_project/core.clj. It’s discouraged in Clojure to use single-segment namespaces – the equivalent of top-level classes in a Java project.

请注意，主源命名空间是my-project.core，并在文件my_project/core.clj中找到。在Clojure中不鼓励使用单段命名空间–相当于Java项目中的顶级类。

Additionally, the filenames are generated with underscores instead of hyphens because the JVM has some problems with hyphens in filenames.

此外，文件名是用下划线而不是连字符生成的，因为JVM对文件名中的连字符有一些问题。

The generated code is pretty simple:

生成的代码相当简单。

(ns my-project.core
  (:gen-class))

(defn -main
  "I don't do a whole lot ... yet."
  [& args]
  (println "Hello, World!"))

Also, notice that Clojure is just a dependency here. This makes it trivial to write projects using whatever version of the Clojure libraries are desired, and especially to have multiple different versions running on the same system.

另外，请注意，Clojure在这里只是一个依赖关系。这使得使用任何版本的Clojure库来编写项目变得非常简单，尤其是在同一个系统上运行多个不同的版本。

If we change this dependency, then we’ll get the alternative version instead.

如果我们改变这个依赖关系，那么我们就会得到替代的版本。

4. Building and Running

4.建设和运行

Our project isn’t worth much if we can’t build it, run it and package it up for distribution, so let’s look at that next.

如果我们不能构建它、运行它并将它打包发布，我们的项目就没有什么价值，所以我们接下来看看这个问题。

4.1. Launching a REPL

4.1.启动REPL

Once we have a project, we can launch a REPL inside of it using lein repl. This will give us a REPL that has everything in the project already available on the classpath – including all project files as well as all dependencies.

一旦我们有了一个项目，我们可以使用lein repl在其中启动一个REPL。这将为我们提供一个 REPL，该项目中的所有内容都已在 classpath 上可用 – 包括所有项目文件以及所有依赖项。

It also starts us in the defined main namespace for our project:

它也让我们在为我们的项目定义的主命名空间中开始。

$ lein repl
nREPL server started on port 62856 on host 127.0.0.1 - nrepl://127.0.0.1:62856
[]REPL-y 0.4.3, nREPL 0.5.3
Clojure 1.9.0
Java HotSpot(TM) 64-Bit Server VM 1.8.0_77-b03

    Docs: (doc function-name-here)
          (find-doc "part-of-name-here")
  Source: (source function-name-here)
 Javadoc: (javadoc java-object-or-class-here)
    Exit: Control+D or (exit) or (quit)
 Results: Stored in vars *1, *2, *3, an exception in *e

my-project.core=> (-main)
Hello, World!
nil

This executes the function -main in the current namespace, which we saw above.

这将在当前命名空间中执行函数-main，我们在上面看到了这个。

4.2. Running the Application

4.2.运行应用程序

If we are working on an application project – created using lein new app – then we can simply run the application from the command line. This is done using lein run:

如果我们正在处理一个应用程序项目–使用lein new app创建–那么我们可以简单地从命令行中运行该应用程序。这是用lein run完成的。

$ lein run
Hello, World!

This will execute the function called -main in the namespace defined as :main in our project.clj file.

这将在我们的project.clj文件中定义为:main的命名空间中执行名为-main的函数。

4.3. Building a Library

4.3.建立一个图书馆

If we are working on a library project – created using lein new default – then we can build the library into a JAR file for inclusion in other projects.

如果我们正在处理一个库项目–使用lein new default创建的–那么我们可以将该库构建为JAR文件，以便纳入其他项目中。

We have two ways that we can achieve this – using lein jar or lein install. The difference is simply in where the output JAR file is placed.

我们有两种方法可以实现这一点–使用lein jar或lein install。区别仅仅在于输出的JAR文件被放在哪里。

If we use lein jar then it will place it in the local target directory:

如果我们使用lein jar，那么它将把它放在本地target目录中。

$ lein jar
Created /Users/user/source/me/my-library/target/my-library-0.1.0-SNAPSHOT.jar

If we use lein install, then it will build the JAR file, generate a pom.xml file and then place the two into the local Maven repository (typically under .m2/repository in the users home directory)

如果我们使用lein install，那么它将构建JAR文件，生成pom.xml文件，然后将两者放入本地Maven仓库（通常在用户主目录下的.m2/repository）。

$ lein install
Created /Users/user/source/me/my-library/target/my-library-0.1.0-SNAPSHOT.jar
Wrote /Users/user/source/me/my-library/pom.xml
Installed jar and pom into local repo.

4.4. Building an Uberjar

4.4.建立一个Uberjar

If we are working on an application project, Leiningen gives us the ability to build what is called an uberjar. This is a JAR file containing the project itself and all dependencies and set up to allow it to be run as-is.

如果我们正在处理一个应用程序项目，Leiningen给我们提供了建立所谓的uberjar的能力。这是一个JAR文件，包含了项目本身和所有的依赖关系，并被设置为允许它按原样运行。

$ lein uberjar
Compiling my-project.core
Created /Users/user/source/me/my-project/target/uberjar/my-project-0.1.0-SNAPSHOT.jar
Created /Users/user/source/me/my-project/target/uberjar/my-project-0.1.0-SNAPSHOT-standalone.jar

The file my-project-0.1.0-SNAPSHOT.jar is a JAR file containing exactly the local project, and the file my-project-0.1.0-SNAPSHOT-standalone.jar contains everything needed to run the application.

文件my-project-0.1.0-SNAPSHOT.jar是一个JAR文件，正好包含了本地项目，而文件my-project-0.1.0-SNAPSHOT-standalone.jar包含了运行应用程序所需的一切。

$ java -jar target/uberjar/my-project-0.1.0-SNAPSHOT-standalone.jar
Hello, World!

5. Dependencies

5.依赖性

Whilst we can write everything needed for our project ourselves, it’s generally significantly better to re-use the work that others have already done on our behalf. We can do this by having our project depend on these other libraries.

虽然我们可以自己编写项目所需的一切，但一般来说，重新使用别人已经代表我们完成的工作会好得多。我们可以通过让我们的项目依赖这些其他的库来做到这一点。

5.1. Adding Dependencies to Our Project

5.1.向我们的项目添加依赖项

To add dependencies to our project, we need to add them correctly to our project.clj file.

为了向我们的项目添加依赖，我们需要将它们正确地添加到我们的project.clj文件中。

Dependencies are represented as a vector consisting of the name and version of the dependency in question. We’ve already seen that Clojure itself is added as a dependency, written in the form [org.clojure/clojure “1.9.0”].

依赖关系被表示为一个由相关依赖关系的名称和版本组成的向量。我们已经看到，Clojure本身被添加为一个依赖关系，以[org.clojure/clojure “1.9.0”]的形式书写。

If we want to add other dependencies, we can do so by adding them to the vector next to the :dependencies keyword. For example, if we want to depend on clj-json we would update the file:

如果我们想添加其他的依赖关系，我们可以通过把它们添加到:dependencies关键字旁边的向量中来实现。例如，如果我们想依赖clj-json，我们将更新该文件。

  :dependencies [[org.clojure/clojure "1.9.0"] [clj-json "0.5.3"]]

Once done, if we start our REPL – or any other way to build or run our project – then Leiningen will ensure that the dependencies are downloaded and available on the classpath:

一旦完成，如果我们启动我们的REPL–或任何其他方式来构建或运行我们的项目–那么Leiningen将确保依赖项被下载并在classpath上可用。

$ lein repl
Retrieving clj-json/clj-json/0.5.3/clj-json-0.5.3.pom from clojars
Retrieving clj-json/clj-json/0.5.3/clj-json-0.5.3.jar from clojars
nREPL server started on port 62146 on host 127.0.0.1 - nrepl://127.0.0.1:62146
REPL-y 0.4.3, nREPL 0.5.3
Clojure 1.9.0
Java HotSpot(TM) 64-Bit Server VM 1.8.0_77-b03
    Docs: (doc function-name-here)
          (find-doc "part-of-name-here")
  Source: (source function-name-here)
 Javadoc: (javadoc java-object-or-class-here)
    Exit: Control+D or (exit) or (quit)
 Results: Stored in vars *1, *2, *3, an exception in *e

my-project.core=> (require '(clj-json [core :as json]))
nil
my-project.core=> (json/generate-string {"foo" "bar"})
"{\"foo\":\"bar\"}"
my-project.core=>

We can also use them from inside our project. For example, we could update the generated src/my_project/core.clj file as follows:

我们也可以从我们的项目内部使用它们。例如，我们可以更新生成的src/my_project/core.clj文件，如下。

(ns my-project.core
  (:gen-class))

(require '(clj-json [core :as json]))

(defn -main
  "I don't do a whole lot ... yet."
  [& args]
  (println (json/generate-string {"foo" "bar"})))

And then running it will do exactly as expected:

然后运行它将完全按照预期做。

$ lein run
{"foo":"bar"}

5.2. Finding Dependencies

5.2.寻找依赖关系

Often, it can be difficult to find the dependencies that we want to use in our project. Leiningen comes with a search functionality built in to make this easier. This is done using lein search.

通常情况下，我们很难找到我们项目中想要使用的依赖项。Leiningen内置了一个搜索功能，使之更加容易。这是用lein搜索完成的。

For example, we can find our JSON libraries:

例如，我们可以找到我们的JSON库。

$ lein search json
Searching central ...
[com.jwebmp/json "0.63.0.60"]
[com.ufoscout.coreutils/json "3.7.4"]
[com.github.iarellano/json "20190129"]
.....
Searching clojars ...
[cheshire "5.8.1"]
  JSON and JSON SMILE encoding, fast.
[json-html "0.4.4"]
  Provide JSON and get a DOM node with a human representation of that JSON
[ring/ring-json "0.5.0-beta1"]
  Ring middleware for handling JSON
[clj-json "0.5.3"]
  Fast JSON encoding and decoding for Clojure via the Jackson library.
.....

This searches all of the repositories that our project is working with – in this case, Maven Central and Clojars. It then returns the exact string to put into our project.clj file and, if available, the description of the library.

这将搜索我们的项目所使用的所有资源库 – 在本例中，Maven Central和Clojars。然后，它返回准确的字符串，以放入我们的project.clj文件中，如果有的话，还有库的描述。

6. Testing Our Project

6.测试我们的项目

Clojure has built-in support for unit testing our application, and Leiningen can harness this for our projects.

Clojure内置支持对我们的应用程序进行单元测试，Leiningen可以为我们的项目利用这一点。

Our generated project contains test code in the test directory, alongside the source code in the src directory. It also includes a single, failing test by default – found in test/my_project/core-test.clj:

我们生成的项目在test目录下包含测试代码，以及src目录下的源代码。它还包括一个默认的失败测试–在test/my_project/core-test.clj中找到。

(ns my-project.core-test
  (:require [clojure.test :refer :all]
            [my-project.core :refer :all]))

(deftest a-test
  (testing "FIXME, I fail."
    (is (= 0 1))))

This imports the my-project.core namespace from our project, and the clojure.test namespace from the core Clojure language. We then define a test with the deftest and testing calls.

这从我们的项目中导入my-project.core命名空间，从核心Clojure语言中导入clojure.test命名空间。然后我们用deftest和testing调用来定义一个测试。

We can immediately see the names of the test, and the fact that it’s deliberately written to fail – it asserts that 0 == 1.

我们可以立即看到这个测试的名字，以及它故意写成失败的事实–它断言0 == 1。

Let’s run this using the lein test command, and immediately see the tests running and failing:

让我们使用lein test命令来运行它，并立即看到测试的运行和失败。

$ lein test
lein test my-project.core-test

lein test :only my-project.core-test/a-test

FAIL in (a-test) (core_test.clj:7)
FIXME, I fail.
expected: (= 0 1)
  actual: (not (= 0 1))

Ran 1 tests containing 1 assertions.
1 failures, 0 errors.
Tests failed.

If we instead fix the test, changing it to assert that 1 == 1 instead, then we’ll get a passing message instead:

如果我们修改这个测试，把它改为断言1 == 1，那么我们就会得到一个通过的消息。

$ lein test
lein test my-project.core-test

Ran 1 tests containing 1 assertions.
0 failures, 0 errors.

This is a much more succinct output, only showing what we need to know. This means that when there are failures, they immediately stand out.

这是一个更简洁的输出，只显示我们需要知道的东西。这意味着，当有失败时，它们会立即凸显出来。

If we want to, we can also run a specific subset of the tests. The command line allows for a namespace to be provided, and only tests in that namespace are executed:

如果我们愿意，我们也可以运行一个特定的测试子集。命令行允许提供一个命名空间，并且只执行该命名空间的测试。

$ lein test my-project.core-test

lein test my-project.core-test

Ran 1 tests containing 1 assertions.
0 failures, 0 errors.

$ lein test my-project.unknown

lein test my-project.unknown

Ran 0 tests containing 0 assertions.
0 failures, 0 errors.

7. Summary

7.总结

This article has shown how to get started with the Leiningen build tool, and how to use it to manage our Clojure based projects – both executable applications and shared libraries.

本文介绍了如何开始使用Leiningen构建工具，以及如何使用它来管理我们基于Clojure的项目–包括可执行的应用程序和共享库。

Why not try it for out on the next project and see how well it can work.

为什么不在下一个项目中尝试一下，看看它的工作效果如何。