C++ для Symbian S60: синтаксис PKG-файла

Раньше мы упоминали PKG-файл, который позволяет превратить скомпилированную программу для телефона и набор дополнительных файлов в единый SIS-файл. Теперь рассмотрим его синтаксис подробнее.

Как уже упоминалось ранее, чтобы создать SIS-файл, – необходимо запустить команду makesis, указав в качестве параметра путь к PKG-файлу (или просто имя, если мы находимся в папке, где лежит PKG-файл). Для этого, естественно, нужно создать этот самый PKG-файл. А создать его можно в любом текстовом редакторе.

Важно:

1. PKG-файл предпочтительнее всего создавать в кодировке UNICODE. Это позволит избежать больших проблем с нелатинскими символами.

2. Все инструкции в PKG-файле регистронезависимые.

Вот файл helloworldbasic_gcce.pkg, позволяющий создать helloworldbasic_gcce.sis, для установки helloworld на телефон:

;Language - standard language definitions

&EN

; standard SIS file header

#{"HelloWorldBasic"},(0xA000017F),1,0,0

;Localised Vendor name

%{"Vendor-EN"}

;Unique Vendor name

:"Vendor"

;Supports Series 60 v 3.0

[0x101F7961], 0, 0, 0, {"Series60ProductID"}

;Files to install

"..\..\..\epoc32\release\gcce\urel\HelloWorldBasic.exe"                 -"!:\sys\bin\HelloWorldBasic.exe"

"..\..\..\epoc32\data\z\resource\apps\HelloWorldBasic.rsc"              -"!:\resource\apps\HelloWorldBasic.rsc"

"..\..\..\epoc32\data\z\private\10003a3f\import\apps\HelloWorldBasic_reg.rsc"  -"!:\private\10003a3f\import\apps\HelloWorldBasic_reg.rsc"

"..\..\..\epoc32\data\z\resource\apps\helloworldbasic_aif.mif"         -"!:\resource\apps\helloworldbasic_aif.mif"

"..\..\..\epoc32\winscw\c\private\A000017F\hello.txt"                  -"!:\private\A000017F\hello.txt"

;required for application to be covered by backup/restore facility

"backup_registration.xml"                                  -"!:\private\A000017F\backup_registration.xml"

Строки, начинающиеся с ; (точки с запятой), это комментарии, которые никак не влияют на SIS-файл. Рассмотрим все прочие строки.

Набор языков

&EN - инструкция, задающая набор языков в вашей программе.

Языки перечисляются через запятую, например: &EN,RU.

Если здесь указано несколько языков – при установке sis будет показано меню, позволяющее пользователю выбрать язык.

Заголовок (header)

#{"HelloWorldBasic"},(0xA000017F),1,0,0 - имя вашей программы, её UID и версия.

Если в первой инструкции было указано несколько языков – нужно указать имя программы для каждого из них. Для инструкции &EN,RU – выглядеть будет так: #{"Hello World","Привет, мир" },(0xA000017F),1,0,0.

Версия программы – это последние 3 числа через запятую, в нашем случае версия будет 1.0. Обратите внимание, что последняя цифра версии – это так называемый билд (build), который пользователь при установке не видит, увидеть его можно только в диспетчере приложений. Версия 1,5,0 будет отображена при установке как 1.05.

Кроме того, здесь же могут быть указаны дополнительные опции:

Таблица 1.

Например, #{"HelloWorldBasic"},(0xA000017F),1,0,0, TYPE=SP,SH. Обновляем helloworld, при этом предварительно выгружаем все запущенные приложения.

Производитель

%{"Vendor-EN"}

:"Vendor"

В установочных файлах Symbian 6-7 этих двух инструкций не было, поэтому если их написать – будет выдана ошибка и sis не соберется.

Для более поздних версий – эти инструкции обязательны.

Здесь указываются сведения о разработчике программы. На Symbian 9, если sis был подписан сертификатом self-signed, эти строки игнорируются, но указать их всё равно нужно.

Первая строчка, которая начинается с %, – локализованное имя разработчика, его можно указать для каждого из языков, например: %{"English vendor","Русский производитель"}.

Вторая строчка – нелокализуемое имя, здесь недопустимы языковые варианты.

Платформа для установки

[0x101F7961], 0, 0, 0, {"Series60ProductID"} - инструкция, в которой задаётся самая младшая версия платформы, где может устанавливаться собранный SIS-файл. Если версия платформы, где, устанавливается SIS-файл, ниже указанной – будет выдано сообщение: "Приложение не совместимо с телефоном. Продолжить?"

Значения, которое можно указывать в квадратных скобках, приведены в самой первой статье, в таблице 1.

Для S60 1st – 2nd – первая часть инструкции задаётся в круглых скобках, например для S60 1.2 так: (0x101F6F88), 0, 0, 0, {"Series60ProductID"}.

Также с помощью этой инструкции можно разрешить установку программы только в том случае, если на телефоне установлено какое-то необходимое приложение не ниже заданной версии: (0x2000015a), 8,65,0,{"Opera"}.

Это означает: sis можно устанавливать только в том случае, если на телефоне есть браузер Opera.

Для приложений UID задаётся в круглых скобках на всех платформах.

Есть ещё возможность задать диапазон необходимых версий – вот так: (0xA0004641), 0,16,0 ~ 1,0,0, {"DEd"}.

Что означает: для установки SIS-файла требуется DEdit версии не ниже 0.16 и не выше 1.0.

Список файлов для установки

Теперь собственно файлы, которые нужно поместить в SIS-файл на компьютере и извлечь из SIS-файла на телефоне.

Задаются в виде: "файл на жёстком диске" – "файл на телефоне".

Путь к файлу на жёстком диске может быть абсолютным – с буквой диска:

C:\Symbian\9.1\S60_3rd\epoc32\release\gcce\urel\HelloWorldBasic.exe

или относительный, как в примере:

"..\..\..\epoc32\release\gcce\urel\HelloWorldBasic.exe

Относительный путь задаётся от текущего PKG-файла, в данном случае путь означает "подняться на 3 папки вверх (окажемся в корне SDK), затем перейти в epoc32\release\gcce\urel\".

Если файл находится в одной папке с PKG-файлом – достаточно указать его имя:

"HelloWorldBasic.txt"-"!:\sys\bin\HelloWorldBasic.txt"

Путь к файлу на жёстком диске не может содержать русских символов. Путь к файлу на телефоне может содержать русские символы только в том случае, если PKG-файл в кодировке UNICODE.

Путь на телефоне может начинаться с буквы диска (C: или E:) или с ! (восклицательного знака). Если хотя бы один путь в PKG-файле начинается  c восклицательного знака – при установке пользователю будет предложено выбрать диск для установки, а все файлы, у которых путь начинается с восклицательного знака, установятся на выбранный диск.

Все несуществующие папки будут созданы.

Если файл не должен устанавливаться, но предполагается, что он будет создан программой в процессе работы, – его рекомендуется удалять при деинсталляции программы. Это задаётся в PKG-файле инструкцией:

"" - "!:\System\TempFile.txt"

т.е. локальный путь пустой.

Если в первой инструкции было задано несколько языков, можно задать файл для каждого из них. Тогда файл будет установлен в зависимости от выбора пользователя:

{"readme_en.txt" "readme_ru.txt"}-"!:\System\apps\MyApp\readme.txt"

Кроме того, для каждой пары файлов можно задать дополнительные опции:

Таблица 2.

Обратите внимание: если новая версия программы устанавливается поверх предыдущей – программа установки вначале удаляет все файлы, установленные с предыдущей версией, а потом ставит новые.

Например, нужно установить какой-то INI-файл, содержащий значения по умолчанию, а если такой файл уже есть и, возможно,  изменён пользователем, то оставить старый. Такая логика не получится, программа установки вначале снесёт существующий файл, а потом установит новый.

Решить эту проблему силами одного только PKG-файла мне не удалось. Потребовалось такое шаманство:

1. В PKG-файле:

; Устанавливаем пустой текстовый файл - он будет индикатором первого запуска

"empty.txt"-"!:\System\Apps\MyApp\FirstRun.flg"

; Устанавливаем ini, но с расширением txt

"config.ini"-"!:\System\Apps\MyApp\config.txt"

2. В программе реализуем такую логику: если во время старта программы найден файл System\Apps\MyApp\FirstRun.flg – переименовываем config.txt в config.ini и удаляем FirstRun.flg.

Теперь понятно, что было написано в helloworldbasic_gcce.pkg, и читатель может самостоятельно написать PKG-файл.

Но это ещё не все доступные инструкции.

Условия

Файлы можно ставить или не ставить в зависимости от различных условий. В общем случае это выглядит так:

IF(Условие 1) Набор_файлов_1

ELSEIF (Условие 2) Набор_файлов_2

ELSE Набор_файлов_3

ENDIF

Например, часто используемое условие – проверка существования файла:

IF EXISTS("c:\test.txt")

"text\exists.txt"-" c:\test.txt "

ELSE

; Ничего не ставим

ENDIF

С помощью условия можно ставить файлы в зависимости от модели телефона, это выглядит так:

; Если sis устанавливается на Nokia 6600, установим my.exe

IF (MachineUid = 0x101fb3dd)

"my.exe"-" c:\my.exe" FR,RI

ENDIF

Вот теперь и пригодились эти непонятные MachineUID'ы из таблицы в первой статье .  

Чтобы выполнить установку некоторых файлов в зависимости от версии SDK, нужно поступить чуть хитрее. Видели в таблице загадочное поле "Файл в папке Z:\System\Install"? Так вот, здесь оно и пригодилось:

; Ставим специфический файл для 3rd FP1:

IF EXISTS("Z:\System\Install\Series60v3.1.sis")

"file3.1.txt"-" c:\file3.1"

ENDIF

Обратите внимание: на платформе  2nd Ed, FP3 например, в Z:\System\Install\ находятся также SIS-файлы для всех младших версий. Т.е. условия:

IF EXISTS("Z:\System\Install\Series60v2.8.sis")

"file2_fp3.txt"-" c:\file2_fp3"

ENDIF

IF EXISTS("Z:\System\Install\Series60v1.2.sis")

"file1.2txt"-" c:\file1.2"

ENDIF

установят и файл file2_fp3, и файл file1.2. Чтобы поставился файл именно для текущей версии SDK, делаем так:

IF EXISTS("Z:\System\Install\Series60v2.8.sis")

"file2_fp3.txt"-" c:\file2_fp3"

ELSEIF("Z:\System\Install\Series60v1.2.sis")

"file1.2txt"-" c:\file1.2"

ENDIF

Также при установке файла можно проверить наличие той или иной программы на телефоне:

IF PACKAGE(0x2000015a)

"file_for_Opera1.txt"-"!:\file_for_Opera1.txt"

"file_for_Opera2.txt"-"!:\file_for_Opera2.txt"

ENDIF

Различных возможных условий много, можно ставить разные файлы в зависимости от типа процессора, его скорости, цветности монитора и многих других факторов. Не буду их все здесь перечислять.

Выбор дополнительных файлов для установки

Позволяет вывести во время установки меню, в котором пользователь может отметить нужные ему пункты.

Пример из реального проекта:

!(

{"PhpBB для TextPockets"},

{"Системные шаблоны TextPockets"},

{"Шаблоны Dimonvideo.ru"},

{"Утилита KeyCode"},

{"Не ставить ErrRd"},

{"Автозагрузка"}

)

Каждое выражение в фигурных скобках – один пункт меню.

В случае многоязычного интерфейса – пишется так (это пример с русским и английским):

!(

{"Item 1"," Элемент 1"},

{"Item 1"," Элемент 2"}

)

Далее – для обработки пользовательского выбора создаём набор условий:

; Дополнительные файлы, если выбран первый пункт меню

IF option1

"file_for_item1"-"C:\file_for_item1"

ENDIF

; Дополнительные файлы, если выбран второй пункт меню

IF option2

"file_for_item2"-"C:\file_for_item2"

ENDIF

Ну всё. Думаю, теперь стало ясно, почему PKG-файл, созданный для CodeWarrior, был кривой и как сделать его прямым.

Сборка SIS-пакета

Как уже было сказано, SIS-файл собирается с командной строки командой:

makesis <PKG-файл>

Если в PKG-файле допущена ошибка или какой-то из файлов не найден – в консоли появится сообщение об ошибке, например:

C:\Symbian\DEdit\sis>makesis DEdit6.pkg

Processing DEdit6.pkg...

DEdit6.pkg(19) : error: file not found

В скобках указана строка PKG-файла, где произошла ошибка. Переход на строку по её номеру в большинстве Windows-редакторов – Ctrl+G.

Пользователи Carbide не смогут пользоваться командной строкой для сгенерированного для них PKG-файла, т.к. он содержит некоторые записи, понятные только Carbide.  Вместо этого предлагается редактировать PKG-файл в самой программе и, как мы уже видели, Carbide сам соберёт sis из проекта.

Что ещё есть хорошего?

Рассмотренного выше для начала более чем достаточно. Ещё есть некоторые возможности, которые могут потребоваться уже на поздних этапах, когда читатель станет опытным Symbian-developer и будет всю эту кухню знать лучше, чем автор.  Тогда будет проще в SDK посмотреть.

Существуют специализированные программы, позволяющие создать SIS-файл визуально. Одна из них – под названием SISAr – поставляется с SDK 1st и 2nd и требует для своей работы JAVA-машину. Найти SISAr можно в Epoc32/tools либо Shared/Tools, а лучше поиском по ключевому слову sisar.jar. Читатель, освоивший всё, что было описано выше, сможет разобраться в программе самостоятельно.

В целом программа может помочь в создании простенького SIS-файла и совершенно неприменима для чего-то сложного.