vcompare VERSION VERSION

Summary

Compare two OSGi version strings using proper version semantics, returning -1, 0, or 1.

Syntax

${vcompare;<version1>;<version2>}

Parameters

• version1: First version to compare (OSGi version format)
• version2: Second version to compare (OSGi version format)

Behavior

Compares two OSGi version strings using semantic version comparison and returns:

• 0 - The versions are equal
• 1 - The first version is greater than the second (newer)
• -1 - The first version is less than the second (older)

OSGi versions follow the format: major.minor.micro.qualifier

• Numeric parts (major, minor, micro) are compared numerically
• Qualifier is compared lexicographically

Examples

# Equal versions
${vcompare;1.0.0;1.0.0}
# Returns: 0

# First version greater
${vcompare;2.0.0;1.5.0}
# Returns: 1

# First version less
${vcompare;1.0.0;2.0.0}
# Returns: -1

# Micro version comparison
${vcompare;1.2.3;1.2.2}
# Returns: 1

# With qualifiers
${vcompare;1.0.0.SNAPSHOT;1.0.0.RELEASE}
# Returns: 1 (SNAPSHOT > RELEASE lexicographically)

# Different lengths
${vcompare;1.0;1.0.0}
# Returns: 0 (1.0 equals 1.0.0.0)

# Use in conditional logic
-include ${if;${vcompare;${bndversion};7.0.0};modern.bnd;legacy.bnd}

# Check minimum version requirement
-include ${if;${vcompare;${Bundle-Version};2.0.0};compatible.bnd;incompatible.bnd}

# Version range check
is-current = ${if;${vcompare;${Bundle-Version};3.0.0};true;false}

# Compare with project version
${vcompare;${version;===;${Bundle-Version}};${minimum-version}}

Use Cases

1. Version Requirements: Check if a version meets minimum requirements
2. Conditional Configuration: Apply different settings based on version
3. Build Compatibility: Ensure compatibility with specific versions
4. Version Validation: Verify version constraints are met
5. Feature Gating: Enable features only in certain version ranges

Notes

• Uses OSGi version semantics, not lexicographic comparison
• For string comparison, use compare
• For numeric comparison, use ncompare
• Properly handles major.minor.micro.qualifier format
• Missing version parts default to 0 (or empty qualifier)
• Numeric parts compared numerically (2.0 > 1.10)
• Qualifier compared alphabetically
• Returns only -1, 0, or 1

Related Macros

• compare - Compare strings lexicographically
• ncompare - Compare numbers numerically
• version / versionmask - Format version numbers
• if - Conditional macro that can use comparison results
• bndversion - Get current bnd version for comparison

See test cases in MacroTestsForDocsExamples.java