Admin/PLATFORMS
author wenzelm
Sun Sep 11 14:42:15 2011 +0200 (2011-09-11)
changeset 44876 243e2a413787
parent 42424 e94350a2ed20
child 44977 1b2ce8d0f8e3
permissions -rw-r--r--
some updates of PLATFORMS;
     1 Some notes on multi-platform support of Isabelle
     2 ================================================
     3 
     4 Preamble
     5 --------
     6 
     7 The general programming model is that of a stylized ML + Scala + POSIX
     8 environment, with hardly any system specific code in user-space tools
     9 and packages.
    10 
    11 The basic Isabelle system infrastructure provides some facilities to
    12 make this work, e.g. see the ML structures File and Path, or functions
    13 like Isabelle_System.bash.  The settings environment also provides
    14 some means for portability, e.g. jvm_path to keep the impression that
    15 Java on Windows/Cygwin adheres to Isabelle/POSIX standards (inside the
    16 JVM itself there are many Windows-specific things, though).
    17 
    18 When producing add-on tools, it is important to stay within this clean
    19 room of Isabelle, and refrain from overly ambitious system hacking.
    20 The existing Isabelle scripts follow a certain style that might look
    21 odd at first sight, but it reflects long years of experience in
    22 getting system plumbing right (which is quite hard).
    23 
    24 
    25 Supported platforms
    26 -------------------
    27 
    28 The following hardware and operating system platforms are officially
    29 supported by the Isabelle distribution (and bundled tools), with the
    30 following reference versions (which have been selected to be neither
    31 too old nor too new):
    32 
    33   x86-linux         Ubuntu 10.04 LTS
    34   x86-darwin        Mac OS Leopard (macbroy30)
    35   x86-cygwin        Cygwin 1.7 (vmbroy9)
    36 
    37   x86_64-linux      Ubuntu 10.04 LTS
    38   x86_64-darwin     Mac OS Leopard (macbroy30)
    39 
    40 All of the above platforms are 100% supported by Isabelle -- end-users
    41 should not have to care about the differences (at least in theory).
    42 There are also some additional platforms where Poly/ML also happens to
    43 work, but they are *not* covered by the official Isabelle
    44 distribution:
    45 
    46   ppc-darwin
    47   sparc-solaris
    48   x86-solaris
    49   x86-bsd
    50 
    51 There are increasing problems to make contributing components of
    52 Isabelle work on such fringe platforms.  Note that x86-bsd is silently
    53 treated like x86-linux -- this works if certain Linux compatibility
    54 packages are installed on BSD.
    55 
    56 
    57 32 bit vs. 64 bit platforms
    58 ---------------------------
    59 
    60 64 bit hardware becomes more and more important for many users.
    61 Add-on tools need to work seamlessly without manual user
    62 configuration, although it is often sufficient to fall back on 32 bit
    63 executables.
    64 
    65 The ISABELLE_PLATFORM setting variable refers to the 32 bit version of
    66 the platform, even on 64 bit hardware.  Power-tools need to indicate
    67 64 bit support explicitly, via the (optional) ISABELLE_PLATFORM64
    68 setting.  The following bash expression prefers the 64 bit platform,
    69 if that is available:
    70 
    71   "${ISABELLE_PLATFORM64:-$ISABELLE_PLATFORM}"
    72 
    73 Note that ML and JVM may have a different idea of the platform,
    74 depending on the respective binaries that are actually run.
    75 
    76 
    77 Dependable system tools
    78 -----------------------
    79 
    80 The following portable system tools can be taken for granted:
    81 
    82 * GNU bash as uniform shell on all platforms.  The POSIX "standard"
    83   shell /bin/sh is *not* appropriate, because there are too many
    84   non-standard implementations of it.
    85 
    86 * Perl as largely portable system programming language.  In some
    87   situations Python may serve as an alternative, but it usually
    88   performs not as well in addressing various delicate details of
    89   operating system concepts (processes, signals, sockets etc.).
    90 
    91 * Scala with Java Runtime 1.6.  The Isabelle/Scala layer irons out
    92   many oddities and portability issues of the Java platform.
    93 
    94 
    95 Known problems
    96 --------------
    97 
    98 * Mac OS: If MacPorts is installed there is some danger that
    99   accidental references to its shared libraries are created
   100   (e.g. libgmp).  Use otool -L to check if compiled binaries also work
   101   without MacPorts.
   102 
   103 * Mac OS: If MacPorts is installed and its version of Perl takes
   104   precedence over /usr/bin/perl in the PATH, then the end-user needs
   105   to take care of installing extra modules, e.g. for HTTP support.
   106   Such add-ons are usually included in Apple's /usr/bin/perl by
   107   default.
   108 
   109 * The Java runtime has its own idea about the underlying platform,
   110   e.g. on a 64 bit machine Isabelle/ML could be x86-linux, but the JVM
   111   could be x86_64-linux.  This affects Java native libraries in
   112   particular -- which cause extra portability problems and can make
   113   the JVM crash anyway.
   114 
   115   In Isabelle/Scala isabelle.Platform.jvm_platform identifies the JVM
   116   platform.  Since there can be many different Java installations on
   117   the same machine, which can also be run with different options,
   118   reliable JVM platform identification works from inside the running
   119   JVM only.