spring-boot/spring-boot-cli/README.md

Spring Boot - CLI

Installing the CLI

You need Java SDK v1.6 or higher to run the command line tool (there are even some issues with the 1.7.0_25 build of openjdk, so stick to earlier builds or use 1.6 for preference). You should check your current Java installation before you begin:

$ java -version

Manual installation

You can download the Spring CLI distribution from the Spring software repository:

• spring-boot-cli-1.0.0.RC1-bin.zip
• spring-boot-cli-1.0.0.RC1-bin.tar.gz

Cutting edge snapshot distributions are also available.

Once downloaded, follow the INSTALL instructions from the unpacked archive. In summary: there is a spring script (spring.bat for Windows) in a bin/ directory in the .zip file, or alternatively you can use java -jar with the .jar file (the script helps you to be sure that the classpath is set correctly).

Installation with GVM

GVM (the Groovy Environment Manager) can be used for managing multiple versions of verious Groovy and Java binary packages, including Groovy itself and the Spring Boot CLI. Get gvm from the gvm home page and install Spring Boot with

$ gvm install springboot
$ spring --version
Spring Boot v1.0.0.RC1

Note: If you are developing features for the CLI and want easy access to the version you just built, follow these extra instructions.

$ gvm install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-1.0.0.BUILD-SNAPSHOT-bin/spring-1.0.0.BUILD-SNAPSHOT/
$ gvm use springboot dev
$ spring --version
Spring CLI v1.0.0.BUILD-SNAPSHOT

This will install a local instance of spring called the dev instance inside your gvm repository. It points at your target build location, so every time you rebuild Spring Boot, spring will be up-to-date.

You can see it by doing this:

$ gvm ls springboot

================================================================================
Available Springboot Versions
================================================================================
 > + dev
   * 1.0.0.RC1

================================================================================
+ - local version
* - installed
> - currently in use
================================================================================

OSX Homebrew installation

If you are on a Mac and using homebrew, all you need to do to install the Spring Boot CLI is:

$ brew install http://repo.spring.io/install/spring-boot-cli.rb

Homebrew will install spring to /usr/local/bin. Now you can jump right to a quick start example.

Note: If you don't see the formula, you're installation of brew might be out-of-date. Just execute brew update and try again.

Quick start script example

Here's a really simple web application. Create a file called app.groovy:

@RestController
class ThisWillActuallyRun {

	@RequestMapping("/")
	String home() {
		return "Hello World!"
	}

}

Then run it from a shell:

$ spring run app.groovy

Note: It will take some time when you first run the application as dependencies are downloaded, subsequent runs will be much quicker.

Open http://localhost:8080 in your favorite web browser and you should see the following output:

Hello World!

Testing Your Code

The Spring Boot CLI has a test command. Example usage:

$ spring test app.groovy tests.groovy
Total: 1, Success: 1, : Failures: 0
Passed? true

Where tests.groovy contains JUnit @Test methods or Spock Specification classes. All the common framework annotations and static methods should be available to you without having to import them. Example with JUnit (for the above application):

class ApplicationTests {
    @Test
    void homeSaysHello() {
        assertEquals("Hello World", new ThisWillActuallyRun().home())
    }
}

You can add more tests by adding additional files, or you might prefer to put them in a special directory.

Applications with Multiple Source Files

You can use shell globbing to pick up multiple files in a single directory, e.g.

$ spring run *.groovy

and this enables you to easily segregate your test or spec code from the main application code, if that's what you prefer, e.g.

$ spring test app/*.groovy test/*.groovy

Beans DSL

Spring has native support for a beans{} DSL (borrowed from Grails), and you can embedd bean definitions in your Groovy application scripts using the same format. This is sometimes a good way to include external features like middleware declarations. E.g.

@Configuration
class Application implements CommandLineRunner {

  @Autowired
  SharedService service

  @Override
  void run(String... args) {
    println service.message
  }

}

import my.company.SharedService

beans {
    service(SharedService) {
        message "Hello World"
    }
}

You can mix class declarations with beans{} in the same file as long as they stay at the top level, or you can put the beans DSL in a separate file if you prefer.

Commandline Completion

Spring Boot CLI ships with a script that provides command completion in a standard bash-like shell. You can source the script (also named spring) in any shell, or put it in your personal or system-wide bash completion initialization. On a Debian system the system-wide scripts are in /etc/bash_completion.d and all scripts in that directory are executed in a new shell. To run the script manually, e.g. if you have installed using GVM

$ . ~/.gvm/springboot/current/bash_completion.d/spring
$ spring <HIT TAB HERE>
clean    -d       debug    help     run      test     version

Packaging Your Application

You can use the jar command to package your application into a self-contained executable jar file. For example:

$ spring jar my-app.jar *.groovy

The resulting jar will containe the classes produced by compiling the application and all of the application's dependencies such that it can then be run using java -jar. The jar file will also contain entries from the application's classpath. See the output of spring help jar for more information.