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.
- luna-send - On-device or Emulator command-line tool that sends commands to the System Manager.
Also in this document:
These tools run on any supported development platforms. To view a list of the tools installed on a Mac or Linux system (or Windows, with cygwin installed):
- Open a Command Prompt window.
- Type palm- and press TAB twice.
palm-generate
Generates applications and scenes.
Note: Currently, only generating Mojo apps is supported.
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 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.
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/helloand 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/tickerand 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
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 when the device is in USB mode or Media Sync mode. The device must be in Developer mode; see Enabling Developer Mode (below).
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).
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.
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.
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.
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 help information
Usage
palm-help
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
Examples
- List commands
palm-help --commands
- Display SDK info
palm-help --sdk-info
- Display system info
palm-help --system-info
luna-send
luna-send is a command-line tool accessible through a shell on the Emulator or a device. luna-send is mainly used to test calls to services accessible on the device bus through the luna System Manager.
Options
-h this help screen
-P send over the public bus (send over private bus is default)
-s send a signal
-a send specified appId in message (default is none)
-m service name (default is none)
-d turn debug logging on
-i turn on interactive mode
-t x average over x times getting one response
-n x exit interactive mode after x replies
-l number responses
-f format JSON responses usefully
-q apply specific query to responses (multiple queries may be supplied), e.g.:
-q 'returnValue' -q 'queues[0]'
Examples
- db8 - Delete a kind object
luna-send -n 1 -a com.palm.contacts luna://com.palm.db/delKind '{"id":"com.palm.test:1"}' {"returnValue":true}
- GPS - Get current location
luna-send -f -P -i palm://com.palm.location/getCurrentPosition '{"subscribe":true}' { "altitude": 0, "errorCode": 0, "heading": 0, "horizAccuracy": 20, "latitude": 37.390196, "longitude": -122.037845, "returnValue": true, "timestamp": 2147483647, "velocity": 0, "vertAccuracy": 0 }
- Key service - Subscribe to volume key status changes
luna-send -n -i palm://com.palm.keys/audio/status '{"subscribe":true}' { "returnValue": true, "subscribed": true } { "key": "volume_up", "state": "down" } { "key": "volume_up", "state": "up" } . . .
Enabling Developer Mode
To install and test applications on a HP webOS device, you need to enable developer mode.
Note:
Locking the phone with a PIN does not protect data on the device in developer mode. When developer mode is enabled, it is possible to use tools such as novaterm to access the device through the USB even if the phone is locked.
To enable developer mode, webOS 1.0-1.4.5
- In Card view or in the Launcher application, type the following: upupdowndownleftrightleftrightbastart
- Tap the resulting Developer Mode Enabler icon.
- In the application, move the Developer Mode slider to the On position.
- Tap Reset the Device. When reset is complete, Developer mode is enabled.
To enable developer mode, webOS 2.0
You can enable developer mode either from your phone's keypad (phones) or from Just Type (phones and TouchPad).
On an unactivated phone that has not been through the webOS "first use" (before creating a Palm Profile) procedure, the keypad method is your only option since Just Type is not accessible from a device in this state.
Keypad method
- Launch the phone app.
- On a GSM phone, press "#*DEVMODE#", followed by the call button. On a CDMA phone, press "##DEVMODE#". (If the device is GSM, and there is no SIM card, a screen might be displayed instructing you to install one. Just begin typing the "#*" and the phone app appears.) The Developer Mode scene is displayed.
- Select "On". You are prompted to reboot the device.
Just Type method
Note that this method is only for activated devices.
- From card view (that is, no apps active), type the following: upupdowndownleftrightleftrightbastart. The "Developer Mode" app appears.
- Move the Developer Mode slider to the On position.. The app dims momentarily and then Developer Mode is set.
Launching a Hidden App from Device Info
Beginning with webOS 3.0 (build #3025+), you no longer need to use the PhoneApp's dial-pad to run hidden applications such as "CollectLogs" and "USBPassthrough".
Because we cannot rely on the PhoneApp's dial-pad to be easily accessible, we added a new screen to the Device Info application to enter the codes for these applications.
To run a hidden application
-
Launch Device Info and tap its top-left menu.
-
Select "Custom Application..."
-
Enter the code you would have entered in the PhoneApp's dial-pad.
Notes:
-
Eventually, support for the PhoneApp dial-pad is going to be removed but, currently, its only unsupported 'hidden' application is the in-store demo.
-
You can use either the ## or #* prefix.
-
You can use either the numeric code (i.e., ##5647# ) or the alphabetic code (i.e., ##LOGS# ) from the normal keypad.
-
Entries for alphabetic codes are not case sensitive. For example, the following are identical: ##LOGS#, ##logs#, ##Logs#
-
"CollectLogs" will be hidden before the TouchPad ships.