... {section}
{column:width=30%}
h1. Getting Started
h4. Try HelloWorld
If you'd like to review and try out a very basic end-to-end example of publishing and installing a package using the Image Packaging System, take a look at the [Hello World Example].
For an overview of how to package software using IPS see the [Multi-platform IPS Packaging for Software Engineers|http://wikis.sun.com/download/attachments/42085446/Multi_Platform_IPS_Packaging_for_Software_Engineers.pdf] presentation.
h3. What's Different About pkg(5)?
*Packages Consist of Actions*: There are actions for defining files and directories that are part of the package, actions for setting package attributes, actions for declaring dependencies on other packages, actions for creating users and groups, installing device drivers, etc. Some of these actions are only used for operating system distributions. Each action has various properties, such as the name of the file to install or the value of an attribute, and actions may optionally have tags that provide meta information about the action, such as what locale it is for.
*Separation of Building from Packaging*: The pkg(5) system intentionally does not impose requirements on the build system for how packages are actually produced. The interface between the build system and pkg(5) is the package publishing interface, which consists of the pkgsend command or other tools that perform the same operations on a repository as pkgsend.
*No On-disk Format*: Currently, there is no standard on-disk format for an pkg(5) package that can be transfered from system to system (like a .rpm file or a SVR4 package datastream file or a .nbm file). A pkg(5) package does not exist apart from a repository that contains it. So the package creation process for pkg(5) consists of determining how to publish an pkg(5) package to a repository. As pkg(5) matures, there are plans to deliver an on disk format.
h3. Package Scripts and Install-time Configuration
Th pkg(5) system does not support open-ended package scripts. Instead it supports a set of well defined package actions that can be used to perform specific, reversible operations, such as: creating users and groups, installing device drivers, etc. There has been some discussion on supporting a general "run this later after the package has been installed" action, but this has not been specified let alone implemented.
So how do packages perform basic configuration that is not covered by existing pkg(5) actions? Here are some ideas:
# Minimize configuration needed by your software by simplifying it and choosing good defaults.
# Have your software perform basic configuration at application start-up instead of package install time
# Handle configuration tasks by implementing mechanisms that are triggered by placing files in well-known locations (for example Gnome's mechanism of placing a .desktop file in \~/.config/autostart to register a desktop startup task).
# Use your installer's configuration framework for basic initial installation configuration
# Use the UpdateCenter 2.0's package attributes for triggering install scripts when packages are installed/updated via the UC2 GUI.
# Ensure there is a manual option, where configuration can be performed directly by the user
More details on option #5 is included in the [Install Time Configuration Functional Specification|http://wiki.updatecenter.java.net/Wiki.jsp?page=UC20FSD.InstallConfig].
{column}
{column:width=3%}
{column}
{column:width=30%}
h1. Packaging Publishing Tools
There are several ways in which you can publish pkg(5) packages based on your existing binary content:
* {{pkgsend}}
* {{makepkgs}}
* SVR4 Conversion
Why so many tools? Simple: Different package authors use different build technologies and have different requirements as to how they like to specify content for packages. Some authors are fine with pointing to a reference installation and packaging all or most of the content while other authors like to provide a list of every file to be represented in a package.
Once you've understood the following package authoring tool options, you might want to read [Assembling Install Bundles] to learn how to create distributions containing pkg(5) packages.
h4. {{pkgsend}} Command
The publication client, {{[pkgsend(1)|http://src.opensolaris.org/source/raw/pkg/gate/src/man/pkgsend.1.txt]}}, is built into the core pkg(5) system and allows the publication of new packages and new package versions to an image packaging depot server. Each publication is structured as a transaction; multiple invocations of pkgsend through a transaction allow the addition of actions and the transaction submission. Each action can be published with a separate {{pkgsend}} invocation (as shown in the [Hello World Example]), or a manifest file with many actions in it can be published with a single {{pkgsend}} invocation. The {{pkgsend}} command also has the ability to pull files from a directory tree.
h4. {{makepkgs}} Command
The {{makepkgs}} script was developed as a front-end to the {{pkgsend}} command. A package prototype file per package is used to represent the directories, files and metadata (package name, description, version, etc.) to include in the package. Refer to the {{[makepkgs]}} documentation for more details.
The {{makepkgs}} command is part of the {{pkg-extra-tools}} package in the pkg(5) multi-platform toolkit. See the [Downloads] page to download a copy of the tooklkit.
h4. {{makepkgs}} Custom Ant Task
A set of custom Ant tasks act as front ends to the {{makepkgs}}, {{copypkgs}} and {{makeimage}} Python-based utilities. You can read about and try an [example of using these Ant tasks with the OpenDS|http://blogs.sun.com/pkg/entry/pkg_5_custom_ant_tasks] project. See the [pkg(5) Custom Ant Task Documentation|http://download.java.net/updatecenter2/promoted/latest/pkg-toolkit-docs/index.html] for more details.
These custom Ant tasks are included in the {{pkg-extra-tools}} package in the pkg(5) multi-platform toolkit. See the [Downloads] page to download a copy of the tooklkit.
h4. {{makepkgs}} Maven Plugin
If you are using Maven for your build process you can use the ["Maven plugin for makepkgs"|https://updatecenter2.dev.java.net/maven-makepkgs-plugin] for generating and publishing IPS package of your project. More information about the plugin can be found at the following link ["Maven plugin for makepkgs"|https://updatecenter2.dev.java.net/maven-makepkgs-plugin]
h4. SVR4 Conversion
Since pkg(5) has been developed within the context of OpenSolaris, and there are many preexisting SVR4 packages, the package publishing command, {{[pkgsend(1)|http://src.opensolaris.org/source/raw/pkg/gate/src/man/pkgsend.1.txt]}}, includes an option for taking an SVR4 package and publishing it as a pkg(5) package. To use this method, the project uses SVR4 packaging tools ({{pkgmk}}, etc.) to create an SVR4 package, and then {{pkgsend}} is invoked to publish the package to a repository.
Assuming the SVR4 package is called foo, an example of publishing an SVR4 package in pkg(5) format is:
{noformat}
pkgsend -s http://pkg.example.com:10000/ send foo
{noformat}
The version information for the package is extracted from the SVR4 package meta data, i.e., the {{pkginfo}} file.
{column}
{column:width=3%}
{column}
{column:width=30%}
h1. Packaging Best Practices
|| h4. Identifying Packages || |