Skip to content

Commit

Permalink
Fix markdown and formatting issues.
Browse files Browse the repository at this point in the history
  • Loading branch information
@mneise
mneise committed Apr 24, 2017
1 parent 4ba27e5 commit 29ba1f5
Show file tree
Hide file tree
Showing 6 changed files with 90 additions and 91 deletions.
52 changes: 26 additions & 26 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
[![Clojars Project](https://clojars.org/lein-cljsbuild/latest-version.svg)](http://clojars.org/lein-cljsbuild)

This is a Leiningen plugin that makes it quick and easy to automatically compile
your ClojureScript code into Javascript whenever you modify it. It's simple
your ClojureScript code into Javascript whenever you modify it. It's simple
to install and allows you to configure the ClojureScript compiler from within your
`project.clj` file.

Expand All @@ -26,7 +26,7 @@ to target both Clojure and ClojureScript from the same codebase.*
## Requirements

The lein-cljsbuild plugin works with
[Leiningen] (https://github.com/technomancy/leiningen/blob/master/README.md)
[Leiningen](https://github.com/technomancy/leiningen/blob/master/README.md)
version `2.1.2` or higher.

## Installation
Expand All @@ -40,35 +40,35 @@ file in the `:plugins` section:
```

In addition, _you should add an explicit ClojureScript dependency to your
project_, like this:
project using the ClojureScript version you want to use_:

```clojure
:dependencies [[org.clojure/clojurescript "0.0-XXXX"]]
:dependencies [[org.clojure/clojurescript "1.9.521"]]
```

lein-cljsbuild will add a dependency to your project if it doesn't already
contain one, but that functionality will not remain for long. The latest
contain one, but that functionality will not remain for long. The latest
version of lein-cljsbuild currently requires a minimum of ClojureScript
`0.0-3211`.

## Just Give Me a Damned Example Already!

See the
[example-projects] (https://github.com/emezeske/lein-cljsbuild/blob/1.1.5/example-projects)
directory for a couple of simple examples of how to use lein-cljsbuild. The
[simple project] (https://github.com/emezeske/lein-cljsbuild/blob/1.1.5/example-projects/simple)
shows a dead-simple "compile only" configuration, which is a good place to start. The
[advanced project] (https://github.com/emezeske/lein-cljsbuild/blob/1.1.5/example-projects/advanced)
[example-projects](https://github.com/emezeske/lein-cljsbuild/blob/1.1.5/example-projects)
directory for a couple of simple examples of how to use lein-cljsbuild. The
[simple project](https://github.com/emezeske/lein-cljsbuild/blob/1.1.5/example-projects/simple)
shows a dead-simple "compile only" configuration, which is a good place to start. The
[advanced project](https://github.com/emezeske/lein-cljsbuild/blob/1.1.5/example-projects/advanced)
contains examples of how to use the extended features of the plugin.

Also, see the
[sample.project.clj] (https://github.com/emezeske/lein-cljsbuild/blob/1.1.5/sample.project.clj)
[sample.project.clj](https://github.com/emezeske/lein-cljsbuild/blob/1.1.5/sample.project.clj)
file for an exhaustive list of all options supported by lein-cljsbuild.

## Basic Configuration

The lein-cljsbuild configuration is specified under the `:cljsbuild` section
of your `project.clj` file. A simple project might look like this:
of your `project.clj` file. A simple project might look like this:

```clj
(defproject lein-cljsbuild-example "1.2.3"
Expand All @@ -86,7 +86,7 @@ of your `project.clj` file. A simple project might look like this:
```

For an exhaustive list of the configuration options supported by lein-cljsbuild, see the
[sample.project.clj] (https://github.com/emezeske/lein-cljsbuild/blob/1.1.5/sample.project.clj)
[sample.project.clj](https://github.com/emezeske/lein-cljsbuild/blob/1.1.5/sample.project.clj)
file.

## Basic Usage
Expand All @@ -96,7 +96,7 @@ Once the plugin is installed, you can build the ClojureScript once:
$ lein cljsbuild once

Or you can have lein-cljsbuild watch your source files for changes and
automatically rebuild them. This is recommended for development, as it
automatically rebuild them. This is recommended for development, as it
avoids the time-consuming JVM startup for each build:

$ lein cljsbuild auto
Expand All @@ -109,21 +109,21 @@ generates during compilation.
### Color-coded output on Windows

Colors are a big deal when reading ClojureScript compiler output, but Windows
consoles don't support ANSI color codes. This limitation is commonly corrected by
consoles don't support ANSI color codes. This limitation is commonly corrected by
installing ANSICON:

1. Download and unzip [ANSICON](https://github.com/downloads/adoxa/ansicon/ansi160.zip) anywhere.
1. Open a command prompt (Run as administrator).
1. Navigate to the unzipped folder.
1. cd x86 or x64 (depending on whether you have 32-bit or 64-bit machine, respectively)
1. Run `ansicon -i` to install.
2. Open a command prompt (Run as administrator).
3. Navigate to the unzipped folder.
4. cd x86 or x64 (depending on whether you have 32-bit or 64-bit machine, respectively)
5. Run `ansicon -i` to install.

Afterwards, you should get colored output from all future console sessions that use ANSI color codes.

## Hooks

Some common lein-cljsbuild tasks can hook into the main Leiningen tasks
to enable ClojureScript support in each of them. The following tasks are
to enable ClojureScript support in each of them. The following tasks are
supported:

$ lein compile
Expand All @@ -138,7 +138,7 @@ your project configuration:
```

Note that by default the `lein jar` task does *not* package your ClojureScript
code in the JAR file. This feature needs to be explicitly enabled by adding
code in the JAR file. This feature needs to be explicitly enabled by adding
the following entry to each of the `:builds` that you want included in the
JAR file. `lein uberjar` derives its behavior from `lein jar` and will include
the ClojureScript as well if enabled.
Expand Down Expand Up @@ -214,20 +214,20 @@ You can also build multiple configurations at once:
$ lein cljsbuild auto main other

See the
[example-projects/advanced] (https://github.com/emezeske/lein-cljsbuild/blob/1.1.5/example-projects/advanced)
[example-projects/advanced](https://github.com/emezeske/lein-cljsbuild/blob/1.1.5/example-projects/advanced)
directory for a working example of a project that uses this feature.

## REPL Support

Lein-cljsbuild has built-in support for launching ClojureScript REPLs in a variety
of ways. See the
[REPL documentation] (https://github.com/emezeske/lein-cljsbuild/blob/1.1.5/doc/REPL.md)
of ways. See the
[REPL documentation](https://github.com/emezeske/lein-cljsbuild/blob/1.1.5/doc/REPL.md)
for more details.

## Testing Support

Lein-cljsbuild has built-in support for running external ClojureScript test processes. See the
[testing documentation] (https://github.com/emezeske/lein-cljsbuild/blob/1.1.5/doc/TESTING.md)
Lein-cljsbuild has built-in support for running external ClojureScript test processes. See the
[testing documentation](https://github.com/emezeske/lein-cljsbuild/blob/1.1.5/doc/TESTING.md)
for more details.

## Extended Configuration
Expand Down
14 changes: 7 additions & 7 deletions doc/CROSSOVERS.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,8 @@ conditionals](http://dev.clojure.org/display/design/Reader+Conditionals)
target both Clojure and ClojureScript from the same codebase.

Sharing code with lein-cljsbuild is accomplished via the configuration
of "crossovers". A crossover specifies a Clojure namespace, the content
of which should be copied into your ClojureScript project. This can be any
of "crossovers". A crossover specifies a Clojure namespace, the content
of which should be copied into your ClojureScript project. This can be any
namespace that is available via the Java CLASSPATH, which includes your
project's main :source-paths by default.

Expand All @@ -36,7 +36,7 @@ the files that make up that namespace (recursively) will be monitored for change
and will be copied to the ClojureScript project whenever modified.

Crossover namespaces provided by jar files cannot be searched recursively, and
thus must be specified on a per-file basis. They are copied over once, when
thus must be specified on a per-file basis. They are copied over once, when
lein-cljsbuild begins compilation, and are not monitored for changes.

Of course, remember that since the namespace will be used by both Clojure
Expand Down Expand Up @@ -93,7 +93,7 @@ to `crossover-cljs`, and you'd end up with this:
</pre>

Notice that the files in the `crossover-cljs` directory have had their extensions
modified so that they will be seen by the ClojureScript compiler. The `crossover-cljs`
modified so that they will be seen by the ClojureScript compiler. The `crossover-cljs`
directory will automatically be added to the classpath for the ClojureScript compiler,
so your other ClojureScript code should be able to reference it via a regular `(ns)` form.

Expand All @@ -104,7 +104,7 @@ by lein-cljsbuild.
# Sharing Macros Between Clojure and ClojureScript

In ClojureScript, macros are still written in Clojure, and can not be written
in the same file as actual ClojureScript code. Also, to use them in a ClojureScript
in the same file as actual ClojureScript code. Also, to use them in a ClojureScript
namespace, they must be required via `:require-macros` rather than the usual `:require`.

This makes using the crossover feature to share macros between Clojure and ClojureScript
Expand All @@ -127,7 +127,7 @@ Add this magical comment to any crossover files that contain macros:
```

This tells lein-cljsbuild to refrain from copying the `.clj` files
into the `:crossover-path`. This step can be skipped if the
into the `:crossover-path`. This step can be skipped if the
macro file is not included in any of the crossover namespaces.

## 3. Use Black Magic to Require Macros Specially
Expand Down Expand Up @@ -157,7 +157,7 @@ Thus, after removing comments, Clojure will see:
```

However, lein-cljsbuild will remove the `;*CLJSBUILD-REMOVE*;` string entirely,
before copying the file. Thus, ClojureScript will see:
before copying the file. Thus, ClojureScript will see:

```clj
(ns example.crossover.some_stuff
Expand Down
18 changes: 9 additions & 9 deletions doc/MIGRATING-TO-0.1.x.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,22 +4,22 @@ The `0.1.x` release of lein-cljsbuild adds several new features that necessitate
some changes to the format of the `:cljsbuild` configuration entry.

With that said, `0.1.x` **is** backwards-compatible with your existing configuration.
However, it will be complaining loudly about how it's deprecated. This document
However, it will be complaining loudly about how it's deprecated. This document
explains how to fix that.

The next major release will drop backwards compatibilty with `0.0.x`, so get
your project updated soon!

## The Easy Way

Before doing anything else, `lein cljsbuild clean`. This will remove old temporary files
that may be renamed in the new version. Most importantly, it will remove any crossover files
that have been copied into place. **This is very important. If you are using crossovers,
Before doing anything else, `lein cljsbuild clean`. This will remove old temporary files
that may be renamed in the new version. Most importantly, it will remove any crossover files
that have been copied into place. **This is very important. If you are using crossovers,
skipping this step will cause pain!**

Once you've updated your project to use `[lein-cljsbuild "0.1.x"]`, run any subcommand,
for instance, `lein cljsbuild once`. The plugin will complain that your configuration
is deprecated. However, it should automatically convert your `:cljsbuild` entry to the new
for instance, `lein cljsbuild once`. The plugin will complain that your configuration
is deprecated. However, it should automatically convert your `:cljsbuild` entry to the new
format, and print it out.

You should be able to just replace your existing `:cljsbuild` entry with this one and be all set.
Expand All @@ -28,13 +28,13 @@ You should be able to just replace your existing `:cljsbuild` entry with this on

In case you want to know specifically what has changed:

* Several plugin-global options have been added. Thus, what used to be the top-level
* Several plugin-global options have been added. Thus, what used to be the top-level
config has been moved into the `:builds` entry.

* The `:builds` entry is not allowed to be either a map or a vector, like the `:cljsbuild`
entry used to be. It is always a vector of maps.
entry used to be. It is always a vector of maps.

* The `:output-dir` entry for each of the `:compiler` entries must now be unique. Previously, they
* The `:output-dir` entry for each of the `:compiler` entries must now be unique. Previously, they
could be set to the same directory, which caused a nasty race condition (and failed compiles).

* `:crossovers` are no longer specified per-build -- they are global to the whole project.
Expand Down
26 changes: 13 additions & 13 deletions doc/RELEASE-NOTES.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@
* ClojureScript `0.0-2156` is now the default release added to projects that do
not specify a ClojureScript dependency explicitly.
* Crossovers are now officially deprecated, and will be removed in future
releases. Please use [cljx](http://github.com/lynaghk/cljx) to target both
releases. Please use [cljx](http://github.com/lynaghk/cljx) to target both
Clojure and ClojureScript from the same codebase.
* Fixed timestamps applied to compiled output files (gh-281, gh-282)

Expand All @@ -99,7 +99,7 @@ No changes since `1.0.0-alpha2`.
## [1.0.0-alpha2](https://github.com/emezeske/lein-cljsbuild/issues?milestone=33&page=1&state=closed)

* ClojureScript `0.0-2014` is now the default release added to projects that do
not specify a ClojureScript dependency explicitly. Further, this version of
not specify a ClojureScript dependency explicitly. Further, this version of
ClojureScript is now a **minimum requirement**; if upgrading to `0.0-2014` is
not possible for some reason, you must stick with prior revisions of
lein-cljsbuild. (gh-253, gh-264)
Expand Down Expand Up @@ -160,9 +160,9 @@ No changes since `1.0.0-alpha2`.

## 0.3.0

1. Dropped support for Leiningen 1.x, now that Leiningen 2.0 is available. **REPEAT: Leiningen 1.x is no longer supported.**
2. Changed the `:source-path "path"` option to `:source-paths ["path" "path"]`. The new option accepts a vector of paths rather than a single path. **The old singular `:source-path` is now deprecated and will be removed soon.**
3. Changed all default output paths (e.g. for temporary compiler files, crossover files, and REPL files) to be in the `:target-path` directory. Explicitly configured paths can still be whatever you like.
1. Dropped support for Leiningen 1.x, now that Leiningen 2.0 is available. **REPEAT: Leiningen 1.x is no longer supported.**
2. Changed the `:source-path "path"` option to `:source-paths ["path" "path"]`. The new option accepts a vector of paths rather than a single path. **The old singular `:source-path` is now deprecated and will be removed soon.**
3. Changed all default output paths (e.g. for temporary compiler files, crossover files, and REPL files) to be in the `:target-path` directory. Explicitly configured paths can still be whatever you like.
4. For compatibility with Leiningen 2.0, `:resource-paths` is now used instead of `:resources-path`.
5. Fixed a long delay before exiting that could sometimes occur after one-shot tasks (like `cljsbuild once`).
6. Changes to JavaScript files in `:libs` now trigger rebuilds when using `cljsbuild auto`.
Expand Down Expand Up @@ -216,7 +216,7 @@ No changes since `1.0.0-alpha2`.

## 0.2.4

1. Removed support for `:warn-on-undeclared`, because the compiler itself now supports a `:warnings` option. Use that instead.
1. Removed support for `:warn-on-undeclared`, because the compiler itself now supports a `:warnings` option. Use that instead.

[Milestone Details for this Release](https://github.com/emezeske/lein-cljsbuild/issues?milestone=18&state=closed)

Expand All @@ -236,7 +236,7 @@ No changes since `1.0.0-alpha2`.

## 0.2.1

1. Automatically add `closure-js/libs` to `:libs` and `closure-js/externs` to `:externs`. This means that libraries can put their libs and externs in `resources/closure-js/libs/<library-name>` and `resources/closure-js/externs/<library-name>`, respectively, and lein-cljsbuild will automatically pick them up.
1. Automatically add `closure-js/libs` to `:libs` and `closure-js/externs` to `:externs`. This means that libraries can put their libs and externs in `resources/closure-js/libs/<library-name>` and `resources/closure-js/externs/<library-name>`, respectively, and lein-cljsbuild will automatically pick them up.

[Milestone Details for this Release](https://github.com/emezeske/lein-cljsbuild/issues?milestone=15&state=closed)

Expand All @@ -245,10 +245,10 @@ No changes since `1.0.0-alpha2`.
Note that the minor version was incremented not due to any major features, but due to the fact that the `:notify-command` option was changed in a backwards-incompatible way.

1. The compiler is now run under Clojure 1.4.0.
2. Added a new `:build` suboption `:incremental`, which determines whether intermediate JavaScript sources are left intact between automatic builds. The old behavior was to delete intermediate files before each build. This slowed things down, but worked around (unisolated) problems with incremental compilation. Incremental builds are now the default, as they appear to work well, but this option allows the old behavior to be selected if necessary for troubleshooting.
3. The :notify option has been changed such that its argument is consistent with other cljsbuild shell commands. This means that the `%` argument is no longer respected, and the textual result will simply be appended as the last command line argument. Also, `:beep true` no longer has any effect. If either of these features is desired, the recommended solution is a small shell script wrapper.
4. Clojure source files that reside in the ClojureScript :source-path (as well as crossover macro files) are now monitored for changes. When modified, they will be reloaded, and a build will be triggered. This is useful for ClojureScript projects that use macros.
5. Multiple builds are now built sequentially instead of in parallel. This is due to the fact that the underlying compiler is no longer thread-safe.
2. Added a new `:build` suboption `:incremental`, which determines whether intermediate JavaScript sources are left intact between automatic builds. The old behavior was to delete intermediate files before each build. This slowed things down, but worked around (unisolated) problems with incremental compilation. Incremental builds are now the default, as they appear to work well, but this option allows the old behavior to be selected if necessary for troubleshooting.
3. The :notify option has been changed such that its argument is consistent with other cljsbuild shell commands. This means that the `%` argument is no longer respected, and the textual result will simply be appended as the last command line argument. Also, `:beep true` no longer has any effect. If either of these features is desired, the recommended solution is a small shell script wrapper.
4. Clojure source files that reside in the ClojureScript :source-path (as well as crossover macro files) are now monitored for changes. When modified, they will be reloaded, and a build will be triggered. This is useful for ClojureScript projects that use macros.
5. Multiple builds are now built sequentially instead of in parallel. This is due to the fact that the underlying compiler is no longer thread-safe.

[Milestone Details for this Release](https://github.com/emezeske/lein-cljsbuild/issues?milestone=14&state=closed)

Expand All @@ -273,7 +273,7 @@ Note that the minor version was incremented not due to any major features, but d

## 0.1.7

1. The various REPL commands now work when used via Leiningen 2. This should mean that lein-cljsbuild is fully Leiningen-2-compatible.
1. The various REPL commands now work when used via Leiningen 2. This should mean that lein-cljsbuild is fully Leiningen-2-compatible.
2. Raise a descriptive error if the parent project uses Clojure < 1.3.
3. Ensure that `lein cljsbuild clean` cleans up :stdout and :stderr files for various commands.
4. Add a comprehensive unit test suite, to hopefully help prevent new releases from breaking things.
Expand All @@ -282,6 +282,6 @@ Note that the minor version was incremented not due to any major features, but d

## 0.1.6

1. Changed to use upstream ClojureScript version 0.0-1011. This should fix REPL issues.
1. Changed to use upstream ClojureScript version 0.0-1011. This should fix REPL issues.

[Milestone Details for this Release](https://github.com/emezeske/lein-cljsbuild/issues?sort=created&direction=desc&state=closed&page=1&milestone=9)
Loading

0 comments on commit 29ba1f5

Please sign in to comment.