michael@0: # subprocess michael@0: michael@0: michael@0: 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. michael@0: michael@0: `subprocess.jsm` is originally from [http://hg.mozilla.org/ipccode/](http://hg.mozilla.org/ipccode/). michael@0: michael@0: How to Use subprocess.jsm in your Add-on michael@0: ---------------------------------------- michael@0: michael@0: 1. copy subprocess.jsm and subprocess_worker_*.js into the modules/ directory michael@0: of your add-on. michael@0: michael@0: 2. add this line to chrome.manifest: michael@0: resource EXTENSION modules/ michael@0: michael@0: 3. import it where needed: michael@0: Components.utils.import("resource://EXTENSION/subprocess.jsm"); michael@0: michael@0: This object allows to start a process, and read/write data to/from it michael@0: using stdin/stdout/stderr streams. michael@0: michael@0: Usage example: michael@0: michael@0: var p = subprocess.call({ michael@0: command: '/bin/foo', michael@0: arguments: ['-v', 'foo'], michael@0: environment: [ "XYZ=abc", "MYVAR=def" ], michael@0: charset: 'UTF-8', michael@0: workdir: '/home/foo', michael@0: //stdin: "some value to write to stdin\nfoobar", michael@0: stdin: function(stdin) { michael@0: stdin.write("some value to write to stdin\nfoobar"); michael@0: stdin.close(); michael@0: }, michael@0: stdout: function(data) { michael@0: dump("got data on stdout:" + data + "\n"); michael@0: }, michael@0: stderr: function(data) { michael@0: dump("got data on stderr:" + data + "\n"); michael@0: }, michael@0: done: function(result) { michael@0: dump("process terminated with " + result.exitCode + "\n"); michael@0: }, michael@0: mergeStderr: false michael@0: }); michael@0: michael@0: p.wait(); // wait for the subprocess to terminate, michael@0: // this will block the main thread, michael@0: // only do if you can wait that long michael@0: michael@0: michael@0: Description of subprocess.call(...) Parameters michael@0: ---------------------------------------------- michael@0: Apart from , all arguments are optional. michael@0: michael@0: command: either a |nsIFile| object pointing to an executable file or a michael@0: String containing the platform-dependent path to an executable michael@0: file. michael@0: michael@0: arguments: optional string array containing the arguments to the command. michael@0: michael@0: environment: optional string array containing environment variables to pass michael@0: to the command. The array elements must have the form michael@0: "VAR=data". Please note that if environment is defined, it michael@0: replaces any existing environment variables for the subprocess. michael@0: michael@0: charset: Output is decoded with given charset and a string is returned. michael@0: If charset is undefined, "UTF-8" is used as default. michael@0: To get binary data, set this to null and the returned string michael@0: is not decoded in any way. michael@0: michael@0: workdir: Optional; either a |nsIFile| object or string containing the michael@0: platform-dependent path to a directory to become the current michael@0: working directory of the subprocess. michael@0: michael@0: stdin: Optional input data for the process to be passed on standard michael@0: input. stdin can either be a string or a function. michael@0: A |string| gets written to stdin and stdin gets closed; michael@0: A |function| gets passed an object with write and close function. michael@0: Please note that the write() function will return almost immediately; michael@0: data is always written asynchronously on a separate thread. michael@0: michael@0: stdout: An optional function that can receive output data from the michael@0: process. The stdout-function is called asynchronously; it can be michael@0: called mutliple times during the execution of a process. michael@0: At a minimum at each occurance of \n or \r. michael@0: Please note that null-characters might need to be escaped michael@0: with something like 'data.replace(/\0/g, "\\0");'. michael@0: michael@0: stderr: An optional function that can receive stderr data from the michael@0: process. The stderr-function is called asynchronously; it can be michael@0: called mutliple times during the execution of a process. Please michael@0: note that null-characters might need to be escaped with michael@0: something like 'data.replace(/\0/g, "\\0");'. michael@0: (on windows it only gets called once right now) michael@0: michael@0: done: Optional function that is called when the process has terminated. michael@0: The exit code from the process available via result.exitCode. If michael@0: stdout is not defined, then the output from stdout is available michael@0: via result.stdout. stderr data is in result.stderr michael@0: michael@0: mergeStderr: Optional boolean value. If true, stderr is merged with stdout; michael@0: no data will be provided to stderr. michael@0: michael@0: michael@0: Description of object returned by subprocess.call(...) michael@0: ------------------------------------------------------ michael@0: The object returned by subprocess.call offers a few methods that can be michael@0: executed: michael@0: michael@0: wait(): waits for the subprocess to terminate. It is not required to use michael@0: wait; done will be called in any case when the subprocess terminated. michael@0: michael@0: kill(): kill the subprocess. Any open pipes will be closed and michael@0: done will be called. michael@0: michael@0: michael@0: Other methods exported by subprocess michael@0: ------------------------------------ michael@0: The following functions help debugging and provide logging facilities. michael@0: michael@0: registerDebugHandler(functionRef): register a handler that is called to get michael@0: debugging information michael@0: registerLogHandler(functionRef): register a handler that is called to get error michael@0: messages michael@0: michael@0: example: michael@0: subprocess.registerLogHandler( function(s) { dump(s); } );