ysb33r/gradle-compass

A SASS / Compass plugin for Gradle

Fork of robfletcher/gradle-compass

Gradle Compass plugin

A SASS / Compass plugin for Gradle. The plugin uses JRuby to install and run 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"

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 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:

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 and importPath 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/