grunt-tizen is a grunt plugin for installing, uninstalling, running and debugging applications on a Tizen device. It wraps sdb to push files to the device and operate its command line (c.f. Android's adb); and wraps pkgcmd and wrt-launcher on the device itself to manage the application lifecycle.
Apache version 2, copyright Intel Corporation Ltd. See LICENSE for more details.
Bug reports and feature requests are encouraged: please use the github issue tracker for the project to file them.
If you are interested in contributing code to the project, the HACKING.md file explains more about building grunt-tizen and running its test suite. Please ensure that any code you write has test coverage as close as possible to 100%. Pull requests should be targeted at the master branch.
This plugin requires Grunt ~0.4.0.
To use grunt-tizen in your own project, install it with:
npm install grunt-tizen --save-dev
Once the plugin has been installed, enable it with a line of JavaScript in your Gruntfile.js:
module.exports = function (grunt) {
grunt.loadNpmTasks('grunt-tizen');
// grunt.initConfig({ ... }) etc.
};
grunt-tizen has been tested on:
- Fedora 17 Linux (64bit)
- Windows 7 Enterprise (64bit)
grunt-tizen depends on the sdb command line tool. This is available for various platforms from http://download.tizen.org/tools/latest-release/.
It will also work with the version of sdb bundled with the Tizen IDE (located in <IDE root directory>\tools\sdb.exe).
You will also need a device running Tizen 2.1.
The device should be connected to the host running grunt via a USB connection. This plugin has not been tested with multiple simultaneous USB connections to Tizen devices. It is unlikely to work in such an environment.
If you want to use the asRoot option for the tizen task, you will need a very recent version of sdb with support for the "root" command. Note that this feature is undocumented, so you may have to do the following to test for its presence:
$ sdb root on
Switched to 'root' account mode
If you get the "Switched to 'root' account mode", your version of sdb supports asRoot.Note that all of the other tizen:* task options work with older versions of sdb, however.
Note: the version of Tizen used for testing grunt-tizen has a broken pkgcmd which will not allow installation by non-root users. So at the moment, a version of sdb which supports sdb root on/off is REQUIRED. The intention is to remove this requirement once pkgcmd is fixed.
Note that grunt-tizen does not package applications for deployment to Tizen. You will need another packaging tool (e.g. webtizen from the Tizen SDK or grunt-zipup) to package your application into a wgt file ready for deployment.
The shared configuration for both tasks (tizen_prepare and tizen) should be added to grunt.initConfig() as follows:
grunt.initConfig({
// ... other task configuration ...
tizen_configuration: {
// location on the device to install the tizen-app.sh script to
// (default: '/tmp')
tizenAppScriptDir: '/home/developer/',
// path to the config.xml file for the Tizen wgt file
// (default: 'config.xml')
configFile: 'data/config.xml',
// path to the sdb command (default: process.env.SDB or 'sdb')
sdbCmd: '/home/bilbo/bin/sdb'
}
});
The tizen-app.sh script is a shell script which runs on Tizen devices, wrapping native Tizen commands to make them simpler to call remotely via sdb shell. It also does some of the work to interpret error messages and output from the Tizen commands to simplify the grunt-tizen code. You can find it in the scripts directory of the grunt-tizen source.
Configuration for grunt-tizen tasks is described below.
This task automates pushing the tizen-app.sh script to the attached device, overwriting any file already in the specified location. It also applies a chmod +x to the script to make it executable.
The destination of the file is tizenAppScriptDir (from tizen_configuration) + 'tizen-app.sh'.
The task requires no configuration beyond that in the tizen_configuration section (see above).
Run it with:
grunt tizen_prepare
You only need to run this task once to put the script in place. Once you've done this, you should be able to use the full range of commands to the tizen task, as described below.
It is also possible to run the tizen-app.sh script independently of grunt-tizen: see the script for details of how to invoke it.
The tizen task wraps the sdb command to perform various actions with a project.
The tizen task is actually a multitask, but is typically used to run different actions on the target device, specified by an action option (see Options below).
Note that several tasks rely on metadata from a config.xml file (Tizen package configuration XML file). A minimal version of this might look like:
<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns="http://www.w3.org/ns/widgets"
xmlns:tizen="http://tizen.org/ns/widgets"
id="https://github.com/01org/tetesttest"
version="0.0.1"
viewmodes="fullscreen">
<name>MyApplication</name>
<icon src="icon.png"/>
<tizen:application id="myapplictn.7dhfyr7e7f"
package="myapplictn"
required_version="2.1"/>
<content src="index.html"/>
</widget>The important data here are the id and package of the tizen:application element. In grunt-tizen, these are referred to as the app ID and the package name respectively. These identifiers are required by the pkgcmd and wrt-launcher commands on the Tizen device. They are automagically provided to the tizen-app.sh script when certain tizen task subcommands are invoked.
It is also important to note that these tasks are intended for the control of a single application, with a single config.xml file, and are not intended to control multiple applications simultaneously.
Having said that, the Bridge API (in lib/bridge.js) provides a low-level wrapper around sdb which is not tied to a single config.xml file. Alternative grunt tasks could be defined on top of the Bridge API if more flexibility were needed.
type: boolean, default: false
If set to true, grunt-tizen attempts to run the action specified as the root user on the device. It does this by preceding the "real" action with a call to sdb root on, then calling the action, then calling sdb root off.
If the action fails, grunt-tizen will still attempt to call sdb root off to ensure that any further commands do not run as root.
If at any point you need to reset to the non-root user but are unable to do so via grunt-tizen, call the following directly instead:
$ sdb root off
type: string, mandatory
The action option specifies which subcommand to run. The available values are:
- push: Push one or more files to the device.
- install: Install one or more wgt files which are already on the device.
- uninstall: Uninstall an application which is already installed on the device.
- start: Start an application already installed on the device.
- stop: Stop an application which is running on the device.
- debug: Start an application on the device in debug mode.
- script: Run an arbitrary script/command on the device.
Each action has its own additional options, as described in the following sections.
-
localFiles
type: string | string[] | object, mandatory
-
If the value is a string, it is treated as a reference to a single file on the local filesystem. If a relative path, it is resolved relative to Gruntfile.js.
-
If an array of strings, this option is treated as a reference to multiple files on the local filesystem.
-
If an object, the value should have the following format:
localFiles: { pattern: 'foo/bar/*', filter: 'latest' }- The pattern property is a file glob pattern which is matched against local files.
- The filter property is optional. Currently only 'latest' is supported. If set to this value, only the most recent of the files matching pattern is pushed.
-
-
remoteDir
type: string, mandatory
The remote directory on the device to which the files specified by localFiles should be pushed.
The destination filename for a file is the basename of the local file joined to remoteDir.
-
chmod
type: string, default: null
The chmod string to apply to each file after it is pushed to the device, to set permissions for the file. This can be a symbolic string (e.g. 'a+x') or an octal one (e.g. '0777').
-
overwrite
type: boolean, default: true
If set to
true, any existing file with a matching file name will be overwritten. Iffalse, the action will fail if a file with the same path already exists on the device.
-
remoteFiles
type: string | string[] | object, mandatory
Specifies the paths of wgt files on the device which should be installed.
See push options > localFiles (above) for the acceptable values.
-
stopOnFailure
type: boolean, default: false
If the application cannot be uninstalled and this option is set to
true, grunt will exit with an error. Iffalse, any subsequent tasks will still run even if this task failed.
-
stopOnFailure
type: boolean, default: false
If the application cannot be started and this option is set to
true, grunt will exit with an error. Iffalse, any subsequent tasks will still run even if this task failed.
-
stopOnFailure
type: boolean, default: false
If the application cannot be stopped and this option is set to
true, grunt will exit with an error. Iffalse, any subsequent tasks will still run even if this task failed.
-
localPort
type: integer, default: 8888
If an application is started in debug mode, this specifies the local port which should be connected to the remote debug port on the device.
-
browserCmd
type: string, default: null
Command to open a browser with the debug window for the application. If set, grunt-tizen will attempt to run the specified browser.
The string should have a format like:
'google-chrome %URL%'The '%URL%' part of this provides a placeholder for grunt-tizen to insert the debug URL for the application.
At the moment, only Google Chrome is known to work as a debug client for Tizen apps.
-
stopOnFailure
type: boolean, default: false
If the application cannot be started and this option is set to
true, grunt will exit with an error. Iffalse, any subsequent tasks will still run even if this task failed.Note that if you are debugging and any step in the debug sequence fails (i.e. if a remote port cannot be established on the device, or the browserCmd is not set), grunt will exit anyway. This option only has an effect on the application start itself.
By default, running this action invokes the specified remoteScript like this:
remoteScript <package name> <app ID>
where:
-
<package name>is the value of thewidget.tizen:application@packageattribute in config.xml. -
<app URI>is the value of thewidget.tizen:application@idattribute in config.xml.
Extra arguments can be passed to the script by setting the args option.
Options:
-
remoteScript
type: string, mandatory
Remote path on the device of the script to be executed.
-
args
type: string[], default: []
Extra arguments to pass to the script.
grunt.initConfig({
tizen_configuration: {
tizenAppScriptDir: '/home/developer/',
configFile: 'config.xml',
sdbCmd: 'sdb'
},
tizen: {
push: {
action: 'push',
localFiles: {
pattern: 'build/*.wgt',
filter: 'latest'
},
remoteDir: '/home/developer/'
},
install: {
action: 'install',
remoteFiles: {
pattern: '/home/developer/*.wgt',
filter: 'latest'
}
},
uninstall: {
action: 'uninstall'
},
start: {
action: 'start',
stopOnFailure: true
},
stop: {
action: 'stop',
stopOnFailure: false
},
debug: {
action: 'debug',
browserCmd: 'google-chrome %URL%',
localPort: 9090,
stopOnFailure: true
}
}
});