# MulleObjC-startup Versioning Scheme: Semantic Versioning Implementation

> MulleObjC-startup uses strict semantic versioning MAJOR.MINOR.PATCH. Discover how this scheme ensures consistent releases and dependency management.

- Repository: [mulle-objc/mulleobjc-startup](https://github.com/mulle-objc/mulleobjc-startup)
- Tags: internals
- Published: 2026-03-07

---

**MulleObjC-startup follows strict semantic versioning (MAJOR.MINOR.PATCH) defined in [`CMakeLists.txt`](https://github.com/mulle-objc/mulleobjc-startup/blob/main/CMakeLists.txt) and synchronized with Git tags to ensure consistent release management across build systems and downstream dependencies.**

The MulleObjC-startup repository provides essential initialization code for the Mulle Objective-C runtime. Understanding its versioning scheme is critical for maintaining compatibility in downstream projects and CI/CD pipelines. This guide examines how MulleObjC-startup implements semantic versioning across its CMake build system, source code, and release artifacts.

## Semantic Versioning Structure in MulleObjC-startup

MulleObjC-startup adheres to the classic **MAJOR.MINOR.PATCH** semantic versioning format. Three numeric components, separated by dots, define the release identity.

**Major version** changes (transitioning from 0 to 1) are reserved for breaking API modifications. While the library maintains a 0.x version number, it indicates a pre-1.0 stable line where the API may still evolve.

**Minor version** increments introduce new, backward-compatible features. These additions extend functionality without breaking existing consumer code.

**Patch version** increments address bug fixes, security patches, or trivial adjustments that do not add new functionality.

## Where Version Information Is Stored

The MulleObjC-startup versioning scheme relies on multiple synchronized locations to ensure consistency across build and distribution channels.

### CMakeLists.txt as the Source of Truth

The primary version definition resides in the root [`CMakeLists.txt`](https://github.com/mulle-objc/mulleobjc-startup/blob/main/CMakeLists.txt) file. The CMake `project()` command establishes the canonical version string used throughout the build system.

```cmake
project( MulleObjC-startup VERSION 0.20.7 LANGUAGES C )

```

This declaration sets the `PROJECT_VERSION` variable, which CMake uses for packaging and for generating configuration headers.

### Git Tags for Release Management

Release versions are permanently marked in the Git repository through annotated tags. The tag names exactly mirror the CMake version strings.

Key tag references include:
- `.git/refs/tags/0.20.7`
- `.git/refs/tags/0.27.0`

These tags appear on the GitHub Releases page and serve as the exact version strings referenced by CI systems and downstream dependency managers.

### Generated Configuration Headers

CMake processes the template file `cmake/share/MulleObjC-startup-config.h.in` to generate [`MulleObjC-startup-config.h`](https://github.com/mulle-objc/mulleobjc-startup/blob/main/MulleObjC-startup-config.h). This header exposes the version to client code through a preprocessor macro.

The generated header contains:

```c
#define MULLE_OBJC_STARTUP_VERSION "0.20.7"

```

Source files such as `src/MulleObjC-startup.m` include this header to access version information at compile-time.

### Release Documentation

The [`RELEASENOTES.md`](https://github.com/mulle-objc/mulleobjc-startup/blob/main/RELEASENOTES.md) file maintains a human-readable changelog. Each release receives a dedicated section header using the version number.

Example entry:

```markdown

### 0.20.7

```

This documentation ensures users can track changes between specific semantic versions.

## Practical Examples for Developers

### Querying the Version in C Code

Client applications can determine the linked version of MulleObjC-startup at runtime by checking the generated version macro.

```c
#include <MulleObjC-startup/MulleObjC-startup.h>
#include <stdio.h>

int main(void)
{
    printf("MulleObjC-startup version: %s\n",
           MULLE_OBJC_STARTUP_VERSION);
    return 0;
}

```

The macro `MULLE_OBJC_STARTUP_VERSION` expands to the string defined in the CMake project configuration.

### Enforcing Version Requirements in CMake

Downstream projects can specify minimum version requirements when locating the package. CMake validates the installed version against the semantic version constraint.

```cmake

# In a consumer's CMakeLists.txt

find_package(MulleObjC-startup 0.20 REQUIRED)

# The call will fail if the installed startup library is older than 0.20.x

```

This mechanism relies on the `PROJECT_VERSION` defined in the upstream [`CMakeLists.txt`](https://github.com/mulle-objc/mulleobjc-startup/blob/main/CMakeLists.txt).

### Creating a New Release Tag

Maintainers must synchronize Git tags with the CMake project version. The following commands create an annotated tag matching the version declared in [`CMakeLists.txt`](https://github.com/mulle-objc/mulleobjc-startup/blob/main/CMakeLists.txt).

```sh

# After bumping the version in CMakeLists.txt

git tag -a 0.27.0 -m "Release 0.27.0 – new loader support"
git push origin 0.27.0

```

The tag name must exactly match the version string used in the `project(... VERSION ...)` declaration to maintain consistency across the versioning scheme.

## Version Compatibility Guidelines

When depending on MulleObjC-startup, observe these semantic versioning rules:

- **Major version zero** (0.x.y) indicates the library is in a pre-1.0 stable line. While functional, breaking changes may occur when transitioning to 1.0.0.
- **Minor version** bumps guarantee backward compatibility. You can safely upgrade from 0.20.0 to 0.27.0 without modifying client code.
- **Patch version** bumps contain only bug fixes. These are always safe to apply immediately.

The single source of truth remains the [`CMakeLists.txt`](https://github.com/mulle-objc/mulleobjc-startup/blob/main/CMakeLists.txt) file, with all other references (Git tags, headers, documentation) deriving from this definition.

## Summary

- MulleObjC-startup uses **semantic versioning** (MAJOR.MINOR.PATCH) to communicate compatibility and change impact.
- The canonical version lives in **[`CMakeLists.txt`](https://github.com/mulle-objc/mulleobjc-startup/blob/main/CMakeLists.txt)** within the `project()` command.
- **Git tags** (e.g., `0.20.7`, `0.27.0`) mirror the CMake version to mark release points.
- The **`MULLE_OBJC_STARTUP_VERSION`** macro exposes the version to C code via generated headers.
- **Minor** and **patch** updates maintain backward compatibility; **major** updates (including the eventual 0→1 transition) signal breaking changes.

## Frequently Asked Questions

### What versioning scheme does MulleObjC-startup use?

MulleObjC-startup follows **semantic versioning** with a three-part number format: MAJOR.MINOR.PATCH. This scheme is implemented in the CMake build system and synchronized with Git tags to ensure consistent version identification across source code and binary distributions.

### How do I check which version of MulleObjC-startup is installed?

You can query the version at compile-time by checking the `MULLE_OBJC_STARTUP_VERSION` macro defined in the generated [`MulleObjC-startup-config.h`](https://github.com/mulle-objc/mulleobjc-startup/blob/main/MulleObjC-startup-config.h) header. In CMake-based projects, you can also verify the version through the `find_package` command, which validates the installed version against your project's requirements.

### What does the 0.x version number indicate?

The **0.x** version line indicates that MulleObjC-startup is in a pre-1.0 stable state. While the library is functional and maintained, the major version zero signals that breaking API changes may occur when the project eventually transitions to version 1.0.0. Minor and patch releases within the 0.x line still follow semantic versioning rules for backward compatibility.

### How do I specify a minimum version requirement in CMake?

Use the `find_package` command with a version constraint in your [`CMakeLists.txt`](https://github.com/mulle-objc/mulleobjc-startup/blob/main/CMakeLists.txt). For example, `find_package(MulleObjC-startup 0.20 REQUIRED)` ensures that CMake will only accept version 0.20.0 or higher (such as 0.27.0) while rejecting older releases. This mechanism relies on the version defined in the upstream [`CMakeLists.txt`](https://github.com/mulle-objc/mulleobjc-startup/blob/main/CMakeLists.txt) project declaration.