gecko-dev/xpfe/bootstrap/init.d/README

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.