Packaging

VOS3 packages contain a package manifest. Besides name and version of the bundle, the manifest provides options for assigning the bundle to a device users and sub-structuring the bundle into packages.

Each package can then bear attributes for the User Package Types and as well as optional group belongings and umask for file permissions.

Optionally, the bundle can bear User Installation Hooks helping with migration tasks during update installations, as well specifying Dependencies to other bundles and Targeting for specific device types or serial numbers only.

Manifest Structure

The following table describes the structure of VOS3 manifest JSON files applicable for application packages.

the manifest will contain additional fields that are automatically added by the packman packaging tool or are for internal system use only. Please do not delete these fields from the final manifest after creating the package.

Properties	Type	Mandatory	Description	Default	Example
BUNDLE INFORMATION
name	string	Yes	Name of the bundle	--	"BundleA"
version	string	Yes	Version of the bundle.	--	see Version String Format Example: "1.0.0"
user	string	Yes	User name, one of: usrX (1-16)	--	"usr1"
software_platforms	array of strings	Yes	List of target software platforms to install this bundle to. One of: "vos3"	--	[ "vos3" ]
PACKAGES
packages	array of objects	Yes	unlimited list of objects
name	string	Yes	name of package must match package name listed in bundle changeset		"packageA"
type	string	Yes	One of available package types, see User Package Types		"system_ro"
group	string	No	One of available owner groups: usrX (1-16) : private to user usrXsys (1-16) : User applications should use this when sharing files with system applications share : Use this when sharing files with all application and all system users users: Application users should use this group when sharing files with all other application users	usrX (1-16)	"usr1sys"
umask	string	No	Umask to be applied during installation	"027"
INSTALLATION HOOKS
hook	object	No	One of available package types, see User Installation Hooks
when	string	Yes	"before_dlfile" "after_dlfile"
executable	string	Yes	Path of executable		"patch_config.sh"
DEPENDENCIES
requires	array of objects	No	once the current dlfile has finished installation, this bundle requires that all listed requirements are met
bundle	object	No	requirement on bundle presence		"BundleB"
name		Yes	name of bundle
version_ranges	array of objects	No	list of version ranges, if absent all versions are assumed
version_start	string	Yes	Lowest version that is allowed (included)		use Version String Format Example: "1.0.0"
version_end	string	Yes	Highest version that is allowed (included)		use Version String Format Example: "999.0.0"
TARGETING
target	object	No	Installs this bundle if it matches at least one of the "include" expressions and none of the "exclude" expressions
include	object	No	If absent, matching all is assumed
devices	array of strings	No	List (union/OR) of regular expressions (pcre) matching device model names (model_num)	[ "[]" ]
dt_names	array of strings	No	List (union/OR) of regular expressions (pcre) matching device tree names (dt_name)	[ "[]" ]
serial_numbers	array of strings	No	List (union/OR) of regular expressions (pcre) matching serial_numbers	[ "[]" ]
exclude	object		If absent, matching none is assumed
devices	array of strings	No	List (union/OR) of regular expressions (pcre) matching device model names (model_num)	[ "[]" ]
dt_names	array of strings	No	List (union/OR) of regular expressions (pcre) matching device tree names (dt_name)	[ "[]" ]
serial_numbers	array of strings	No	List (union/OR) of regular expressions (pcre) matching serial_numbers	[ "[]" ]

User Package Types

Users need to package the applications according to VOS3 installation rules and choose one of the following package types

VOS3 package type	Installation Location	Users	Owner groups	Access	A/B Support	Main purpose
user_ro	/home/<user>/	sys_<>, usr<X>	usr<X>, sys_<>	RO	Y	application read-only executable, libraries, gui resources and other read-only data
font_ro	/usr/share/fonts/	sys_<>, usr<X>	share	RO	Y	additional fonts
versioned_data	/mnt/appdata/versioned/<user>/	usr<X>	usr<X>	RW	Y	private application configuration and assets
share_users_versioned_data	/mnt/appdata/versioned/share/	usr<X>	users	RW	Y	shared data between usr<X>
share_all_versioned_data	/mnt/appdata/versioned/globalshare/	sys_<>, usr<X>	share	RW	Y	shared data between sys_<> and usr<X>
data	/mnt/appdata/data/<user>/	usr<X>	usr<X>	RW	N	application non-critical runtime data (large media, etc.)
user_hook	<tmpfs>	usr<X>		RW	N/A	user application plugin to modify RW user data or versioned data

Note that additional VOS3 system package types are provided for system usage only.

User Installation Hooks

A hook is declared in the bundle manifest file using the "hook".

Hooks are extracted, authenticated and executed in a temporary environment with same permissions as the user's home.

The following library paths will be setup for executable to run in this order:

• Extracted path of executable (.)
• Extracted path "lib" path (./lib)
• Default runtime paths for the user in the active binary read-only partition

The "when" attribute specifies time of execution:

• "before_dlfile": before the DL file gets installed
• "after_dlfile": after the DL file got installed

The bundle that declares itself as a hook provides "when" (before / after) and specifies the "executable" that gets run by the installer.

This executable returns an exit code:

• 0: indicates that hook installation performed correctly

  • bundle (hook) is considered as installed
• 1: indicates that hook is not applicable to this platform

  • bundle (hook) is considered as not targeted
  • installation continues
• 2: indicates an error

  • bundle (hook) is considered not installed
  • installation is aborted

Version String Format

It recommended to follow the semantic of MAJOR . MINOR . PATCH [.PATCH_REVX] :

• MAJOR version when you make incompatible API changes,
• MINOR version when you add functionality in a backwards compatible manner, and
• PATCH version when you make backwards compatible bug fixes.
• The "PATCH_REVX" being considered as an extension to the PATCH field.

This versioning is used for:

• Validate/reject version formatting
• Validate/reject dependencies between bundles
• other version checks

Packman allows to specify a version extension in alphanumeric format, to add more, usually human readable information to the version string and is not considered for any version checks.

Versioned User Data

As opposed to the "data" location (pointed by "~/flash"), the current "versioned data" content is backed up when installation takes place.

Typically, the following sequence happens:

1. Install application v1 with usr1 which contains "versioned_data"

   • versioned_data content v1
2. Application runs for a while and update its versioned_data

   • versioned_data content v1b
3. Install application v2 with usr1 which contains "versioned_data"

   • versioned_data content v2
4. Application runs for a while and update its versioned_data

   • versioned_data content v2b
5. Fallback (to v1)

   • versioned_data content v1b

Package Creation

The package creation tool is called packman. Please refer to the packman user guide for more details.

Here is a sample showing how to create dlfile for single or multiple bundles and merging them:

multi_bundles_sample.zip

archive · 42KB

Open

Create Package from bundle directory

To build a DL-file with a bundle use:

./packman.py build -t vos3 -s dev -i <bundle_dir> -d <dlfile>

Where:

• "bundle_dir" contains manifest.json at its root
• all package directories are at its root
• manifest.json contains bundle name, version, packages with name and types

The packaging process will show errors and warning explaining issues.

Notes:

• the build command accepts several directories by using "-i <bundle_dir1> <bundle_dir2>" option.
• the build command will issue an error if destination already exists, to overwrite, use "-f" option.

Create Package from dlfile directory (recursive)

To build a DL-file with multiple bundles use:

./packman.py build -t vos3 -s dev -r -i <dlfile_dir> -d <dlfile>

Where:

• "dlfile_dir" contains one or more bundle directories
• each "dlfile_dir/bundle_dir" contains manifest.json at its root
• each package directory for each bundle is at the root of "dlfile_dir/bundle_dir"
• each manifest.json contains bundle name, version, packages with name and types

Merging several DL-files

To merge the content of several dlfiles into one usr:

./packman.py merge -t vos3 -s dev -d <dlfile1> <dlfile2>  -o vos3dlfile.tar

Example:

./packman.py merge -t vos3 -s dev -d dl.file1.tar dl.file2.tar  -o dl.allfiles.tar

Notes:

• the merge command accepts more than 2 dlfiles in input on the "-d" option
• the merge command will issue an error if destination already exists, to overwrite, use "-f" option: example: ./packman.py merge -t vos3 -s dev -d <dlfile1><dlfile2> -fo vos3dlfile.tar

Validate DL-file

Validation for VOS3 packaging verifies the json schema of manifests and changesets.

It also checks for valid entries, coherency between bundles, etc.

To validate a DL-file use:

./packman.py validate -t vos3 -rd <dlfile>

Guidance and examples

All bundles

• must have a meaningful name
• must not have prefix (dl. , bdl. , pkg.)
• should not have postfix
• bundle names should not include version information

All packages

• must be a directory at the root of the CSD file (xxxx.csd.tgz) → automatically done by packman tool

Example 1: structure and manifest

usr1 application manifest

Application bundle manifest

{
    "name": "bankapp",
    "version": "1.0.1",
    "user": "usr1",
    "software_platforms": ["vos3"],
    "packages": [
        {
            "name": "bankapp",
            "type": "user_ro"
        },
        {
            "name": "bankapp_res",
            "group": "share",
            "type": "user_ro"
        }
    ]
}

Directory structure:

Build command line:

packman.py build -t vos3 -s dev -i bankapp -fd dl.bankapp_1.0.1.tar

Example 2: manifest for configuration

usr1 configuration manifest

Application bundle manifest

{
    "name": "bankAconfig",
    "version": "1.0.1",
    "user": "usr1",
    "software_platforms": [
        "vos3"
        ],
    "packages": [{
        "name": "bankA",
        "type": "versioned_data"
        }
    ]
}

Package Signing

Managing signers

By default, if no signer specified in manifest, the signer list in manifest is set to ['SPONSOR'] for customer applications.

Development signing

Development signing is done using packman tool as shown above

Production signing

Production signing is performed using the Signing Portal. dl files with user bundles use this portal: https://sign.verifone.com/

1. Upload the dlfile to the portal
2. Reviewers are alerted by mail that an approval is requested
3. As soon as 2 reviewers have approved, the signature is done
4. Requester receives notification by mail that request was approved
5. Signed dlfile is available for download

Note: the signing portal will only sign / resign bundles that are for the users the signer can sign

Handling conflicts

A conflict is an attempt to package and install entries (dir, file, symlink) with the same path.

Rules

Here are the conflicting rules:

1. Within one package of any type, two or more entries of ANY type MUST NOT conflict with each other (this would be a TAR archive with duplicate entries)
2. Within one bundle, between two or more packages of same type:

   • two or more entries MUST NOT conflict with each other with only one exception:

     • conflicting entries are directories with same user/group and permissions
3. Among all applicable bundles (result of install session on already installed bundles) for READ-ONLY package types (system_ro, user_ro, font_ro, kernel_ro) :

   • two or more entries MUST NOT conflict with each other with only one exception:

     • conflicting entries are directories with same user/group and permissions

Note: Rules above allow conflicts for Read-write locations in different bundles, the order of installation (see below) will determine the outcome and installing these packages will overwrite any runtime modifications.

Verifying rules

Installer will detect & reject any attempt to break the above rules and fail the installation.

Packman tool will detect & reject any attempt to break the above rules in the scope the dlfiles provided to it.

If several dlfiles may be involved in a conflict, an attempt to use the "merge" command of packman will reveal the conflicts during installation, even if they will be installed separately.

Dependencies

Dependencies are verified for each dlfile at the end of the verification phase.

Here is a example for multiple dlfiles provided for installation in one session:

• Already installed: bundle A
• Installation session (3 dlfiles), verification starts:

  • dlfile 1 : bundle B and C (depends on bundle A and B) → OK
  • dlfile 2 : bundle D (depends on B and E) → ERROR → E is not satisfied
  • dlfile 3 : bundle E (depends on A)

Note: this installation session is rejected and none of the dlfiles are installed (and fallback is kept).

Targeting vs dependency

Definitions

Targeting: "manifest rules to check if a valid bundle should be filtered out from installation depending on device characteristics"

Dependency: "manifest rules to check if a valid bundle has all required resources to work properly on device, failing installation otherwise"

Comparison

	Criteria type	Criteria	Matching action	Not matching
Targeting	Target reference value is always present and immutable	Serial Number Device Model Device tree name	install bundle	skip bundle installation
Dependency	Dependency reference value can change (or be removed) and be part of the same installation session	Bundle name / version Sponsor ID	accept installation	FAIL

Installation order

Bundle ordering (BO):

1. root

   1. bundle name alphabetic order
2. sys_<>

   1. bundle name alphabetic order
3. usr (bundle alpha)

   1. bundle name alphabetic order

Installation order:

1. Verification of all dlfiles, for each dlfile in provided order:

   1. installer hook
   2. remove bundles (BO)
   3. "before_dlfile" hooks (BO)
   4. normal bundles (BO)
   5. "after_dlfile" hooks (BO)
   6. dependency check
2. Installation of all dlfiles, for each dlfile in provided order:

   1. installer hook
   2. remove bundles (BO)
   3. "before_dlfile" hooks (BO)
   4. normal bundles (BO)
   5. "after_dlfile" hooks (BO)