Interlisp.medley/docs/man-page/man_medley.html

<h1>NAME</h1>
<p><strong>medley</strong> — starts up Medley Interlisp</p>
<h1>SYNOPSIS</h1>
<p><strong>medley</strong> [ flags ... ] [ <em>SYSOUT_FILE</em> ] [ --
<em>PASS_ON_ARGS</em> ]</p>
<h1>DESCRIPTION</h1>
<p>Starts Medley Interlisp in a window.</p>
<h1>OPTIONS</h1>
<p><strong>MEDLEYDIR</strong> is an environment variable set by Medley
and used by many of the options described below. MEDLEYDIR is the top
level directory of the Medley installation that contains the specific
medley script that is invoked after all symbolic links are resolved. In
the standard global installation this will be
/usr/local/interlisp/medley. But Medley can be installed in multiple
places on any given machine and hence MEDLEYDIR is computed on each
invocation of medley.</p>
<h2>Flags</h2>
<dl>
<dt>-h, --help</dt>
<dd>
<p>Prints out a brief summary of the flags and arguments to medley.</p>
</dd>
<dt>-z [+], --man [+]</dt>
<dd>
<p>Show the man page for medley. If the <strong>+</strong> parameter is
specified, then no pager is used when displaying the man page.</p>
</dd>
<dt>-c [<em>FILE</em> | -], --config [<em>FILE</em> | -]</dt>
<dd>
<p>Use <em>FILE</em> as the config file for this run of Medley. See
information on <em>CONFIG FILE</em> below.</p>
<p>If the given value is “-”, then suppress the use of a config file for
this run of Medley.</p>
</dd>
<dt>-f, --full</dt>
<dd>
<p>Start Medley from the standard “full” sysout. full.sysout includes a
complete Interlisp and CommonLisp environment with a standard set of
development tools. It does not include any of the applications built
using Medley.</p>
<p>(See <em>SYSOUT_FILE</em> below for more information on starting
sysouts.)</p>
</dd>
<dt>-l, --lisp</dt>
<dd>
<p>Start Medley from the standard “lisp” sysout. lisp.sysout only
includes the basic Interlisp and CommonLisp environment.</p>
<p>(See <em>SYSOUT_FILE</em> below for more information on starting
sysouts.)</p>
</dd>
<dt>-a, --apps</dt>
<dd>
<p>Start Medley from the standard “apps” sysout. apps.sysout includes
everything in full.sysout plus Medley applications including Notecards,
Rooms and CLOS. It also includes pre-installed links to key Medley
documentation.</p>
<p>(See <em>SYSOUT_FILE</em> below for more information on starting
sysouts.)</p>
</dd>
<dt>-u, --continue</dt>
<dd>
<p>Nullify any prior setting of the sysout file (e.g., from the config
file) - causing Medley to start from the virtual memory file resulting
from the previous invocation (with the same values for –id and
–logindir), if any. If there is no matching virtual memory file, Medley
will start from the full.sysout (see -f/–full above).</p>
<p>Equivalent to “-y -”.</p>
<p>(See <em>SYSOUT FILE</em> section below.)</p>
</dd>
<dt>-y [<em>SYSOUT_FILE</em> | -], --sysout [<em>SYSOUT-FILE</em> |
-]</dt>
<dd>
<p>Start Medley from the specified <em>SYSOUT-FILE</em>. This is an
alternative to specifying the <em>SYSOUT-FILE</em> as the last argument
on the command line (but before any <em>PASS_ON_ARGS</em>). It can be
used to specify the <em>SYSOUT-FILE</em> in the config file (see
information on <em>CONFIG FILE</em> below).</p>
<p>If the given value is “-”, then any prior setting of the sysout file
(e.g., from the config file) is nullified (see -u/–continue above).</p>
<p>(See <em>SYSOUT FILE</em> section below.)</p>
</dd>
<dt>-e [+ | -], --interlisp [+ | -]</dt>
<dd>
<p>If value is “+” or no value, make the initial Exec window within
Medley be an Interlisp Exec. If value is “-”, make the initial Exec
window be the default XCL Exec.</p>
<p>This flag applies only when the –apps flag is used.</p>
</dd>
<dt>-n [+ | -], --noscroll [+ | -]</dt>
<dd>
<p>Medley ordinarily displays scroll bars to enable the user to pan the
Medley virtual display within the Medley window. This is true even when
the entire virtual display fits within the window.</p>
<p>Specifying “-n +” (–noscroll +) turns off scroll bars. Specifying “-n
-” (–scroll -) turns on scroll bars. Specifying -n (–noscroll) with no
value is equivalent to specifying “–noscroll +”.</p>
<p>Default is scroll bars off.</p>
<p>Note: If scroll bars are off and the virtual screen is larger than
the window, there will be no way to pan to the non-visible parts of the
virtual display.</p>
</dd>
<dt>-g [<em>WxH</em> | -], --geometry [<em>WxH</em> | -]</dt>
<dd>
<p>Sets the size of the X Window (or VNC window) that Medley runs in to
be Width x Height. (Full X Windows geometry specification with +X+Y is
not currently supported).</p>
<p>If a value of “-” is given, geometry is set to the default value.</p>
<p>If --geometry is not specified but --screensize is, then the window
size will be determined based on the --screensize values and the
--noscroll flag. If neither --geometry nor --screensize is provided,
then the window size is set to 1440x900 if --noscroll is set and
1462x922 if --noscroll is not set.</p>
<p>(Also see note below under <em>CONFIG FILE</em> on the use of
geometry and screensize in config files.)</p>
</dd>
<dt>-s [<em>WxH</em> | -], --screensize [<em>WxH</em> | -]</dt>
<dd>
<p>Sets the size of the virtual display as seen from Medley’s point of
view. The Medley window is an unscaled viewport onto this virtual
display.</p>
<p>If a value of “-” is given, screensize is set to the default
value.</p>
<p>If --screensize is not specified but --geometry is, then the virtual
display size will be set so that the entire virtual display fits into
the given window geometry. If neither --screensize nor --geometry is
provided, then the screen size is set to 1440x900.</p>
<p>(Also see note below under <em>CONFIG FILE</em> on the use of
geometry and screensize in config files.)</p>
</dd>
<dt>-ps [<em>N</em> | -], –pixelscale [<em>N</em> | -] **
<strong>Applicable only when display is SDL-based (e.g., on
Windows/Cygwin)</strong> **</dt>
<dd>
<p>Sets the pixel scaling factor to <em>N</em>, an integer</p>
<p>If value of “-” is given, the pixel scale factor is set to its
default of 1.</p>
</dd>
<dt>-t [<em>STRING</em> | -], --title [<em>STRING</em> | -]</dt>
<dd>
<p>Use <em>STRING</em> as title of Medley window.</p>
<p>If <em>STRING</em> includes the character sequence “%i”, then the
value of the id string (see –id flag below) prefixed by “::” will be
substituited for the “%i”. Example: if the id is “run_45” and
<em>STRING</em> is “Medley Interlisp %i”, then the actual window title
will be “Medley Interlisp :: run_45”.</p>
<p>If the value of “-” is given, sets the title to its default value
(“Medley Interlisp %i”).</p>
<p>This flag is ignored when when the --vnc flag is set.</p>
</dd>
<dt>-d [<em>:N</em> | -], --display [<em>:N</em> | -]</dt>
<dd>
<p>Use X display <em>:N</em>.</p>
<p>If value is “-”, reset display to its default value. Default value is
the value of $DISPLAY.</p>
<p>On platforms that support both SDL and X Windows, set the value of -d
(–display) to “SDL” to select using SDL instead of X Windows.</p>
<p>This flag is ignored on the Windows/Cygwin platform and when the
--vnc flag is set on Windows System for Linux.</p>
</dd>
<dt>-v [+ | -] , --vnc [+ | -] ** <strong>Applicable only to WSL
installations</strong> **</dt>
<dd>
<p>If value is “+” or no value is given, then use a VNC window running
on the Windows side instead of an X window. If value is “-”, then do not
use a VNC window, relying instead on a standard X Window.</p>
<p>A VNC window will folllow the Windows desktop scaling setting
allowing for much more usable Medley on high resolution displays. On
WSL, X windows do not scale well.</p>
<p>This flag is always set for WSL1 installations.</p>
</dd>
<dt>-i [<em>ID_STRING</em> | - | --], --id [<em>ID_STRING</em> | - |
--]</dt>
<dd>
<p>Use <em>ID_STRING</em> as the id for this run of Medley, unless the
given value is “-”, “--”, or “---”.</p>
<p>Only one instance of Medley can be run simultaneously for any given
id.</p>
<p><em>ID-STRING</em> can consist of any alphanumeric character plus the
underscore (_) character, ending (optionally) in a “+” character. If
<em>ID_STRING</em> ends with a “+” (including just a singleton “+”),
then Medley will add a number to the id to make it unique among
currently running Medley intsances.</p>
<p>If the given value is “-”, then the id will be (re)set to “default”
(e.g., if it was previously set in the config file). If it is “--”, then
id will be set to the basename of $MEDLEYDIR. If ID_STRING is “---”,
then id will be set to the basename of the parent directory of
$MEDLEYDIR.</p>
<p>Default id is “default”.</p>
</dd>
<dt>-m [<em>N</em> | -], --mem [<em>N</em> | -]</dt>
<dd>
<p>Set Medley to run in <em>N</em> MB of virtual memory. Defaults to
256MB.</p>
</dd>
</dl>
<p>If a value of “-” is given, resets to default value.</p>
<dl>
<dt>-p [<em>FILE</em> | -], --vmem [<em>FILE</em> | -]</dt>
<dd>
<p>Use <em>FILE</em> as the Medley virtual memory (vmem) store.
<em>FILE</em> must be writeable by the current user.</p>
<p>Care must be taken not to use the same vmem FILE for two instances of
Medley running simultaneously. The --id flag will not protect against
vmem collisions when the --vmem flag is used.</p>
<p>If the value “-” is given, then resets the vmem file to the
default.</p>
<p>Default is to store the vmem in LOGINDIR/vmem/lisp_III.virtualmem,
where III is the id of this Medley run (see --id flag above). See
--logindir below for setting of LOGINDIR.</p>
</dd>
<dt>-r [<em>FILE</em> | -], --greet [<em>FILE</em> | -]</dt>
<dd>
<p>Use <em>FILE</em> as the Medley greetfile.</p>
<p>If the given value is “-”, Medley will start up without using a
greetfile.</p>
<p>The default Medley greetfile is $MEDLEYDIR/greetfiles/MEDLEYDIR-INIT,
except when the --apps flag is used in which case it is
$MEDLEYDIR/greetfiles/APPS-INIT.</p>
<p>On Windows/Cygwin installations, <em>FILE</em> is specified in the
Medley file system, not the host Windows file system.</p>
</dd>
<dt>-cm [<em>FILE</em> | -], --rem.cm [<em>FILE</em> | -]</dt>
<dd>
<p>Use <em>FILE</em> as the REM.CM file that Medley reads and executes
at startup - after any greet files. Usually used only for loadups and
other maintenance operations .</p>
<p>If the given value is “-”, Medley will start up without using REM.CM
file.</p>
<p>There is no default Medley REM.CM file.</p>
<p>On Windows/Cygwin installations, <em>FILE</em> is specified in the
Medley file system, not the host Windows file system.</p>
</dd>
<dt>-x [<em>DIR</em> | - | –], --logindir [<em>DIR</em> | - | –]</dt>
<dd>
<p>Use <em>DIR</em> as LOGINDIR in Medley. <em>DIR</em> must be
writeable by the current user.</p>
<p>LOGINDIR is used by Medley as the working directory on start-up and
where it loads any “personal” initialization file from.</p>
<p>If the given value is “-”, then reset LOGINDIR to its default value.
If the given value is “–”, uses $MEDLEYDIR/logindir as LOGINDIR.</p>
<p>LOGINDIR defaults to $HOME/il.</p>
<p>On Windows/Cygwin installations, <em>FILE</em> is specified in the
Medley file system, not the host Windows file system.</p>
</dd>
<dt>-nh <em>Host:Port:Mac:Debug</em>, --nethub
<em>Host:Port:Mac:Debug</em></dt>
<dd>
<p>Set the parameters for using Nethub XNS networking. <em>Host</em> is
the full domain name of the nethub host. <em>Port</em> is the port on
<em>Host</em> that nethub is using. <em>Mac</em> is the Mac address that
this instance of Medley should use when contacting the nethub host.
<em>Debug</em> is the level of nethub debug information that should be
printed on stdout (value is 0, 1, or 2). A <em>Host</em> value is
required and serves to turn nethub functionality on. <em>Port</em>,
<em>Mac</em> and <em>Debug</em> parameters are optional and will default
if left off.</p>
<p>If any of the parameters have a value of “-”, any previous setting
(e.g., in a config file) for the parameter will be reset to the default
value - which in the case of <em>Host</em> is the null string, turning
nethub functionality off.</p>
</dd>
<dt>-nf, -NF, –nofork</dt>
<dd>
<p>No fork. Relevant only to the Medley loadup workflow.</p>
</dd>
<dt>-prog <em>EXE</em>, –maikoprog <em>EXE</em></dt>
<dd>
<p>Use <em>EXE</em> as the basename of the Maiko executable. Relevant
only to the Medley loadup workflow.</p>
</dd>
<dt>–maikodir <em>DIR</em></dt>
<dd>
<p>Use <em>DIR</em> as the directory containing the Maiko emulator. For
testing purposes only.</p>
</dd>
<dt>-cc [<em>FILE</em> | -], --repeat [<em>FILE</em> | -]</dt>
<dd>
<p>Run Medley once. And then as long as <em>FILE</em> exists and is
greater then zero length, repeatedly run Medley using <em>FILE</em> as
the REM.CM file that Medley reads and executes at startup. Each run of
Medley can change the contents of <em>FILE</em> to effect the subsequent
run of Medley. To end the cycle, Medley needs to delete <em>FILE</em>.
WIthin Medley, <em>FILE</em> can be found as the value of the
environment variable LDEREPEATCM.</p>
<p>On Windows/Cygwin installations, <em>FILE</em> is specified in the
Medley file system, not the host Windows file system.</p>
</dd>
<dt>-am, –automation</dt>
<dd>
<p>Useful only when using –vnc (and always on WSL1). When calling medley
as part of an automation script, often Medley will run for a very short
time (&lt; a couple of seconds). This can cause issues with medley code
that detects Xvnc server failures. Setting this flag notifies Medley
that very short Medley sessions are possible and the Xvnc error
detection needs to be adjusted accordingly.</p>
</dd>
<dt>-tg [<em>TAG</em> | -], --tag [<em>TAG</em> | -]</dt>
<dd>
<p>By default, sysout files are loaded from the MEDLEYDIR/loadups
directory. If “--tag <em>TAG</em>” is specified, then by default sysout
files are loaded from the MEDLEYDIR/loadups/tagged/TAG directory. The
sysouts in these directories are created using a loadups script with the
--tag flag set. See the loadup man page. If <em>TAG</em> is “-”, then
the name of the active git branch for MEDLEYDIR (if any) is used as
<em>TAG</em>.</p>
</dd>
</dl>
<h2>Other Options</h2>
<dl>
<dt><em>SYSOUT_FILE</em></dt>
<dd>
<p>The pathname of the file to use as a sysout for Medley to start from.
If SYSOUT_FILE is not provided and none of the flags (--apps, --full,
--lisp) is used, then Medley will start from the saved virtual memory
file from the previous session with the same ID_STRING as this run. If
no such virtual memory file exists, then Medley will start from the
standard full.sysout (equivalent to specifying the --full flag). On
Windows (Docker) installations, <em>SYSOUT_FILE</em> is specified in the
Medley file system, not the host Windows file system.</p>
</dd>
<dt><em>PASS_ON_ARGS</em></dt>
<dd>
<p>All arguments after the “--” flag, are passed unaltered to the Maiko
emulator.</p>
</dd>
</dl>
<h1>CONFIG FILE</h1>
<p>A config file can be used to “pre-specify” any of the above command
line arguments. The config file consists of command line arguments
(flags or flag-value pairs), <em>one per line</em>. These arguments are
read from the config file and prepended to the arguments actually given
on the command line. Since later arguments override earlier arguments,
any argument actually given on the command line will override a
conflicting argument given in the config file.</p>
<p>Unless specified using the -c (–config) argument, the default config
file will be $MEDLEYDIR/.medley_config, if it exists, and
$HOME/.medley_config, otherwise.</p>
<p>Specifying, “-c -” or “–config -” on the command line will suppress
the use of config files for the current run of Medley.</p>
<p><em>Note:</em> care must be taken when using -g (–geometry) and/or -s
(–screensize) arguments in config files. If only one of these is
specified, then the other is conputed. But if both are specified, then
the specified dimensions are used as given. Unexpected results can arise
if one is specified in the config file but the other is specified on the
command line. In this case, the two specified dimensions will be used as
given. It will not be the case, as might be expected, that the dimension
given in the config file will be overridden by a dimension computed from
the dimension given on the command line.</p>
<h1>OTHER FILES</h1>
<dl>
<dt>$HOME/il</dt>
<dd>
<p>Default Medley LOGINDIR</p>
</dd>
<dt>$HOME/il/vmem/lisp.virtualmem</dt>
<dd>
<p>Default virtual memory file</p>
</dd>
<dt>$HOME/il/INIT(.LCOM)</dt>
<dd>
<p>Default personal init file</p>
</dd>
<dt>$MEDLEYDIR/greetfiles/MEDLEYDIR-INIT(.LCOM)</dt>
<dd>
<p>Default Medley greetfile</p>
</dd>
</dl>
<h1>BUGS</h1>
<p>See GitHub Issues:
&lt;https://github.com/Interlisp/medley/issues&gt;</p>
<h1>COPYRIGHT</h1>
<p>Copyright(c) 2023-2024 by Interlisp.org</p>