Running and debugging apps

Running apps

When you're ready to run the app, you need to select a runtime from the Runtimes sidebar. If you don't have any available runtimes here, find out how to add some in Setting up runtimes.

The "play" button in the center of the WebIDE toolbar is now enabled: click it to install and run the app in the selected runtime:

Running a custom build step

For some use cases you need to run a custom command before pushing your app to the device. For example, you might want to satisfy JavaScript dependencies or minify CSS, or use WebIDE to develop Gaia apps or Cordova apps, both of which require a custom build step.

You can do this by including a file called "package.json" in the root of your app. This is the same file that's used to package a node.js library, so you might already have one in the root of your project. If you don't, you can create one for this purpose.

Inside package.json, WebIDE looks for a property called "webide". The table below summarises the syntax of "webide":

`webide`			Object containing instructions for WebIDE. This may contain two properties, both optional: "`prepackage`" and "`packageDir`".
	`prepackage`		Specifies a command-line command for WebIDE to run before pushing the app to the runtime. This may be a string, in which case the command is just executed as-is, or may be an object which must contain "`command`", and may contain any of "`env`", "`args`", and "`cwd`".
		`command`	The command to execute in the command shell. For example: "`echo`".
		`env`	Any environment variables to set. This is specified as an array of strings in the form "NAME=value". For example: `["NAME=world"]`
		`args`	Any arguments to pass along with the command. This is specified as an array of strings.
		`cwd`	The directory from which to run the command. This may be absolute or relative to the current directory.
	`packageDir`		The directory from which WebIDE should look for the app to push to the runtime. Use this if you want the project in WebIDE to be the source from which to build a packaged app. The build step specified in `prepackage` would place the built app in an output directory, you will specify the output directory in `packageDir`, and WebIDE will install the app from that output directory rather than the project directory. This property is optional, and if it's omitted WebIDE will package the app from the project root, just as if package.json was omitted.

A "package.json" to build a Gaia app:

{
  "webide": {
    "prepackage": {
      "command": "make",
      "env": ["APP=settings"],
      "cwd": "../.."
    },
    "packageDir": "../../build_stage/settings/"
  }
}

A "package.json" for working with Cordova:

{
  "webide": {
    "prepackage": "cordova prepare",
    "packageDir": "./platforms/firefoxos/www"
  }
}

WebIDE automatically detects Cordova apps, and if it decides that your app is a Cordova app, will automatically generate a "package.json" file with these contents. See Working with Cordova apps in WebIDE.

Debugging apps

To debug the app, click the wrench icon and the Developer Tools Toolbox appears, connected to your app:

Exactly which tools you'll have available depends on the runtime, but you will at least have the basics: the Inspector, Console, JavaScript Debugger, Style Editor, Profiler and Scratchpad. Just as in a web page, any changes you make in the tools are visible immediately in the app, but are not persistent. Conversely, any changes you make in the editor pane can be saved straight back to disk, but are not visible without restarting the app.

If you're interested in the performance of your apps, there are a few ways to measure their impact on the runtime in WebIDE:

The Monitor panel offers a good overview of a device's performance. This can help you detect problems, e.g. a sudden, excessive increase in an app's memory usage (leak).
The Profiler tool gives you a way to analyze a single app's footprint in great detail. This is especially useful when investigating a known performance problem.

Unrestricted app debugging (including certified apps, main process, etc.)

You can run the debugger against the simulator, b2g desktop, or a real device.

With the Simulator, while the runtime is selected you can see and debug not only your app but all apps running in that runtime, including certified apps:

However, when connecting to a real device we have a security policy in force:

On devices running Firefox OS versions up to 2.1, all installed apps on device that are not certified apps (so privileged and web / regular apps) appear in "Runtime Apps" by default.
On Firefox 2.1 and above, we changed this so that only apps installed via DevTools / WebIDE appear in "Runtime Apps", regardless of app type. We did this to protect potentially sensitive data that could be present in apps.

To remove this restriction:

The device must be running a development build of Firefox OS 1.2+
You must disable the DevTools restricted privileges setting.

To disable DevTools restricted privileges, connect to the runtime, and then, in Runtime sidebar go to "Runtime Info". The path then differs depending on what you are debugging against:

Real device
- If it can be rooted, clicking "request higher privileges" will enable unrestricted app debugging (Firefox OS will restart). You may need to select your device again in the 'Select Runtime' drop down.
- If it cannot be rooted, there is a developer setting available in Firefox OS 2.2 onwards called Reset and enable full DevTools — when activated this will wipe all user data (for security reasons), reset the device, and enable unrestricted priviledges on any device.
Simulator
- The simulators come with unrestricted app debugging enabled by default.
B2G desktop
- Manually edit the B2G desktop client preferences before connecting to enable unrestricted app debugging.

Now (or after a restart of the B2G desktop client) in WebIDE you should see all the apps on the device.

Debugging add-ons

Please note due to bug 1185464 it is not currently possible to debug add-ons with WebIDE.