Use VPT for Vega App Packages

Vega Packaging Tool (VPT) manages Vega app packages. Use it to create, examine, manage, and validate .vpkg files (Vega’s standard package format). To get started with VPT, install the Vega Software Development Kit (SDK), which includes two main command-line tools:

VPT: Manages package operations like creation and validation
Vega CLI: Handles the overall app development workflow, including building and deploying apps

While Vega CLI uses VPT during app builds, you can also run VPT directly to:

Examine packages
Validate content
Add custom signatures to your apps

Package contents and filtering

When you run vega exec vpt pack, VPT reads only the folders that Vega OS mounts at runtime. It drops build artifacts that have no runtime purpose on a device. Starting with VPT 1.2.18, VPT also drops files from lib/ that aren’t shared libraries. If you upgrade from an earlier Vega SDK version, files that your app previously shipped in lib/ might no longer be packaged. This filtering runs inside vega exec vpt pack, which every build path uses. It applies to React Native for Vega apps and native apps alike, including builds you start with vega build.

Folders that VPT packages

VPT reads manifest.toml and the following folders from your source directory: lib/, bin/, assets/, bundle/, config/, shared/lib/, and shared/assets/. VPT doesn’t package any other top-level folder, and it gives no warning when it ignores one. The following table lists what VPT keeps and drops in each folder.

Folder	Files that VPT keeps	Files that VPT drops
`lib/`	Files whose name ends in `.so` or contains `.so.`, such as `libfoo.so`, `libfoo.so.0`, and `libfoo.so.0.1.0`.	`.debug` files, with no warning. Every other file, with a warning.
`bin/`	Every file except the types in the next column.	`.debug` files, with no warning. `.a`, `.dylib`, `.lib`, and `.dll` files, with a warning.
`assets/`	Every file, with no filtering by file type.	The generated `asset-index.bin` file.
`bundle/`	Every file except source maps.	Files whose name ends in `.bundle.map`.
`config/`	Every file.	None.

shared/lib/ and shared/assets/ follow the same rules as lib/ and assets/. A CMake build can stage shared artifacts into that separate tree, and VPT filters both trees the same way. A dropped file doesn’t fail your build. The warning looks like the following example.

Warning: skipping non-runtime artifact 'lib/armv7/startup.lua' from VPKG. This file has no runtime purpose on Vega; update your build to stop staging it.

After each of these warnings, VPT pauses for 10 seconds. A build that stages several non-runtime files in lib/ or bin/ takes noticeably longer as a result. To get that time back, remove the files from your build. To confirm what a built package contains, run show-contents or unpack.

How VPT filters the lib folder

VPT decides what to keep in lib/ by filename, not by file format. A file stays in the package when its name ends in .so or contains .so.. VPT drops every other file, including static libraries, scripts, JSON files, and files that have no extension. Three more rules apply to lib/:

VPT checks the .debug suffix first. A debug symbol file named libfoo.so.debug is dropped, even though its name contains .so..
VPT judges a symlink by the symlink’s own name, so libfoo.so -> libfoo.so.1 is packaged as a symlink. A symlink that points to a missing file causes an error.
VPT flattens subfolders under lib/. Each file that VPT keeps lands at lib/<arch>/<filename> in the package.

For guidance on bundling native libraries and linking against system libraries, see Manage native libraries with linker namespacing.

Where to put files that aren’t shared libraries

Put runtime files that aren’t shared libraries in assets/raw/. VPT doesn’t filter assets/ by file type, so scripts, JSON files, certificates, and archives are packaged as they are. At runtime, these files are read-only at /pkg/assets/raw/<filename>. Subfolders keep their paths, so assets/raw/scripts/main.lua is available at /pkg/assets/raw/scripts/main.lua. To change one of these files at runtime, copy it to /data first.

Commands

VPT provides the following command categories. For a complete list of commands and their latest options, use vega exec vpt --help.

Package information

These commands view package details and contents.

info

Shows package information, including ID, title, and build details.

Usage: vega exec vpt info [OPTIONS] <PACKAGE>

Arguments:
<PACKAGE>          Path to the vpkg

Options:
  --json           Output in JSON format
  -h, --help       Print help

Example:

vega exec vpt info /path/to/sampleapp.vpkg

Example output:

Sample App    com.amazondeveloper.sampleapp v1.3.4 b53

show-contents

Lists all files in the package.

Usage: vega exec vpt show-contents [OPTIONS] <PACKAGE>

Arguments:
  <PACKAGE>     Path to the vpkg

Options:
  -h, --help    Print help

Example:

vega exec vpt show-contents /path/to/sampleapp.vpkg

Example output:

Package contents:
assets/ (6 files)
lib/ (2 files)
manifest.toml
meta-info/ (4 files)

Package creation and extraction

These commands create and modify packages.

pack

Creates a package from source directories. You can specify package name, version, and build number. For the folders that pack reads and the files it drops, see Package contents and filtering.

Usage: vega exec vpt pack [OPTIONS] <SOURCE_PATHS>...

Arguments:
  <SOURCE_PATHS>...  Source directories

Options:
  -n, --pkg-name <PKG_NAME>          Name of the package
  -d, --dest-path <DEST_PATH>        Destination path
  -b, --build-number <BUILD_NUMBER>  Build number
  -v, --version <VERSION>            Build version
      --validate                     Enforce validation of the manifest
      --no-strict-abi-check          Disable strict ABI check
  -h, --help                         Print help

Example:

vega exec vpt pack /path/to/source --pkg-name sampleapp --dest-path /path/to/output --version 1.0.0 --build-number 42

Example output:

Creating package sampleapp...
Validating manifest...
Package created at /path/to/output/sampleapp.vpkg

unpack

Extracts all package files to a destination path.

Usage: vega exec vpt unpack [OPTIONS] <PACKAGE>

Arguments:
  <PACKAGE>                    Path to the vpkg

Options:
  -d, --dest-path <DEST_PATH>  Destination path
  -h, --help                   Print help

Example:

vega exec vpt unpack /path/to/sampleapp.vpkg --dest-path /path/to/output

Example output:

Extracting package contents...
Files extracted to /path/to/output

dump

Extracts a file from the package. Prints to stdout, or saves to the destination path you specified.

Usage: vega exec vpt dump [OPTIONS] <PACKAGE> <ENTRY>

Arguments:
  <PACKAGE>                    Path to the vpkg
  <ENTRY>                      Path to the entry inside vpkg

Options:
  -d, --dest-path <DEST_PATH>  Destination path
  -h, --help                   Print help

Example:

vega exec vpt dump /path/to/sampleapp.vpkg manifest.toml

Example output:

Extracting manifest.toml from sampleapp.vpkg
Content written to stdout

extract-locales

Extracts localization files from a package as JSON or text.

Usage: vega exec vpt extract-locales [OPTIONS] <PACKAGE>

Arguments:
  <PACKAGE>                           Path to the vpkg

Options:
  -f, --format <FORMAT>               Output format [default: json] [possible values: json, text]
  -h, --help                          Print help

Example:

vega exec vpt extract-locales --format json /path/to/sampleapp.vpkg

Example output:

Extracting localization files...
Files extracted to current directory:
- en/strings.json
- es/strings.json

Package signature and verification

These commands handle security and validation.

pull

Extracts digest and signature files from the package. A digest file lists cryptographic checksums for all files in the VPKG. A signature file contains a detached cryptographic signature that verifies the digest file’s authenticity. Use --json-digest to extract the digest file in JSON format, or --json-signature to extract the signature file in JSON format.

Usage: vega exec vpt pull [OPTIONS] <--signature|--digest|--json-signature|--json-digest> <PACKAGE> <DEST>

Arguments:
  <PACKAGE>           Path to the vpkg
  <DEST>              Destination path

Options:
  --signature
  --digest
  --json-signature
  --json-digest
  -h, --help          Print help

Example:

vega exec vpt pull --signature /path/to/sampleapp.vpkg /path/to/output/digest.sig

Example output:

Extracting signature from sampleapp.vpkg
Signature saved to /path/to/output/digest.sig

push

Adds a signature file to the package. Use --json-signature to insert a JSON-formatted signature file that corresponds to the package’s digest.

Usage: vega exec vpt push [OPTIONS] <--signature <SIGNATURE>|--json-signature <JSON_SIGNATURE>> <PACKAGE>

Arguments:
  <PACKAGE>                           Path to the vpkg

Options:
  --signature <SIGNATURE>             Legacy signature of a digest file path to push
  --json-signature <JSON_SIGNATURE>   Signature of a digest.json file path to push
  -h, --help                          Print help

Example:

vega exec vpt push --signature /path/to/input/digest.sig /path/to/sampleapp.vpkg

Example output:

Adding signature to sampleapp.vpkg
Signature successfully added

sign

Signs a message using a private key and certificate.

Usage: vega exec vpt sign [OPTIONS] <MESSAGE> <PRIVKEY> <CERTFILE> <OUTPUTFILE>

Arguments:
  <MESSAGE>      Message to sign
  <PRIVKEY>      Private key used to sign the message
  <CERTFILE>     X.509 certificate that corresponds to the private key
  <OUTPUTFILE>   Output path

Options:
  -r, --resign   Resign a signed message
  -h, --help     Print help

Example:

vega exec vpt sign --resign /path/to/input/digest.sig /path/to/developer-private.key /path/to/developer-cert.pem /path/to/output/digest.sig

Example output:

Signing digest.sig with provided key and certificate
Signature created at /path/to/output/digest.sig

verify

Verifies a message’s signature using specified certificates.

Usage: vega exec vpt verify [OPTIONS] <MESSAGEFILE> <SIGFILE> <CERTIFICATES>...

Arguments:
  <MESSAGEFILE>      File to verify
  <SIGFILE>          Signature used to verify the message
  <CERTIFICATES>...  List of X.509 certificates to verify against

Options:
  -p, --partial      Perform a partial/non-exhaustive verification using only the provided CAs
  -h, --help         Print help

Example:

vega exec vpt verify /path/to/message.txt /path/to/message.sig /path/to/cert.pem

Example output:

Verifying signature...
Signature verification successful

checksum

Calculates the package checksum.

Usage: vega exec vpt checksum [OPTIONS] <PACKAGE>

Arguments:
  <PACKAGE>     Path to the vpkg

Options:
  -h, --help    Print help

Example:

vega exec vpt checksum /path/to/sampleapp.vpkg

Example output:

Calculating checksum...
SHA256: a1b2c3d4e5f6...

generate-csr

Creates a certificate signing request (CSR) from a configuration file.

Usage: vega exec vpt generate-csr [OPTIONS]

Options:
  -k, --key <KEY>        Private key
  -c, --config <CONFIG>  Config file
  -o, --out <OUT>        Output directory
  -v, --verbose          Print the generated CSR path
  -h, --help             Print help

Example:

vega exec vpt generate-csr -k /path/to/private.key -c /path/to/config.json -o /path/to/output/dir -v

Example output:

Reading configuration from config.json
Generating CSR using private.key
CSR created at /output/dir/certificate.csr

Package analysis

These commands validate package structure and contents.

validate

Runs validation checks for AppStore submission requirements:

Validates the package manifest for required configurations and syntactical correctness. See the manifest user guide.
Validates whether the bundled libraries or declared dependencies for your app’s native code meet Vega’s ABI requirements.

Usage: vega exec vpt validate [OPTIONS] <PATH>

Arguments:
  <PATH>        Path to the vpkg, directory, or manifest.toml

Options:
      --no-strict-abi-check          Disable strict ABI check
      --no-color                     Disable colored output
  -h, --help                         Print help

Example:

vega exec vpt validate sampleapp.vpkg

Example output:

validating 'sampleapp.vpkg' ...
analyzing manifest.toml ...
found issues in manifest.toml ...
manifest validation found 2 errors
manifest.toml:3:1 info: [package.icon] Icon isn't defined in the manifest. Using system default.
  help: Define an icon to help users recognize your app
manifest.toml:15:6 error: [components.interactive.id] Component ID 'com.company.sample.badcomponentname' doesnt have package ID prefix 'com.amazondeveloper.sampleapp'
  help: Component ID should follow the format: package_id.component_name
manifest.toml:9:1 error: [components.interactive.categories] No interactive component declares 'com.amazon.category.main' category. App can't launch without package-id or package ASIN.
  help: One interactive component should declare 'com.amazon.category.main' category in the manifest

starting ABI validation ...
found issues in ABI validation ...
Missing dt_needed dependencies found:
  - Library 'libsample-app.so.0.1.0' at path '/sampleapp/lib/arm/libsample-app.so.0.1.0' has missing dt_needed dependencies: libsample-deps.so
Missing dlopen dependencies found:
  - Library 'libsample-app.so.0.1.0' at path '/sampleapp/lib/arm/libsample-app.so.0.1.0' has missing dlopen dependencies: libsample-deps.so

Create a custom signature for your package

Pull the signature file from the package:

vega exec vpt pull --json-signature /path/to/sampleapp.vpkg /path/to/output/digest.json.sig

Example output:

Extracting signature from sampleapp.vpkg
Signature saved to /path/to/output/digest.json.sig

Update the signature file using your private key and certificate:

vega exec vpt sign --resign /path/to/input/digest.json.sig /path/to/developer-private.key /path/to/developer-cert.pem /path/to/output/digest.json.sig

Example output:

Signing digest.json.sig with provided key and certificate
Signature created at /path/to/output/digest.json.sig

Push the updated signature file back to the package:

vega exec vpt push --json-signature /path/to/output/digest.json.sig /path/to/sampleapp.vpkg

Example output:

Adding signature to sampleapp.vpkg
Signature successfully added

​Package contents and filtering

​Folders that VPT packages

​How VPT filters the lib folder

​Where to put files that aren’t shared libraries

​Commands

​Package information

​info

​show-contents

​Package creation and extraction

​pack

​unpack

​dump

​extract-locales

​Package signature and verification

​pull

​push

​sign

​verify

​checksum

​generate-csr

​Package analysis

​validate

​Create a custom signature for your package

​Related topics

Package contents and filtering

Folders that VPT packages

How VPT filters the lib folder

Where to put files that aren’t shared libraries

Commands

Package information

info

show-contents

Package creation and extraction

pack

unpack

dump

extract-locales

Package signature and verification

pull

push

sign

verify

checksum

generate-csr

Package analysis

validate

Create a custom signature for your package

Related topics