Skip to content

Commit

Permalink
Merge pull request mozilla#707 from wbamberg/784865
Browse files Browse the repository at this point in the history 
Address review comments, and fix bug 784865: document the `system` module(cherry picked from commit 6d3b0f1)
  • Loading branch information
wbamberg committed Jan 18, 2013
1 parent 9f4bf2f commit acb4c2f
Show file tree
Hide file tree
Showing 2 changed files with 253 additions and 8 deletions.
17 changes: 9 additions & 8 deletions doc/dev-guide-source/cfx-tool.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -872,16 +872,17 @@ You can use the cfx `--static-args` option to pass arbitrary data to your
program. This may be especially useful if you run cfx from a script.

The value of `--static-args` must be a JSON string. The object encoded by the
JSON becomes the `staticArgs` member of the `options` object passed as the
first argument to your program's `main` function. The default value of
JSON becomes the `staticArgs` property of the
[`system` module](modules/sdk/system.html).

The default value of
`--static-args` is `"{}"` (an empty object), so you don't have to worry about
checking whether `staticArgs` exists in `options`.
checking whether `staticArgs` exists in `system`.

For example, if your `main.js` looks like this:
For example, if your add-on looks like this:

exports.main = function (options, callbacks) {
console.log(options.staticArgs.foo);
};
var system = require("sdk/system");
console.log(system.staticArgs.foo);

And you run cfx like this:

Expand All @@ -892,7 +893,7 @@ And you run cfx like this:
Then your console should contain this:

<pre>
info: Hello from the command line
info: my-addon: Hello from the command line
</pre>

The `--static-args` option is recognized by two of the package-specific
Expand Down
244 changes: 244 additions & 0 deletions doc/module-source/sdk/system.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,244 @@
<!-- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, You can obtain one at http://mozilla.org/MPL/2.0/. -->

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`](dev-guide/cfx-tool.html#arguments) 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`](modules/sdk/system.html#staticArgs) property.

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

## Quit the host application ##

To quit the host application, use the
[`exit()`](modules/sdk/system.html#exit(code)) function.

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

<api name="staticArgs">
@property {Object}

The JSON object that was passed via the
[`cfx --static-args` option](dev-guide/cfx-tool.html#arguments).

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:

<pre>
(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
</pre>

</api>

<api name="env">
@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.

</api>

<api name="exit">
@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.

</api>

<api name="pathFor">
@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"](https://developer.mozilla.org/en-US/docs/Code_snippets/File_I_O#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.

</api>

<api name="platform">
@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);
</api>

<api name="architecture">
@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);
</api>

<api name="compiler">
@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);
</api>

<api name="build">
@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);
</api>

<api name="id">
@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`](https://developer.mozilla.org/en-US/docs/Using_nsIXULAppInfo#ID).

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

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

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

</api>

<api name="version">
@property {String}
The version of the host application.

See [nsIXULAppInfo's `version`](https://developer.mozilla.org/en-US/docs/Using_nsIXULAppInfo#Version).

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

<api name="platformVersion">
@property {String}
The version of XULRunner that underlies the host application.

See [nsIXULAppInfo's `platformVersion`](https://developer.mozilla.org/en-US/docs/Using_nsIXULAppInfo#Platform_version).

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

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

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

0 comments on commit acb4c2f

Please sign in to comment.