Skip to content

Backward Compatibility

Jump to bottom
Yuki Kimoto edited this page Feb 17, 2026 · 23 revisions

Backward Compatibility.

Policy of Keeping Backward Compatibility

There is currently no policy to keep the backward compatibility of the SPVM language.

If you look at Changes, you see a lot of breaking backward compatibility.

You expect backward compatibility to be improved little by little as more modules are released to CPAN. For now, there are more than 100 SPVM modules on CPAN.

Binary Compatibility

How developers can keep binary compatibility of SPVM

SPVM is designed to keep binary compatibility.

Even if the SPVM language itself is upgraded, previously installed SPVM modules and applications will work correctly without experiencing segmentation faults.

However, whether or not SPVM developers will actually keep binary compatibility is pending until version 1.0.

Here is how developers can keep binary compatibility after version 1.0 is reached.

Requirement 1: Do not change the SPVM operation code implementation defined in spvm_implement.h

Binary compatibility is not kept if the implementation of the SPVM operation code defined in spvm_implement.h is changed.

This is because the precompiled code contains the implementation of the operation code defined in spvm_implement.h.

On the other hand, implementation changes in spvm_api.c will not affect binary compatibility.

Requirement 2: Do not change the Native API order defined in spvm_native.h

Binary compatibility is not be kept if the order of Native APIs defined in spvm_native.h is changed (i.e., the IDs are changed in the documentation).

Requirement 3: Do not change the enumeration value published to users.

Do not change the enumeration value published to users.

A getting enumeration value is replaced to an interger literal at compilation time.

For this, if an enumeration value is changed after first publication to users, the binary compatibility is not kept.

How to Recover if Binary Compatibility is Broken

If binary compatibility is broken due to a major upgrade of the SPVM core or an intentional change in the ABI, precompiled or native modules may cause segmentation faults. In such cases, you can recover the environment by reinstalling the affected modules.

Recovery Command

The following one-liner identifies modules that contain native or precompiled classes and reinstalls them using cpanm.

# Reinstall modules affected by binary compatibility changes (Example for SPVM::Mojolicious)
curl -sL https://raw.githubusercontent.com/yuki-kimoto/SPVM/refs/heads/master/util/cpandeps | perl - --verbose --native-class-only SPVM::Mojolicious | grep -vx "SPVM" | xargs cpanm --reinstall

Note: Replace SPVM::Mojolicious with the module name you are using.

Explanation of the Command

This one-liner automates the identification and reinstallation of modules that are susceptible to ABI changes:

  1. Fetching and Executing cpandeps: curl retrieves the latest dependency analysis script from the SPVM repository, and perl - executes it directly without needing to save the file locally.
  2. Filtering with --native-class-only: This is the core of the optimization. The script analyzes the dependency tree of the specified module (e.g., SPVM::Mojolicious) and filters for only those distributions that contain Native or Precompiled classes.
  3. Excluding the Core: grep -vx "SPVM" ensures that the SPVM core itself is excluded from the reinstallation list, as it has presumably already been upgraded.
  4. Forced Reinstallation: xargs cpanm --reinstall takes the list of identified modules and performs a fresh installation. This process ensures that all C source files (including precompiled ones) are compiled again and linked against the currently installed SPVM core headers and libraries.

By targeting only modules with native or precompiled components, this command minimizes the recovery time while ensuring that all binary-dependent parts of your environment are consistent with the new SPVM version.

Home

Clone this wiki locally