Install and Run

• 1: Install and Run on Linux
• 2: Install and Run on Windows with WSL
• 3: Install and Run on MacOS
• 4: Install and Run on Windows 10/11

1 - Install and Run on Linux

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.

• Standard installation will install Medley into system directories and install any prerequisite packages.
• Local installation will install Medley into any user directory but any prerequisite packages must be installed manually.

Standard Installation (Debian-based systems only)

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.

Accessing Medley

1. 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

2. Enter the following in a terminal to install the download:

   ubuntu@oio:~$ sudo apt update
   ubuntu@oio:~$ sudo apt install -y <deb_filepath>
   

3. 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.

Notes:

• By default, 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.

Local Installation

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.

To install and run Medley locally:

1. 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.

2. 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.

3. Install Medley

   In a terminal:

   ubuntu@oio:~$ mkdir <interlisp_directory>
   ubuntu@oio:~$ tar -C <interlisp_directory> -xzf <tar_filepath>
   

4. 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.

Notes:

• By default, 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.

2 - Install and Run on Windows with WSL

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.

Accessing Medley for WSL

1. Use a browser to download from the .deb package for your platform (i.e., “standard” WSL) and your machine architecture (X86_64, ARM64, or ARMv7) to <deb_filepath> from the Medley downloads site

<deb_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 <deb_filepath> will be in ~/Downloads.
  • If using a Windows-based browser, <deb_filepath> will be in /mnt/c/Users/<username>/Downloads.

3 - Install and Run on MacOS

How to Install

1. Get the Installer Download the MacOS installer from the latest release page.

2. 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.

install medley from release, build maiko

Need XCode Need XQuartz installed before you build maiko (includes XClient libraries).

• Requirements

• Intel or M1/M2 Macintosh (or even older)
• XQuartz Macintosh X server for your OS/mac vintage)

XQuartz settings

emulate 3-button mouse

4 - Install and Run on Windows 10/11

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.

Running on Windows natively**

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.

To install and run Medley natively

1. Download the Medley Windows installer from under the Windows 10/11 heading here.

2. 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.

3. 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.

Notes

1. One anomaly of the native Windows install is that the file system from within Medley does not map directly to the file system as seen from the Windows Explorer. Specifically, within Medley, the {DSK} and {UNIX} file system root (i.e., “{DSK}/” and “{UNIX}/”) is mapped to install_dir. Medley will find the Windows C: drive as {DSK}/c/ (or “{DSK}”).

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.)

2. 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.

3. 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).