Next Previous Contents

7. SLP Header Data Structure

7.1 Design Principle

Original design

The SLP v5 format (and preceding SLP formats: 2, 3 and 4) were developed by the developers of the Stampede Linux distribution. The original SLP package formats were designed by Matthew S. Wood of the Stampede Linux distribution. Basic features requested by Stampede Linux end-users, developers, and other project groups considering the SLP format, have been added to the SLP format. This enhanced format, termed SLP v5a, has been developed by the Marble Horse Free Software Group, an independent free software development group.

Forward-Compatibility of Format Enhancements

In the design of the enhancements and extensions to the SLP v5 file format, also known as SLP v5a, the design team considered forward-compatibility for existing SLP-handling tools to be of high importance. Forward-compatibility has been preserved for all critical tools: installer and remover. Forward-compatibility has not been preserved for SLP editors and field viewing tools, due to the change in field definition.

Classes of field use

This document includes information related to each field used with the SLP v5a package header. Information regarding anticipated field usage has been included for each field. The following classes of field use have been defined to aid in understanding the meaning of the data in package header fields:

Field is used during package installation; field supplies data used during the extraction or pre/post-extraction processing for package.

Field is used during package removal (deletion); field supplies data used during the removal of files or pre/post-removal processing for package.

Field is used during package upgrade (installation of a different package version over an existing version of the same package); field supplies data used during the extraction or pre/post-extraction processing for package.

Field is used in the formulation, specification or completion of dependencies. Dependency handling is performed during nearly all package management operations.

Field is fundamental in nature. Field represents unique identifying information regarding a package or supplies information used in all package management operations.

Field is cosmetic in nature. Field is used for the storage of detail data which is not used (from a technical perspective) in package management operations.

Portability

The SLP header format is designed to be cross-platform compatible. Standard C99 types are used for all fields (char, int32_t), enabling the SLP header to accurately be accessed from virtually any platform.

Mandatory field population vs. optional field population

This section of the document is pending merge from internal sources.

Padding in unpopulated fields

All unpopulated fields shall be padded with NULL.

String termination and maximal string length

This section of the document is pending merge from internal sources.

7.2 SLP v5a Header Data Structure

/* 
** SLP v5a package header data structure 
*/ 
struct SLPv5a_header_format { 
    char FilesToRetain[756];
    int32_t InstallRecommendation;
    int32_t DistributionMagicNumber;
    int32_t PackageReleaseIndex;
    int32_t DistributionReleaseIndex;
    char PackageConflictsWith[128];
    char InstallScript[128];
    char DescriptionShort[80];
    char DescriptionLong[1456];
    char PackageCategory[80];
    char DependsRequired[512];
    char CryptographicSignature[512];
    char PackageOrigin[30];
    char PackageCreationDate[30];
    int32_t SoftwareVersionKnownOutdated;
    char SoftwareVersion[20];
    char SoftwareName[20];
    int32_t SoftwareBinaryFormat;
    int32_t AdvancedInstallScript;
    int32_t SLPFormatIndex; 
};
 

7.3 SLP v5 Header Data Structure

/* 
** SLP v5 package header data structure 
** This structure is included for historical reference purposes.
*/
struct SLPv5_header_format {
    char FilesToKeep[756];
    int32_t Priority;
    int32_t CompressionMechanism;
    int32_t Release;
    int32_t Copyright;
    char ConflictsWith[128];
    char SetupScript[128];
    char ShortDescription[80];
    char LongDescription[1536];
    char DependsRequirements[512];
    char DependsSatisfy[512];
    char Author[30];
    char Date[30];
    int32_t CompilerVersion;
    char SoftwareVersion[20];
    char PackageName[20];
    int32_t BinaryFormat;
    int32_t PackageGrouping;
    int32_t SlPackageVersion;
};
 

7.4 Field Changes in SLP v5a (from SLP v5)

Terminology

With the development of the SLP v5a package format, it has become necessary to document changes from the previous package format (SLP v5). Due to maintenance of backward-compatibility with existing tools, the field sizes have not been altered; the following are definitions for the terms we have used to describe the changes between the two package format header structures:

Fields which have been renamed have retained their original meaning but the element name used to access this field has been altered from the element name used in the previous format specification.

Fields which have been redefined have received new meaning. The data stored a particular field in the new header format has altered meaning or value structure from the same field in the previous format specification.

Fields which have been unchanged have not been redefined or renamed; the element name and meaning of stored data has not been changed in comparison to the same field in the previous format specification.

Field changes

7.5 SLP v5a Field Definitions

FilesToRetain

Type: character array of length 756 Position: 1 Offset: 0 Used During: install, removal, upgrade

FilesToRetain shall contain a semi-colon delimited list of files which should not be overwritten, removed or otherwise modified during install, removal or upgrade operations. Full paths to each file should be included. Population of this field is not mandatory.

InstallRecommendation

Type: 32-bit integer Field Position: 2 Offset: unknown Used During: install, removal

InstallRecommendation shall contain a value representing the perceived need for installation of a package. Inclusion of valid data within this field is required; this field must be populated.

Value definitions:

Package is required for system operation. De-selection of this package from an installer's package select list should result in a warning message akin to, "Warning: The package you have attempted to de-select is tagged as 'required'. Your system may not function correctly without this package." Required packages should encompass only those packages which are absolutely crucial to fundamental system operation.

Package is recommended for installation. Removal of this package from an installation will not cause significant harm to system operation. Packages in this category include non-critical system libraries and common network support packages, such as dhcpcd and pppd.

Package installation is entirely optional. Packages in this category include system enhancement packages, games and most application packages. Nearly all packages in a full-blown distribution should be classified as optional.

Package is not recommended for installation. Packages in this category may represent imminent danger to your system; installation of these packages should be preceded by a warning, forcing user confirmation. Examples of packages which might exist in this category include experimental kernels, alpha-grade software and filesystem manipulation utilities which are known to be potentially dangerous.

DistributionMagicNumber

Type: 32-bit integer Field Position: 3 Offset: unknown Used During: dependency handling

Values for DistributionMagicNumber shall be maintained by a central authority. Value 0 through 100 shall be reserved. Values increasing from 101 shall be assigned based on request. Assigned values shall be unique to a distribution effort (defined as a distinct project entity which will be creating a series or set of packages not designed to interoperate with existing distribution systems or package suites). Inclusion of valid data within this field is required; this field must be populated.

Value definitions:

101 Stampede Linux

PackageReleaseIndex

Type: 32-bit integer Field Position: 4 Offset: unknown Used During: fundamental

Values for PackageReleaseIndex shall be unique to a distribution and distribution release (as specified by DistributionMagicNumber and DistributionReleaseIndex) as well as software package and software package version (as specified by SoftwareName and SoftwareVersion). The PackageReleaseIndex shall be assigned a value of '1' for initial release of a package.

In the event that a package designed for a specific distribution release, which contains a particular piece of software of a specific revision is, due to bug resolution, mis-packaging resolution or other improvement, re-released, the PackageReleaseIndex shall be incremented. Updates to a specific package, which consist of internally-created patches to resolve issues or enhance software, shall result in increment of PackageReleaseIndex (SoftwareName and SoftwareVersion are governed by official (external) release parameters).

Inclusion of valid data within this field is required; this field must be populated.

DistributionReleaseIndex

Type: 32-bit integer Field Position: 5 Offset: unknown Used During: dependency handling

Values for DistributionReleaseIndex shall be maintained by a central authority for each distribution (see DistributionMagicNumber). Values 0 through 100 shall be reserved for special use. Values increasing from 101 shall be assigned by a distribution's central authority, based on new releases, development trees and experimental projects.

Assigned values shall be unique to a packaging effort (defined as a distinct release or development tree which creates and/or distributes packages which are not compatible (or favorably combined) with other package sets, due to library incompatibility, initscript style change, etc.).

Each distribution's central authority shall be responsible for defining and tracking these numbers. This should be done with care so as to avoid potential conflicts in the future. Inclusion of valid data within this field is required; this field must be populated.

PackageConflictsWith

Type: character array of length 128 Field Position: 6 Offset: unknown Used During: dependency handling

Values for PackageConflictsWith shall be listed in dependency format. If no packages conflict with the package, this field will be left empty. In the event that there are conflicting packages, this field will contain software names and may contain software versions or package revisions for conflicting packages. The (O) optional dependency flag shall be omitted from use within this field. Population of this field is not mandatory.

InstallScript

Type: character array of length 128 Field Position: 7 Offset: unknown Used During: install, (upgrade), (removal)

InstallScript shall contain the full path to an executable script which shall be called by one or more of the SLP utilities. Though this specification generally does not govern anything related to the file contents of a SLP archive, it should be noted that the specified install script file must be flagged executable. Population of this field is not mandatory.

DescriptionShort

Type: character array of length 80 Field Position: 8 Offset: unknown Used During: cosmetic

DescriptionShort shall contain text providing a simple explanation of the purpose of the packaged software. This description should be fairly limited in detail, but should provide a suitable list of the intent of the packaged software. Exact parameters for this field shall be defined on a distribution-specific basis. Population of this field is not mandatory.

DescriptionLong

Type: character array of length 1456 Field Position: 9 Offset: unknown Used During: cosmetic,

field use may be extended for metadata storage

DescriptionLong shall contain text providing a verbose explanation of the purpose of the packaged software. This description should constitute an overview for the package. Exact parameters for this field shall be defined on a distribution-specific basis. Population of this field is not mandatory.

PackageCategory

Type: character array of length 80 Field Position: 10 Used During: cosmetic

PackageCategory shall contain text defining the general category of the package, to be used by management utilities to provide some level of hierarchical view of the installed list of packages and packages to be installed. Population of this field is not mandatory.

DependsRequired

Type: character array of length 512 Field Position: 11 Used During: dependency handling

DependsRequired shall contain dependency information based on the format used by the SLPv5a dependency handling mechanisms. Population of this field is not mandatory.

CryptographicSignature

Type: character array of length 512 Field Position: 12 Used During: fundamental

CryptographicSignature shall contain GPG signatures (binary) for the package body (compressed archive) and the header (less data in the CryptographicSignature and PackageCreationDate fields (which shall be NULL padded for purpose of signature generation). Population of this field is not mandatory.

PackageOrigin

Type: character array of length 30 Field Position: 13 Used During: fundamental

PackageOrigin shall contain text providing a short identifier for the group or person from which a particular package originated. This identifier may match the short identifier associated with the appropriate DistributionMagicNumber should the package originate from an official distribution release. The PackageOrigin field should also be an indicator of the key or family of keys used when the cryptographic signature for the package was generated. Population of this field is not mandatory.

PackageCreationDate

Type: character array of length 30 Field Position: 14 Offset: unknown Used During: fundamental

PackageCreationDate shall contain the date and time of package creation in compliance with the ISO 8601 specification for 'Combination of extended format calendar date and extended format Coordinated Universal Time (UCT) of day'. Based on the definitions found within the ISO 8601 specification, this date format may be referenced using the following notation, whereby 'T' is a delimiter specifying beginning of time value and 'Z' is an indicator of Zero-Meridian time (UCT):

CCYY-MM-DDThh:mm:ssZ
 

SoftwareVersionKnownOutdated

Type: 32-bit integer Field Position: 15 Used During: dependency handling

SoftwareVersionKnownOutdated shall contain a boolean flag value. This flag selects the use or disuse of a version-related exception to package installation and upgrade. Population of this field is not mandatory; if this field is unpopulated, false (0) is assumed.

Value definitions:

Packaged software version is a normal release; this package may be handled using standard install, upgrade and removal procedural mechanisms.

Packaged software version is a special release, not designed to be upgraded by packages of higher version indicator. This flag allows one to define a package as an exception, an older version of software which does not conflict with newer versions of software and is never upgraded by future software versions. Examples of packages which would have this flag set are gcc version 2.7.2.3 and sgml-tools 1.0.9, both older versions of the respective packages; newer versions of gcc (such as 2.95.2) and sgml-tools (such as 2.x) are not upgrades to these older versions as the older versions must be retained due to features and functionality not found in new versions of the software.

SoftwareVersion

Type: character array of length 30 Field Position: 16 Used During: fundamental

SoftwareVersion shall contain a string value for the version of software packaged. This value most frequently matches that supplied by the original source archive used to create the package. Inclusion of valid data within this field is required; this field must be populated.

SoftwareName

Type: character array of length 30 Field Position: 17 Used During: fundamental

SoftwareName shall contain a string value for the name of the software packaged. This value most frequently matches that supplied by the original source archive used to create the package. Inclusion of valid data within this field is required; this field must be populated.

SoftwareBinaryFormat

Type: 32-bit integer Field Position: 18 Used During: fundamental

SoftwareBinaryFormat shall contain one value from a predefined list of hardware architectures/binary formats. This field shall be used to determine basic hardware compatibility of a package with a given platform. Inclusion of valid data within this field is required; this field must be populated. Valid values for this field shall be defined prior to final release of the SLPv5a specification.

AdvancedInstallScript

Type: 32-bit integer Field Position: 19 Used During: install, (upgrade), (removal)

AdvancedInstallScript shall contain a boolean flag value. This flag selects the use or disuse of mechanisms passing additional stage-related information to the install script in conjunction with calls to the install script during three stages for each package handling operation. Population of this field is not mandatory; if this field is unpopulated, false (0) is assumed.

Value definitions:

Referenced install script is a standard install script; it should be called only during the post-extraction phase of a package install operation.

Referenced install script is capable of handling stage-related command-line arguments; based on these arguments, the script may choose to perform operations at one or more supported stages (of 'pre-', 'at-' and 'post-' for each package handling operation). If this flag is set, the script is expected to disregard any command-line arguments referencing stages it does not support or stages at which it does not need to perform any operations.

SLPFormatIndex

Type: 32-bit integer Field Position: 20 Used During: fundamental

Indicator used to delineate the version of the SLP format used. Inclusion of valid data within this field is required; this field must be populated. For all SLPv5a programs, this field must be set to a value of '5' in order to maintain backward compatibility with SLPv5 utilities.


Next Previous Contents