![[Index]](../../../stock/btn_index.gif){kind=small}
![[Glossary]](../../../stock/btn_glossary.gif){kind=small}
![[Previous]](../../../stock/btn_prev.gif){kind=small}
![[Next]](../../../stock/btn_next.gif){kind=small}
| |
|
| |
.pkgA pkg file is a text file which contains installation
information for applications or files. It consists of the following parts, some
of which may be omitted:
the languages supported
the package header, including the name of the component to be installed and its build and version information
package-signature details (optional)
package-lines (optional) formed from the following:
options line
condition blocks
language independent files to install
language-dependent files, of which only one will be installed
capabilities line
requisite components
embedded sis files
comments
The first item in the pkg file should detail the
languages provided within the sis file followed by the package
header which details the name of the component to be installed in all supported
languages, the UID of the component, and version information. An optional
digital signature line may be specified which gives the name of the private key
file and associated certificates to be used to digitally sign the
sis file. The remainder of the file lists the files and components
to be included in the sis file or dependencies upon other
installed components.
With respect to v5, arguments in pkg files no
longer have to be abbreviated — longer variants of the same options are
supported, e.g. FILETEXT rather than "FT".
All pkg files parsed by the Installation File
Generator may be in either UTF8 or Unicode format. UTF8 text is converted to
Unicode when creating a sis file. Both little-endian and
big-endian Unicode files may be used; automatic conversion is performed by the
Installation File Generator as appropriate.
Characters may be included within strings using an escape syntax. The following samples demonstrate the use of a character code to include a "™" symbol at the end of the application name:
"MyApp<153>"
"MyApp<0x99>"
Numeric character codes should be entered outside double quotes and bounded by "<" and ">". The value may be in the range 0-65535.
A single PKG command line may be spread over multiple lines if desired, it does not all have to appear on a single line.
|
The language line specifies which languages are supported by the component. Languages are identified by a two character code. The line may be omitted; if so, UK English is assumed by default. The language line must be specified before any other section. Its format is as follows:
&Language_1,...,
Language_n
For example:
&EN,FR,IT
The following languages are supported:
|
The number of text strings in the following line types should match the number of languages specified in the languages line and be in the same order:
package header
option lines
language dependent files
requisites
|
The package header must be included before all other items, except the language line, if one is specified. Its format is:
#{"Component Name for language1",
"Component Name for language
n"},(ComponentUID),Major,Minor,Build-Number[,Package
Options] [,TYPE=Package Type]
The package header contains the component name in each of the supported languages, the UID of the component, the major and minor version number and build number, and package options.
For example:
#{"MyApp"},(0x10000001),1,0,0,TYPE=SISAPP
All sis files require a UID, even if the installed
files do not require one.
The application's major and minor version numbers are required for
version control (eg. AppName 3.1 specifies a major build 3, and
minor build 1.)
The build-number replaces the variant value which was unimplemented in ER5 and previous versions of the Installation File Generator.
All numbers can be hexadecimal.
The component name is language dependent. It is used to identify
the component in the installation dialogs and in the list of installed programs
in the control panel's Add\remove program.
The number of component names must equal the number of languages specified in the languages line, and should be in the same order.
One or both of the following package options can be specified:
|
The package type allows the user to easily identify the main installed applications, distinct from any system components. They also let the add/remove control panel item distinguish the packages which the user may not remove. For example, installing an application is installed using the SYSAPP type: #{"MyApp"},(0X100000001),1,0,0,SH,NC,TYPE=SYSAPP
The package type may be followed with only one of the package type arguments;
|
The ID and I8 (non-Unicode sis files) flags have been
dropped from post ER5 releases
The UID value should be unique for the following types of sis
file: Applications (SISAPP), System/shared components (SISSYSTEM),
Add-on/optional components (SISOPTION).
The UID for the following types of SIS files should be identical to the UID for the main app or system component with which they are associated: Configuration components (SISCONFIG), Patches (SISPATCH), Upgrade components (SISUPGRADE).
|
The package signature line is used when creating a digitally signed installation file. The signature will be checked when the package is installed and details of the certificate will be available to the user at install time and when listing installed components. The signature line format is:
*private-key-file,public-key-cert[,KEY=privatekey-password]
The private-key-file refers to the name of a
private key file used to create a digital
signature. The private key is used only when creating
the sis file, the name of the file is not embedded within the
resultant sis file. If no package-signature line appears in the
pkg file the package will be unsigned.
The optional KEY parameter specifies the password used to access the private key file if it has been encrypted. If the key is encrypted, but the KEY parameter has not been specified then the Installation File Generator will prompt the user for the access password
The public-key-cert refers to a single file containing
either the corresponding public key certificate (.cer file) or
a certificate chain file (.p7c) containing the corresponding
public key certificate and its associated certificates (necessary to form a
certificate chain to a trusted root certificate).
|
Condition blocks may be used to control the installer according to various attributes. The syntax is as follows:
IF
condition package-lines
[
ELSEIF
condition package-lines
] [ ELSE
package-lines
] ENDIF
For example, two sets of files may be included within the install
package, one set for an ARM processor and one set for an M-CORE processor. An
IF/ELSEIF block may be used with the CPU-type attribute to ensure
the correct files are installed on the target device.
For example:
IF cpu=0 ; ARM
"marm\myapp.app"-"!:\System\Apps\MyApp\Myapp.app"
ELSEIF cpu=1 ; MCORE
"mcore\myapp.app"-"!:\System\Apps\MyApp\Myapp.app"
ELSE
; unsupported cpu type, display a message & exit!
"nosupport.txt"-"", FILETEXT, TEXTEXIT
ENDIF
Most pkg lines are valid within a condition block,
however the following line types may not be used: languages, package-header,
package signature, requisites, capabilities.
The use of an IF…ELSE construct and conditions allows
a single installation file to support any number of different Symbian OS phones.
|
The exists() function may be used to test for the
existence of a given file. The devcap() and appcap()
functions may be used to test for device and application capabilites.
|
Option<n> attributes behave as global variables, which is
significant if there is an options line both in a main sis file
and an embedded sis file.
|
Option lines are used to display a list of options to the user. The
option required is selected and will usually control the installation of
optional components later on in the .sis file. The syntax of the
options line is as follows:
!({“Option1 string
language 1”,…, “Option1 string
language n }, …,{“Option m string
language1”,…,
“Option m string language
n”})
For example:
!({"Add-on 1 (20KB)"},{"Add-on 2 (75KB)"}, {"Add-on 3 (80KB)"},{"Add-on 4 (20KB)"})
Selection affects the values of special built-in attributes (option1, option2, option3,…). If option 1 is selected then the value of the option1 attribute will be 1, otherwise it would be 0. Condition-block statements that follow the option-line may test and act upon these selections. For example:
IF option1
"addon1.opo"-"!:\System\Apps\MyApp\addon1.opo"
ENDIF
Ideally these lines should appear towards the start of the
pkg file so that the user is prompted at the start of
installation, however this is not required and the options may be displayed at
any point in the installation
|
Files which will be installed regardless of the language variant selected by the end user, are specified as follows;
"Source"-"Destination"[,Arguments]
For example:
"epoc32ex\ToolsAndUtilities\HelloWorld.app"-"!:\system\apps\HelloWorld\HelloWorld.app"
The source is the path and filename for the source file on the PC. The destination is the target path and filename on the Symbian OS phone. A destination must be specified unless the file is a text file displayed at install time — text files are not installed. Consequently their destination is irrelevant, and may consist of empty quotes.
A “!” character may be used in place of the drive letter if the user is to be given the choice of the drive to install the file to.
Applications must be installed to
\system\apps\appname\appname.app. Other component files which form
part of the application, for example resource files and application information
files, should reside in the same directory as the application. If the
\appname\ directory does not exist, it will be created.
Files are installed in the order in which they are specified in the
pkg file.
If the file is used by other components, e.g. if it is a shared DLL for
instance, you may want to avoid the possibility of it being overwritten by an
earlier version. In this case, do not specify the file in this section.
Instead, create a separate sis file for the shared file, including
appropriate major, minor build numbers in the package header, and include the
new sis file in the sis Component Files
section.
An optional comma-separated list of arguments following the destination file may be specified, to describe the type of file and how it will affect the installation or removal process.
Use one of the following arguments to describe the type of file to install:
|
Text files displayed during install (using the FT option) should be in UTF8 or Unicode format and will be converted by the Installation File Generator to the correct format, i.e. Unicode.
Note that where installation is controlled from a connected PC, and FR or FM options are used, the application will be started on the Symbian OS phone, not the PC and therefore if the application displays anything it will be on the Symbian OS phone, not the PC.
Use one of the following arguments for a text file, i.e. after
FT has been specified, to determine how the text file dialog
should be cancelled, and how cancellation should affect the
installation:
|
One of the following arguments may be specified for a file which will be
run during the installation or removal process, i.e. after FR has
been specified. If the file is a document, the appropriate application will be
launched. For example, on installation, you may want to open a Word document
providing information about the new application.
|
Use the following argument after RI, RR or RB has been specified.
|
If RE is not specified, then the installer runs the file and continues with the installation. It does not wait for the started program to complete.
|
This format is used to specify a list of files, of which only one will be installed, depending on the language selected by the user during installation:
{ "Source
FileName"..."Source
FileName"}-"Destination"[,Arguments]
This format will commonly be used to specify lists of resource files.
Like applications, resource files must be installed to
\system\apps\appname\appname.rsc. If the appname
directory does not exist, it will be created.
For example;
{
"\epoc32ex\ToolsAndUtilities\HelloWorld.ruk"
"\epoc32ex\ToolsAndUtilities\HelloWorld.rfr"
"\epoc32ex\ToolsAndUtilities\HelloWorld.rit"
}-"!:\system\apps\HelloWorld\HelloWorld.rsc"
Here, three compiled resource files are specified, but only one will be
installed on the target machine. Whichever language is chosen, the resource
file will be installed as ikhello.rsc.
The opening brace denotes the start of the block of language-dependent files.
The order of the files should be the same as the order in which the languages were specified in the languages line
The number of files specified must be the same as the number of languages supported.
Options may appear after the destination name — as for the previous section, e.g. use FT to display a language specific dialog.
|
A requisite component is one that is required by the component which is being installed. It must be present on the target machine and its major and minor build numbers must be the same as, or greater than, those specified — otherwise installation will fail. Its name does not need to match the name specified, as it is identified by UID. However the name will be displayed to the user if there is a problem, e.g. the component is missing.
A requisite component is specified in the following way;
(UID),Major,Minor,Build-Number,{"Requisite
Name1", " Requisite
Name2"}
For example;
; Depends on STDLIB being installed
(0x100002c3), 1, 0, 14, {"Standard C Library"}
When de-installation of a component involves the removal of another component's requisite files, the user is warned that continuing may prevent other programs from working.
When the installer checks for the presence of requisites it uses the
information specified in the package header of the target component's
pkg file, see the Package header section.
Installation files of type SISCONFIG, SISPATCH, and SISUPGRADE, must declare a dependency on the main component which they are affecting.
|
![[Top]](../../../stock/arrow_up_2.gif){kind=icon}
Embedded sis filesOne or more embedded sis files may be specified, to be
installed as part of the installation of the main component. Embedded
sis files are removed when the component within which they were
embedded is removed, provided no other component has a dependency upon
them.
They are specified in the following way;
@
source-filename,(component-uid)
For example;
@"CsHelpExample.sis",(0x100002c3)
|
A capabilities line is used in conjunction with the Symbian OS Connect
capabilities manager, or with the pkg
appcap()
function in a condition block. The capabilities manager may be used to
determine the capabilities of a device or installed applications. The
capabilities line is specified in the following way;
+(capid=value,…)
Device and application capabilities may be used to control specific
behaviour when software is installed via a sis file or PC based
software.
Device capabilities (hardware related) may also be set when the Symbian OS phone's ROM is built. The pkg file devcap() function
may be used to query device capability values within a condition block.
Application capabilities are defined when a sis file is
created and stored on the device in the sis stub files.
Application capabilities are key/value pairs whose meaning is application
specific. The capid value is a unique application specific value and the
associated value is an integer which may be queried via the capabilities
manager PC based interface or using the appcap()
pkg
file syntax in an IF…ENDIF construct.
|
Lines of comment are preceded by a semicolon. They are ignored by the Installation File Generator
Copyright ©2002 Symbian Ltd. 6.1-00174 |
|
![[Top]](../../../stock/arrow_up.gif){kind=icon}