Skip to content

Commit

Permalink
Remove outdated stuff from README
Browse files Browse the repository at this point in the history
  • Loading branch information
@Deraen
Deraen committed May 17, 2015
1 parent decb386 commit 1f7457c
Showing 1 changed file with 28 additions and 98 deletions.
126 changes: 28 additions & 98 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,6 @@
* Provides a mechanism by which multiple multiple JS applications can be
compiled in the same project.

* Provides a mechanism by which JS preamble, and Google Closure libs and
externs files can be included in Maven jar dependencies or from the project
source directories.

## Try It

In a terminal do:
Expand Down Expand Up @@ -44,7 +40,7 @@ You can see the options available on the command line:
boot cljs -h
```

or in the REPL:
Or in the REPL:

```clj
boot.user=> (doc cljs)
Expand Down Expand Up @@ -83,31 +79,6 @@ JavaScript:
<script type='text/javascript' src='main.js'></script>
```

Since the Closure compiler concatenates the individual JS files this is all
you need for the production version of your application.

For development, however, the Closure compiler is bypassed and no concatenation
is done, so you normally need to add two other `<script>` tags for the Closure
`base.js` dependency and to `goog.require()` your main namespace, plus tags to
load any external JS libraries your application depends on:

```html
<!-- external JS libraries -->
<script type='text/javascript' src='react.min.js'></script>
<script type='text/javascript' src='jquery.min.js'></script>

<!-- compiling with optimizations == none -->
<script type='text/javascript' src='out/goog/base.js'></script>
<script type='text/javascript' src='main.js'></script>
<script type='text/javascript'>goog.require('my.namespace');</script>
```

**This is not necessary with the boot `cljs` task.** The `cljs` task is smart
enough to arrange all of this for you automatically, so the application HTML
file can be the same whether compiling with or without optimizations. You only
need the one `<script>` tag as in the first example above. This will work with
all compilation levels.

### Source Maps

[Source maps][src-maps] associate locations in the compiled JavaScript file with
Expand Down Expand Up @@ -156,7 +127,7 @@ The `cljs` task provides a way to specify application entry points at which it
can point the CLJS compiler for compilation. These entry points are provided
via files with the `.cljs.edn` extension.

These files have the following structure (eg. `js/index.cljs.edn`):
These files have the following structure (e.g. `js/index.cljs.edn`):

```clojure
{:require [foo.bar baz.baf]
Expand All @@ -166,7 +137,7 @@ These files have the following structure (eg. `js/index.cljs.edn`):

For each `.cljs.edn` file in the fileset, the `cljs` task will:

* Create a CLJS namespace corresponding to the file's path, eg. given the file
* Create a CLJS namespace corresponding to the file's path, e.g. given the file
`foo/bar.cljs.edn` it will create the `foo.bar` CLJS namespace. This namespace
will `:require` any namespaces given in the `:require` key of the EDN, and
add a `do` expression that calls any functions in `:init-fns` at the top
Expand All @@ -176,7 +147,7 @@ For each `.cljs.edn` file in the fileset, the `cljs` task will:
if there is one.

* Configure the compiler to produce compiled JS at a location derived from the
file's path, eg. given the file `foo/bar.cljs.edn` the output JS file will
file's path, e.g. given the file `foo/bar.cljs.edn` the output JS file will
be `foo/bar.js`.

* Point the CLJS compiler at the generated namespace only. This "scopes" the
Expand All @@ -192,33 +163,37 @@ The example above would result in the following CLJS namespace, `js/index.cljs`:
(baz.baf/doit))
```

and would be compiled to `js/index.js`. This is the JS script you'd add to the
application's HTML file via a `<script>` tag.
The result would be compiled to `js/index.js`. This is the JS script you'd add
to the application's HTML file via a `<script>` tag.

### Browser REPL

See the [adzerk/boot-cljs-repl][boot-cljs-repl] boot task.

### Preamble, Externs, and Lib Files
### Preamble and Externs Files

Jars with `deps.cljs`, like the ones provided by [cljsjs][cljsjs] can
be used to supply Javascript libraries. Alternatively the mechanism
described below can be used:
be used to supply Javascript libraries. If you need to use local js files
you can manually create deps.cljs in your local project:

The `cljs` task scans the fileset for files that have special filename
extensions. File extensions recognized by the `cljs` task:

* `.inc.js`: JavaScript preamble files–these are prepended to the compiled
Javascript in dependency order (i.e. if jar B depends on jar A then entries
from A will be added to the JavaScript file such that they'll be evaluated
before entries from B).
src/deps.cljs:
```clj
{:foreign-libs [{:file "bar.js"
:provides ["foo.bar"]}]
:externs ["bar.ext.js"]}
```

* `.lib.js`: GClosure lib files (JavaScript source compatible with the Google
Closure compiler).
src/bar.js:
```js
function foo() {
console.log("Hello world from local js");
}
```

* `.ext.js`: [GClosure externs files][closure-externs]–hints to the Closure
compiler that prevent it from mangling external names under advanced
optimizations.
src/bar.ext.js:
```js
foo = function() {};
```

## Examples

Expand All @@ -233,7 +208,7 @@ my-project
└── foop.cljs
```

and add the following contents to `build.boot`:
And add the following contents to `build.boot`:

```clj
(set-env!
Expand All @@ -252,66 +227,21 @@ boot cljs -s

The compiled JavaScript file will be `target/main.js`.

### Preamble and Externs

Add preamble and extern files to the project, like so:

```
my-project
├── build.boot
├── html
│   └── index.html
└── src
├── foop.cljs
└── js
├── barp.ext.js
└── barp.inc.js
```

With the contents of `barp.inc.js` (a preamble file):

```javascript
(function() {
window.Barp = {
bazz: function(x) {
return x + 1;
}
};
})();
```

and `barp.ext.js` (the externs file for `barp.inc.js`):

```javascript
var Barp = {};
Barp.bazz = function() {};
```

Then, in `foop.cljs` you may freely use `Barp`, like so:

```clj
(ns foop)

(.log js/console "Barp.bazz(1) ==" (.bazz js/Barp 1))
```

Compile with advanced optimizations and source maps:

```bash
boot cljs -sO advanced
```

You will see the preamble inserted at the top of `main.js`, and the references
to `Barp.bazz()` are not mangled by the Closure compiler. Whew!

### Further Reading

For an example project with a local web server, CLJS REPL, and live-reload,
check out [boot-cljs-example]!

## License

Copyright © 2014 Adzerk
Copyright © 2014 Adzerk<br>
Copyright © 2015 Juho Teperi

Distributed under the Eclipse Public License either version 1.0 or (at
your option) any later version.
Expand Down

0 comments on commit 1f7457c

Please sign in to comment.