README.md in sprockets-2.12.5 vs README.md in sprockets-3.0.0.beta.1
- old
+ new
@@ -1,21 +1,21 @@
# Sprockets: Rack-based asset packaging
Sprockets is a Ruby library for compiling and serving web assets.
It features declarative dependency management for JavaScript and CSS
assets, as well as a powerful preprocessor pipeline that allows you to
-write assets in languages like CoffeeScript, Sass, SCSS and LESS.
+write assets in languages like CoffeeScript, Sass and SCSS.
# Installation #
Install Sprockets from RubyGems:
$ gem install sprockets
Or include it in your project's `Gemfile` with Bundler:
- gem 'sprockets', '~> 2.0'
+ gem 'sprockets', '~> 3.0'
# Understanding the Sprockets Environment #
You'll need an instance of the `Sprockets::Environment` class to
access and serve assets from your application. Under Rails 3.1 and
@@ -124,11 +124,11 @@
environment['application.js']
# => #<Sprockets::BundledAsset ...>
Call `to_s` on the resulting asset to access its contents, `length` to
get its length in bytes, `mtime` to query its last-modified time, and
-`pathname` to get its full path on the filesystem.
+`filename` to get its full path on the filesystem.
# Using Engines #
Asset source files can be written in another language, like SCSS or
CoffeeScript, and automatically compiled to CSS or JavaScript by
@@ -137,10 +137,19 @@
Engines are specified by additional extensions on the asset source
filename. For example, a CSS file written in SCSS might have the name
`layout.css.scss`, while a JavaScript file written in CoffeeScript
might have the name `dialog.js.coffee`.
+## Minifying Assets ##
+
+Several JavaScript and CSS minifiers are available through shorthand.
+
+``` ruby
+environment.js_compressor = :uglify
+environment.css_compressor = :scss
+```
+
## Styling with Sass and SCSS ##
[Sass](http://sass-lang.com/) is a language that compiles to CSS and
adds features like nested rules, variables, mixins and selector
inheritance.
@@ -150,23 +159,10 @@
Sprockets supports both Sass syntaxes. For the original
whitespace-sensitive syntax, use the extension `.css.sass`. For the
new SCSS syntax, use the extension `.css.scss`.
-## Styling with LESS ##
-
-[LESS](http://lesscss.org/) extends CSS with dynamic behavior such as
-variables, mixins, operations and functions.
-
-If the `less` gem is available to your application, you can use LESS
-to write CSS assets in Sprockets. Note that the LESS compiler is
-written in JavaScript and the `less` gem (on MRI) uses `therubyracer`
-which embeds the V8 JavaScript runtime in Ruby, while on JRuby you're
-going to need `therubyrhino` gem installed.
-
-To write CSS assets with LESS, use the extension `.css.less`.
-
## Scripting with CoffeeScript ##
[CoffeeScript](http://jashkenas.github.com/coffee-script/) is a
language that compiles to the "good parts" of JavaScript, featuring a
cleaner syntax with array comprehensions, classes, and function
@@ -235,11 +231,11 @@
helper provided by the Sprockets Rails plugin
- embedding other application resources, such as a localized string
database, in a JavaScript asset via JSON
- embedding version constants loaded from another file
-See the [Helper Methods](#FIXME) section for more information about
+See the [Helper Methods](lib/sprockets/context.rb) section for more information about
interacting with `Sprockets::Context` instances via ERB.
### String Interpolation Syntax ###
If you need access to Ruby from an asset but cannot use ERB's `<% …
@@ -305,16 +301,10 @@
`require` *path* inserts the contents of the asset source file
specified by *path*. If the file is required multiple times, it will
appear in the bundle only once.
-### The `include` Directive ###
-
-`include` *path* works like `require`, but inserts the contents of the
-specified source file even if it has already been included or
-required.
-
### The `require_directory` Directive ###
`require_directory` *path* requires all source files of the same
format in the directory specified by *path*. Files are required in
alphabetical order.
@@ -326,29 +316,54 @@
directory specified by *path*.
### The `require_self` Directive ###
`require_self` tells Sprockets to insert the body of the current
-source file before any subsequent `require` or `include` directives.
+source file before any subsequent `require` directives.
+### The `link` Directive ###
+
+`link` *path* declares a dependency on the target *path* and adds it to a list
+of subdependencies to automatically be compiled when the asset is written out to
+disk.
+
+For an example, in a CSS file you might reference an external image that always
+need to be compiled along with the css file.
+
+``` css
+/* link "logo.png" */
+.logo {
+ background-image: url(logo.png)
+}
+```
+
+However, if you use a `asset-path/url` SCSS helper, these links will
+automatically be setup for you.
+
+``` css
+.logo {
+ background-image: asset-url("logo.png")
+}
+```
+
### The `depend_on` Directive ###
`depend_on` *path* declares a dependency on the given *path* without
including it in the bundle. This is useful when you need to expire an
asset's cache in response to a change in another file.
### The `depend_on_asset` Directive ###
`depend_on_asset` *path* works like `depend_on`, but operates
-recursively reading the the file and following the directives found.
+recursively reading the file and following the directives found.
### The `stub` Directive ###
`stub` *path* allows dependency to be excluded from the asset bundle.
The *path* must be a valid asset and may or may not already be part
-of the bundle. Once stubbed, it is blacklisted and can't be brought
-back by any other `require`.
+of the bundle. `stub` should only be used at the top level bundle, not
+within any subdependencies.
# Development #
## Contributing ##
@@ -364,13 +379,23 @@
the Sprockets repository, write a failing test case, fix the bug and
submit a pull request.
## Version History ##
-**2.12.3** (October 28, 2014)
+**3.0.0**
-* Security: Fix directory traversal bug in development mode server.
+* MIME Types now accept charset custom charset detecters. Improves support for UTF-16/32 files.
+* Environment#version no longer affects asset digests. Only used for busting the asset cache.
+* Removed builtin support for LESS.
+* Removed include directive support.
+* Deprecated BundledAsset#to_a. Use BundledAsset#included to access debugging subcomponents.
+* Support circular dependencies. For parity with ES6 modules.
+* Manifest compilation will no longer generate .gz files by default. [Mixing
+ Content-Encoding and ETags is just a bad
+ idea](https://issues.apache.org/bugzilla/show_bug.cgi?id=39727)
+* Added linked or referenced assets. When an asset is compiled, any of its links
+ will be compiled as well.
**2.12.2** (September 5, 2014)
* Ensure internal asset lookups calls are still restricted to load paths within
asset compiles. Though, you should not depend on internal asset resolves to be
@@ -386,11 +411,13 @@
* Avoid context reference in SassImporter hack so its Marshallable. Fixes
issues with Sass 3.3.x.
**2.11.0** (February 19, 2014)
-* Support for `.bower.json`
+* Cache store must now be an LRU implementation.
+* Default digest changed to SHA1. To continue using MD5.
+ `env.digest_class = Digest::MD5`.
**2.10.0** (May 24, 2013)
* Support for `bower.json`
@@ -420,11 +447,11 @@
* Fixed Sass importer bug
**2.8.0** (October 16, 2012)
-* Allow manifest location to be seperated from output directory
+* Allow manifest location to be separated from output directory
* Pass logical path and absolute path to each_logical_path iterator
**2.7.0** (October 10, 2012)
* Added --css-compressor and --js-compressor command line flags
@@ -493,11 +520,11 @@
* Added `stub` directive that allows you to exclude files from the bundle.
* Added per environment external encoding (Environment#default_external_encoding). Defaults to UTF-8. Fixes issues where LANG is not set correctly and Rubys default external is set to ASCII.
**2.1.2** (November 20, 2011)
-* Disabled If-Modified-Since server checks. Fixes some browser caching issues when serving the asset body only. If-None-Match caching is sufficent.
+* Disabled If-Modified-Since server checks. Fixes some browser caching issues when serving the asset body only. If-None-Match caching is sufficient.
**2.1.1** (November 18, 2011)
* Fix windows absolute path check bug.
@@ -526,11 +553,11 @@
* Initial public release.
# License #
-Copyright © 2011 Sam Stephenson <<sstephenson@gmail.com>>
+Copyright © 2014 Sam Stephenson <<sstephenson@gmail.com>>
-Copyright © 2011 Joshua Peek <<josh@joshpeek.com>>
+Copyright © 2014 Joshua Peek <<josh@joshpeek.com>>
Sprockets is distributed under an MIT-style license. See LICENSE for
details.