Creating RPM packages for Ice
=============================

This file describes how to create source and binary RPMs for Ice as a
regular (non-root) user on your Linux system.


Table of Contents
-----------------

  1. The .rpmmacros file
  2. The RPM package directory
  3. Ice Source RPM
  4. Ice Binary RPMs
     - SuSE Mono Notes
  5. Applying a Patch


======================================================================
1. The .rpmmacros file
======================================================================

Create a file named .rpmmacros in your home directory similar to the
following:

%_signature gpg

%_gpg_path /home/rpmbuilder/.gnupg

%_gpg_name ZeroC, Inc. (release key) <support@zeroc.com>

%_gpgbin /usr/bin/gpg

%vendor ZeroC, Inc.

%dist .sles11

The gpg settings are only needed if you want to sign your RPMs.
Replace "/home/rpmbuilder" with a path name that is appropriate for
your system.

The value for %dist should be ".sles11" or ".el6".


======================================================================
2. The RPM package build directory
======================================================================

The RPM package build directory is /usr/src/packages on SLES. For 
RHEL 6, create and use ~/rpmbuild. In this document we refer to the 
package directory symbolically as <rpm-package>.

You may need to adjust the permissions on all subdirectories of this
directory to be able to create RPMs as a non-root user.


======================================================================
3. Ice Source RPM
======================================================================

You will need three files in order to create a source RPM for Ice:

 - the ice.spec file (the RPM specification file)
 - the Ice-@ver@.tar.gz file (the main Ice source distribution)
 - the Ice-rpmbuild-@ver@.tar.gz (additional files for the RPM
   distribution)

These files can be extracted from an existing Ice source RPM by
installing it:

$ rpm -i ice-@ver@-1.src.rpm

You can find the ice.spec file in the <rpm-package>/SPECS directory,
while the .tar.gz files are in the <rpm-package>/SOURCES directory.

If you prefer not to install the Ice source RPM, you can extract the
contents of the file using the following command:

$ rpm2cpio ice-@ver@-1.src.rpm | cpio -idmv

The ice.spec file defines a number of build requirements that must be
installed on your system in order to build the source RPM. These
dependencies are listed below:

 - db53
 - db53-devel
 - db53-java
 - mcpp-devel
 - openssl-devel
 - jpackage-utils
 - python-devel
 - bzip2-devel (RHEL)
 - expat-devel (RHEL)
 - php-devel (RHEL)
 - php5-devel (SLES)
 - mono-core (SLES)
 - mono-devel (SLES)

The db53* and mcpp-devel RPMs are provided by ZeroC. You can determine
the version requirements for all other prerequisites by examining the
BuildRequires directives in the ice.spec file.

Follow these steps to create the Ice source RPM:

 1. Copy all desired source files and patches into the directory
    <rpm-package>/SOURCES

 2. Comment out the %dist setting in ~/.rpmmacros

 3. Run rpmbuild:

    $ rpmbuild -bs --sign ice.spec

    Omit the --sign option if you do not want to sign the source RPM,
    or if you do not have a GnuPG key prepared.

The source RPM is created in <rpm-package>/SRPMS.


======================================================================
4. Ice Binary RPMs
======================================================================

To create binary RPMs for Ice, you must first install the source RPM:

$ rpm -i ice-@ver@-1.src.rpm

If you have not already done so, install the RPM prerequisites listed
in step 3 above. The following additional steps are also necessary:

 - Install the JGoodies Looks 2.5.2 JAR file as

   /usr/share/java/jgoodies-looks-2.5.2.jar

 - Install the JGoodies Forms 1.6.0 JAR file as

   /usr/share/java/jgoodies-forms-1.6.0.jar

 - Install the JGoodies Common 1.4.0 JAR file as

   /usr/share/java/jgoodies-common-1.4.0.jar

 - Install the ProGuard 4.8 JAR file as

   /usr/share/java/proguard.jar

 - Install the Java Development Kit version 1.7 and verify that the
   'javac' command is present in your PATH

   Note: JDK 1.7 with JavaFX is necessary for compiling the IceGrid
   Admin GUI client. Java7 is required to run this client, but the
   other Ice JAR files (Ice.jar, Glacier2.jar, etc.) are compiled to
   be compatible with Java6.

 - Install Apache Ant 1.7 or later and verify that the 'ant'
   command is present in your PATH, such as by running

   $ ant -version

 - Enable the %dist setting in ~/.rpmmacros (if you disabled it when
   building the source RPM)

You can run the 'find-jar' program to verify that the JAR files are
installed correctly. For example:

$ find-jar jgoodies-looks-2.5.2.jar
$ find-jar jgoodies-forms-1.6.0.jar
$ find-jar jgoodies-common-1.4.0.jar
$ find-jar proguard.jar

Finally, build the RPMs as a non-root user.

On Red Hat Enterprise Linux:

$ cd <rpm-package>/SPECS
$ rpmbuild -bb --sign --target i386,noarch ice.spec

On SuSE Linux Enterprise Server (also see Mono Notes below):

$ cd <rpm-package>/SPECS
$ rpmbuild -bb --sign --target i586,noarch ice.spec

Omit the --sign option if you do not want to sign the RPMs, or if you
do not have a GnuPG key setup.

On an x86_64 system, omit the --target option to build only x86_64
RPMs.

Upon completion, the binary RPMs can be found in <rpm-package>/RPMS.


SuSE Mono Notes
---------------

By default, the Mono assemblies are strong-name signed using the Ice
development key included in the source distribution. If you would like
to strong-name sign the assemblies using your own key, set the KEYFILE
environment variable with the path name of your key file prior to
building the binary RPMs.

The Mono-related RPMs created during this process are shown below:

  ice-mono-@ver@-1.sles11.noarch.rpm
  ice-mono-devel-@ver@-1.sles11.<arch>.rpm

The ice-mono-devel RPM is arch-specific because it contains the
executable for the Slice-to-C# compiler.

Note that building the binary RPMs also generates an arch-specific
ice-mono package:

  ice-mono-@ver@-1.sles11.<arch>.rpm

This file is an artifact of the build process and should be removed.


======================================================================
5. Applying a Patch
======================================================================

Follow these steps to create a new set of RPMs that incorporates
one or more source patches:

- Install the Ice source RPM

- Edit ice.spec:

  - Modify the Release setting, for example:

    # Second build by ACME, Inc.:
    Release: 2acme%{?dist}

  - List the patch (or patches) after Source1, for example:

    Source0: Ice-%{version}.tar.gz
    Source1: Ice-rpmbuild-%{version}.tar.gz
    Patch1: Ice-%{version}-patch1.patch
    Patch2: Ice-%{version}-patch2.patch

  - Apply the patch(es) in the %prep section. Continuing our example
    with two patches:

    %prep
    %if %{buildall}
    %setup -n Ice-%{version} -q
    %setup -q -n Ice-rpmbuild-%{version} -T -b 1
    %patch1 -p0 -b .orig1
    %patch2 -p0 -b .orig2
    %endif

- Copy the patch(es) to <rpm-package>/SOURCES

- Finally, create the source and binary RPMs as described in the
  sections above.
