Documentation

Creating an Application Package

This section describes the officially prescribed way for installing a Plug-in Development Kit (PDK) application on the device and running it. At some point, you will have to do it this way if you want to upload your application to the HP App Catalog for wider distribution. This involves some configuration and using PDK command-line tools for packaging and installing the application. Packaging involves creating a package file (with an .ipk extension), and installation involves placing the application at a designated location on the device and creating a Launcher menu icon.

Note: For combined JS/Plug-in apps, see Building a Combined JS and Plug-in Application.

In this section:

Using Command-Line Tools to Package and Install Your Application for the Device
Configuring Your Application's appinfo.json File
Configuring Application Memory
Example Complete Build, Package, and Install Process

Using Command-Line Tools to Package and Install Your Application

The PDK includes the following command-line development tools to create, package, and install your application on the device:

palm-generate -- Generates an empty project with the necessary files and directory structure.
palm-package -- Creates an installable application package.
palm-install -- Installs an application package on the device.

To package, install and launch your application on the device

Open a program to access the filesystem.
- On Windows, open a command prompt.
- On the Mac, launch the Terminal application.
  
  Type "export PATH=$PATH:/opt/PalmPDK/bin" and press ENTER. This puts the development tools in your path.
Go to the directory (i.e., C:\PalmApps) where you want your app (project) sub-directory to be created.
Run palm-generate <app-dir-name>.

For example: palm-generate simple

This creates a simple directory (C:\PalmApps\simple) containing project skeleton files. This creates a number of files, but the only ones of concern are appinfo.json and icon.png. The latter is the default icon (a half-moon shape) for your app on the launcher menu. You can replace this with another file, but it must also be a png file.
Modify your application's appinfo.json file in the <app-dir-name> directory.
Copy your application's executable into the <app-dir-name> directory. For example, after doing this, the simple application would have the following structure:
```
simple
      appinfo.json
      icon.png
      simple-executable
```
In the <app-dir-name> directory, create a new file in a text editor called package.properties. This file ensures the app binaries have executable permissions when installed.

Edit package.properties to have this one line:

filemode.755 = <relative-path-to-executable>

For example, for the simple application, it would look like this:

filemode.755 = simple

If your package makes use of multiple plug-ins, you can add entries for them separated by commas:

filemode.755 = simple, plugin2, plugin3,...

Create your installable package.
- Go to the parent directory of <app-dir-name>, i.e., C:\PalmApps.
- Run palm-package <app-dir-name>.
This command creates a package in the parent directory with the format:
```
com.<vendor>.app.<app-name>_<app-version>_all.ipk                       
```
For example:
```
C:\PalmApps\com.palm.app.simple_1.0.0_all.ipk                      
```
Note:

If you see an error similar to this:
```
palm-package: Expected a ',' or '}'at line 191                     
```
Then, in appinfo.json, you probably neglected to add a comma (',') at the end of the line before the added requiredMemory line.

This package file -- with the .ipk file extension -- is what you would submit to Palm if you would like to see your app distributed.
Install your package on the device.

Make sure your device is prepared and USB connected, then run the following command:
```
palm-install <package-name>                                    
```
For example:
```
C:\PalmApps> palm-install com.palm.app.simple_1.0.0_all.ipk                                     
```
You should now see your application and its icon listed in the Launcher menu. Tap its icon and it should launch.

Troubleshooting:

If you did not get an error message, but do not see your icon in the Launcher menu, check to make sure your icon is a .png file and not a .jpg or other format file. See Configuring Your Application's appinfo.json File.

Notes:

Once your project is created with palm-generate, you only need to use palm-package and palm-install as you continue to develop and test your app.

Configuring Your Application's appinfo.json File

Each application directory on the device must contain an appinfo.json file (JSON is short for JavaScript Object Notation, a lightweight computer data interchange format). The appinfo.json file provides information that the PDK framework uses to package and run the application.

Note:

If you use the PDK command-line tools for packaging and installing your app, the appinfo.json file is automatically transferred to its proper location on the device.

Format of appinfo.json file:

{
  "id": "<com.vendor.app.appname>",
  "version": "<x.x.x>",
  "vendor": "<vendor name>",
  "type": "pdk",
  "main": "<relative path to executable>",
  "title": "<application title>",
  "icon": "<relative path to icon>.png",
  "requiredMemory": <required memory in megabytes>
}

The following table lists the fields in appinfo.json.

Property	Description	Required	Example
id	Application's unique ID, created from reverse DNS naming conventions. The launcher uses the ID to uniquely identify your application and displays it with the title above. The application ID is unique, set once, and cannot be changed after publishing the application. The ID must be lower-case.	Yes	"com.palm.app.chess"
version	The application version number in major.minor.revision format. The major, minor, and revision numbers are all mandatory, non-negative integers. Leading zeros are stripped. The major, minor, and revision numbers are compared individually as whole numbers. For example, 1.5.3 would be considered an earlier version than 1.15.3. After uploading an application, the same version cannot be uploaded again. To update and re-upload an application, you must increase the version number.	Yes	"1.0.0"
vendor	Application vendor.	Yes	"Palm"
type	Must be "pdk" for pure C/C++ apps. Prior to release 1.4.5, "game" was allowed, but this is no longer the case. For hybrid apps, use "web".	Yes	"pdk"
main	The app executable. This is a file path relative to the location of the appinfo.json file.	Yes	"ChessApp"
title	The application's title as it shows in the Launcher and the app window. The application title is unique, set once, and cannot be changed after publishing the application.	Yes	"Chess"
icon	The file path relative to the `appinfo.json` file. The default is `icon.png`. If you use a different image, it must be a `.png` file. The image is re-sized to standard Launcher menu size.	No	"ChessIcon.png"
requiredMemory	Maximum application memory usage in megabytes.*	Yes	30

* See Configuring Application Memory for information on setting this field.

When the user taps on an icon, the system launches the executable referenced by the main attribute.

Example appinfo.json file (from the PDK simple sample application):

{
  "id": "com.palm.app.simple",
  "version": "1.0.0",
  "vendor": "Palm",
  "type": "pdk",
  "main": "simple/simple",
  "title": "Simple",
  "icon": "icon.png",
  "requiredMemory": 10
}

Developers can also use the appinfo.json file to contain any name/value data they find useful. An app can access this data with the PDL_GetAppinfoValue call.

Notes about JSON syntax:

Do not include any comments in json files (/* or //).
Must use double quotes around properties; no single quotes.

Configuring Application Memory

To ensure your application has enough memory to run, you must specify its maximum application memory usage (in megabytes) in the application's appinfo.json file.

For example:

 "requiredMemory": 32

The memory usage specified ensures two things:

The app can launch. If there is not enough device memory available to satisfy the stated memory usage, the application does not launch and the user is presented with a "you must dismiss cards" message. For this reason, it is important not to make this limit too large.
The app is not terminated. If the device becomes low on memory and the application is using more than its stated quota for 10 seconds, the application is terminated. For this reason, it is important not to make this limit too small.

Determining your application's memory usage

Use this procedure to help determine your application's memory usage. For demonstration purposes, we are going to use the simple sample application that came with the PDK.

To determine your application's memory usage:

Make sure the device is USB connected to your host PC.
Prepare the device.
Launch a program to access the device.
- In Windows, open a command prompt.
- On the Mac, launch the Terminal application.
Go to the sample application's directory.
- In Windows, go to C:\Program Files\HP webOS\PDK\share\samplecode\simple\windows.
- On the Mac, go to /opt/PalmPDK/share/samplecode/simple/mac.
Execute the runit.cmd script (PC) or runit.sh (Mac, ./runit.sh or "sh runit.sh"). This builds and transfers the simple app to the device.

Note:

For your app, you would follow steps 5 and 6 as enumerated in Application Development Process.

In a few seconds or less, the rotating red shape is visible on the device.
Log into the device.
Run the top command.

top provides an ongoing look at processor activity in real time. It displays a listing of the most CPU-intensive tasks on the system. After running the top command, a display similar to the following appears:

Note the row for simple under the COMMAND column. The RES (RESident memory) column indicates the simple application's current memory usage. In this case, it is 12MB.
Observe your application's memory usage over a period of time. You will see your application move up and down the list depending on its current CPU usage. It will usually be near the top when you are interacting with it.

Tips:
- To make your application's memory usage easier to observe, take note of its PID (Process ID) number in the PID column, then run the top command again with the -p option. This will display only your application in the table.
  
  For example: top -p 21471
- You can also use the -d option to change the amount of time between screen updates. The default is 3 seconds.
  
  For example (1 second delay): top -p 21471 -d 1
Take the application's maximum observed memory usage and add an additional amount as a buffer -- something on the order of 5-10 megabytes. This should be the number you enter for required memory in your application's appinfo.json file.

Example Complete Build, Package, and Install Process

The following procedure is provided to show you all the steps in a complete build, package, and installation of a device app. Once again, we are going to use the simple sample application that comes with the PDK.

Note:

This is going to be done using a Windows machine, but Mac users should have no problem determining equivalent commands and file locations for their platform.

To build, package, install, and launch an application:

Prepare your device.
Open a command prompt.
Create a C:\PalmApps directory.

In C:\PalmApps, create an empty project structure:

C:\PalmApps>palm-generate simple

The following message appears:

"Generating new app in C:\PalmApps\simple"

In a text editor, open C:\PalmApps\simple\appinfo.json. Initially, it appears like this:

{ 
  "id": "com.yourdomain.simple", 
  "version": "1.0.0", 
  "vendor": "My Company", 
  "type": "web", 
  "main": "index.html", 
  "title": "simple", 
  "icon": "icon.png" 
}

Change it to look like this and save it:

{ 
  "id": "com.mydomain.app.simple", 
  "version": "1.0.0", 
  "vendor": "My Company", 
  "type": "pdk", 
  "main": "simple", 
  "title": "simple", 
  "icon": "icon.png", 
  "requiredMemory": 10 
}

In a text editor, open a new file and type this:
```
filemode.755 = simple  
```
Save the file as C:\PalmApps\simple\package.properties.
Build the simple application:
- Go to C:\Program Files\HP webOS\PDK\share\samples\simple\src.
- Run the following command:
```
arm-none-linux-gnueabi-gcc -o simple simple.cpp "-I..\..\..\..\include" "-I..\..\..\..\include\SDL" "-L..\..\..\..\device\lib" -Wl,--allow-shlib-undefined -lSDL -lGLESv2 -lpdl
```
Note: This is being done for a Pre; for a Pixi, you may have to include the Pixi compiler options. See the section on Compiling for the Pre and Pixi in Building for the Device.

Mac users would use the following:
```
export PATH=$PATH:/opt/PalmPDK/arm-gcc/bin arm-none-linux-gnueabi-gcc -o simple simple.cpp -I/opt/PalmPDK/include -I/opt/PalmPDK/include/SDL --sysroot=/opt/PalmPDK/arm-gcc/sysroot -L/opt/PalmPDK/device/lib -Wl,--allow-shlib-undefined -lSDL -lGLESv2 -lpdl       
```
Notice that we are linking to device libraries (L..\..\..\device\lib). If we were building for the host PC, we would use the host libraries (L..\..\..\host\lib).

Ignore the warning messages that appear. These pertain to unresolved references that are resolved at run-time on the device.

This command creates a simple executable file.
Copy the newly-created simple executable to C:\PalmApps\simple\.
Run the following command:
```
C:\PalmApps>palm-package simple  
```
This creates a C:\PalmApps\com.mydomain.app.simple_1.0.0_all.ipk package file.
Make sure the device is prepared and USB connected.

Run the following command:

C:\PalmApps>palm-install com.mydomain.app.simple_1.0.0_all.ipk

The following message appears:

installing package com.mydomain.app.simple_1.0.0_all.ipk on device "castle-linux" {8fe37d5a9c7793af12fc0f6a129470721027d81b} usb 2376

There should now be a half-moon icon for simple in the launcher:

Tap the icon to launch the app and see the app's fullscreen red rotating shape.

Troubleshooting:

If you see this screen when you launch simple:

Then, check to make sure the "type" field in your appinfo.json file is "pdk" and not "web" or "game".

Documentation

Creating an Application Package

Using Command-Line Tools to Package and Install Your Application

To package, install and launch your application on the device

Configuring Your Application's appinfo.json File

Configuring Application Memory

Determining your application's memory usage

Example Complete Build, Package, and Install Process

Why webOS

Getting Started

Videos

Stay up to date