Please use the Scar discussion group for support.
Scar is a collection of utilities that make it easier to do build related tasks using Java code. Building with Java code makes sense for Java developers. Rather than a complicated tool that caters to all needs, Scar is a simple tool that allows you to get what you need done in a simple, straightforward manner. Familiar tools and libraries can be used. Builds can be debugged like any other Java program. There is no new language to learn or XML attributes to look up.
Scar has the following key components:
- The
Scar
class has static utility methods for various tasks such as zip, unzip, jar, compile, etc. - The
Paths
class conveniently collects file paths using globs (asterisks) or regex. - The
Project
class is a generic project descriptor. It holds strings, numbers, paths, and other data about a project. - The
Build
class takes a Project and uses the Scar class to compile sources and package a JAR.
There are generally two ways of using Scar:
Create a new class and add a main method. Import the Scar
and Paths
classes, and use them to do whatever tasks you need: glob paths, zip files, etc.
Use the Build
class to do common build tasks on a project descriptor. The project descriptor is simply a map with convenience methods to get values (eg, as a list of file paths) and to do token replacement. The Build
class looks in the project for specific values (source paths, dependency JARs, etc) and then compiles Java source and creates a JAR. For example, this builds a JAR from a project directory using the default project values:
Project project = Build.project("path to project dir");
Build.build(project);
Running Scar on a directory runs Build.main which does the above two lines of code.
scar /path_to_project_dir/
If the directory contains a "project.yaml" file, it is used to customize the project values. When writing code to build a project instead of the command line, the project values can be customized in code.
The Project
class is a project descriptor. It consists of a path to the root directory of the project and a HashMap holding some data. The Project
class itself is a generic data structure and doesn't know anything about how the data will be used. The requirements for what should be specified in the project are determined by the tasks that need to be performed.
Projects can be defined entirely in Java:
Project project = new Project();
project.set("name", "AwesomeLib");
ArrayList sourceDirs = new ArrayList();
sourceDirs.add("src");
sourceDirs.add("other");
project.set("source", sourceDirs);
Projects can also be loaded from a YAML file on disk. YAML is a human readable format that makes it easy to specify the project object graph. Scar uses the YamlBeans library to parse YAML.
name: AwesomeLib
source:
- src
- other
Project project = new Project("project.yaml");
Separate from the object graph, a project can also store a "document" string. What is done with this string is left up to the code that is actually performing the tasks. The document can be set in Java with the Project#setDocument(String)
method or in YAML by using the document separator "---":
name: AwesomeLib
source:
- src
- other
---
System.out.println("The document data can be any text, ");
System.out.println("but is a convenient place to put code.");
Scar uses the Wildcard library to collect and manipulate files. For many tasks, the majority of the work is collecting the files to act upon, and Wildcard makes this easy. See the Wildcard documentation for how to construct paths.
Paths used in project YAML files can be either a single entry or a list. They should use the pipe delimited patterns format. Some YAML examples are provided below.
The Build
class has static methods that take a Project
and perform various tasks, such as compile and JAR. The Scar
class actually performs most tasks, the Build
class just defines how to project descriptors are interpreted. Note that using the Project
and Build
classes are optional. Your own customized build system could be implemented using only the Scar
and Paths
classes.
The Build
class has the following conventions for the data in the project descriptor:
**Property** | **Description** |
name | The name of the project. Used to name the JAR. Default: The name of the directory containing the project YAML file. |
target | The directory to output build artifacts. Default: The directory containing the project YAML file, plus "../target/`name`". |
version | The version of the project. If available, used to name the JAR. Default: *blank* |
resources | Wildcard patterns for the files to include in the JAR. Default: `resources`, `src/main/resources`, and 'assets'. |
dist | Wildcard patterns for the files to include in the distribution, outside the JAR. Default: `dist`. |
source | Wildcard patterns for the Java files to compile. Default: `src|**/*.java` and `src/main/java|**/*.java`. |
classpath | Wildcard patterns for the files to include on the classpath. Default: `lib|**/*.jar` and `libs|**/*.jar`. |
dependencies | Relative or absolute paths to dependency project directories or YAML files. Default: *blank* |
include | Relative or absolute paths to project files to inherit properties from. Default: *blank* |
main | Name of the main class. Default: *blank* |
If any of these are defined in the project.yaml file, those values are used instead of the defaults.
When the Scar JAR is run from the command line, it creates a project for the current directory and calls Build.build(project)
. This calls the buildDependencies
, clean
, compile
, jar
, and dist
utility methods on the Build
class. These methods respectively build all dependency projects (recursively), clean the output directory, compile sources to class files, JAR class files and resources, and place all distribution files and JARs needed to run the application in an output directory. If a main class was defined, the resulting JAR will have a manifest that allows it to be executed.
The project descriptor describes the project's files, and this is often a sufficient to completely build a Java project. If no project.yaml file is found, the defaults are used. If the defaults match your project, you don't even need a project.yaml file. However, it is often convenient to have one at least to specify a main class:
main: com.example.MainClass
When the Scar JAR is run, if a project has a document string (text included after the YAML), the string is compiled as Java code and executed instead of calling Build.build(project)
. The code will be executed with a static import for Scar
and the project instance is available through a variable named project
. See Scar.executeCode()
for more details about how the code is compiled and run.
Here is an example project descriptor that does the default build and then signs the JARs for use with Java WebStart:
source: tools|**.java
resources:
- images
- fonts|!arial.ttf
main: com.example.MainClass
---
Build.build(project);
keystore("keystore", "alias", "password", "Company", "Title");
Build.jws(project, false, "keystore", "alias", "password");
The static methods on the Scar
class, along with the Paths
class, are really what makes building using Java code manageable. Some of the methods are listed below. Please refer to the javadocs for exactly how to use each method.
- compile: Compiles Java source to class files.
- jar: Puts files in a JAR file, optionally generating a manifest to make the JAR executable.
- oneJar: Unzips multiple JARs and repackages them into a single JAR.
- keystore: Generatesa keystore for signing JARs.
- sign/unsign: Cryptographically signs JAR files.
- pack200/unpack200: Encodes JAR files with pack200.
- gzip/ungzip: Encodes files with GZIP.
- zip/unzip: Encodes files with ZIP.
- lzma/unlzma: Encodes files with LZMA.
- shell: Executes shell commands.
- copyFile/moveFile/delete/mkdir: Manipulate files.
- executeCode: Compiles and executes a string as if it were a Java method body.
- ftpUpload: Uploads files via FTP.
- jws: Prepares JARs to be deployed with Java WebStart. Removes any previous signing, does pack200 and unpack200 to normalize the JAR, signs it with a keystore, does pack200, and then GZIP.
- jnlp: Generates a JNLP file referencing all the JARs for Java WebStart.
- jwsHtaccess: Generates .htaccess and VAR "type map" files that allow Apache to serve both pack200/GZIP JARs and regular JARs, based on capability of the client requesting the JAR.
- lwjglApplet: Prepares JARs to be deployed as an LWJGL applet. Removes any previous signing, does pack200 and unpack200 to normalize the JAR, signs it with your keystore, does pack200, and then LZMA.
- lwjglAppletHtml: Generates an HTML file referencing all the JARs for an applet.
Scar.jwsHtaccess(project) generates ".htaccess" and "type map" VAR files in the jws
directory. These files allow Apache to serve both pack200/gzipped JARs and regular JARs, based on capability of the client requesting the JAR. More information.
Scar uses the MinLog library for logging. Little is logged at the INFO
level, which is the default. The DEBUG
and TRACE
levels can be enabled for increasingly more information:
Log.DEBUG();
Log.TRACE();
Besides logging, since Scar is simply Java code, a build can be run through a debugger to quickly figure out problems.
Wildcard properties can be specified as a single item:
source: src|**/*.java
resources: resources
classpath: lib|**/*.jar
dist: dist
Or as a list:
source:
- src|**/*.java
- tools|**/*.java
resources:
- resources/main|!**/test/**
- resources/images|*.png|*.jpg
classpath: lib|**/*.jar
dist: dist
A more complex example that uses all the properties:
include: ../common.yaml
version: 1.2-alpha3
source:
- src/main|**/*.java|!**Test.java
- src/tools|**/*.java
resources:
- resources/main|!**/test/**
- resources/images|*.png|*.jpg
classpath:
- lib|**/*.jar
- some/class/dir|**/*.class
dist: dist
dependencies:
- ../common-tools
- ../supporting-lib/special.yaml
- /some/absolute/project/path
main: com.example.SomeClass
target: build
---
classpath build/tools.jar;
import java.io.File;
DEBUG();
Build.compile(project);
Build.jar(project);
Build.dist(project);
keystore("keystore", "alias", "password", "Company", "Title");
Build.jws(project, true, "keystore", "alias", "password");
Build.jwsHtaccess(project);
Build.jnlp(project, "http://example.com/run.jnlp", "Company", "Title", "splash.png");