= Gradle Compass plugin
A http://sass-lang.com/[SASS] / http://compass-style.org/[Compass] plugin for http://gradle.org/[Gradle]. The plugin uses JRuby to install and run Compass.
image:https://travis-ci.org/robfletcher/gradle-compass.svg?branch=master["Build Status", link="https://travis-ci.org/robfletcher/gradle-compass"]
== Tasks
The plugin adds the following tasks:
=== compassCompile
Compiles all SASS files. Equivalent to the compass compile
command. The task supports incremental build.
=== compassWatch
Compiles and watches all SASS files. Equivalent to the compass watch
command.
=== compassVersion
Prints out the compass version.
=== compassConfig
Writes compass configuration out to config/compass.rb
.
== Installation
Add the plugin like this:
apply plugin: "com.github.robfletcher.compass"
== Configuration
General configuration for the plugin goes inside a compass
block in your build file and will apply to all tasks. You can also specify configuration properties on the individual tasks (for example you may want to set environment = "production"
on the compileSass and debugInfo = true
on watchSass). For example:
=== Configuration parameters
The full set of parameters supported by the plugin is…
==== Paths
cssDir
: the target directory where compiled CSS is output. Equivalent to --css-dir
. Defaults to build/stylesheets
.sassDir
: the source directory where you keep .scss and/or .sass files. Equivalent to --sass-dir
. Defaults to src/main/sass
.imagesDir
: the source directory where you keep image files. Equivalent to --images-dir
.javascriptsDir
: the source directory where you keep JavaScript files. You don't need to specify this unless you have Compass extensions in your scripts. Equivalent to --javascripts-dir
.fontsDir
: the source directory where you keep fonts. Equivalent to --fonts-dir
.importPath
: a set of directories containing other Sass stylesheets. Specifying this allows you to reference those stylesheets in @import
directives. Equivalent to --import-paths
.load
: loads a framework or extensions found in the specified directory. Equivalent to --load
.loadAll
: loads all frameworks or extensions found in the specified directory. Equivalent to --load-all
.==== Compilation options
sourcemap
: if true Compass will generate a sourcemap during compilation. Equivaluent to --sourcemap
.debugInfo
: if true (the default) Compass adds debug information to the compiled CSS. Equivalent to --debug-info
if set to true or --no-debug-info
if set to false.force
: if true Compass will overwrite existing files. Equivalent to --force
.environment
: sets default options when set to 'development' (the default) or 'production'. Equivalent to --environment
.noLineComments
: if true Compass will not output line comments to the compiled CSS files. Equivalent to --no-line-comments
.outputStyle
: selects the style for compiled CSS. One of nested, expanded, compact (the default) or compressed. Eqivalent to --output-style
.relativeAssets
: if true Compass will generate relative urls to assets. Equivalent to --relative-assets
.httpPath
: sets the path to the root of the web application when deployed. Equivalent to --http-path
.generatedImagesPath
: sets the path where generated images are stored. Equivalent to --generated-images-path
.==== Command line output
time
: if true Compass will print timing information during compilation. Equivaluent to --time
.boring
: if true colorized output is disabled. Equivalent to --boring
.quiet
: if true Compass output is suppressed. Equivalent to --quiet
.trace
: if true Compass displays full stack traces on error. Equivalent to --trace
.==== Dependency options
gemDir
: the directory where the Compass gem (and any other gems you specify) will be installed. Defaults to build/tmp/gems
. You may want to override this to use a shared location in multi-project builds so that gems only get downloaded once.=== Specifying the Compass version
By default the plugin will use the latest version of Compass available. If you need a specific version you can set the version using Gradle's dependency management. For example:
Gems are installed using the JRuby Gradle plugin. The Compass plugin creates a special "compass" configuration that is used by all the plugin's tasks.
=== Cleaning output
The Compass plugin creates a cleanCompassCompile
task automatically that will delete compiles CSS. The main clean
task will also delete CSS assuming cssDir
is inside the project's build
directory.
=== Using additional gems
You can use Compass extensions from Ruby gems by adding dependencies to the compass configuration. The plugin will automatically add a --require
argument for each gem when invoking Compass commands. For example to use the Breakpoint extension:
=== Automatically recompiling stylesheets while other tasks are running
A typical use-case is to run compassWatch
in the background while another task runs your web-server application. This is very easy with the Compass plugin.
Assuming you're using the http://www.gradle.org/docs/current/userguide/application_plugin.html[Application plugin]'s run
task you would configure your build with:
=== Advanced Gem Install Options
You can specify additional options to gem install
:
= Version history
=== 2.0.5
=== 2.0.5
compassClean
task – instead apply the base plugin so we get cleanup by convention.=== 2.0.4
=== 2.0.3
=== 2.0.2
compassWatch
using John Engleman's https://github.com/johnrengelman/gradle-processes[Process plugin].=== 2.0
=== 1.0.10
=== 1.0.9
=== 1.0.8
=== 1.0.7
javascriptsDir
, imagesDir
and importPath
optional.=== 1.0.6
importPath
.=== 1.0.5
=== 1.0.4
[app-plugin]: