Command-Line Tools

Figure 1: Application Development Tools

The HP webOS SDK includes the following command-line development tools:

palm-generate - Generates basic applications and scenes.
palm-package - Packages a webOS application before installation on the Emulator or device.
palm-install - Installs a packaged application on the Emulator or device.
palm-launch - Launches an installed application on the Emulator or device.
palm-run - Packages, installs, and launches a webOS application, then follows the log output.
palm-log - Displays app log messages on the Emulator or device.
palm-help - Display help information.

palm-generate

Generates Enyo or Mojo applications.

Note:

With SDK version 3.0.4 the following is now supported:

Generating Enyo apps, which can be packaged for a device or Emulator, or inspected and debugged in a desktop (Safari or Chrome) browser.
The sanitizing of a specified app title or directory name (removing hyphens, spaces, etc.) before using it as a generated app's Enyo kind.

Usage

palm-generate [OPTION...] APP_DIR

Options

      Option                    Description
-f, --overwrite             Overwrite existing files
-l, --list                  List the available templates
-p, --property=PROPERTY     Set the property PROPERTY
-t, --template=TEMPLATE     Use the template named TEMPLATE
    --version               Display version info and exit
    --help                  Display this help and exit

Usage Notes

APP_DIR is the application directory. It will be created if it does not exist.

PROPERTY defines properties to be used during generation. Properties can beo specified as key-value pairs of the form "key=value" or as JSON objects of the form "{'key1':'value1', 'key2':'value2', ...}". Surrounding quotes are required in both cases.

TEMPLATE is the application template to use. If not specified, the default template is used ('new_app').

Examples

List the available templates

 palm-generate -l

Generate a "hello world" sample application in ~/projects/hello and set the title.

 palm-generate -t hello_app -p "title=My First App" ~/projects/hello

Generate a new application in ~/projects/newapp.

 palm-generate -t new_app ~/projects/newapp

Generate a new application in ~/projects/ticker and set the id, version, vendor and title.

 palm-generate -p "{'id':'com.example.ticker', 'version':'1.0.0', 'vendor':'My Shop', 'title':'Stock Ticker'}" ~/projects/ticker

Generate a new scene named "first" in ~/projects/ticker.

 palm-generate -t new_scene -p "name=first" ~/projects/ticker

Generate a new Enyo single-pane application in ~/projects/singlepane.

 palm-generate ~/projects/singlepane

Generate a new Enyo split-view application in ~/projects/splitview.

 palm-generate -t enyo_splitview ~/projects/splitview

Generate a new Enyo application in ~/projects/multipane and set the id,# version, vendor and title.

 palm-generate -t enyo_multipane -p "{'id':'com.example.multipane', 'version':'1.0.0', 'vendor':'My Shop', 'title':'MultiPane'}" ~/projects/multipane

palm-package

Prepares an application for installation by converting the files in the application directory to an .ipkg file that you can run on a webOS device or Emulator.

Usage

Usage 1: Create a package for webOS containing a single application.

 palm-package [OPTION...] APP_DIR

Usage 2: Create a package for webOS containing an application and/or services and accounts.

 palm-package [OPTION...] PKG_DIR [APP_DIR] [SERVICE_DIR...] [ACCOUNT_DIR...]

Options

The package filename is automatically generated from the id and version properties in the application's appinfo.json file.

         Option                        Description
    --check                    Check the application but don't package it
-o, --outdir=OUTPUT_DIR        Use OUTPUT_DIR as the output directory
    --exclude=PATTERN          Exclude files, given as a PATTERN
-X, --exclude-from=PATFILE     Exclude patterns listed in PATFILE
    --ignore-case              Ignore case when matching names
    --no-exclude-eclipse       Don't exclude Eclipse meta-data
    --no-exclude-hidden        Don't exclude hidden files
    --no-exclude-vcs           Don't exclude version control meta-data
    --no-exclude-ipk           Don't exclude .ipk files
-p, --property=PROPERTY        Set the property PROPERTY
    --use-v1-format            Generate packages in old format (apps only)
    --version                  Display version info and exit
    --help                     Display this help and exit

Usage Notes

APP_DIR is an application directory containing a valid appinfo.json file. Only one application directory is allowed.

PKG_DIR is a package info directory containing a valid packageinfo.json file. Only one package info directory is allowed.

SERVICE_DIR is a service directory containing a valid services.json file.

ACCOUNT_DIR is a account directory containing a valid account-templates.json file.

OUTPUT_DIR is the output directory where the package will be created. If not specified, the current directory is used.

PATTERN is a name-matching string which may contain the wildcards * and ?. Matching is case-sensitive unless the --ignore-case option is used.

PATFILE is a text file with one PATTERN per line. Matching is case-sensitive unless the --ignore-case option is used.

By default, palm-package will exclude meta-data files used by Eclipse plugins. Use the --no-exclude-eclipse option to include these files.

By default, palm-package will exclude hidden files. Use the --no-exclude-hidden option to include these files.

By default, palm-package will exclude meta-data files used by the following version control systems: CVS, RCS, SCCS, SVN, Arch, Bazaar, Mercurial, and Darcs. Use the --no-exclude-vcs option to include these files.

By default, palm-package will exclude ipk files. Use the --no-exclude-ipk option to include these files.

PROPERTY defines properties to be used during package creation. Properties can be specified as key-value pairs of the form "key=value" or as JSON objects of the form "{'key1':'value1', 'key2':'value2', ...}". Surrounding quotes are required in both cases.

If not specified, the package id and package version will be derived from the id and version properties in the application's appinfo.json file.

The filename of the newly created package will be derived from the package id and package version.

When developing a webOS 3.0 application using the Enyo framework, simply point the <script> tag in index.html at your local Enyo installation; when you run palm-package, the script will automatically change the URL to point to the location of Enyo on the device.

Note: To create a package compatible with webOS versions earlier than 2.0, use the "--use-v1-format" option. Only single-app packages (usage 1) are supported.

Examples

Create a package for the webOS application in ~/projects/Ticker.

 palm-package ~/projects/Ticker

Create a package for the webOS application in ~/projects/Ticker and set the output directory to ~/packages.

 palm-package -o ~/packages ~/projects/Ticker

Create a package for the webOS application in ~/projects/Ticker. Exclude all text files and the tests directory.

 palm-package --exclude="*.txt" --exclude="tests" ~/projects/Ticker

Create a package for a webOS application and service.

 palm-package ticker-info ticker-app ticker-service

palm-install

Installs or remove applications from a webOS device or Emulator.

Note:

You cannot install an application if the device is in USB mode or Media Sync mode; it must be in developer mode.

Usage

 palm-install [OPTION...] [PACKAGE | APP_ID]

Where:

[package] is the full path to the package ( .ipkg) file.

Options

      Option                 Description
-d, --device=DEVICE     Specify DEVICE to use
    --device-list       List the available devices
-l, --list              List the installed applications
-r, --remove            Remove applications instead of installing
    --version           Display version info and exit
    --help              Display this help and exit

Usage Notes

PACKAGE is the file path of the package to install, e.g. ~/projects/packages/com.example.app_1.0_all.ipk.

APP_ID is the id of the application to remove.

DEVICE is a unique identifier which matches a device name, type, or id (as returned by the device-list option). e.g. Use "usb" for a usb-connected device, or "tcp" for an Emulator (note: Emulator must be running). If not specified, the first device found is used.

Examples

Install package

palm-install ~/projects/packages/com.example.app_1.0_all.ipk

Remove application

palm-install -r com.example.app

List applications on default device

palm-install -l

List applications on usb device

palm-install -d usb -l

List applications on Emulator

palm-install -d tcp -l

palm-launch

Launches (or closes) an application on a webOS device or Emulator.

Usage

palm-launch [OPTION...] [APP_ID]

Where:

[APP_ID] is the application ID corresponding to the id property in the application's appinfo.json file.

Options

      Option                  Description
-c, --close             Close running applications instead of launching
-d, --device=DEVICE     Specify DEVICE to use
    --device-list       List the available devices
-f, --relaunch          Relaunch app (close and reopen)
-i, --inspect           Inspect the application
-q, --list-stages       List the running stages
-s, --stage=STAGE       Specify STAGE to inspect
-l, --list              List the installed applications
-p, --params=PARAMS     Set the launch parameters to PARAMS
    --version           Display version info and exit
    --help              Display help and exit

Usage Notes

APP_ID is the id of the application to launch (or close).

STAGE is the id of the application's stage (as returned by the --list-stages option).

PARAMS defines launch parameters to be passed when launching an application. It is specified as a key-value pair of the form "key:value" or as a JSON object. Surrounding quotes are required in both cases.

Examples

Launch application on default device

 palm-launch com.example.app

Launch application, passing in framework configuration options

 palm-launch -p "{mojoConfig: {debuggingEnabled:true,timingEnabled:true}}" com.example.app

Launch and inspect application

 palm-launch -i com.example.app

List stages of running application

 palm-launch -q com.example.app

Inspect specific stage of application

 palm-launch -i -s 1023 com.example.app

Close application

 palm-launch -c com.example.app

List applications on default device

 palm-launch -l

List applications on usb device

 palm-launch -d usb -l

List applications on Emulator

 palm-launch -d tcp -l

palm-run

Packages, installs, and launches a Palm webOS application, then follows the log output.

Usage

 palm-run [OPTION...] [DIR]...

Options

        Option                        Description
    --exclude=PATTERN          Exclude files, given as a PATTERN
-X, --exclude-from=PATFILE     Exclude patterns listed in PATFILE
    --ignore-case              Ignore case when matching names
    --no-exclude-eclipse       Don't exclude Eclipse meta-data
    --no-exclude-hidden        Don't exclude hidden files
    --no-exclude-vcs           Don't exclude version control meta-data
    --no-exclude-ipk           Don't exclude .ipk files
-p, --property=PROPERTY        Set the property PROPERTY
-d, --device=DEVICE            Specify DEVICE to use
    --device-list              List the available devices
-l, --list                     List the installed applications
    --version                  Display version info and exit
    --help                     Display this help and exit

Usage Notes

PATTERN is a name-matching string which may contain the wildcards * and ?. Matching is case-sensitive unless the --ignore-case option is used.

PATFILE is a text file with one PATTERN per line. Matching is case-sensitive unless the --ignore-case option is used.

By default, palm-run will exclude meta-data files used by Eclipse plugins. Use the --no-exclude-eclipse option to include these files.

By default, palm-run will exclude hidden files. Use the --no-exclude-hidden option to include these files.

By default, palm-run will exclude meta-data files used by following version control systems: CVS, RCS, SCCS, SVN, Arch, Bazaar, Mercurial, and Darcs. Use the --no-exclude-vcs option to include these files.

By default, palm-run will exclude ipk files. Use the --no-exclude-ipk option to include these files.

DEVICE is a unique identifier which matches a device name, type, or id (as returned by the device-list option). e.g. Use "usb" for a usb-connected device, or "tcp" for an emulator (note: Emulator must be running). If not specified, the first device found is used.

Examples

Package, install, and run the Palm application in ~/projects/Ticker.

 palm-run ~/projects/Ticker

List applications on default device

 palm-run -l

List applications on usb device

 palm-run -d usb -l

List applications on emulator

 palm-run -d tcp -l

palm-log

The palm-log tool displays log messages from an application on the Emulator or USB-connected HP webOS device. The log output is simpler and easier to read than the output in /var/log/messages, and the timestamp is the local time instead of GMT. You can also use palm-log to display the installed applications, which is useful for getting the ID of the application to log.

For information about creating log output from your application, see the Logging page. It is especially important to set the log level, which controls which information (errors, warnings, etc.) gets logged.

Note:

If you hit Ctrl-C while running palm-log on Windows, you will see the message: "terminate batch job (Y/N)?". It doesn't matter if you answer Y or N, since the palm-log tool has already stopped. This is not a bug; it's a Windows message that displays whenever a batch file is interrupted with Ctrl-C.

Usage

palm-log [OPTION...] [APP_ID]

Displays application logs from an application on a webOS device. The App ID is the application ID, as specified in the application's appinfo.json file. Example: com.mystuff.hello

Options

      Option                         Description
-d, --device=DEVICE              Specify DEVICE to use (emulator must be running)
    --device-list                List the available devices
-f, --follow                     Follow the log output (use Ctrl-C to terminate)
-l, --list                       List the installed applications
    --system-log-level=LEVEL     Set the system log level {error,warning, or info}. 
                                 Default is  error. For more detailed logging, use warning or info.
    --version                    Display version info and exit
    --help                       Display help and exit

Examples

Follow logs for app

palm-log -f com.example.app

Display logs for app

palm-log com.example.app

List applications on default device

palm-log -l

List applications on usb-connected device

palm-log -d usb -l

List applications on the Emulator

palm-log -d tcp -l

Set the system log level to "info"

palm-log --system-log-level info

Sample Output

$ palm-log -f com.palm.app.maps

connecting to device emulator

(96C3BC9CC41E8A2A440C265DEDB8FB048F35B30E:tcp:64640)

following logs for application com.palm.app.maps

[20090813-07:51:06.138630] info: loadRealPage: 452
[20090813-07:51:06.144874] info: palm system: true
[20090813-07:51:06.145419] info: prepare transition
[20090813-07:51:06.270742] info: =========> looking for palmInitFramework191_15
[20090813-07:51:06.271141] info: =========> Calling palmInitFramework191_15
[20090813-07:51:06.358450] info: Requested submission : 191.15
[20090813-07:51:06.359008] info: Current locale is en_us
[20090813-07:51:06.383186] info: MAPS App: AppAssistant
[20090813-07:51:06.384085] info: Maps: AppAssistant: maps-countrycode cookie exists us
[20090813-07:51:06.388776] info: Maps App: _startConnectionWatch
[20090813-07:51:06.388998] info: Maps App: onAppActivate creating new connectionInfoRequest

palm-help

Displays system and SDK information.

Usage

 palm-help [OPTION...]

Options

       Option                 Description
    --commands        List the available commands
    --sdk-info        Display SDK information
    --system-info     Display system information
    --version         Display version info and exit
    --help            Display help and exit

Note - The --system-info option returns a volumnious amount of information about your system and takes awhile to run.

Examples

Version information

  palm-help --version

  Version: 3.0.0b22

Commands

  palm-help --commands

  Available commands:

      palm-generate
      palm-help
      palm-install
      palm-launch
      palm-log
      palm-package
      palm-run

  Type "<command> --help" for usage information.

SDK information

  palm-help --sdk-info

  Component versions for HP webOS SDK
  =============================================
  HP webOS SDK Version          3.0.2
  HP webOS SDK Build            652
  Framework (enyo)              117
  Framework (mojo)              506
  Emulator ROM                  3041
  SDK Tools                     22
  SDK Tools - Emulator          24
  Enyo Framework                99
  Samples                       142413
  Reference Applications code...
      com.palm.app.maps at submission 35
      com.palm.app.email at submission 107.1
      com.palm.app.browser at submission 68
      com.palm.app.messaging at submission 58.2
      com.palm.app.photos at submission 60.2
      com.palm.app.notes at submission 22
 End of Reference Applications code
 Inspector                     2
 Novacom(32-bit)               76
 PDK                           115
 Build mark                    499303
 =============================================

. . .