SafeHaskell: Initial work on documentation

6 files changed, 309 insertions, 7 deletions

diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml
index 3e70be999b..43c713e119 100644
--- a/docs/users_guide/flags.xml
+++ b/docs/users_guide/flags.xml
@@ -599,6 +599,26 @@
 	      <entry>dynamic</entry>
 	      <entry>-</entry>
 	    </row>
+	    <row>
+	      <entry><option>-trust</option> <replaceable>P</replaceable></entry>
+        <entry>Expose package <replaceable>P</replaceable> and set it to be
+          trusted</entry>
+	      <entry>static/<literal>:set</literal></entry>
+	      <entry>-</entry>
+	    </row>
+	    <row>
+	      <entry><option>-distrust</option> <replaceable>P</replaceable></entry>
+        <entry>Expose package <replaceable>P</replaceable> and set it to be
+          distrusted</entry>
+	      <entry>static/<literal>:set</literal></entry>
+	      <entry>-</entry>
+	    </row>
+	    <row>
+	      <entry><option>-distrust-all</option> </entry>
+        <entry>Distrust all packages by default</entry>
+	      <entry>static/<literal>:set</literal></entry>
+	      <entry>-</entry>
+	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
@@ -1033,6 +1053,30 @@
 	      <entry>dynamic</entry>
 	      <entry><option>-XNoPackageImports</option></entry>
 	    </row>
+	    <row>
+	      <entry><option>-XSafe</option></entry>
+        <entry>Enable the <link linkend="safe-haskell">Safe Haskell</link> Safe mode.</entry>
+	      <entry>dynamic</entry>
+	      <entry><option>-</option></entry>
+	    </row>
+	    <row>
+	      <entry><option>-XTrustworthy</option></entry>
+        <entry>Enable the <link linkend="safe-haskell">Safe Haskell</link> Trustworthy mode.</entry>
+	      <entry>dynamic</entry>
+	      <entry><option>-</option></entry>
+	    </row>
+	    <row>
+	      <entry><option>-XSafeLanguage</option></entry>
+        <entry>Enable the <link linkend="safe-haskell">Safe Haskell</link> Safe Language.</entry>
+	      <entry>dynamic</entry>
+	      <entry><option>-</option></entry>
+	    </row>
+	    <row>
+	      <entry><option>-XSafeImports</option></entry>
+        <entry>Enable <link linkend="safe-imports-ext">Safe Imports</link>.</entry>
+	      <entry>dynamic</entry>
+	      <entry><option>-</option></entry>
+	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index e1795f2b28..09a9062ffc 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -1897,6 +1897,25 @@ import "network" Network.Socket
     another, rendering any package-qualified imports broken.</para>
 </sect2>
 
+<sect2 id="safe-imports-ext">
+  <title>Safe imports</title>
+
+  <para>With the <option>-XSafeImports</option> flag, GHC extends
+	the import declaration syntax to take an optional <literal>safe</literal>
+	keyword after the <literal>import</literal> keyword.  This feature
+	is part of the Safe Haskell GHC extension.  For example:</para>
+
+<programlisting>
+import safe qualified Network.Socket as NS
+</programlisting>
+
+  <para>would import the module <literal>Network.Socket</literal>
+  with compilation only succeeding if Network.Socket can be
+	safely imported. For a description of when a import is
+	considered safe see <xref linkend="safe-haskell"/></para>
+
+</sect2>
+
 <sect2 id="syntax-stolen">
 <title>Summary of stolen syntax</title>
 
@@ -9411,7 +9430,6 @@ standard behaviour.
 </sect1>
 
 
-
 <!-- Emacs stuff:
      ;;; Local Variables: ***
      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
diff --git a/docs/users_guide/lang.xml b/docs/users_guide/lang.xml
index 3870dd72a3..95f70894d2 100644
--- a/docs/users_guide/lang.xml
+++ b/docs/users_guide/lang.xml
@@ -4,6 +4,7 @@
 
 &glasgowexts;
 &parallel;
+&safehaskell;
 
 </chapter>
 
diff --git a/docs/users_guide/packages.xml b/docs/users_guide/packages.xml
index 0a8412bbd2..3076a2aa2f 100644
--- a/docs/users_guide/packages.xml
+++ b/docs/users_guide/packages.xml
@@ -101,6 +101,13 @@ $ ghc-pkg list
       directly.
     </para>
 
+    <para>Similar to a package's hidden status is a package's trusted
+      status. A package can be either trusted or not trusted (distrusted).
+      By default packages are distrusted. This property of a package only
+      plays a role when compiling code using GHC's Safe Haskell feature
+      (see <xref linkend="safe-haskell"/>).
+    </para>
+
     <para>To see which modules are provided by a package use the
       <literal>ghc-pkg</literal> command (see <xref linkend="package-management"/>):</para>
 
@@ -265,6 +272,53 @@ exposed-modules: Network.BSD,
             <literal>-package mypkg-1.2</literal>.</para>
         </listitem>
       </varlistentry>
+
+      <varlistentry>
+        <term><option>-trust</option> <replaceable>P</replaceable>
+        <indexterm><primary><option>-trust</option></primary>
+          </indexterm></term>
+        <listitem>
+          <para>This option causes the install package <replaceable>P
+            </replaceable> to be both exposed and trusted by GHC. This
+            command functions in the in a very similar way to the <option>
+            -package</option> command but in addition sets the selected
+            packaged to be trusted by GHC, regardless of the contents of
+            the package database. (see <xref linkend="safe-haskell"/>).
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-distrust</option> <replaceable>P</replaceable>
+        <indexterm><primary><option>-distrust</option></primary>
+          </indexterm></term>
+        <listitem>
+          <para>This option causes the install package <replaceable>P
+            </replaceable> to be both exposed and distrusted by GHC. This
+            command functions in the in a very similar way to the <option>
+            -package</option> command but in addition sets the selected
+            packaged to be distrusted by GHC, regardless of the contents of
+            the package database. (see <xref linkend="safe-haskell"/>).
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-distrust-all</option>
+        <indexterm><primary><option>-distrust-all</option></primary>
+          </indexterm></term>
+        <listitem>
+          <para>Ignore the trusted flag on installed packages, and distrust
+            them by default. If you use this flag and Safe Haskell then any
+            packages you require to be trusted (including <literal>base
+            </literal>) need to be explicitly trusted using <option>-trust
+            </option> options. This option does not change the exposed/hidden
+            status of a package, so it isn't equivalent to applying <option>
+            -distrust</option> to all packages on the system. (see
+            <xref linkend="safe-haskell"/>).
+          </para>
+        </listitem>
+      </varlistentry>
     </variablelist>
   </sect2>
 
@@ -624,6 +678,15 @@ haskell98-1.0.1.0
       </varlistentry>
 
       <varlistentry>
+        <term><literal>ghc-pkg check</literal></term>
+        <listitem>
+          <para>Check consistency of dependencies in the package
+          database, and report packages that have missing
+          dependencies.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
         <term><literal>ghc-pkg expose <replaceable>P</replaceable></literal></term>
         <listitem>
           <para>Sets the <literal>exposed</literal> flag for package
@@ -632,18 +695,25 @@ haskell98-1.0.1.0
       </varlistentry>
 
       <varlistentry>
-        <term><literal>ghc-pkg check</literal></term>
+        <term><literal>ghc-pkg hide <replaceable>P</replaceable></literal></term>
         <listitem>
-          <para>Check consistency of dependencies in the package
-          database, and report packages that have missing
-          dependencies.</para>
+          <para>Sets the <literal>exposed</literal> flag for package
+            <replaceable>P</replaceable> to <literal>False</literal>.</para>
         </listitem>
       </varlistentry>
 
       <varlistentry>
-        <term><literal>ghc-pkg hide <replaceable>P</replaceable></literal></term>
+        <term><literal>ghc-pkg trust <replaceable>P</replaceable></literal></term>
         <listitem>
-          <para>Sets the <literal>exposed</literal> flag for package
+          <para>Sets the <literal>trusted</literal> flag for package
+            <replaceable>P</replaceable> to <literal>True</literal>.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><literal>ghc-pkg distrust <replaceable>P</replaceable></literal></term>
+        <listitem>
+          <para>Sets the <literal>trusted</literal> flag for package
             <replaceable>P</replaceable> to <literal>False</literal>.</para>
         </listitem>
       </varlistentry>
@@ -1093,6 +1163,7 @@ exposed-modules: System.Posix System.Posix.DynamicLinker.Module
                  System.Posix.Signals.Exts System.Posix.Semaphore
                  System.Posix.SharedMem
 hidden-modules:
+trusted: False
 import-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0
 library-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0
 hs-libraries: HSunix-2.3.1.0
@@ -1325,6 +1396,16 @@ haddock-html: /usr/share/doc/ghc/html/libraries/unix
 
         <varlistentry>
           <term>
+            <literal>trusted</literal>
+            <indexterm><primary><literal>trusted</literal></primary><secondary>package specification</secondary></indexterm>
+          </term>
+          <listitem>
+            <para>(bool) Whether the package is trusted or not.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
             <literal>import-dirs</literal>
             <indexterm><primary><literal>import-dirs</literal></primary><secondary>package specification</secondary></indexterm>
           </term>
diff --git a/docs/users_guide/safe_haskell.xml b/docs/users_guide/safe_haskell.xml
new file mode 100644
index 0000000000..efb842b072
--- /dev/null
+++ b/docs/users_guide/safe_haskell.xml
@@ -0,0 +1,157 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<sect1 id="safe-haskell">
+  <title>Safe Haskell</title>
+  
+  Safe Haskell is an extension to the Haskell language supported by GHC, that
+  provides certain safety guarantees about Haskell code compiled using this
+  extension. It allows people to build more advance security mechanisms on top
+  of Haskell and for the safe execution of untrusted Haskell code. Its purpose
+  isn't to provide a complete secure execution environment for Haskell code but
+  to give users enough guarantees about the Haskell language to be able to
+  build such systems. Its design is similar to the safe and unsafe module
+  system supported by the Modula-3 language.
+  
+  The design of Safe Haskell covers the following aspects:
+  <itemizedlist>
+    <listitem>A <link linkend="safe-language">safe language</link>dialect of
+      Haskell that provides guarantees about the code. Mainly it allows the
+      types and module boundaries to be trusted.
+    </listitem>
+    <listitem>A new <emphasis>safe import</emphasis> extension that specifies
+      the module being imported must be trusted.
+    </listitem>
+    <listitem>A definition of <emphasis>trust</emphasis> (or safety) and how it
+      operates, along with ways of defining and changing the trust of modules
+      and packages.
+    </listitem>
+  </itemizedlist>
+  
+  <sect2 id="safe-language">
+    <title>Safe Language</title>
+
+    The Safe Haskell <emphasis>Safe language</emphasis> guarantees the
+    following properties:
+    <itemizedlist>
+      <listitem><emphasis>Referential transparency.</emphasis> Functions
+        in the Safe language are deterministic, evaluating them will not
+        cause any side effects. Functions in the <emphasis>IO</emphasis>
+        monad are still allowed and behave as usual but any pure function
+        as according to the functions type is guaranteed to indeed be
+        pure. This property allows a user of the Safe language to trust
+        the types of functions.
+      </listitem>
+      <listitem><emphasis>Module boundary control.</emphasis> Haskell code
+        compiled using the Safe language is guaranteed to only access
+        symbols that are publicly available to it through other modules
+        export lists. An import part of this is that safe compiled code
+        is not able to examine or create data values using data constructors
+        that the module cannot import. If a module M establishes some
+        invariants through careful use of its export list then code
+        compiled using the Safe language that imports M is guaranteed to
+        respect those invariants.
+      </listitem>
+      <listitem><emphasis>Semantic consistency.</emphasis> The Safe language
+        is strictly a subset of Haskell as implemented by GHC. Any expression
+        that compiles in the safe language has the same meaning as it does
+        when compiled in normal Haskell. In addtion, in any module that imports
+        a Safe language module, expressions that compile both with and without
+        the safe import have the same meaning in both cases. That is, importing
+        a module using the Safe language cannot change the meaning of existing
+        code that isn't dependent on that module.
+      </listitem>
+    </itemizedlist>
+    
+    Put simply, these three properties guarantee that you can trust the types
+    in the Safe language, can trust module export lists are respected
+    in the Safe language and that code which succesfully compiles in the Safe
+    language has the same meaning as it normally would.
+  </sect2>
+
+  <sect2 id="safe-imports">
+    <title>Safe Imports</title>
+
+    Safe Haskell enables a small extension to the usual import syntax of
+    Haskell, adding a <emphasis>safe</emphasis> keyword:
+
+    <programlisting>
+      impdecl -> import [safe] [qualified] modid [as modid] [impspec]
+    </programlisting>
+
+    When used, the module being imported with the safe keyword must be a trusted
+    module, otherwise a compilation error will occur. The safe import extension
+    is enabled by either of the <emphasis>-XSafe</emphasis>,
+    <emphasis>-XTrustworthy</emphasis>, <emphasis>-XSafeLanguage</emphasis> or
+    <emphasis>-XSafeImports</emphasis> flags and corresponding PRAGMA's. When
+    either the <empahsis>-XSafe</empahsis> or
+    <emphasis>-XSafeLanguage</emphasis> flag is used, all imports are assumed to
+    be safe imports.
+  </sect2>
+
+  <sect2 id="safe-trust">
+    <title>Trust</title>
+
+    The Safe Haskell extension introduces the following two new language flags:
+    <itemizedlist>
+      <listitem><emphasis>-XSafe:</emphasis> Enables the Safe language dialect,
+      asking GHC to guarantee trust. The safe language dialect requires that
+      all imports be trusted or a compile error will occur.</listitem>
+      <listitem><emphasis>-XTrustworthy:</emphasis> Means that while this module
+      may invoke unsafe functions internally, the module's author claims that
+      it exports an API that can't be used in an unsafe way. This doesn't enable
+      the Safe language or place any restrictions on the allowed Haskell code.
+      The trust guarantee is provided by the module author, not GHC. Modules
+      imported with the <emphasis>safe</emphasis> import feature are required
+      to be trusted but otherwise unsafe modules can be imported as usual.
+      </listitem>
+    </itemizedlist>
+
+    The definition of trust for a module <emphasis>M</emphasis>, residing in
+    a package <emphasis>P</emphasis> for a user of GHC, a client
+    <emphasis>C</emphasis> (someone who is compiling a source module with GHC,
+    aka you!), is defined as follows:
+
+    A <emphasis>package P is trusted by client C</emphasis> if and only if one of
+    these conditions hold:
+    <itemizedlist>
+      <listitem>C's package database records that P is trusted (and no
+        command line arguments override this).</listitem>
+      <listitem>C's command-line flags say to trust it regardless of the
+        what is recorded in the package database.</listitem>
+    </itemizedlist>
+
+    It is important to note that C is the only authority on package trust. It is
+    up to the client to decide which packages they trust.
+
+    A <emphasis>module M is trusted by a client C</emphasis> if and only if:
+    <itemizedlist>
+      <listitem>Both of these hold:
+        <itemizedlist>
+          <listitem> The module was compiled with <emphasis>-XSafe</emphasis></listitem>
+          <listitem> All of M's direct imports are trusted by C</listitem>
+        </itemizedlist>
+      </listitem>
+      <listitem><emphasis>OR</emphasis> all of these hold:
+        <itemizedlist>
+          <listitem>The module was compiled with <emphasis>-XTrustworthy</emphasis></listitem>
+          <listitem>All of M's direct safe imports are trusted by C</listitem>
+          <listitem>Package P is trusted by C</listitem>
+        </itemizedlist>
+      </listitem>
+    </itemizedlist>
+
+    For the first trust definition the trust guarantee is provided by GHC
+    through the restrictions imposed by the Safe language. For the second
+    definition of trust, the guarantee is provided initially by the
+    module author. The client C then establishes that they trust the
+    module author by indicating they trust the package the module resides
+    in. This trust chain is required as GHC provides no guarantee for
+    <emphasis>-XTrustworthy</emphasis> compiled modules.
+  </sect2>
+
+</sect1>
+
+<!-- Emacs stuff:
+     ;;; Local Variables: ***
+     ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
+     ;;; End: ***
+ -->
diff --git a/docs/users_guide/ug-ent.xml.in b/docs/users_guide/ug-ent.xml.in
index 040c25267b..2d19d97688 100644
--- a/docs/users_guide/ug-ent.xml.in
+++ b/docs/users_guide/ug-ent.xml.in
@@ -13,6 +13,7 @@
 <!ENTITY glasgowexts    SYSTEM "glasgow_exts.xml" >
 <!ENTITY packages       SYSTEM "packages.xml" >
 <!ENTITY parallel       SYSTEM "parallel.xml" >
+<!ENTITY safehaskell    SYSTEM "safe_haskell.xml" >
 <!ENTITY phases         SYSTEM "phases.xml" >
 <!ENTITY separate       SYSTEM "separate_compilation.xml" >
 <!ENTITY bugs           SYSTEM "bugs.xml" >