Application packaging and deployment


This page attempts to document important aspects of the internals of tpkg as a guide for developers new to the project.

Package Format

Packages consist of two nested tarballs. The top level directory of the outer tarball generally matches the package filename with the ".tpkg" extension removed. The outer tarball contains the inner tarball and a checksum.xml file used to verify the integrity of the inner tarball. The inner tarball may be compressed. For example:

% tar tf ruby-1.8.7-p352-1-darwin107-x86_64.tpkg

The inner tarball is named tpkg.tar or tpkg.tar.gz or similar, depending on the compression used. The top level directory of the inner tarball is "tpkg". In that toplevel directory will be a tpkg.yml or tpkg.xml (deprecated) file, perhaps other metadata and supporting files like pre or post install scripts, and then the package files in a root or reloc directory, depending on whether the user built a relocatable package or not. The contents of the inner tarball are provided entirely by the user (it is a tar of whatever directory they passed to "tpkg --make"), so it could contain arbitrary other directories or contents that might be ignored by tpkg. tpkg does some sanity checking of the directory, but generally gives the user freedom to include arbitrary contents in the package. Here's an example showing the structure of the inner tarball, and how to use tar to examine the inner tarball without unpacking it first.

% tar -O - -xf ruby-1.8.7-p352-1-darwin107-x86_64.tpkg ruby-1.8.7-p352-1-darwin107-x86_64/tpkg.tar.gz | tar ztf -


The concept of a "requirement" or "request" is widely used in tpkg. These are usually stored in a variable named something like "req". A req represents a set of requirements for a package. These requirements can either come from a dependency in another package, or via a user's request on the command line. I.e. "tpkg -i foo=2.4=6" includes a request for "foo=2.4=6".

A req is stored as a Hash. For example, here's the req for "foo=2.4=6":

>> Tpkg.parse_request('foo=2.4=6')
=> {:name=>"foo", :minimum_version=>"2.4", :maximum_version=>"2.4", :minimum_package_version=>"6", :maximum_package_version=>"6", :type=>:tpkg}


Each installed or available package is represented internally as a "pkg". A pkg is stored as a Hash. It has the following fields:


One of :currently_installed, :native_installed, :native_available or the file, directory or URL that is the source for an available package


Instance of Metadata (see below) for the package


Boolean to indicate that this currently installed package should be preferred over newer versions that might be available. Set to true by default for all currently installed packages, but then set to false if the user has requested an upgrade for that particular package.


The Metadata class represents the metadata from a package. It abstracts the differences between YAML and XML metadata.

View on GitHub