a4b9099b80
This PR is an extensive revamp of the loadup scripts including the following changes: New omnibus script scripts/loadup which is meant to be the single interface to the loadup system. The man page for this script can be found here: https://online.interlisp.org/downloads/man_loadup.html The new loadup script allows you to restart the loadup process from any particular stage - init, mid, lisp, full, etc. For example, you can start the loadup from an existing init-mid.sysout and have it run thru creating the full.sysout. The call for this would be: ./scripts/loadup --target full --start mid. (See man page for all options to the loadup script as well as examples of their use.) In order to facilitate this target/start feature, the loadup workdir has been moved to a single location per MEDLEYDIR, specifically to MEDLEDIR/loadups/build. (Previously, it was different for every invocation in /tmp/loadups-$$) When restarting the loadup from, say, lisp.sysout, the script will look for the lisp.sysout to start from first in MEDLEYDIR/loadups and then in MEDLEYDIR/loadups/build. If the starting sysout is found in loadups, it will be copied (non-versioned) into the workdir before doing the loadup, overwriting whatever is already there. There is now a lock (MEDLEYDIR/loadups/build/lock) that prevents concurrent loadups from running (and very occassionally needs to be manually removed). At successful completion of a loadup run, the created .sysouts and other files are moved into the loadups directory as before (unless the --nocopy option is specified). BUT the build files - including the dribble files - are left in the working directory (i.e., in loadups/build) The loadup script now supersedes the former loadup-all.sh, loadup-full.sh and loadup-db.sh scripts. But I have left in their place scripts that call the new loadup script with the right options. loadup-all.sh is now just a link to the single loadup script, who's options are (hopefully) a superset of loadup-all.sh. All of the worker scripts (e.g., loadup-full-from-lisp.sh) have been updated to use better mechanisms to catch and report errors, including the new (LOGOUT T EXITCODE) feature. The main script has been updated to better catch errors in these worker scripts when they do happen. You can now specify a MAIKODIR for the loadup, either using the MAIKODIR env variable or thru the --maikodir command line option. All of the loadup scripts have been moved down one level into scripts/loadups. But there are links from the scripts/ directory into the scripts/loadups directory for all of the top-level legacy scripts - loadup-all.sh, loadup-db.sh, loadup-full.sh so that you do not have to change your own scripts unless you need to use some of the new features. More importantly, none of the github workflows need to change right now. The SYSOUTCOMMITS mechanism had to be changed since there is no guarantee that e.g., lisp.sysout and full.sysout are built on the same commit. So (ASSOC 'MEDLEY SYSOUTCOMMITS) now returns an assoc list of sysouts, e.g., ((INIT "aaa")(LISP "bbb")(FULL "ccc")(APPS "ddd")), showing the commits for the various layers of the loadup. The new loadup scheme allows different sysouts to be created from different commits, so there is an issue with RDSYS (and RDSYS.LCOM) being out of sync with one or more of the sysout in loadups. RDSYS(.LCOM) are copied into library when ever a loadup of the Init stage completes successfully (unless the -nocopy option is specified). The only way to solve this issue when it arises is to do a complete loadup from starter.sysout to full.sysout (or apps.sysout) to ensure evrything is built on the same commit.
270 lines
11 KiB
HTML
270 lines
11 KiB
HTML
<h1>NAME</h1>
|
||
<p><strong>loadup</strong> — runs a loadup procedure for Medley
|
||
Interlisp</p>
|
||
<h1>SYNOPSIS</h1>
|
||
<p><strong><MEDLEYDIR>/scripts/loadup</strong> [ options ... ]</p>
|
||
<h1>DESCRIPTION</h1>
|
||
<p>Runs all or part of the <strong>loadup</strong> procedure for Medley
|
||
Interlisp. The loadup procedure is used to create the standard sysout
|
||
files from which you can start a Medley session as well as other
|
||
standard files that are useful in running Medley. After cloning Medley
|
||
from GitHub or after making significant changes to the Medley source,
|
||
you need to run the loadup procedure to (re)create these standard
|
||
files.</p>
|
||
<p>The complete loadup procedure happens in 5 sequential stages with
|
||
each stage depending on successful completion of the previous stage.
|
||
There are two other non-sequential stages (Aux and DB), which depend
|
||
only on the completion of Stage 4 (full.sysout).</p>
|
||
<p>You need not run all 5 stages, depending on what sysout files you
|
||
need to create for your work. The target files created in each stage are
|
||
copied into a loadups directory (<MEDLEYDIR>/loadups). The
|
||
<em>medley</em> run script and other Medley tools look for these files
|
||
in the loadups directory.</p>
|
||
<p>The 5 sequential stages and their main products are:</p>
|
||
<blockquote>
|
||
<ol type="1">
|
||
<li><p><strong>Init:</strong> create an <em>init.dlinit</em> sysout
|
||
file. This init.dlinit file is used internally for Stage 2 and is not
|
||
copied into the loadups directory.</p></li>
|
||
</ol>
|
||
</blockquote>
|
||
<blockquote>
|
||
<ol start="2" type="1">
|
||
<li><p><strong>Mid:</strong> create an <em>init-mid.sysout</em>. This
|
||
init-mid.sysout is used only internally for Stage 3 and is not copied
|
||
into the loadups directory.</p></li>
|
||
</ol>
|
||
</blockquote>
|
||
<blockquote>
|
||
<ol start="3" type="1">
|
||
<li><p><strong>Lisp:</strong> create <em>lisp.sysout</em>. Lisp.sysout
|
||
has a minimal set of Medley’s functionality loaded and can be used as
|
||
the basis for running a stripped-down Medley session. Lisp.sysout is
|
||
copied into the loadups directory.</p></li>
|
||
</ol>
|
||
</blockquote>
|
||
<blockquote>
|
||
<ol start="4" type="1">
|
||
<li><p><strong>Full:</strong> create <em>full.sysout</em>. Full.sysout
|
||
has all of the “standard” set of Medley functionality loaded and is the
|
||
primary sysout used for running Medley sessions. Full.sysout is copied
|
||
into the loadups directory.</p></li>
|
||
</ol>
|
||
</blockquote>
|
||
<blockquote>
|
||
<ol start="5" type="1">
|
||
<li><p><strong>Apps:</strong>: create <em>apps.sysout</em>. Apps.sysout
|
||
includes everything in full.sysout plus the Medley applications Buttons,
|
||
CLOS, Rooms, and Notecards.</p></li>
|
||
</ol>
|
||
</blockquote>
|
||
<p>The two independent stages that can be run if the first 4 sequential
|
||
stages complete successfully are:</p>
|
||
<blockquote>
|
||
<ul>
|
||
<li><p><strong>Aux:</strong>: create the <em>whereis.hash</em> and
|
||
<em>exports.all</em> files. These are databases that are commonly used
|
||
when working on Medley source code. They are copied into the loadups
|
||
directory.</p></li>
|
||
<li><p><strong>DB:</strong>: creates the <em>fuller.database</em> file.
|
||
Fuller.database is a Mastercope database created by analyzing all of the
|
||
source code included in full.sysout. (Stage 4) Fuller.database is copied
|
||
into the loadups directory.</p></li>
|
||
</ul>
|
||
</blockquote>
|
||
<p>Loadup does all of its work in a work directory
|
||
(<MEDLEYDIR>loadups/build). The target files are copied from this
|
||
work directory to the loadups directory if the loadup is successful.
|
||
Each stage of the loadup also creates a dribble file containing the
|
||
terminal output from within the Medley environment. These dribble files
|
||
are not copied to the loadups directory, but remain available in the
|
||
work directory after the loadup completes.</p>
|
||
<p>Only one instance (per <MEDLEIDIR>) of loadup can be run at a
|
||
time. (The lock file is in the work directory and is named
|
||
<strong><em>lock</em></strong>. It can be removed in case of an
|
||
uncontrolled failure of the loadup procedure.)</p>
|
||
<p>Note: <strong>MEDLEYDIR</strong> is an environment variable set by
|
||
the loadup script. It is set to the top level directory of the Medley
|
||
installation that contains the specific loadup 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 loadup.</p>
|
||
<h1>OPTIONS</h1>
|
||
<dl>
|
||
<dt><strong>-z, --man, -man</strong></dt>
|
||
<dd>
|
||
<p>Print this manual page on the screen.</p>
|
||
</dd>
|
||
<dt><strong>-t STAGE, --target STAGE, -target STAGE</strong></dt>
|
||
<dd>
|
||
<p>Run the sequential loadup procedure until the STAGE is complete,
|
||
starting from the files created by the previously run STAGE specified in
|
||
the –start option.</p>
|
||
<p>STAGE can be one of the following:</p>
|
||
<blockquote>
|
||
<p>i, init, 1: Run the loadup sequence through Stage 1 (init.dlinit).
|
||
Init.dlinit is <em>not</em> copied into the loadups directory.</p>
|
||
</blockquote>
|
||
<blockquote>
|
||
<p>m, mid, 2: Run the loadup sequence through Stage 2 (init-mid.sysout).
|
||
Init-mid.sysout is <em>not</em> copied into the loadups directory.</p>
|
||
</blockquote>
|
||
<blockquote>
|
||
<p>l, lisp, 3: Run the loadup sequence through Stage 3 (lisp.sysout).
|
||
Lisp.sysout is copied into the loadups directory.</p>
|
||
</blockquote>
|
||
<blockquote>
|
||
<p>f, full, 4: Run the loadup sequence through Stage 4 (full.sysout).
|
||
Full.sysout is copied into the loadups directory.</p>
|
||
</blockquote>
|
||
<blockquote>
|
||
<p>a, apps, 5: Run the loadup sequence through Stage 5 (apps.sysout).
|
||
Also run the Aux stage as if –aux option had been specified. Apps.sysout
|
||
and the Aux files are copied into the loadups directory.</p>
|
||
</blockquote>
|
||
<blockquote>
|
||
<p>a-, apps-, 5-: Run the loadup sequence through Stage 5 (apps.sysout).
|
||
The Aux stage is not run unless otherwise specified. Apps.sysout is
|
||
copied into the loadups directory. Also run the Aux stage as if –aux
|
||
option had been specified.</p>
|
||
</blockquote>
|
||
</dd>
|
||
<dt><strong>-s STAGE --start STAGE, -start STAGE</strong></dt>
|
||
<dd>
|
||
<p>Start the loadup process using the files previously created by STAGE.
|
||
These files are looked for first in the loadups directory or, if not
|
||
found there, in the work directory. It is an error if the files created
|
||
by STAGE cannot be found.</p>
|
||
<p>STAGE can be one of the following:</p>
|
||
<blockquote>
|
||
<p>s, scratch, 0 : Start the loadup process from the beginning. This is
|
||
the default.</p>
|
||
</blockquote>
|
||
<blockquote>
|
||
<p>i, init, 1 : Start the loadup process using the files created by
|
||
Stage 1 (init.dlinit).</p>
|
||
</blockquote>
|
||
<blockquote>
|
||
<p>m, mid, 2 : Start the loadup process using the files created by Stage
|
||
2 (init-mid.sysout).</p>
|
||
</blockquote>
|
||
<blockquote>
|
||
<p>l, lisp, 3 : Start the loadup process using the files created by
|
||
Stage 3 (lisp.sysout)</p>
|
||
</blockquote>
|
||
<blockquote>
|
||
<p>f, full, 4 : Start the loadup process using the files created by
|
||
Stage 4 (full.sysout).</p>
|
||
</blockquote>
|
||
</dd>
|
||
<dt><strong>-x, --aux, -aux</strong></dt>
|
||
<dd>
|
||
<p>Run the Aux loadup stage, creating the <em>whereis.hash</em> and
|
||
<em>exports.all</em> files. If loadup completes successfully, these
|
||
files are copied into loadups.</p>
|
||
</dd>
|
||
<dt><strong>-b, --db, -db</strong></dt>
|
||
<dd>
|
||
<p>Run the DB loadup stage, creating the <em>fuller.database</em> file.
|
||
If this stage complete successfully, these files are copied into
|
||
loadups.</p>
|
||
</dd>
|
||
<dt><strong>-i, --init, -init, -1</strong></dt>
|
||
<dd>
|
||
<p>Synonym for “–target init”</p>
|
||
</dd>
|
||
<dt><strong>-m, --mid, -mid, -2</strong></dt>
|
||
<dd>
|
||
<p>Synonym for “–target mid”</p>
|
||
</dd>
|
||
<dt><strong>-l, --lisp, -lisp, -3</strong></dt>
|
||
<dd>
|
||
<p>Synonym for “–target lisp”</p>
|
||
</dd>
|
||
<dt><strong>-f, --full. -full, -4</strong></dt>
|
||
<dd>
|
||
<p>Synonym for “–target full”</p>
|
||
</dd>
|
||
<dt><strong>-a, --apps, -apps, -5</strong></dt>
|
||
<dd>
|
||
<p>Synonym for “–target apps”</p>
|
||
</dd>
|
||
<dt><strong>-a-, --apps-, -apps-, -5-</strong></dt>
|
||
<dd>
|
||
<p>Synonym for “–target apps”</p>
|
||
</dd>
|
||
<dt><strong>-nc, --nocopy, -nocopy</strong></dt>
|
||
<dd>
|
||
<p>Run the specified loadups, but do not copy results into loadups
|
||
directory.</p>
|
||
</dd>
|
||
<dt><strong>-tw, --thinw, -thinw</strong></dt>
|
||
<dd>
|
||
<p>Before running loadups (if any), thin the working directory by
|
||
deleting all versioned (<em>.~[0-9]</em>~) files.</p>
|
||
</dd>
|
||
<dt><strong>-tl, --thinl, -thinl</strong></dt>
|
||
<dd>
|
||
<p>Before running loadups (if any), thin the loadups directory by
|
||
deleting all versioned (<em>.~[0-9]</em>~) files.</p>
|
||
</dd>
|
||
<dt><strong>-d DIR --maikodir DIR, -maikodir DIR</strong></dt>
|
||
<dd>
|
||
<p>Use DIR as the directory from which to execute lde (Miko) when
|
||
running Medley in the loadup process. If this flag is not present, the
|
||
value of the environment variable MAIKODIR will be used instead. And if
|
||
MAIKODIR does not exist, then the default Maiko directory search within
|
||
Medley will be used.</p>
|
||
</dd>
|
||
</dl>
|
||
<h1>DEFAULTS</h1>
|
||
<p>The defaults for the Options context-dependent and somewhat
|
||
complicated due to the goal of maintaining compatibility with legacy
|
||
loadup scripts. All of the following defaults rules hold independent of
|
||
the –maikodir (-d) option.</p>
|
||
<ol type="1">
|
||
<li><p>If none of –target, –start, –aux, and –db are specified,
|
||
then:</p>
|
||
<p>1A. If neither –thinw nor –thinl are specified, the options default
|
||
to:</p>
|
||
<blockquote>
|
||
<p><strong>–target full –start 0 –aux</strong></p>
|
||
</blockquote>
|
||
<p>1B. If either –thinw or –thinl are specified, no loadups are
|
||
run.</p></li>
|
||
<li><p>If neither –start nor –target are specified but either -aux or
|
||
-db or both are, then –start defaults to <em>full</em> and –target is
|
||
irrelevant.</p></li>
|
||
<li><p>If –start is specified and –target is not, then –target defaults
|
||
to <em>full</em></p></li>
|
||
<li><p>If –target is specified and –start is not, then –start defaults
|
||
to <em>0</em></p></li>
|
||
</ol>
|
||
<h1>EXAMPLES</h1>
|
||
<p><strong>./loadup -full -s lisp</strong> : run loadup thru Stage 4
|
||
(full.sysout) starting from existing Stage 3 outputs (lisp.sysout).</p>
|
||
<p><strong>./loadup --target full --start lisp</strong> : run loadup
|
||
thru Stage 4 (full.sysout) starting from existing Stage 3 outputs
|
||
(lisp.sysout).</p>
|
||
<p><strong>./loadup -5 –aux</strong> : run loadup from the beginning
|
||
thru Stage 5 (apps.sysout) then run the Aux “stage” to create
|
||
<em>whereis.hash</em> and <em>exports.all</em></p>
|
||
<p><strong>./loadup -db</strong> : just run the DB “stage” starting from
|
||
an existing full.sysout; do not run any of the sequential stages.</p>
|
||
<p><strong>./loadup –maikodir ~/il/newmaiko</strong> : run loadup
|
||
sequence from beginning to full plus the loadup Aux stage, while using
|
||
<em>~/il/newmaiko</em> as the location for the lde executables when
|
||
running Medley.</p>
|
||
<p><strong>./loadup -full</strong> : run loadup sequence from beginning
|
||
thru full</p>
|
||
<p><strong>./loadup -apps</strong> : run loadup sequence from beginning
|
||
thru app. Also run the Aux stage loadup.</p>
|
||
<p><strong>./loadup -apps-</strong> : run loadup sequence from beginning
|
||
thru app. Do not run the Aux stage loadup.</p>
|
||
<h1>BUGS</h1>
|
||
<p>See GitHub Issues:
|
||
<https://github.com/Interlisp/medley/issues></p>
|
||
<h1>COPYRIGHT</h1>
|
||
<p>Copyright(c) 2025 by Interlisp.org</p>
|