v QNX Package Generation (QPG) file structure

Ø QPG files are used to direct the ‘packager’ utility in how to generate packages, so that the operator need not have direct intervention when building packages; this permits automated packaging as needed. The main advantage is that files need not appear in a directory structure which matches the installation directory structure—this is a huge advantage over the packager utility’s default operation, and allows you to keep your development setup without requiring the files to be copied to another part of your filesystem.

Ø Generate a sample QPG file by typing: packager –j1

Ø Wherever you plan to run the packager utility, you can place the main QPG file. If you just start ‘packager’ with no command-line arguments, it looks for package.qpg, which will be used as the default. To specify a particular QPG file, pass the name of the file as the final argument to the packager utility.

Ø Any QPG file can reference other QPG files (using the QPG:Merge specifier). Thus, your main QPG can reference a number of smaller (easier to manage) QPG files. Merging of QPG files allows you to add to the list of files to be packaged (see QPG:Files), and define the manifest settings that will be used for all generated packages (see QPG:PackageFilter). Note that the QPG:Options section (command-line adjustments) are not merged—only the primary QPG file’s QPG:Options section will be used by the packager.

§ For example, you might have one QPG file that sets up a product’s license settings, and which adds the license.txt file into the package.

Ø For each file which is to be packaged, use a QPG:Add entry to put it into the list of files. Wildcards are allowed, or you can add an entire directory or directory tree (see QPG:Add).

Ø By reading the various QPG options below, you will discover further functionality not outlined in this brief section—reading the full document is recommended.

Ø Notes

1. When adding a personal script to a package by putting the script block into a QPG file, you must reference the location of the script explicitly—which is not possible because you don’t know the exact directory path of the package in case it is altered by a change in the package (build number, for example). To fix this, reference the script like this: pkg://script1 The pkg:// will be replaced with rep://path/to/the/package/ each time the package is built, so that the path need not be explicitly known. The pkg:// qualifier may be used in any part of the manifest, and right before the manifest is written, it will be replaced with the actual value.

2. Similarly, when adding a license to a package by putting the <LicenseUrl> tag into a QPG file, you must reference the location of the license explicitly—which may not be possible because you don’t know the exact filename of the QPR file in case it is altered by a change in the package (build number, for example). To fix this, reference the license like this: repdata://LicenseUrl/license.txt The repdata:// will be replaced with rep://package.repdata/ each time the package is built, so that the filename need not be explicitly known. The repdata:// qualifier may be used in any part of the manifest, and right before the manifest is written, it will be replaced with the actual value.

v QPG:Generation

§ QPG:Options

· The options specified in this section specify the command-line options to be used when packager is run. Options actually specified on the command-line override any options entered in the QPG file (unless the –y option is specified). Options are used in the original (first) QPG file only; merged QPG files’ options are ignored.

· QPG:User

¨ verbosity=0 (normal), 1 (advanced), 2 (expert)

¨ unattended=yes (accept defaults only), no (ask operator for non-QPR-specified elements)

¨ listfiles=yes (shows each file that will be packaged), no (only shows the number of files that will be packaged).

· QPG:Defaults

¨ type=qnx_package (based on a QPM/QPK/QPR file), none (do not use a default file)

¨ file=filename (which file to use)

· QPG:Source

¨ basedir=directory (which directory is base directory)

¨ If this entry is not specified, and the command-line has no basedir specified, then no directory scan will be done; only files in QPGs will be packaged.

· QPG:Release

¨ number=+ (autoincrement), - (do not autoincrement)

¨ date=today (set release date to today), default (use date found in previous QPM/QRM). This option only matters if the ReleaseDate tag(s) are not specified explicitly in the QPG file.

· QPG:Build

¨ number=+ (autoincrement), - (do not autoincrement), # (use this number), date (use today’s date as yyyymmddhh).

· QPG:FileSorting

¨ strip=yes/no (strip files when sorting)

¨ ownership=standard (change ownership where possible), override

¨ dir=directory (which directory to sort into and not clean up), none (do not sort into a specific directory)

· QPG:Package

¨ targets=combine (combine targets into one package), standard (separate target packages)

¨ filter=pattern (pattern must match the product identifier for the package to be actually filled with files. This is for package testing purposes only).

¨ compatible=default (use packager version in the manifest), desired version (ie: 1.01) to appear in the manifests.

¨ union=terminate (union root-level directories only), deep (union entries are as deep as possible), default (same as deep).

· QPG:Repository

¨ generate=yes (create QPR files), no (create QPK/QPM files only)

¨ index=yes (create index file of the final directory), no (no index file is created).

¨ content=yes (create content.tgz file), no (no content file is created).

¨ qrm=yes (create repository.qrm file), no (don’t create repository.qrm).

· QPG:FinalDir

¨ dir=directory (which directory to put final QPM/QPK/QPR files into), none (use CWD only to sort final files).

· QPG:Cleanup

¨ manifest=clean (remove manifests), keep (keep manifests).

§ QPG:Responsible

· This section specifies the company/department/employee who is responsible for the files referenced in this QPG. Any or all of the following fields may be shown or omitted, and multiple entries for each are allowed.

· QPG:EmailAddress (multiple entries)

¨ This is the email address of the person/group which will be contacted when determined necessary by the packager, regarding this file.

· QPG:Company (multiple entries)

· QPG:Department (multiple entries)

· QPG:Group (multiple entries)

· QPG:Team (multiple entries)

· QPG:Employee (multiple entries)

§ QPG:Owner

§ file=filename (location of the owner’s QPG file which contains only a QPG:Responsible section).

§ QPG:MergeFilter (optional, multiple entries)

Any number of attributes can be defined, which will be applied to all QPG:Add and QPG:PackageFilter entries within any Merged QPG files within this block.

ie: <QPG:MergeFilter component=”drivers”> will set all subsequently merged QPG files within this block to have component=”drivers” if the component attribute is not already set.

This section can also appear within another QPG:MergeFilter block, if necessary (nesting is valid).

If a QPG:Add tag or a QPG:PackageFilter tag has an attribute: inherit=”no”, then no attributes will be inherited from any of its ancestor MergeFilter tags.

§ QPG:Merge (multiple entries)

· Any Merge entries specify another QPG file which is to be included as if it were part of this QPG file. Using any number of these tags, packages can be built-up from any number of small QPG files/programs.

· file=filename (location of another QPG to merge)

§ QPG:Generate (multiple entries)

· Optionally, a QPG can specify that another package must be built as a result of building the current package. Another instance of the packager utility will be started, and the current instance can be told to wait for its completion. This will be useful in generating dependent packages.

· dir=directory (CWD for the new instance of packager)

· wait=yes (wait until packager is complete before continuing [default]), no (continue immediately)

§ QPG:Values

· This block defines all manifest values and files which are to be included in the package. The PackageFilter can be used to direct certain values into particular manifests, and similarly, files can have the same direction.

· QPG:PackageFilter (multiple entries)

¨ (This is an exception to the attributes mentioned below) If this tag has an attribute: readonly=”1”, then any generated package which matches this PackageFilter will be marked as a read-only package in the package filesystem when it is installed. There are side-effects to setting this option—see QNX for details.

¨ When a PackageFilter is used, you can specify any or all of the following attributes, which must all match in order to be merged into a particular package’s manifest.

¨ type=core (only for packages with no parent), all (for all generated packages), ignore (the parentage does not matter [default]), child (only for packages with a parent—processor-specific packages).

¨ proc=any (any processor-specific package), none (any CPU independent package), ignore (processor is irrelevant [default]), or the processor name (string match).

¨ target=any (any target-specified package), none (any package where the target is not specified), ignore (target is irrelevant [default]), or the target name (string match).

¨ component=any (any component type-specific package), none (any package where the component type is not specified), ignore (component type is irrelevant [default]), or the component type itself (string match).

¨ The following sections correlate directly to the MANIFEST tags, and the tags used must match exactly. Entries in this section which are specified explicitly cause an attended session of packager to skip asking the questions that correspond to those entries.

¨ xmlmultiple=true (if this attribute is present on ANY tag in this section, the added block will be in addition to existing blocks of the same name, instead of overwriting the previous block which is what is normally done). This will be required on tags which can have multiple entries, like <QPM:Dependency>, <QPM:Script>, and <QPM:Launch>.

¨ QPM:PackageManifest

Ø QPM:PackageDescription

§ etc.

¨ QPM:FileManifest

Ø QPM:Listing

§ etc…

§ QPM:File or QPM:Link or QPM:Union

· xmlmultiple=true (this attribute must be present on all files/links/unions added in this manner).

· QPG:Files

¨ This section is used to specify the files and/or directories to include in the package being generated. To get files into a package, you can use a ‘basedir’ on the command-line, specify a ‘QPG:Source’ tag in the ‘QPG:Options’ section, or add any number of the following tags. Also, you can use this section to exclude particular files from being packaged, or have them inserted into the QPK or QPR only (without being in the manifest).

¨ QPG:Add (multiple entries)

Ø Used to add files to the package. Use a type attribute to specify what is being added, and a file attribute to specify the file/directory to add. The values entered here will be applied to all files added (pattern-matched). However, if a .pinfo file is also present, its values will overwrite the values specified here.

Ø For example, to add a license file into the repository directory, use the following: <QPG:Add file=”./license.txt” install=”LicenseUrl/” handling=”repdata”/>. The corresponding <LicenseUrl> tag could be: rep://packager-1.1-qnx.repdata/LicenseUrl/license.txt

Ø Any <QPG:Add> tag can have any number of <QPG:Rule> tags within it. See the section on Rules at the end of this document, for details on how to use these rules (advanced feature).

Ø type=file (add the following files [default setting]), dir (add all files under the following directory), tree (add all files within the following directory and its subdirectories).

Ø file=pattern (pattern match to the source file(s) to include in the package). If ‘type’ is dir or tree, then this attribute holds the directory name. This is the only attribute which is absolutely required for each <QPG:Add> entry.

Ø pinfo=pattern (explicit filename of .pinfo file, or relative location of the .pinfo file from the source file). If the pattern is equal to “$”, the resultant filename will be used, with .pinfo appended onto it (replacing its extension if there is one).

Ø install=directory to install the file into (must end in a slash ‘/’ character), or the exact filename to use when the source file is installed. [overrides default packager location]. This attribute is optional—if not included, the installation location is determined by the file type, or it will be gathered from a .pinfo file.

Ø license=license which applies to the specified file(s). This license will be added to whatever licenses are specified in the .pinfo file.

Ø permissions=chmod arguments to be applied (or default to not change permissions).

Ø user=chown arguments to be applied (or default to not change ownership).

Ø group=chgrp arguments to be applied (or default to not change group).

Ø stacksize=the stack size for this program (in bytes) which is applied using ldrel –S (or default to not change stack size).

Ø description=text description of the purpose of the file(s) (or default).

Ø name=text name of the file(s).

Ø filter=exact (the specified proc/target/component settings will not be changed from the values that are specified in this line).

Ø proc=any (any processor-specific package), none (any CPU independent package), ignore (processor is irrelevant), or the processor name (string match), default (packager will determine the host processor).

Ø target=any (any target-specified package), none (any package where the target is not specified), ignore (target is irrelevant), or the target name (string match), default (packager will determine the target processor).

Ø component=any (any component type-specific package), none (any package where the component type is not specified), ignore (component type is irrelevant), or the component type itself (string match), default (packager will determine the component type).

Ø handling=repdata (repository data file which will be copied into the repository but not packaged), pkgdata (package data which will be copied into the required QPK files, but not included in the manifests), script (same as pkgdata), exclude (file will not be packaged), copy (add the specified file, even if it’s already listed, with a different install location), default (none of the above).

(a) To add a script (in a QPG file), it will appear as: <QPG:Add handling=”script” file=”script_filename” install=”/”/>

(b) If it is a processor-dependent script: <QPG:Add handling=”script” file=”script_filename” install=”/” proc=”x86” filter=”exact”/>

Ø filetype=dir (directory), doc (documenation), exe (an ELF executable), obj (a relocatable object for linking), so (a shared object for linking and executing), dll (a shared object for executing), script (a shell script), symlink (a symbolic link), default (packager will determine the filetype).

Ø linkto=alternative location to which the symbolic link points (only valid if the filetype=symlink). To properly insert a symbolic link into the list of files, do the following: <QPG:Add file=”symbolic_link_name” install=”install_directory/” filetype=”symlink” linkto=”file/to/link/to”/>. Or you can enter “default” to remove the linkto attribute.

Ø slib=”slib-component” (forces a symbolic link into both the expected package, and the specified slib-component package).

Ø ar=yes (the file is an archive), no (force it to not be an archive), default (packager will determine whether the file is an archive).

Ø gzip=yes (the file is gzip’ed), no (force it to not be gzip’ed), default (packager will determine whether the file is gzip’ed).

Ø pkg=yes (the file is only for packages), no (force it to be not just for packages), default (packager will determine whether the file is only for packages).

Ø qpr=yes (the file should only be in a QPR), no (allow the file to go anywhere), default (packager will determine whether the file should only be in the QPR).

Ø qpg=the source QPG from which this entry was generated.

Ø strip=no (does not strip this file, regardless of the overall settings), yes (strip this file, regardless of the overall settings).

¨ QPG:File (multiple entries)

Ø These entries are created dynamically by the packager utility. Do not add this section by hand--use the QPG:Add tags instead which allow pattern-matching (see above).

Ø file=filename to be packaged.

Ø install=directory to install the file into (must end in a slash ‘/’ character), or the exact filename to use when the source file is installed.

Ø permissions=chmod arguments to be applied.

Ø user=chown arguments to be applied.

Ø group=chgrp arguments to be applied.

Ø stacksize=the stack size for this program (in bytes) which is applied using ldrel –S.

Ø description=text description of the purpose of the file(s).

Ø name=text name of the file(s).

Ø proc=any (any processor-specific package), none (any CPU independent package), ignore (processor is irrelevant), or the processor name (string match).

Ø target=any (any target-specified package), none (any package where the target is not specified), ignore (target is irrelevant), or the target name (string match).

Ø component=any (any component type-specific package), none (any package where the component type is not specified), ignore (component type is irrelevant), or the component type itself (string match).

Ø filetype=dir (directory), doc (documenation), exe (an ELF executable), obj (a relocatable object for linking), so (a shared object for linking and executing), dll (a shared object for executing), script (a shell script), symlink (a symbolic link).

Ø linkto=alternative location to which the symbolic link points (only valid if the filetype=symlink).

Ø ar=yes (the file is an archive), no (force it to not be an archive)

Ø gzip=yes (the file is gzip’ed), no (force it to not be gziped)

Ø pkg=yes (the file is only for packages), no (force it to be not just for packages)

Ø qpr=yes (the file should only be in a QPR), no (allow the file to go anywhere)

Ø qpg=the source QPG from which this entry was generated.

Ø strip=no (does not strip this file, regardless of the overall settings), yes (strip this file, regardless of the overall settings).

Ø size=number of bytes that this file uses.

Ø patch=product identifier of the package from which this file differs (patching only; automatically determined).

Ø handling=repdata (repository data file which will be copied into the repository but not packaged), pkgdata (package data which will be copied into the required QPK files, but not included in the manifests), script (same as pkgdata), exclude (file will not be packaged) copy (add the specified file, even though it’s already listed with a different install location),.

Ø QPG:License (multiple entries)

§ type=license type, taken from QPG and .pinfo files.

§ QPG:Rule

§ When you are adding a file, using a <QPG:Add> tag, it can enclose any number of <QPG:Rule> commands within it. As the file(s) are sorted, they are checked against each rule, in the order that they are specified. The file may match more than one rule.

§ Remember that if multiple rules are specified exactly the same, they will be merged into one entry. To prevent this behaviour, add an xmlmultiple=”true” attribute to each rule which might conflict with another.

§ When a rule is matched, the rule’s attributes are copied into the file’s attributes, thus redirecting it, renaming it, etc. The following attributes however, will not be copied as they are part of the rule itself.

§ match=”stop” (stops processing of rules if this rule is matched), “skip” (skips to another rule if this rule is matched), “exclude” (stops rule processing and removes this file from the list of files to be packaged, if this rule is matched).

If “skip” is specified as a number, you can skip any number of rules by setting a skip=”X” command, where X is the number of lines to skip. (ie: skip=”3” skips the next 3 rules)

If “skip” is a string, execution will jump to the first rule in this block which has the corresponding label=”string” tag., if any. (ie: skip=”main” goes to a rule with label=”main”)

§ search=”pattern” [default value] (if the source filename matches the specified argument as an fnmatch pattern, the rule will be applied), “path” (matches full path using fnmatch, treating ‘/’ as a special delimiter).

§ argument=(the pattern to be matched) For example: argument=”*/include/*.h”

You can use the $(PROCESSOR) macro to match any processor. For example: /$(PROCESSOR)/usr/bin/ph*. The $(PROCESSOR) can also be specified in any of the attributes on this Rule line, and the matching processor will be inserted.

Examples:

<QPG:Rule search=”pattern” argument=”/$(PROCESSOR)/usr/bin/*” proc=”$(PROCESSOR)”/>

<QPG:Rule argument=”*/doc/*” component=”docs” install=”/usr/doc/”/>