NAME

installwidgets.pl - A script for generating all the files needed to install Widgets


SYNOPSIS

installwidgets.pl [-h] [-ver] [-v] [-debug] [-e <dir>] [-l <lang_code|lproj.xml>] config.ini

 Options:
   -help|h                        Show this help
   -version|ver                   Show version number
   -verbose|v                     Show verbose output
   -debug                         Show debug output
   -epocroot|e                    Override value of EPOCROOT
   -localization|l                lproj_dir

A script for generating all the files needed to preinstall Widgets.

 Example:
   perl installwidgets.pl -l fr config.ini       Install widgets listed in config.ini using French localization
 Author:
   peter.harper@sosco.com


DESCRIPTION

This tool can be used to pre-generate all the files needed to install Widgets. The tool and its dependencies can be placed anywhere on your PATH. It generates the results in the epoc32 folder - in the appropriate locations for the emulator. It finds the epoc32 folder using the EPOCROOT environment variable which can be overridden via the -e command line option.

CONFIG FILE

The preferred way to run the tool is via a configuration INI file. You can list the widgets to install on each drive. You can specify the exact location of the Widget, otherwise it will try and find the Widget via EPOCROOT.

You can specify whether a widget is intended for the homescreen by adding the text [HomeScreen] after the filename This will set the BlanketPermissionGranted attribute in the registry. Widgets intended for the homescreen must have the MiniViewEnabled attribute set in its PLIST file otherwise an error is generated.

    # Widgets to be pre-installed for the ROM
    [drive-z]
    \somepath\foo.wgz
    \somepath\bar.wgz
    # Widgets for the internal disk
    [drive-c]
    \somepath\widget1.wdgt.zip [HomeScreen]
    # Widgets for the removable disk
    [drive-e]
    \somepath\widget2.wdgt.zip
    # Commands to run at the end
    [run-commands]
    dostuff.pl
    domorestuff.exe

DEPENDENCIES

The tool has some dependencies which must exist for it to work.

  1. png2mbm.pl - A script to generate an MBM file from a PNG

  2. WidgetRegFiles.exe - an EXE which can generate Symbian REG and LOC files for registering non-native Widget apps. This tool is built with "SymPort" a native tools port of basic Symbian OS services.

  3. 7z/unzip - For extracting files from the Widget archive. 7Zip will be used in preference to unzip if it's found on your path because it handles Unicode a better.

  4. GD.pm - Perl support for the GD graphics library for PNG support, see http://www.libgd.org .

INSTALLING GD

You can install GD automatically with a simple command - however the command you need to use differs depending on the version of Perl you have installed. At the time of writing Symbian requires Perl version 5.6 - although in my experience Perl 5.8 works okay. To find out which version of Perl you have type "perl -v" on the command line.

To install the GD library:

WIDGET INSTALL PROCESS

Here's a detailed breakdown of what the script does.

  1. It gets the lists of Widgets from the config.ini file passed on the command line. This process is repeated for all Widgets and all drives listed in the config file.

  2. Any existing Widgets listed in "private\10282f06\WidgetEntryStore.xml" are deleted from the epoc32 tree. This ensures that there are no problems when testing Widgets in the emulator.

  3. All the compressed files in the Widget are extracted to a temporary folder.

  4. The details for the Widget are loaded from its "Info.plist" file.

  5. A UID is chosen for the widget. This differs depending on whether installation is for an internal drive (z: or c:) or an external drive (e: etc).

  6. A Symbian MBM file is generated from the "Icon.png" file supplied by the Widgets. Three different sized icons are generated "88x88", "32x32" and "24x24". The MBM file is placed in "private/10003a3f/import/apps/NonNative/Resource/[<UID>].mbm".

  7. "WidgetRegFiles.exe" is executed to generate REG and LOC resource files used to register the Widget as an app in Symbian OS. These files are placed in "private/10003a3f/import/apps/NonNative/Resource".

  8. All the widgets files are copied to a folder under "private\10282822". The Widget's bundle identifier is used to create a unique folder under here for the Widget.

  9. The Widget registry is generated in "private\10282f06\WidgetEntryStore.xml"

  10. If Widgets are being preinstalled for ROM an IBY file is created in "epoc32\rom\include\preinstalledwidgets.iby". A separate IBY file is generated for the localised parts of a Widget "epoc32\rom\include\preinstalledwidgets_rsc.iby". Separate IBY files (per drive) are generated for Widgets preinstalled to UDA, e.g. preinstalledwidgets_driveC.iby and preinstalledwidgets_driveC_rsc.iby. These IBY files can be used to add all the Widgets to ROM, ROFS or UDA.

INSTALLING ON HARDWARE USING iMaker

  1. Create the following folder structure at the root level.

    X:\variants\content
  2. Copy the files specified in the generated ibys (preinstalledwidgets_driveC.iby and preinstalledwidgets_driveC_rsc.iby) to X:\variants\content. Preserve the dir structure. (Note, this step will be automated in the future)

    For example if you want the following file on UDA (User Disk Area, C drive on phone) at the following location C:\private\10282f06\WidgetEntryStore.xml

    Drop the file under X:\variants\content\private\10282f06\WidgetEntryStore.xml

  3. Run the foll command to generate UDA

    Gadget: X:\epoc32\tools>imaker -f /epoc32/rom/s60_makefiles/image_conf_sp_rnd_gadget.mk VARIANT_DIR=/variants variantuda

    Tube: Y:\epoc32\tools>imaker -f /epoc32/rom/config/ncp52/tube/image_conf_tube_ui.mk VARIANT_DIR=/variants variantuda

  4. Flash the fpsx file generated under X:\epoc32\rombuild\gadget\uda for Gadget and Y:\epoc32\rombuild\tube\uda for Tube to your device.

    Note: More info on iMaker tool at: http://configurationtools.nmp.nokia.com/imaker/wiki/iMakerUserGuide

LOCALISATION

Widget handles localization by providing localized resources in various language project directories(lproj_dir), one level deep than the root directory. In order to specify a language variant for pre-installing widget, you need to provide the language project directory name, e.g. 'en' for english, 'fr' for French.

A list of Nokia supported languages can be found in Widget_lproj.xml or at http://wiki.forum.nokia.com/index.php/Web_Runtime_localisation_support. If the widget does not provide the localized resource for the variant you specified, the default resources in widget's home directory will be used instead.

NOTES

  1. The location of the private folder is in the appropriate place for the files to appear in the emulator. This is different depending on the intended destination drive (see -dd command line option) for the Widget. e.g. "epoc32/release/winscw/udeb/z/", "epoc32/winscw/c" or "epoc32/winscw/e"

  2. Files are extracted to epoc32 on the current drive relative to the EPOCROOT environment variable or the value given for -epocroot (-e) on the command line.

  3. A different IBY file is generated for each drive.

    There are separate resource files for localised resources e.g. preinstalledwidgets_rsc.iby.