Building Packages

Last modified: 03 Jan 2008

This document explains what are packages in H-Sphere and how to build them.

• Overview
• Building Procedure
  • 1. Preconfiguration
  • 2. Configuration
    • Package Configuration File (_pkg.xml)
    • Package Properties File (default.properties)
    • Templates
    • XML Configuration Files
    • Language Bundles
    • Scripts
    • Java Classes
  • 3. Building

Overview

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:

• resources: new or custom Java classes
• system scripts (in the /hsphere/shared/scripts directory)
• templates: new or custom templates
• images: custom images
• Control Panel menu
• CP skins and icon sets
• language bundles: adding new languages to H-Sphere interface or updating language files
• context help XML customization
• plans: XML plan wizards
• crons: new or custom CP cron jobs
• promotions: custom promotion validators and calculators
• SQL quieries: making changes into the H-Sphere database
• third party RPMs and tarballs to be included into H-Sphere scripts.

These components are built into one portable .hsp file which can be easily installed by an H-Sphere system administrator.

Building Procedure

Building packages is performed in the following steps:

1. preconfiguration:
   - 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
2. configuration:
   - 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
   
3. building:
   - assemble the package into one Java archive file with .hsp extension

1. Preconfiguration

1. Log into the CP server as cpanel user.

2. 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]]

   Here:

   • 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.

   Example:

   cd ~cpanel/shiva/custom/Packages
   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 package installation
    
  • _SCRIPTS/_post-install - script to be executed after the package installation
    
  • _SCRIPTS/_pre-uninstall - script to be executed before the package uninstallation
    
  • _SCRIPTS/_post_uninstall - script to be executed after the package uninstallation
    

2. Configuration

Package Configuration File (_pkg.xml)

DTD Scheme | Description of Tags and Attributes in _pkg.xml | Example

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"
    vendor="Vendor" version="00.00.00">
    <scripts src="pkg_scripts/"/>
    <templates src="templates/"/>
    <classes src="pkg_classes/"/>
    <xmls src="pkg_xmls/"/>
    <config path="pkg_config/default.properties"/>
</pkg>

1. 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.

2. 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!

Templates

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 (see 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.

1. In default.properties, specify just the names of the XML config files to be customized, without paths to them, for example:

   DESIGN_SCHEME_CONFIG=design_config.xml
   MENU_CONFIG=menu.xml

2. 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.

Language Bundles

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:

Important: 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 src/pkg_lang_bundle directory (see Understanding Bundles for reference):
  

  hsphere_lang_<language>_<COUNTRY>.properties
  menu_<language>_<COUNTRY>.properties
  messages_<language>_<COUNTRY>.properties

  For example, language bundles for Portuguese (Brazil) will be:
  

  hsphere_lang_pt_BR.properties
  menu_pt_BR.properties
  messages_pt_BR.properties
  

• 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:
  

  cd src/pkg_lang_bundle
  touch hsphere_lang.properties menu.properties messages.properties

  This is required for correct bundle compilation.
• In default.properties, add the following lines:
  

  TEMPLATE_BUNDLE=packages.PackageName.hsphere_lang
  MENU_BUNDLE=packages.PackageName.menu
  USER_BUNDLE=packages.PackageName.messages

  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

Scripts

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/

Classes

The pkg_classes/ directory will have a tree of Java classes similar to the H-Sphere resource tree in /hsphere/local/home/cpanel/shiva.

3. Building

Run package builder to build the package. Use the --help option to see the list of possible parameters:

java psoft.hsp.tools.PkgBuilder --help

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 installed and uninstalled on other H-Sphere's.