Admin/PLATFORMS

Added contributors

Multi-platform support of Isabelle
==================================

Preamble
--------

The general programming model is that of a stylized ML + Scala + POSIX
environment, with a minimum of system-specific code in user-space
tools.

The Isabelle system infrastructure provides some facilities to make
this work, e.g. see the ML and Scala modules File and Path, or
functions like Isabelle_System.bash.  The settings environment also
provides some means for portability, e.g. the bash function
"platform_path" to keep the impression that Windows/Cygwin adheres to
Isabelle/POSIX standards, although Poly/ML and the JVM are native on
Windows.

When producing add-on tools, it is important to stay within this clean
room of Isabelle, and refrain from non-portable access to operating
system functions. The Isabelle environment uses peculiar scripts for
GNU bash and perl as system glue: this style should be observed as far
as possible.


Supported platforms
-------------------

A broad range of hardware and operating system platforms are supported
by building executables on base-line versions that are neither too old
nor too new. Common OS families work: Linux, Windows, macOS, but
exotic ones are unsupported: BSD, Solaris, NixOS.

Official (full support):

  x86_64-linux      Ubuntu 14.04 LTS

  x86_64-darwin     macOS 10.13 High Sierra (lapbroy68 MacBookPro11,2)
                    macOS 10.14 Mojave (mini2 Macmini8,1)
                    macOS 10.15 Catalina (laramac01 Macmini8,1)

  x86_64-windows    Windows 7
  x86_64-cygwin     Cygwin 3.1.x https://isabelle.sketis.net/cygwin_2021 (x86_64/release)

Old (partial support):

  x86_64-darwin     Mac OS X 10.11 El Capitan (macbroy2 MacPro4,1)

New (experimental):

  arm64-linux       Raspberry Pi OS 64bit beta (Debian 10 / Buster)


64 bit vs. 32 bit platform personality
--------------------------------------

Isabelle requires 64 bit hardware running a 64 bit operating
system. Windows and Mac OS X allow x86 executables as well, but for
Linux this requires separate installation of 32 bit shared
libraries. The POSIX emulation on Windows via Cygwin64 works
exclusively for x86_64.

Poly/ML supports both for x86_64 and x86, and the latter is preferred
for space and performance reasons. Java is always the x86_64 version
on all platforms.

Add-on executables are expected to work without manual user
configuration. Each component settings script needs to determine the
platform details appropriately.


The Isabelle settings environment provides the following important
variables to help configuring platform-dependent tools:

  ISABELLE_PLATFORM64  (potentially empty)
  ISABELLE_PLATFORM32  (potentially empty)

Each can be empty, but not both at the same time. Using GNU bash
notation, tools may express their platform preference, e.g. first 64
bit and second 32 bit, or the opposite:

  "${ISABELLE_PLATFORM64:-$ISABELLE_PLATFORM32}"
  "${ISABELLE_PLATFORM32:-$ISABELLE_PLATFORM64}"


There is a another set of settings for native Windows (instead of the
POSIX emulation of Cygwin used before):

  ISABELLE_WINDOWS_PLATFORM64
  ISABELLE_WINDOWS_PLATFORM32

These are always empty on Linux and Mac OS X, and non-empty on
Windows. They can be used like this to prefer native Windows and then
Unix (first 64 bit second 32 bit):

  "${ISABELLE_WINDOWS_PLATFORM64:-${ISABELLE_WINDOWS_PLATFORM32:-${ISABELLE_PLATFORM64:-$ISABELLE_PLATFORM32}}}"


Dependable system tools
-----------------------

The following portable system tools can be taken for granted:

* Scala on top of Java.  Isabelle/Scala irons out many oddities and
  portability issues of the Java platform.

* GNU bash as uniform shell on all platforms. The POSIX "standard"
  shell /bin/sh does *not* work portably -- there are too many
  non-standard implementations of it. On Debian and Ubuntu /bin/sh is
  actually /bin/dash and introduces many oddities.

* Perl as largely portable system programming language, with its
  fairly robust support for processes, signals, sockets etc.


Known problems
--------------

* Mac OS X: If MacPorts is installed there is some danger that
  accidental references to its shared libraries are created
  (e.g. libgmp).  Use otool -L to check if compiled binaries also work
  without MacPorts.

* Mac OS X: If MacPorts is installed and its version of Perl takes
  precedence over /usr/bin/perl in the PATH, then the end-user needs
  to take care of installing extra modules, e.g. for HTTP support.
  Such add-ons are usually included in Apple's /usr/bin/perl by
  default.

* Common Unix tools like /bin/sh, /bin/kill, sed, ulimit are
  notoriously non-portable an should be avoided.

* The traditional "uname" Unix tool only tells about its own executable
  format, not the underlying platform!