Gradle Compass plugin
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" buildscript { repositories { jcenter() maven { url "http://dl.bintray.com/robfletcher/gradle-plugins" } } dependencies { classpath "com.github.robfletcher:compass-gradle-plugin:2.0.5" } }
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:
compass { cssDir = file("public/styles") sassDir = file("src/main/sass") }
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 tobuild/stylesheets
. -
sassDir
: the source directory where you keep .scss and/or .sass files. Equivalent to--sass-dir
. Defaults tosrc/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 tobuild/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:
dependencies { compass "rubygems:compass:1.0.1" }
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][breakpoint] extension:
dependencies { compass "rubygems:breakpoint:2.5.0" }
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 Application plugin's run
task you would configure your build with:
run.dependsOn compassWatchStart run.finalizedBy compassWatchStop
Advanced Gem Install Options
You can specify additional options to gem install
:
compass { gems = [ [ name: "compass", version: "0.12.7", ], [ name: "compass-css-arrow", version: "0.0.4", opts: ["--ignore-dependencies"], ], ] }
Version history
2.0.5
-
Fixes JDK version compatibility so plugin can be used with Java 1.7.
2.0.5
-
No custom
compassClean
task – instead apply the base plugin so we get cleanup by convention.
2.0.4
-
Allow setting of directory where compass gems get installed (mainly this helps the integration tests run in a sane amount of time but it’s also useful for multi-project builds).
2.0.3
-
Fixes problem with POM configuration that meant transitive dependencies didn’t work.
2.0.2
-
Implements
compassWatch
using John Engleman’s Process plugin.
2.0
-
JRuby is handled by the [JRuby Gradle plugin](https://github.com/jruby-gradle/jruby-gradle-plugin).
1.0.10
-
added ability to specify gem versions.
1.0.9
-
use additional gems without needing a config.rb file.
1.0.8
-
added ability to specify additional gems.
1.0.7
-
made
javascriptsDir
,imagesDir
andimportPath
optional.
1.0.6
-
added ability to specify
importPath
.
1.0.5
-
added various command line options. Thanks [Ben Groves](http://github.com/bgroves).
1.0.4
-
added ability to specify file encoding used by JRuby.
[app-plugin]: [compass]:http://compass-style.org/ [gradle]:http://gradle.org/ [sass]:http://sass-lang.com/ [breakpoint]:http://breakpoint-sass.com/