src/Doc/System/Environment.thy
author wenzelm
Thu, 19 Apr 2018 12:34:52 +0200
changeset 68003 9b89d831dc80
parent 67904 465f43a9f780
child 68219 c0341c0080e2
permissions -rw-r--r--
prefer explicit 32/64 bit platform settings;
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
66732
e566fb4d43d4 more and updated documentation;
wenzelm
parents: 64509
diff changeset
     1
(*:maxLineLen=78:*)
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
     2
62640
e36cbe677c17 clarified name;
wenzelm
parents: 62639
diff changeset
     3
theory Environment
43564
9864182c6bad document antiquotations are managed as theory data, with proper name space and entity markup;
wenzelm
parents: 41955
diff changeset
     4
imports Base
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
     5
begin
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
     6
58618
782f0b662cae more cartouches;
wenzelm
parents: 58553
diff changeset
     7
chapter \<open>The Isabelle system environment\<close>
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
     8
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
     9
text \<open>
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
    10
  This manual describes Isabelle together with related tools as seen from a
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
    11
  system oriented view. See also the \<^emph>\<open>Isabelle/Isar Reference Manual\<close> @{cite
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
    12
  "isabelle-isar-ref"} for the actual Isabelle input language and related
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
    13
  concepts, and \<^emph>\<open>The Isabelle/Isar Implementation Manual\<close> @{cite
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
    14
  "isabelle-implementation"} for the main concepts of the underlying
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
    15
  implementation in Isabelle/ML.
58618
782f0b662cae more cartouches;
wenzelm
parents: 58553
diff changeset
    16
\<close>
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
    17
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
    18
58618
782f0b662cae more cartouches;
wenzelm
parents: 58553
diff changeset
    19
section \<open>Isabelle settings \label{sec:settings}\<close>
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
    20
58618
782f0b662cae more cartouches;
wenzelm
parents: 58553
diff changeset
    21
text \<open>
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
    22
  Isabelle executables may depend on the \<^emph>\<open>Isabelle settings\<close> within the
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
    23
  process environment. This is a statically scoped collection of environment
62013
92a2372a226b discontinued documentation of old browser;
wenzelm
parents: 61656
diff changeset
    24
  variables, such as @{setting ISABELLE_HOME}, @{setting ML_SYSTEM}, @{setting
92a2372a226b discontinued documentation of old browser;
wenzelm
parents: 61656
diff changeset
    25
  ML_HOME}. These variables are \<^emph>\<open>not\<close> intended to be set directly from the
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
    26
  shell, but are provided by Isabelle \<^emph>\<open>components\<close> their \<^emph>\<open>settings files\<close> as
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
    27
  explained below.
58618
782f0b662cae more cartouches;
wenzelm
parents: 58553
diff changeset
    28
\<close>
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
    29
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
    30
58618
782f0b662cae more cartouches;
wenzelm
parents: 58553
diff changeset
    31
subsection \<open>Bootstrapping the environment \label{sec:boot}\<close>
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
    32
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    33
text \<open>
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    34
  Isabelle executables need to be run within a proper settings environment.
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    35
  This is bootstrapped as described below, on the first invocation of one of
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    36
  the outer wrapper scripts (such as @{executable_ref isabelle}). This happens
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    37
  only once for each process tree, i.e.\ the environment is passed to
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    38
  subprocesses according to regular Unix conventions.
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    39
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    40
    \<^enum> The special variable @{setting_def ISABELLE_HOME} is determined
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    41
    automatically from the location of the binary that has been run.
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
    42
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    43
    You should not try to set @{setting ISABELLE_HOME} manually. Also note
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    44
    that the Isabelle executables either have to be run from their original
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    45
    location in the distribution directory, or via the executable objects
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    46
    created by the @{tool install} tool. Symbolic links are admissible, but a
63680
6e1e8b5abbfa more symbols;
wenzelm
parents: 63669
diff changeset
    47
    plain copy of the \<^dir>\<open>$ISABELLE_HOME/bin\<close> files will not work!
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    48
63680
6e1e8b5abbfa more symbols;
wenzelm
parents: 63669
diff changeset
    49
    \<^enum> The file \<^file>\<open>$ISABELLE_HOME/etc/settings\<close> is run as a @{executable_ref
6e1e8b5abbfa more symbols;
wenzelm
parents: 63669
diff changeset
    50
    bash} shell script with the auto-export option for variables enabled.
28238
398bf960d3d4 misc tuning and modernization;
wenzelm
parents: 28223
diff changeset
    51
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    52
    This file holds a rather long list of shell variable assignments, thus
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    53
    providing the site-wide default settings. The Isabelle distribution
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    54
    already contains a global settings file with sensible defaults for most
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    55
    variables. When installing the system, only a few of these may have to be
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    56
    adapted (probably @{setting ML_SYSTEM} etc.).
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    57
63669
256fc20716f2 clarified antiquotations;
wenzelm
parents: 62847
diff changeset
    58
    \<^enum> The file @{path "$ISABELLE_HOME_USER/etc/settings"} (if it
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    59
    exists) is run in the same way as the site default settings. Note that the
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    60
    variable @{setting ISABELLE_HOME_USER} has already been set before ---
67044
wenzelm
parents: 66947
diff changeset
    61
    usually to something like \<^verbatim>\<open>$USER_HOME/.isabelle/Isabelle2017\<close>.
61458
987533262fc2 Markdown support in document text;
wenzelm
parents: 61439
diff changeset
    62
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    63
    Thus individual users may override the site-wide defaults. Typically, a
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    64
    user settings file contains only a few lines, with some assignments that
63680
6e1e8b5abbfa more symbols;
wenzelm
parents: 63669
diff changeset
    65
    are actually changed. Never copy the central
6e1e8b5abbfa more symbols;
wenzelm
parents: 63669
diff changeset
    66
    \<^file>\<open>$ISABELLE_HOME/etc/settings\<close> file!
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
    67
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    68
  Since settings files are regular GNU @{executable_def bash} scripts, one may
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    69
  use complex shell commands, such as \<^verbatim>\<open>if\<close> or \<^verbatim>\<open>case\<close> statements to set
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    70
  variables depending on the system architecture or other environment
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    71
  variables. Such advanced features should be added only with great care,
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    72
  though. In particular, external environment references should be kept at a
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
    73
  minimum.
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
    74
61406
eb2463fc4d7b more symbols;
wenzelm
parents: 59904
diff changeset
    75
  \<^medskip>
eb2463fc4d7b more symbols;
wenzelm
parents: 59904
diff changeset
    76
  A few variables are somewhat special:
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
    77
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
    78
    \<^item> @{setting_def ISABELLE_TOOL} is set automatically to the absolute path
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
    79
    name of the @{executable isabelle} executables.
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
    80
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    81
    \<^item> @{setting_ref ISABELLE_OUTPUT} will have the identifiers of the Isabelle
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    82
    distribution (cf.\ @{setting ISABELLE_IDENTIFIER}) and the ML system (cf.\
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    83
    @{setting ML_IDENTIFIER}) appended automatically to its value.
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
    84
61406
eb2463fc4d7b more symbols;
wenzelm
parents: 59904
diff changeset
    85
  \<^medskip>
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    86
  Note that the settings environment may be inspected with the @{tool getenv}
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    87
  tool. This might help to figure out the effect of complex settings scripts.
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    88
\<close>
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
    89
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
    90
58618
782f0b662cae more cartouches;
wenzelm
parents: 58553
diff changeset
    91
subsection \<open>Common variables\<close>
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
    92
58618
782f0b662cae more cartouches;
wenzelm
parents: 58553
diff changeset
    93
text \<open>
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    94
  This is a reference of common Isabelle settings variables. Note that the
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    95
  list is somewhat open-ended. Third-party utilities or interfaces may add
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    96
  their own selection. Variables that are special in some sense are marked
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    97
  with \<open>\<^sup>*\<close>.
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
    98
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
    99
  \<^descr>[@{setting_def USER_HOME}\<open>\<^sup>*\<close>] Is the cross-platform user home directory.
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   100
  On Unix systems this is usually the same as @{setting HOME}, but on Windows
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   101
  it is the regular home directory of the user, not the one of within the
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   102
  Cygwin root file-system.\<^footnote>\<open>Cygwin itself offers another choice whether its
63669
256fc20716f2 clarified antiquotations;
wenzelm
parents: 62847
diff changeset
   103
  HOME should point to the @{path "/home"} directory tree or the Windows user
256fc20716f2 clarified antiquotations;
wenzelm
parents: 62847
diff changeset
   104
  home.\<close>
47661
012a887997f3 USER_HOME settings variable points to cross-platform user home directory;
wenzelm
parents: 45028
diff changeset
   105
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   106
  \<^descr>[@{setting_def ISABELLE_HOME}\<open>\<^sup>*\<close>] is the location of the top-level
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   107
  Isabelle distribution directory. This is automatically determined from the
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   108
  Isabelle executable that has been invoked. Do not attempt to set @{setting
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   109
  ISABELLE_HOME} yourself from the shell!
50182
30177ec0be36 added ISABELLE_PLATFORM_FAMILY;
wenzelm
parents: 49173
diff changeset
   110
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   111
  \<^descr>[@{setting_def ISABELLE_HOME_USER}] is the user-specific counterpart of
63669
256fc20716f2 clarified antiquotations;
wenzelm
parents: 62847
diff changeset
   112
  @{setting ISABELLE_HOME}. The default value is relative to @{path
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   113
  "$USER_HOME/.isabelle"}, under rare circumstances this may be changed in the
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   114
  global setting file. Typically, the @{setting ISABELLE_HOME_USER} directory
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   115
  mimics @{setting ISABELLE_HOME} to some extend. In particular, site-wide
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   116
  defaults may be overridden by a private \<^verbatim>\<open>$ISABELLE_HOME_USER/etc/settings\<close>.
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   117
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   118
  \<^descr>[@{setting_def ISABELLE_PLATFORM_FAMILY}\<open>\<^sup>*\<close>] is automatically set to the
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   119
  general platform family: \<^verbatim>\<open>linux\<close>, \<^verbatim>\<open>macos\<close>, \<^verbatim>\<open>windows\<close>. Note that
50182
30177ec0be36 added ISABELLE_PLATFORM_FAMILY;
wenzelm
parents: 49173
diff changeset
   120
  platform-dependent tools usually need to refer to the more specific
68003
9b89d831dc80 prefer explicit 32/64 bit platform settings;
wenzelm
parents: 67904
diff changeset
   121
  identification according to @{setting ISABELLE_PLATFORM64}, @{setting
9b89d831dc80 prefer explicit 32/64 bit platform settings;
wenzelm
parents: 67904
diff changeset
   122
  ISABELLE_PLATFORM32}, @{setting ISABELLE_WINDOWS_PLATFORM64}, @{setting
9b89d831dc80 prefer explicit 32/64 bit platform settings;
wenzelm
parents: 67904
diff changeset
   123
  ISABELLE_WINDOWS_PLATFORM32}.
66732
e566fb4d43d4 more and updated documentation;
wenzelm
parents: 64509
diff changeset
   124
68003
9b89d831dc80 prefer explicit 32/64 bit platform settings;
wenzelm
parents: 67904
diff changeset
   125
  \<^descr>[@{setting_def ISABELLE_PLATFORM64}\<open>\<^sup>*\<close>, @{setting_def
9b89d831dc80 prefer explicit 32/64 bit platform settings;
wenzelm
parents: 67904
diff changeset
   126
  ISABELLE_PLATFORM32}\<open>\<^sup>*\<close>] indicate the standard Posix platform: \<^verbatim>\<open>x86_64\<close>
9b89d831dc80 prefer explicit 32/64 bit platform settings;
wenzelm
parents: 67904
diff changeset
   127
  for 64 bit and \<^verbatim>\<open>x86\<close> for 32 bit, together with a symbolic name for the
9b89d831dc80 prefer explicit 32/64 bit platform settings;
wenzelm
parents: 67904
diff changeset
   128
  operating system (\<^verbatim>\<open>linux\<close>, \<^verbatim>\<open>darwin\<close>, \<^verbatim>\<open>cygwin\<close>). All platforms support 64
9b89d831dc80 prefer explicit 32/64 bit platform settings;
wenzelm
parents: 67904
diff changeset
   129
  bit executables, some platforms also support 32 bit executables.
66732
e566fb4d43d4 more and updated documentation;
wenzelm
parents: 64509
diff changeset
   130
68003
9b89d831dc80 prefer explicit 32/64 bit platform settings;
wenzelm
parents: 67904
diff changeset
   131
  In GNU bash scripts, it is possible to use the following expressions (with
9b89d831dc80 prefer explicit 32/64 bit platform settings;
wenzelm
parents: 67904
diff changeset
   132
  quotes) to specify a preference of 64 bit over 32 bit:
66732
e566fb4d43d4 more and updated documentation;
wenzelm
parents: 64509
diff changeset
   133
e566fb4d43d4 more and updated documentation;
wenzelm
parents: 64509
diff changeset
   134
  @{verbatim [display] \<open>"${ISABELLE_PLATFORM64:-$ISABELLE_PLATFORM32}"\<close>}
50182
30177ec0be36 added ISABELLE_PLATFORM_FAMILY;
wenzelm
parents: 49173
diff changeset
   135
68003
9b89d831dc80 prefer explicit 32/64 bit platform settings;
wenzelm
parents: 67904
diff changeset
   136
  In contrast, the subsequent expression prefers the old 32 bit variant (which
9b89d831dc80 prefer explicit 32/64 bit platform settings;
wenzelm
parents: 67904
diff changeset
   137
  is only relevant for unusual applications):
66732
e566fb4d43d4 more and updated documentation;
wenzelm
parents: 64509
diff changeset
   138
e566fb4d43d4 more and updated documentation;
wenzelm
parents: 64509
diff changeset
   139
  @{verbatim [display] \<open>"${ISABELLE_PLATFORM32:-$ISABELLE_PLATFORM64}"\<close>}
36196
cbb9ee265cdd added ISABELLE_PLATFORM and ISABELLE_PLATFORM64 -- NB: ML and JVM may have a different idea;
wenzelm
parents: 33952
diff changeset
   140
68003
9b89d831dc80 prefer explicit 32/64 bit platform settings;
wenzelm
parents: 67904
diff changeset
   141
  \<^descr>[@{setting_def ISABELLE_WINDOWS_PLATFORM64}\<open>\<^sup>*\<close>, @{setting_def
9b89d831dc80 prefer explicit 32/64 bit platform settings;
wenzelm
parents: 67904
diff changeset
   142
  ISABELLE_WINDOWS_PLATFORM32}\<open>\<^sup>*\<close>] indicate the native Windows platform.
9b89d831dc80 prefer explicit 32/64 bit platform settings;
wenzelm
parents: 67904
diff changeset
   143
  These settings are analogous (but independent) of those for the standard
9b89d831dc80 prefer explicit 32/64 bit platform settings;
wenzelm
parents: 67904
diff changeset
   144
  Posix subsystem: @{setting ISABELLE_PLATFORM64}, @{setting
9b89d831dc80 prefer explicit 32/64 bit platform settings;
wenzelm
parents: 67904
diff changeset
   145
  ISABELLE_PLATFORM32}.
47823
4fad76e6f4ba some manual updates;
wenzelm
parents: 47661
diff changeset
   146
66732
e566fb4d43d4 more and updated documentation;
wenzelm
parents: 64509
diff changeset
   147
  In GNU bash scripts, a preference for native Windows platform variants may
68003
9b89d831dc80 prefer explicit 32/64 bit platform settings;
wenzelm
parents: 67904
diff changeset
   148
  be specified like this (first 64 bit, second 32 bit):
66732
e566fb4d43d4 more and updated documentation;
wenzelm
parents: 64509
diff changeset
   149
68003
9b89d831dc80 prefer explicit 32/64 bit platform settings;
wenzelm
parents: 67904
diff changeset
   150
  @{verbatim [display] \<open>"${ISABELLE_WINDOWS_PLATFORM64:-${ISABELLE_WINDOWS_PLATFORM32:-
9b89d831dc80 prefer explicit 32/64 bit platform settings;
wenzelm
parents: 67904
diff changeset
   151
  ${ISABELLE_PLATFORM64:-$ISABELLE_PLATFORM32}}}"\<close>}
36196
cbb9ee265cdd added ISABELLE_PLATFORM and ISABELLE_PLATFORM64 -- NB: ML and JVM may have a different idea;
wenzelm
parents: 33952
diff changeset
   152
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   153
  \<^descr>[@{setting ISABELLE_TOOL}\<open>\<^sup>*\<close>] is automatically set to the full path name
66787
64b47495676d obsolete;
wenzelm
parents: 66785
diff changeset
   154
  of the @{executable isabelle} executable.
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
   155
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   156
  \<^descr>[@{setting_def ISABELLE_IDENTIFIER}\<open>\<^sup>*\<close>] refers to the name of this
66785
6fbd7fc824a9 updated for release;
wenzelm
parents: 64509
diff changeset
   157
  Isabelle distribution, e.g.\ ``\<^verbatim>\<open>Isabelle2017\<close>''.
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   158
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   159
  \<^descr>[@{setting_def ML_SYSTEM}, @{setting_def ML_HOME}, @{setting_def
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   160
  ML_OPTIONS}, @{setting_def ML_PLATFORM}, @{setting_def ML_IDENTIFIER}\<open>\<^sup>*\<close>]
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   161
  specify the underlying ML system to be used for Isabelle. There is only a
63680
6e1e8b5abbfa more symbols;
wenzelm
parents: 63669
diff changeset
   162
  fixed set of admissable @{setting ML_SYSTEM} names (see the
6e1e8b5abbfa more symbols;
wenzelm
parents: 63669
diff changeset
   163
  \<^file>\<open>$ISABELLE_HOME/etc/settings\<close> file of the distribution).
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   164
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
   165
  The actual compiler binary will be run from the directory @{setting
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   166
  ML_HOME}, with @{setting ML_OPTIONS} as first arguments on the command line.
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   167
  The optional @{setting ML_PLATFORM} may specify the binary format of ML heap
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   168
  images, which is useful for cross-platform installations. The value of
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   169
  @{setting ML_IDENTIFIER} is automatically obtained by composing the values
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   170
  of @{setting ML_SYSTEM}, @{setting ML_PLATFORM} and the Isabelle version
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   171
  values.
47823
4fad76e6f4ba some manual updates;
wenzelm
parents: 47661
diff changeset
   172
66733
9180953b976b more and updated documentation;
wenzelm
parents: 66732
diff changeset
   173
  \<^descr>[@{setting_def ISABELLE_JDK_HOME}] points to a full JDK (Java Development
9180953b976b more and updated documentation;
wenzelm
parents: 66732
diff changeset
   174
  Kit) installation with \<^verbatim>\<open>javac\<close> and \<^verbatim>\<open>jar\<close> executables. Note that
9180953b976b more and updated documentation;
wenzelm
parents: 66732
diff changeset
   175
  conventional \<^verbatim>\<open>JAVA_HOME\<close> points to the JRE (Java Runtime Environment), not
9180953b976b more and updated documentation;
wenzelm
parents: 66732
diff changeset
   176
  the JDK.
9180953b976b more and updated documentation;
wenzelm
parents: 66732
diff changeset
   177
9180953b976b more and updated documentation;
wenzelm
parents: 66732
diff changeset
   178
  \<^descr>[@{setting_def ISABELLE_JAVA_PLATFORM}] identifies the hardware and
9180953b976b more and updated documentation;
wenzelm
parents: 66732
diff changeset
   179
  operating system platform for the Java installation of Isabelle. That is
66906
03a96b8c7c06 updated to jdk-8u152, which is for x86_64 only;
wenzelm
parents: 66789
diff changeset
   180
  always the (native) 64 bit variant: \<^verbatim>\<open>x86_64-linux\<close>, \<^verbatim>\<open>x86_64-darwin\<close>,
66733
9180953b976b more and updated documentation;
wenzelm
parents: 66732
diff changeset
   181
  \<^verbatim>\<open>x86_64-windows\<close>.
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   182
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   183
  \<^descr>[@{setting_def ISABELLE_PATH}] is a list of directories (separated by
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   184
  colons) where Isabelle logic images may reside. When looking up heaps files,
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   185
  the value of @{setting ML_IDENTIFIER} is appended to each component
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   186
  internally.
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   187
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   188
  \<^descr>[@{setting_def ISABELLE_OUTPUT}\<open>\<^sup>*\<close>] is a directory where output heap files
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   189
  should be stored by default. The ML system and Isabelle version identifier
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   190
  is appended here, too.
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   191
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   192
  \<^descr>[@{setting_def ISABELLE_BROWSER_INFO}] is the directory where theory
62013
92a2372a226b discontinued documentation of old browser;
wenzelm
parents: 61656
diff changeset
   193
  browser information is stored as HTML and PDF (see also \secref{sec:info}).
63669
256fc20716f2 clarified antiquotations;
wenzelm
parents: 62847
diff changeset
   194
  The default value is @{path "$ISABELLE_HOME_USER/browser_info"}.
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   195
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   196
  \<^descr>[@{setting_def ISABELLE_LOGIC}] specifies the default logic to load if none
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   197
  is given explicitely by the user. The default value is \<^verbatim>\<open>HOL\<close>.
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   198
62562
905a5db3932d back to external line editor, due to problems of JLine with multithreading of in vs. out;
wenzelm
parents: 62559
diff changeset
   199
  \<^descr>[@{setting_def ISABELLE_LINE_EDITOR}] specifies the line editor for the
905a5db3932d back to external line editor, due to problems of JLine with multithreading of in vs. out;
wenzelm
parents: 62559
diff changeset
   200
  @{tool_ref console} interface.
905a5db3932d back to external line editor, due to problems of JLine with multithreading of in vs. out;
wenzelm
parents: 62559
diff changeset
   201
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   202
  \<^descr>[@{setting_def ISABELLE_LATEX}, @{setting_def ISABELLE_PDFLATEX},
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   203
  @{setting_def ISABELLE_BIBTEX}] refer to {\LaTeX} related tools for Isabelle
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   204
  document preparation (see also \secref{sec:tool-latex}).
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   205
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   206
  \<^descr>[@{setting_def ISABELLE_TOOLS}] is a colon separated list of directories
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   207
  that are scanned by @{executable isabelle} for external utility programs
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   208
  (see also \secref{sec:isabelle-tool}).
50197
b385d134926d eval PDF_VIEWER/DVI_VIEWER command line, which allows additional quotes for program name, for example;
wenzelm
parents: 50182
diff changeset
   209
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   210
  \<^descr>[@{setting_def ISABELLE_DOCS}] is a colon separated list of directories
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   211
  with documentation files.
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   212
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   213
  \<^descr>[@{setting_def PDF_VIEWER}] specifies the program to be used for displaying
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   214
  \<^verbatim>\<open>pdf\<close> files.
54683
cf48ddc266e5 clarified "isabelle display" and 'display_drafts': re-use file and program instance, open asynchronously via desktop environment;
wenzelm
parents: 52746
diff changeset
   215
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   216
  \<^descr>[@{setting_def DVI_VIEWER}] specifies the program to be used for displaying
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   217
  \<^verbatim>\<open>dvi\<close> files.
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   218
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   219
  \<^descr>[@{setting_def ISABELLE_TMP_PREFIX}\<open>\<^sup>*\<close>] is the prefix from which any
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   220
  running Isabelle ML process derives an individual directory for temporary
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   221
  files.
58618
782f0b662cae more cartouches;
wenzelm
parents: 58553
diff changeset
   222
\<close>
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
   223
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
   224
58618
782f0b662cae more cartouches;
wenzelm
parents: 58553
diff changeset
   225
subsection \<open>Additional components \label{sec:components}\<close>
32323
8185d3bfcbf1 tuned "Bootstrapping the environment";
wenzelm
parents: 32088
diff changeset
   226
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   227
text \<open>
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   228
  Any directory may be registered as an explicit \<^emph>\<open>Isabelle component\<close>. The
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   229
  general layout conventions are that of the main Isabelle distribution
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   230
  itself, and the following two files (both optional) have a special meaning:
32323
8185d3bfcbf1 tuned "Bootstrapping the environment";
wenzelm
parents: 32088
diff changeset
   231
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   232
    \<^item> \<^verbatim>\<open>etc/settings\<close> holds additional settings that are initialized when
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   233
    bootstrapping the overall Isabelle environment, cf.\ \secref{sec:boot}. As
64509
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   234
    usual, the content is interpreted as a GNU bash script. It may refer to
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   235
    the component's enclosing directory via the \<^verbatim>\<open>COMPONENT\<close> shell variable.
32323
8185d3bfcbf1 tuned "Bootstrapping the environment";
wenzelm
parents: 32088
diff changeset
   236
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   237
    For example, the following setting allows to refer to files within the
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   238
    component later on, without having to hardwire absolute paths:
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   239
    @{verbatim [display] \<open>MY_COMPONENT_HOME="$COMPONENT"\<close>}
32323
8185d3bfcbf1 tuned "Bootstrapping the environment";
wenzelm
parents: 32088
diff changeset
   240
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   241
    Components can also add to existing Isabelle settings such as
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   242
    @{setting_def ISABELLE_TOOLS}, in order to provide component-specific
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   243
    tools that can be invoked by end-users. For example:
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   244
    @{verbatim [display] \<open>ISABELLE_TOOLS="$ISABELLE_TOOLS:$COMPONENT/lib/Tools"\<close>}
32323
8185d3bfcbf1 tuned "Bootstrapping the environment";
wenzelm
parents: 32088
diff changeset
   245
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   246
    \<^item> \<^verbatim>\<open>etc/components\<close> holds a list of further sub-components of the same
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   247
    structure. The directory specifications given here can be either absolute
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   248
    (with leading \<^verbatim>\<open>/\<close>) or relative to the component's main directory.
32323
8185d3bfcbf1 tuned "Bootstrapping the environment";
wenzelm
parents: 32088
diff changeset
   249
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   250
  The root of component initialization is @{setting ISABELLE_HOME} itself.
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   251
  After initializing all of its sub-components recursively, @{setting
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   252
  ISABELLE_HOME_USER} is included in the same manner (if that directory
63669
256fc20716f2 clarified antiquotations;
wenzelm
parents: 62847
diff changeset
   253
  exists). This allows to install private components via @{path
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   254
  "$ISABELLE_HOME_USER/etc/components"}, although it is often more convenient
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   255
  to do that programmatically via the \<^verbatim>\<open>init_component\<close> shell function in the
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   256
  \<^verbatim>\<open>etc/settings\<close> script of \<^verbatim>\<open>$ISABELLE_HOME_USER\<close> (or any other component
66947
wenzelm
parents: 66906
diff changeset
   257
  directory). For example:
wenzelm
parents: 66906
diff changeset
   258
  @{verbatim [display] \<open>init_component "$HOME/screwdriver-2.0"\<close>}
48838
623ba165d059 direct support for component forests via init_components;
wenzelm
parents: 48813
diff changeset
   259
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   260
  This is tolerant wrt.\ missing component directories, but might produce a
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   261
  warning.
48838
623ba165d059 direct support for component forests via init_components;
wenzelm
parents: 48813
diff changeset
   262
61406
eb2463fc4d7b more symbols;
wenzelm
parents: 59904
diff changeset
   263
  \<^medskip>
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   264
  More complex situations may be addressed by initializing components listed
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   265
  in a given catalog file, relatively to some base directory:
61407
7ba7b8103565 @{verbatim [display]} supersedes old alltt/ttbox;
wenzelm
parents: 61406
diff changeset
   266
  @{verbatim [display] \<open>init_components "$HOME/my_component_store" "some_catalog_file"\<close>}
48838
623ba165d059 direct support for component forests via init_components;
wenzelm
parents: 48813
diff changeset
   267
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   268
  The component directories listed in the catalog file are treated as relative
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   269
  to the given base directory.
48844
6408fb6f7d81 some explanations on isabelle components;
wenzelm
parents: 48838
diff changeset
   270
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   271
  See also \secref{sec:tool-components} for some tool-support for resolving
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   272
  components that are formally initialized but not installed yet.
58618
782f0b662cae more cartouches;
wenzelm
parents: 58553
diff changeset
   273
\<close>
32323
8185d3bfcbf1 tuned "Bootstrapping the environment";
wenzelm
parents: 32088
diff changeset
   274
8185d3bfcbf1 tuned "Bootstrapping the environment";
wenzelm
parents: 32088
diff changeset
   275
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   276
section \<open>The Isabelle tool wrapper \label{sec:isabelle-tool}\<close>
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
   277
58618
782f0b662cae more cartouches;
wenzelm
parents: 58553
diff changeset
   278
text \<open>
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   279
  The main \<^emph>\<open>Isabelle tool wrapper\<close> provides a generic startup environment for
64509
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   280
  Isabelle-related utilities, user interfaces, add-on applications etc. Such
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   281
  tools automatically benefit from the settings mechanism
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   282
  (\secref{sec:settings}). Moreover, this is the standard way to invoke
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   283
  Isabelle/Scala functionality as a separate operating-system process.
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   284
  Isabelle command-line tools are run uniformly via a common wrapper ---
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   285
  @{executable_ref isabelle}:
61407
7ba7b8103565 @{verbatim [display]} supersedes old alltt/ttbox;
wenzelm
parents: 61406
diff changeset
   286
  @{verbatim [display]
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   287
\<open>Usage: isabelle TOOL [ARGS ...]
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   288
62829
4141c2a8458b clarified Isabelle tool wrapper: bash, Scala, no perl, no ML;
wenzelm
parents: 62677
diff changeset
   289
  Start Isabelle TOOL with ARGS; pass "-?" for tool-specific help.
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   290
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   291
Available tools:
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   292
  ...\<close>}
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   293
64509
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   294
  Tools may be implemented in Isabelle/Scala or as stand-alone executables
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   295
  (usually as GNU bash scripts). In the invocation of ``@{executable
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   296
  isabelle}~\<open>tool\<close>'', the named \<open>tool\<close> is resolved as follows (and in the
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   297
  given order).
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   298
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   299
    \<^enum> An external tool found on the directories listed in the @{setting
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   300
    ISABELLE_TOOLS} settings variable (colon-separated list in standard POSIX
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   301
    notation).
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   302
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   303
      \<^enum> If a file ``\<open>tool\<close>\<^verbatim>\<open>.scala\<close>'' is found, the source needs to define
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   304
      some object that extends the class \<^verbatim>\<open>Isabelle_Tool.Body\<close>. The Scala
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   305
      compiler is invoked on the spot (which may take some time), and the body
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   306
      function is run with the command-line arguments as \<^verbatim>\<open>List[String]\<close>.
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   307
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   308
      \<^enum> If an executable file ``\<open>tool\<close>'' is found, it is invoked as
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   309
      stand-alone program with the command-line arguments provided as \<^verbatim>\<open>argv\<close>
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   310
      array.
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   311
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   312
    \<^enum> An internal tool that is registered in \<^verbatim>\<open>Isabelle_Tool.internal_tools\<close>
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   313
    within the Isabelle/Scala namespace of \<^verbatim>\<open>Pure.jar\<close>. This is the preferred
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   314
    entry-point for high-end tools implemented in Isabelle/Scala --- compiled
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   315
    once when the Isabelle distribution is built. These tools are provided by
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   316
    Isabelle/Pure and cannot be augmented in user-space.
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   317
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   318
  There are also some administrative tools that are available from a bare
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   319
  repository clone of Isabelle, but not in regular distributions.
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   320
\<close>
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   321
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   322
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   323
subsubsection \<open>Examples\<close>
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   324
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   325
text \<open>
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   326
  Show the list of available documentation of the Isabelle distribution:
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   327
  @{verbatim [display] \<open>isabelle doc\<close>}
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   328
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   329
  View a certain document as follows:
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   330
  @{verbatim [display] \<open>isabelle doc system\<close>}
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   331
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   332
  Query the Isabelle settings environment:
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   333
  @{verbatim [display] \<open>isabelle getenv ISABELLE_HOME_USER\<close>}
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   334
\<close>
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   335
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   336
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   337
section \<open>The raw Isabelle ML process\<close>
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   338
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   339
subsection \<open>Batch mode \label{sec:tool-process}\<close>
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   340
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   341
text \<open>
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   342
  The @{tool_def process} tool runs the raw ML process in batch mode:
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   343
  @{verbatim [display]
62634
aa3b47b32100 less physical "logic" argument, with option -l like "isabelle console" etc.;
wenzelm
parents: 62588
diff changeset
   344
\<open>Usage: isabelle process [OPTIONS]
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
   345
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
   346
  Options are:
62677
0df43889f496 isabelle process -T THEORY;
wenzelm
parents: 62643
diff changeset
   347
    -T THEORY    load theory
62639
699e86051e35 isabelle process -d;
wenzelm
parents: 62634
diff changeset
   348
    -d DIR       include session directory
62506
860cd901ab43 clarified isabelle_process;
wenzelm
parents: 62475
diff changeset
   349
    -e ML_EXPR   evaluate ML expression on startup
860cd901ab43 clarified isabelle_process;
wenzelm
parents: 62475
diff changeset
   350
    -f ML_FILE   evaluate ML file on startup
62634
aa3b47b32100 less physical "logic" argument, with option -l like "isabelle console" etc.;
wenzelm
parents: 62588
diff changeset
   351
    -l NAME      logic session name (default ISABELLE_LOGIC="HOL")
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
   352
    -m MODE      add print mode for output
52056
fc458f304f93 added isabelle-process option -o;
wenzelm
parents: 52054
diff changeset
   353
    -o OPTION    override Isabelle system OPTION (via NAME=VAL or NAME)
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
   354
62634
aa3b47b32100 less physical "logic" argument, with option -l like "isabelle console" etc.;
wenzelm
parents: 62588
diff changeset
   355
  Run the raw Isabelle ML process in batch mode.\<close>}
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
   356
62643
6f7ac44365d7 eliminated without magic name;
wenzelm
parents: 62640
diff changeset
   357
  \<^medskip>
62506
860cd901ab43 clarified isabelle_process;
wenzelm
parents: 62475
diff changeset
   358
  Options \<^verbatim>\<open>-e\<close> and \<^verbatim>\<open>-f\<close> allow to evaluate ML code, before the ML process is
860cd901ab43 clarified isabelle_process;
wenzelm
parents: 62475
diff changeset
   359
  started. The source is either given literally or taken from a file. Multiple
860cd901ab43 clarified isabelle_process;
wenzelm
parents: 62475
diff changeset
   360
  \<^verbatim>\<open>-e\<close> and \<^verbatim>\<open>-f\<close> options are evaluated in the given order. Errors lead to
860cd901ab43 clarified isabelle_process;
wenzelm
parents: 62475
diff changeset
   361
  premature exit of the ML process with return code 1.
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
   362
61406
eb2463fc4d7b more symbols;
wenzelm
parents: 59904
diff changeset
   363
  \<^medskip>
62677
0df43889f496 isabelle process -T THEORY;
wenzelm
parents: 62643
diff changeset
   364
  Option \<^verbatim>\<open>-T\<close> loads a specified theory file. This is a wrapper for \<^verbatim>\<open>-e\<close> with
0df43889f496 isabelle process -T THEORY;
wenzelm
parents: 62643
diff changeset
   365
  a suitable @{ML use_thy} invocation.
0df43889f496 isabelle process -T THEORY;
wenzelm
parents: 62643
diff changeset
   366
0df43889f496 isabelle process -T THEORY;
wenzelm
parents: 62643
diff changeset
   367
  \<^medskip>
62639
699e86051e35 isabelle process -d;
wenzelm
parents: 62634
diff changeset
   368
  Option \<^verbatim>\<open>-l\<close> specifies the logic session name. Option \<^verbatim>\<open>-d\<close> specifies
699e86051e35 isabelle process -d;
wenzelm
parents: 62634
diff changeset
   369
  additional directories for session roots, see also \secref{sec:tool-build}.
62634
aa3b47b32100 less physical "logic" argument, with option -l like "isabelle console" etc.;
wenzelm
parents: 62588
diff changeset
   370
aa3b47b32100 less physical "logic" argument, with option -l like "isabelle console" etc.;
wenzelm
parents: 62588
diff changeset
   371
  \<^medskip>
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   372
  The \<^verbatim>\<open>-m\<close> option adds identifiers of print modes to be made active for this
62573
27f90319a499 isabelle.Build uses ML_Process directly;
wenzelm
parents: 62562
diff changeset
   373
  session. For example, \<^verbatim>\<open>-m ASCII\<close> prefers ASCII replacement syntax over
27f90319a499 isabelle.Build uses ML_Process directly;
wenzelm
parents: 62562
diff changeset
   374
  mathematical Isabelle symbols.
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
   375
61406
eb2463fc4d7b more symbols;
wenzelm
parents: 59904
diff changeset
   376
  \<^medskip>
61575
f18f6e51e901 tuned whitespace;
wenzelm
parents: 61572
diff changeset
   377
  Option \<^verbatim>\<open>-o\<close> allows to override Isabelle system options for this process,
62573
27f90319a499 isabelle.Build uses ML_Process directly;
wenzelm
parents: 62562
diff changeset
   378
  see also \secref{sec:system-options}.
58618
782f0b662cae more cartouches;
wenzelm
parents: 58553
diff changeset
   379
\<close>
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
   380
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
   381
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   382
subsubsection \<open>Example\<close>
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
   383
58618
782f0b662cae more cartouches;
wenzelm
parents: 58553
diff changeset
   384
text \<open>
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   385
  The subsequent example retrieves the \<^verbatim>\<open>Main\<close> theory value from the theory
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   386
  loader within ML:
62634
aa3b47b32100 less physical "logic" argument, with option -l like "isabelle console" etc.;
wenzelm
parents: 62588
diff changeset
   387
  @{verbatim [display] \<open>isabelle process -e 'Thy_Info.get_theory "Main"'\<close>}
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   388
64509
80aaa4ff7fed documentation for Isabelle/Scala tools;
wenzelm
parents: 63995
diff changeset
   389
  Observe the delicate quoting rules for the GNU bash shell vs.\ ML. The
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   390
  Isabelle/ML and Scala libraries provide functions for that, but here we need
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   391
  to do it manually.
58618
782f0b662cae more cartouches;
wenzelm
parents: 58553
diff changeset
   392
\<close>
28238
398bf960d3d4 misc tuning and modernization;
wenzelm
parents: 28223
diff changeset
   393
398bf960d3d4 misc tuning and modernization;
wenzelm
parents: 28223
diff changeset
   394
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   395
subsection \<open>Interactive mode\<close>
28238
398bf960d3d4 misc tuning and modernization;
wenzelm
parents: 28223
diff changeset
   396
58618
782f0b662cae more cartouches;
wenzelm
parents: 58553
diff changeset
   397
text \<open>
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   398
  The @{tool_def console} tool runs the raw ML process with interactive
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   399
  console and line editor:
61407
7ba7b8103565 @{verbatim [display]} supersedes old alltt/ttbox;
wenzelm
parents: 61406
diff changeset
   400
  @{verbatim [display]
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   401
\<open>Usage: isabelle console [OPTIONS]
28238
398bf960d3d4 misc tuning and modernization;
wenzelm
parents: 28223
diff changeset
   402
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   403
  Options are:
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   404
    -d DIR       include session directory
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   405
    -l NAME      logic session name (default ISABELLE_LOGIC)
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   406
    -m MODE      add print mode for output
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   407
    -n           no build of session image on startup
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   408
    -o OPTION    override Isabelle system OPTION (via NAME=VAL or NAME)
62643
6f7ac44365d7 eliminated without magic name;
wenzelm
parents: 62640
diff changeset
   409
    -r           bootstrap from raw Poly/ML
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   410
    -s           system build mode for session image
28238
398bf960d3d4 misc tuning and modernization;
wenzelm
parents: 28223
diff changeset
   411
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   412
  Build a logic session image and run the raw Isabelle ML process
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   413
  in interactive mode, with line editor ISABELLE_LINE_EDITOR.\<close>}
28238
398bf960d3d4 misc tuning and modernization;
wenzelm
parents: 28223
diff changeset
   414
62643
6f7ac44365d7 eliminated without magic name;
wenzelm
parents: 62640
diff changeset
   415
  \<^medskip>
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   416
  Option \<^verbatim>\<open>-l\<close> specifies the logic session name. By default, its heap image is
62643
6f7ac44365d7 eliminated without magic name;
wenzelm
parents: 62640
diff changeset
   417
  checked and built on demand, but the option \<^verbatim>\<open>-n\<close> skips that.
28238
398bf960d3d4 misc tuning and modernization;
wenzelm
parents: 28223
diff changeset
   418
62643
6f7ac44365d7 eliminated without magic name;
wenzelm
parents: 62640
diff changeset
   419
  Option \<^verbatim>\<open>-r\<close> indicates a bootstrap from the raw Poly/ML system, which is
6f7ac44365d7 eliminated without magic name;
wenzelm
parents: 62640
diff changeset
   420
  relevant for Isabelle/Pure development.
6f7ac44365d7 eliminated without magic name;
wenzelm
parents: 62640
diff changeset
   421
6f7ac44365d7 eliminated without magic name;
wenzelm
parents: 62640
diff changeset
   422
  \<^medskip>
62639
699e86051e35 isabelle process -d;
wenzelm
parents: 62634
diff changeset
   423
  Options \<^verbatim>\<open>-d\<close>, \<^verbatim>\<open>-m\<close>, \<^verbatim>\<open>-o\<close> have the same meaning as for @{tool process}
699e86051e35 isabelle process -d;
wenzelm
parents: 62634
diff changeset
   424
  (\secref{sec:tool-process}).
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   425
62639
699e86051e35 isabelle process -d;
wenzelm
parents: 62634
diff changeset
   426
  Option \<^verbatim>\<open>-s\<close> has the same meaning as for @{tool build}
699e86051e35 isabelle process -d;
wenzelm
parents: 62634
diff changeset
   427
  (\secref{sec:tool-build}).
28238
398bf960d3d4 misc tuning and modernization;
wenzelm
parents: 28223
diff changeset
   428
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   429
  \<^medskip>
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   430
  The Isabelle/ML process is run through the line editor that is specified via
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   431
  the settings variable @{setting ISABELLE_LINE_EDITOR} (e.g.\
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   432
  @{executable_def rlwrap} for GNU readline); the fall-back is to use plain
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   433
  standard input/output.
28238
398bf960d3d4 misc tuning and modernization;
wenzelm
parents: 28223
diff changeset
   434
62588
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   435
  The user is connected to the raw ML toplevel loop: this is neither
cd266473b81b isabelle_process is superseded by "isabelle process" tool;
wenzelm
parents: 62576
diff changeset
   436
  Isabelle/Isar nor Isabelle/ML within the usual formal context. The most
62847
1bd1d8492931 clarified bootstrap;
wenzelm
parents: 62829
diff changeset
   437
  relevant ML commands at this stage are @{ML use} (for ML files) and
1bd1d8492931 clarified bootstrap;
wenzelm
parents: 62829
diff changeset
   438
  @{ML use_thy} (for theory files).
58618
782f0b662cae more cartouches;
wenzelm
parents: 58553
diff changeset
   439
\<close>
28215
a1cfc43ac47d converted basics.tex to theory file;
wenzelm
parents:
diff changeset
   440
62451
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   441
63995
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   442
section \<open>The raw Isabelle Java process \label{sec:isabelle-java}\<close>
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   443
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   444
text \<open>
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   445
  The @{executable_ref isabelle_java} executable allows to run a Java process
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   446
  within the name space of Java and Scala components that are bundled with
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   447
  Isabelle, but \<^emph>\<open>without\<close> the Isabelle settings environment
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   448
  (\secref{sec:settings}).
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   449
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   450
  After such a JVM cold-start, the Isabelle environment can be accessed via
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   451
  \<^verbatim>\<open>Isabelle_System.getenv\<close> as usual, but the underlying process environment
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   452
  remains clean. This is e.g.\ relevant when invoking other processes that
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   453
  should remain separate from the current Isabelle installation.
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   454
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   455
  \<^medskip>
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   456
  Note that under normal circumstances, Isabelle command-line tools are run
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   457
  \<^emph>\<open>within\<close> the settings environment, as provided by the @{executable
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   458
  isabelle} wrapper (\secref{sec:isabelle-tool} and \secref{sec:tool-java}).
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   459
\<close>
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   460
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   461
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   462
subsubsection \<open>Example\<close>
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   463
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   464
text \<open>
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   465
  The subsequent example creates a raw Java process on the command-line and
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   466
  invokes the main Isabelle application entry point:
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   467
  @{verbatim [display] \<open>isabelle_java isabelle.Main\<close>}
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   468
\<close>
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   469
2e4d80723fb0 added isabelle_java cold-start executable;
wenzelm
parents: 63680
diff changeset
   470
67904
465f43a9f780 documentation for the Isabelle server;
wenzelm
parents: 67399
diff changeset
   471
section \<open>YXML versus XML \label{sec:yxml-vs-xml}\<close>
62451
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   472
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   473
text \<open>
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   474
  Isabelle tools often use YXML, which is a simple and efficient syntax for
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   475
  untyped XML trees. The YXML format is defined as follows.
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   476
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   477
    \<^enum> The encoding is always UTF-8.
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   478
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   479
    \<^enum> Body text is represented verbatim (no escaping, no special treatment of
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   480
    white space, no named entities, no CDATA chunks, no comments).
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   481
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   482
    \<^enum> Markup elements are represented via ASCII control characters \<open>\<^bold>X = 5\<close>
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   483
    and \<open>\<^bold>Y = 6\<close> as follows:
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   484
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   485
    \begin{tabular}{ll}
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   486
      XML & YXML \\\hline
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   487
      \<^verbatim>\<open><\<close>\<open>name attribute\<close>\<^verbatim>\<open>=\<close>\<open>value \<dots>\<close>\<^verbatim>\<open>>\<close> &
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   488
      \<open>\<^bold>X\<^bold>Yname\<^bold>Yattribute\<close>\<^verbatim>\<open>=\<close>\<open>value\<dots>\<^bold>X\<close> \\
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   489
      \<^verbatim>\<open></\<close>\<open>name\<close>\<^verbatim>\<open>>\<close> & \<open>\<^bold>X\<^bold>Y\<^bold>X\<close> \\
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   490
    \end{tabular}
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   491
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   492
    There is no special case for empty body text, i.e.\ \<^verbatim>\<open><foo/>\<close> is treated
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   493
    like \<^verbatim>\<open><foo></foo>\<close>. Also note that \<open>\<^bold>X\<close> and \<open>\<^bold>Y\<close> may never occur in
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   494
    well-formed XML documents.
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   495
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   496
  Parsing YXML is pretty straight-forward: split the text into chunks
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   497
  separated by \<open>\<^bold>X\<close>, then split each chunk into sub-chunks separated by \<open>\<^bold>Y\<close>.
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   498
  Markup chunks start with an empty sub-chunk, and a second empty sub-chunk
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   499
  indicates close of an element. Any other non-empty chunk consists of plain
63680
6e1e8b5abbfa more symbols;
wenzelm
parents: 63669
diff changeset
   500
  text. For example, see \<^file>\<open>~~/src/Pure/PIDE/yxml.ML\<close> or
6e1e8b5abbfa more symbols;
wenzelm
parents: 63669
diff changeset
   501
  \<^file>\<open>~~/src/Pure/PIDE/yxml.scala\<close>.
62451
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   502
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   503
  YXML documents may be detected quickly by checking that the first two
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   504
  characters are \<open>\<^bold>X\<^bold>Y\<close>.
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   505
\<close>
040b94ffbdde removed pointless "isabelle yxml";
wenzelm
parents: 62354
diff changeset
   506
67399
eab6ce8368fa ran isabelle update_op on all sources
nipkow
parents: 67044
diff changeset
   507
end