Skip to content

Extensions

Jump to bottom
Geert Bevin edited this page Aug 30, 2024 · 16 revisions

bld project files are written in Java and are automatically compiled before executing the commands. Like any Java application, your project file can only use classes that are present on the classpath. The standard Java JDK, RIFE2/core and bld classes are always available to your build and are already very powerful, but you often need custom features in order to perform more specialized build tasks.

This is where bld extensions come into play.

What are bld extensions?

There is no plugin API nor plugin architecture for bld. Extensions are merely classes that will be available to your build sources, so that you can write build code that depends on other libraries. Just like the other classpath entries that are used to compile your main application, the classpath of your build sources is automatically created from the jar files that are present in the lib/bld directory of your project.

You could manually place libraries in that directory, but just like for your project dependencies, it might be inconvenient to track down and download everything by hand.

The bld-wrapper.properties file

The requirement to compile your build file, presents a chicken-and-egg situation if you would also specify the extension dependencies there. Therefore, you instead add properties the lib/bld/bld-wrapper.properties to indicate extension dependencies and repositories.

For example:

bld.downloadExtensionSources=true
bld.downloadExtensionJavadoc=false
bld.extensions=com.uwyn.rife2:bld-antlr4:1.4.0
bld.repositories=MAVEN_CENTRAL,RIFE2_RELEASES
bld.downloadLocation=
bld.version=2.1.0

Let's go over the properties:

Versioning

The bld.version is critical, it tells bld which version to use. That version will be automatically downloaded from Maven central but by specifying a bld.downloadLocation property you can provide a path where the jar file will be downloaded from instead. You should never have to change this, it's mainly used to test pre-release artifacts amongst all the RIFE2 projects.

Extension dependencies

Any property starting with bld.extension, can contain a comma-seperated list of extensions in the common dependency description format groupId:arfifactId:version.

Extension repositories

The property bld.repositories contains a comma separated list of Maven repositories. You have three ways to specify a repository:

  • Use one of standard repositories are available as shortcuts: APACHE, GOOGLE, MAVEN_CENTRAL, MAVEN_LOCAL, RIFE2_RELEASES, RIFE2_SNAPSHOT, SECURECHAIN_REBUILT, SECURECHAIN_VETTED, SONATYPE_RELEASES, SONATYPE_RELEASES_LEGACY, SONATYPE_SNAPSHOTS and SONATYPE_SNAPSHOTS_LEGACY.
  • Type in the complete location, for instance: https://repo1.maven.org/maven2/
  • Use a repository name that will be resolved through the hierarchical properties

To resolve a repository name through the properties, bld looks for three property name patterns. For instance, consider the repository name rife2 will work with the following properties:

bld.repo.rife2=https://repo.rife2.com/releases
bld.repo.rife2.username=youruser
bld.repo.rife2.password=yourpass

Extension artifacts

The final two properties bld.downloadExtensionSources and bld.downloadExtensionJavadoc respectively also download the sources and the javadoc artifacts of the specified dependencies.

Finding extensions

A growing collection of bld extensions are available through the RIFE2 Maven repository at https://repo.rife2.com. These are specifically designed to provide bld operations that work in a similar way as the standard bld operations. Please refer to the extension documentation for usage instructions.

TIP: don't forget that extensions are simply Java classes! You can specify any Maven dependency as an extension and use it to implement your own custom commands or operations.

Our current official extensions are:

Next learn more about CI Integration

Clone this wiki locally