×
Namespaces

Variants
Actions
Revision as of 18:52, 25 November 2009 by dcrocha (Talk | contribs)

Installing Java apps and WRT widgets using sis files

From Nokia Developer Wiki
Jump to: navigation, search


Contents

Introduction

This article introduces the Software Installer package. It allows developers to install their Java ME, Web Runtime (WRT), Symbian S60 and Flash Lite (packaged as .sis) applications and dependencies using a single .sis file. A Carbide.c++ project is provided, and developers will customize them for their own installation needs.

Benefits

Multiple applications can be installed at a single shot, along with dependent components such as: image files, music, videos, configuration files, native (C++) components and so on. For example, WRT Widgets can be installed along with the APIBridge_Web_Runtime_API if they depend on it, making the user experience a lot better than when installing multiple components separately.

Prerequisites

Update: If you want to test a ready-made example to see what the user experience looks like, please download this package, unzip it and install the signed .sisx file to your phone:

Software Installer.sis

In order to use this package to customize your installations, you need to have installed:

Testing this package

First thing is to do a test build to make sure the environment is set up correctly:

  1. Install the SDKs and the Extensions Plug-in Pack listed above, if you still haven't done so.
  2. Extract the attached SoftwareInstaller.zip package anywhere in your computer. In this example, the folder generated is C:\temp\SoftwareInstaller
  3. Open a Windows Command Prompt, and cd into the project folder.
  4. Cd into group folder and type
    bldmake bldfiles
    to create the build files.
  5. Type
    abld build gcce
    . This will build the package for the GCCE target, meant to be used in real hardware.
  6. Cd into ..\sis folder.
  7. Type
    makesis SoftwareInstaller_EKA2.pkg SoftwareInstaller.sis
    . This will generate an unsigned .sis file. You will now need to sign the file so it works on your phone.


If you do not own a Developer certificate:

  1. Go to Symbian Signed web site and choose the Open Signed Online option. Fill out the IMEI, E-mail and Application fields. You will receive a confirmation on your e-mail.
  2. Check your e-mail for the confirmation message. Click on the link provided.
  3. Refresh your e-mail a couple of minutes later; you will have a link to download the signed SoftwareInstaller.sis file.


If you have a Developer certificate:

  1. Sign the SoftwareInstaller.sis file with your certificate and key.


Now you can install the signed SoftwareInstaller.sis file on your phone. The S60 installer will prompt you about the file being a development-version application, then will install itself. A couple of seconds after the installation of the main package is completed, you will be prompted for the installation of the STEW widget (example from Forum Nokia Developer's Library). After the installation of STEW is finished, the MyTestApp Java MIDlet will be installed.

After these two applications are installed, you can use them from the Application folder and check they work correctly. Both have been installed by a single .sis file. Here is a visual summary of the installation experience on the phone:

Next we'll see how you can customize this package to suit your application installation needs.

Customizing the installation package

The first thing you need to know is that this is not simply a .sis file. There's a small executable ("SoftwareInstaller.exe") that does the job of installing all components whose files are in the data folder and whose names are in the data\WidgetInstFile file. This has implications in what you, the developer, must do to customize this package.

At a first glance, it would be easy to add your component to the data folder and add its name to WidgetInstFile. However, this is not an ordinary .sis file, but an actual Symbian C++ application. In the Symbian environment, all applications must have a valid, unique ID (UID) and a unique executable file name, to avoid collision with other applications installed on the phone. Therefore you need to implement those changes before using this package, in order to install your applications in a production environment. To achieve this, you need to:

  1. Go to the Symbian Signed website, and get a valid UID for your application. It will be in the format 0x12345678. Please notice that the example package comes with a UID of the test range (0xExxxxxxx) which must not be used for production applications. You will need a valid one or you will have problems with application collision and it will be impossible to sign them.
  2. After you have the valid UID, open the SoftwareInstaller.mmp (group folder) file and change the line
    UID			 0 0xEDC63187
    to
    UID			 0 0x2xxxxxxx
    where 0x2xxxxxxx is the UID you've received from Symbian Signed. Modify the TARGET parameter to something like MyApplicationName_0x2xxxxxxx.exe, again where 0x2xxxxxxx is your UID. This will ensure the file name for your executable is unique in the phone. Save and close the file.
  3. Open the ..\sis\SoftwareInstaller_EKA2.pkg file. Look for the line:
    #{"SoftwareInstaller EXE"},(0xEDC63187),1,0,0
    and change it to
    #{"MyApplicationNAme"},(0x2xxxxxxx),1,0,0
    where MyApplicationName is, unsurprisingly, your application's name, and 0x2xxxxxxx is the same UID you used in the .mmp file. You can also change the Vendor section to reflect your company's name.
  4. Look for the line
    "\S60\devices\S60_5th_Edition_SDK_v1.0\Epoc32\release\gcce\urel\SoftwareInstaller.exe" - "!:\sys\bin\SoftwareInstaller.exe", FR, RI
    and change the name of SoftwareInstaller.exe in both sides to the same name you've defined in step 2 of this section ("MyApplicationName_0x2xxxxxxx.exe").
  5. Copy your applications to the data folder. In this example, our apps are stew.wgz and MyTestApp, which is a Java ME application consisting of the JAD and JAR files. Make sure you copy ALL the installation files to the data folder.
  6. Edit ..\data\WidgetInstFile (Notepad or Wordpad) and add the file names of the applications you want to install. In this example, we are adding stew.wgz and MyTestApp.jad. Please note that, for Java ME apps, you can enter either the JAD or the JAR file name, but not both. If you are using JAD properties, or your MIDlet is signed, you must use the JAD file name, otherwise your MIDlet will not be installed correctly. Also note that WidgetInstFile is not an ASCII file. Therefore you must use either Wordpad or Notepad (on Windows) and save the file as Unicode, not as regular text. Save and close the file.
  7. Now you need to tell the package creator to add your files to the final .sis package. Open ..\sis\SoftwareInstaller_EKA2.pkg file and look for the lines:
    ;Files to be installed	
    "..\data\stew.wgz" - "d:\WidgetInstaller\stew.wgz"
    "..\data\MyTestApp.jad" - "d:\WidgetInstaller\MyTestApp.jad"
    "..\data\MyTestApp.jar" - "d:\WidgetInstaller\MyTestApp.jar"
    These directives will copy files stew.wgz, MyTestApp.jad and MyTestApp.jar from your HD disk to the .sis file. If you fail to add these lines, nothing will be installed. Add your files here as needed. On the left side of the hyphen ("-") you add the path to the file on your disk; on the right side you add the path on your phone's disk. Note that the latter must always be "d:\WidgetInstaller\", otherwise the installer app won't find it.
  8. Now you are ready to rebuild the package. Change to the group" folder, type
    abld reallyclean gcce
    then
    abld build gcce
  9. Create the package using makesis as described in the previous section.
  10. Sign the package using either Symbian Signed Open Signed Online or your developer certificate.
  11. You are then ready to test the package on your phone.
  12. ATTENTION: At this point you may receive an "Update error" when installing your newly-created package on the phone. This happens because you've changed the UID of the package but kept some of the files that the old package (the one installed on the phone) was also using. To solve this error, you can either remove the previous package prior to installing the new one, or remove conflicting files, which will most likely be the ones from the data folder. This will not happen in production since it's very unlikely that you are installing exactly the same file as any other package in the world with a different UID.

Deploying the installation package

In order to deploy the installation package to all your users, you need to sign the application with a real certificate. For that you will need to go to Symbian Signed and sign the application. You can use Express Signed since the app doesn't require any Manufacturer-granted capabilities. For an overview of the Symbian Signed process for production applications Step by Step instructions to Express signing.

Questions / feedback

Questions or feedback can be posted as comments to this page.

Daniel Rocha
Forum Nokia

--dcrocha 23:23, 24 November 2009 (UTC)

299 page views in the last 30 days.

Was this page helpful?

Your feedback about this content is important. Let us know what you think.

 

Thank you!

We appreciate your feedback.

×