gradle-compass

gradle-compass copied to clipboard

= 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"]

image::https://api.bintray.com/packages/robfletcher/gradle-plugins/compass-gradle-plugin/images/download.svg[link="https://bintray.com/robfletcher/gradle-plugins/compass-gradle-plugin/_latestVersion"]

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

[code, lang=groovy]

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:

[code, lang=groovy]

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:

[code, lang=groovy]

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

[code, lang=groovy]

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 http://www.gradle.org/docs/current/userguide/application_plugin.html[Application plugin]'s run task you would configure your build with:

[code, lang=groovy]

run.dependsOn compassWatchStart run.finalizedBy compassWatchStop

=== Advanced Gem Install Options

You can specify additional options to gem install:

[code, lang=groovy]

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 https://github.com/johnrengelman/gradle-processes[Process plugin].

=== 2.0

• JRuby is handled by the 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.

=== 1.0.4

• added ability to specify file encoding used by JRuby.