Last modified: 03 Jan 2008
WARNING: This documentation covers Parallels H-Sphere versions up to 3.1. For the latest up-to-date Parallels H-Sphere documentation, please proceed to the
official Parallels site.
This document explains what are packages in H-Sphere and how to build them.
H-Sphere offers an interface for integrating custom plugins, or packages.
With these packages, you may add new or override default H-Sphere functionality.
Packages can be used to integrate the following elements:
These components are built into one portable .hsp file which
can be easily installed by an H-Sphere system administrator.
Building packages is performed in the following steps:
- determine package configuration: what resources, templates, systems scripts,
XML configuration files, language bundles, jars, etc. would
be included into a package
- prepare package content: make sure the files to be included to a package
are located in the corresponding directories you
will specify in the package configurator's command line
- run package configurator to collect package source files
into one preconfigured package source directory
- set package info: package name, version, build, etc.
- set package custom properties configuration: custom XML configs,
language bundles, etc.
- check and manually add source files wherever needed
- assemble the package into one Java archive file with .hsp extension
Log into the CP server as
Run package configurator to prepare the structure of your package. The format is:
java psoft.hsp.tools.PkgConfigurator --with-prefix[=TARGET_DIR] [WITH-OPTIONS]
[-l LOG_FILE [-dl]]
TARGET_DIR is the directory where the package will be assembled.
Package configurator creates the directory structure where you will later
add files to build the package.
If the specified directory does not exist, the configurator will try to create it.
If TARGET_DIR is omitted, the directory structure will be created
in the current directory.
WITH-OPTIONS: you choose the options to specify which components you will
include into the package: templates, language bundles, images, scripts, etc.
See Package Tools for details.
LOG_FILE: with the -l option, package configurator writes
its actions to a log file where you could check if it worked through correctly;
-dl is a detailed log mode.
java psoft.hsp.tools.PkgConfigurator --with-prefix=./MyPackage
--with-properties --with-templates --with-lang-bundle
--with-classes --with-scripts --with-xmls -l conf.log -dl
Notes on usage:
1) It is convenient to create a special location where you will assemble your packages.
For example, you can create the ~cpanel/shiva/custom/Packages directory
and specify the MyPackage subdirectory as TARGET_DIR for package configurator.
2) Normally, you don't need to specify paths in WITH-OPTIONS.
In such case, package configurator will create empty directories
(with empty default files for some options) within the TARGET_DIR directory,
and you will be able to add the files later.
Inside the package directory (specified in the --with-prefix option),
package configurator creates:
the package configuration file _pkg.xml.
In this XML file you define the package info (name, version, build, vendor, description)
and configure what elements will be included into the package.
the src directory where all source files are collected in
the following directories and files specified in _pkg.xml,
in accordance with the configurator's options chosen:
- templates/ - custom templates;
- pkg_classes/ - custom Java classes;
- pkg_scripts/ - custom scripts;
- pkg_xmls/ - custom XML configuration files;
- pkg_jars/ - 3rd party JARs;
- pkg_config/ - custom package properties
(the empty default.properties file created);
- pkg_lang_bundle/ - language bundles
- pkg_images/ - custom images
- pkg_tarballs - 3rd-party tarballs
- pkg_rpms - 3rd-party RPMs
- _SCRIPTS/_pkg.sql - SQL queries to be performed upon the H-Sphere database
- _SCRIPTS/_pre-install - script to be executed before the
- _SCRIPTS/_post-install - script to be executed after the package installation
- _SCRIPTS/_pre-uninstall - script to be executed before the
- _SCRIPTS/_post_uninstall - script to be executed after the package uninstallation
Package Configuration File (_pkg.xml)
DTD Scheme |
Description of Tags and Attributes in _pkg.xml |
According to the options selected, package configurator creates
the package configuration file _pkg.xml which looks similar to this:
<?xml version="1.0" encoding="utf-8"?>
<pkg build="00" description="Description for test package"
info="Additional information" name="NameOfThePackage"
Here, define the package name, description, vendor, version and build. This may look like:
<pkg build="2" description="Test Package"
info="This is a package built for test purposes" name="MyPackage"
vendor="Company Name" version="1.0.1">
In the above example, the package will be built into the MyPackage-1.0.1-2.hsp file.
You may not need to edit paths specified in _pkg.xml.
Package Properties File (default.properties)
If you run the package configurator with the --with-properties option,
package configurator creates the empty src/pkg_config/default.propeties file.
It has the same syntax as the default H-Sphere properties file
~cpanel/shiva/psoft_config/hsphere.properties. Package properties will customize the
default properties in hsphere.properties.
1) You must not change settings in hsphere.properties;
2) The package's default.properties file should contain only settings to be added to/override
the settings in hsphere.properties. Don't copy the whole content of hsphere.properties!
The src/templates/ directory with custom templates must have a structure
similar to that of the
H-Sphere custom templates directory.
Important: For those templates that have both .html and .html.in files,
you should include only .html.in templates sources into the package.
They should be automatically compiled during installation.
Read a separate document on customizing templates with packages.
XML Configuration Files
The pkg_xmls/ directory will include custom XML configuration files,
such as menu.xml
(see Menu Customization or design-config.xml
Skin and Icon Set Customization).
If you are planning to include XML configuration files into your package,
you must run package configurator with the --with-xmls --with-properties options.
The --with-properties option will create the package properties file,
where you will set the corresponding properties for custom XML config files to be included to the package.
specify just the names of the XML config files to be customized, without paths to them, for example:
Make sure that custom XML config files contain only those tags that need to be customized.
Package builder will automatically
find and merge custom XML configuration
with default configuration.
Read a separate document on customizing XML configuration files with packages.
If you include language bundles to the package, you must run package configuration with the --with-lang-bundle --with-properties options.
The --with-properties option is used to create the package properties file.
1) Add custom language bundle files:
Starting with H-Sphere 3.0 RC 1, menu.properties and messages.properties
become deprecated, and all labels are merged into a single hsphere_lang.properties for each language!
- Copy your customized language bundle files to the
Understanding Bundles for reference):
For example, language bundles for Portuguese (Brazil) will be:
- If you are not changing the default language files
(hsphere_lang.properties, menu.properties, messages.properties),
add empty files with these names to the src/pkg_lang_bundle directory:
This is required for correct bundle compilation.
touch hsphere_lang.properties menu.properties messages.properties
- In default.properties, add the following lines:
The package properties will be merged with the default settings in hsphere.properties.
2) Adding a new language to H-Sphere:
see Building New Language Packages
The pkg_scripts/ directory will have a tree of subdirectories, their level
reflecting the server type, OS family, OS name. For example, if you need to integrate
a script that will run on the CP server with RedHat Linux v. 7.3, you will have to put
your script into the directory src/pkg_scripts/CP/Linux/RH7.3/
The pkg_classes/ directory will have a tree of Java classes
similar to the H-Sphere resource tree in /hsphere/local/home/cpanel/shiva.
Run package builder to build the package. Use the --help option
to see the list of possible parameters:
java psoft.hsp.tools.PkgBuilder --help
The command will look similar to the following:
java psoft.hsp.tools.PkgBuilder --with-source=./MyPackage
Package builder checks if all required files in the source directory are present,
forms one jar file of Java classes (if they are present),
and makes a package as one jar file with the .hsp extension
(e.g., MyPackage-1.0.1-2.hsp) in the source directory
(./MyPackage in the example above).
After the package is built successfully, the package is ready to use.
It can be easily
uninstalled on other H-Sphere's.