Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/robfletcher/gradle-compass

A SASS / Compass plugin for Gradle
https://github.com/robfletcher/gradle-compass

Last synced: about 1 month ago
JSON representation

A SASS / Compass plugin for Gradle

Awesome Lists containing this project

README 

        
= 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][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](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/