raptor/notes/sis_create_and_sign.txt

Overview
========
Raptor now ships a createsis FLM to support .sis generation and signing.

This FLM is available as part of the "utility" grouping and runs as part
of the main, .default, section of the build.

General Syntax
==============
bld.inf

    PRJ_EXTENSIONS (or PRJ_TESTEXTENSIONS)
    
    START EXTENSION utility.createsis
        OPTION PKG_FILE input_package_file.pkg
        OPTION PKG_PATH /path/to/pkg/file
        OPTION SIS_FILE output_sis_file.sis
        OPTION SIS_PATH /path/to/sis/file
        OPTION TARGET_FILE core_binary_to_be_packaged
        OPTION SEARCH_PATH /root/path/to/resolve/pkg/content
        OPTION BUILD_TYPE urel|udeb
        OPTION STUB_SIS true|false
        OPTION DEPEND_FILES additional_dependent_file[s]
        OPTION DEPEND_PATH /path/to/additional/dependencies
        OPTION CERTIFICATE_FILE signing_certificate_file.cer
        OPTION PRIVATE_KEY_FILE private_key_file.key
        OPTION PRIVATE_KEY_PASSPHRASE passphrase
        OPTION MAKESIS_ARGS additional_arguments_to_makesis
        OPTION SIGNSIS_ARGS additional_arguments_to_signsis
    END

Option Breakdown
================
Option                  Description            Mandatory?  Additional Info
------                  -----------            ----------  ---------------
PKG_FILE                .pkg file input        Yes
PKG_PATH                Path to .pkg file      No          default: bld.inf path
SIS_FILE                Output .sis file       Yes
SIS_PATH                Path to .sis file      No          default: bld.inf path
                                                           (into release tree
                                                           if "STUB_SIS true")
TARGET_FILE             Core binary            No          Resolved with regard
                                                           to release location
SEARCH_PATH             Root location for      No          default: $EPOCROOT
                        locating .pkg content
BUILD_TYPE              urel or udeb           Yes         Restricts a createsis
                                                           instance to a release
                                                           or debug run
STUB_SIS                true or false          No          Generate a rom stub
                                                           default: false
DEPEND_FILES            Additional build       No
                        files to track
DEPEND_PATH             Path to dependencies   No          default: $EPOCROOT
MAKESIS_ARGS            Additional arguments
                        for makesis
SIGNSIS_ARGS            Additional arguments
                        for signsis 
CERTIFICATE_FILE        Certificate file       No          Relative to bld.inf
PRIVATE_KEY_FILE        Key file for signing   No          Relative to bld.inf
PRIVATE_KEY_PASSPHRASE  Key file passphrase    No
	  
Option Notes
------------
As with all bld.inf content, build platform/configuration preprocessor
conditionals/substitutions are supported.

$(PLATFORM) and $(TARGET) values in .pkg file are replaced by the FLM with
the current build platform and BUILD_TYPE (respectively).  This permits a more
generic form of .pkg file, as generated by QMAKE for QT applications.

TARGET_FILE values are resolved in relation to the following template:
$EPOCROOT/epoc32/release/build-platform/BUILD_TYPE/TARGET_FILE

Default SIS_FILE locations are resolved relative to the bld.inf file unless
STUB_SIS is true.  Stub .sis files are generated to
$EPOCROOT/epoc32/data/z/system/install for target builds and using the
following template for emulator builds:
$(EPOCROOT)/epoc32/release/winscw/BUILD_TYPE/data/z/system/install/SIS_FILE

The resolved TARGET_FILE, if listed, is always tracked as a dependency of the
.sis file, as are any other resolved *_FILE option values.

All *_PATH values support $(EPOCROOT), $(EXTENSION_ROOT) etc. if the default
locations need to be overridden for a specific use case.

DEPEND_FILES support is present to ensure the correct running of the FLM with
regard to other files generated in the build.  Not all additional files
referenced in the .pkg file need to be present here, only those that:
a) have the potential to be generated later in the build than the .sis file
b) should be additionally acknowledged for the purpose of an incremental build

Example
=======
/src/examples/helloworld/bld.inf

    PRJ_EXTENSIONS

    // release packaging
    START EXTENSION utility.createsis
    #ifdef WINSCW
    OPTION PKG_FILE sis/winscw_urel.pkg
    OPTION SIS_FILE sis/helloworld_winscw.sisx
    #else
    OPTION PKG_FILE sis/armv5_urel.pkg
    OPTION SIS_FILE sis/helloworld_armv5.sisx
    #endif
    OPTION TARGET_FILE helloworld.exe
    OPTION BUILD_TYPE urel
    OPTION CERTIFICATE_FILE sis/sign.cer
    OPTION PRIVATE_KEY_FILE sis/sign.key
    OPTION PRIVATE_KEY_PASSPHRASE velociraptor123
    OPTION SIGNSIS_ARGS -cd // Sign using RSA
    OPTION DEPEND_FILES epoc32/data/z/resource/apps/HelloWorld.rsc \
        epoc32/data/z/resource/apps/helloworld.mbm
    END

    // debug packaging
    START EXTENSION utility.createsis
    #ifdef WINSCW
    OPTION PKG_FILE sis/winscw_udeb.pkg
    OPTION SIS_FILE sis/helloworld_winscw_debug.sis
    #else
    OPTION PKG_FILE sis/armv5_udeb.pkg
    OPTION SIS_FILE sis/helloworld_armv5_debug.sis
    #endif
    OPTION TARGET_FILE helloworld.exe
    OPTION BUILD_TYPE udeb
    OPTION MAKESIS_ARGS -v
    OPTION DEPEND_FILES epoc32/data/z/resource/apps/HelloWorld.rsc \
        epoc32/data/z/resource/apps/helloworld.mbm
    END

    // custom release packaging
    // uses the optional overrides for default locations
    START EXTENSION utility.createsis
    OPTION PKG_PATH $(EXTENSION_ROOT)/sis
    OPTION SIS_PATH $(EPOCROOT)/epoc32/packaging/helloworld
    #ifdef WINSCW
    OPTION PKG_FILE winscw_urel_custom.pkg
    OPTION SIS_FILE helloworld_winscw_custom.sis
    #else
    OPTION PKG_FILE armv5_urel_custom.pkg
    OPTION SIS_FILE helloworld_armv5_custom.sis
    #endif
    OPTION TARGET_FILE helloworld.exe
    OPTION SEARCH_PATH $(EPOCROOT)/epoc32
    OPTION BUILD_TYPE urel
    OPTION DEPEND_PATH $(EPOCROOT)/epoc32/data/z/resource/apps
    OPTION DEPEND_FILES HelloWorld.rsc helloworld.mbm
    END

    // stub .sis file
    START EXTENSION utility.createsis
    OPTION PKG_FILE sis/stub.pkg
    OPTION SIS_FILE helloworld_stub.sis
    OPTION BUILD_TYPE urel
    OPTION STUB_SIS true
    END