This is the multi-page printable view of this section. Click here to print.
This section contains information on installing or setting up Medley and using it.
Access Medley Online: how to access Medley running on our servers using your web browser.
Install and Run: how to set Medley up on your computer, and restart each time.
Using Medley: Once you are up and running, some basics and pointers to other documentation.
Coming: Running Medley in the browser!!
You can install Medley on a variety of different computer systems.
Medley has a virtual machine architecture: there’s a virtual machine implementation (called Maiko) and Lisp software that is compiled into instructions for it. The compiled code and memory images can be moved from one architecture to another – only Maiko needs to be ported. Maiko has been substantially revised and modernized, so you can to run Medley on many different OSes and machine architectures.
See the Maiko README and Medley README in their respective GitHub repository pages for more details on how to build and run them.
The current systems we’ve tested or for which we have confirmed reports can be found in the Maiko github repository, including:
Medley can run on any Linux system that includes X Windows and a number of others.
For Windows users of System For Linux (WSL) on Windows 11 and Windows 10 Build 19044+, there are separate instructions.
We recommend the Linux system have a web browser installed. A browser is not strictly necessary to run Medley, but several features of the system (e.g., displaying some user documentation) will not work without an external browser installed.
Medley can be installed on your Linux system in one of two configurations: standard and local.
We are currently only building standard installations for Debian-based systems (i.e., systems that support dpkg).
In a standard installation, Medley is installed in system directories (specifically, /usr/local/interlisp). Support-like man pages and (a link to) the medley executable are also installed in standard system locations (e.g., /usr/local/man and /usr/local/bin).
Standard installations are ideal for users who want to explore Medley (including its system code) or to develop applications built on top of Medley. Standard installations are not good for users who want to modify the Medley system code, since that code is installed in protected locations.
Standard installation uses apt to install a .deb package downloaded from
the Medley downloads site.
The .deb package will install Medley as well as any other packages needed for Medley to run.
Use a browser to download from the .deb package for your platform (i.e., “standard” Linux or WSL) and your machine architecture (X86_64, ARM64, or ARMv7) to <deb_filepath> from the Medley downloads site
Enter the following in a terminal to install the download:
ubuntu@oio:~$ sudo apt update
ubuntu@oio:~$ sudo apt install -y <deb_filepath>
Enter the following in a terminal to run medley:
ubuntu@oio:~$ medley
There are many options to the medley command. For a brief overview, run medley --help.
For a more complete description, run man medley or medley --man or click
here.
For first-time users: medley --apps or for WSL medley --apps --vnc is a good starting
point. This will give you a fully populated Medley system, including the applications built on Medley such as Notecards and Rooms.
medley will create a directory in $HOME/il. This will be used by the Medley
system as its LOGINDIR. Medley will start up with LOGINDIR as its current connected directory.
It will load the personal init file (if any) from LOGINDIR/INIT or LOGINDIR/INIT.LCOM. Finally,
Medley will use LOGINDIR/vmem/ to store its virtual memory file(s). The location of LOGINDIR
can be changed using the --logindir option to medley.In a local installation, the Medley system is installed into any user directory from a .tar file. Multiple “Medleys” can be installed in different directories on one machine without interference (except see description of Medley LOGINDIR below). Local installation makes it easy (from a file management p.o.v.) to modify the Medley system code.
Local installation doesn’t involve a package manager, so you are responsible for installing any prerequisite packages onto your system before you install Medley.
Also note that with local installations, man medley will not work. However, as indicated below,
./medley --man will show the medley man page.
Install prerequite packages
For non-WSL installations, use your distro’s package manager to install xdg-utils.
For WSL all installations, use your distro’s package manager to install wslu.
Note that some distros do not include wslu in their standard repos. See
https://wslutiliti.es/wslu/install.html
for installation instructions if this is the case.
Also note that wslu v4.0 does not work with Medley, so you will need to install
either a version < v.40 or >= v4.1.
For WSL installations where the VNC feature will be used, install the tigervnc-standalone-server and tigervnc-xorg-extension packages.
When using the VNC feature Medley will display in a VNC Window instead of a standard X Window. This is useful on high resolution displays since the VNC window will scale according to the Windows Settings->Display->Scale setting, while the X Window on WSL will not so scale.
Note that Medley will install and run even if none of these prerequite packages are installed. However, some features (e.g., viewing documentation in an external browser) will be inoperable.
Download
Using a browser download from
the Medley downloads site
the tar (.tgz) file for your platform (i.e., “standard” Linux or WSL) and your machine
architecture (X86_64, ARM64, or ARMv7) to <tar_filepath>.
Note that on WSL, <tar_filepath> will depend on whether the browser was started in Windows or in WSL. If downloading to the standard Downloads folder, using a WSL-based browser <tar_filepath> will be in ~/Downloads. If using a Windows-based browser, <tar_filepath> will be in /mnt/c/Users/<username>/Downloads.
Install Medley
In a terminal:
ubuntu@oio:~$ mkdir <interlisp_directory>
ubuntu@oio:~$ tar -C <interlisp_directory> -xzf <tar_filepath>
Run Medley
In a terminal:
ubuntu@oio:~$ cd <interlisp_directory>/medley
ubuntu@oio:~$ ./medley
There are many options to the medley command. For a brief overview, run ./medley --help.
For a more complete description, run ./medley --man or click
here.
For first-time users: ./medley --apps or for WSL (and you have installed the VNC prerequisites)
./medley --apps --vnc is a good starting point. This will give you a fully populated Medley system,
including the applications built on Medley such as Notecards and Rooms.
medley will create a directory in $HOME/il. This will be used by the Medley
system as its LOGINDIR. Medley will start up LOGINDIR as its current connected directory.
It will load any personal init file from LOGINDIR/INIT or LOGINDIR/INIT.LCOM. Finally,
Medley will use LOGINDIR/vmem/ to store its virtual memory file(s). The location of LOGINDIR
can be changed using the --logindir option to medley. In particular, if you have multiple
installations of Medley that you would like to keep completely separate, then you can use the
--logindir - option, which will set LOGINDIR to <medley_directory>/logindir.Medley on WSL involves installing and maintaining the WSL subsystem within Windows. And when installing and using Medley on WSL you are working within Linux. Some familiarity with Linux and the Linux command line is helpful. Medley on WSL is best for users who are running WSL anyway and/or prefer working in a Linux environment. Medley sees the WSL file system, and Windows files appear under “/mnt/c/”, e.g., Windows download will be in “/mnt/c/Users/yourname/Downloads”).
Medley will run on either WSL1 or WSL2. WSL2 is preferred, but for older machines that do not support virtualization (see here) or Windows builds prior to Windows 10 Build 19041, WSL1 will work just fine although it will be limited to the VNC mode (see below).
For WSL installations, the browser(s) on the Windows side will suffice.
There are release configurations for Debian-based systems; i.e., systems that support dpkg), including Debian-based distros on WSL.
In the Medley downloads site get the release asset for WSL and your host machine type (X86_64, ARM64, ARMv7).
The WSL packages differ only in that they include an additional functionality to have Medley display in a VNC Window instead of a standard X Window. This is useful on high resolution displays since the VNC window will scale according to the Windows Settings->Display->Scale setting, while the X Window on WSL will not so scale. The WSL packages also install the wslu package, which is used by Medley to connect to external browsers as described above. Aside from these two features, a non-WSL .deb package will install and run on WSL.
<deb_filepath> from the Medley downloads site<deb_filepath> will depend on whether the browser was started in Windows or in WSL:
<deb_filepath> will be in ~/Downloads.
<deb_filepath> will be in /mnt/c/Users/<username>/Downloads.Get the Installer Download the MacOS installer from the latest release page.
Run Medley
Unzip the medley-full-macos-universal...zip file on your computer. Run the medley/run-medley script in the unzipped folder to start Medley.
Need XCode Need XQuartz installed before you build maiko (includes XClient libraries).
emulate 3-button mouse
Running Medley on Windows can be done with some ease if you have WSL (Windows System for Linux). There’s now also the possibility a “native” install.
The two ways result in similar Medley experiences, but differ in how Medley is installed and run, how the Windows file system is seen, and possibly some unforeseen challenges (the “native” install is relatively new).
Medley native works within the ordinary Windows environment. Installation uses standard Windows installer and you start Medley from a standard Command (or Powershell) window. Medley native is best for users who prefer to stay (almost) exclusively in the Windows environment.
Medley on WSL and native Medley both require 64-bit Windows 10/11.
When running on Windows natively, Medley will be installed into a directory (of your choice). This directory will contain an isolated copy of the Cygwin environment and a version of Medley that runs within that specific Cygwin environment. This complexity, however, is largely hidden from the user and Medley behaves as if it is a native Windows app.
Download the Medley Windows installer from under the Windows 10/11 heading here.
Start the Medley installation app (e.g., by double clicking on the .exe just downloaded).
The installation app will ask for the directory in which to install Medley. Any directory that you have read/write access to will suffice. (We will refer to this directory as the Medley install_dir.)
The installation app will then copy the Medley files into the specified directory. It will also run the Cygwin installer to install Cygwin into the specified directory as well.
**Note:** To run the installation app, you may have to bypass the Windows security protections against running .exe files downloaded from the web. For example, if the following dialog appears, you will need to select the `More info` link and then click on the `Run anyway` button that appears.
Run Medley: Once it is installed, you can start Medley from either a Command window or a Powershell window. You cannot (currently) start Medley from the Start Menu or from an icon on the desktop.
From a Command window, type:
cd <install_dir>
medley <flags and options>
From a Powershell window, type:
cd <install_dir>
cmd /C medley <flags and options>
Documentation for the <flags and options> to the medley command can be found here
For first-time users: medley --apps --interlisp --noscroll or, equivalently, medley -a -e -n is a good starting point. This will give you a fully populated Medley system, including the applications built on Medley such as Notecards and Rooms.
Your Medley LOGINDIR will be /home/<name>/il (or <install_dir>\home\<name>\il from the Windows perspective), where <name> is your Windows username. Medley code is stored in /medley (or <install_dir>\medley from the Windows perspective).
Also, from within Medley you can refer to any file in the Windows file system using /<drive letter>/<windows path using “/” instead of “\">. Example: C:\User\Frank\Downloads\foo in Windows will be /c/User/Frank/Downloads/foo in Medley. (Note that this means that within Medley, /medley/foo and /c/<install_dir>/medley/foo will be references to the same Windows file.)
If you want to work with the Medley code using git, etc. You will probably find it easier to work with git within Cygwin rather than work with git in Windows. To work within the Medley-specific Cygwin, within a Powershell or Command window:
cd <install_dir>
.\bin\bash -login
This will get you a bash terminal running under the Medley-specific Cygwin - which means that the file mappings will be the same as in Medley.
The Medley-specific Cygwin install is rather minimal, so if you find you need other Linux tools to work with the Medley code, the Cygwin setup tool (which also functions as its package manager) is available at <install_dir>\cygwin\setup_x86_64.exe (in Windows) or at /cygwin/setup_x86_64.exe (from within Cygwin bash).
Running Interlisp online is good for experimenting and introducing yourself to the environment. However, anything you create in the online environment should be treated as transient. If you’re interested in developing and experimenting with Lisp programs, you will want to investigate other options. For a first foray, it is a good starting point.
Go to Interlisp Online
Interlisp Online Login 
Login to Medley Interlisp Online:
on the login screen. However, guest sessions are not saved.
or
on the login screen. Having an account enables you to save your sessions. To create an account, you just need an email address and password. Click Register here on the login screen to create your own account.
orSelect the Exec you want to run. For this exercise, select Interlisp
Leave the Fill browser window option set.
Select Run Medley.
Your browser will open a window that represents the Interlisp Desktop and looks much like this:
Medley Interlisp
The Interlisp Desktop at startup contains 4 windows of interest:
In the Exec window, type the following:
(PLUS 1 1)
When you complete typing the ending ) the Interlisp interpreter will perform the calculation and return the result.
One thing you probably noticed, the command PLUS is capitalized. It’s not that the developers of Interlisp were always shouting at each other. Rather, when Interlisp was developed computer programming was in its infancy and standards for naming commands were still evolving.
(What is a memory image? How is it different from an image or memory?)
In Interlisp, there are two types of files relevant to managing memory images and updating them across sessions: lisp.virtualmem and .sysout.
The lisp.virtualmem file is a capture of the “current” state of the system (i.e., it is a copy of the virtual memory at a point in time). lisp.virtualmem is written whenever you execute (IL:LOGOUT) and also whenever executing (IL:SAVEVM). You can restart Medley using a lisp.virtualmem and it will pick up essentially where it left off before the LOGOUT or SAVEVM (with the exception that the user can set BEFORE/AFTER and LOGOUT/SAVEVM code that runs before you get control of the restarted lisp.virtualmem).
A .sysout is a virtual memory image produced by MAKESYS (for writing an image for distribution) and SYSOUT (for saving a named checkpoint, e.g. to revert to a previous state if needed), which differ in the way they process the startup options. You can (and most frequently do) start Medley from a sysout file. When Medley starts from a sysout, it automatically runs initialization scripts — a site initialization script followed by a per-user initialization script (if available). A sysout is what you might call “a clean image”.
As for Interlisp Online: except as noted below, every time you Run Medley you are starting up from a sysout file (i.e., from a clean image). The exception is if you check the Resume previous session box. In that case, you will be starting up from the lisp.virtualmem stored for you online (if any) and that was created by the (IL:LOGOUT) at the end of your previous session.
As a registered Interlisp Online user you get the choice of resuming your previous image or starting from a clean image — with the default being starting from a clean image.
For guest logins, there is no Resume previous session because lisp.virtualmem is never preserved for guests.
For registered users, any files that you create (e.g., with IL:MAKEFILE) will also be preserved across sessions online. But these files will never be automatically loaded into the system when you re-start with a clean image — you need to LOAD them explicitly (or add a LOAD to your personal INIT file stored online at {DSK}/home/medley/il/INIT).
Whether you’re just getting started or refreshing your knowledge of Interlisp, we have a variety of documentation to help you along.
The following links lead to PDF files containing Interlisp documentation. We are in the process of organizing this documentation.
Most Interlisp/Medley documentation was written using the Medley Text Editor, one of the first WYSIWYG graphical user interface text editors, called TEdit. Written in and for Interlisp users, it features muliple fonts, embedded graphics including line drawings and raster images.
TEdit files are scattered through the the various Interlisp repositories. For the convenience of those who would rather read the files using more modern tools, see the files from different Medley Interlisp repositories, converted to PDF. NOTE: This is not a permanent location!
For the searcher’s conveneience, these have also been combined into searchable PDFs named All-*-PDFs.pdf.
These documents were converted from Medley’s internal format into PDFs. Watch out for weird formatting, but these are firsthand sources on Medley features and applications.
A few basics – enough to get you started from the Medley User’s Guide of ~30 years ago.
Interlisp is a dialect of Lisp and as such, it is based on the familiar syntax of left-parenthesis, function name, arguments, and right-parenthesis. Besides many of the functions having different names and arguments compared to Common Lisp, Interlisp has many other, more fundamental, differences from Common Lisp. While this section will not go into any of the functional differences between Interlisp and Common Lisp, it will attempt to detail the more fundamental differences between the two. The reference manual may be used for a detailed description of the Interlisp functions.
Interlisp uses mixed case. That is, upper-case letters and lower-case
letters are treated as different. This means you can have a variable
name my-var and a variable named MY-VAR that are unique and
unrelated to each other. This is true for Common Lisp too, but
the READ function in Common Lisp translates.
Most Interlisp primitives are upper case.
As a side note, the Medley system includes a package called DWIM (Do What I Mean). This system reads in what you type and attempts to automatically correct input errors. At times, in an effort to correct typing errors this system will auto-convert something you type in lowercase into uppercase. Thus it may appear that the case doesn’t matter - but it does.
Except for Special Variables, variables in Common Lisp are lexically scoped. This means that local variables are only visible within the scope they are defined. This means, among other things, that variables defined in one function are not visible to other functions.
In functions that are running interpretively (as opposed to having
been compiled), variables in Interlisp are dynamically scoped. This
means that variables are visible within the dynamic environment they
are in. For example, let’s say we create two functions FUN1
and FUN2. If FUN1 introduced a local variable and then
called FUN2, then FUN2 would have access to the variable
since it is in the dynamic environment of being called by FUN1.
In other words, the variable was in existence when FUN2 was
called. However, the Interlisp compiler “hides” variables unless
they are “declared special”, so that they are essentially lexically scoped,
as in Common Lisp.
Common Lisp also supports dynamic variables as well. They are called the Special Variables.
Like Common Lisp but unlike Scheme, Interlisp is a LISP-2 language.
This means, in part, that the namespace for variables is separate from
the namespace for functions. For example, in Interlisp and
Common Lisp, you can simultaneously have a variable named ABC
and a function named ABC that are unrelated.
Interlisp shares the notion of LAMBDA expressions with Common Lisp,
as a way of defining functions. Interlisp LAMBDA specifies a list
of parameters; Common Lisp parameter lists can be decorated with
&OPTIONAL, &REST and &KEYWORD parameters. Interlisp also
adds the notion of an NLAMBDA function that doesn’t evaluate
its arguments – arguments to
NLAMBDA function are passed directly into a function without
being evaluated.
Interlisp supports spread and no-spread lambda arguments similar to Common Lisp. However, Interlisp treats all arguments as optional (if not provided they default to NIL) and ignores extra arguments (no warning or error is raised).
Interlisp supports macros but unlike Common Lisp, Interlisp symbols may simultaneously have a function definition and a macro definition. If a symbol has both a function definition and a macro definition, the function definition is used by the interpreter and the macro is used by the compiler. This allows for extra error checking during development and fast operation during production use.
Interlisp also has a backquote facility similar to Common Lisp’s ` and , read macros.
Unlike Common Lisp, Interlisp does not have a special function for defining macros. Macros are defined by placing their definition on the property list of the symbol.
The term “Common Lisp” covers a range of development stages, first defined by the book “Common Lisp, the Language” editions 1 (aka CLtL1) and 2 (aka CLtL2) and ultimately the ANSI Standard Common Lisp (aka ANSI). The Common Lisp currently supported by Medley is somewhere between CLtl1 and CLtl2. We are hoping to complete the move to CLtl2.
In Medley Common Lisp and Interlisp are fully integrated. From within Common Lisp, Interlisp functions may be accessed through the Common Lisp package nicknamed ``IL’'.
This introduction was designed to provide the most general of information – just enough to get you started. Medley comes with extensive documentation.
In searchable PDF and (imperfect) HTML:
Medley Interlisp also includes an online reference:
or, at any prompt, the man command will look up an (Interlisp) symbol.
Many thanks to Blake McBride and his Medley Intro from which this was initially taken.