/ 
SPVM-0.990149
River stage two • 47 direct dependents • 48 total dependents
⭐ Starred 61 GitHub stars
/ SPVM::Document::SPVMArchive

Name

SPVM::Document::SPVMArchive - SPVM Archive

Description

SPVM Archive is a format used to bundle SPVM class files, compiled SPVM native classes, precompiled classes, third-party header files, and static libraries into a single directory or a .tar.gz file.

These bundled assets are used by spvmcc to build a standalone native executable.

How to Create an SPVM Archive

To create an SPVM Archive, use the spvmcc command with the --build-spvm-archive option.

spvmcc --build-spvm-archive [Archive Directory] [Main SPVM File]

Examples:

If you have a main SPVM file myapp.spvm, you can build the SPVM Archive into a directory named spvm-archive-myapp as follows:

spvmcc -o spvm-archive-myapp --build-spvm-archive myapp.spvm

After execution, you can verify the created SPVM Archive using the ls command:

ls -R spvm-archive-myapp

The output should contain spvm-archive.json and the directories SPVM/, object/, lib/, and include/.

  • spvm-archive.json

    The metadata file of the archive. It contains the application name, SPVM version, build mode, and a registry (classes_h) that lists all classes included in the archive along with their types (native or precompile).

  • SPVM/

    This directory contains the .spvm source files. These are required so that the compiler can resolve class definitions when the archive is used in other projects.

  • object/

    This directory stores the compiled object files (.o). It includes objects for both SPVM native classes and precompiled classes, organized by their class namespace.

  • lib/ and include/

    These directories are created to store third-party static libraries (.a, .lib) and header files (.h, .hpp). Even if the target application has no external dependencies at the time of creation, these directories are generated as placeholders so that users can manually bundle necessary native assets into the archive.

How to Use an SPVM Archive

To use an existing SPVM Archive, call the use_spvm_archive method in your .config file.

Examples:

If you have created an SPVM Archive named spvm-archive-myapp, you can use it in your .config file like this:

use strict;
use warnings;
use File::Basename 'dirname';

my $config_global = SPVM::Builder::Config::Exe->new;
my $config_dir = dirname __FILE__;

# Load the pre-compiled assets from the SPVM Archive
$config_global->use_spvm_archive("$config_dir/spvm-archive-myapp");

$config_global;

Then, build your application using the spvmcc command:

spvmcc -o myapp myapp.spvm

Merging SPVM Archives

You can merge an existing SPVM Archive into a new one by combining the use_spvm_archive method in your .config file with the --build-spvm-archive option of the spvmcc command.

Examples:

If your myapp.config uses an existing archive:

# In myapp.config
$config_global->use_spvm_archive("/path/to/existing-archive");

And you run spvmcc with the --build-spvm-archive option:

spvmcc -o spvm-archive-merged --build-spvm-archive myapp.spvm

The following merging process occurs:

  • Class Metadata

    The classes_h registry and other metadata fields (app_name, app_version, mode, spvm_version) are merged or updated. If there are duplicate class names, the ones from the new build take precedence.

  • SPVM Class Files

    All .spvm source files required for the classes are collected from the existing archive and the current include paths, then stored in the SPVM/ directory of the new archive.

  • Object Files

    All .o files for SPVM native classes and precompiled classes are collected from the existing archive and copied into the new archive's object/ directory, alongside the newly generated object files.

  • Native Assets

    Static libraries (.a, .lib) in lib/ and header files (.h, .hpp) in include/ from the existing archive are collected and bundled into the new archive.

SPVM Archive Metadata

spvm-archive.json is the metadata file for the SPVM Archive.

The native and precompile fields are represented as integers: 1 for true and 0 for false. If a field is omitted, its value is considered to be 0.

Example of spvm-archive.json:

{
   "app_name" : "spvm-archive",
   "app_version" : "1.005",
   "spvm_version" : "0.990133",
   "mode" : "linux-64bit",
   "classes_h" : {
      "Array" : {
         "native" : 1,
         "precompile" : 1
      },
      "Packer" : {
         "precompile" : 1
      },
      "TestCase::NativeAPI" : {
         "native" : 1
      },
      "Address" : {}
   }
}

app_name

The name of the application from which this archive was generated.

app_version

The version of the application from which this archive was generated.

spvm_version

The version of SPVM used to create this archive.

mode

The mode of the application's config file (e.g., linux-64bit, debug, release) used to generate this archive. This field may not exist.

classes_h

A hash map of class information. Each key is a class name, and its value is a hash map that can contain the following fields:

  • native

    Set to 1 if the class has native methods.

  • precompile

    Set to 1 if the class has precompiled methods.

If these fields are missing, they are treated as 0. For example, Address : {} represents a pure SPVM class.

See Also

Copyright & License

Copyright (c) 2023 Yuki Kimoto

MIT License