Document means of executing Emacs from unrelated Android applications

* doc/emacs/android.texi (Android Environment): Document
significance, effect and purpose of EMACS_CLASS_PATH and
EMACS_LD_LIBRARY_PATH, and the utility of `pm path
org.gnu.emacs'.

1 files changed, 52 insertions, 11 deletions

diff --git a/doc/emacs/android.texi b/doc/emacs/android.texi
index 606c5e719cb..2d95f5c8fef 100644
--- a/doc/emacs/android.texi
+++ b/doc/emacs/android.texi
@@ -364,17 +364,58 @@ consult the values of the variables @code{ctags-program-name},
 @code{ebrowse-program-name}, and @code{rcs2log-program-name}.
 @xref{Subprocess Creation,,, elisp, the Emacs Lisp Reference Manual}.
 
-  The @file{/assets} directory containing Emacs start-up files is
-meant to be inaccessible to processes not directly created by
-@code{zygote}, the system service responsible for starting
-applications.  Since required Lisp is found in the @file{/assets}
-directory, it would thus follow that it is not possible for Emacs to
-start itself as a subprocess.  A special binary named
-@command{libandroid-emacs.so} is provided with Emacs, which tries its
-best to start Emacs for the purpose of running Lisp in batch mode.
-However, the approach it takes was devised by reading Android source
-code, and is not sanctioned by the Android compatibility definition
-documents, so your mileage may vary.
+  The @file{/assets} directory containing Emacs start-up files is meant
+to be inaccessible to processes not directly created by @code{zygote},
+the system service responsible for starting applications.  Since
+required Lisp is found in the @file{/assets} directory, it would thus
+follow that it is not possible for Emacs to start itself as a
+subprocess.  A special binary named @command{libandroid-emacs.so} is
+provided with Emacs, which is installed into the library directory, and
+which tries its best to start Emacs for the purpose of running Lisp in
+batch mode.  The approach it takes was devised by reference to Android
+source code, and is not sanctioned by the Android compatibility
+definition documents, so your mileage may vary.
+
+@cindex EMACS_CLASS_PATH environment variable, Android
+  Even when the location of the @command{libandroid-emacs.so} command is
+known in advance, special configuration is required to run Emacs from
+elsewhere than a subprocess of an existing Emacs session, as it must be
+made to understand the location of resources and shared libraries in or
+extracted from the installed application package.  The OS command
+@command{pm path org.gnu.emacs} will print the location of the
+application package, and the adjacent @file{lib} directory will hold
+shared libraries extracted from the same, though the said command must
+be invoked in a peculiar manner to satisfy system restrictions on
+communication between pseudoterminal devices created by user
+applications and system services such as the package manager, which is
+to say, with the standard IO streams redirected to a real file or a
+pipe.  Such values, once established, must be specified in the
+environment variables @code{EMACS_CLASS_PATH} and
+@code{EMACS_LD_LIBRARY_PATH}, so that this sample shell script may be
+installed as @code{emacs} in any location that is accessible:
+
+@example
+#!/system/bin/sh
+
+package_name=`pm path org.gnu.emacs 2>/dev/null </dev/null \
+               | sed 's/^package://'`
+emacs=
+ld_path=
+EMACS_CLASS_PATH=$package_name
+
+for libdir in `dirname $package_name`/lib/*; do
+  ld_path=$@{ld_path:+$@{ld_path@}:@}$libdir
+  test -x "$libdir"/libandroid-emacs.so \
+    && emacs="$libdir"/libandroid-emacs.so
+done
+
+EMACS_LD_LIBRARY_PATH=$ld_path
+
+export EMACS_CLASS_PATH
+export EMACS_LD_LIBRARY_PATH
+test -x "$emacs" || exit 1
+exec $emacs "$@@"
+@end example
 
 @cindex call-process, Android
 @vindex android-use-exec-loader