Bnd has a simple macro processor for the header processing. Variables allow a single definition of a value, and the use of derivations. Each header is a macro that can be expanded. Notice that headers that do not start with an upper case character will not be copied to the manifest, so they can be used as working variables. Variables are expanded by enclosing the name of the variable in ${<name>} (curly braces) or $(<name>) (parenthesis). Additionally, square brackets [], angled brackets <>, double guillemets «», and single guillemets ‹› are also allowed for brackets. If brackets are nested, that is $[replace;acaca;a(.*)a;[$1]] will return [cac].

There are also a number of macros that perform basic functions. All these functions have the following basic syntax:

 macro ::= '${' function '}' 
     | '$\[' function '\]'
     | '$(' function ')'
     | '$<' function '>'

 function ::= name ( ';' argument ) *

For example:

version=1.23.87.200109111023542
Bundle-Version= ${version}
Bundle-Description= This bundle has version ${version}

All macros are listed in the index at the bottom of this page.

Macro patterns

The default macro pattern is the ${...} pattern, a dollar sign (‘$’) followed by a left curly bracket (‘{‘) and closed by a right curly bracket (‘}’). However, since bndlib is often used inside other systems it also supports alternative macro patterns:

  • $(...),
  • $<...>,
  • $[...],
  • $«..» (pointing double angle quotation mark \u00AB abd \u00BB), and
  • $‹...› (single pointing angle quotation mark)

Arguments

@Since(“2.3”) Macros can contain arguments. These arguments are available in the expansion as ${0} to ${9}. ${0} is the name of the macro, so the actual arguments start at 1. The name is also available as ${@}. The arguments as an array (without the name of the macro) is available as ${#}. The more traditional * could not be used because it clashes with wildcard keys, it means ALL values.

For example:

foo: Hello ${1} -> ${foo;Peter} -> "Hello Peter"

Wildcarded Keys

Keys can be wildcarded. For example, if you want to set -plugin from different places, then you can set the plugin.xxx properties in different places and combine them with -plugins= ${plugins.*}.

Expansion of ./

The ./ sequence is automatically expanded to the current filename when found in a macro source file. This generally what you want but unfortunately not always. The ./ prefix is only replaced when:

  • It is at the start of the expansion, or
  • Preceded by a whitespace.

So, do you really require the ./ without expansion? If so, then there are the following solutions. The first one is to use another macro to break the sequence:

.=.
Some-Header: ${.}/conf/admin.xml

Alternatively there are a couple of macros that return the given value when called appropriately, and thereby break the sequence:

Some-Header-1: ${def;.;.}/conf/jetty/admin.xml
Some-Header-2: ${uniq;.}/conf/jetty/admin.xml
Some-Header-3: ${unescape;.}/conf/jetty/admin.xml

Booleans

In many places a header is used to indicate false or true. In those cases we use some heuristics. The header/macro or whatever is false when:

  • not set
  • empty string
  • ‘false’
  • ’!’
  • ‘off’
  • ‘not’

If the value starts with ! and text follows, the ! is removed and the remaining text is interpreted as a boolean and then negated.

In other cases, the value is considered true.

Macro Index

page Description Class
apply ';' MACRO (';' LIST)* Convert a list to an invocation with arguments Macro
average (';' LIST )* Calculate the arithmetic mean (average) of numeric values in one or more lists Macro
base64 ';' FILE [';' LONG ] Encode a file's contents as Base64 text Macro
basedir Get the base directory of the current processor context Processor
basename ( ';' FILEPATH ) + Extract the filename from one or more file paths Macro
basenameext ';' PATH ( ';' EXTENSION ) The basename of the given path optionally minus a specified extension Macro
bndversion Returns the current running bnd version as full major.minor.micro Macro
bsn Get the Bundle Symbolic Name (BSN) of the current bundle being built Analyzer
bytes ( ';' LONG )* Format byte a count into human-readable size unit Macro
cat ';' FILEPATH Read and return the contents of a file or URL Macro
classes ( ; QUERY ( ; PATTERN )? )* A list of class names filtered by a query language Analyzer
compare STRING STRING Compare two strings by using the compareTo method of the String class. Macro
currenttime Get the current system time as milliseconds since epoch Macro
decorated ';' NAME [ ';' BOOLEAN ] The merged and decorated Parameters object Macro
def ';' KEY (';' STRING)? Get a property value with an optional default Macro
digest ';' ALGORITHM ';' FILE Calculate a cryptographic digest (hash) of a file Macro
dir ( ';' FILE )* Extract the directory path from one or more file paths Macro
driver ( ';' NAME )? Get or check the build environment driver (gradle, eclipse, intellij, etc.) Workspace
ee Get the highest Java Execution Environment (EE) required by the bundle Analyzer
endswith ';' STRING ';' SUFFIX Check if a string ends with a specific suffix Macro
env ';' KEY (';' STRING)? Get an environment variable with an optional default Macro
error ( ';' STRING )* Generate a build error with a custom message Macro
exporters ';' PACKAGE List JARs on the classpath that export a given package Analyzer
exports Get the list of packages exported by the current bundle Analyzer
extension ';' PATH The file extension of the given path or empty string if no extension Macro
fileuri ';' PATH Return a file uri for the specified path. Relative paths are resolved against the domain processor base. Macro
filter ';' LIST ';' REGEX Filter a list to include only entries matching a regular expression Macro
filterout ';' LIST ';' REGEX Filter a list to exclude entries matching a regular expression Macro
find ';' VALUE ';' SEARCHED Find the index position of a substring in a string Macro
findfile ';' PATH ( ';' FILTER ) Get filtered list of file paths from a directory tree Project
findlast ';' VALUE ';' SEARCHED Find the last occurrence of a substring in a string Macro
findname ';' REGEX ( ';' REPLACEMENT )? Find bundle resources by filename with optional regex replacement Project
findpath ';' REGEX ( ';' REPLACE )? Find bundle resources by full path with optional regex replacement Project
findproviders ';' namespace ( ';' FILTER ( ';' STRATEGY)? )? find resources in the workspace repository matching the given namespace and optional filter. Intended for use in bndrun files. STRATEGY can one of ALL, REPOS or WORKSPACE. Workspace
first (';' LIST )* Get the first element from one or more lists Macro
fmodified ( ';' RESOURCE )+ Get the latest modification timestamp from a list of files Macro
foreach ';' MACRO (';' LIST)* Iterate over a list, calling a macro for each element with value and index Macro
format ';' STRING (';' ANY )* Print a formatted string using Locale.ROOT, automatically converting variables to the specified format if possible. Macro
frange ';' VERSION ( ';' BOOLEAN )? Generate an OSGi filter expression for a version range Analyzer
gestalt ';' NAME ( ';' NAME (';' ANY )? )? Access environment description properties (gestalt) Workspace
get ';' INDEX (';' LIST )* Get an element from a list at a specific index Macro
githead Get the Git commit SHA of the current HEAD Builder
glob ';' GLOBEXP Convert a glob pattern to a regular expression Macro
global ';' KEY ( ';' DEFAULT )? Access user settings from the ~/.bnd/settings.json file Workspace
ide ';' ( 'javac.target' | 'javac.source' ) Read Java compiler settings from Eclipse IDE configuration Project
if ';' STRING ';' STRING ( ';' STRING )? Conditional macro that depending on a condition returns either a value for true or optionally for false. Macro
imports Get the list of packages imported by the current bundle Analyzer
Macro Reference
indexof ';' STRING (';' LIST )* Find the index position of a value in one or more lists Macro
is ( ';' ANY )* Check if all given values are equal Macro
isdir ( ';' FILE )+ Check if all specified paths are directories Macro
isempty ( ';' STRING )* Check if all given strings are empty Macro
isfile (';' FILE )+ Check if all specified paths are regular files Macro
isnumber ( ';' STRING )* Check if all given strings are valid numbers Macro
join ( ';' LIST )+ Combine multiple lists into a single comma-separated list Macro
js (';' JAVASCRIPT )* Execute JavaScript expressions and return the result. Macro
last (';' LIST )* Get the last element from one or more lists Macro
lastindexof ';' STRING (';' LIST )* Find the last index position of a value in one or more lists Macro
length STRING Get the length of a string in characters Macro
list (';' KEY)* Returns a list of the values of the named properties with escaped semicolons. Macro
literal ';' STRING Prevent macro expansion by wrapping a value with macro delimiters Macro
long2date Convert a millisecond timestamp to a readable date string Macro
lsa ';' DIR (';' SELECTORS ) List files with absolute paths, optionally filtered Macro
lsr ';' DIR (';' SELECTORS ) List files with relative paths, optionally filtered Macro
map ';' MACRO (';' LIST)* Transform each element of a list using a macro function Macro
matches STRING REGEX Check if a string matches a regular expression pattern Macro
maven_version ';' MAVEN-VERSION Cleanup a potential maven version to make it match an OSGi Version syntax. Builder
max (';' LIST )* Find the maximum string in one or more lists Macro
md5 ';' RESOURCE Calculate MD5 digest of a resource in the bundle Analyzer
min (';' LIST )* Find the minimum string in one or more lists Macro
native_capability ( ';' ( 'os.name' | 'os.version' | 'os.processor' ) '=' STRING )* Generate OSGi native capability string for current or specified platform Processor
ncompare NUMBER NUMBER Compare two numbers by using the Double.compare method. Macro
nmax (';' LIST )* Find the maximum number in one or more lists Macro
nmin (';' LIST )* Find the minimum number in one or more lists Macro
now ( 'long' | DATEFORMAT ) Get current date and time in various formats Macro
nsort (';' LIST )+ Sort lists numerically by treating values as numbers Macro
osfile ';' DIR ';' NAME Create an OS-specific absolute file path Macro
p_allsourcepath Get paths to all source directories Project
p_bootclasspath Get the project's boot classpath Project
p_buildpath Get the project's buildpath as a list Project
p_dependson Get list of project names this project depends on Project
p_output Get the absolute path to the project's output directory Project
p_sourcepath Get the project's source directories Project
p_testpath Get the project's test runtime path Project
packageattribute ';' PACKAGE (';' ATTRIBUTE)? The value of a package attribute Analyzer
packages A list of package names filtered by a query language Analyzer
path ( ';' FILES )+ Join file paths with the OS path separator Macro
pathseparator Get the operating system's path separator character Macro
permissions (';' ( 'packages' | 'admin' | 'permissions' ) )+ Generate OSGi permission declarations for the bundle Builder
propertiesdir Get the directory containing the current properties file Processor
propertiesname Get the filename of the current properties file Project
rand (';' MIN ' (;' MAX )?)? Generate a random number within a specified range Macro
random Generate a random string that is a valid Java identifier Processor
range ';' RANGE_MASK ( ';' VERSION ) Create a semantic version range out of a version using a mask to control the bump of the ceiling Macro
reject ';' LIST ';' REGEX Rejects a list by matching it against a regular expression Macro
removeall ';' LIST ';' LIST Return the first list where items from the second list are removed Macro
replace ';' LIST ';' REGEX (';' STRING (';' STRING)? )? Replace parts of list elements using regex patterns Macro
replacelist ';' LIST ';' REGEX (';' STRING (';' STRING)? )? Replace parts of list elements using regex with quoted section support Macro
replacestring ';' STRING ';' REGEX (';' STRING )? Replace parts of a string using regex patterns Macro
repo ';' BSN ( ';' VERSION ( ';' STRATEGY )? )? Provides the file paths to artifact in the repositories Project
repodigests ( ';' NAME )* Get cryptographic digests of repository contents Workspace
repos Get a list of configured repository names Project
retainall ';' LIST ';' LIST Return the first list where items not in the second list are removed Macro
reverse (';' LIST )* Reverse the order of elements in one or more lists Macro
select ';' LIST ';' REGEX Selects entries in a list that matching a regular expression Macro
separator Get the operating system's file separator character Macro
sha1 ';' RESOURCE Calculate SHA-1 digest of a resource in the bundle Analyzer
size ( ';' LIST )* Count the total number of elements in one or more lists Macro
sjoin ';' SEPARATOR ( ';' LIST )+ Join lists with a custom separator Macro
sort (';' LIST )+ Sort lists alphabetically Macro
split ';' REGEX (';' STRING )* Split strings into a list using a regular expression Macro
startswith ';' STRING ';' PREFIX Check if a string starts with a specific prefix Macro
stem ';' STRING Extract the portion of a string before the first dot Macro
sublist ';' START ';' END (';' LIST )* Extract a portion of a list with support for negative indices Macro
subst ';' STRING ';' REGEX (';' STRING (';' NUMBER )? )? Substitute all the regex matches in the target for the given value; if a count is specified, limit the number of replacements to that count. Macro
substring ';' STRING ';' START ( ';' END )? Extract a substring from a string with support for negative indices Macro
sum (';' LIST )* Calculate the sum of numeric values in one or more lists Macro
system ';' STRING ( ';' STRING )? Execute a system command and return its output Macro
system_allow_fail ';' STRING ( ';' STRING )? Execute a system command, returning output and ignoring failures Macro
template ';' NAME [ ';' template ]+ Expand the entries of a merged and decorated Parameters object using a template that can refer to the key and attributes Macro
thisfile Get the absolute path of the current properties file Processor
toclasspath ';' LIST ( ';' BOOLEAN )? Convert class names to file paths Macro
toclassname ';' FILES Convert file paths to fully qualified class names Macro
tolower STRING Convert a string to lowercase Macro
toupper STRING Convert a string to uppercase Macro
trim ';' STRING Remove leading and trailing whitespace from a string Macro
tstamp ( ';' DATEFORMAT ( ';' TIMEZONE ( ';' LONG )? )? )? Generate a formatted timestamp Macro
unescape ( ';' STRING )* Convert escape sequences to their control characters Macro
uniq (';' LIST )* Remove duplicate elements from one or more lists Macro
uri ';' URI (';' URI)? Resolve a uri against a base uri. Processor
user ';' KEY ( ';' DEFAULT )? A current user setting from the ~/.bnd/settings.json file Workspace
vcompare VERSION VERSION Compare two version strings Macro
version MASK VERSION? Modify a version using a template. This is an alias to the versionmask macro. Macro
version_cleanup ';' VERSION Cleanup a potential maven version to make it match the OSGi Version syntax. Macro
versionmask MASK VERSION? Modify a version using a template Macro
vmax (';' LIST )* Find the maximum version in one or more lists Macro
vmin (';' LIST )* Find the minimum version in one or more lists Macro
warning ( ';' STRING )* Generate a build warning with a custom message Macro
workspace Get the absolute path to the workspace directory Workspace

Table of contents