version.h File Reference

#include <banjo/api.h>

Include dependency graph for version.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	BJ_VERSION_MAJOR(version)
#define	BJ_VERSION_MINOR(version)
#define	BJ_VERSION_PATCH(version)
#define	BJ_VERSION_STAGE(version)
#define	BJ_MAKE_VERSION(major, minor, patch, stage)
#define	BJ_NAME   "Banjo"
#define	BJ_NAME_VARIANT   ""
#define	BJ_VERSION_MAJOR_NUMBER   0
#define	BJ_VERSION_MINOR_NUMBER   1
#define	BJ_VERSION_PATCH_NUMBER   0
#define	BJ_VERSION_STAGE_NUMBER   (BJ_VERSION_DEV | 0x00)
#define	BJ_VERSION   BJ_MAKE_VERSION(BJ_VERSION_MAJOR_NUMBER, BJ_VERSION_MINOR_NUMBER, BJ_VERSION_PATCH_NUMBER, BJ_VERSION_STAGE_NUMBER)
#define	BJ_VERSION_DEV   0x00
#define	BJ_VERSION_ALPHA   0x40
#define	BJ_VERSION_BETA   0x80
#define	BJ_VERSION_RC   0xC0
#define	BJ_VERSION_STABLE   0xFF

Functions
size_t	bj_format_version (char *buffer, size_t bufsize, uint32_t version)

Detailed Description

32-bit packed version storage following the SemVer standard.

Banjo versions are stored in a single 32-bit integer, with each byte representing a different component in order from most significant to least significant: major version, minor version, patch version, and stage (pre-release type and number).

For example, the version 3.4.0-rc.2 is represented as 0x030400C2:

• 0x03000000 → Major version 3
• 0x00040000 → Minor version 4
• 0x00000000 → Patch version 0
• 0x000000C2 → Release Candidate, second iteration

This header provides macros to construct packed version integers, extract each component, and define stage flags. The encoding respects SemVer precedence, so comparing two packed versions using standard integer comparison operators correctly reflects SemVer ordering. Pre-release stages always compare lower than stable releases, and the stage byte allows internal numbering for alpha, beta, and RC builds.

SemVer Standard: https://semver.org/

Macro Definition Documentation

BJ_MAKE_VERSION

#define BJ_MAKE_VERSION	(		major,
			minor,
			patch,
			stage )

Value:

    ((((uint32_t)(major)) << 24U) | (((uint32_t)(minor)) << 16U) | \
     (((uint32_t)(patch)) << 8U) | ((uint32_t)(stage)))

Construct a packed 32-bit version.

The 32-bit version layout is [major:8 | minor:8 | patch:8 | stage:8].

Parameters

major	Major version in the range [0, 255].
minor	Minor version in the range [0, 255].
patch	Patch version in the range [0, 255].
stage	Stage byte, typically one of BJ_VERSION_ALPHA, BJ_VERSION_BETA, BJ_VERSION_RC, or BJ_VERSION_STABLE optionally OR'ed with a stage number.

Returns

Packed 32-bit version suitable for BJ_VERSION_* macros.

BJ_NAME

#define BJ_NAME   "Banjo"

Library name string.

This macro can be changed to modify the name of the library in case of fork, for example.

BJ_NAME_VARIANT

#define BJ_NAME_VARIANT   ""

Variant name for Banjo binary.

The variant is an additional name set after the version number. It can be used in a fork project to specify a non-mainstream version of banjo, while still keeping the name Banjo.

BJ_VERSION

#define BJ_VERSION   BJ_MAKE_VERSION(BJ_VERSION_MAJOR_NUMBER, BJ_VERSION_MINOR_NUMBER, BJ_VERSION_PATCH_NUMBER, BJ_VERSION_STAGE_NUMBER)

Current API version as a packed 32-bit value.

BJ_VERSION_ALPHA

#define BJ_VERSION_ALPHA   0x40

Alpha release.

BJ_VERSION_BETA

#define BJ_VERSION_BETA   0x80

Beta release.

BJ_VERSION_DEV

#define BJ_VERSION_DEV   0x00

Version stage flags.

The least significant byte of the 32-bit version integer encodes the stage of the release.

The two most significant bits indicate the stage type: alpha, beta, rc, or stable. The remaining six bits store the stage number, for example rc.2 would be encoded as BJ_VERSION_RC | 0x02.

Certain values are treated specially: 0xFF always represents a stable release and has the highest precedence. Any 0b00xxxxxx value is implementation-defined.

This encoding cannot distinguish between, for example, rc and rc.0. Version precedence follows SemVer rules, so all pre-release stages are considered lower than stable releases. Alpha release

BJ_VERSION_MAJOR

#define BJ_VERSION_MAJOR

(

version

)

Value:

((uint8_t)(((version) >> 24U) & 0xFFU))

Extract the major version from a packed 32-bit version.

The most significant byte of the version represents the major version.

Parameters

version

The packed 32-bit version value.

Returns

Major version in the range [0, 255].

BJ_VERSION_MAJOR_NUMBER

#define BJ_VERSION_MAJOR_NUMBER   0

Current major version number.

BJ_VERSION_MINOR

#define BJ_VERSION_MINOR

(

version

)

Value:

(((version) >> 16U) & 0xFFU)

Extract the minor version from a packed 32-bit version.

The second byte of the packed version represents the minor version.

Parameters

version

The packed 32-bit version value.

Returns

Minor version in the range [0, 255].

BJ_VERSION_MINOR_NUMBER

#define BJ_VERSION_MINOR_NUMBER   1

Current minor version number.

BJ_VERSION_PATCH

#define BJ_VERSION_PATCH

(

version

)

Value:

(((version) >> 8U) & 0xFFU)

Extract the patch version from a packed 32-bit version.

The third byte of the packed version represents the patch version.

Parameters

version

The packed 32-bit version value.

Returns

Patch version in the range [0, 255].

BJ_VERSION_PATCH_NUMBER

#define BJ_VERSION_PATCH_NUMBER   0

Current patch version number.

BJ_VERSION_RC

#define BJ_VERSION_RC   0xC0

Release Candidate.

BJ_VERSION_STABLE

#define BJ_VERSION_STABLE   0xFF

Stable Release.

BJ_VERSION_STAGE

#define BJ_VERSION_STAGE

(

version

)

Value:

((version) & 0xFFU)

Extract the stage byte from a packed 32-bit version.

The least significant byte of the packed version contains the stage type and stage number.

Parameters

version

The packed 32-bit version value.

Returns

Stage byte in the range [0, 255].

BJ_VERSION_STAGE_NUMBER

#define BJ_VERSION_STAGE_NUMBER   (BJ_VERSION_DEV | 0x00)

Current stage version specifier.

Function Documentation

bj_format_version()

size_t bj_format_version	(	char *	buffer,
		size_t	bufsize,
		uint32_t	version )

Format a packed version number as a SemVer-compatible string.

Writes a human-readable Semantic Version string into the provided buffer, using the packed 32-bit version representation defined in version.h. The output follows the form:

major.minor.patch[-stage[.number]]

Stable releases are printed without a pre-release suffix. Pre-release stages (alpha, beta, rc, or implementation-defined unstable stages) are formatted according to the encoded stage type and stage number.

This function behaves like snprintf: it writes at most bufsize bytes (including the null terminator), never overflows the buffer, and returns the number of characters that would have been written if the buffer were sufficiently large.

Parameters

buffer	Destination buffer for the formatted version string.
bufsize	Size of the destination buffer in bytes, including the terminating null character.
version	Packed 32-bit version value to format.

Returns

The number of characters that would have been written, excluding the terminating null character. If the return value is greater than or equal to bufsize, the output has been truncated.

Examples

build_info.c.