global ';' KEY ( ';' DEFAULT )?

Summary

The global macro provides access to user-specific settings stored in the ~/.bnd/settings.json file. This allows builds to use machine-specific configuration like credentials, API tokens, or user preferences without storing them in project files.

Syntax

${global;<key>[;<default>]}

Parameters

• key - The setting name to retrieve from settings.json
• default (optional) - Default value to return if the setting is not found

Behavior

• Reads from the user’s ~/.bnd/settings.json file in their home directory
• Returns the value for the specified key
• Returns the default value if provided and key is not found
• Returns null if key is not found and no default is provided
• Special keys:
  • key.public - Returns the user’s public key as hex string
  • key.private - Returns the user’s private key as hex string

Examples

Access a custom setting:

maven.user=${global;maven.username}

Use with default value:

api.key=${global;example.api.key;default-key}

Access credentials:

-connection: ${global;nexus.url}; \
             uid=${global;nexus.username}; \
             pwd=${global;nexus.password}

Get public key:

signing.key=${global;key.public}

Conditional on global setting:

${if;${global;enable.feature};enabled;disabled}

Use Cases

• Storing user-specific credentials outside project files
• Machine-specific configuration (different per developer)
• API tokens and authentication information
• User preferences for build behavior
• Private repository credentials
• Signing keys and certificates
• Environment-specific URLs and endpoints

Notes

• Settings are stored in JSON format in ~/.bnd/settings.json
• The settings file is per-user, not per-project
• Keeps sensitive information out of version control
• Returns null (not empty string) when key is missing and no default
• The special key.public and key.private keys access cryptographic keys
• Settings can be edited directly in the JSON file
• Useful for CI/CD where different machines need different configurations

See test cases in MacroTestsForDocsExamples.java