tubestation/addon-sdk/source/doc/module-source/sdk/system.md

The system module enables an add-on to get information about the environment it's running in, access arguments passed to it via the cfx --static-args option, and quit the host application.

Querying Your Environment

Using the system module you can access environment variables (such as PATH), find out which operating system your add-on is running on and get information about the host application (for example, Firefox or Fennec), such as its version.

var system = require("sdk/system");
// PATH environment variable
console.log(system.env.PATH);
// operating system
console.log("platform = " + system.platform);
// processor architecture
console.log("architecture = " + system.architecture);
// compiler used to build host application
console.log("compiler = " + system.compiler);
// host application build identifier
console.log("build = " + system.build);
// host application UUID
console.log("id = " + system.id);
// host application name
console.log("name = " + system.name);
// host application version
console.log("version = " + system.version);
// host application vendor
console.log("vendor = " + system.vendor);
// host application profile directory
console.log("profile directory = " + system.pathFor("ProfD"));

Accessing --static-args

Static arguments are accessible by name as properties of the staticArgs property.

var system = require("sdk/system");
console.log(system.staticArgs.foo);

Quit the host application

To quit the host application, use the exit() function.

var system = require("sdk/system");
system.exit();

@property {Object}

The JSON object that was passed via the cfx --static-args option.

For example, suppose your add-on includes code like this:

var system = require("sdk/system");
console.log(system.staticArgs.foo);

If you pass it a static argument named "foo" using --static-args, then the value of "foo" will be written to the console:

(addon-sdk)~/my-addons/system > cfx run --static-args="{ \"foo\": \"Hello\" }"
Using binary at '/Applications/Firefox.app/Contents/MacOS/firefox-bin'.
Using profile at '/var/folders/me/DVFDGavr5GDFGDtU/-Tmp-/tmpOCTgL3.mozrunner'.
info: system: Hello

@property {Object}

This object provides access to environment variables.

You can get the value of an environment variable by accessing the property with that name:

var system = require("sdk/system");
console.log(system.env.PATH);

You can test whether a variable exists by checking whether a property with that name exists:

var system = require("sdk/system");
if ('PATH' in system.env) {
  console.log("PATH is set");
}

You can set a variable by setting the property:

var system = require("sdk/system");
system.env.FOO = "bar";
console.log(system.env.FOO);

You can unset a variable by deleting the property:

var system = require("sdk/system");
delete system.env.FOO;

You can't enumerate environment variables.

@function

Quits the host application with the specified code. If code is omitted, exit() uses the success code 0. To exit with failure use 1.

var system = require("sdk/system");
system.exit();

@param code {integer} To exit with failure, set this to 1. To exit with success, omit this argument.

@function

Firefox enables you to get the path to certain "special" directories, such as the desktop or the profile directory. This function exposes that functionality to add-on authors.

For the full list of "special" directories and their IDs, see "Getting_files in special directories".

For example:

// get Firefox profile path
var profilePath = require('sdk/system').pathFor('ProfD');
// get OS temp files directory (/tmp)
var temps = require('sdk/system').pathFor('TmpD');
// get OS desktop path for an active user (~/Desktop on linux
// or C:\Documents and Settings\username\Desktop on windows).
var desktopPath = require('sdk/system').pathFor('Desk');

@param id {String} The ID of the special directory. @returns {String} The path to the directory.

@property {String} The type of operating system you're running on. This will be one of the values listed as [OS_TARGET](https://developer.mozilla.org/en-US/docs/OS_TARGET), converted to lower case.

var system = require("sdk/system");
console.log("platform = " + system.platform);

@property {String} The type of processor architecture you're running on. This will be one of: `"arm"``, `"ia32"`, or `"x64"`.

var system = require("sdk/system");
console.log("architecture = " + system.architecture);

@property {String} The type of compiler used to build the host application. For example: `"msvc"`, `"n32"`, `"gcc2"`, `"gcc3"`, `"sunc"`, `"ibmc"`

var system = require("sdk/system");
console.log("compiler = " + system.compiler);

@property {String} An identifier for the specific build, derived from the build date. This is useful if you're trying to target individual nightly builds. See [nsIXULAppInfo's `appBuildID`](https://developer.mozilla.org/en-US/docs/Using_nsIXULAppInfo#Version).

var system = require("sdk/system");
console.log("build = " + system.build);

@property {String} The UUID for the host application. For example, `"{ec8030f7-c20a-464f-9b0e-13a3a9e97384}"` for Firefox. This has traditionally been in the form `"{AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE}"` but for some applications it may be in the form `"appname@vendor.tld"`.

See nsIXULAppInfo's ID.

var system = require("sdk/system");
console.log("id = " + system.id);

@property {String} The human-readable name for the host application. For example, "Firefox".

var system = require("sdk/system");
console.log("name = " + system.name);

@property {String} The version of the host application.

See nsIXULAppInfo's version.

var system = require("sdk/system");
console.log("version = " + system.version);

@property {String} The version of XULRunner that underlies the host application.

See nsIXULAppInfo's platformVersion.

var system = require("sdk/system");
console.log("XULRunner version = " + system.platformVersion);

@property {String} The name of the host application's vendor, for example: `"Mozilla"`.

var system = require("sdk/system");
console.log("vendor = " + system.vendor);