summaryrefslogtreecommitdiffstats
path: root/txr.1
diff options
context:
space:
mode:
authorKaz Kylheku <kaz@kylheku.com>2016-05-25 21:38:36 -0700
committerKaz Kylheku <kaz@kylheku.com>2016-05-25 21:38:36 -0700
commitd59b921c8ec271ed5861b54186519a09f617aaee (patch)
treedc8378a5570c7d91e281ce76084e108c5780c4f9 /txr.1
parentf492fa9b676e95dbf317ec3b34d085909713da73 (diff)
downloadtxr-d59b921c8ec271ed5861b54186519a09f617aaee.tar.gz
txr-d59b921c8ec271ed5861b54186519a09f617aaee.tar.bz2
txr-d59b921c8ec271ed5861b54186519a09f617aaee.zip
Stand-alone application support.
* txr.c (sysroot_init): Don't print "unable to calculate sysroot" error message in the fallback case, and use the absolute path of the executable directory as the sysroot in this case. (txr_main): Define static area prefixed by @(txr): header. If a string is present in this data area then process it as an argument. Treat the *args* variable carefully. If we use the stored string as the argument, save the args in orig_args variable, then later bind *args* to that. In the -e, -p and related options processing, we bind *args* to the original list so args are available to the expression being evaluated. If the expression mutates *args* then we keep the mutated args whether or not we are processing the stored string. * txr.1: Documented in new sction, STAND-ALONE APPLICATION SUPPORT.
Diffstat (limited to 'txr.1')
-rw-r--r--txr.1107
1 files changed, 107 insertions, 0 deletions
diff --git a/txr.1 b/txr.1
index 4ad3ebbb..ebb4d7dc 100644
--- a/txr.1
+++ b/txr.1
@@ -42479,6 +42479,113 @@ running with setuid privilege. No group IDs are added to the list which
need to be retracted when privileges are dropped. The supplementary
groups also persist across the execution of a setuid/setgid script.
+.SH* STAND-ALONE APPLICATION SUPPORT
+
+The \*(TX executable image supports a general mechanism by means of which
+a custom program can be packaged as an apparent stand-alone executable.
+
+.SS* The Internal Argument String
+
+The \*(TX executable contains a 128 byte data area preceded by the
+seven-byte ASCII character sequence
+.strn @(txr): .
+The 128 byte data area which follows this identifying prefix
+represents a null-terminated UTF-8 string. In the stock executable,
+this area is filled with null bytes.
+
+If the \*(TX executable is edited such that this area is replaced
+with a non-empty, null-terminated UTF-8 string, the program will,
+for the purposes of command line argument processing, treat this string as if
+it were the one and only command line argument. (The original command
+line arguments are still retained in the
+.code *args*
+and
+.code *args-full*
+variables).
+
+.TP* Example:
+
+Suppose that \*(TX is copied to an executable in the same directory called
+.code myapp
+(or
+.code myapp.exe
+on an operating system which requires the
+.code .exe
+suffix). Also suppose that in the same directory, there exists a file
+called
+.codn myscript.tl .
+
+This
+.code myapp
+executable can then be edited so that the data area which follows the
+.code @(txr):
+bytes contains the following string:
+
+.cblk
+ --args|-e|(load `@{txr-path}/main.tl`)
+.cble
+
+When the
+.code myapp
+executable is invoked, it will process the above string as a single
+command line argument, causing the
+.code main.tl
+\*(TL source file to be loaded.
+Any arguments passed to
+.code myapp
+are ignored and available to
+.code main.tl
+via the
+.code *args*
+variable.
+
+.SS* Deployment Directory Structure
+
+The \*(TX executable may require library files, depending on the
+functionality invoked by the program code. Library files are located
+relative to the installation directory, called the
+.IR sysroot .
+The executable tries to dynamically determine the sysroot from
+its own location, according to this directory structure:
+
+.cblk
+ /path/to/sysroot/bin/txr
+ .../share/txr/stdlib/cadr.tl
+ .../stdlib/except.tl
+ ...
+.cble
+
+The above structure is assumed if the executable finds itself
+in a directory named
+.strn bin .
+
+Otherwise, if the executable finds itself in a directory not
+named
+.strn bin ,
+the following structure is expected:
+
+.cblk
+ /path/to/installation/txr
+ .../share/txr/stdlib/cadr.tl
+ .../share/txr/stdlib/except.tl
+ ...
+.cble
+
+When a custom application is deployed using a possibly renamed
+.code txr
+executable, one of the above structures should be observed:
+either the sysroot with a
+.code bin
+subdirectory where the executable is located, on the
+same level with the
+.code share
+directory, or else the second structure in which the
+.code share
+directory is a subdirectory of the executable directory.
+If one of these structures is not observed, the application
+may fail due to the failure of a library file to load.
+
+
.SH* DEBUGGER
\*(TX has a simple, crude, built-in debugger. The debugger is invoked by adding
the