mozilla/xpfe/bootstrap/init.d/README
This file describes the mechanism for installing and executing
initialization and termination scripts used to implement pluggable
shell scripts to modify the behaviour of SeaMonkey/FireFox/ThunderBird/SunBird.
File names in the mozilla/init.d/ and %user_profile%/init.d/
(for example ${HOME}/.mozilla/init.d/ for SeaMonkey) are of the form
[SK]nn<filename> where 'S' means "run this script at application startup",
'K' means "run this script at application termination", and 'nn' is the
sequence number for killing or starting the job.
When the application (e.g. SeaMonkey) starts scripts prefixed with 'S' are
executed (first those in the app's installation directory, then those in
user's profile directory), on termination those scripts prefixed with 'K'
are being executed (first those in user's profile dir, finally those in
mozilla's installation directory).
** Rules (for Mozilla Pluggable Init Script API Version 2):
* When executing each script a single argument is passed to it - argument
'stop' for scripts prefixed with 'K' and the argument 'start' for scripts
prefixed with 'S'.
An exception of this rule are scripts with the suffix *.sh - they are called
"inline" in the current shell process which starts/terminates the app. These
scripts have FULL ACCESS to all variables of the calling script (which means
these scripts can set/modify/unset environment variables used by the app).
Since these scripts run in the same shell the author of such scripts should
ensure that no namespace collisions occur (e.g. accidential modify variable
names used by the parent script).
* Any files which do not match the [SK][0-9][0-9]* pattern are FORBIDDEN
in ${HOME}/.mozilla/init.d/ and %dist_bin%/init.d/. The only
exception is this README file.
* The following environment variables are defined if ${MOZ_PIS_API} is equal
or greater than "2" (none of these variables is guranteed to exists before
API version "2"):
- "MOZ_PIS_API":
Integer value describing the version of the "Mozilla Pluggable Init Script
API". Current version is "2".
- "MOZ_PIS_MOZBINDIR":
Relative (!!) or absolute path to the location where the mozilla binary
is located.
- "MOZ_PIS_SESSION_PID":
Process id of the initial application launch script. In this case used as
session identifier. The value identifies the current application
session. Note that one user may run multiple application sessions (with
differnt profiles) in parallel. "stop"-scripts must ensure that they
only affect resources created by the "start"-script of the same session
(identified via "MOZ_PIS_SESSION_PID") and same machine (use 'uname -n'
on demand).
- "MOZ_PIS_USER_DIR":
Name of the user dir (e.g. ".mozilla" for Mozilla, ".phoenix" for Phoenix
etc.)
The full path to the users profile base directory can be constructed using
"${HOME}/${MOZ_PIS_USER_DIR}/"
- "HOME":
Absolute path to users home directory.
* Shell scripts must test the existence of any MOZ_PIS_*-variables before using
them. It may happen that any of these variables may not exists in a future
version of this API.
If any of the requested MOZ_PIS_*-variables is not set the script should print
an error message to stderr and exit with error code 1.
* Mozilla pluggable init shell scripts MUST NOT rely on any other variable names
than those starting with "MOZ_PIS_";
"HOME" is the only exception of this rule.
* The namespace "MOZ_PIS"/"moz_pis" is reserved for the "Mozilla Pluggable
Init Script API". Scripts MUST NOT use function names, file names or variable
name which start with "MOZ_PIS"/"moz_pis".
* Scripts ending with *.sh (=scripts called in the same shell process as the
mozilla startup script) MUST use their own name space for function and
variable names.
The usage of single-letter variable names (Example: ${i}) is STRICTLY
FORBIDDEN!
This rule does not apply to scripts which operate in their own child process.
* Scripts ending with *.sh (=scripts called in the same shell process as the
mozilla startup script) restricted to the Bourne Shell syntax.
Any extensions supported by ksh, ksh93, dtksh and bash are FORBIDDEN.
This restriction does not apply to non-inline shell scripts; they may choose
their interpreter freely (even #!/usr/bin/perl).
* Pluggable shell scripts must have the "readable" and "executable" permission
bit (e.g. chmod a+rx) set for "user", "group" and "others" when being placed
in */init.d/
* The only allowed way to test whether a mozilla supports the Mozilla Pluggable
Init Script API is to test for "$dist_bin/init.d/README".
The following fragment of a XPI install.js script illustrates the test:
-- snip --
/* Test whether this mozilla supports pluggable init shell scripts */
var fProgram = getFolder("Program");
var init_d_readme_path = getFolder(fProgram, "init.d/README");
logComment("# Checking whether '" + init_d_readme_path + "' exists.");
if (!File.exists(init_d_readme_path)) {
logComment("# init_d_readme_path missing");
alert("Your version of Mozilla does not support " +
"pluggable init shell scripts.\n" +
"You need at least Mozilla 1.7a (or later).");
cancelInstall(ACCESS_DENIED);
return;
}
-- snip --
* Scripts must be able to handle that "start" and "stop" are being called
multiple times (for example when one user works in different profiles).
The PIS framework provides "MOZ_PIS_SESSION_PID" to identify the current
running session.
* There is no gurantee that "stop"-scripts are being called. The user, admin
or a reboot may prevent the execution of the "stop" scripts; the "start"
scripts should include a check to cleanup orphaned resources (orphaned
resources can simply be identified via checking whether MOZ_PIS_SESSION_PID
is still a valid PID).
* Inline shell scripts are allowed to abort the start sequence with "exit".
This will PREVENT mozilla from being launched. USE THIS FUNCTIONALITY ONLY
in EMERGENCY cases or if the user has been asked (GUI etc.) to abort.
It is STRONGLY recommended to call 'moz_pis_startstop_scripts "stop"' to
ensure that the "stop"-scripts are being executed (please do not do that
from "stop" scripts, that will end in an endless loop).
Example:
-- snip --
if [ ! -f "/usr/local/lib/libgtk.so" ] ; then
echo "${0}: Fatal error: libgtk.so not found." 1>&2
moz_pis_startstop_scripts "stop"
exit 1
fi
-- snip --
** Rules (for Mozilla Pluggable Init Script API Version 3):
NOT DEFINED YET
# EOF.
