Tuesday, May 25, 2010

Create Shortcut Specification for IzPack

In IzPack software, operating system specific shortcut specification must be provided along with the common configuration specification to support the shortcuts. This is caused by the OS specific nature of shortcuts’ operation. In other, words today we will discuss how to write the shortcutSpec.xml that is required to accommodate shortcuts in the Windows environment.
Platform: Windows
File Name: shortcutSpec.xml
The root element of this xml document is <shortcuts>.This xml document has 3 other important sub elements under this tag. they are <skipIfNotSupported/>, <programGroup/> and <defaultCurrentUser/>. <skipIfNotSupported/> allows the panel to be silent on a non-supporting system. <defaultCurrentUser/> allows the “current user” to be the default selection for the panel. If this element is not present, the default selection is “all users”. <programGroup/> allows to specify the name of the menu under which shortcuts to be specified.
<skipIfNotSupported/>
<programGroup defaultName="Jefe" location="applications"/>
After these 3 elements, comes the most important functionality providers of the specification. <shortcut> tags each per shortcut, will provides the OS specific details to the installer to create the shortcuts.
Given below is the code for a shortcut to execute a startup.bat of a Tomcat bundle. This will create a desktop shortcut specified by desktop="yes" attribute and a shortcut in the program group specified by programGroup="yes" attribute, under the name Jefe which is defined in <programGroup> tag. In this shortcut configuration data name of the shortcut appears as Jefe – Startup and the required bat file to execute is located in the path given in the target attribute. While name and target attributes are essential to be specified in a short cut, all other attributes are optional. workingDirectory specify the folder in which the startup.bat is located.  iconFile will specify the location and the name of the icon to use for this shortcut, which will appear in both desktop and the program group. description attribute will give a brief description about the shortcut when it is been requested. initialState=”noShow” will hide command prompt opening when bat files are requested to execute. Since I need to monitor the command prompt information at startup of the Tomcat I used the initialState as “normal”. Even though all the attributes expect name and the target are considered optional, programGroup, desktop, startMenu and startup are considered as semi-optional attributes. There value is either yes or no. Any other value other than these two are interpreted as no. createForPack another important child element of shortcut. It will specify under which pack this shortcut is installed. If this pack is not selected while installation, the respective shortcut is omitted automatically.
<shortcut
        name="Jefe - Startup"
        target="$INSTALL_PATH\core\liferay-portal-5.2.3\tomcat-6.0.18\bin\startup.bat"
        commandLine=""
        workingDirectory="$INSTALL_PATH\core\liferay-portal-5.2.3\tomcat-6.0.18\bin"
        description="Jefe Server Startup"
        iconFile="$INSTALL_PATH\images\startup.ico"
        iconIndex="0"
        initialState="normal"
        programGroup="yes"
        desktop="yes"
        applications="no"
        startMenu="no"
        startup="no">

       <createForPack name="core"/>
</shortcut>
Similarly I have created another shortcut to execute the shutdown.bat in the same folder to shutdown the Tomcat server. I’ll not discuss this since it is just a replacement for the word startup by shutdown. Now let’s take a look on how to create a shortcut to execute the uninstall.jar created by the IzPack installer for the Jefe installer.
<shortcut
        name="Jefe - Uninstaller"
        target="$INSTALL_PATH\uninstaller\uninstall.bat"
        commandLine=""
        workingDirectory="$INSTALL_PATH\uninstaller"
        description="Jefe Server will be completely Uninstalled"
        iconFile="$INSTALL_PATH\images\uninstall.ico"
        iconIndex="0"
        initialState="noShow"
        programGroup="yes"
        desktop="no"
        applications="no"
        startMenu="no"
        startup="no">

       <createForPack name="core"/>
</shortcut>
The difference in this shortcut to the one discussed earlier is that we are using a a bat file given below to execute the jar file and has configured following 2 attributes differently to how they were configured previously. initialState=”noShow” and desktop=”no”. The bat file I’m using for this operation is as given bellow,
@Echo Uninstalling…
java –jar uninstall.jar
@Echo Successfully Uninstalled
The full description of the different attributes are given in the IzPack manual under Desktop Shortcuts section. The same shortcuts created for the Unix base system in also given as an example in the IzPack manual under the sub section A simple shortcut specification for Unix under the Section Desktop Shortcuts.

Thursday, May 6, 2010

Installing Ant and Maven

Installing Ant

Installing Ant is very very simple. Following are the steps for that,
Step 1: Download the latest ant binary from http://ant.apache.org/bindownload.cgi
Step 2: Extract it to folder in your machine. In my case C:\ant
Step 3: Set the following environmental variables in your machine
  • JAVA_HOME : path/to/your/jdk (eg: C:\Java)
  • ANT_HOME : path to folder where you extracted your ant copy (eg: C:\ant\apache-ant-1.8.0)
  • PATH : %PATH%;%ANT_HOME%\bin
Step 4: To check whether the installation was successful, in command prompt type “ant” if it displays “build failed” then ant installation is successfully installed to your machine. But if it says it can not identify the command ant then there is a problem in the installation.

Installing Maven 2

Installing Maven is so simple, and is very much similar to the ant installation process. Given below is the maven installation process,
Step 1: Download the latest maven binary from http://maven.apache.org/download.html
Step 2: Extract it to folder in your machine. In my case C:\maven
Step 3: Set the following environmental variables in your machine
  • JAVA_HOME : path/to/your/jdk (eg: C:\Java)
  • M2_HOME : path to folder where you extracted your maven copy (eg: C:\maven\apache-maven-2.2.1)
  • Set the following user variables in your machine (just above the environmental variables). M2 : %M2_HOME%\bin
  • PATH : %PATH%;%JAVA_HOME%\bin;%M2%
Step 4: To check whether the installation was successful, in command prompt type “mvn --version” if it displays the version information then the maven installation is successfully installed in your machine. But if it says it can not identify the command mvn then there is a problem in the installation.

Monday, May 3, 2010

Write an installer with IzPack

Features and Drawbacks of Using IzPack

Because of the following reasons I chose IzPack to create the installer for my application, from all other free and open source installer software. The reasons which helped me to make my decision are as follows,
  • IzPack is Open Source
  • It has attractive GUI
  • Great Customizability
  • It is a Cross-Platform Installer
  • Automatic Uninstaller Creation
The drawback of using IzPack is, it doesn’t contain enough documentation or working examples for a beginner to use it and get the job done easily.
Because of this reason I thought of discussing and guiding you on how to use IzPack to create an Installer today in this blog.

How IzPack Installer Operates

All what we have to do to make the installer is write an xml file stating all the necessary configuration information and compile it using the compiler provided by the IzPack. Then according to our xml, an installer file named install.jar will be created by the IzPack. It will wrap all the files and folder structure from the end user. Then a separate application should be used to convert this jar file to a windows executable or a Mac application. For this example I’m using a software named Launch4j for this purpose.
Download and Install IzPack latest version from: http://izpack.org/
Download and Install Launch4j latest version from: http://launch4j.sourceforge.net/

Creating an install.xml file

This xml file has a root element as “installation” which has an attribute named “version”. i.e. all other tags of the xml file should be placed somewhere inside the main tag of <installation version=”1.0></installation>
The first configuration data to appear inside these installation tag is the data of information section.
<info>
        <appname>Jefe</appname>
        <appversion>1.0</appversion>
        <authors>
            <author name="Ms. K.M.L. Sureshika" email=""/>
            <author name="Ms. A.P. Pathirage" email=""/>
            <author name="Ms. S.P. Mendis" email=""/>
            <author name="Mr. S. Nirathan" email=""/>
        </authors>
        <javaversion>1.5</javaversion>
        <requiresjdk>no</requiresjdk>
        <url>
http://www.jefe-sdwms.com/</url>
        <uninstaller name="uninstall.jar" path="${INSTALL_PATH}/uninstaller" write="yes"/>
        <summarylogfilepath>$INSTALL_PATH/InstallationSummary.htm</summarylogfilepath>
        <writeinstallationinformation>no</writeinstallationinformation>
</info>

Information in the appname, appversion,authors and url tags will be used to display on the HelloPanel. javaversion will be used to specify the minimum java version required for your application to work. requirejdk has the values yes and no which will enforce the user to install a java jdk of minimum java version specified or above. uninstaller tag will allow you to specify the location where the uninstaller should be created and its name. summarylogfilepath will be used to store a html file of installation summary after successful installation. writeinstallainformation has values yes or no. If yes is given it gives the user the ability to generate an installation script for further installations.
The next section in my install.xml is “guiprefs”. It will allow me to change the appearance of the ultimate installer of my application.
<guiprefs width="600" height="480" resizable="no">
        <modifier key="layoutAnchor" value="CENTER"/>
        <modifier key="useHeadingPanel" value="yes"/>
        <modifier key="useHeadingForSummary" value="yes"/>
        <modifier key="headingImageOnLeft" value="yes"/>
        <modifier key="headingLineCount" value="2"/>
        <modifier key="headingFontSize" value="1.5"/>
        <modifier key="headingBackgroundColor" value="0x00ffffff"/>
        <modifier key="headingPanelCounter" value="text"/>
        <modifier key="headingPanelCounterPos" value="inHeading"/>
</guiprefs>

Here I’m specifying the width and the height of the gui and restricting it from resizing which will be problematic since I’m using two images in the installer. I’m also placing a layout anchor for the gui and instructing it that I’m using a header panel and heading image on the left.
According to the IzPack manual, you can specify various new variables other than the default variables as $INSTALL_PATH and $JAVA_HOME. In my code I have used the following variable to use in the shortcut panel.
<variables>
        <variable name="DesktopShortcutCheckboxEnabled" value="true"/>
</variables>

We can also specify many languages for the installer to operates. For my installer I only specified English. Because there aren’t any choice the initial panel for language selection is not appearing in my installer. All the language codes needed for configuring this option is given in the IzPack manual clearly
<locale>
    <langpack iso3="eng"/>
</locale>

Next comes an important section in the install.xml. Resources tag will contain information and location of all the additional files in the installation other than the install.xml itself.
<resources>
        <res id="shortcutSpec.xml" src="shortcutSpec.xml"/>
        <res id="HTMLInfoPanel.readme" src="Readme.html"/>
        <res id="HTMLLicencePanel.licence" src="Licence.html"/>
        <res id="Heading.image" src="images/heading-image.png"/>
       <res id="Installer.image" src="images/side-image.png"/>
</resources>

In here, shortcutSpec.xml file, Readme.html file and Licence.html file are located on the root of the installation folder. But header image and side image are located inside a folder named images which is located on the root. Likewise you can specify any resource used for the installation process, located anywhere with respect to the installation folder. For all the resources you also need to give a unique id which can be used later for identifying the resource. And remember to include all the files you have mentioned under resources with exact names and locations unless you need half a dozen compilation errors.
Panel section will be used to specify the different panels you need to show in your installation and their order of appearance. All different panels are given in the manual. These are what I’m using for my installation in the order they required to appear.
<panels>
        <panel classname="HelloPanel"/>
        <panel classname="HTMLInfoPanel" id="readme"/>
        <panel classname="HTMLLicencePanel" id="licence"/>
        <panel classname="TargetPanel"/>
        <panel classname="TreePacksPanel"/>
        <panel classname="SummaryPanel"/>
        <panel classname="InstallPanel"/>
        <panel classname="ShortcutPanel"/>
        <panel classname="FinishPanel"/>
</panels>

For your information I’ll include GUIs of the above panels in the above order.










Then next most important section of our install.xml is the packs section, which define what need to be installed, to where and how. This implements the core of the installation process. Since the code of the packs section of my installer is so lengthy I will include the code of one pack only.
<packs>
        <pack name="core" required="yes">
            <description>This will include the necessary processing of Liferay framework and other core files used in the jefe solution.</description>
            <file src="Readme.html" targetdir="$INSTALL_PATH"/>
            <file src="Licence.html" targetdir="$INSTALL_PATH"/>
            <fileset dir="images" targetdir="$INSTALL_PATH\images">
                <include name="**"/>
            </fileset>
            <file src="liferay-portal-tomcat-6.0-5.2.3.zip" targetdir="$INSTALL_PATH\core" unpack="true"/>
            <executable targetfile="$INSTALL_PATH/liferay-portal-5.2.3/tomcat-6.0.18/bin/startup.bat" stage="never" />
            <executable targetfile="$INSTALL_PATH/liferay-portal-5.2.3/tomcat-6.0.18/bin/shutdown.bat" stage="never" />   
    </pack>
    …
    …
</packs>

Installation process is divided into many parts according to packs. As you can see in the 5th image since pack give in the above code is set as “required=yes” user does not get the opportunity to select or deselect it according to his requirements. Hence this is a good option to include all the required and essential features of the application under this pack. So I have used this pack named core to copy the Readme file, Licence file and images folder to the root of the installation location and i have also unzipped the zip file named “liferay-portal-tomcat-6.0-5.2.3.zip” to the folder “core” in the root. After unzipping I’m specifying 2 runnable bat file locations in it which I need to run later. But here I’m asking the installer not to run these files by specifying the stage as never. The other alternatives to the stage are postinstall and uninstall which will be called soon after installation and at the time of uninstalling respectively. Description will appear when you click on a pack.
You can also list packs that appears inside some other packs as in image 5. For this, you can code your packs as follows.
<pack name="stack" required="no" preselect="yes">
            <description>This is custom portlet stack provided by the jefe solution.</description>
</pack>

            <pack name="Document Repository" required="no" parent="stack">
                  <description>This will include all the document repository plugins to the core.</description>
            </pack>

Parent pack needs not contain any special tags for this functionality to implement. But the child pack need to have an attribute named parent with the name of its parent pack as the value. When compared to previous pack code this code has some more changes. I have stated the attribute “required=no” giving the user the flexibility to choice and added a new attribute “preselect=yes” to persuade the user to install this pack too.
I  have also used an listener for windows users, to catch the summary log of the installer. The code for the following segment represent the inclusion of the above listener.
<listeners>
      <listener installer="SummaryLoggerInstallerListener">
          <os family="windows"/>
      </listener>
</listeners>

Native packs are also required to include in your installation xml file to implement the installer functionality. The code for the above native pack is included below.
<native type="izpack" name="ShellLink.dll"/>
<native type="izpack" name="ShellLink_x64.dll"/>
<native type="3rdparty" name="COIOSHelper.dll" stage="both">
    <os family="windows"/>
</native>

The code of the completed install.xml file is attached here: install.xml
The code of the completed shortcutSpec.xml file is attached here: shortcutSpec.xml
 

Creating an install.jar out of install.xml

install.xml file alone will not lead you to any where. So let’s make a cross-platform install.jar file that will build your actual installer. For this,

  1. Create a new folder and include all the resource files to it in the exact location mentioned in the resources tag.

  2. Now save the install.xml file the root of the same folder.

  3. Go to the IzPack installation folder and then to IzPack bin using command prompt with Administration privileges and type the following command
    E:\IzPack\bin>compile E:\jefeInst\install.xml -b E:\jefeInst
This will compile your install.xml file to a install.jar file. For this command after the key word “compile” you are required to give the path of the install.xml file then –b and then the path to which the install.jar file need to be saved.
After creating the install.jar file, you can once again navigate to the location where you saved it in the command prompt and execute the following command to launch your installer as how you launch any other .jar file.
E:\jefeInst>java -jar install.jar

Creating install.exe out of install.jar

Start the Launch4j and create an new project in it.
  1. In the Basic tab input the output file name and location where you need your executable file to be saved in “*Output file”.
  2. In the Basic tab again under “*Jar” browse and give the install.jar file you just created using IzPack.
  3. In the Basic tab you can also give a custom icon for the executable installer you are going to create.
  4. In the JRE tab under “Min JRE Version” include the minimum JRE version needed for your application to work.
  5. Now save the file and build the wrapper from the menu.
You are now having a complete single file windows executable for your application!

How to configure a SVN repository

Platform: Windows 7 (64bit) OS
SVN Client: TortoiseSVN
These few steps will guide you on how to install your own basic SVN repository on a windows machine using the client, TortoiseSVN.

Step 1:

Go to TortoiseSVN download page at http://tortoisesvn.net/ and download the latest version of the application. In my case it was TortoiseSVN-1.8.4.24972-x64-svn-1.8.5.msi

Step 2:

Double click the installer and follow the wizard to set up the TortoiseSVN client application. This application can be installed to any location in the machine. For this example I’ll install it to E:\svn At the end of installation process restart will be requested. After rebooting the machine go for the Step 3.

Step 3:

Now go to the location where you installed the application (i.e. E:\svn) and create a new folder named ‘repository’.

Step 4:

Right click on this new folder and choose ‘TortoiseSVN’ –> ‘Create repository here’. Now your SVN repository is successfully created.

Step 5:

To upload your first set of files to the repository, in my case first folder with some documentation right click on the desktop and select ‘TortoiseSVN’ –> ‘Repo-browser’.
Then give the path to the newly created repository as file://path/to/the/repository
This is a view of your SVN repository created at the given location. Now right click on the middle and select Add folder as below and browse the folder you need to upload to the repository and then proceed with ok.
Now you can see your first set of files in the repository successfully.

Step 6:

For any further uploads to the repository you can proceed with right clicking the folder you need to upload and select ‘TortoiseSVN’ –> ‘Import’ and to download a working copy from the SVN, you can proceed by creating a new folder and then right clicking to select ‘SVN checkout…’. After modifying a checked out copy you can commit it back to the repository by right clicking and selecting ‘commit…’.

Step 7:

Until now there aren’t any users created to restrict the access to the repository. You can manually set the users by editing the ‘passwd’ file at following location ‘E:\svn\repository\conf\’ (w.r.t. this installation example).
When this file is opened in a text editor you can see the following lines.
[users]
# harry = harryssecret
# sally = sallyssecret
According to this, a user can be created as ‘harry’ with the login password as ‘harryssecret’ by un-commenting the line by removing the ‘#’ sign in the beginning of it and saving the file. Likewise any number of users can be created to use the repository.