Ant Plugin

General Information

The plugin is an Ant task that integrates automatic open source management with Apache Ant.

Once it is set up, all usage of open source software in the organization will be continuously and automatically synchronized with White Source:

  • New projects will be created
  • Existing projects will be updated
  • Policies will be enforced on every action, failing the build if necessary

The plugin is licensed under the Apache 2.0 license.

Source code and issues are hosted on Github.

How it Works

On execution, the plugin will determine which open source is currently used by your project and send it to WhiteSource.

Normal Flow

WhiteSource uses the collected information to create new projects or update existing ones.

Policy Check Flow

The plugin will check each new library with the organizational policies. If any library should be automatically rejected by some policy, then the build will fail. Otherwise, your account will be updated.

An informative report of the results will be generated regardless of the outcome.

Installation

Prerequisites

  • Ant 1.7.1 or higher
  • Java (see table below for required version)

Download

Download the latest version and insert it in your ${ANT_HOME}/lib directory

Setup

  •  Define a new task named 'whitesource':
  • Add a new target with White Source container declaration:
  •  Edit your ANT project build.xml

  •  Set an ANT property for the URL that you would like to use

  • Pass the property name to your 'whitesource' ant plugin as shown below.
  • Save the file.

Configuration

The task configuration is flexible and can be customized to match your project structure.

General Parameters

AttributeTypeDescriptionRequired
apikeyStringUnique identifier of the organization to update. It can be retrieved from the admin page in your WhiteSource accountYes
productStringName or unique identifier of the product to update.
productversionStringVersion of the product to update.
failonerrorBooleanWhether or not to stop the build when encountering an errorNo. Defaults to true
forceUpdateBooleanWhether or not to update inventory when encountering policy violation.No. Defaults to false

Check Policies

You can initiate a policies check during the update with a nested element<checkpolicies>.

AttributeTypeDescriptionRequired
reportdirFileOutput directory for generated report file (a folder named 'whitesource' will be created at this location)No. Default is project.baseDir/reports
failonrejectionBooleanWhether or not to fail the build if policy rejects a libraryNo. Defaults to true

Modules

Project module in your work space to be updated or created with nested <module> elements.

AttributeTypeDescriptionRequired
nameString

Module name to be matched with an existing WhiteSource project name. If a project with this name does not exist, then a new project will be created.

One of these attributes

tokenStringModule token to match an existing WhiteSource project can be retrieved from the admin page in your WhiteSource account

Each module must be declared with nested <path> elements that stores the location of the module's lib folder (with all the dependencies).

More information on working with nested <path> elements can be found here.

Example

This example shows how to configure a Multi-module project structure with two modules. The first is matched by name and the second by a project token.


Executing the Plugin

To execute the task directly, simply run 'ant whitesource' in your shell.

You can setup Ant to execute the task as part of a build by binding it to a target.

Build Log

The plugin is executed during the build process. Sample log section: