1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/addon-sdk/source/lib/sdk/system/child_process/README.md Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,129 @@
1.4 +# subprocess
1.5 +
1.6 +
1.7 +Created by [Jan Gerber](j@mailb.org), with contributions from [Patrick Brunschwig](patrick@enigmail.net), subprocess.jsm is used as the underlying library, supporting the Addon-SDK's implementation of Node's `child-process` API.
1.8 +
1.9 +`subprocess.jsm` is originally from [http://hg.mozilla.org/ipccode/](http://hg.mozilla.org/ipccode/).
1.10 +
1.11 +How to Use subprocess.jsm in your Add-on
1.12 +----------------------------------------
1.13 +
1.14 +1. copy subprocess.jsm and subprocess_worker_*.js into the modules/ directory
1.15 + of your add-on.
1.16 +
1.17 +2. add this line to chrome.manifest:
1.18 + resource EXTENSION modules/
1.19 +
1.20 +3. import it where needed:
1.21 + Components.utils.import("resource://EXTENSION/subprocess.jsm");
1.22 +
1.23 +This object allows to start a process, and read/write data to/from it
1.24 +using stdin/stdout/stderr streams.
1.25 +
1.26 +Usage example:
1.27 +
1.28 + var p = subprocess.call({
1.29 + command: '/bin/foo',
1.30 + arguments: ['-v', 'foo'],
1.31 + environment: [ "XYZ=abc", "MYVAR=def" ],
1.32 + charset: 'UTF-8',
1.33 + workdir: '/home/foo',
1.34 + //stdin: "some value to write to stdin\nfoobar",
1.35 + stdin: function(stdin) {
1.36 + stdin.write("some value to write to stdin\nfoobar");
1.37 + stdin.close();
1.38 + },
1.39 + stdout: function(data) {
1.40 + dump("got data on stdout:" + data + "\n");
1.41 + },
1.42 + stderr: function(data) {
1.43 + dump("got data on stderr:" + data + "\n");
1.44 + },
1.45 + done: function(result) {
1.46 + dump("process terminated with " + result.exitCode + "\n");
1.47 + },
1.48 + mergeStderr: false
1.49 + });
1.50 +
1.51 + p.wait(); // wait for the subprocess to terminate,
1.52 + // this will block the main thread,
1.53 + // only do if you can wait that long
1.54 +
1.55 +
1.56 +Description of subprocess.call(...) Parameters
1.57 +----------------------------------------------
1.58 +Apart from <command>, all arguments are optional.
1.59 +
1.60 + command: either a |nsIFile| object pointing to an executable file or a
1.61 + String containing the platform-dependent path to an executable
1.62 + file.
1.63 +
1.64 + arguments: optional string array containing the arguments to the command.
1.65 +
1.66 + environment: optional string array containing environment variables to pass
1.67 + to the command. The array elements must have the form
1.68 + "VAR=data". Please note that if environment is defined, it
1.69 + replaces any existing environment variables for the subprocess.
1.70 +
1.71 + charset: Output is decoded with given charset and a string is returned.
1.72 + If charset is undefined, "UTF-8" is used as default.
1.73 + To get binary data, set this to null and the returned string
1.74 + is not decoded in any way.
1.75 +
1.76 + workdir: Optional; either a |nsIFile| object or string containing the
1.77 + platform-dependent path to a directory to become the current
1.78 + working directory of the subprocess.
1.79 +
1.80 + stdin: Optional input data for the process to be passed on standard
1.81 + input. stdin can either be a string or a function.
1.82 + A |string| gets written to stdin and stdin gets closed;
1.83 + A |function| gets passed an object with write and close function.
1.84 + Please note that the write() function will return almost immediately;
1.85 + data is always written asynchronously on a separate thread.
1.86 +
1.87 + stdout: An optional function that can receive output data from the
1.88 + process. The stdout-function is called asynchronously; it can be
1.89 + called mutliple times during the execution of a process.
1.90 + At a minimum at each occurance of \n or \r.
1.91 + Please note that null-characters might need to be escaped
1.92 + with something like 'data.replace(/\0/g, "\\0");'.
1.93 +
1.94 + stderr: An optional function that can receive stderr data from the
1.95 + process. The stderr-function is called asynchronously; it can be
1.96 + called mutliple times during the execution of a process. Please
1.97 + note that null-characters might need to be escaped with
1.98 + something like 'data.replace(/\0/g, "\\0");'.
1.99 + (on windows it only gets called once right now)
1.100 +
1.101 + done: Optional function that is called when the process has terminated.
1.102 + The exit code from the process available via result.exitCode. If
1.103 + stdout is not defined, then the output from stdout is available
1.104 + via result.stdout. stderr data is in result.stderr
1.105 +
1.106 + mergeStderr: Optional boolean value. If true, stderr is merged with stdout;
1.107 + no data will be provided to stderr.
1.108 +
1.109 +
1.110 +Description of object returned by subprocess.call(...)
1.111 +------------------------------------------------------
1.112 +The object returned by subprocess.call offers a few methods that can be
1.113 +executed:
1.114 +
1.115 + wait(): waits for the subprocess to terminate. It is not required to use
1.116 + wait; done will be called in any case when the subprocess terminated.
1.117 +
1.118 + kill(): kill the subprocess. Any open pipes will be closed and
1.119 + done will be called.
1.120 +
1.121 +
1.122 +Other methods exported by subprocess
1.123 +------------------------------------
1.124 +The following functions help debugging and provide logging facilities.
1.125 +
1.126 + registerDebugHandler(functionRef): register a handler that is called to get
1.127 + debugging information
1.128 + registerLogHandler(functionRef): register a handler that is called to get error
1.129 + messages
1.130 +
1.131 + example:
1.132 + subprocess.registerLogHandler( function(s) { dump(s); } );
