Apr 25, 2014

Abstract

You won’t have to change the original sources. You won’t even have to download them manually.

I’ll also show how you can inspect the LESS sources in your browser (in stead of the generated CSS) and how to get productive
with automatic compilation.

Quick start

If you already have gradle:

There’s only one file to download: build.gradle :)
Save it in the directory less-bootstrap and then:

cd less-bootstrap
gradle init
gradle lesscDaemon --info

You don’t have Gradle yet:

Clone the github project with git clone https://github.com/houbie/less-bootstrap
or download and unpack the zip distribution
and use the included gradle wrapper:

cd less-bootstrap
gradlew init
gradlew lesscDaemon --info

Now you can:

open less-bootstrap/web/bootstrap-examples/theme/index.html (or an other example)

change less-bootstrap/web/less/custom-variables.less

reload the page to see the changes

Tip

Before reloading the page in your browser, you’ll have to wait a few seconds until the style sheets are compiled.
If you don’t like waiting (who does?), see Speeding up compilation

Exploring the examples

The examples are located in less-bootstrap/web/bootstrap-examples. When you open f.e. less-bootstrap/web/bootstrap-examples/theme/index.html
and inspect the Learn more button in Google Chrome, you will see something like this:

Figure 1. Inspecting an element in Chrome

The inspector shows the LESS sources because the the lessc task is configured to generate source maps:

Enabling source maps in build.gradle

lessc {
...
//generate source maps so that Google Chrome shows the less source in the inspector i.s.o. the raw CSS
options.sourceMap = true//the generated css file contains a reference to the source map, this reference will be relative to//the sourceMapBasepath in this case it will be in the same directory as the css itself//(default location of source maps)
options.sourceMapBasepath = file("$webDir/css").absolutePath
//we could try to specify the sourceMapxxx options so that the browser can load the LESS sources//directly, but this is not trivial since our sources reside in different locations//therefore we just copy all the less source code into the source map file
options.sourceMapLessInline = true
}

Note

At the moment of writing, Chrome is the only browser that supports source maps for CSS files.
This blog shows how to enable CSS source maps
if they are not enabled by default.

Customizing the style sheet

Where is the code?

We would like to change the background color of the Learn more button, but how do we locate its definition?

Again, by inspecting the element in Chrome, we see that the background color is defined in buttons.less.

Figure 2. The button’s background colour

When we double-click buttons.less, the source is opened in the inspector:

Figure 3. Buttons.less

We see that the variable that we need to change is btn-primary-bg. Unfortunately, we cannot navigate further anymore
in the inspector, so we have to search manually.

The bootstrap source files can be found in less-bootstrap/build/bootstrap/web-app/less. A text search leads us to mixins.less
for the button-variant definition and to variables.less for the background color variable:

@btn-primary-bg: @brand-primary;

Albeit not perfect, it is a lot easier to find the code in this way than if we would only see the raw CSS in the inspector.

At this point we have to decide whether we want to change only the color of the primary buttons, or if we want to change
the primary brand color.

Modifying styles

There are 3 ways to modify the style sheets:

Overwrite variables in build.gradle

Modify a copy of the original source

Create our own customization LESS file

Overwriting variables in build.gradle

The lesscss compiler allows us to declare new or overwrite existing variables via the commandline or in build.gradle:

lessc {
...
options.modifyVars = ['brand-primary': 'purple']
}

Overwriting variables this way can be useful if you want f.e. to use a different color scheme for development builds than for release builds, but
it is not suitable for more involved customizations.

Modify a copy of the original source

The lessc task is configured to lookup LESS files first in less-bootstrap/web/less:

This means that if we would copy variables.less to less-bootstrap/web/less and modify it, it will take precedence over
the original file.

However, when we would like to upgrade to a newer bootstrap version, we would need to apply all our changes again in the
new file, which is far from ideal.

Note

Changing brand-primary in our copy of variables.less won’t have any effect, it will always be overridden by
the value in build.gradle!

Create our own customization LESS file

The main LESS file, bootstrap.less, consists of only import statements. If we would append a few import statements to
include our own customization files, we wouldn’t have to change the original LESS code. This is exactly what the init
task does when it unpacks the bootstrap sources:

Use the fast node.js compiler in the lesscDaemon task to save time when developing the style sheets. Keep the default
(java rhino based) compiler in the lessc task to avoid installing node.js on your CI server and to have deterministic
builds that always use the same compiler version.

Setup

I recently released a new version of lesscss that supports 3 execution engines:

rhino 1.7R4: it runs a pre-compiled version of less.js in the highest optimization level (9)

nashorn: the JDK8 built-in version, which does not (yet) support pre-compilation nor optimization

node.js lessc: prepare a commandline string and execute it with Runtime.exec

I compiled the Twitter Bootstrap style sheets using different engines.
I used my mac book (2.66GHz core i7 with 8GB memory and JVM args -Xms512m -Xmx1500m -XX:MaxPermSize=320m).
For each run I instantiated one engine for 15 consecutive compilations.

As you can see, both rhino and nashorn perform better when the JVM warmed up, but the differences in performance are huge:

Time needed to compile Twitter Bootstrap (seconds)
The first row includes JavaScript compilation in case of Nashorn

#

Rhino
(optimized)

Nashorn

node.js

1

3.9

18.4

0.9

2

1.9

7.9

0.6

3

1.7

6.1

0.6

4

1.6

5.8

0.6

5

1.4

5.0

0.6

6

1.4

4.9

0.6

7

1.5

4.5

0.6

8

1.4

5.3

0.6

9

1.3

5.8

0.6

10

1.3

4.4

0.6

11

1.0

4.0

0.6

12

1.0

3.8

0.6

13

1.0

3.5

0.6

14

0.9

3.1

0.6

15

0.9

2.8

0.6

Conclusions

Although this is not a real benchmark,
the figures differed less then 20% between runs and the trends are clear (at least for this use case):

Dec 2, 2013

Yennick Trevels wrote a great
blog on how to set up a Gradle build to deploy to the Sonatype OSS Repository (and from there to maven central).
Here I will show how the Gradle release plugin can be configured to

streamline the release process

automatically provide download links to you latest release on Github

The standard release process

The principles of the Gradle release plugin originate from the Maven release plugin. The release steps are:

Configuration

The release plugin is not fully documented, but fortunately it is small and the code speaks for itself (its Gradle :)
In
ReleasePluginConvention.groovy
you find all the properties that can be specified.
I changed the default versionPropertyFile (gradle.properties) to
versions.txt, to make it obvious to find the project version.
You can also see how to use complex version schemes.

//the release plugin expects the content to be 'version=xyz',
//without whitespace around the =
version = file('version.txt').text.split('=')[1].trim()

Build hooks

One of the most powerful features of Gradle is the ability to hook custom tasks about anywhere in the build cycle.
gradle tasks --all shows all the steps in the release task that we can hook into:

checkCommitNeeded - Checks to see if there are any added, modified, removed, or un-versioned files.
checkSnapshotDependencies - Checks to see if your project has any SNAPSHOT dependencies.
checkUpdateNeeded - Checks to see if there are any incoming or outgoing changes that haven't been
applied locally.
commitNewVersion - Commits the version update to your SCM
confirmReleaseVersion - Prompts user for this release version. Allows for alpha or pre releases.
createReleaseTag - Creates a tag in SCM for the current (un-snapshotted) version. [uploadArchives]
initScmPlugin - Initializes the SCM plugin (based on hidden directories in your project's
directory)
preTagCommit - Commits any changes made by the Release plugin - eg. If the unSnapshotVersion tas
was executed
release - Verify project, release, and update version to next. [clean]
unSnapshotVersion - Removes "-SNAPSHOT" from your project's current version.
updateVersion - Prompts user for the next version. Does it's best to supply a smart default.

Hooking in is straightforward:

//always clean before building a release
release.dependsOn clean
//upload to sonatype before tagging the VCS
createReleaseTag.dependsOn uploadArchives

We should only upload release builds to the sonatype staging repository, so we tweak the 'uploadArchives' a little bit:

Oct 22, 2013

Groovy is a superb language for automated tests: it is far more powerful than Java and it allows to skip lots of boilerplate code. The Spock framework adds a nice test specification DSL on top of that. In this post, you will find out more about my favorite Spock feature: data driven testing.

Write one test and get 40 for free

I build a Java port of the LESS CSS compiler, originally written in JavaScript.
The LESS compiler already has more than 40 test cases that compare a compiled LESS file with the expected CSS result. I only had to create one unit test that loops over all LESS files, compiles them and checks the result.

Notice how you can tell Spock that it has to create one test for each variable in a collection:

where:
variable << collection

Also notice the absence of assertEquals in the expect block: we only need to write boolean conditions. As programmers (and even non-programmers), we are trained to recognize these comparisons, so they are easier to read, understand and maintain then the classical assertXxx method calls.

Test isolation

We could also write a plain JUnit test that loops over the files to test them, but the problem would then be test isolation: if one test fails, the test method is aborted and we won't know the status of the remaining tests.
Spock, instead, runs an isolated test for each iteration. All failures are reported separately, but if all tests pass, you will see only one method in the test report.
In the above example, it would be even better to have one test method with a descriptive name for each LESS file. This is what Spock's Unroll annotation does:

@Unroll
def "#lessFile.name compatibility test"() {...}

By using #lessFile.name in the method name, we get clear test reports:

Data tables

Spock where blocks are not limited to one variable. If you want to populate more than one variable in each iteration, you can use the collection approach as shown above, or you can provide a table with values:

This example will run 3 tests: one for each data row.
Data tables are especially useful for testing the typical use cases and corner cases in one go.
Syntactically, a data table is a bunch of unrelated or statements, so it may look strange at first sight. But if well formatted, data tables look like tables, and that's how Spock interprets them.
Intellij IDEA users get an extra here: it knows about Spock data tables and can format them automatically.

Jun 17, 2013

I recently experimented with the upcoming Nashorn JavaScript run-time to compile Less style sheets.
I hoped to boost the performance in comparison with existing Less compilers for the JVM, but the results where not what I expected...

Motivation

Although I am a fan of Twitter Bootstrap and Less CSS in general, I found that the Less compilation in Java projects could take several seconds and thus be really bad for development turnaround.
During Devoxx 2012, Marcus Lagergren explained how much faster Nashorn was compared with Rhino (being already included in the standard Java distribution). So I took it for a test drive.

Can't wait for Java 8

I didn't have JDK8 installed yet, so I forked a backport on GitHub and build the nashorn.jar that provides a standard javax.script.ScriptEngine implementation.
This made it easy to support both Rhino and Nashorn: by specifying -Djava.ext.dirs=/path/to/nashorn, Nashorn was used by default with a fallback to Rhino.

The compiler

I didn't use the Rhino specific less script, but instead used the standard less-1.3.3.js. I only had to add a few lines of JavaScript in front, to stub a little browser functionality, and add a compile function at the back to be called from Java.
The Java code was rather simple:

The Bootstrap test

The Twitter Bootstrap style sheets compiled successfully with both Rhino and Nashorn
Compilation with Rhino took 10 seconds on my Macbook, while Nashorn did in in 8 seconds. Not exactly impressive...
To get an idea of the JavaScript compilation / execution ratio , I invoked the Less compile function multiple times, hereby reusing the JavaScript context.

Time needed to compile Twitter Bootstrap (seconds)
The first row includes JavaScript compilation

#

Rhino

Rhino
(optimized)

Nashorn
JDK7

Nashorn
JDK8

1

9.8

5.5

8.0

15.0

2

7.5

2.1

2.5

5.8

3

7.3

1.5

/

3.7

4

7.4

1.1

/

3.4

5

7.3

1.0

/

3.4

The first column is for Rhino invoked as described above using the javax.script interfaces. By default Rhino always runs in interpreted mode. Compare this with the second column, where the Rhino Context is used directly which allows to set the optimization level to 9 (highest level).
The third column is for Nashorn on Java 7. The Nashorn backport apparently contains some bugs, causing the third Less compilation within the same JavaScript context to fail.
The fourth column contains the results of the Less compilation using a JDK8 snapshot. The engine now works correctly, but the performance still needs to improve a lot.

Conclusions

I realize that the Nashorn project is still in alpha, but until the team comes up with an API that allows compiler optimizations like Rhino does, the latter still seems to be the best bet.