diff options
| author | Ben Gamari <ben@smart-cactus.org> | 2015-10-01 01:08:41 +0200 |
|---|---|---|
| committer | Ben Gamari <ben@smart-cactus.org> | 2015-10-03 09:44:48 +0200 |
| commit | 4fd6207ec6960c429e6a1bcbe0282f625010f52a (patch) | |
| tree | 26e1f43199fbde80f26225f7409b5c00ce8792a9 | |
| parent | 9ed700bb4128b1cbf59d99d725c44d7a0bfb1de6 (diff) | |
| download | haskell-4fd6207ec6960c429e6a1bcbe0282f625010f52a.tar.gz | |
Move user's guide to ReStructuredText
131 files changed, 33995 insertions, 40720 deletions
diff --git a/.gitignore b/.gitignore index bb4a2934c7..48ab1943eb 100644 --- a/.gitignore +++ b/.gitignore @@ -39,8 +39,6 @@ configure # Temporarily generated configure files confdefs.h -conftest-book.xml -conftest.xml # ----------------------------------------------------------------------------- # Ignore any overlapped darcs repos and back up files @@ -89,16 +87,14 @@ _darcs/ /distrib/configure.ac /distrib/ghc.iss /docs/index.html -/docs/man/flags.xml -/docs/man/flags.xsl -/docs/man/ghc.1 -/docs/users_guide/ug-book.xml -/docs/users_guide/ug-ent.xml -/docs/users_guide/users_guide.xml +/docs/users_guide/ghc.1 +/docs/users_guide/*.gen.rst +/docs/users_guide/ghc_config.py +/docs/users_guide/ghc_config.pyc /docs/users_guide/users_guide.pdf -/docs/users_guide/users_guide.ps -/docs/users_guide/users_guide/ -/docs/users_guide/what_glasgow_exts_does.gen.xml +/docs/users_guide/build-html +/docs/users_guide/build-pdf +/docs/users_guide/.doctrees /driver/ghci/ghc-pkg-inplace /driver/ghci/ghci-inplace /driver/ghci/ghci.res diff --git a/.travis.yml b/.travis.yml index 3a9d337344..2974b818cd 100644 --- a/.travis.yml +++ b/.travis.yml @@ -41,9 +41,8 @@ before_install: script: # do not build docs - echo 'HADDOCK_DOCS = NO' >> mk/validate.mk - - echo 'BUILD_DOCBOOK_HTML = NO' >> mk/validate.mk - - echo 'BUILD_DOCBOOK_PS = NO' >> mk/validate.mk - - echo 'BUILD_DOCBOOK_PDF = NO' >> mk/validate.mk + - echo 'BUILD_SPHINX_HTML = NO' >> mk/validate.mk + - echo 'BUILD_SPHINX_PDF = NO' >> mk/validate.mk # do not build dynamic libraries - echo 'DYNAMIC_GHC_PROGRAMS = NO' >> mk/validate.mk - echo 'GhcLibWays = v' >> mk/validate.mk diff --git a/INSTALL.md b/INSTALL.md index 58930afeb8..34bb5b45b7 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -13,8 +13,8 @@ because the compiler is itself written in Haskell. For instructions on how to port GHC to a new platform, see the Building Guide [1]. For building library documentation, you'll need Haddock [3]. To build -the compiler documentation, you need a good DocBook XML toolchain and -dblatex. +the compiler documentation, you need [Sphinx](http://www.sphinx-doc.org/) and +Xelatex (only for PDF output). Quick start: the following gives you a default build: @@ -51,8 +51,8 @@ because the compiler is itself written in Haskell. You also need to port GHC to a new platform, see the [GHC Building Guide] [3]. For building library documentation, you'll need [Haddock] [6]. To build -the compiler documentation, you need a good DocBook XML toolchain and -dblatex. +the compiler documentation, you need [Sphinx](http://www.sphinx-doc.org/) +and Xelatex (only for PDF output). **Quick start**: the following gives you a default build: diff --git a/aclocal.m4 b/aclocal.m4 index 2f4d516945..0c2633a090 100644 --- a/aclocal.m4 +++ b/aclocal.m4 @@ -1373,124 +1373,6 @@ AS_IF([test AS_VAR_GET(fp_func) = yes], AS_VAR_POPDEF([fp_func])dnl ])# FP_CHECK_FUNC - -# FP_GEN_DOCBOOK_XML -# ------------------ -# Generates a DocBook XML V4.5 document in conftest.xml. -# -# It took a lot of experimentation to find a document that will cause -# xsltproc to fail with an error code when the relevant -# stylesheets/DTDs are not found. I couldn't make xsltproc fail with -# a single-file document, it seems a multi-file document is needed. -# -- SDM 2009-06-03 -# -AC_DEFUN([FP_GEN_DOCBOOK_XML], -[rm -f conftest.xml conftest-book.xml -cat > conftest.xml << EOF -<?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [[ -<!ENTITY conftest-book SYSTEM "conftest-book.xml"> -]]> -<book id="test"> -&conftest-book; -</book> -EOF -cat >conftest-book.xml << EOF -<?xml version="1.0" encoding="iso-8859-1"?> - <title>A DocBook “Test Document”</title> - <chapter id="id-one"> - <title>A Chapter Title</title> - <para>This is a paragraph, referencing <xref linkend="id-two"/>.</para> - </chapter> - <chapter id="id-two"> - <title>Another Chapter Title</title> - <para>This is another paragraph, referencing <xref linkend="id-one"/>.</para> - </chapter> -EOF -]) # FP_GEN_DOCBOOK_XML - - -# FP_PROG_DBLATEX -# ---------------- -# Sets the output variable DblatexCmd to the full path of dblatex, -# which we use for building PDF and PS docs. -# DblatexCmd is empty if dblatex could not be found. -AC_DEFUN([FP_PROG_DBLATEX], -[AC_PATH_PROG([DblatexCmd], [dblatex]) -if test -z "$DblatexCmd"; then - AC_MSG_WARN([cannot find dblatex in your PATH, you will not be able to build the PDF and PS documentation]) -fi -])# FP_PROG_DBLATEX - - -# FP_PROG_XSLTPROC -# ---------------- -# Sets the output variable XsltprocCmd to the full path of the XSLT processor -# xsltproc. XsltprocCmd is empty if xsltproc could not be found. -AC_DEFUN([FP_PROG_XSLTPROC], -[AC_PATH_PROG([XsltprocCmd], [xsltproc]) -if test -z "$XsltprocCmd"; then - AC_MSG_WARN([cannot find xsltproc in your PATH, you will not be able to build the HTML documentation]) -fi -])# FP_PROG_XSLTPROC - - -# FP_DOCBOOK_XSL -# ---------------------------- -# Check that we can process a DocBook XML document to HTML using xsltproc. -AC_DEFUN([FP_DOCBOOK_XSL], -[AC_REQUIRE([FP_PROG_XSLTPROC])dnl -if test -n "$XsltprocCmd"; then - AC_CACHE_CHECK([for DocBook XSL stylesheet], fp_cv_dir_docbook_xsl, - [FP_GEN_DOCBOOK_XML - fp_cv_dir_docbook_xsl=no - if $XsltprocCmd --nonet http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl conftest.xml > /dev/null 2>&1; then - fp_cv_dir_docbook_xsl=yes - fi - rm -rf conftest*]) -fi -if test x"$fp_cv_dir_docbook_xsl" = xno; then - AC_MSG_WARN([cannot find DocBook XSL stylesheets, you will not be able to build the documentation]) - HAVE_DOCBOOK_XSL=NO -else - HAVE_DOCBOOK_XSL=YES -fi -AC_SUBST([HAVE_DOCBOOK_XSL]) -])# FP_DOCBOOK_XSL - - -# FP_PROG_XMLLINT -# ---------------- -# Sets the output variable XmllintCmd to the full path of the XSLT processor -# xmllint. XmllintCmd is empty if xmllint could not be found. -AC_DEFUN([FP_PROG_XMLLINT], -[AC_PATH_PROG([XmllintCmd], [xmllint]) -if test -z "$XmllintCmd"; then - AC_MSG_WARN([cannot find xmllint in your PATH, you will not be able to validate your documentation]) -fi -])# FP_PROG_XMLLINT - - -# FP_CHECK_DOCBOOK_DTD -# -------------------- -AC_DEFUN([FP_CHECK_DOCBOOK_DTD], -[AC_REQUIRE([FP_PROG_XMLLINT])dnl -if test -n "$XmllintCmd"; then - AC_MSG_CHECKING([for DocBook DTD]) - FP_GEN_DOCBOOK_XML - if $XmllintCmd --nonet --valid --noout conftest.xml ; then - AC_MSG_RESULT([ok]) - else - AC_MSG_RESULT([failed]) - AC_MSG_WARN([cannot find a DTD for DocBook XML V4.5, you will not be able to validate your documentation]) - AC_MSG_WARN([check your XML_CATALOG_FILES environment variable and/or /etc/xml/catalog]) - fi - rm -rf conftest* -fi -])# FP_CHECK_DOCBOOK_DTD - - # FP_PROG_GHC_PKG # ---------------- # Try to find a ghc-pkg matching the ghc mentioned in the environment variable diff --git a/configure.ac b/configure.ac index 406a4a60d4..d890a6f618 100644 --- a/configure.ac +++ b/configure.ac @@ -768,10 +768,11 @@ then HSCOLOUR=`cygpath -m ${HSCOLOUR}` fi -dnl ** check for DocBook toolchain -FP_CHECK_DOCBOOK_DTD -FP_DOCBOOK_XSL -FP_PROG_DBLATEX +dnl ** check for Sphinx toolchain +AC_PATH_PROG(SPHINXBUILD,sphinx-build) + +dnl ** check for xelatex +AC_PATH_PROG(XELATEX,xelatex) dnl ** check for ghc-pkg command FP_PROG_GHC_PKG @@ -1092,25 +1093,22 @@ if test "$use_large_address_space" = "yes" ; then AC_DEFINE([USE_LARGE_ADDRESS_SPACE], [1], [Enable single heap address space support]) fi -if test "$HAVE_DOCBOOK_XSL" = "NO" || - test "$XsltprocCmd" = "" -then - BUILD_DOCBOOK_HTML=NO -else - BUILD_DOCBOOK_HTML=YES -fi -AC_SUBST(BUILD_DOCBOOK_HTML) - -if test "$DblatexCmd" = "" -then - BUILD_DOCBOOK_PS=NO - BUILD_DOCBOOK_PDF=NO +if test -n "$SPHINXBUILD"; then + BUILD_MAN=YES + BUILD_SPHINX_HTML=YES + if test -n "$XELATEX"; then + BUILD_SPHINX_PDF=YES + else + BUILD_SPHINX_PDF=NO + fi else - BUILD_DOCBOOK_PS=YES - BUILD_DOCBOOK_PDF=YES + BUILD_MAN=NO + BUILD_SPHINX_HTML=NO + BUILD_SPHINX_PDF=NO fi -AC_SUBST(BUILD_DOCBOOK_PS) -AC_SUBST(BUILD_DOCBOOK_PDF) +AC_SUBST(BUILD_MAN) +AC_SUBST(BUILD_SPHINX_HTML) +AC_SUBST(BUILD_SPHINX_PDF) LIBRARY_VERSION(base) LIBRARY_VERSION(Cabal, Cabal/Cabal) @@ -1122,7 +1120,7 @@ if grep ' ' compiler/ghc.cabal.in 2>&1 >/dev/null; then AC_MSG_ERROR([compiler/ghc.cabal.in contains tab characters; please remove them]) fi -AC_CONFIG_FILES([mk/config.mk mk/install.mk mk/project.mk compiler/ghc.cabal ghc/ghc-bin.cabal utils/runghc/runghc.cabal settings docs/users_guide/ug-book.xml docs/users_guide/ug-ent.xml docs/index.html libraries/prologue.txt distrib/configure.ac]) +AC_CONFIG_FILES([mk/config.mk mk/install.mk mk/project.mk compiler/ghc.cabal ghc/ghc-bin.cabal utils/runghc/runghc.cabal settings docs/users_guide/ghc_config.py docs/index.html libraries/prologue.txt distrib/configure.ac]) AC_OUTPUT # We got caught by @@ -1181,8 +1179,8 @@ echo ["\ Happy : $HappyCmd ($HappyVersion) Alex : $AlexCmd ($AlexVersion) Perl : $PerlCmd - dblatex : $DblatexCmd - xsltproc : $XsltprocCmd + sphinx-build : $SPHINXBUILD + xelatex : $XELATEX Using LLVM tools llc : $LlcCmd @@ -1199,9 +1197,8 @@ echo ["\ fi echo ["\ - Can build DocBook HTML documentation : $BUILD_DOCBOOK_HTML - Can build DocBook PS documentation : $BUILD_DOCBOOK_PS - Can build DocBook PDF documentation : $BUILD_DOCBOOK_PDF"] + Building Sphinx HTML documentation : $BUILD_SPHINX_HTML + Building Sphinx PDF documentation : $BUILD_SPHINX_PDF"] echo ["---------------------------------------------------------------------- "] diff --git a/docs/man/gen_flags.xsl.sh b/docs/man/gen_flags.xsl.sh deleted file mode 100644 index fed694f1e0..0000000000 --- a/docs/man/gen_flags.xsl.sh +++ /dev/null @@ -1,290 +0,0 @@ -#!/bin/sh - -if [ "$#" -ne 2 ] -then - echo "Usage: $0 <ghc commands> <libdir>" - exit 1 -fi - -GHC_COMMANDS="$1" -LIBDIR="$2" - -cat <<'EOF' -<?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE xsl:stylesheet [ -]> - -<xsl:stylesheet version="1.0" - xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - xmlns="http://www.w3.org/TR/xhtml1/strict"> - -<xsl:output method="text" omit-xml-declaration="yes" /> - -<xsl:template match="/">.\" -.\" This is a generated file. Changes might get clobbered. Edit at own's risk. -.\" -.TH GHC 1 "2002-10-25" "Glasgow FP Suite" "Glasgow Haskell Compiler" -.SH NAME -GHC \- the Glasgow Haskell Compiler - - -.SH SYNOPSIS -EOF - -STARTED=0 - -for GHC_COMMAND in $GHC_COMMANDS -do - if [ "$STARTED" -ne 0 ] - then - echo ".br" - fi - STARTED=1 - cat <<EOF -.B $GHC_COMMAND -.RI [ option | filename ]... -EOF -done - -cat <<'EOF' - -.SH DESCRIPTION -This manual page documents briefly the -.B ghc -and -.B ghci -commands. -Note that -.B ghci -is not yet available on all architectures. -Extensive documentation is available in various other formats -including DVI, PostScript and HTML; see below. - -.PP -Each of GHC's command line options is classified as either -.IR static " or " dynamic . -A static flag may only be specified on the command line, whereas a -dynamic flag may also be given in an \f(CROPTIONS\fP pragma in a -source file or set from the GHCi command-line with \f(CR:set\fP. - -As a rule of thumb, all the language options are dynamic, as are the -warning options and the debugging options. - -The rest are static, with the notable exceptions of -.BR \-v ", " \-cpp ", " \-fasm ", " \-fvia\-C ", " \-fllvm ", and -" \-#include . -The OPTIONS sections lists the status of each flag. - -.PP -Common suffixes of file names for Haskell are: -.TP -.B .hs -Haskell source code; preprocess, compile -.TP -.B .lhs -literate Haskell source; unlit, preprocess, compile -.TP -.B .hi -Interface file; contains information about exported -symbols -.TP -.B .hc -intermediate C files -.TP -.BI . x _o -way -.I x -object files; common ways are: -.BR p ", " u ", " s -.TP -.BI . x _hi -way -.I x -interface files - - -.SH OPTIONS - -<xsl:apply-templates select="sect1/sect2" mode="overview"/> - -<xsl:apply-templates select="sect1/sect2"/> - - -.SH FILES -EOF - -echo ".I $LIBDIR" -cat <<'EOF' - -.SH COPYRIGHT - -Copyright 2002, The University Court of the University of Glasgow. -.br -All rights reserved. - - -.SH AUTHOR - -This manual page was generated from the XML documentation of GHC with blood, -sweat, tears and a breaks-if-you-look-at-it-the-wrong-way XSL -stylesheet originally written by Michael Weber <michaelw@debian.org> -for the Debian GNU/Linux system (but may be used by others). - -.\" End -</xsl:template> - - -<xsl:template match="sect1/sect2" mode="overview"> -<xsl:choose> -<xsl:when test="contains(title/.,' (')"> -.SS <xsl:value-of select="substring-before(title/.,' (')"/> -</xsl:when> -<xsl:otherwise> -.SS <xsl:value-of select="title/."/> -</xsl:otherwise> -</xsl:choose> -.nh -<xsl:apply-templates select="informaltable/tgroup/tbody/row" mode="overview"/> -.hy -</xsl:template> - - -<xsl:template match="sect1/sect2"> -<xsl:choose> -<xsl:when test="contains(title/.,' (')"> - -.SH <xsl:value-of select='translate(substring-before(title/.," ("),"abcdefghijklmnopqrstuvwxyz","ABCDEFGHIJKLMNOPQRSTUVWXYZ")'/> - -</xsl:when> -<xsl:otherwise> - -.SH <xsl:value-of select='translate(title/.,"abcdefghijklmnopqrstuvwxyz","ABCDEFGHIJKLMNOPQRSTUVWXYZ")'/> - -</xsl:otherwise> -</xsl:choose><xsl:text> -</xsl:text> -<xsl:apply-templates select="informaltable/tgroup/tbody/row"/> -</xsl:template> - - -<xsl:template match="informaltable/tgroup/tbody/row" mode="overview"> - <xsl:apply-templates select="entry[1]|entry[4]" mode="overview"/> - <xsl:text> </xsl:text> -</xsl:template> - -<xsl:template match="informaltable/tgroup/tbody/row"> -.TP -<xsl:apply-templates select="entry[1]"/><xsl:text> -</xsl:text> -<xsl:variable name="x"> -<xsl:apply-templates select="entry[2]"/> -</xsl:variable> -<xsl:value-of select="normalize-space($x)"/> -.rj -[<xsl:apply-templates select="entry[3]"/>] -<!-- IGNORE NEGATIVE OPTIONS -<xsl:if test="not(entry[4]='-')"> - <xsl:text>.TP -</xsl:text> - <xsl:apply-templates select="entry[4]/option"/> -</xsl:if> - --> -</xsl:template> - - -<xsl:template match="option" mode="escape-dash"> - <xsl:variable name="x"> - <xsl:value-of select="."/> - </xsl:variable> - <xsl:variable name="y"> - <xsl:call-template name="replace-string"> - <xsl:with-param name="text" select="$x"/> - <xsl:with-param name="from" select="'-'"/> - <xsl:with-param name="to" select="'\-'"/> - </xsl:call-template> - </xsl:variable> - <xsl:value-of select="$y"/> -</xsl:template> - -<xsl:template match="option" mode="overview"> - <xsl:apply-templates select="." mode="escape-dash"/> -</xsl:template> - -<xsl:template match="option"> - <xsl:text>\fB</xsl:text> - <xsl:apply-templates select="." mode="escape-dash"/> - <xsl:text>\fP</xsl:text> -</xsl:template> - - -<xsl:template match="entry[1]" mode="overview"> - <xsl:apply-templates mode="overview"/> - <xsl:text> </xsl:text> -</xsl:template> - -<xsl:template match="entry[1]"> - <xsl:apply-templates/><xsl:text> </xsl:text> -</xsl:template> - -<xsl:template match="entry[4]" mode="overview"> - <xsl:if test="not(.='-')"> - <xsl:apply-templates select="option" mode="overview"/> - <xsl:text> </xsl:text> - </xsl:if> -</xsl:template> - -<xsl:template match="entry[4]"> - <xsl:if test="not(.='-')"> - <xsl:value-of select="."/><xsl:text> </xsl:text> - </xsl:if> -</xsl:template> - - -<xsl:template match="replaceable" mode="overview"> - <xsl:apply-templates select="."/> -</xsl:template> - -<xsl:template match="replaceable"> - <xsl:text>\fI</xsl:text> - <xsl:value-of select='.'/> - <xsl:text>\fP</xsl:text> -</xsl:template> - - -<xsl:template match="literal"> - <xsl:text>\f(CR</xsl:text> - <xsl:value-of select="."/> - <xsl:text>\fP</xsl:text> -</xsl:template> - - - -<!-- reusable replace-string function --> - <xsl:template name="replace-string"> - <xsl:param name="text"/> - <xsl:param name="from"/> - <xsl:param name="to"/> - - <xsl:choose> - <xsl:when test="contains($text, $from)"> - - <xsl:variable name="before" select="substring-before($text, $from)"/> - <xsl:variable name="after" select="substring-after($text, $from)"/> - <xsl:variable name="prefix" select="concat($before, $to)"/> - - <xsl:value-of select="$before"/> - <xsl:value-of select="$to"/> - <xsl:call-template name="replace-string"> - <xsl:with-param name="text" select="$after"/> - <xsl:with-param name="from" select="$from"/> - <xsl:with-param name="to" select="$to"/> - </xsl:call-template> - </xsl:when> - <xsl:otherwise> - <xsl:value-of select="$text"/> - </xsl:otherwise> - </xsl:choose> - </xsl:template> -</xsl:stylesheet> -EOF - diff --git a/docs/man/ghc.mk b/docs/man/ghc.mk deleted file mode 100644 index 470bd9ad34..0000000000 --- a/docs/man/ghc.mk +++ /dev/null @@ -1,58 +0,0 @@ - -ifeq "$(BUILD_MAN)" "" -ifeq "$(strip $(XSLTPROC))" "" -BUILD_MAN = NO -else -BUILD_MAN = YES -endif -endif - -# The commands which should be mentioned in the man page -MAN_GHC_COMMANDS = ghc ghci - -# The man page we are generating -MAN_PAGE = ghc - -# The manual section -MAN_SECTION = 1 - -MAN_PATH = docs/man/$(MAN_PAGE).$(MAN_SECTION) - -ifneq "$(BINDIST)" "YES" -$(MAN_PATH): docs/man/flags.xsl docs/man/flags.xml - $(XSLTPROC) $(XSLTPROC_OPTS) $^ > $@ -endif - -# Insert the commands and the library directory into the man page -docs/man/flags.xsl: docs/man/gen_flags.xsl.sh - $(SHELL) $< "$(MAN_GHC_COMMANDS)" "$(libdir)" > $@ - -# Re-use the flags documentation from the user's guide by injecting some -# entities after the XML declaration to make it a stand-alone document. -docs/man/flags.xml: docs/users_guide/flags.xml - $(call removeFiles,$@) - head -n 1 $< >> $@ - echo "<!DOCTYPE sect1 [<!ENTITY ndash \"-\"> \ - <!ENTITY ldquo \"\`\"> \ - <!ENTITY rdquo \"'\">]>" >> $@ -# "sed 1d" == "tail -n +2", but Solaris apparently rejects the latter - sed 1d $< >> $@ - -ifeq "$(BUILD_MAN)" "YES" -ifeq "$(phase)" "final" -$(eval $(call all-target,docs/man,$(MAN_PATH))) -endif - -INSTALL_MANPAGES += $(MAN_PATH) - -install: install_man - -.PHONY: install_man -install_man: $(MAN_PATH) - $(INSTALL_DIR) "$(DESTDIR)$(mandir)" - $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man$(MAN_SECTION)" - $(INSTALL_MAN) $(INSTALL_OPTS) $(MAN_PATH) "$(DESTDIR)$(mandir)/man$(MAN_SECTION)" -endif - -$(eval $(call clean-target,docs/man,,$(MAN_PATH) docs/man/flags.xsl docs/man/flags.xml)) - diff --git a/docs/users_guide/7.12.1-notes.rst b/docs/users_guide/7.12.1-notes.rst new file mode 100644 index 0000000000..188daa9217 --- /dev/null +++ b/docs/users_guide/7.12.1-notes.rst @@ -0,0 +1,332 @@ +.. _release-7-12-1: + +Release notes for version 7.12.1 +================================ + +The significant changes to the various parts of the compiler are listed +in the following sections. There have also been numerous bug fixes and +performance improvements over the 7.10 branch. + +Highlights +---------- + +The highlights, since the 7.10 branch, are: + +- TODO FIXME + +Full details +------------ + +Language +~~~~~~~~ + +- TODO FIXME. + +- The parser now supports Haddock comments on GADT data constructors. + For example, + + :: + + data Expr a where + -- | Just a normal sum + Sum :: Int -> Int -> Expr Int + +- Implicit parameters of the new ghc-prim type ``GHC.Types.CallStack`` + are treated specially, and automatically solved for the current + source location. For example + + :: + + f = print (?stk :: CallStack) + + will print the singleton stack containing the occurrence of ``?stk``. + If there is another ``CallStack`` implicit in-scope, the new location + will be appended to the existing stack, e.g. + + :: + + f :: (?stk :: CallStack) => IO () + f = print (?stk :: CallStack) + + will print the occurrence of ``?stk`` and the call-site of ``f``. The + name of the implicit parameter does not matter. + + See the release notes for ghc-prim for a description of the + ``CallStack`` type. + +- To conform to the common case, the default role assigned to + parameters of datatypes declared in ``hs-boot`` files is + ``representational``. However, if the constructor(s) for the datatype + are given, it makes sense to do normal role inference. This is now + implemented, effectively making the default role for non-abstract + datatypes in ``hs-boot`` files to be ``phantom``, like it is in + regular Haskell code. + +- Wildcards can be used in the type arguments of type/data family + instance declarations to indicate that the name of a type variable + doesn't matter. They will be replaced with new unique type variables. + See :ref:`data-instance-declarations` for more details. + +- GHC now allows to declare type families as injective. Injectivity + information can then be used by the typechecker. See + :ref:`injective-ty-fams` for details. + +- Due to a :ghc-ticket:`security issue <10826>`, Safe Haskell now forbids + annotations in programs marked as ``-XSafe``. + + +Compiler +~~~~~~~~ + +- Added the option ``-dth-dec-file``. This dumps out a .th.hs file of + all Template Haskell declarations in a corresponding .hs file. The + idea is that application developers can check this into their + repository so that they can grep for identifiers used elsewhere that + were defined in Template Haskell. This is similar to using + ``-ddump-to-file`` with ``-ddump-splices`` but it always generates a + file instead of being coupled to ``-ddump-to-file`` and only outputs + code that does not exist in the .hs file and a comment for the splice + location in the original file. + +- Added the option ``-fprint-expanded-types``. When enabled, GHC also + prints type-synonym-expanded types in type errors. + +- Added the option ``-fcpr-anal``. When enabled, the demand analyser + performs CPR analysis. It is implied by ``-O``. Consequently, + ``-fcpr-off`` is now removed, run with ``-fno-cpr-anal`` to get the + old ``-fcpr-off`` behaviour. + +GHCi +~~~~ + +- ``Main`` with an explicit module header but without ``main`` is now + an error (#7765). + + The ``:back`` and ``:forward`` commands now take an optional count + allowing the user to move forward or backward in history several + steps at a time. + + Added commands ``:load!`` and ``:reload!``, effectively setting + "-fdefer-type-errors" before loading a module and unsetting it after + loading if it has not been set before (#8353). + +Template Haskell +~~~~~~~~~~~~~~~~ + +- The ``TemplateHaskell`` now no longer automatically errors when used + with a stage 1 compiler (i.e. GHC without interpreter support); in + particular, plain Haskell quotes (not quasi-quotes) can now be + compiled without erroring. Splices and quasi-quotes continue to only + be supported by a stage 2 compiler. + +- Partial type signatures can now be used in splices, see + :ref:`pts-where`. + +- ``Template Haskell`` now supports the use of ``UInfixT`` in types to + resolve infix operator fixities, in the same vein as ``UInfixP`` and + ``UInfixE`` in patterns and expressions. ``ParensT`` and ``InfixT`` + have also been introduced, serving the same functions as their + pattern and expression counterparts. + +- Primitive chars (e.g., ``[| 'a'# |]``) and primitive strings (e.g., + ``[| "abc"# |]``) can now be quoted with Template Haskell. The + ``Lit`` data type also has a new constructor, ``CharPrimL``, for + primitive char literals. + +- ``addTopDecls`` now accepts annotation pragmas. + +- Internally, the implementation of quasi-quotes has been unified with + that of normal Template Haskell splices. Under the previous + implementation, top-level declaration quasi-quotes did not cause a + break in the declaration groups, unlike splices of the form + ``$(...)``. This behavior has been preserved under the new + implementation, and is now recognized and documented in + :ref:`th-syntax`. + +- The ``Lift`` class is now derivable via the ``-XDeriveLift`` extension. See + :ref:`deriving-lift` for more information. + + +Runtime system +~~~~~~~~~~~~~~ + +- TODO FIXME. + +Build system +~~~~~~~~~~~~ + +- TODO FIXME. + +Package system +~~~~~~~~~~~~~~ + +- TODO FIXME. + +Libraries +--------- + +array +~~~~~ + +- Version number XXXXX (was 0.5.0.0) + +base +~~~~ + +- Version number XXXXX (was 4.7.0.0) + +- A new module ``GHC.SrcLoc`` was added, exporting a new type + ``SrcLoc``. A ``SrcLoc`` contains package, module, and file names, as + well as start and end positions. + +- A new type ``CallStack`` was added for use with the new implicit + callstack parameters. A ``CallStack`` is a ``[(String, SrcLoc)]``, + sorted by most-recent call. + +- A new function, ``interruptible``, was added to ``GHC.IO`` allowing + an ``IO`` action to be run such that it can be interrupted by an + asynchronous exception, even if exceptions are masked (except if + masked with ``interruptibleMask``). + + This was introduced to fix the behavior of ``allowInterrupt``, which + would previously incorrectly allow exceptions in uninterruptible + regions (see :ghc-ticket:`9516`). + +- Per-thread allocation counters (``setAllocationCounter`` and + ``getAllocationCounter``) and limits (``enableAllocationLimit``, + ``disableAllocationLimit`` are now available from ``System.Mem``. Previously + this functionality was only available from ``GHC.Conc``. + + +bin-package-db +~~~~~~~~~~~~~~ + +- This is an internal package, and should not be used. + +binary +~~~~~~ + +- Version number XXXXX (was 0.7.1.0) + +bytestring +~~~~~~~~~~ + +- Version number XXXXX (was 0.10.4.0) + +Cabal +~~~~~ + +- Version number XXXXX (was 1.18.1.3) + +containers +~~~~~~~~~~ + +- Version number XXXXX (was 0.5.4.0) + +deepseq +~~~~~~~ + +- Version number XXXXX (was 1.3.0.2) + +directory +~~~~~~~~~ + +- Version number XXXXX (was 1.2.0.2) + +filepath +~~~~~~~~ + +- Version number XXXXX (was 1.3.0.2) + +ghc +~~~ + +- TODO FIXME. + +- The ``HsBang`` type has been removed in favour of ``HsSrcBang`` and + ``HsImplBang``. Data constructors now always carry around their + strictness annotations as the user wrote them, whether from an + imported module or not. + +ghc-prim +~~~~~~~~ + +- Version number XXXXX (was 0.3.1.0) + +haskell98 +~~~~~~~~~ + +- Version number XXXXX (was 2.0.0.3) + +haskell2010 +~~~~~~~~~~~ + +- Version number XXXXX (was 1.1.1.1) + +hoopl +~~~~~ + +- Version number XXXXX (was 3.10.0.0) + +hpc +~~~ + +- Version number XXXXX (was 0.6.0.1) + +integer-gmp +~~~~~~~~~~~ + +- Version number XXXXX (was 0.5.1.0) + +old-locale +~~~~~~~~~~ + +- Version number XXXXX (was 1.0.0.6) + +old-time +~~~~~~~~ + +- Version number XXXXX (was 1.1.0.2) + +process +~~~~~~~ + +- Version number XXXXX (was 1.2.0.0) + +template-haskell +~~~~~~~~~~~~~~~~ + +- Version number XXXXX (was 2.9.0.0) + +- The ``Lift`` type class for lifting values into Template Haskell + splices now has a default signature ``lift :: Data a => a -> Q Exp``, + which means that you do not have to provide an explicit + implementation of ``lift`` for types which have a ``Data`` instance. + To manually use this default implementation, you can use the + ``liftData`` function which is now exported from + ``Language.Haskell.TH.Syntax``. + +- ``Info``'s constructors no longer have ``Fixity`` fields. A + ``qReifyFixity`` function was added to the ``Quasi`` type class (as + well as the ``reifyFixity`` function, specialized for ``Q``) to allow + lookup of fixity information for any given ``Name``. + +time +~~~~ + +- Version number XXXXX (was 1.4.1) + +unix +~~~~ + +- Version number XXXXX (was 2.7.0.0) + +Win32 +~~~~~ + +- Version number XXXXX (was 2.3.0.1) + +Known bugs +---------- + +- TODO FIXME diff --git a/docs/users_guide/7.12.1-notes.xml b/docs/users_guide/7.12.1-notes.xml deleted file mode 100644 index c71887fa28..0000000000 --- a/docs/users_guide/7.12.1-notes.xml +++ /dev/null @@ -1,628 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<sect1 id="release-7-12-1"> - <title>Release notes for version 7.12.1</title> - - <para> - The significant changes to the various parts of the compiler are listed - in the following sections. There have also been numerous bug fixes and - performance improvements over the 7.10 branch. - </para> - - <sect2> - <title>Highlights</title> - - <para> - The highlights, since the 7.10 branch, are: - </para> - - <itemizedlist> - <listitem> - <para> - TODO FIXME - </para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>Full details</title> - <sect3> - <title>Language</title> - <itemizedlist> - <listitem> - <para> - TODO FIXME. - </para> - </listitem> - - <listitem> - <para> - The parser now supports Haddock comments on GADT data constructors. For example, - <programlisting> - data Expr a where - -- | Just a normal sum - Sum :: Int -> Int -> Expr Int - </programlisting> - </para> - </listitem> - <listitem> - <para> - Implicit parameters of the new ghc-prim type - <literal>GHC.Types.CallStack</literal> are treated - specially, and automatically solved for the current source - location. For example - <programlisting> - f = print (?stk :: CallStack) - </programlisting> - will print the singleton stack containing the occurrence of - <literal>?stk</literal>. If there is another - <literal>CallStack</literal> implicit in-scope, the new location - will be appended to the existing stack, e.g. - <programlisting> - f :: (?stk :: CallStack) => IO () - f = print (?stk :: CallStack) - </programlisting> - will print the occurrence of <literal>?stk</literal> and the - call-site of <literal>f</literal>. The name of the implicit - parameter does not matter. - </para> - <para> - See the release notes for ghc-prim for a description of the - <literal>CallStack</literal> type. - </para> - </listitem> - - <listitem> - <para> - To conform to the common case, the default role assigned to parameters - of datatypes declared in <literal>hs-boot</literal> files is - <literal>representational</literal>. However, if the constructor(s) - for the datatype are given, it makes sense to do normal role inference. - This is now implemented, effectively making the default role for - non-abstract datatypes in <literal>hs-boot</literal> files to be - <literal>phantom</literal>, like it is in regular Haskell code. - </para> - </listitem> - <listitem> - <para> - Wildcards can be used in the type arguments of type/data - family instance declarations to indicate that the name of a - type variable doesn't matter. They will be replaced with new - unique type variables. See <xref - linkend="data-instance-declarations"/> for more details. - </para> - </listitem> - - <listitem> - <para> - GHC now allows to declare type families as injective. - Injectivity information can then be used by the typechecker. - See <xref linkend="injective-ty-fams"/> for details. - </para> - </listitem> - - <listitem> - <para> - Due to a <ulink href="https://ghc.haskell.org/trac/ghc/ticket/10826"> - security issue - </ulink>, Safe Haskell now forbids annotations in programs marked as - <literal>-XSafe</literal> - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>Compiler</title> - <itemizedlist> - <listitem> - <para> - Added the option <option>-dth-dec-file</option>. - - This dumps out a .th.hs file of all Template Haskell declarations in a corresponding .hs file. The idea is that application developers can check this into their repository so that they can grep for identifiers used elsewhere that were defined in Template Haskell. - This is similar to using <option>-ddump-to-file</option> with <option>-ddump-splices</option> but it always generates a file instead of being coupled to <option>-ddump-to-file</option> and only outputs code that does not exist in the .hs file and a comment for the splice location in the original file. - </para> - </listitem> - <listitem> - <para> - Added the option <option>-fprint-expanded-types</option>. - - When enabled, GHC also prints type-synonym-expanded types in - type errors. - </para> - </listitem> - <listitem> - <para> - Added the option <option>-fcpr-anal</option>. - - When enabled, the demand analyser performs CPR analysis. - It is implied by <option>-O</option>. Consequently, - <option>-fcpr-off</option> is now removed, run with - <option>-fno-cpr-anal</option> to get the old - <option>-fcpr-off</option> behaviour. - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>GHCi</title> - <itemizedlist> - <listitem> - <para> - <literal>Main</literal> with an explicit module header but - without <literal>main</literal> is now an error (#7765). - </para> - <para> - The <literal>:back</literal> and <literal>:forward</literal> - commands now take an optional count allowing the user to move forward or - backward in history several steps at a time. - </para> - <para> - Added commands <literal>:load!</literal> and <literal>:reload!</literal>, - effectively setting "-fdefer-type-errors" before loading a module and - unsetting it after loading if it has not been set before (#8353). - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>Template Haskell</title> - <itemizedlist> - <listitem> - <para> - The <literal>TemplateHaskell</literal> now no longer automatically - errors when used with a stage 1 compiler (i.e. GHC without - interpreter support); in particular, plain - Haskell quotes (not quasi-quotes) can now be compiled without erroring. - Splices and quasi-quotes continue to only be supported by a - stage 2 compiler. - </para> - </listitem> - <listitem> - <para> - Partial type signatures can now be used in splices, see <xref linkend="pts-where"/>. - </para> - </listitem> - <listitem> - <para> - <literal>Template Haskell</literal> now supports the use of - <literal>UInfixT</literal> in types to resolve infix - operator fixities, in the same vein as - <literal>UInfixP</literal> and <literal>UInfixE</literal> - in patterns and expressions. <literal>ParensT</literal> - and <literal>InfixT</literal> have also been introduced, - serving the same functions as their pattern and expression - counterparts. - </para> - </listitem> - <listitem> - <para> - Primitive chars (e.g., <literal>[| 'a'# |]</literal>) and - primitive strings (e.g., <literal>[| "abc"# |]</literal>) - can now be quoted with Template Haskell. The - <literal>Lit</literal> data type also has a new - constructor, <literal>CharPrimL</literal>, for primitive - char literals. - </para> - </listitem> - <listitem> - <para> - <literal>addTopDecls</literal> now accepts annotation - pragmas. - </para> - </listitem> - <listitem> - <para> - Internally, the implementation of quasi-quotes has been - unified with that of normal Template Haskell splices. Under - the previous implementation, top-level declaration - quasi-quotes did not cause a break in the declaration - groups, unlike splices of the form - <literal>$(...)</literal>. This behavior has been - preserved under the new implementation, and is now - recognized and documented in <xref linkend="th-syntax"/>. - </para> - </listitem> - <listitem> - <para> - The <literal>Lift</literal> class is now derivable via - the <option>-XDeriveLift</option> extension. See - <xref linkend="deriving-lift"/> for more information. - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>Runtime system</title> - <itemizedlist> - <listitem> - <para> - TODO FIXME. - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>Build system</title> - <itemizedlist> - <listitem> - <para> - TODO FIXME. - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>Package system</title> - <itemizedlist> - <listitem> - <para> - TODO FIXME. - </para> - </listitem> - </itemizedlist> - </sect3> - </sect2> - - <sect2> - <title>Libraries</title> - - <sect3> - <title>array</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 0.5.0.0) - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>base</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 4.7.0.0) - </para> - </listitem> - <listitem> - <para> - A new module <literal>GHC.SrcLoc</literal> was added, - exporting a new type <literal>SrcLoc</literal>. A - <literal>SrcLoc</literal> contains package, module, - and file names, as well as start and end positions. - </para> - </listitem> - <listitem> - <para> - A new type <literal>CallStack</literal> was added for use - with the new implicit callstack parameters. A - <literal>CallStack</literal> is a - <literal>[(String, SrcLoc)]</literal>, sorted by most-recent - call. - </para> - </listitem> - <listitem> - <para> - A new function, <literal>interruptible</literal>, was added - to <literal>GHC.IO</literal> allowing an - <literal>IO</literal> action to be run such that it can be - interrupted by an asynchronous exception, even if exceptions - are masked (except if masked with - <literal>interruptibleMask</literal>). - </para> - <para> - This was introduced to fix the behavior of - <literal>allowInterrupt</literal>, which would previously - incorrectly allow exceptions in uninterruptible regions - (see Trac #9516). - </para> - </listitem> - <listitem> - <para> - Per-thread allocation counters - (<literal>setAllocationCounter</literal> and - <literal>getAllocationCounter</literal>) and limits - (<literal>enableAllocationLimit</literal>, - <literal>disableAllocationLimit</literal> are now - available from <literal>System.Mem</literal>. - Previously this functionality was only available - from <literal>GHC.Conc</literal>. - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>bin-package-db</title> - <itemizedlist> - <listitem> - <para> - This is an internal package, and should not be used. - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>binary</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 0.7.1.0) - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>bytestring</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 0.10.4.0) - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>Cabal</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 1.18.1.3) - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>containers</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 0.5.4.0) - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>deepseq</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 1.3.0.2) - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>directory</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 1.2.0.2) - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>filepath</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 1.3.0.2) - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>ghc</title> - <itemizedlist> - <listitem> - <para> - TODO FIXME. - </para> - </listitem> - <listitem> - <para> - The <literal>HsBang</literal> type has been removed in - favour of <literal>HsSrcBang</literal> and - <literal>HsImplBang</literal>. Data constructors now - always carry around their strictness annotations as - the user wrote them, whether from an imported module - or not. - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>ghc-prim</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 0.3.1.0) - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>haskell98</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 2.0.0.3) - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>haskell2010</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 1.1.1.1) - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>hoopl</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 3.10.0.0) - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>hpc</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 0.6.0.1) - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>integer-gmp</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 0.5.1.0) - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>old-locale</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 1.0.0.6) - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>old-time</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 1.1.0.2) - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>process</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 1.2.0.0) - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>template-haskell</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 2.9.0.0) - </para> - </listitem> - <listitem> - <para> - The <literal>Lift</literal> type class for lifting values - into Template Haskell splices now has a default signature - <literal>lift :: Data a => a -> Q Exp</literal>, which means - that you do not have to provide an explicit implementation - of <literal>lift</literal> for types which have a <literal>Data</literal> - instance. To manually use this default implementation, you - can use the <literal>liftData</literal> function which is - now exported from <literal>Language.Haskell.TH.Syntax</literal>. - </para> - </listitem> - <listitem> - <para> - <literal>Info</literal>'s constructors no longer have - <literal>Fixity</literal> fields. A <literal>qReifyFixity - </literal> function was added to the <literal>Quasi - </literal> type class (as well as the <literal>reifyFixity - </literal> function, specialized for <literal>Q</literal>) - to allow lookup of fixity information for any given - <literal>Name</literal>. - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>time</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 1.4.1) - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>unix</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 2.7.0.0) - </para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>Win32</title> - <itemizedlist> - <listitem> - <para> - Version number XXXXX (was 2.3.0.1) - </para> - </listitem> - </itemizedlist> - </sect3> - </sect2> - - <sect2> - <title>Known bugs</title> - <itemizedlist> - <listitem> - <para> - TODO FIXME - </para> - </listitem> - </itemizedlist> - </sect2> -</sect1> diff --git a/docs/users_guide/bugs.rst b/docs/users_guide/bugs.rst new file mode 100644 index 0000000000..944925ae34 --- /dev/null +++ b/docs/users_guide/bugs.rst @@ -0,0 +1,492 @@ +.. _bugs-and-infelicities: + +Known bugs and infelicities +=========================== + +.. _vs-Haskell-defn: + +Haskell standards vs. Glasgow Haskell: language non-compliance +-------------------------------------------------------------- + +.. index:: + single: GHC vs the Haskell standards + single: Haskell standards vs GHC + +This section lists Glasgow Haskell infelicities in its implementation of +Haskell 98 and Haskell 2010. See also the “when things go wrong” section +(:ref:`wrong`) for information about crashes, space leaks, and other +undesirable phenomena. + +The limitations here are listed in Haskell Report order (roughly). + +.. _haskell-standards-divergence: + +Divergence from Haskell 98 and Haskell 2010 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, GHC mainly aims to behave (mostly) like a Haskell 2010 +compiler, although you can tell it to try to behave like a particular +version of the language with the ``-XHaskell98`` and ``-XHaskell2010`` +flags. The known deviations from the standards are described below. +Unless otherwise stated, the deviation applies in Haskell 98, +Haskell 2010 and the default modes. + +.. _infelicities-lexical: + +Lexical syntax +^^^^^^^^^^^^^^ + +- Certain lexical rules regarding qualified identifiers are slightly + different in GHC compared to the Haskell report. When you have + ⟨module⟩\ ``.``\ ⟨reservedop⟩, such as ``M.\``, GHC will interpret it + as a single qualified operator rather than the two lexemes ``M`` and + ``.\``. + +.. _infelicities-syntax: + +Context-free syntax +^^^^^^^^^^^^^^^^^^^ + +- In Haskell 98 mode and by default (but not in Haskell 2010 mode), GHC + is a little less strict about the layout rule when used in ``do`` + expressions. Specifically, the restriction that "a nested context + must be indented further to the right than the enclosing context" is + relaxed to allow the nested context to be at the same level as the + enclosing context, if the enclosing context is a ``do`` expression. + + For example, the following code is accepted by GHC: + + :: + + main = do args <- getArgs + if null args then return [] else do + ps <- mapM process args + mapM print ps + + This behaviour is controlled by the ``NondecreasingIndentation`` + extension. + +- GHC doesn't do the fixity resolution in expressions during parsing as + required by Haskell 98 (but not by Haskell 2010). For example, + according to the Haskell 98 report, the following expression is + legal: + + :: + + let x = 42 in x == 42 == True + + and parses as: + + :: + + (let x = 42 in x == 42) == True + + because according to the report, the ``let`` expression “extends as + far to the right as possible”. Since it can't extend past the second + equals sign without causing a parse error (``==`` is non-fix), the + ``let``\-expression must terminate there. GHC simply gobbles up the + whole expression, parsing like this: + + :: + + (let x = 42 in x == 42 == True) +- The Haskell Report allows you to put a unary ``-`` preceding certain + expressions headed by keywords, allowing constructs like ``- case x of ...`` + or ``- do { ... }``. GHC does not allow this. Instead, unary ``-`` is allowed + before only expressions that could potentially be applied as a function. + + +.. _infelicities-exprs-pats: + +Expressions and patterns +^^^^^^^^^^^^^^^^^^^^^^^^ + +In its default mode, GHC makes some programs slightly more defined than +they should be. For example, consider + +:: + + f :: [a] -> b -> b + f [] = error "urk" + f (x:xs) = \v -> v + + main = print (f [] `seq` True) + +This should call ``error`` but actually prints ``True``. Reason: GHC +eta-expands ``f`` to + +:: + + f :: [a] -> b -> b + f [] v = error "urk" + f (x:xs) v = v + +This improves efficiency slightly but significantly for most programs, +and is bad for only a few. To suppress this bogus "optimisation" use +``-fpedantic-bottoms``. + +.. _infelicities-decls: + +Declarations and bindings +^^^^^^^^^^^^^^^^^^^^^^^^^ + +In its default mode, GHC does not accept datatype contexts, as it has +been decided to remove them from the next version of the language +standard. This behaviour can be controlled with the ``DatatypeContexts`` +extension. See :ref:`datatype-contexts`. + +.. _infelicities-Modules: + +Module system and interface files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +GHC requires the use of ``hs-boot`` files to cut the recursive loops +among mutually recursive modules as described in +:ref:`mutual-recursion`. This more of an infelicity than a bug: the +Haskell Report says (`Section +5.7 <http://haskell.org/onlinereport/modules.html#sect5.7>`__) + + "Depending on the Haskell implementation used, separate compilation of + mutually recursive modules may require that imported modules contain + additional information so that they may be referenced before they are + compiled. Explicit type signatures for all exported values may be + necessary to deal with mutual recursion. The precise details of separate + compilation are not defined by this Report." + +.. _infelicities-numbers: + +Numbers, basic types, and built-in classes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``Num`` superclasses + The ``Num`` class does not have ``Show`` or ``Eq`` superclasses. + + + You can make code that works with both Haskell98/Haskell2010 and GHC + by: + + - Whenever you make a ``Num`` instance of a type, also make + ``Show`` and ``Eq`` instances, and + + - Whenever you give a function, instance or class a ``Num t`` + constraint, also give it ``Show t`` and ``Eq t`` constraints. + +``Bits`` superclasses + The ``Bits`` class does not have a ``Num`` superclasses. It + therefore does not have default methods for the ``bit``, ``testBit`` + and ``popCount`` methods. + + You can make code that works with both Haskell 2010 and GHC by: + + - Whenever you make a ``Bits`` instance of a type, also make a + ``Num`` instance, and + + - Whenever you give a function, instance or class a ``Bits t`` + constraint, also give it a ``Num t`` constraint, and + + - Always define the ``bit``, ``testBit`` and ``popCount`` methods + in ``Bits`` instances. + +Extra instances + The following extra instances are defined: + + :: + + instance Functor ((->) r) + instance Monad ((->) r) + instance Functor ((,) a) + instance Functor (Either a) + instance Monad (Either e) + +Multiply-defined array elements not checked + This code fragment should elicit a fatal error, but it does not: + + :: + + main = print (array (1,1) [(1,2), (1,3)]) + + GHC's implementation of ``array`` takes the value of an array slot + from the last (index,value) pair in the list, and does no checking + for duplicates. The reason for this is efficiency, pure and simple. + +.. _infelicities-Prelude: + +In ``Prelude`` support +^^^^^^^^^^^^^^^^^^^^^^ + +Arbitrary-sized tuples + Tuples are currently limited to size 100. However, standard + instances for tuples (``Eq``, ``Ord``, ``Bounded``, ``Ix``, ``Read``, + and ``Show``) are available *only* up to 16-tuples. + + This limitation is easily subvertible, so please ask if you get + stuck on it. + +``splitAt`` semantics + ``Data.List.splitAt`` is stricter than specified in the Report. + Specifically, the Report specifies that + + .. + + splitAt n xs = (take n xs, drop n xs) + + which implies that + + .. + + splitAt undefined undefined = (undefined, undefined) + + but GHC's implementation is strict in its first argument, so + + .. + + splitAt undefined [] = undefined + +``Read``\ ing integers + GHC's implementation of the ``Read`` class for integral types + accepts hexadecimal and octal literals (the code in the Haskell 98 + report doesn't). So, for example, + + :: + + read "0xf00" :: Int + + works in GHC. + + A possible reason for this is that ``readLitChar`` accepts hex and + octal escapes, so it seems inconsistent not to do so for integers + too. + +``isAlpha`` + The Haskell 98 definition of ``isAlpha`` is: + + :: + + isAlpha c = isUpper c || isLower c + + GHC's implementation diverges from the Haskell 98 definition in the + sense that Unicode alphabetic characters which are neither upper nor + lower case will still be identified as alphabetic by ``isAlpha``. + +``hGetContents`` + Lazy I/O throws an exception if an error is encountered, in contrast + to the Haskell 98 spec which requires that errors are discarded (see + Section 21.2.2 of the Haskell 98 report). The exception thrown is + the usual IO exception that would be thrown if the failing IO + operation was performed in the IO monad, and can be caught by + ``System.IO.Error.catch`` or ``Control.Exception.catch``. + +.. _infelicities-ffi: + +The Foreign Function Interface +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``hs_init()``, ``hs_exit()`` + The FFI spec requires the implementation to support re-initialising + itself after being shut down with ``hs_exit()``, but GHC does not + currently support that. + + .. index:: + single: hs_init + single: hs_exit + +.. _haskell-98-2010-undefined: + +GHC's interpretation of undefined behaviour in Haskell 98 and Haskell 2010 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section documents GHC's take on various issues that are left +undefined or implementation specific in Haskell 98. + +``Char`` + .. index:: + single: Char; size of + + Following the ISO-10646 standard, ``maxBound :: Char`` in GHC is + ``0x10FFFF``. + +``Int`` + .. index:: + single: Int; size of + single: fromInteger function + single: fromIntegral function + + In GHC the ``Int`` type follows the size of an address on the host + architecture; in other words it holds 32 bits on a 32-bit machine, + and 64-bits on a 64-bit machine. + + Arithmetic on ``Int`` is unchecked for overflowoverflow\ ``Int``, so + all operations on ``Int`` happen modulo 2\ :sup:`⟨n⟩` where ⟨n⟩ is + the size in bits of the ``Int`` type. + + The ``fromInteger`` (and hence also ``fromIntegral``) is a special case when + converting to ``Int``. The value of ``fromIntegral x :: Int`` is + given by taking the lower ⟨n⟩ bits of ``(abs x)``, multiplied by the + sign of ``x`` (in 2's complement ⟨n⟩-bit arithmetic). This behaviour + was chosen so that for example writing ``0xffffffff :: Int`` + preserves the bit-pattern in the resulting ``Int``. + + Negative literals, such as ``-3``, are specified by (a careful + reading of) the Haskell Report as meaning + ``Prelude.negate (Prelude.fromInteger 3)``. So ``-2147483648`` means + ``negate (fromInteger 2147483648)``. Since ``fromInteger`` takes the + lower 32 bits of the representation, + ``fromInteger (2147483648::Integer)``, computed at type ``Int`` is + ``-2147483648::Int``. The ``negate`` operation then overflows, but + it is unchecked, so ``negate (-2147483648::Int)`` is just + ``-2147483648``. In short, one can write ``minBound::Int`` as a + literal with the expected meaning (but that is not in general + guaranteed). + + The ``fromIntegral`` function also preserves bit-patterns when + converting between the sized integral types (``Int8``, ``Int16``, + ``Int32``, ``Int64`` and the unsigned ``Word`` variants), see the + modules ``Data.Int`` and ``Data.Word`` in the library documentation. + +Unchecked floating-point arithmetic + Operations on ``Float`` and ``Double`` numbers are *unchecked* for + overflow, underflow, and other sad occurrences. (note, however, that + some architectures trap floating-point overflow and + loss-of-precision and report a floating-point exception, probably + terminating the program) + + .. index:: + single: floating-point exceptions. + +.. _bugs: + +Known bugs or infelicities +-------------------------- + +The bug tracker lists bugs that have been reported in GHC but not yet +fixed: see the `GHC Trac <http://ghc.haskell.org/trac/ghc/>`__. In +addition to those, GHC also has the following known bugs or +infelicities. These bugs are more permanent; it is unlikely that any of +them will be fixed in the short term. + +.. _bugs-ghc: + +Bugs in GHC +~~~~~~~~~~~ + +- GHC's runtime system implements cooperative multitasking, with + context switching potentially occurring only when a program + allocates. This means that programs that do not allocate may never + context switch. See :ghc-ticket:`367` for further discussion. + + If you are hit by this, you may want to compile the affected module + with ``-fno-omit-yields``. This flag ensures that yield points are + inserted at every function entrypoint (at the expense of a bit of + performance). + +- GHC can warn about non-exhaustive or overlapping patterns (see + :ref:`options-sanity`), and usually does so correctly. But not + always. It gets confused by string patterns, and by guards, and can + then emit bogus warnings. The entire overlap-check code needs an + overhaul really. + +- GHC does not allow you to have a data type with a context that + mentions type variables that are not data type parameters. For + example: + + :: + + data C a b => T a = MkT a + + so that ``MkT``\'s type is + + :: + + MkT :: forall a b. C a b => a -> T a + + In principle, with a suitable class declaration with a functional + dependency, it's possible that this type is not ambiguous; but GHC + nevertheless rejects it. The type variables mentioned in the context + of the data type declaration must be among the type parameters of the + data type. + +- GHC's inliner can be persuaded into non-termination using the + standard way to encode recursion via a data type: + + :: + + data U = MkU (U -> Bool) + + russel :: U -> Bool + russel u@(MkU p) = not $ p u + + x :: Bool + x = russel (MkU russel) + + The non-termination is reported like this: + + :: + + ghc: panic! (the 'impossible' happened) + (GHC version 7.10.1 for x86_64-unknown-linux): + Simplifier ticks exhausted + When trying UnfoldingDone x_alB + To increase the limit, use -fsimpl-tick-factor=N (default 100) + + with the panic being reported no matter how high a + ``-fsimpl-tick-factor`` you supply. + + We have never found another class of programs, other than this + contrived one, that makes GHC diverge, and fixing the problem would + impose an extra overhead on every compilation. So the bug remains + un-fixed. There is more background in `Secrets of the GHC + inliner <http://research.microsoft.com/~simonpj/Papers/inlining/>`__. + +- On 32-bit x86 platforms when using the native code generator, the + ``-fexcess-precision``\ ``-fexcess-precision`` option is always on. + This means that floating-point calculations are non-deterministic, + because depending on how the program is compiled (optimisation + settings, for example), certain calculations might be done at 80-bit + precision instead of the intended 32-bit or 64-bit precision. + Floating-point results may differ when optimisation is turned on. In + the worst case, referential transparency is violated, because for + example ``let x = E1 in E2`` can evaluate to a different value than + ``E2[E1/x]``. + + .. index:: + single: -msse2 option + + One workaround is to use the ``-msse2`` option (see + :ref:`options-platform`, which generates code to use the SSE2 + instruction set instead of the x87 instruction set. SSE2 code uses + the correct precision for all floating-point operations, and so gives + deterministic results. However, note that this only works with + processors that support SSE2 (Intel Pentium 4 or AMD Athlon 64 and + later), which is why the option is not enabled by default. The + libraries that come with GHC are probably built without this option, + unless you built GHC yourself. + +.. _bugs-ghci: + +Bugs in GHCi (the interactive GHC) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- GHCi does not respect the ``default`` declaration in the module whose + scope you are in. Instead, for expressions typed at the command line, + you always get the default default-type behaviour; that is, + ``default(Int,Double)``. + + It would be better for GHCi to record what the default settings in + each module are, and use those of the 'current' module (whatever that + is). + +- On Windows, there's a GNU ld/BFD bug whereby it emits bogus PE object + files that have more than 0xffff relocations. When GHCi tries to load + a package affected by this bug, you get an error message of the form + + :: + + Loading package javavm ... linking ... WARNING: Overflown relocation field (# relocs found: 30765) + + The last time we looked, this bug still wasn't fixed in the BFD + codebase, and there wasn't any noticeable interest in fixing it when + we reported the bug back in 2001 or so. + + The workaround is to split up the .o files that make up your package + into two or more .o's, along the lines of how the ``base`` package does + it. diff --git a/docs/users_guide/bugs.xml b/docs/users_guide/bugs.xml deleted file mode 100644 index bff2bcf056..0000000000 --- a/docs/users_guide/bugs.xml +++ /dev/null @@ -1,638 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<chapter id="bugs-and-infelicities"> - <title>Known bugs and infelicities</title> - - <sect1 id="vs-Haskell-defn"> - <title>Haskell standards vs. Glasgow Haskell: language non-compliance -</title> - - <indexterm><primary>GHC vs the Haskell standards</primary></indexterm> - <indexterm><primary>Haskell standards vs GHC</primary></indexterm> - - <para> - This section lists Glasgow Haskell infelicities in its - implementation of Haskell 98 and Haskell 2010. - See also the “when things go wrong” section - (<xref linkend="wrong"/>) for information about crashes, - space leaks, and other undesirable phenomena. - </para> - - <para> - The limitations here are listed in Haskell Report order - (roughly). - </para> - - <sect2 id="haskell-standards-divergence"> - <title>Divergence from Haskell 98 and Haskell 2010</title> - - <para> - By default, GHC mainly aims to behave (mostly) like a Haskell 2010 - compiler, although you can tell it to try to behave like a - particular version of the language with the - <literal>-XHaskell98</literal> and - <literal>-XHaskell2010</literal> flags. The known deviations - from the standards are described below. Unless otherwise stated, - the deviation applies in Haskell 98, Haskell 2010 and - the default modes. - </para> - - <sect3 id="infelicities-lexical"> - <title>Lexical syntax</title> - - <itemizedlist> - <listitem> - <para>Certain lexical rules regarding qualified identifiers - are slightly different in GHC compared to the Haskell - report. When you have - <replaceable>module</replaceable><literal>.</literal><replaceable>reservedop</replaceable>, - such as <literal>M.\</literal>, GHC will interpret it as a - single qualified operator rather than the two lexemes - <literal>M</literal> and <literal>.\</literal>.</para> - </listitem> - </itemizedlist> - </sect3> - - <sect3 id="infelicities-syntax"> - <title>Context-free syntax</title> - - <itemizedlist> - <listitem> - <para>In Haskell 98 mode and by default (but not in - Haskell 2010 mode), GHC is a little less strict about the - layout rule when used - in <literal>do</literal> expressions. Specifically, the - restriction that "a nested context must be indented further to - the right than the enclosing context" is relaxed to allow the - nested context to be at the same level as the enclosing context, - if the enclosing context is a <literal>do</literal> - expression.</para> - - <para>For example, the following code is accepted by GHC: - -<programlisting> -main = do args <- getArgs - if null args then return [] else do - ps <- mapM process args - mapM print ps</programlisting> - - This behaviour is controlled by the - <literal>NondecreasingIndentation</literal> extension. - </para> - </listitem> - - <listitem> - <para>GHC doesn't do the fixity resolution in expressions during - parsing as required by Haskell 98 (but not by Haskell 2010). - For example, according to the Haskell 98 report, the - following expression is legal: -<programlisting> - let x = 42 in x == 42 == True</programlisting> - and parses as: -<programlisting> - (let x = 42 in x == 42) == True</programlisting> - - because according to the report, the <literal>let</literal> - expression <quote>extends as far to the right as - possible</quote>. Since it can't extend past the second - equals sign without causing a parse error - (<literal>==</literal> is non-fix), the - <literal>let</literal>-expression must terminate there. GHC - simply gobbles up the whole expression, parsing like this: -<programlisting> - (let x = 42 in x == 42 == True)</programlisting></para> - </listitem> - - <listitem> - <para>The Haskell Report allows you to put a unary - <literal>-</literal> preceding certain expressions headed by - keywords, allowing constructs like <literal>- case x of - ...</literal> or <literal>- do { ... }</literal>. GHC does - not allow this. Instead, unary <literal>-</literal> is - allowed before only expressions that could potentially - be applied as a function. - </para> - </listitem> - - </itemizedlist> - </sect3> - - <sect3 id="infelicities-exprs-pats"> - <title>Expressions and patterns</title> - - <para>In its default mode, GHC makes some programs slightly more defined - than they should be. For example, consider - <programlisting> -f :: [a] -> b -> b -f [] = error "urk" -f (x:xs) = \v -> v - -main = print (f [] `seq` True) - </programlisting> -This should call <literal>error</literal> but actually prints <literal>True</literal>. -Reason: GHC eta-expands <literal>f</literal> to - <programlisting> -f :: [a] -> b -> b -f [] v = error "urk" -f (x:xs) v = v - </programlisting> -This improves efficiency slightly but significantly for most programs, and -is bad for only a few. To suppress this bogus "optimisation" use <option>-fpedantic-bottoms</option>. -</para> - - </sect3> - - <sect3 id="infelicities-decls"> - <title>Declarations and bindings</title> - - <para>In its default mode, GHC does not accept datatype contexts, - as it has been decided to remove them from the next version of the - language standard. This behaviour can be controlled with the - <option>DatatypeContexts</option> extension. - See <xref linkend="datatype-contexts" />.</para> - </sect3> - - <sect3 id="infelicities-Modules"> - <title>Module system and interface files</title> - - <para>GHC requires the use of <literal>hs-boot</literal> - files to cut the recursive loops among mutually recursive modules - as described in <xref linkend="mutual-recursion"/>. This more of an infelicity - than a bug: the Haskell Report says - (<ulink url="http://haskell.org/onlinereport/modules.html#sect5.7">Section 5.7</ulink>) "Depending on the Haskell - implementation used, separate compilation of mutually - recursive modules may require that imported modules contain - additional information so that they may be referenced before - they are compiled. Explicit type signatures for all exported - values may be necessary to deal with mutual recursion. The - precise details of separate compilation are not defined by - this Report." - - </para> - - </sect3> - - <sect3 id="infelicities-numbers"> - <title>Numbers, basic types, and built-in classes</title> - - <variablelist> - <varlistentry> - <term>Num superclasses</term> - <listitem> - <para> - The <literal>Num</literal> class does not have - <literal>Show</literal> or <literal>Eq</literal> - superclasses. - </para> - - <para> - You can make code that works with both - Haskell98/Haskell2010 and GHC by: - <itemizedlist> - <listitem> - <para> - Whenever you make a <literal>Num</literal> instance - of a type, also make <literal>Show</literal> and - <literal>Eq</literal> instances, and - </para> - </listitem> - <listitem> - <para> - Whenever you give a function, instance or class a - <literal>Num t</literal> constraint, also give it - <literal>Show t</literal> and - <literal>Eq t</literal> constraints. - </para> - </listitem> - </itemizedlist> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Bits superclasses</term> - <listitem> - <para> - The <literal>Bits</literal> class does not have - a <literal>Num</literal> superclasses. It therefore - does not have default methods for the - <literal>bit</literal>, - <literal>testBit</literal> and - <literal>popCount</literal> methods. - </para> - - <para> - You can make code that works with both - Haskell2010 and GHC by: - <itemizedlist> - <listitem> - <para> - Whenever you make a <literal>Bits</literal> instance - of a type, also make a <literal>Num</literal> - instance, and - </para> - </listitem> - <listitem> - <para> - Whenever you give a function, instance or class a - <literal>Bits t</literal> constraint, also give it - a <literal>Num t</literal> constraint, and - </para> - </listitem> - <listitem> - <para> - Always define the <literal>bit</literal>, - <literal>testBit</literal> and - <literal>popCount</literal> methods in - <literal>Bits</literal> instances. - </para> - </listitem> - </itemizedlist> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Extra instances</term> - <listitem> - <para> - The following extra instances are defined: - </para> -<programlisting> -instance Functor ((->) r) -instance Monad ((->) r) -instance Functor ((,) a) -instance Functor (Either a) -instance Monad (Either e) -</programlisting> - </listitem> - </varlistentry> - - <varlistentry> - <term>Multiply-defined array elements—not checked:</term> - <listitem> - <para>This code fragment should - elicit a fatal error, but it does not: - -<programlisting> -main = print (array (1,1) [(1,2), (1,3)])</programlisting> -GHC's implementation of <literal>array</literal> takes the value of an -array slot from the last (index,value) pair in the list, and does no -checking for duplicates. The reason for this is efficiency, pure and simple. - </para> - </listitem> - </varlistentry> - </variablelist> - - </sect3> - - <sect3 id="infelicities-Prelude"> - <title>In <literal>Prelude</literal> support</title> - - <variablelist> - <varlistentry> - <term>Arbitrary-sized tuples</term> - <listitem> - <para>Tuples are currently limited to size 100. HOWEVER: - standard instances for tuples (<literal>Eq</literal>, - <literal>Ord</literal>, <literal>Bounded</literal>, - <literal>Ix</literal> <literal>Read</literal>, and - <literal>Show</literal>) are available - <emphasis>only</emphasis> up to 16-tuples.</para> - - <para>This limitation is easily subvertible, so please ask - if you get stuck on it.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>splitAt</literal> semantics</term> - <para><literal>Data.List.splitAt</literal> is stricter than specified in the - Report. Specifically, the Report specifies that -<programlisting>splitAt n xs = (take n xs, drop n xs)</programlisting> - which implies that -<programlisting>splitAt undefined undefined = (undefined, undefined)</programlisting> - but GHC's implementation is strict in its first argument, so -<programlisting>splitAt undefined [] = undefined</programlisting> - </para> - </varlistentry> - <varlistentry> - <term><literal>Read</literal>ing integers</term> - <listitem> - <para>GHC's implementation of the - <literal>Read</literal> class for integral types accepts - hexadecimal and octal literals (the code in the Haskell - 98 report doesn't). So, for example, -<programlisting>read "0xf00" :: Int</programlisting> - works in GHC.</para> - <para>A possible reason for this is that <literal>readLitChar</literal> accepts hex and - octal escapes, so it seems inconsistent not to do so for integers too.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>isAlpha</literal></term> - <listitem> - <para>The Haskell 98 definition of <literal>isAlpha</literal> - is:</para> - -<programlisting>isAlpha c = isUpper c || isLower c</programlisting> - - <para>GHC's implementation diverges from the Haskell 98 - definition in the sense that Unicode alphabetic characters which - are neither upper nor lower case will still be identified as - alphabetic by <literal>isAlpha</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>hGetContents</literal></term> - <listitem> - <para> - Lazy I/O throws an exception if an error is - encountered, in contrast to the Haskell 98 spec which - requires that errors are discarded (see Section 21.2.2 - of the Haskell 98 report). The exception thrown is - the usual IO exception that would be thrown if the - failing IO operation was performed in the IO monad, and can - be caught by <literal>System.IO.Error.catch</literal> - or <literal>Control.Exception.catch</literal>. - </para> - </listitem> - </varlistentry> - </variablelist> - </sect3> - - <sect3 id="infelicities-ffi"> - <title>The Foreign Function Interface</title> - <variablelist> - <varlistentry> - <term><literal>hs_init()</literal> not allowed - after <literal>hs_exit()</literal></term> - <listitem> - <para>The FFI spec requires the implementation to support - re-initialising itself after being shut down - with <literal>hs_exit()</literal>, but GHC does not - currently support that.</para> - </listitem> - </varlistentry> - </variablelist> - </sect3> - - </sect2> - - <sect2 id="haskell-98-2010-undefined"> - <title>GHC's interpretation of undefined behaviour in - Haskell 98 and Haskell 2010</title> - - <para>This section documents GHC's take on various issues that are - left undefined or implementation specific in Haskell 98.</para> - - <variablelist> - <varlistentry> - <term> - The <literal>Char</literal> type - <indexterm><primary><literal>Char</literal></primary><secondary>size of</secondary></indexterm> - </term> - <listitem> - <para>Following the ISO-10646 standard, - <literal>maxBound :: Char</literal> in GHC is - <literal>0x10FFFF</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - Sized integral types - <indexterm><primary><literal>Int</literal></primary><secondary>size of</secondary></indexterm> - </term> - <listitem> - <para>In GHC the <literal>Int</literal> type follows the - size of an address on the host architecture; in other words - it holds 32 bits on a 32-bit machine, and 64-bits on a - 64-bit machine.</para> - - <para>Arithmetic on <literal>Int</literal> is unchecked for - overflow<indexterm><primary>overflow</primary><secondary><literal>Int</literal></secondary> - </indexterm>, so all operations on <literal>Int</literal> happen - modulo - 2<superscript><replaceable>n</replaceable></superscript> - where <replaceable>n</replaceable> is the size in bits of - the <literal>Int</literal> type.</para> - - <para>The <literal>fromInteger</literal><indexterm><primary><literal>fromInteger</literal></primary> - </indexterm> function (and hence - also <literal>fromIntegral</literal><indexterm><primary><literal>fromIntegral</literal></primary> - </indexterm>) is a special case when - converting to <literal>Int</literal>. The value of - <literal>fromIntegral x :: Int</literal> is given by taking - the lower <replaceable>n</replaceable> bits of <literal>(abs - x)</literal>, multiplied by the sign of <literal>x</literal> - (in 2's complement <replaceable>n</replaceable>-bit - arithmetic). This behaviour was chosen so that for example - writing <literal>0xffffffff :: Int</literal> preserves the - bit-pattern in the resulting <literal>Int</literal>.</para> - - - <para>Negative literals, such as <literal>-3</literal>, are - specified by (a careful reading of) the Haskell Report as - meaning <literal>Prelude.negate (Prelude.fromInteger 3)</literal>. - So <literal>-2147483648</literal> means <literal>negate (fromInteger 2147483648)</literal>. - Since <literal>fromInteger</literal> takes the lower 32 bits of the representation, - <literal>fromInteger (2147483648::Integer)</literal>, computed at type <literal>Int</literal> is - <literal>-2147483648::Int</literal>. The <literal>negate</literal> operation then - overflows, but it is unchecked, so <literal>negate (-2147483648::Int)</literal> is just - <literal>-2147483648</literal>. In short, one can write <literal>minBound::Int</literal> as - a literal with the expected meaning (but that is not in general guaranteed). - </para> - - <para>The <literal>fromIntegral</literal> function also - preserves bit-patterns when converting between the sized - integral types (<literal>Int8</literal>, - <literal>Int16</literal>, <literal>Int32</literal>, - <literal>Int64</literal> and the unsigned - <literal>Word</literal> variants), see the modules - <literal>Data.Int</literal> and <literal>Data.Word</literal> - in the library documentation.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Unchecked float arithmetic</term> - <listitem> - <para>Operations on <literal>Float</literal> and - <literal>Double</literal> numbers are - <emphasis>unchecked</emphasis> for overflow, underflow, and - other sad occurrences. (note, however, that some - architectures trap floating-point overflow and - loss-of-precision and report a floating-point exception, - probably terminating the - program)<indexterm><primary>floating-point - exceptions</primary></indexterm>.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - </sect1> - - - <sect1 id="bugs"> - <title>Known bugs or infelicities</title> - - <para>The bug tracker lists bugs that have been reported in GHC but not - yet fixed: see the <ulink url="http://ghc.haskell.org/trac/ghc/">GHC Trac</ulink>. In addition to those, GHC also has the following known bugs - or infelicities. These bugs are more permanent; it is unlikely that - any of them will be fixed in the short term.</para> - - <sect2 id="bugs-ghc"> - <title>Bugs in GHC</title> - - <itemizedlist> - <listitem> - <para>GHC's runtime system implements cooperative multitasking, with - context switching potentially occurring only when a program allocates. - This means that programs that do not allocate may never context switch. - See - <ulink url="https://ghc.haskell.org/trac/ghc/ticket/367">Trac #367</ulink> - for further discussion. - </para> - <para>If you are hit by this, you may want to compile the affected module - with <literal>-fno-omit-yields</literal>. This flag ensures that yield points - are inserted at every function entrypoint (at the expense of a bit of - performance). - </para> - </listitem> - - <listitem> - <para> GHC can warn about non-exhaustive or overlapping - patterns (see <xref linkend="options-sanity"/>), and usually - does so correctly. But not always. It gets confused by - string patterns, and by guards, and can then emit bogus - warnings. The entire overlap-check code needs an overhaul - really.</para> - </listitem> - - <listitem> - <para>GHC does not allow you to have a data type with a context - that mentions type variables that are not data type parameters. - For example: -<programlisting> - data C a b => T a = MkT a -</programlisting> - so that <literal>MkT</literal>'s type is -<programlisting> - MkT :: forall a b. C a b => a -> T a -</programlisting> - In principle, with a suitable class declaration with a functional dependency, - it's possible that this type is not ambiguous; but GHC nevertheless rejects - it. The type variables mentioned in the context of the data type declaration must - be among the type parameters of the data type.</para> - </listitem> - - <listitem> - <para>GHC's inliner can be persuaded into non-termination - using the standard way to encode recursion via a data type: -<programlisting> - data U = MkU (U -> Bool) - - russel :: U -> Bool - russel u@(MkU p) = not $ p u - - x :: Bool - x = russel (MkU russel) -</programlisting> - The non-termination is reported like this: -<programlisting> -ghc: panic! (the 'impossible' happened) - (GHC version 7.10.1 for x86_64-unknown-linux): - Simplifier ticks exhausted - When trying UnfoldingDone x_alB - To increase the limit, use -fsimpl-tick-factor=N (default 100) -</programlisting> - with the panic being reported no matter how high a <literal>-fsimpl-tick-factor</literal> you supply. - </para> - <para> - We have never found another class of programs, other - than this contrived one, that makes GHC diverge, and fixing - the problem would impose an extra overhead on every - compilation. So the bug remains un-fixed. There is more - background in <ulink - url="http://research.microsoft.com/~simonpj/Papers/inlining/"> - Secrets of the GHC inliner</ulink>.</para> - </listitem> - - <listitem> - <para>On 32-bit x86 platforms when using the native code - generator, the - <option>-fexcess-precision</option><indexterm><primary><option>-fexcess-precision</option></primary></indexterm> option - is always on. This means that floating-point calculations are - non-deterministic, because depending on how the program is - compiled (optimisation settings, for example), certain - calculations might be done at 80-bit precision instead of the - intended 32-bit or 64-bit precision. Floating-point results - may differ when optimisation is turned on. In the worst case, - referential transparency is violated, because for example - <literal>let x = E1 in E2</literal> can evaluate to a - different value than <literal>E2[E1/x]</literal>.</para> - - <para> - One workaround is to use the - <option>-msse2</option><indexterm><primary><option>-msse2</option></primary></indexterm> - option (see <xref linkend="options-platform" />, which - generates code to use the SSE2 instruction set instead of - the x87 instruction set. SSE2 code uses the correct - precision for all floating-point operations, and so gives - deterministic results. However, note that this only works - with processors that support SSE2 (Intel Pentium 4 or AMD - Athlon 64 and later), which is why the option is not enabled - by default. The libraries that come with GHC are probably - built without this option, unless you built GHC yourself. - </para> - </listitem> - - </itemizedlist> - </sect2> - - <sect2 id="bugs-ghci"> - <title>Bugs in GHCi (the interactive GHC)</title> - <itemizedlist> - <listitem> - <para>GHCi does not respect the <literal>default</literal> - declaration in the module whose scope you are in. Instead, - for expressions typed at the command line, you always get the - default default-type behaviour; that is, - <literal>default(Int,Double)</literal>.</para> - - <para>It would be better for GHCi to record what the default - settings in each module are, and use those of the 'current' - module (whatever that is).</para> - </listitem> - - <listitem> - <para>On Windows, there's a GNU ld/BFD bug - whereby it emits bogus PE object files that have more than - 0xffff relocations. When GHCi tries to load a package affected by this - bug, you get an error message of the form -<screen> -Loading package javavm ... linking ... WARNING: Overflown relocation field (# relocs found: 30765) -</screen> - The last time we looked, this bug still - wasn't fixed in the BFD codebase, and there wasn't any - noticeable interest in fixing it when we reported the bug - back in 2001 or so. - </para> - <para>The workaround is to split up the .o files that make up - your package into two or more .o's, along the lines of - how the "base" package does it.</para> - </listitem> - </itemizedlist> - </sect2> - </sect1> - -</chapter> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> diff --git a/docs/users_guide/codegens.rst b/docs/users_guide/codegens.rst new file mode 100644 index 0000000000..9915452fbd --- /dev/null +++ b/docs/users_guide/codegens.rst @@ -0,0 +1,115 @@ +.. _code-generators: + +GHC Backends +============ + +.. index:: + single: GHC backends + single: GHC code generators + +GHC supports multiple backend code generators. This is the part of the +compiler responsible for taking the last intermediate representation +that GHC uses (a form called Cmm that is a simple, C like language) and +compiling it to executable code. The backends that GHC support are +described below. + +.. _native-code-gen: + +Native code Generator (``-fasm``) +--------------------------------- + +.. index:: + single: native code generator + +The default backend for GHC. It is a native code generator, compiling +Cmm all the way to assembly code. It is the fastest backend and +generally produces good performance code. It has the best support for +compiling shared libraries. Select it with the ``-fasm`` flag. + +.. _llvm-code-gen: + +LLVM Code Generator (``-fllvm``) +-------------------------------- + +.. index:: + single: LLVM code generator + +This is an alternative backend that uses the `LLVM <http://llvm.org>`__ +compiler to produce executable code. It generally produces code as with +performance as good as the native code generator but for some cases can +produce much faster code. This is especially true for numeric, array +heavy code using packages like vector. The penalty is a significant +increase in compilation times. Select the LLVM backend with the +``-fllvm`` flag. Currently *LLVM 2.8* and later are supported. + +You must install and have LLVM available on your ``PATH`` for the LLVM code +generator to work. Specifically GHC needs to be able to call the ``opt`` +and ``llc`` tools. Secondly, if you are running Mac OS X with LLVM 3.0 +or greater then you also need the `Clang c +compiler <http://clang.llvm.org>`__ compiler available on your ``PATH``. + +To install LLVM and Clang: + +- *Linux*: Use your package management tool. + +- *Mac OS X*: Clang is included by default on recent OS X machines when + XCode is installed (from ``10.6`` and later). LLVM is not included. + In order to use the LLVM based code generator, you should install the + `Homebrew <http://mxcl.github.com/homebrew/>`__ package manager for + OS X. Alternatively you can download binaries for LLVM and Clang from + `here <http://llvm.org/releases/download.html>`__. + +- *Windows*: You should download binaries for LLVM and clang from + `here <http://llvm.org/releases/download.html>`__. + +.. _c-code-gen: + +C Code Generator (``-fvia-C``) +------------------------------ + +.. index:: + single: C code generator + single: -fvia-C + +This is the oldest code generator in GHC and is generally not included +any more having been deprecated around GHC 7.0. Select it with the +``-fvia-C`` flag. + +The C code generator is only supported when GHC is built in +unregisterised mode, a mode where GHC produces "portable" C code as +output to facilitate porting GHC itself to a new platform. This mode +produces much slower code though so it's unlikely your version of GHC +was built this way. If it has then the native code generator probably +won't be available. You can check this information by calling +```ghc --info`` (see :ref:`ghc-info`). + +.. _unreg: + +Unregisterised compilation +-------------------------- + +.. index:: + single: unregisterised compilation + +The term "unregisterised" really means "compile via vanilla C", +disabling some of the platform-specific tricks that GHC normally uses to +make programs go faster. When compiling unregisterised, GHC simply +generates a C file which is compiled via gcc. + +When GHC is build in unregisterised mode only the LLVM and C code +generators will be available. The native code generator won't be. LLVM +usually offers a substantial performance benefit over the C backend in +unregisterised mode. + +Unregisterised compilation can be useful when porting GHC to a new +machine, since it reduces the prerequisite tools to ``gcc``, ``as``, and +``ld`` and nothing more, and furthermore the amount of platform-specific +code that needs to be written in order to get unregisterised compilation +going is usually fairly small. + +Unregisterised compilation cannot be selected at compile-time; you have +to build GHC with the appropriate options set. Consult the GHC Building +Guide for details. + +You can check if your GHC is unregisterised by calling +```ghc --info`` (see :ref:`ghc-info`). diff --git a/docs/users_guide/codegens.xml b/docs/users_guide/codegens.xml deleted file mode 100644 index d9c4859071..0000000000 --- a/docs/users_guide/codegens.xml +++ /dev/null @@ -1,125 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<sect1 id="code-generators"> - <title>GHC Backends</title> - <indexterm><primary>ghc backends</primary></indexterm> - <indexterm><primary>ghc code generators</primary></indexterm> - - <para>GHC supports multiple backend code generators. This is the part - of the compiler responsible for taking the last intermediate - representation that GHC uses (a form called Cmm that is a simple, C like - language) and compiling it to executable code. The backends that GHC - support are described below. - </para> - - <sect2 id="native-code-gen"> - <title>Native code Generator (<option>-fasm</option>)</title> - <indexterm><primary>native code generator</primary></indexterm> - - The default backend for GHC. It is a native code generator, compiling Cmm - all the way to assembly code. It is the fastest backend and generally - produces good performance code. It has the best support for compiling - shared libraries. Select it with the <option>-fasm</option> flag. - </sect2> - - <sect2 id="llvm-code-gen"> - <title>LLVM Code Generator (<option>-fllvm</option>)</title> - <indexterm><primary>LLVM code generator</primary></indexterm> - - <para>This is an alternative backend that uses the - <ulink url="http://llvm.org">LLVM</ulink> compiler to produce - executable code. It generally produces code as with performance as - good as the native code generator but for some cases can produce - much faster code. This is especially true for numeric, array heavy - code using packages like vector. The penalty is a significant increase in - compilation times. Select the LLVM backend with the - <option>-fllvm</option> flag. Currently <emphasis>LLVM 2.8</emphasis> and - later are supported. - </para> - - <para>You must install and have LLVM available on your PATH for the LLVM - code generator to work. Specifically GHC needs to be able to call the - <command>opt</command> and <command>llc</command> tools. Secondly, if you - are running Mac OS X with LLVM 3.0 or greater then - you also need the <ulink url="http://clang.llvm.org">Clang c - compiler</ulink> compiler available on your PATH. - </para> - - <para>To install LLVM and Clang: - <itemizedlist> - <listitem><para><emphasis>Linux</emphasis>: Use your package management tool.</para> - </listitem> - <listitem><para><emphasis>Mac OS X</emphasis>: Clang is included by - default on recent OS X machines when XCode is installed (from - <literal>10.6</literal> and later). LLVM is not included. In - order to use the LLVM based code generator, you should install - the <ulink - url="http://mxcl.github.com/homebrew/">Homebrew</ulink> - package manager for OS X. Alternatively you can download - binaries for LLVM and Clang from <ulink - url="http://llvm.org/releases/download.html">here</ulink>.</para> - </listitem> - - <listitem><para><emphasis>Windows</emphasis>: You should download binaries for - LLVM and clang from - <ulink url="http://llvm.org/releases/download.html">here</ulink>.</para> - </listitem> - </itemizedlist> - </para> - </sect2> - - <sect2 id="c-code-gen"> - <title>C Code Generator (<option>-fvia-C</option>)</title> - <indexterm><primary>C code generator</primary></indexterm> - <indexterm><primary>-fvia-C</primary></indexterm> - - <para>This is the oldest code generator in GHC and is generally not included - any more having been deprecated around GHC 7.0. Select it with the - <option>-fvia-C</option> flag. - </para> - - <para>The C code generator is only supported when GHC is built in - unregisterised mode, a mode where GHC produces 'portable' C code as - output to facilitate porting GHC itself to a new platform. This mode - produces much slower code though so it's unlikely your version of - GHC was built this way. If it has then the native code generator - probably won't be available. You can check this information by calling - <link linkend="ghc-info"><literal>ghc --info</literal></link>. - </para> - </sect2> - - <sect2 id="unreg"> - <title>Unregisterised compilation</title> - <indexterm><primary>unregisterised compilation</primary></indexterm> - - <para>The term "unregisterised" really means "compile via vanilla C", - disabling some of the platform-specific tricks that GHC normally uses to - make programs go faster. When compiling unregisterised, GHC simply - generates a C file which is compiled via gcc.</para> - - <para>When GHC is build in unregisterised mode only the LLVM and C code - generators will be available. The native code generator won't be. LLVM - usually offers a substantial performance benefit over the C backend in - unregisterised mode.</para> - - <para>Unregisterised compilation can be useful when porting GHC to a new - machine, since it reduces the prerequisite tools to - <command>gcc</command>, <command>as</command>, and <command>ld</command> - and nothing more, and furthermore the amount of platform-specific code - that needs to be written in order to get - unregisterised compilation going is usually fairly small.</para> - - <para>Unregisterised compilation cannot be selected at compile-time; you - have to build GHC with the appropriate options set. Consult the GHC - Building Guide for details.</para> - - <para>You can check if your GHC is unregisterised by calling - <link linkend="ghc-info"><literal>ghc --info</literal></link>.</para> - </sect2> - -</sect1> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") *** - ;;; End: *** - --> diff --git a/docs/users_guide/conf.py b/docs/users_guide/conf.py new file mode 100644 index 0000000000..eef8f4c1c6 --- /dev/null +++ b/docs/users_guide/conf.py @@ -0,0 +1,112 @@ +# -*- coding: utf-8 -*- +# +# GHC Users Guide documentation build configuration file +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +import sys +import os + +# Support for :base-ref:, etc. +sys.path.insert(0, os.path.abspath('.')) +from ghc_config import extlinks, version + +extensions = ['sphinx.ext.extlinks'] + +templates_path = ['.templates'] +source_suffix = '.rst' +source_encoding = 'utf-8-sig' +master_doc = 'index' + +# General information about the project. +project = u'Glasgow Haskell Compiler' +copyright = u'2015, GHC Team' +# N.B. version comes from ghc_config +release = version # The full version, including alpha/beta/rc tags. + +# Syntax highlighting +highlight_language = 'haskell' +pygments_style = 'colorful' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['.build', "*.gen.rst"] + +# -- Options for HTML output --------------------------------------------- + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +html_title = "Glasgow Haskell Compiler <release> Users Guide" +html_short_title = "GHC %s Users Guide" % release +html_theme_path = ['.'] +html_theme = 'ghc-theme' +html_logo = None +html_static_path = ['images'] +# Convert quotes and dashes to typographically correct entities +html_use_smartypants = True +html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'GHCUsersGuide' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + 'inputenv': '', + 'utf8extra': '', + 'preamble': ''' +\usepackage{fontspec} +\setsansfont{DejaVu Sans} +\setromanfont{DejaVu Serif} +\setmonofont{DejaVu Sans Mono} +''', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'users_guide.tex', u'GHC Users Guide Documentation', + u'GHC Team', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +latex_logo = 'images/logo.pdf' + +# If true, show page references after internal links. +latex_show_pagerefs = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('ghc', 'ghc', 'the Glasgow Haskell Compiler', 'The GHC Team', 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'GHCUsersGuide', u'GHC Users Guide', + u'GHC Team', 'GHCUsersGuide', 'The Glasgow Haskell Compiler.', + 'Compilers'), +] diff --git a/docs/users_guide/debugging.rst b/docs/users_guide/debugging.rst new file mode 100644 index 0000000000..9482b8ef93 --- /dev/null +++ b/docs/users_guide/debugging.rst @@ -0,0 +1,431 @@ +.. _options-debugging: + +Debugging the compiler +====================== + +.. index:: + single: debugging options (for GHC) + +HACKER TERRITORY. HACKER TERRITORY. (You were warned.) + +.. _dumping-output: + +Dumping out compiler intermediate structures +-------------------------------------------- + +.. index:: + single: dumping GHC intermediates + single: intermediate passes, output + +``-ddump-`` ⟨pass⟩ + .. index:: + single: -ddump options + + Make a debugging dump after pass ``<pass>`` (may be common enough to + need a short form…). You can get all of these at once (*lots* of + output) by using ``-v5``, or most of them with ``-v4``. You can + prevent them from clogging up your standard output by passing + ``-ddump-to-file``. Some of the most useful ones are: + + ``-ddump-parsed`` + .. index:: + single: -ddump-parsed + + Dump parser output + + ``-ddump-rn`` + .. index:: + single: -ddump-rn + + Dump renamer output + + ``-ddump-tc`` + .. index:: + single: -ddump-tc + + Dump typechecker output + + ``-ddump-splices`` + .. index:: + single: -ddump-splices + + Dump Template Haskell expressions that we splice in, and what + Haskell code the expression evaluates to. + + ``-ddump-types`` + .. index:: + single: -ddump-types + + Dump a type signature for each value defined at the top level of + the module. The list is sorted alphabetically. Using + ``-dppr-debug`` dumps a type signature for all the imported and + system-defined things as well; useful for debugging the + compiler. + + ``-ddump-deriv`` + .. index:: + single: -ddump-deriv + + Dump derived instances + + ``-ddump-ds`` + .. index:: + single: -ddump-ds + + Dump desugarer output + + ``-ddump-spec`` + .. index:: + single: -ddump-spec + + Dump output of specialisation pass + + ``-ddump-rules`` + .. index:: + single: -ddump-rules + + Dumps all rewrite rules specified in this module; see + :ref:`controlling-rules`. + + ``-ddump-rule-firings`` + .. index:: + single: -ddump-rule-firings + + Dumps the names of all rules that fired in this module + + ``-ddump-rule-rewrites`` + .. index:: + single: -ddump-rule-rewrites + + Dumps detailed information about all rules that fired in this + module + + ``-ddump-vect`` + .. index:: + single: -ddump-vect + + Dumps the output of the vectoriser. + + ``-ddump-simpl`` + .. index:: + single: -ddump-simpl + + Dump simplifier output (Core-to-Core passes) + + ``-ddump-inlinings`` + .. index:: + single: -ddump-inlinings + + Dumps inlining info from the simplifier + + ``-ddump-stranal`` + .. index:: + single: -ddump-stranal + + Dump strictness analyser output + + ``-ddump-strsigs`` + .. index:: + single: -ddump-strsigs + + Dump strictness signatures + + ``-ddump-cse`` + .. index:: + single: -ddump-cse + + Dump common subexpression elimination (CSE) pass output + + ``-ddump-worker-wrapper`` + .. index:: + single: -ddump-worker-wrapper + + Dump worker/wrapper split output + + ``-ddump-occur-anal`` + .. index:: + single: -ddump-occur-anal + + Dump "occurrence analysis" output + + ``-ddump-prep`` + .. index:: + single: -ddump-prep + + Dump output of Core preparation pass + + ``-ddump-stg`` + .. index:: + single: -ddump-stg + + Dump output of STG-to-STG passes + + ``-ddump-cmm`` + .. index:: + single: -ddump-cmm + + Print the C-- code out. + + ``-ddump-opt-cmm`` + .. index:: + single: -ddump-opt-cmm + + Dump the results of C-- to C-- optimising passes. + + ``-ddump-asm`` + .. index:: + single: -ddump-asm + + Dump assembly language produced by the :ref:`native code + generator <native-code-gen>` + + ``-ddump-llvm`` + .. index:: + single: -ddump-llvm + + LLVM code from the :ref:`LLVM code generator <llvm-code-gen>` + + ``-ddump-bcos`` + .. index:: + single: -ddump-bcos + + Dump byte-code compiler output + + ``-ddump-foreign`` + .. index:: + single: -ddump-foreign + + dump foreign export stubs + +``-ddump-simpl-iterations`` + .. index:: + single: -ddump-simpl-iterations + + Show the output of each *iteration* of the simplifier (each run of + the simplifier has a maximum number of iterations, normally 4). This + outputs even more information than ``-ddump-simpl-phases``. + +``-ddump-simpl-stats`` + .. index:: + single: -ddump-simpl-stats option + + Dump statistics about how many of each kind of transformation too + place. If you add ``-dppr-debug`` you get more detailed information. + +``-ddump-if-trace`` + .. index:: + single: -ddump-if-trace + + Make the interface loader be *real* chatty about what it is up to. + +``-ddump-tc-trace`` + .. index:: + single: -ddump-tc-trace + + Make the type checker be *real* chatty about what it is up to. + +``-ddump-vt-trace`` + .. index:: + single: -ddump-tv-trace + + Make the vectoriser be *real* chatty about what it is up to. + +``-ddump-rn-trace`` + .. index:: + single: -ddump-rn-trace + + Make the renamer be *real* chatty about what it is up to. + +``-ddump-rn-stats`` + .. index:: + single: -dshow-rn-stats + + Print out summary of what kind of information the renamer had to + bring in. + +``-dverbose-core2core``, ``-dverbose-stg2stg`` + .. index:: + single: -dverbose-core2core + single: -dverbose-stg2stg + + Show the output of the intermediate Core-to-Core and STG-to-STG + passes, respectively. (*lots* of output!) So: when we're really + desperate: + + :: + + % ghc -noC -O -ddump-simpl -dverbose-core2core -dcore-lint Foo.hs + +``-dshow-passes`` + .. index:: + single: -dshow-passes + + Print out each pass name as it happens. + +``-ddump-core-stats`` + .. index:: + single: -ddump-core-stats + + Print a one-line summary of the size of the Core program at the end + of the optimisation pipeline. + +``-dfaststring-stats`` + .. index:: + single: -dfaststring-stats + + Show statistics on the usage of fast strings by the compiler. + +``-dppr-debug`` + .. index:: + single: -dppr-debug + + Debugging output is in one of several "styles." Take the printing of + types, for example. In the "user" style (the default), the + compiler's internal ideas about types are presented in Haskell + source-level syntax, insofar as possible. In the "debug" style + (which is the default for debugging output), the types are printed + in with explicit foralls, and variables have their unique-id + attached (so you can check for things that look the same but + aren't). This flag makes debugging output appear in the more verbose + debug style. + +.. _formatting dumps: + +Formatting dumps +---------------- + +.. index:: + single: formatting dumps + +``-dppr-user-length`` + .. index:: + single: -dppr-user-length + + In error messages, expressions are printed to a certain "depth", + with subexpressions beyond the depth replaced by ellipses. This flag + sets the depth. Its default value is 5. + +``-dppr-colsNNN`` + .. index:: + single: -dppr-colsNNN + + Set the width of debugging output. Use this if your code is wrapping + too much. For example: ``-dppr-cols200``. + +``-dppr-case-as-let`` + .. index:: + single: -dppr-case-as-let + + Print single alternative case expressions as though they were strict + let expressions. This is helpful when your code does a lot of + unboxing. + +``-dno-debug-output`` + .. index:: + single: -dno-debug-output + + Suppress any unsolicited debugging output. When GHC has been built + with the ``DEBUG`` option it occasionally emits debug output of + interest to developers. The extra output can confuse the testing + framework and cause bogus test failures, so this flag is provided to + turn it off. + +.. _suppression: + +Suppressing unwanted information +-------------------------------- + +.. index:: + single: suppression; of unwanted dump output + +Core dumps contain a large amount of information. Depending on what you +are doing, not all of it will be useful. Use these flags to suppress the +parts that you are not interested in. + +``-dsuppress-all`` + .. index:: + single: -dsuppress-all + + Suppress everything that can be suppressed, except for unique ids as + this often makes the printout ambiguous. If you just want to see the + overall structure of the code, then start here. + +``-dsuppress-uniques`` + .. index:: + single: -dsuppress-uniques + + Suppress the printing of uniques. This may make the printout + ambiguous (e.g. unclear where an occurrence of 'x' is bound), but it + makes the output of two compiler runs have many fewer gratuitous + differences, so you can realistically apply ``diff``. Once ``diff`` + has shown you where to look, you can try again without + ``-dsuppress-uniques`` + +``-dsuppress-idinfo`` + .. index:: + single: -dsuppress-idinfo + + Suppress extended information about identifiers where they are + bound. This includes strictness information and inliner templates. + Using this flag can cut the size of the core dump in half, due to + the lack of inliner templates + +``-dsuppress-unfoldings`` + .. index:: + single: -dsuppress-unfoldings + + Suppress the printing of the stable unfolding of a variable at its + binding site. + +``-dsuppress-module-prefixes`` + .. index:: + single: -dsuppress-module-prefixes + + Suppress the printing of module qualification prefixes. This is the + ``Data.List`` in ``Data.List.length``. + +``-dsuppress-type-signatures`` + .. index:: + single: -dsuppress-type-signatures + + Suppress the printing of type signatures. + +``-dsuppress-type-applications`` + .. index:: + single: -dsuppress-type-applications + + Suppress the printing of type applications. + +``-dsuppress-coercions`` + .. index:: + single: -dsuppress-coercions + + Suppress the printing of type coercions. + +.. _checking-consistency: + +Checking for consistency +------------------------ + +.. index:: + single: consistency checks + single: lint + +``-dcore-lint`` + .. index:: + single: -dcore-lint + + Turn on heavyweight intra-pass sanity-checking within GHC, at Core + level. (It checks GHC's sanity, not yours.) + +``-dstg-lint`` + .. index:: + single: -dstg-lint + + Ditto for STG level. (note: currently doesn't work). + +``-dcmm-lint`` + .. index:: + single: -dcmm-lint + + Ditto for C-- level. diff --git a/docs/users_guide/debugging.xml b/docs/users_guide/debugging.xml deleted file mode 100644 index fd12e1d79a..0000000000 --- a/docs/users_guide/debugging.xml +++ /dev/null @@ -1,681 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<sect1 id="options-debugging"> - <title>Debugging the compiler</title> - - <indexterm><primary>debugging options (for GHC)</primary></indexterm> - - <para>HACKER TERRITORY. HACKER TERRITORY. (You were warned.)</para> - - <sect2 id="dumping-output"> - <title>Dumping out compiler intermediate structures</title> - - <indexterm><primary>dumping GHC intermediates</primary></indexterm> - <indexterm><primary>intermediate passes, output</primary></indexterm> - - <variablelist> - <varlistentry> - <term> - <option>-ddump-</option><replaceable>pass</replaceable> - <indexterm><primary><option>-ddump</option> options</primary></indexterm> - </term> - <listitem> - <para>Make a debugging dump after pass - <literal><pass></literal> (may be common enough to need - a short form…). You can get all of these at once - (<emphasis>lots</emphasis> of output) by using - <option>-v5</option>, or most of them with - <option>-v4</option>. You can prevent them from clogging up - your standard output by passing <option>-ddump-to-file</option>. - Some of the most useful ones are:</para> - - <variablelist> - <varlistentry> - <term> - <option>-ddump-parsed</option>: - <indexterm><primary><option>-ddump-parsed</option></primary></indexterm> - </term> - <listitem> - <para>parser output</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-rn</option>: - <indexterm><primary><option>-ddump-rn</option></primary></indexterm> - </term> - <listitem> - <para>renamer output</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-tc</option>: - <indexterm><primary><option>-ddump-tc</option></primary></indexterm> - </term> - <listitem> - <para>typechecker output</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-splices</option>: - <indexterm><primary><option>-ddump-splices</option></primary></indexterm> - </term> - <listitem> - <para>Dump Template Haskell expressions that we splice in, - and what Haskell code the expression evaluates to.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-types</option>: - <indexterm><primary><option>-ddump-types</option></primary></indexterm> - </term> - <listitem> - <para>Dump a type signature for each value defined at - the top level of the module. The list is sorted - alphabetically. Using <option>-dppr-debug</option> - dumps a type signature for all the imported and - system-defined things as well; useful for debugging the - compiler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-deriv</option>: - <indexterm><primary><option>-ddump-deriv</option></primary></indexterm> - </term> - <listitem> - <para>derived instances</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-ds</option>: - <indexterm><primary><option>-ddump-ds</option></primary></indexterm> - </term> - <listitem> - <para>desugarer output</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-spec</option>: - <indexterm><primary><option>-ddump-spec</option></primary></indexterm> - </term> - <listitem> - <para>output of specialisation pass</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-rules</option>: - <indexterm><primary><option>-ddump-rules</option></primary></indexterm> - </term> - <listitem> - <para>dumps all rewrite rules specified in this module; - see <xref linkend="controlling-rules"/>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-rule-firings</option>: - <indexterm><primary><option>-ddump-rule-firings</option></primary></indexterm> - </term> - <listitem> - <para>dumps the names of all rules that fired in this module</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-rule-rewrites</option>: - <indexterm><primary><option>-ddump-rule-rewrites</option></primary></indexterm> - </term> - <listitem> - <para>dumps detailed information about all rules that fired in - this module - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-vect</option>: - <indexterm><primary><option>-ddump-vect</option></primary></indexterm> - </term> - <listitem> - <para>dumps the output of the vectoriser. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-simpl</option>: - <indexterm><primary><option>-ddump-simpl</option></primary></indexterm> - </term> - <listitem> - <para>simplifier output (Core-to-Core passes)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-inlinings</option>: - <indexterm><primary><option>-ddump-inlinings</option></primary></indexterm> - </term> - <listitem> - <para>inlining info from the simplifier</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-stranal</option>: - <indexterm><primary><option>-ddump-stranal</option></primary></indexterm> - </term> - <listitem> - <para>strictness analyser output</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-strsigs</option>: - <indexterm><primary><option>-ddump-strsigs</option></primary></indexterm> - </term> - <listitem> - <para>strictness signatures</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-cse</option>: - <indexterm><primary><option>-ddump-cse</option></primary></indexterm> - </term> - <listitem> - <para>CSE pass output</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-worker-wrapper</option>: - <indexterm><primary><option>-ddump-worker-wrapper</option></primary></indexterm> - </term> - <listitem> - <para>worker/wrapper split output</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-occur-anal</option>: - <indexterm><primary><option>-ddump-occur-anal</option></primary></indexterm> - </term> - <listitem> - <para>`occurrence analysis' output</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-prep</option>: - <indexterm><primary><option>-ddump-prep</option></primary></indexterm> - </term> - <listitem> - <para>output of core preparation pass</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-stg</option>: - <indexterm><primary><option>-ddump-stg</option></primary></indexterm> - </term> - <listitem> - <para>output of STG-to-STG passes</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-cmm</option>: - <indexterm><primary><option>-ddump-cmm</option></primary></indexterm> - </term> - <listitem> - <para>Print the C-- code out.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-opt-cmm</option>: - <indexterm><primary><option>-ddump-opt-cmm</option></primary></indexterm> - </term> - <listitem> - <para>Dump the results of C-- to C-- optimising passes.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-asm</option>: - <indexterm><primary><option>-ddump-asm</option></primary></indexterm> - </term> - <listitem> - <para>assembly language from the - <link linkend="native-code-gen">native code generator</link></para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-llvm</option>: - <indexterm><primary><option>-ddump-llvm</option></primary></indexterm> - </term> - <listitem> - <para>LLVM code from the <link linkend="llvm-code-gen">LLVM code - generator</link></para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-bcos</option>: - <indexterm><primary><option>-ddump-bcos</option></primary></indexterm> - </term> - <listitem> - <para>byte code compiler output</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-foreign</option>: - <indexterm><primary><option>-ddump-foreign</option></primary></indexterm> - </term> - <listitem> - <para>dump foreign export stubs</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-simpl-iterations</option>: - <indexterm><primary><option>-ddump-simpl-iterations</option></primary></indexterm> - </term> - <listitem> - <para>Show the output of each <emphasis>iteration</emphasis> - of the simplifier (each run of the simplifier has a maximum - number of iterations, normally 4). This outputs even more information - than <option>-ddump-simpl-phases</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-simpl-stats</option> - <indexterm><primary><option>-ddump-simpl-stats option</option></primary></indexterm> - </term> - <listitem> - <para>Dump statistics about how many of each kind of - transformation too place. If you add - <option>-dppr-debug</option> you get more detailed - information.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-if-trace</option> - <indexterm><primary><option>-ddump-if-trace</option></primary></indexterm> - </term> - <listitem> - <para>Make the interface loader be *real* chatty about what it is - up to.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-tc-trace</option> - <indexterm><primary><option>-ddump-tc-trace</option></primary></indexterm> - </term> - <listitem> - <para>Make the type checker be *real* chatty about what it is - up to.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-vt-trace</option> - <indexterm><primary><option>-ddump-tv-trace</option></primary></indexterm> - </term> - <listitem> - <para>Make the vectoriser be *real* chatty about what it is - up to.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-rn-trace</option> - <indexterm><primary><option>-ddump-rn-trace</option></primary></indexterm> - </term> - <listitem> - <para>Make the renamer be *real* chatty about what it is - up to.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-rn-stats</option> - <indexterm><primary><option>-dshow-rn-stats</option></primary></indexterm> - </term> - <listitem> - <para>Print out summary of what kind of information the renamer - had to bring in.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dverbose-core2core</option> - <indexterm><primary><option>-dverbose-core2core</option></primary></indexterm> - </term> - <term> - <option>-dverbose-stg2stg</option> - <indexterm><primary><option>-dverbose-stg2stg</option></primary></indexterm> - </term> - <listitem> - <para>Show the output of the intermediate Core-to-Core and - STG-to-STG passes, respectively. (<emphasis>Lots</emphasis> - of output!) So: when we're really desperate:</para> - - <screen> -% ghc -noC -O -ddump-simpl -dverbose-core2core -dcore-lint Foo.hs -</screen> - - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dshow-passes</option> - <indexterm><primary><option>-dshow-passes</option></primary></indexterm> - </term> - <listitem> - <para>Print out each pass name as it happens.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-core-stats</option> - <indexterm><primary><option>-ddump-core-stats</option></primary></indexterm> - </term> - <listitem> - <para>Print a one-line summary of the size of the Core program - at the end of the optimisation pipeline.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dfaststring-stats</option> - <indexterm><primary><option>-dfaststring-stats</option></primary></indexterm> - </term> - <listitem> - <para>Show statistics for the usage of fast strings by the - compiler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dppr-debug</option> - <indexterm><primary><option>-dppr-debug</option></primary></indexterm> - </term> - <listitem> - <para>Debugging output is in one of several - “styles.” Take the printing of types, for - example. In the “user” style (the default), the - compiler's internal ideas about types are presented in - Haskell source-level syntax, insofar as possible. In the - “debug” style (which is the default for - debugging output), the types are printed in with explicit - foralls, and variables have their unique-id attached (so you - can check for things that look the same but aren't). This - flag makes debugging output appear in the more verbose debug - style.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="formatting dumps"> - <title>Formatting dumps</title> - - <indexterm><primary>formatting dumps</primary></indexterm> - - <variablelist> - <varlistentry> - <term> - <option>-dppr-user-length</option> - <indexterm><primary><option>-dppr-user-length</option></primary></indexterm> - </term> - <listitem> - <para>In error messages, expressions are printed to a - certain “depth”, with subexpressions beyond the - depth replaced by ellipses. This flag sets the - depth. Its default value is 5.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dppr-colsNNN</option> - <indexterm><primary><option>-dppr-colsNNN</option></primary></indexterm> - </term> - <listitem> - <para>Set the width of debugging output. Use this if your code is wrapping too much. - For example: <option>-dppr-cols200</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dppr-case-as-let</option> - <indexterm><primary><option>-dppr-case-as-let</option></primary></indexterm> - </term> - <listitem> - <para>Print single alternative case expressions as though they were strict - let expressions. This is helpful when your code does a lot of unboxing.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dno-debug-output</option> - <indexterm><primary><option>-dno-debug-output</option></primary></indexterm> - </term> - <listitem> - <para>Suppress any unsolicited debugging output. When GHC - has been built with the <literal>DEBUG</literal> option it - occasionally emits debug output of interest to developers. - The extra output can confuse the testing framework and - cause bogus test failures, so this flag is provided to - turn it off.</para> - </listitem> - </varlistentry> - </variablelist> - - </sect2> - - <sect2 id="suppression"> - <title>Suppressing unwanted information</title> - - <indexterm><primary>suppression</primary></indexterm> - - Core dumps contain a large amount of information. Depending on what you are doing, not all of it will be useful. - Use these flags to suppress the parts that you are not interested in. - - <variablelist> - <varlistentry> - <term> - <option>-dsuppress-all</option> - <indexterm><primary><option>-dsuppress-all</option></primary></indexterm> - </term> - <listitem> - <para>Suppress everything that can be suppressed, except for unique ids as this often - makes the printout ambiguous. If you just want to see the overall structure of - the code, then start here.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dsuppress-uniques</option> - <indexterm><primary><option>-dsuppress-uniques</option></primary></indexterm> - </term> - <listitem> - <para>Suppress the printing of uniques. This may make - the printout ambiguous (e.g. unclear where an occurrence of 'x' is bound), but - it makes the output of two compiler runs have many fewer gratuitous differences, - so you can realistically apply <command>diff</command>. Once <command>diff</command> - has shown you where to look, you can try again without <option>-dsuppress-uniques</option></para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dsuppress-idinfo</option> - <indexterm><primary><option>-dsuppress-idinfo</option></primary></indexterm> - </term> - <listitem> - <para>Suppress extended information about identifiers where they are bound. This includes - strictness information and inliner templates. Using this flag can cut the size - of the core dump in half, due to the lack of inliner templates</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dsuppress-unfoldings</option> - <indexterm><primary><option>-dsuppress-unfoldings</option></primary></indexterm> - </term> - <listitem> - <para>Suppress the printing of the stable unfolding of a variable at its binding site.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dsuppress-module-prefixes</option> - <indexterm><primary><option>-dsuppress-module-prefixes</option></primary></indexterm> - </term> - <listitem> - <para>Suppress the printing of module qualification prefixes. - This is the <constant>Data.List</constant> in <constant>Data.List.length</constant>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dsuppress-type-signatures</option> - <indexterm><primary><option>-dsuppress-type-signatures</option></primary></indexterm> - </term> - <listitem> - <para>Suppress the printing of type signatures.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dsuppress-type-applications</option> - <indexterm><primary><option>-dsuppress-type-applications</option></primary></indexterm> - </term> - <listitem> - <para>Suppress the printing of type applications.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dsuppress-coercions</option> - <indexterm><primary><option>-dsuppress-coercions</option></primary></indexterm> - </term> - <listitem> - <para>Suppress the printing of type coercions.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="checking-consistency"> - <title>Checking for consistency</title> - - <indexterm><primary>consistency checks</primary></indexterm> - <indexterm><primary>lint</primary></indexterm> - - <variablelist> - - <varlistentry> - <term> - <option>-dcore-lint</option> - <indexterm><primary><option>-dcore-lint</option></primary></indexterm> - </term> - <listitem> - <para>Turn on heavyweight intra-pass sanity-checking within - GHC, at Core level. (It checks GHC's sanity, not yours.)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dstg-lint</option>: - <indexterm><primary><option>-dstg-lint</option></primary></indexterm> - </term> - <listitem> - <para>Ditto for STG level. (NOTE: currently doesn't work).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dcmm-lint</option>: - <indexterm><primary><option>-dcmm-lint</option></primary></indexterm> - </term> - <listitem> - <para>Ditto for C-- level.</para> - </listitem> - </varlistentry> - - </variablelist> - </sect2> - -</sect1> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") *** - ;;; End: *** - --> diff --git a/docs/users_guide/editing-guide.rst b/docs/users_guide/editing-guide.rst new file mode 100644 index 0000000000..7e973ce6d3 --- /dev/null +++ b/docs/users_guide/editing-guide.rst @@ -0,0 +1,334 @@ +Care and feeding of your GHC Users Guide +======================================== + +The GHC User's Guide is the primary reference documentation +for the Glasgow Haskell Compiler. Even more than this, it at times serves (for +better or for worse) as a de-facto language standard, being the sole +non-academic reference for many widely used language extensions. + +Since GHC 8.0, the User's Guide is authored in `ReStructuredText +<https://en.wikipedia.org/wiki/ReStructuredText>`__ (or ReST or RST, for short) +a rich but light-weight mark-up language aimed at producing documentation. The +`Sphinx <http://sphinx-doc.org/>`__ tool is used to produce the final PDF and +HTML documentation. + +This document (also written in ReST) serves as a brief introducion to ReST and to +document the conventions used in the User's Guide. This document is *not* intended +to be a thorough guide to ReST. For this see the resources referenced +`below <#references>`__. + +Basics +------ + +Unicode characters are allowed in the document. + +The basic syntax works largely as one would expect. For instance, + +.. code-block:: rest + + This is a paragraph containing a few sentences of text. Purple turtles walk + through green fields of lofty maize. Lorem ipsum dolor sit amet, consectetur + adipiscing elit. Some lists, + + 1. This is a list item + + a. Followed by a sub-item + b. And another! + c. Now with ``a bit of code`` and some *emphasis*. + + 2. Back to the first list + + Or perhaps you are more of a bullet list person, + + * Foo + * Fizzle + + - Bar + - Blah + + Or perhaps a definition list is in order, + + *Chelonii* + The taxonomic order consisting of modern turtles + *Meiolaniidae* + The taxonomic order of an extinct variety of herbivorous turtles. + +Note the blank lines between a list item and its sub-items. Sub-items should be +on the same indentation level as the content of their parent items. Also note +that no whitespace is necessary or desirable before the bullet or item number +(lest the list be indented unnecessarily). + +The above would be rendered as, + + This is a paragraph containing a few sentences of text. Purple turtles walk + through green fields of lofty maize. Lorem ipsum dolor sit amet, consectetur + adipiscing elit. Some lists, + + 1. This is a list item + + a. Followed by a sub-item + b. And another! + c. Now with ``a bit of code`` and some *emphasis*. + + 2. Back to the first list + + Or perhaps you are more of a bullet list person, + + * Foo + * Fizzle + + - Bar + - Blah + + Or perhaps a definition list is in order, + + *Chelonii* + The taxonomic order consisting of modern turtles + *Meiolaniidae* + The taxonomic order of an extinct variety of herbivorous turtles. + + +Headings +~~~~~~~~ + +While ReST can accomodate a wide range of heading styles, we have standardized +on this convention in the User's Guide, + +.. code-block:: rest + + Header level 1 + ============== + + Header level 2 + -------------- + + Header level 3 + ~~~~~~~~~~~~~~ + + Header level 4 + ^^^^^^^^^^^^^^^ + + +Formatting code +~~~~~~~~~~~~~~~ + +Haskell +^^^^^^^ + +Code snippets can be included as both inline and block elements. Inline +code is denoted with double-backticks whereas block of code are introduced +by ending a paragraph with double-colons and indentation, + +.. code-block:: rest + + The ``fib`` function is defined as, :: + + fib :: Integer -> Integer + fib 1 = 1 + fib n = n * fib (n - 1) + +Which would be rendered as, + + The ``fib`` function is defined as, :: + + fib :: Integer -> Integer + fib 1 = 1 + fib n = n * fib (n - 1) + +Other languages +^^^^^^^^^^^^^^^ + +Double-colon blocks are syntax-highlighted as Haskell by default. To avoid this +use a +``.. code-block`` `directive +<http://sphinx-doc.org/markup/code.html#directive-code-block>`__ with explicit +language designation, + +.. code-block:: rest + + This is a simple shell script, + + .. code-block:: sh + + #!/bin/bash + echo "Hello World!" + + +Links +~~~~~ + +Within the Users Guide +^^^^^^^^^^^^^^^^^^^^^^ + +Frequently we want to give a name to a section so it can be referred to +from other points in the document, + +.. code-block:: rest + + .. _options-platform: + + Platform-specific Flags + ----------------------- + + There are lots of platform-specific flags. + + Some other section + ------------------- + + GHC supports a variety of :ref:`x86 specific features <options-platform>`. + + See :ref:`options-platform` for details. + + +To GHC Trac resources +^^^^^^^^^^^^^^^^^^^^^ + +There are special macros for conveniently linking to GHC Trac +Wiki articles and tickets, + +.. code-block:: rest + + See :ghc-wiki:`Commentary/Latedmd` for details on demand analysis. + + See the :ghc-wiki:`coding style <Commentary/CodingStyle>` for guidelines. + + See the :ghc-ticket:`123` for further discussion. + + See the :ghc-ticket:`this bug <123>` for what happens when this fails. + + +To external resources +^^^^^^^^^^^^^^^^^^^^^ + +External links can be written in either of these ways, + +.. code-block:: rest + + See the `GHC Wiki <http://ghc.haskell.org/wiki>`_ for details. + + See the `GHC Wiki`_ for details. + + .. _GHC Wiki: http://ghc.haskell.org/wiki + + +To core library Haddock documentation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It is often useful to be able to refer to the Haddock documention of the +libraries shipped with GHC. The users guide's build system provides +commands for referring to documentation for the following core GHC packages, + +* ``base``: ``:base-ref:`` +* ``cabal``: ``:cabal-ref:`` +* ``ghc-prim``: ``:ghc-prim-ref:`` + +For instance, + +.. code-block:: rest + + See the documentation for :base-ref:`Control.Applicative <Control-Applicative.html>` + for details. + + +Index entries +~~~~~~~~~~~~~ + +Index entries can be included anywhere in the document as a block element. +They look like, + +.. code-block:: rest + + Here is some discussion on the Strict Haskell extension. + + .. index:: + single: strict haskell + single: language extensions; StrictData + +This would produce two entries in the index referring to the "Strict Haskell" +section. One would be a simple "strict haskell" heading whereas the other would +be a "StrictData" subheading under "language extensions". + +Sadly it is not possible to use inline elements (e.g. monotype inlines) inside +index headings. + +Citations +--------- + +Citations can be marked-up like this, + +.. code-block:: rest + + See the original paper [Doe2008]_ + + .. [Doe2008] John Doe and Leslie Conway. + "This is the title of our paper" (2008) + + +Admonitions +----------- + +`Admonitions`_ are block elements used to draw the readers attention to a point. +They should not be over-used for the sake of readability but they can be quite +effective in separating and drawing attention to points of importance, + +.. code-block:: rest + + .. important:: + + Be friendly and supportive to your fellow contributors. + +Would be rendered as, + + .. important:: + + Be friendly and supportive to your fellow contributors. + +There are a number of admonitions types, + +.. hlist:: + + * attention + * caution + * danger + * error + * hint + * important + * note + * tip + * warning + + +.. _Admonitions: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions + +Style Conventions +----------------- + +When describing user commands and the like it is common to need to denote +user-substitutable tokens. In this document we use the convention, ``⟨subst⟩`` +(note that these are angle brackets, ``U+27E8`` and ``U+27E9``, not +less-than/greater-than signs). + + +.. _references: + +GHC command-line options reference +---------------------------------- + +The tabular nature of GHC flags reference (``flags.rst``) makes it very +difficult to maintain as ReST. For this reason it is generated by +``utils/mkUserGuidePart``. Any command-line options added to GHC should +be added to the appropriate file in ``utils/mkUserGuidePart/Options``. + + +ReST reference materials +------------------------ + +* `Sphinx ReST Primer`_: A great place to start. +* `Sphinx extensions`_: How Sphinx extends ReST +* `ReST reference`_: When you really need the details. +* `Directives reference`_ + +.. _Sphinx ReST Primer: http://sphinx-doc.org/rest.html +.. _ReST reference: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html +.. _Sphinx extensions: http://sphinx-doc.org/markup/index.html +.. _Directives reference: http://docutils.sourceforge.net/docs/ref/rst/directives.html#code diff --git a/docs/users_guide/extending_ghc.rst b/docs/users_guide/extending_ghc.rst new file mode 100644 index 0000000000..efe18b0a3f --- /dev/null +++ b/docs/users_guide/extending_ghc.rst @@ -0,0 +1,535 @@ +.. _extending-ghc: + +Extending and using GHC as a Library +==================================== + +GHC exposes its internal APIs to users through the built-in ghc package. +It allows you to write programs that leverage GHC's entire compilation +driver, in order to analyze or compile Haskell code programmatically. +Furthermore, GHC gives users the ability to load compiler plugins during +compilation - modules which are allowed to view and change GHC's +internal intermediate representation, Core. Plugins are suitable for +things like experimental optimizations or analysis, and offer a lower +barrier of entry to compiler development for many common cases. + +Furthermore, GHC offers a lightweight annotation mechanism that you can +use to annotate your source code with metadata, which you can later +inspect with either the compiler API or a compiler plugin. + +.. _annotation-pragmas: + +Source annotations +------------------ + +Annotations are small pragmas that allow you to attach data to +identifiers in source code, which are persisted when compiled. These +pieces of data can then inspected and utilized when using GHC as a +library or writing a compiler plugin. + +.. _ann-pragma: + +Annotating values +~~~~~~~~~~~~~~~~~ + +.. index:: + single: ANN pragma + single: pragma; ANN + single: source annotations + +Any expression that has both ``Typeable`` and ``Data`` instances may be +attached to a top-level value binding using an ``ANN`` pragma. In +particular, this means you can use ``ANN`` to annotate data constructors +(e.g. ``Just``) as well as normal values (e.g. ``take``). By way of +example, to annotate the function ``foo`` with the annotation +``Just "Hello"`` you would do this: + +:: + + {-# ANN foo (Just "Hello") #-} + foo = ... + +A number of restrictions apply to use of annotations: + +- The binder being annotated must be at the top level (i.e. no nested + binders) + +- The binder being annotated must be declared in the current module + +- The expression you are annotating with must have a type with + ``Typeable`` and ``Data`` instances + +- The `Template Haskell staging restrictions <>`__ apply to the + expression being annotated with, so for example you cannot run a + function from the module being compiled. + + To be precise, the annotation ``{-# ANN x e #-}`` is well staged if + and only if ``$(e)`` would be (disregarding the usual type + restrictions of the splice syntax, and the usual restriction on + splicing inside a splice - ``$([|1|])`` is fine as an annotation, + albeit redundant). + +If you feel strongly that any of these restrictions are too onerous, +:ghc-wiki:`please give the GHC team a shout <MailingListsAndIRC>`. + +However, apart from these restrictions, many things are allowed, +including expressions which are not fully evaluated! Annotation +expressions will be evaluated by the compiler just like Template Haskell +splices are. So, this annotation is fine: + +:: + + {-# ANN f SillyAnnotation { foo = (id 10) + $([| 20 |]), bar = 'f } #-} + f = ... + +.. _typeann-pragma: + +Annotating types +~~~~~~~~~~~~~~~~ + +.. index:: + single: ANN pragma; on types + +You can annotate types with the ``ANN`` pragma by using the ``type`` +keyword. For example: + +:: + + {-# ANN type Foo (Just "A `Maybe String' annotation") #-} + data Foo = ... + +.. _modann-pragma: + +Annotating modules +~~~~~~~~~~~~~~~~~~ + +.. index:: + single: ANN pragma; on modules + +You can annotate modules with the ``ANN`` pragma by using the ``module`` +keyword. For example: + +:: + + {-# ANN module (Just "A `Maybe String' annotation") #-} + +.. _ghc-as-a-library: + +Using GHC as a Library +---------------------- + +The ``ghc`` package exposes most of GHC's frontend to users, and thus +allows you to write programs that leverage it. This library is actually +the same library used by GHC's internal, frontend compilation driver, +and thus allows you to write tools that programmatically compile source +code and inspect it. Such functionality is useful in order to write +things like IDE or refactoring tools. As a simple example, here's a +program which compiles a module, much like ghc itself does by default +when invoked: + +:: + + import GHC + import GHC.Paths ( libdir ) + import DynFlags ( defaultLogAction ) + + main = + defaultErrorHandler defaultLogAction $ do + runGhc (Just libdir) $ do + dflags <- getSessionDynFlags + setSessionDynFlags dflags + target <- guessTarget "test_main.hs" Nothing + setTargets [target] + load LoadAllTargets + +The argument to ``runGhc`` is a bit tricky. GHC needs this to find its +libraries, so the argument must refer to the directory that is printed +by ``ghc --print-libdir`` for the same version of GHC that the program +is being compiled with. Above we therefore use the ``ghc-paths`` package +which provides this for us. + +Compiling it results in: + +:: + + $ cat test_main.hs + main = putStrLn "hi" + $ ghc -package ghc simple_ghc_api.hs + [1 of 1] Compiling Main ( simple_ghc_api.hs, simple_ghc_api.o ) + Linking simple_ghc_api ... + $ ./simple_ghc_api + $ ./test_main + hi + $ + +For more information on using the API, as well as more samples and +references, please see `this Haskell.org wiki +page <http://haskell.org/haskellwiki/GHC/As_a_library>`__. + +.. _compiler-plugins: + +Compiler Plugins +---------------- + +GHC has the ability to load compiler plugins at compile time. The +feature is similar to the one provided by +`GCC <http://gcc.gnu.org/wiki/plugins>`__, and allows users to write +plugins that can adjust the behaviour of the constraint solver, inspect +and modify the compilation pipeline, as well as transform and inspect +GHC's intermediate language, Core. Plugins are suitable for experimental +analysis or optimization, and require no changes to GHC's source code to +use. + +Plugins cannot optimize/inspect C--, nor can they implement things like +parser/front-end modifications like GCC, apart from limited changes to +the constraint solver. If you feel strongly that any of these +restrictions are too onerous, +:ghc-wiki:`please give the GHC team a shout <MailingListsAndIRC>`. + +.. _using-compiler-plugins: + +Using compiler plugins +~~~~~~~~~~~~~~~~~~~~~~ + +Plugins can be specified on the command line with the option +``-fplugin=module`` where ⟨module⟩ is a module in a registered package +that exports a plugin. Arguments can be given to plugins with the +command line option ``-fplugin-opt=module:args``, where ⟨args⟩ are +arguments interpreted by the plugin provided by ⟨module⟩. + +As an example, in order to load the plugin exported by ``Foo.Plugin`` in +the package ``foo-ghc-plugin``, and give it the parameter "baz", we +would invoke GHC like this: + +:: + + $ ghc -fplugin Foo.Plugin -fplugin-opt Foo.Plugin:baz Test.hs + [1 of 1] Compiling Main ( Test.hs, Test.o ) + Loading package ghc-prim ... linking ... done. + Loading package integer-gmp ... linking ... done. + Loading package base ... linking ... done. + Loading package ffi-1.0 ... linking ... done. + Loading package foo-ghc-plugin-0.1 ... linking ... done. + ... + Linking Test ... + $ + +Since plugins are exported by registered packages, it's safe to put +dependencies on them in cabal for example, and specify plugin arguments +to GHC through the ``ghc-options`` field. + +.. _writing-compiler-plugins: + +Writing compiler plugins +~~~~~~~~~~~~~~~~~~~~~~~~ + +Plugins are modules that export at least a single identifier, +``plugin``, of type ``GhcPlugins.Plugin``. All plugins should +``import GhcPlugins`` as it defines the interface to the compilation +pipeline. + +A ``Plugin`` effectively holds a function which installs a compilation +pass into the compiler pipeline. By default there is the empty plugin +which does nothing, ``GhcPlugins.defaultPlugin``, which you should +override with record syntax to specify your installation function. Since +the exact fields of the ``Plugin`` type are open to change, this is the +best way to ensure your plugins will continue to work in the future with +minimal interface impact. + +``Plugin`` exports a field, ``installCoreToDos`` which is a function of +type ``[CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo]``. A +``CommandLineOption`` is effectively just ``String``, and a ``CoreToDo`` +is basically a function of type ``Core -> Core``. A ``CoreToDo`` gives +your pass a name and runs it over every compiled module when you invoke +GHC. + +As a quick example, here is a simple plugin that just does nothing and +just returns the original compilation pipeline, unmodified, and says +'Hello': + +:: + + module DoNothing.Plugin (plugin) where + import GhcPlugins + + plugin :: Plugin + plugin = defaultPlugin { + installCoreToDos = install + } + + install :: [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo] + install _ todo = do + reinitializeGlobals + putMsgS "Hello!" + return todo + +Provided you compiled this plugin and registered it in a package (with +cabal for instance,) you can then use it by just specifying +``-fplugin=DoNothing.Plugin`` on the command line, and during the +compilation you should see GHC say 'Hello'. + +Note carefully the ``reinitializeGlobals`` call at the beginning of the +installation function. Due to bugs in the windows linker dealing with +``libghc``, this call is necessary to properly ensure compiler plugins +have the same global state as GHC at the time of invocation. Without +``reinitializeGlobals``, compiler plugins can crash at runtime because +they may require state that hasn't otherwise been initialized. + +In the future, when the linking bugs are fixed, ``reinitializeGlobals`` +will be deprecated with a warning, and changed to do nothing. + +.. _core-plugins-in-more-detail: + +Core plugins in more detail +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``CoreToDo`` is effectively a data type that describes all the kinds of +optimization passes GHC does on Core. There are passes for +simplification, CSE, vectorisation, etc. There is a specific case for +plugins, ``CoreDoPluginPass :: String -> PluginPass -> CoreToDo`` which +should be what you always use when inserting your own pass into the +pipeline. The first parameter is the name of the plugin, and the second +is the pass you wish to insert. + +``CoreM`` is a monad that all of the Core optimizations live and operate +inside of. + +A plugin's installation function (``install`` in the above example) +takes a list of ``CoreToDo``\ s and returns a list of ``CoreToDo``. +Before GHC begins compiling modules, it enumerates all the needed +plugins you tell it to load, and runs all of their installation +functions, initially on a list of passes that GHC specifies itself. +After doing this for every plugin, the final list of passes is given to +the optimizer, and are run by simply going over the list in order. + +You should be careful with your installation function, because the list +of passes you give back isn't questioned or double checked by GHC at the +time of this writing. An installation function like the following: + +:: + + install :: [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo] + install _ _ = return [] + +is certainly valid, but also certainly not what anyone really wants. + +.. _manipulating-bindings: + +Manipulating bindings +^^^^^^^^^^^^^^^^^^^^^ + +In the last section we saw that besides a name, a ``CoreDoPluginPass`` +takes a pass of type ``PluginPass``. A ``PluginPass`` is a synonym for +``(ModGuts -> CoreM ModGuts)``. ``ModGuts`` is a type that represents +the one module being compiled by GHC at any given time. + +A ``ModGuts`` holds all of the module's top level bindings which we can +examine. These bindings are of type ``CoreBind`` and effectively +represent the binding of a name to body of code. Top-level module +bindings are part of a ``ModGuts`` in the field ``mg_binds``. +Implementing a pass that manipulates the top level bindings merely needs +to iterate over this field, and return a new ``ModGuts`` with an updated +``mg_binds`` field. Because this is such a common case, there is a +function provided named ``bindsOnlyPass`` which lifts a function of type +``([CoreBind] -> CoreM [CoreBind])`` to type +``(ModGuts -> CoreM ModGuts)``. + +Continuing with our example from the last section, we can write a simple +plugin that just prints out the name of all the non-recursive bindings +in a module it compiles: + +:: + + module SayNames.Plugin (plugin) where + import GhcPlugins + + plugin :: Plugin + plugin = defaultPlugin { + installCoreToDos = install + } + + install :: [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo] + install _ todo = do + reinitializeGlobals + return (CoreDoPluginPass "Say name" pass : todo) + + pass :: ModGuts -> CoreM ModGuts + pass guts = do dflags <- getDynFlags + bindsOnlyPass (mapM (printBind dflags)) guts + where printBind :: DynFlags -> CoreBind -> CoreM CoreBind + printBind dflags bndr@(NonRec b _) = do + putMsgS $ "Non-recursive binding named " ++ showSDoc dflags (ppr b) + return bndr + printBind _ bndr = return bndr + +.. _getting-annotations: + +Using Annotations +^^^^^^^^^^^^^^^^^ + +Previously we discussed annotation pragmas (:ref:`annotation-pragmas`), +which we mentioned could be used to give compiler plugins extra guidance +or information. Annotations for a module can be retrieved by a plugin, +but you must go through the modules ``ModGuts`` in order to get it. +Because annotations can be arbitrary instances of ``Data`` and +``Typeable``, you need to give a type annotation specifying the proper +type of data to retrieve from the interface file, and you need to make +sure the annotation type used by your users is the same one your plugin +uses. For this reason, we advise distributing annotations as part of the +package which also provides compiler plugins if possible. + +To get the annotations of a single binder, you can use +``getAnnotations`` and specify the proper type. Here's an example that +will print out the name of any top-level non-recursive binding with the +``SomeAnn`` annotation: + +:: + + {-# LANGUAGE DeriveDataTypeable #-} + module SayAnnNames.Plugin (plugin, SomeAnn(..)) where + import GhcPlugins + import Control.Monad (unless) + import Data.Data + + data SomeAnn = SomeAnn deriving (Data, Typeable) + + plugin :: Plugin + plugin = defaultPlugin { + installCoreToDos = install + } + + install :: [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo] + install _ todo = do + reinitializeGlobals + return (CoreDoPluginPass "Say name" pass : todo) + + pass :: ModGuts -> CoreM ModGuts + pass g = do + dflags <- getDynFlags + mapM_ (printAnn dflags g) (mg_binds g) >> return g + where printAnn :: DynFlags -> ModGuts -> CoreBind -> CoreM CoreBind + printAnn dflags guts bndr@(NonRec b _) = do + anns <- annotationsOn guts b :: CoreM [SomeAnn] + unless (null anns) $ putMsgS $ "Annotated binding found: " ++ showSDoc dflags (ppr b) + return bndr + printAnn _ _ bndr = return bndr + + annotationsOn :: Data a => ModGuts -> CoreBndr -> CoreM [a] + annotationsOn guts bndr = do + anns <- getAnnotations deserializeWithData guts + return $ lookupWithDefaultUFM anns [] (varUnique bndr) + +Please see the GHC API documentation for more about how to use internal +APIs, etc. + +.. _typechecker-plugins: + +Typechecker plugins +~~~~~~~~~~~~~~~~~~~ + +In addition to Core plugins, GHC has experimental support for +typechecker plugins, which allow the behaviour of the constraint solver +to be modified. For example, they make it possible to interface the +compiler to an SMT solver, in order to support a richer theory of +type-level arithmetic expressions than the theory built into GHC (see +:ref:`typelit-tyfuns`). + +The ``Plugin`` type has a field ``tcPlugin`` of type +``[CommandLineOption] -> Maybe TcPlugin``, where the ``TcPlugin`` type +is defined thus: + +:: + + data TcPlugin = forall s . TcPlugin + { tcPluginInit :: TcPluginM s + , tcPluginSolve :: s -> TcPluginSolver + , tcPluginStop :: s -> TcPluginM () + } + + type TcPluginSolver = [Ct] -> [Ct] -> [Ct] -> TcPluginM TcPluginResult + + data TcPluginResult = TcPluginContradiction [Ct] | TcPluginOk [(EvTerm,Ct)] [Ct] + +(The details of this representation are subject to change as we gain +more experience writing typechecker plugins. It should not be assumed to +be stable between GHC releases.) + +The basic idea is as follows: + +- When type checking a module, GHC calls ``tcPluginInit`` once before + constraint solving starts. This allows the plugin to look things up + in the context, initialise mutable state or open a connection to an + external process (e.g. an external SMT solver). The plugin can return + a result of any type it likes, and the result will be passed to the + other two fields. + +- During constraint solving, GHC repeatedly calls ``tcPluginSolve``. + This function is provided with the current set of constraints, and + should return a ``TcPluginResult`` that indicates whether a + contradiction was found or progress was made. If the plugin solver + makes progress, GHC will re-start the constraint solving pipeline, + looping until a fixed point is reached. + +- Finally, GHC calls ``tcPluginStop`` after constraint solving is + finished, allowing the plugin to dispose of any resources it has + allocated (e.g. terminating the SMT solver process). + +Plugin code runs in the ``TcPluginM`` monad, which provides a restricted +interface to GHC API functionality that is relevant for typechecker +plugins, including ``IO`` and reading the environment. If you need +functionality that is not exposed in the ``TcPluginM`` module, you can +use ``unsafeTcPluginTcM :: TcM a -> TcPluginM a``, but are encouraged to +contact the GHC team to suggest additions to the interface. Note that +``TcPluginM`` can perform arbitrary IO via +``tcPluginIO :: IO a -> TcPluginM a``, although some care must be taken +with side effects (particularly in ``tcPluginSolve``). In general, it is +up to the plugin author to make sure that any IO they do is safe. + +.. _constraint-solving-with-plugins: + +Constraint solving with plugins +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The key component of a typechecker plugin is a function of type +``TcPluginSolver``, like this: + +:: + + solve :: [Ct] -> [Ct] -> [Ct] -> TcPluginM TcPluginResult + solve givens deriveds wanteds = ... + +This function will be invoked at two points in the constraint solving +process: after simplification of given constraints, and after +unflattening of wanted constraints. The two phases can be distinguished +because the deriveds and wanteds will be empty in the first case. In +each case, the plugin should either + +- return ``TcPluginContradiction`` with a list of impossible + constraints (which must be a subset of those passed in), so they can + be turned into errors; or + +- return ``TcPluginOk`` with lists of solved and new constraints (the + former must be a subset of those passed in and must be supplied with + corresponding evidence terms). + +If the plugin cannot make any progress, it should return +``TcPluginOk [] []``. Otherwise, if there were any new constraints, the +main constraint solver will be re-invoked to simplify them, then the +plugin will be invoked again. The plugin is responsible for making sure +that this process eventually terminates. + +Plugins are provided with all available constraints (including +equalities and typeclass constraints), but it is easy for them to +discard those that are not relevant to their domain, because they need +return only those constraints for which they have made progress (either +by solving or contradicting them). + +Constraints that have been solved by the plugin must be provided with +evidence in the form of an ``EvTerm`` of the type of the constraint. +This evidence is ignored for given and derived constraints, which GHC +"solves" simply by discarding them; typically this is used when they are +uninformative (e.g. reflexive equations). For wanted constraints, the +evidence will form part of the Core term that is generated after +typechecking, and can be checked by ``-dcore-lint``. It is possible for +the plugin to create equality axioms for use in evidence terms, but GHC +does not check their consistency, and inconsistent axiom sets may lead +to segfaults or other runtime misbehaviour. diff --git a/docs/users_guide/extending_ghc.xml b/docs/users_guide/extending_ghc.xml deleted file mode 100644 index c7b062b64d..0000000000 --- a/docs/users_guide/extending_ghc.xml +++ /dev/null @@ -1,350 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<chapter id="extending-ghc"> - <title>Extending and using GHC as a Library</title> - - <para>GHC exposes its internal APIs to users through the built-in ghc package. It allows you to write programs that leverage GHC's entire compilation driver, in order to analyze or compile Haskell code programmatically. Furthermore, GHC gives users the ability to load compiler plugins during compilation - modules which are allowed to view and change GHC's internal intermediate representation, Core. Plugins are suitable for things like experimental optimizations or analysis, and offer a lower barrier of entry to compiler development for many common cases.</para> - - <para>Furthermore, GHC offers a lightweight annotation mechanism that you can use to annotate your source code with metadata, which you can later inspect with either the compiler API or a compiler plugin.</para> - - <sect1 id="annotation-pragmas"> - <title>Source annotations</title> - - <para>Annotations are small pragmas that allow you to attach data to identifiers in source code, which are persisted when compiled. These pieces of data can then inspected and utilized when using GHC as a library or writing a compiler plugin.</para> - - <sect2 id="ann-pragma"> - <title>Annotating values</title> - - <indexterm><primary>ANN</primary></indexterm> - - <para>Any expression that has both <literal>Typeable</literal> and <literal>Data</literal> instances may be attached to a top-level value - binding using an <literal>ANN</literal> pragma. In particular, this means you can use <literal>ANN</literal> - to annotate data constructors (e.g. <literal>Just</literal>) as well as normal values (e.g. <literal>take</literal>). - By way of example, to annotate the function <literal>foo</literal> with the annotation <literal>Just "Hello"</literal> - you would do this:</para> - -<programlisting> -{-# ANN foo (Just "Hello") #-} -foo = ... -</programlisting> - - <para> - A number of restrictions apply to use of annotations: - <itemizedlist> - <listitem><para>The binder being annotated must be at the top level (i.e. no nested binders)</para></listitem> - <listitem><para>The binder being annotated must be declared in the current module</para></listitem> - <listitem><para>The expression you are annotating with must have a type with <literal>Typeable</literal> and <literal>Data</literal> instances</para></listitem> - <listitem><para>The <ulink linkend="using-template-haskell">Template Haskell staging restrictions</ulink> apply to the - expression being annotated with, so for example you cannot run a function from the module being compiled.</para> - - <para>To be precise, the annotation <literal>{-# ANN x e #-}</literal> is well staged if and only if <literal>$(e)</literal> would be - (disregarding the usual type restrictions of the splice syntax, and the usual restriction on splicing inside a splice - <literal>$([|1|])</literal> is fine as an annotation, albeit redundant).</para></listitem> - </itemizedlist> - - If you feel strongly that any of these restrictions are too onerous, <ulink url="http://ghc.haskell.org/trac/ghc/wiki/MailingListsAndIRC"> - please give the GHC team a shout</ulink>. - </para> - - <para>However, apart from these restrictions, many things are allowed, including expressions which are not fully evaluated! - Annotation expressions will be evaluated by the compiler just like Template Haskell splices are. So, this annotation is fine:</para> - -<programlisting> -{-# ANN f SillyAnnotation { foo = (id 10) + $([| 20 |]), bar = 'f } #-} -f = ... -</programlisting> - </sect2> - - <sect2 id="typeann-pragma"> - <title>Annotating types</title> - - <indexterm><primary>ANN type</primary></indexterm> - <indexterm><primary>ANN</primary></indexterm> - - <para>You can annotate types with the <literal>ANN</literal> pragma by using the <literal>type</literal> keyword. For example:</para> - -<programlisting> -{-# ANN type Foo (Just "A `Maybe String' annotation") #-} -data Foo = ... -</programlisting> - </sect2> - - <sect2 id="modann-pragma"> - <title>Annotating modules</title> - - <indexterm><primary>ANN module</primary></indexterm> - <indexterm><primary>ANN</primary></indexterm> - - <para>You can annotate modules with the <literal>ANN</literal> pragma by using the <literal>module</literal> keyword. For example:</para> - -<programlisting> -{-# ANN module (Just "A `Maybe String' annotation") #-} -</programlisting> - </sect2> - - </sect1> - - <sect1 id="ghc-as-a-library"> - <title>Using GHC as a Library</title> - - <para>The <literal>ghc</literal> package exposes most of GHC's frontend to users, and thus allows you to write programs that leverage it. This library is actually the same library used by GHC's internal, frontend compilation driver, and thus allows you to write tools that programmatically compile source code and inspect it. Such functionality is useful in order to write things like IDE or refactoring tools. As a simple example, here's a program which compiles a module, much like ghc itself does by default when invoked:</para> - -<programlisting> -import GHC -import GHC.Paths ( libdir ) -import DynFlags ( defaultLogAction ) - -main = - defaultErrorHandler defaultLogAction $ do - runGhc (Just libdir) $ do - dflags <- getSessionDynFlags - setSessionDynFlags dflags - target <- guessTarget "test_main.hs" Nothing - setTargets [target] - load LoadAllTargets -</programlisting> - - <para>The argument to <literal>runGhc</literal> is a bit tricky. GHC needs this to find its libraries, so the argument must refer to the directory that is printed by <literal>ghc --print-libdir</literal> for the same version of GHC that the program is being compiled with. Above we therefore use the <literal>ghc-paths</literal> package which provides this for us. </para> - - <para>Compiling it results in:</para> - -<programlisting> -$ cat test_main.hs -main = putStrLn "hi" -$ ghc -package ghc simple_ghc_api.hs -[1 of 1] Compiling Main ( simple_ghc_api.hs, simple_ghc_api.o ) -Linking simple_ghc_api ... -$ ./simple_ghc_api -$ ./test_main -hi -$ -</programlisting> - - <para>For more information on using the API, as well as more samples and references, please see <ulink url="http://haskell.org/haskellwiki/GHC/As_a_library">this Haskell.org wiki page</ulink>.</para> - </sect1> - - <sect1 id="compiler-plugins"> - <title>Compiler Plugins</title> - - <para>GHC has the ability to load compiler plugins at compile time. The feature is similar to the one provided by <ulink url="http://gcc.gnu.org/wiki/plugins">GCC</ulink>, and allows users to write plugins that can adjust the behaviour of the constraint solver, inspect and modify the compilation pipeline, as well as transform and inspect GHC's intermediate language, Core. Plugins are suitable for experimental analysis or optimization, and require no changes to GHC's source code to use.</para> - - <para>Plugins cannot optimize/inspect C--, nor can they implement things like parser/front-end modifications like GCC, apart from limited changes to the constraint solver. If you feel strongly that any of these restrictions are too onerous, <ulink url="http://ghc.haskell.org/trac/ghc/wiki/MailingListsAndIRC"> please give the GHC team a shout</ulink>.</para> - - <sect2 id="using-compiler-plugins"> - <title>Using compiler plugins</title> - - <para>Plugins can be specified on the command line with the option <literal>-fplugin=<replaceable>module</replaceable></literal> where <replaceable>module</replaceable> is a module in a registered package that exports a plugin. Arguments can be given to plugins with the command line option <literal>-fplugin-opt=<replaceable>module</replaceable>:<replaceable>args</replaceable></literal>, where <replaceable>args</replaceable> are arguments interpreted by the plugin provided by <replaceable>module</replaceable>.</para> - - <para>As an example, in order to load the plugin exported by <literal>Foo.Plugin</literal> in the package <literal>foo-ghc-plugin</literal>, and give it the parameter "baz", we would invoke GHC like this:</para> - -<programlisting> -$ ghc -fplugin Foo.Plugin -fplugin-opt Foo.Plugin:baz Test.hs -[1 of 1] Compiling Main ( Test.hs, Test.o ) -Loading package ghc-prim ... linking ... done. -Loading package integer-gmp ... linking ... done. -Loading package base ... linking ... done. -Loading package ffi-1.0 ... linking ... done. -Loading package foo-ghc-plugin-0.1 ... linking ... done. -... -Linking Test ... -$ -</programlisting> - - <para>Since plugins are exported by registered packages, it's safe to put dependencies on them in cabal for example, and specify plugin arguments to GHC through the <literal>ghc-options</literal> field.</para> - </sect2> - - <sect2 id="writing-compiler-plugins"> - <title>Writing compiler plugins</title> - - <para>Plugins are modules that export at least a single identifier, <literal>plugin</literal>, of type <literal>GhcPlugins.Plugin</literal>. All plugins should <literal>import GhcPlugins</literal> as it defines the interface to the compilation pipeline.</para> - - <para>A <literal>Plugin</literal> effectively holds a function which installs a compilation pass into the compiler pipeline. By default there is the empty plugin which does nothing, <literal>GhcPlugins.defaultPlugin</literal>, which you should override with record syntax to specify your installation function. Since the exact fields of the <literal>Plugin</literal> type are open to change, this is the best way to ensure your plugins will continue to work in the future with minimal interface impact.</para> - - <para><literal>Plugin</literal> exports a field, <literal>installCoreToDos</literal> which is a function of type <literal>[CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo]</literal>. A <literal>CommandLineOption</literal> is effectively just <literal>String</literal>, and a <literal>CoreToDo</literal> is basically a function of type <literal>Core -> Core</literal>. A <literal>CoreToDo</literal> gives your pass a name and runs it over every compiled module when you invoke GHC.</para> - - <para>As a quick example, here is a simple plugin that just does nothing and just returns the original compilation pipeline, unmodified, and says 'Hello':</para> - -<programlisting> -module DoNothing.Plugin (plugin) where -import GhcPlugins - -plugin :: Plugin -plugin = defaultPlugin { - installCoreToDos = install - } - -install :: [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo] -install _ todo = do - reinitializeGlobals - putMsgS "Hello!" - return todo -</programlisting> - - <para>Provided you compiled this plugin and registered it in a package (with cabal for instance,) you can then use it by just specifying <literal>-fplugin=DoNothing.Plugin</literal> on the command line, and during the compilation you should see GHC say 'Hello'.</para> - - <para>Note carefully the <literal>reinitializeGlobals</literal> call at the beginning of the installation function. Due to bugs in the windows linker dealing with <literal>libghc</literal>, this call is necessary to properly ensure compiler plugins have the same global state as GHC at the time of invocation. Without <literal>reinitializeGlobals</literal>, compiler plugins can crash at runtime because they may require state that hasn't otherwise been initialized.</para> - - <para>In the future, when the linking bugs are fixed, <literal>reinitializeGlobals</literal> will be deprecated with a warning, and changed to do nothing.</para> - </sect2> - - <sect2 id="core-plugins-in-more-detail"> - <title>Core plugins in more detail</title> - - <para><literal>CoreToDo</literal> is effectively a data type that describes all the kinds of optimization passes GHC does on Core. There are passes for simplification, CSE, vectorisation, etc. There is a specific case for plugins, <literal>CoreDoPluginPass :: String -> PluginPass -> CoreToDo</literal> which should be what you always use when inserting your own pass into the pipeline. The first parameter is the name of the plugin, and the second is the pass you wish to insert.</para> - - <para><literal>CoreM</literal> is a monad that all of the Core optimizations live and operate inside of.</para> - - <para>A plugin's installation function (<literal>install</literal> in the above example) takes a list of <literal>CoreToDo</literal>s and returns a list of <literal>CoreToDo</literal>. Before GHC begins compiling modules, it enumerates all the needed plugins you tell it to load, and runs all of their installation functions, initially on a list of passes that GHC specifies itself. After doing this for every plugin, the final list of passes is given to the optimizer, and are run by simply going over the list in order.</para> - - <para>You should be careful with your installation function, because the list of passes you give back isn't questioned or double checked by GHC at the time of this writing. An installation function like the following:</para> - -<programlisting> -install :: [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo] -install _ _ = return [] -</programlisting> - - <para>is certainly valid, but also certainly not what anyone really wants.</para> - - <sect3 id="manipulating-bindings"> - <title>Manipulating bindings</title> - - <para>In the last section we saw that besides a name, a <literal>CoreDoPluginPass</literal> takes a pass of type <literal>PluginPass</literal>. A <literal>PluginPass</literal> is a synonym for <literal>(ModGuts -> CoreM ModGuts)</literal>. <literal>ModGuts</literal> is a type that represents the one module being compiled by GHC at any given time.</para> - - <para>A <literal>ModGuts</literal> holds all of the module's top level bindings which we can examine. These bindings are of type <literal>CoreBind</literal> and effectively represent the binding of a name to body of code. Top-level module bindings are part of a <literal>ModGuts</literal> in the field <literal>mg_binds</literal>. Implementing a pass that manipulates the top level bindings merely needs to iterate over this field, and return a new <literal>ModGuts</literal> with an updated <literal>mg_binds</literal> field. Because this is such a common case, there is a function provided named <literal>bindsOnlyPass</literal> which lifts a function of type <literal>([CoreBind] -> CoreM [CoreBind])</literal> to type <literal>(ModGuts -> CoreM ModGuts)</literal>. </para> - - <para>Continuing with our example from the last section, we can write a simple plugin that just prints out the name of all the non-recursive bindings in a module it compiles:</para> - -<programlisting> -module SayNames.Plugin (plugin) where -import GhcPlugins - -plugin :: Plugin -plugin = defaultPlugin { - installCoreToDos = install - } - -install :: [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo] -install _ todo = do - reinitializeGlobals - return (CoreDoPluginPass "Say name" pass : todo) - -pass :: ModGuts -> CoreM ModGuts -pass guts = do dflags <- getDynFlags - bindsOnlyPass (mapM (printBind dflags)) guts - where printBind :: DynFlags -> CoreBind -> CoreM CoreBind - printBind dflags bndr@(NonRec b _) = do - putMsgS $ "Non-recursive binding named " ++ showSDoc dflags (ppr b) - return bndr - printBind _ bndr = return bndr -</programlisting> - </sect3> - - <sect3 id="getting-annotations"> - <title>Using Annotations</title> - - <para>Previously we discussed annotation pragmas (<xref linkend="annotation-pragmas"/>), which we mentioned could be used to give compiler plugins extra guidance or information. Annotations for a module can be retrieved by a plugin, but you must go through the modules <literal>ModGuts</literal> in order to get it. Because annotations can be arbitrary instances of <literal>Data</literal> and <literal>Typeable</literal>, you need to give a type annotation specifying the proper type of data to retrieve from the interface file, and you need to make sure the annotation type used by your users is the same one your plugin uses. For this reason, we advise distributing annotations as part of the package which also provides compiler plugins if possible.</para> - - <para>To get the annotations of a single binder, you can use `getAnnotations` and specify the proper type. Here's an example that will print out the name of any top-level non-recursive binding with the <literal>SomeAnn</literal> annotation:</para> - -<programlisting> -{-# LANGUAGE DeriveDataTypeable #-} -module SayAnnNames.Plugin (plugin, SomeAnn(..)) where -import GhcPlugins -import Control.Monad (unless) -import Data.Data - -data SomeAnn = SomeAnn deriving (Data, Typeable) - -plugin :: Plugin -plugin = defaultPlugin { - installCoreToDos = install - } - -install :: [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo] -install _ todo = do - reinitializeGlobals - return (CoreDoPluginPass "Say name" pass : todo) - -pass :: ModGuts -> CoreM ModGuts -pass g = do - dflags <- getDynFlags - mapM_ (printAnn dflags g) (mg_binds g) >> return g - where printAnn :: DynFlags -> ModGuts -> CoreBind -> CoreM CoreBind - printAnn dflags guts bndr@(NonRec b _) = do - anns <- annotationsOn guts b :: CoreM [SomeAnn] - unless (null anns) $ putMsgS $ "Annotated binding found: " ++ showSDoc dflags (ppr b) - return bndr - printAnn _ _ bndr = return bndr - -annotationsOn :: Data a => ModGuts -> CoreBndr -> CoreM [a] -annotationsOn guts bndr = do - anns <- getAnnotations deserializeWithData guts - return $ lookupWithDefaultUFM anns [] (varUnique bndr) -</programlisting> - - <para>Please see the GHC API documentation for more about how to use internal APIs, etc.</para> - </sect3> - </sect2> - - <sect2 id="typechecker-plugins"> - <title>Typechecker plugins</title> - - <para>In addition to Core plugins, GHC has experimental support for typechecker plugins, which allow the behaviour of the constraint solver to be modified. For example, they make it possible to interface the compiler to an SMT solver, in order to support a richer theory of type-level arithmetic expressions than the theory built into GHC (see <xref linkend="typelit-tyfuns"/>).</para> - - <para>The <literal>Plugin</literal> type has a field <literal>tcPlugin</literal> of type <literal>[CommandLineOption] -> Maybe TcPlugin</literal>, where the <literal>TcPlugin</literal> type is defined thus:</para> - -<programlisting> -data TcPlugin = forall s . TcPlugin - { tcPluginInit :: TcPluginM s - , tcPluginSolve :: s -> TcPluginSolver - , tcPluginStop :: s -> TcPluginM () - } - -type TcPluginSolver = [Ct] -> [Ct] -> [Ct] -> TcPluginM TcPluginResult - -data TcPluginResult = TcPluginContradiction [Ct] | TcPluginOk [(EvTerm,Ct)] [Ct] -</programlisting> - - <para>(The details of this representation are subject to change as we gain more experience writing typechecker plugins. It should not be assumed to be stable between GHC releases.)</para> - - <para>The basic idea is as follows: - <itemizedlist> - <listitem><para>When type checking a module, GHC calls <literal>tcPluginInit</literal> once before constraint solving starts. This allows the plugin to look things up in the context, initialise mutable state or open a connection to an external process (e.g. an external SMT solver). The plugin can return a result of any type it likes, and the result will be passed to the other two fields.</para></listitem> - <listitem><para>During constraint solving, GHC repeatedly calls <literal>tcPluginSolve</literal>. This function is provided with the current set of constraints, and should return a <literal>TcPluginResult</literal> that indicates whether a contradiction was found or progress was made. If the plugin solver makes progress, GHC will re-start the constraint solving pipeline, looping until a fixed point is reached.</para></listitem> - <listitem><para>Finally, GHC calls <literal>tcPluginStop</literal> after constraint solving is finished, allowing the plugin to dispose of any resources it has allocated (e.g. terminating the SMT solver process).</para></listitem> - </itemizedlist> - </para> - - <para>Plugin code runs in the <literal>TcPluginM</literal> monad, which provides a restricted interface to GHC API functionality that is relevant for typechecker plugins, including <literal>IO</literal> and reading the environment. If you need functionality that is not exposed in the <literal>TcPluginM</literal> module, you can use <literal>unsafeTcPluginTcM :: TcM a -> TcPluginM a</literal>, but are encouraged to contact the GHC team to suggest additions to the interface. Note that <literal>TcPluginM</literal> can perform arbitrary IO via <literal>tcPluginIO :: IO a -> TcPluginM a</literal>, although some care must be taken with side effects (particularly in <literal>tcPluginSolve</literal>). In general, it is up to the plugin author to make sure that any IO they do is safe.</para> - - <sect3 id="constraint-solving-with-plugins"> - - <title>Constraint solving with plugins</title> - - <para>The key component of a typechecker plugin is a function of type <literal>TcPluginSolver</literal>, like this:</para> - -<programlisting> -solve :: [Ct] -> [Ct] -> [Ct] -> TcPluginM TcPluginResult -solve givens deriveds wanteds = ... -</programlisting> - - <para>This function will be invoked at two points in the constraint solving process: after simplification of given constraints, and after unflattening of wanted constraints. The two phases can be distinguished because the deriveds and wanteds will be empty in the first case. In each case, the plugin should either - <itemizedlist> - <listitem><para>return <literal>TcPluginContradiction</literal> with a list of impossible constraints (which must be a subset of those passed in), so they can be turned into errors; or</para></listitem> - <listitem><para>return <literal>TcPluginOk</literal> with lists of solved and new constraints (the former must be a subset of those passed in and must be supplied with corresponding evidence terms).</para></listitem> - </itemizedlist> - If the plugin cannot make any progress, it should return <literal>TcPluginOk [] []</literal>. Otherwise, if there were any new constraints, the main constraint solver will be re-invoked to simplify them, then the plugin will be invoked again. The plugin is responsible for making sure that this process eventually terminates.</para> - - <para>Plugins are provided with all available constraints (including equalities and typeclass constraints), but it is easy for them to discard those that are not relevant to their domain, because they need return only those constraints for which they have made progress (either by solving or contradicting them).</para> - - <para>Constraints that have been solved by the plugin must be provided with evidence in the form of an <literal>EvTerm</literal> of the type of the constraint. This evidence is ignored for given and derived constraints, which GHC "solves" simply by discarding them; typically this is used when they are uninformative (e.g. reflexive equations). For wanted constraints, the evidence will form part of the Core term that is generated after typechecking, and can be checked by <option>-dcore-lint</option>. It is possible for the plugin to create equality axioms for use in evidence terms, but GHC does not check their consistency, and inconsistent axiom sets may lead to segfaults or other runtime misbehaviour.</para> - </sect3> - </sect2> - </sect1> - -</chapter> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> diff --git a/docs/users_guide/ffi-chap.rst b/docs/users_guide/ffi-chap.rst new file mode 100644 index 0000000000..f9ebe5ae6e --- /dev/null +++ b/docs/users_guide/ffi-chap.rst @@ -0,0 +1,658 @@ +.. _ffi: + +Foreign function interface (FFI) +================================ + +.. index:: + single: -XForeignFunctionInterface + single: Foreign function interface + single: interfacing with native code + +GHC (mostly) conforms to the Haskell Foreign Function Interface, whose +definition is part of the Haskell Report on +```http://www.haskell.org/`` <http://www.haskell.org/>`__. + +FFI support is enabled by default, but can be enabled or disabled +explicitly with the ``-XForeignFunctionInterface`` flag. + +GHC implements a number of GHC-specific extensions to the FFI Addendum. +These extensions are described in :ref:`ffi-ghcexts`, but please note +that programs using these features are not portable. Hence, these +features should be avoided where possible. + +The FFI libraries are documented in the accompanying library +documentation; see for example the :base-ref:`Foreign` module. + +.. _ffi-ghcexts: + +GHC extensions to the FFI Addendum +---------------------------------- + +The FFI features that are described in this section are specific to GHC. +Your code will not be portable to other compilers if you use them. + +Unboxed types +~~~~~~~~~~~~~ + +The following unboxed types may be used as basic foreign types (see FFI +Addendum, Section 3.2): ``Int#``, ``Word#``, ``Char#``, ``Float#``, +``Double#``, ``Addr#``, ``StablePtr# a``, ``MutableByteArray#``, +``ForeignObj#``, and ``ByteArray#``. + +.. _ffi-newtype-io: + +Newtype wrapping of the IO monad +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The FFI spec requires the IO monad to appear in various places, but it +can sometimes be convenient to wrap the IO monad in a ``newtype``, thus: + +:: + + newtype MyIO a = MIO (IO a) + +(A reason for doing so might be to prevent the programmer from calling +arbitrary IO procedures in some part of the program.) + +The Haskell FFI already specifies that arguments and results of foreign +imports and exports will be automatically unwrapped if they are newtypes +(Section 3.2 of the FFI addendum). GHC extends the FFI by automatically +unwrapping any newtypes that wrap the IO monad itself. More precisely, +wherever the FFI specification requires an ``IO`` type, GHC will accept any +newtype-wrapping of an ``IO`` type. For example, these declarations are OK: + +:: + + foreign import foo :: Int -> MyIO Int + foreign import "dynamic" baz :: (Int -> MyIO Int) -> CInt -> MyIO Int + +.. _ffi-prim: + +Primitive imports +~~~~~~~~~~~~~~~~~ + +GHC extends the FFI with an additional calling convention ``prim``, +e.g.: + +:: + + foreign import prim "foo" foo :: ByteArray# -> (# Int#, Int# #) + +This is used to import functions written in Cmm code that follow an +internal GHC calling convention. The arguments and results must be +unboxed types, except that an argument may be of type ``Any`` (by way of +``unsafeCoerce#``) and the result type is allowed to be an unboxed tuple +or the type ``Any``. + +This feature is not intended for use outside of the core libraries that +come with GHC. For more details see the +:ghc-wiki:`GHC developer wiki <Commentary/PrimOps>`. + +.. _ffi-interruptible: + +Interruptible foreign calls +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This concerns the interaction of foreign calls with +``Control.Concurrent.throwTo``. Normally when the target of a +``throwTo`` is involved in a foreign call, the exception is not raised +until the call returns, and in the meantime the caller is blocked. This +can result in unresponsiveness, which is particularly undesirable in the +case of user interrupt (e.g. Control-C). The default behaviour when a +Control-C signal is received (``SIGINT`` on Unix) is to raise the +``UserInterrupt`` exception in the main thread; if the main thread is +blocked in a foreign call at the time, then the program will not respond +to the user interrupt. + +The problem is that it is not possible in general to interrupt a foreign +call safely. However, GHC does provide a way to interrupt blocking +system calls which works for most system calls on both Unix and Windows. +When the ``InterruptibleFFI`` extension is enabled, a foreign call can +be annotated with ``interruptible`` instead of ``safe`` or ``unsafe``: + +:: + + foreign import ccall interruptible + "sleep" sleepBlock :: CUint -> IO CUint + +``interruptible`` behaves exactly as ``safe``, except that when a +``throwTo`` is directed at a thread in an interruptible foreign call, an +OS-specific mechanism will be used to attempt to cause the foreign call +to return: + +Unix systems + The thread making the foreign call is sent a ``SIGPIPE`` signal + using ``pthread_kill()``. This is usually enough to cause a blocking + system call to return with ``EINTR`` (GHC by default installs an + empty signal handler for ``SIGPIPE``, to override the default + behaviour which is to terminate the process immediately). + +Windows systems + [Vista and later only] The RTS calls the Win32 function + ``CancelSynchronousIO``, which will cause a blocking I/O operation + to return with the error ``ERROR_OPERATION_ABORTED``. + +If the system call is successfully interrupted, it will return to +Haskell whereupon the exception can be raised. Be especially careful +when using ``interruptible`` that the caller of the foreign function is +prepared to deal with the consequences of the call being interrupted; on +Unix it is good practice to check for ``EINTR`` always, but on Windows +it is not typically necessary to handle ``ERROR_OPERATION_ABORTED``. + +.. _ffi-capi: + +The CAPI calling convention +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``CApiFFI`` extension allows a calling convention of ``capi`` to be +used in foreign declarations, e.g. + +:: + + foreign import capi "header.h f" f :: CInt -> IO CInt + +Rather than generating code to call ``f`` according to the platform's +ABI, we instead call ``f`` using the C API defined in the header +``header.h``. Thus ``f`` can be called even if it may be defined as a +CPP ``#define`` rather than a proper function. + +When using ``capi``, it is also possible to import values, rather than +functions. For example, + +:: + + foreign import capi "pi.h value pi" c_pi :: CDouble + +will work regardless of whether ``pi`` is defined as + +:: + + const double pi = 3.14; + +or with + +:: + + #define pi 3.14 + +In order to tell GHC the C type that a Haskell type corresponds to when +it is used with the CAPI, a ``CTYPE`` pragma can be used on the type +definition. The header which defines the type can optionally also be +specified. The syntax looks like: + +:: + + data {-# CTYPE "unistd.h" "useconds_t" #-} T = ... + newtype {-# CTYPE "useconds_t" #-} T = ... + +``hs_thread_done()`` +~~~~~~~~~~~~~~~~~~~~ + +:: + + void hs_thread_done(void); + +GHC allocates a small amount of thread-local memory when a thread calls +a Haskell function via a ``foreign export``. This memory is not normally +freed until ``hs_exit()``; the memory is cached so that subsequent calls +into Haskell are fast. However, if your application is long-running and +repeatedly creates new threads that call into Haskell, you probably want +to arrange that this memory is freed in those threads that have finished +calling Haskell functions. To do this, call ``hs_thread_done()`` from +the thread whose memory you want to free. + +Calling ``hs_thread_done()`` is entirely optional. You can call it as +often or as little as you like. It is safe to call it from a thread that +has never called any Haskell functions, or one that never will. If you +forget to call it, the worst that can happen is that some memory remains +allocated until ``hs_exit()`` is called. If you call it too often, the +worst that can happen is that the next call to a Haskell function incurs +some extra overhead. + +.. _ffi-ghc: + +Using the FFI with GHC +---------------------- + +The following sections also give some hints and tips on the use of the +foreign function interface in GHC. + +.. _foreign-export-ghc: + +Using ``foreign export`` and ``foreign import ccall "wrapper"`` with GHC +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: foreign export; with GHC + +When GHC compiles a module (say ``M.hs``) which uses ``foreign export`` +or ``foreign import "wrapper"``, it generates a ``M_stub.h`` for use by +C programs. + +For a plain ``foreign export``, the file ``M_stub.h`` contains a C +prototype for the foreign exported function. For example, if we compile +the following module: + +:: + + module Foo where + + foreign export ccall foo :: Int -> IO Int + + foo :: Int -> IO Int + foo n = return (length (f n)) + + f :: Int -> [Int] + f 0 = [] + f n = n:(f (n-1)) + +Then ``Foo_stub.h`` will contain something like this: + +:: + + #include "HsFFI.h" + extern HsInt foo(HsInt a0); + +To invoke ``foo()`` from C, just ``#include "Foo_stub.h"`` and call +``foo()``. + +The ``Foo_stub.h`` file can be redirected using the ``-stubdir`` option; +see :ref:`options-output`. + +.. _using-own-main: + +Using your own ``main()`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Normally, GHC's runtime system provides a ``main()``, which arranges to +invoke ``Main.main`` in the Haskell program. However, you might want to +link some Haskell code into a program which has a main function written +in another language, say C. In order to do this, you have to initialize +the Haskell runtime system explicitly. + +Let's take the example from above, and invoke it from a standalone C +program. Here's the C code: + +:: + + #include <stdio.h> + #include "HsFFI.h" + + #ifdef __GLASGOW_HASKELL__ + #include "Foo_stub.h" + #endif + + int main(int argc, char *argv[]) + { + int i; + + hs_init(&argc, &argv); + + for (i = 0; i < 5; i++) { + printf("%d\n", foo(2500)); + } + + hs_exit(); + return 0; + } + +We've surrounded the GHC-specific bits with +``#ifdef __GLASGOW_HASKELL__``; the rest of the code should be portable +across Haskell implementations that support the FFI standard. + +The call to ``hs_init()`` initializes GHC's runtime system. Do NOT try +to invoke any Haskell functions before calling ``hs_init()``: bad things +will undoubtedly happen. + +We pass references to ``argc`` and ``argv`` to ``hs_init()`` so that it +can separate out any arguments for the RTS (i.e. those arguments between +``+RTS...-RTS``). + +After we've finished invoking our Haskell functions, we can call +``hs_exit()``, which terminates the RTS. + +There can be multiple calls to ``hs_init()``, but each one should be +matched by one (and only one) call to ``hs_exit()`` [1]_. + +.. note:: + When linking the final program, it is normally easiest to do the + link using GHC, although this isn't essential. If you do use GHC, then + don't forget the flag ``-no-hs-main``\ ``-no-hs-main``, otherwise GHC + will try to link to the ``Main`` Haskell module. + +.. [1] + The outermost ``hs_exit()`` will actually de-initialise the system. + NOTE that currently GHC's runtime cannot reliably re-initialise after + this has happened, see :ref:`infelicities-ffi`. + +To use ``+RTS`` flags with ``hs_init()``, we have to modify the example +slightly. By default, GHC's RTS will only accept "safe" ``+RTS`` flags +(see :ref:`options-linker`), and the ``-rtsopts``\ ``-rtsopts`` +link-time flag overrides this. However, ``-rtsopts`` has no effect when +``-no-hs-main`` is in use (and the same goes for ``-with-rtsopts``). To +set these options we have to call a GHC-specific API instead of +``hs_init()``: + +:: + + #include <stdio.h> + #include "HsFFI.h" + + #ifdef __GLASGOW_HASKELL__ + #include "Foo_stub.h" + #include "Rts.h" + #endif + + int main(int argc, char *argv[]) + { + int i; + + #if __GLASGOW_HASKELL__ >= 703 + { + RtsConfig conf = defaultRtsConfig; + conf.rts_opts_enabled = RtsOptsAll; + hs_init_ghc(&argc, &argv, conf); + } + #else + hs_init(&argc, &argv); + #endif + + for (i = 0; i < 5; i++) { + printf("%d\n", foo(2500)); + } + + hs_exit(); + return 0; + } + +Note two changes: we included ``Rts.h``, which defines the GHC-specific +external RTS interface, and we called ``hs_init_ghc()`` instead of +``hs_init()``, passing an argument of type ``RtsConfig``. ``RtsConfig`` +is a struct with various fields that affect the behaviour of the runtime +system. Its definition is: + +:: + + typedef struct { + RtsOptsEnabledEnum rts_opts_enabled; + const char *rts_opts; + } RtsConfig; + + extern const RtsConfig defaultRtsConfig; + + typedef enum { + RtsOptsNone, // +RTS causes an error + RtsOptsSafeOnly, // safe RTS options allowed; others cause an error + RtsOptsAll // all RTS options allowed + } RtsOptsEnabledEnum; + +There is a default value ``defaultRtsConfig`` that should be used to +initialise variables of type ``RtsConfig``. More fields will undoubtedly +be added to ``RtsConfig`` in the future, so in order to keep your code +forwards-compatible it is best to initialise with ``defaultRtsConfig`` +and then modify the required fields, as in the code sample above. + +.. _ffi-library: + +Making a Haskell library that can be called from foreign code +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The scenario here is much like in :ref:`using-own-main`, except that the +aim is not to link a complete program, but to make a library from +Haskell code that can be deployed in the same way that you would deploy +a library of C code. + +The main requirement here is that the runtime needs to be initialized +before any Haskell code can be called, so your library should provide +initialisation and deinitialisation entry points, implemented in C or +C++. For example: + +:: + + #include <stdlib.h> + #include "HsFFI.h" + + HsBool mylib_init(void){ + int argc = 2; + char *argv[] = { "+RTS", "-A32m", NULL }; + char **pargv = argv; + + // Initialize Haskell runtime + hs_init(&argc, &pargv); + + // do any other initialization here and + // return false if there was a problem + return HS_BOOL_TRUE; + } + + void mylib_end(void){ + hs_exit(); + } + +The initialisation routine, ``mylib_init``, calls ``hs_init()`` as +normal to initialise the Haskell runtime, and the corresponding +deinitialisation function ``mylib_end()`` calls ``hs_exit()`` to shut +down the runtime. + +.. _glasgow-foreign-headers: + +Using header files +~~~~~~~~~~~~~~~~~~ + +.. index:: + single: C calls, function headers + +C functions are normally declared using prototypes in a C header file. +Earlier versions of GHC (6.8.3 and earlier) ``#include``\ d the header +file in the C source file generated from the Haskell code, and the C +compiler could therefore check that the C function being called via the +FFI was being called at the right type. + +GHC no longer includes external header files when compiling via C, so +this checking is not performed. The change was made for compatibility +with the :ref:`native code generator <native-code-gen>` (``-fasm``) and to +comply strictly with the FFI specification, which requires that FFI calls are +not subject to macro expansion and other CPP conversions that may be applied +when using C header files. This approach also simplifies the inlining of foreign +calls across module and package boundaries: there's no need for the header file +to be available when compiling an inlined version of a foreign call, so the +compiler is free to inline foreign calls in any context. + +The ``-#include`` option is now deprecated, and the ``include-files`` +field in a Cabal package specification is ignored. + +Memory Allocation +~~~~~~~~~~~~~~~~~ + +The FFI libraries provide several ways to allocate memory for use with +the FFI, and it isn't always clear which way is the best. This decision +may be affected by how efficient a particular kind of allocation is on a +given compiler/platform, so this section aims to shed some light on how +the different kinds of allocation perform with GHC. + +``alloca`` + Useful for short-term allocation when the allocation is intended to + scope over a given ``IO`` computation. This kind of allocation is + commonly used when marshalling data to and from FFI functions. + + In GHC, ``alloca`` is implemented using ``MutableByteArray#``, so + allocation and deallocation are fast: much faster than C's + ``malloc/free``, but not quite as fast as stack allocation in C. Use + ``alloca`` whenever you can. + +``mallocForeignPtr`` + Useful for longer-term allocation which requires garbage collection. + If you intend to store the pointer to the memory in a foreign data + structure, then ``mallocForeignPtr`` is *not* a good choice, + however. + + In GHC, ``mallocForeignPtr`` is also implemented using + ``MutableByteArray#``. Although the memory is pointed to by a + ``ForeignPtr``, there are no actual finalizers involved (unless you + add one with ``addForeignPtrFinalizer``), and the deallocation is + done using GC, so ``mallocForeignPtr`` is normally very cheap. + +``malloc/free`` + If all else fails, then you need to resort to ``Foreign.malloc`` and + ``Foreign.free``. These are just wrappers around the C functions of + the same name, and their efficiency will depend ultimately on the + implementations of these functions in your platform's C library. We + usually find ``malloc`` and ``free`` to be significantly slower than + the other forms of allocation above. + +``Foreign.Marshal.Pool`` + Pools are currently implemented using ``malloc/free``, so while they + might be a more convenient way to structure your memory allocation + than using one of the other forms of allocation, they won't be any + more efficient. We do plan to provide an improved-performance + implementation of Pools in the future, however. + +.. _ffi-threads: + +Multi-threading and the FFI +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In order to use the FFI in a multi-threaded setting, you must use the +``-threaded`` option (see :ref:`options-linker`). + +Foreign imports and multi-threading +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When you call a ``foreign import``\ ed function that is annotated as +``safe`` (the default), and the program was linked using ``-threaded``, +then the call will run concurrently with other running Haskell threads. +If the program was linked without ``-threaded``, then the other Haskell +threads will be blocked until the call returns. + +This means that if you need to make a foreign call to a function that +takes a long time or blocks indefinitely, then you should mark it +``safe`` and use ``-threaded``. Some library functions make such calls +internally; their documentation should indicate when this is the case. + +If you are making foreign calls from multiple Haskell threads and using +``-threaded``, make sure that the foreign code you are calling is +thread-safe. In particularly, some GUI libraries are not thread-safe and +require that the caller only invokes GUI methods from a single thread. +If this is the case, you may need to restrict your GUI operations to a +single Haskell thread, and possibly also use a bound thread (see +:ref:`haskell-threads-and-os-threads`). + +Note that foreign calls made by different Haskell threads may execute in +*parallel*, even when the ``+RTS -N`` flag is not being used +(:ref:`parallel-options`). The ``+RTS -N`` flag controls parallel +execution of Haskell threads, but there may be an arbitrary number of +foreign calls in progress at any one time, regardless of the ``+RTS -N`` +value. + +If a call is annotated as ``interruptible`` and the program was +multithreaded, the call may be interrupted in the event that the Haskell +thread receives an exception. The mechanism by which the interrupt +occurs is platform dependent, but is intended to cause blocking system +calls to return immediately with an interrupted error code. The +underlying operating system thread is not to be destroyed. See +:ref:`ffi-interruptible` for more details. + +.. _haskell-threads-and-os-threads: + +The relationship between Haskell threads and OS threads +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Normally there is no fixed relationship between Haskell threads and OS +threads. This means that when you make a foreign call, that call may +take place in an unspecified OS thread. Furthermore, there is no +guarantee that multiple calls made by one Haskell thread will be made by +the same OS thread. + +This usually isn't a problem, and it allows the GHC runtime system to +make efficient use of OS thread resources. However, there are cases +where it is useful to have more control over which OS thread is used, +for example when calling foreign code that makes use of thread-local +state. For cases like this, we provide *bound threads*, which are +Haskell threads tied to a particular OS thread. For information on bound +threads, see the documentation for the :base-ref:`Control.Concurrent` module. + +Foreign exports and multi-threading +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When the program is linked with ``-threaded``, then you may invoke +``foreign export``\ ed functions from multiple OS threads concurrently. +The runtime system must be initialised as usual by calling +``hs_init()``, and this call must complete before invoking any +``foreign export``\ ed functions. + +.. _hs-exit: + +On the use of ``hs_exit()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``hs_exit()`` normally causes the termination of any running Haskell +threads in the system, and when ``hs_exit()`` returns, there will be no +more Haskell threads running. The runtime will then shut down the system +in an orderly way, generating profiling output and statistics if +necessary, and freeing all the memory it owns. + +It isn't always possible to terminate a Haskell thread forcibly: for +example, the thread might be currently executing a foreign call, and we +have no way to force the foreign call to complete. What's more, the +runtime must assume that in the worst case the Haskell code and runtime +are about to be removed from memory (e.g. if this is a +:ref:`Windows DLL <win32-dlls>`, ``hs_exit()`` is normally called before unloading +the DLL). So ``hs_exit()`` *must* wait until all outstanding foreign +calls return before it can return itself. + +The upshot of this is that if you have Haskell threads that are blocked +in foreign calls, then ``hs_exit()`` may hang (or possibly busy-wait) +until the calls return. Therefore it's a good idea to make sure you +don't have any such threads in the system when calling ``hs_exit()``. +This includes any threads doing I/O, because I/O may (or may not, +depending on the type of I/O and the platform) be implemented using +blocking foreign calls. + +The GHC runtime treats program exit as a special case, to avoid the need +to wait for blocked threads when a standalone executable exits. Since +the program and all its threads are about to terminate at the same time +that the code is removed from memory, it isn't necessary to ensure that +the threads have exited first. (Unofficially, if you want to use this +fast and loose version of ``hs_exit()``, then call +``shutdownHaskellAndExit()`` instead). + +.. _ffi-floating-point: + +Floating point and the FFI +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: Floating point; and the FFI + +The standard C99 ``fenv.h`` header provides operations for inspecting +and modifying the state of the floating point unit. In particular, the +rounding mode used by floating point operations can be changed, and the +exception flags can be tested. + +In Haskell, floating-point operations have pure types, and the +evaluation order is unspecified. So strictly speaking, since the +``fenv.h`` functions let you change the results of, or observe the +effects of floating point operations, use of ``fenv.h`` renders the +behaviour of floating-point operations anywhere in the program +undefined. + +Having said that, we *can* document exactly what GHC does with respect +to the floating point state, so that if you really need to use +``fenv.h`` then you can do so with full knowledge of the pitfalls: + +- GHC completely ignores the floating-point environment, the runtime + neither modifies nor reads it. + +- The floating-point environment is not saved over a normal thread + context-switch. So if you modify the floating-point state in one + thread, those changes may be visible in other threads. Furthermore, + testing the exception state is not reliable, because a context switch + may change it. If you need to modify or test the floating point state + and use threads, then you must use bound threads + (``Control.Concurrent.forkOS``), because a bound thread has its own + OS thread, and OS threads do save and restore the floating-point + state. + +- It is safe to modify the floating-point unit state temporarily during + a foreign call, because foreign calls are never pre-empted by GHC. + diff --git a/docs/users_guide/ffi-chap.xml b/docs/users_guide/ffi-chap.xml deleted file mode 100644 index 8417ef506b..0000000000 --- a/docs/users_guide/ffi-chap.xml +++ /dev/null @@ -1,818 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- FFI docs as a chapter --> - -<chapter id="ffi"> - <title> -Foreign function interface (FFI) - </title> - - <para>GHC (mostly) conforms to the Haskell Foreign Function Interface, - whose definition is part of the Haskell Report on <ulink url="http://www.haskell.org/"><literal>http://www.haskell.org/</literal></ulink>.</para> - - <para>FFI support is enabled by default, but can be enabled or disabled explicitly with the <option>-XForeignFunctionInterface</option><indexterm><primary><option>-XForeignFunctionInterface</option></primary> - </indexterm> flag.</para> - - <para>GHC implements a number of GHC-specific extensions to the FFI - Addendum. These extensions are described in <xref linkend="ffi-ghcexts" />, but please note that programs using - these features are not portable. Hence, these features should be - avoided where possible.</para> - - <para>The FFI libraries are documented in the accompanying library - documentation; see for example the - <ulink url="&libraryBaseLocation;/Control-Concurrent.html"><literal>Foreign</literal></ulink> module.</para> - - <sect1 id="ffi-ghcexts"> - <title>GHC extensions to the FFI Addendum</title> - - <para>The FFI features that are described in this section are specific to - GHC. Your code will not be portable to other compilers if you use them.</para> - - <sect2> - <title>Unboxed types</title> - - <para>The following unboxed types may be used as basic foreign types - (see FFI Addendum, Section 3.2): <literal>Int#</literal>, - <literal>Word#</literal>, <literal>Char#</literal>, - <literal>Float#</literal>, <literal>Double#</literal>, - <literal>Addr#</literal>, <literal>StablePtr# a</literal>, - <literal>MutableByteArray#</literal>, <literal>ForeignObj#</literal>, - and <literal>ByteArray#</literal>.</para> - </sect2> - - <sect2 id="ffi-newtype-io"> - <title>Newtype wrapping of the IO monad</title> - <para>The FFI spec requires the IO monad to appear in various places, - but it can sometimes be convenient to wrap the IO monad in a - <literal>newtype</literal>, thus: -<programlisting> - newtype MyIO a = MIO (IO a) -</programlisting> - (A reason for doing so might be to prevent the programmer from - calling arbitrary IO procedures in some part of the program.) -</para> -<para>The Haskell FFI already specifies that arguments and results of -foreign imports and exports will be automatically unwrapped if they are -newtypes (Section 3.2 of the FFI addendum). GHC extends the FFI by automatically unwrapping any newtypes that -wrap the IO monad itself. -More precisely, wherever the FFI specification requires an IO type, GHC will -accept any newtype-wrapping of an IO type. For example, these declarations are -OK: -<programlisting> - foreign import foo :: Int -> MyIO Int - foreign import "dynamic" baz :: (Int -> MyIO Int) -> CInt -> MyIO Int -</programlisting> -</para> - </sect2> - - <sect2 id="ffi-prim"> - <title>Primitive imports</title> - <para> - GHC extends the FFI with an additional calling convention - <literal>prim</literal>, e.g.: -<programlisting> - foreign import prim "foo" foo :: ByteArray# -> (# Int#, Int# #) -</programlisting> - This is used to import functions written in Cmm code that follow an - internal GHC calling convention. The arguments and results must - be unboxed types, except that an argument may be of type - <literal>Any</literal> (by way of <literal>unsafeCoerce#</literal>) - and the result type is allowed to be an unboxed tuple or the - type <literal>Any</literal>. - </para> - <para> - This feature is not intended for - use outside of the core libraries that come with GHC. For more - details see the <ulink linkend="http://ghc.haskell.org/trac/ghc/wiki/Commentary/PrimOps"> - GHC developer wiki</ulink>. - </para> - </sect2> - - <sect2 id="ffi-interruptible"> - <title>Interruptible foreign calls</title> - <para> - This concerns the interaction of foreign calls - with <literal>Control.Concurrent.throwTo</literal>. - Normally when the target of a <literal>throwTo</literal> is - involved in a foreign call, the exception is not raised - until the call returns, and in the meantime the caller is - blocked. This can result in unresponsiveness, which is - particularly undesirable in the case of user interrupt - (e.g. Control-C). The default behaviour when a Control-C - signal is received (<literal>SIGINT</literal> on Unix) is to raise - the <literal>UserInterrupt</literal> exception in the main - thread; if the main thread is blocked in a foreign call at - the time, then the program will not respond to the user - interrupt. - </para> - - <para> - The problem is that it is not possible in general to - interrupt a foreign call safely. However, GHC does provide - a way to interrupt blocking system calls which works for - most system calls on both Unix and Windows. When the - <literal>InterruptibleFFI</literal> extension is enabled, - a foreign call - can be annotated with <literal>interruptible</literal> instead - of <literal>safe</literal> or <literal>unsafe</literal>: - -<programlisting> -foreign import ccall interruptible - "sleep" sleepBlock :: CUint -> IO CUint -</programlisting> - - <literal>interruptible</literal> behaves exactly as - <literal>safe</literal>, except that when - a <literal>throwTo</literal> is directed at a thread in an - interruptible foreign call, an OS-specific mechanism will be - used to attempt to cause the foreign call to return: - - <variablelist> - <varlistentry> - <term>Unix systems</term> - <listitem> - <para> - The thread making the foreign call is sent - a <literal>SIGPIPE</literal> signal - using <literal>pthread_kill()</literal>. This is - usually enough to cause a blocking system call to - return with <literal>EINTR</literal> (GHC by default - installs an empty signal handler - for <literal>SIGPIPE</literal>, to override the - default behaviour which is to terminate the process - immediately). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Windows systems</term> - <listitem> - <para> - [Vista and later only] The RTS calls the Win32 - function <literal>CancelSynchronousIO</literal>, - which will cause a blocking I/O operation to return - with the - error <literal>ERROR_OPERATION_ABORTED</literal>. - </para> - </listitem> - </varlistentry> - </variablelist> - - If the system call is successfully interrupted, it will - return to Haskell whereupon the exception can be raised. Be - especially careful when - using <literal>interruptible</literal> that the caller of - the foreign function is prepared to deal with the - consequences of the call being interrupted; on Unix it is - good practice to check for <literal>EINTR</literal> always, - but on Windows it is not typically necessary to - handle <literal>ERROR_OPERATION_ABORTED</literal>. - </para> - </sect2> - - <sect2 id="ffi-capi"> - <title>The CAPI calling convention</title> - <para> - The <literal>CApiFFI</literal> extension allows a calling - convention of <literal>capi</literal> to be used in foreign - declarations, e.g. - -<programlisting> -foreign import capi "header.h f" f :: CInt -> IO CInt -</programlisting> - - Rather than generating code to call <literal>f</literal> - according to the platform's ABI, we instead call - <literal>f</literal> using the C API defined in the header - <literal>header.h</literal>. Thus <literal>f</literal> can be - called even if it may be defined as a CPP - <literal>#define</literal> rather than a proper function. - </para> - - <para> - When using <literal>capi</literal>, it is also possible to - import values, rather than functions. For example, - -<programlisting> -foreign import capi "pi.h value pi" c_pi :: CDouble -</programlisting> - - will work regardless of whether <literal>pi</literal> is - defined as -<programlisting> -const double pi = 3.14; -</programlisting> - or with -<programlisting> -#define pi 3.14 -</programlisting> - </para> - - <para> - In order to tell GHC the C type that a Haskell type - corresponds to when it is used with the CAPI, a - <literal>CTYPE</literal> pragma can be used on the type - definition. The header which defines the type can optionally - also be specified. The syntax looks like: - -<programlisting> -data {-# CTYPE "unistd.h" "useconds_t" #-} T = ... -newtype {-# CTYPE "useconds_t" #-} T = ... -</programlisting> - </para> - </sect2> - - <sect2> - <title><literal>hs_thread_done()</literal></title> - -<programlisting> -void hs_thread_done(void); -</programlisting> - - <para> - GHC allocates a small amount of thread-local memory when a - thread calls a Haskell function via a <literal>foreign - export</literal>. This memory is not normally freed until - <literal>hs_exit()</literal>; the memory is cached so that - subsequent calls into Haskell are fast. However, if your - application is long-running and repeatedly creates new - threads that call into Haskell, you probably want to arrange - that this memory is freed in those threads that have - finished calling Haskell functions. To do this, call - <literal>hs_thread_done()</literal> from the thread whose - memory you want to free. - </para> - - <para> - Calling <literal>hs_thread_done()</literal> is entirely - optional. You can call it as often or as little as you - like. It is safe to call it from a thread that has never - called any Haskell functions, or one that never will. If - you forget to call it, the worst that can happen is that - some memory remains allocated until - <literal>hs_exit()</literal> is called. If you call it too - often, the worst that can happen is that the next call to a - Haskell function incurs some extra overhead. - </para> - </sect2> - </sect1> - - <sect1 id="ffi-ghc"> - <title>Using the FFI with GHC</title> - - <para>The following sections also give some hints and tips on the - use of the foreign function interface in GHC.</para> - - <sect2 id="foreign-export-ghc"> - <title>Using <literal>foreign export</literal> and <literal>foreign import ccall "wrapper"</literal> with GHC</title> - - <indexterm><primary><literal>foreign export - </literal></primary><secondary>with GHC</secondary> - </indexterm> - - <para>When GHC compiles a module (say <filename>M.hs</filename>) - which uses <literal>foreign export</literal> or - <literal>foreign import "wrapper"</literal>, it generates - a <filename>M_stub.h</filename> for use by C programs.</para> - - <para>For a plain <literal>foreign export</literal>, the file - <filename>M_stub.h</filename> contains a C prototype for the - foreign exported function. For example, if we compile the - following module:</para> - -<programlisting> -module Foo where - -foreign export ccall foo :: Int -> IO Int - -foo :: Int -> IO Int -foo n = return (length (f n)) - -f :: Int -> [Int] -f 0 = [] -f n = n:(f (n-1))</programlisting> - - <para>Then <filename>Foo_stub.h</filename> will contain - something like this:</para> - -<programlisting> -#include "HsFFI.h" -extern HsInt foo(HsInt a0);</programlisting> - - <para>To invoke <literal>foo()</literal> from C, just <literal>#include - "Foo_stub.h"</literal> and call <literal>foo()</literal>.</para> - - <para>The - <filename>Foo_stub.h</filename> file can be redirected using the - <option>-stubdir</option> option; see <xref linkend="options-output" - />.</para> - - <sect3 id="using-own-main"> - <title>Using your own <literal>main()</literal></title> - - <para>Normally, GHC's runtime system provides a - <literal>main()</literal>, which arranges to invoke - <literal>Main.main</literal> in the Haskell program. However, - you might want to link some Haskell code into a program which - has a main function written in another language, say C. In - order to do this, you have to initialize the Haskell runtime - system explicitly.</para> - - <para>Let's take the example from above, and invoke it from a - standalone C program. Here's the C code:</para> - -<programlisting> -#include <stdio.h> -#include "HsFFI.h" - -#ifdef __GLASGOW_HASKELL__ -#include "Foo_stub.h" -#endif - -int main(int argc, char *argv[]) -{ - int i; - - hs_init(&argc, &argv); - - for (i = 0; i < 5; i++) { - printf("%d\n", foo(2500)); - } - - hs_exit(); - return 0; -}</programlisting> - - <para>We've surrounded the GHC-specific bits with - <literal>#ifdef __GLASGOW_HASKELL__</literal>; the rest of the - code should be portable across Haskell implementations that - support the FFI standard.</para> - - <para>The call to <literal>hs_init()</literal> - initializes GHC's runtime system. Do NOT try to invoke any - Haskell functions before calling - <literal>hs_init()</literal>: bad things will - undoubtedly happen.</para> - - <para>We pass references to <literal>argc</literal> and - <literal>argv</literal> to <literal>hs_init()</literal> - so that it can separate out any arguments for the RTS - (i.e. those arguments between - <literal>+RTS...-RTS</literal>).</para> - - <para>After we've finished invoking our Haskell functions, we - can call <literal>hs_exit()</literal>, which terminates the - RTS.</para> - - <para>There can be multiple calls to - <literal>hs_init()</literal>, but each one should be matched - by one (and only one) call to - <literal>hs_exit()</literal><footnote><para>The outermost - <literal>hs_exit()</literal> will actually de-initialise the - system. NOTE that currently GHC's runtime cannot reliably - re-initialise after this has happened, - see <xref linkend="infelicities-ffi" />.</para> - </footnote>.</para> - - <para>NOTE: when linking the final program, it is normally - easiest to do the link using GHC, although this isn't - essential. If you do use GHC, then don't forget the flag - <option>-no-hs-main</option><indexterm><primary><option>-no-hs-main</option></primary> - </indexterm>, otherwise GHC will try to link - to the <literal>Main</literal> Haskell module.</para> - - <para>To use <literal>+RTS</literal> flags - with <literal>hs_init()</literal>, we have to modify the - example slightly. By default, GHC's RTS will only accept - "safe" - <literal>+RTS</literal> flags (see - <xref linkend="options-linker" />), and - the <option>-rtsopts</option><indexterm><primary><option>-rtsopts</option></primary></indexterm> link-time flag overrides this. - However, <option>-rtsopts</option> has no effect - when <option>-no-hs-main</option> is in use (and the same - goes for <option>-with-rtsopts</option>). To set these - options we have to call a GHC-specific API instead - of <option>hs_init()</option>:</para> - -<programlisting> -#include <stdio.h> -#include "HsFFI.h" - -#ifdef __GLASGOW_HASKELL__ -#include "Foo_stub.h" -#include "Rts.h" -#endif - -int main(int argc, char *argv[]) -{ - int i; - -#if __GLASGOW_HASKELL__ >= 703 - { - RtsConfig conf = defaultRtsConfig; - conf.rts_opts_enabled = RtsOptsAll; - hs_init_ghc(&argc, &argv, conf); - } -#else - hs_init(&argc, &argv); -#endif - - for (i = 0; i < 5; i++) { - printf("%d\n", foo(2500)); - } - - hs_exit(); - return 0; -}</programlisting> - - <para>Note two changes: we included <literal>Rts.h</literal>, - which defines the GHC-specific external RTS interface, and we - called <literal>hs_init_ghc()</literal> instead - of <literal>hs_init()</literal>, passing an argument of - type <literal>RtsConfig</literal>. - <literal>RtsConfig</literal> is a struct with various fields - that affect the behaviour of the runtime system. Its - definition is:</para> - -<programlisting> -typedef struct { - RtsOptsEnabledEnum rts_opts_enabled; - const char *rts_opts; -} RtsConfig; - -extern const RtsConfig defaultRtsConfig; - -typedef enum { - RtsOptsNone, // +RTS causes an error - RtsOptsSafeOnly, // safe RTS options allowed; others cause an error - RtsOptsAll // all RTS options allowed - } RtsOptsEnabledEnum; -</programlisting> - - <para>There is a default - value <literal>defaultRtsConfig</literal> that should be used - to initialise variables of type <literal>RtsConfig</literal>. - More fields will undoubtedly be added - to <literal>RtsConfig</literal> in the future, so in order to - keep your code forwards-compatible it is best to initialise - with <literal>defaultRtsConfig</literal> and then modify the - required fields, as in the code sample above.</para> - - - </sect3> - - <sect3 id="ffi-library"> - <title>Making a Haskell library that can be called from foreign - code</title> - - <para>The scenario here is much like in <xref linkend="using-own-main" - />, except that the aim is not to link a complete program, but to - make a library from Haskell code that can be deployed in the same - way that you would deploy a library of C code.</para> - - <para>The main requirement here is that the runtime needs to be - initialized before any Haskell code can be called, so your library - should provide initialisation and deinitialisation entry points, - implemented in C or C++. For example:</para> - -<programlisting> -#include <stdlib.h> -#include "HsFFI.h" - -HsBool mylib_init(void){ - int argc = 2; - char *argv[] = { "+RTS", "-A32m", NULL }; - char **pargv = argv; - - // Initialize Haskell runtime - hs_init(&argc, &pargv); - - // do any other initialization here and - // return false if there was a problem - return HS_BOOL_TRUE; -} - -void mylib_end(void){ - hs_exit(); -} -</programlisting> - - <para>The initialisation routine, <literal>mylib_init</literal>, calls - <literal>hs_init()</literal> as - normal to initialise the Haskell runtime, and the corresponding - deinitialisation function <literal>mylib_end()</literal> calls - <literal>hs_exit()</literal> to shut down the runtime.</para> - </sect3> - - </sect2> - - <sect2 id="glasgow-foreign-headers"> - <title>Using header files</title> - - <indexterm><primary>C calls, function headers</primary></indexterm> - - <para>C functions are normally declared using prototypes in a C - header file. Earlier versions of GHC (6.8.3 and - earlier) <literal>#include</literal>d the header file in - the C source file generated from the Haskell code, and the C - compiler could therefore check that the C function being - called via the FFI was being called at the right type.</para> - - <para>GHC no longer includes external header files when - compiling via C, so this checking is not performed. The - change was made for compatibility with the - <ulink linkend="native-code-gen">native code generator</ulink> - (<literal>-fasm</literal>) and to comply strictly with the FFI - specification, which requires that FFI calls are not subject - to macro expansion and other CPP conversions that may be - applied when using C header files. This approach also - simplifies the inlining of foreign calls across module and - package boundaries: there's no need for the header file to be - available when compiling an inlined version of a foreign call, - so the compiler is free to inline foreign calls in any - context.</para> - - <para>The <literal>-#include</literal> option is now - deprecated, and the <literal>include-files</literal> field - in a Cabal package specification is ignored.</para> - - </sect2> - - <sect2> - <title>Memory Allocation</title> - - <para>The FFI libraries provide several ways to allocate memory - for use with the FFI, and it isn't always clear which way is the - best. This decision may be affected by how efficient a - particular kind of allocation is on a given compiler/platform, - so this section aims to shed some light on how the different - kinds of allocation perform with GHC.</para> - - <variablelist> - <varlistentry> - <term><literal>alloca</literal> and friends</term> - <listitem> - <para>Useful for short-term allocation when the allocation - is intended to scope over a given <literal>IO</literal> - computation. This kind of allocation is commonly used - when marshalling data to and from FFI functions.</para> - - <para>In GHC, <literal>alloca</literal> is implemented - using <literal>MutableByteArray#</literal>, so allocation - and deallocation are fast: much faster than C's - <literal>malloc/free</literal>, but not quite as fast as - stack allocation in C. Use <literal>alloca</literal> - whenever you can.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>mallocForeignPtr</literal></term> - <listitem> - <para>Useful for longer-term allocation which requires - garbage collection. If you intend to store the pointer to - the memory in a foreign data structure, then - <literal>mallocForeignPtr</literal> is - <emphasis>not</emphasis> a good choice, however.</para> - - <para>In GHC, <literal>mallocForeignPtr</literal> is also - implemented using <literal>MutableByteArray#</literal>. - Although the memory is pointed to by a - <literal>ForeignPtr</literal>, there are no actual - finalizers involved (unless you add one with - <literal>addForeignPtrFinalizer</literal>), and the - deallocation is done using GC, so - <literal>mallocForeignPtr</literal> is normally very - cheap.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>malloc/free</literal></term> - <listitem> - <para>If all else fails, then you need to resort to - <literal>Foreign.malloc</literal> and - <literal>Foreign.free</literal>. These are just wrappers - around the C functions of the same name, and their - efficiency will depend ultimately on the implementations - of these functions in your platform's C library. We - usually find <literal>malloc</literal> and - <literal>free</literal> to be significantly slower than - the other forms of allocation above.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>Foreign.Marshal.Pool</literal></term> - <listitem> - <para>Pools are currently implemented using - <literal>malloc/free</literal>, so while they might be a - more convenient way to structure your memory allocation - than using one of the other forms of allocation, they - won't be any more efficient. We do plan to provide an - improved-performance implementation of Pools in the - future, however.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="ffi-threads"> - <title>Multi-threading and the FFI</title> - - <para>In order to use the FFI in a multi-threaded setting, you must - use the <option>-threaded</option> option - (see <xref linkend="options-linker" />).</para> - - <sect3> - <title>Foreign imports and multi-threading</title> - - <para>When you call a <literal>foreign import</literal>ed - function that is annotated as <literal>safe</literal> (the - default), and the program was linked - using <option>-threaded</option>, then the call will run - concurrently with other running Haskell threads. If the - program was linked without <option>-threaded</option>, - then the other Haskell threads will be blocked until the - call returns.</para> - - <para>This means that if you need to make a foreign call to - a function that takes a long time or blocks indefinitely, - then you should mark it <literal>safe</literal> and - use <option>-threaded</option>. Some library functions - make such calls internally; their documentation should - indicate when this is the case.</para> - - <para>If you are making foreign calls from multiple Haskell - threads and using <option>-threaded</option>, make sure that - the foreign code you are calling is thread-safe. In - particularly, some GUI libraries are not thread-safe and - require that the caller only invokes GUI methods from a - single thread. If this is the case, you may need to - restrict your GUI operations to a single Haskell thread, - and possibly also use a bound thread (see - <xref linkend="haskell-threads-and-os-threads" />).</para> - - <para>Note that foreign calls made by different Haskell - threads may execute in <emphasis>parallel</emphasis>, even - when the <literal>+RTS -N</literal> flag is not being used - (<xref linkend="parallel-options" />). The <literal>+RTS - -N</literal> flag controls parallel execution of Haskell - threads, but there may be an arbitrary number of foreign - calls in progress at any one time, regardless of - the <literal>+RTS -N</literal> value.</para> - - <para>If a call is annotated as <literal>interruptible</literal> - and the program was multithreaded, the call may be - interrupted in the event that the Haskell thread receives an - exception. The mechanism by which the interrupt occurs - is platform dependent, but is intended to cause blocking - system calls to return immediately with an interrupted error - code. The underlying operating system thread is not to be - destroyed. See <xref linkend="ffi-interruptible"/> for more details.</para> - </sect3> - - <sect3 id="haskell-threads-and-os-threads"> - <title>The relationship between Haskell threads and OS - threads</title> - - <para>Normally there is no fixed relationship between Haskell - threads and OS threads. This means that when you make a - foreign call, that call may take place in an unspecified OS - thread. Furthermore, there is no guarantee that multiple - calls made by one Haskell thread will be made by the same OS - thread.</para> - - <para>This usually isn't a problem, and it allows the GHC - runtime system to make efficient use of OS thread resources. - However, there are cases where it is useful to have more - control over which OS thread is used, for example when - calling foreign code that makes use of thread-local state. - For cases like this, we provide <emphasis>bound - threads</emphasis>, which are Haskell threads tied to a - particular OS thread. For information on bound threads, see - the documentation - for the <ulink url="&libraryBaseLocation;/Control-Concurrent.html"><literal>Control.Concurrent</literal></ulink> - module.</para> - </sect3> - - <sect3> - <title>Foreign exports and multi-threading</title> - - <para>When the program is linked - with <option>-threaded</option>, then you may - invoke <literal>foreign export</literal>ed functions from - multiple OS threads concurrently. The runtime system must - be initialised as usual by - calling <literal>hs_init()</literal>, and this call must - complete before invoking any <literal>foreign - export</literal>ed functions.</para> - </sect3> - - <sect3 id="hs-exit"> - <title>On the use of <literal>hs_exit()</literal></title> - - <para><literal>hs_exit()</literal> normally causes the termination of - any running Haskell threads in the system, and when - <literal>hs_exit()</literal> returns, there will be no more Haskell - threads running. The runtime will then shut down the system in an - orderly way, generating profiling - output and statistics if necessary, and freeing all the memory it - owns.</para> - - <para>It isn't always possible to terminate a Haskell thread forcibly: - for example, the thread might be currently executing a foreign call, - and we have no way to force the foreign call to complete. What's - more, the runtime must - assume that in the worst case the Haskell code and runtime are about - to be removed from memory (e.g. if this is a <link linkend="win32-dlls">Windows DLL</link>, - <literal>hs_exit()</literal> is normally called before unloading the - DLL). So <literal>hs_exit()</literal> <emphasis>must</emphasis> wait - until all outstanding foreign calls return before it can return - itself.</para> - - <para>The upshot of this is that if you have Haskell threads that are - blocked in foreign calls, then <literal>hs_exit()</literal> may hang - (or possibly busy-wait) until the calls return. Therefore it's a - good idea to make sure you don't have any such threads in the system - when calling <literal>hs_exit()</literal>. This includes any threads - doing I/O, because I/O may (or may not, depending on the - type of I/O and the platform) be implemented using blocking foreign - calls.</para> - - <para>The GHC runtime treats program exit as a special case, to avoid - the need to wait for blocked threads when a standalone - executable exits. Since the program and all its threads are about to - terminate at the same time that the code is removed from memory, it - isn't necessary to ensure that the threads have exited first. - (Unofficially, if you want to use this fast and loose version of - <literal>hs_exit()</literal>, then call - <literal>shutdownHaskellAndExit()</literal> instead).</para> - </sect3> - </sect2> - - <sect2 id="ffi-floating-point"> - <title>Floating point and the FFI</title> - - <para> - The standard C99 <literal>fenv.h</literal> header - provides operations for inspecting and modifying the state of - the floating point unit. In particular, the rounding mode - used by floating point operations can be changed, and the - exception flags can be tested. - </para> - - <para> - In Haskell, floating-point operations have pure types, and the - evaluation order is unspecified. So strictly speaking, since - the <literal>fenv.h</literal> functions let you change the - results of, or observe the effects of floating point - operations, use of <literal>fenv.h</literal> renders the - behaviour of floating-point operations anywhere in the program - undefined. - </para> - - <para> - Having said that, we <emphasis>can</emphasis> document exactly - what GHC does with respect to the floating point state, so - that if you really need to use <literal>fenv.h</literal> then - you can do so with full knowledge of the pitfalls: - <itemizedlist> - <listitem> - <para> - GHC completely ignores the floating-point - environment, the runtime neither modifies nor reads it. - </para> - </listitem> - <listitem> - <para> - The floating-point environment is not saved over a - normal thread context-switch. So if you modify the - floating-point state in one thread, those changes may be - visible in other threads. Furthermore, testing the - exception state is not reliable, because a context - switch may change it. If you need to modify or test the - floating point state and use threads, then you must use - bound threads - (<literal>Control.Concurrent.forkOS</literal>), because - a bound thread has its own OS thread, and OS threads do - save and restore the floating-point state. - </para> - </listitem> - <listitem> - <para> - It is safe to modify the floating-point unit state - temporarily during a foreign call, because foreign calls - are never pre-empted by GHC. - </para> - </listitem> - </itemizedlist> - </para> - </sect2> - </sect1> -</chapter> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") *** - ;;; End: *** - --> diff --git a/docs/users_guide/flags.rst b/docs/users_guide/flags.rst new file mode 100644 index 0000000000..4064f46bdf --- /dev/null +++ b/docs/users_guide/flags.rst @@ -0,0 +1,212 @@ +.. _flag-reference: + +Flag reference +============== + +This section is a quick-reference for GHC's command-line flags. For each +flag, we also list its static/dynamic status (see +:ref:`static-dynamic-flags`), and the flag's opposite (if available). + +Verbosity options +----------------- + +More details in :ref:`options-help` + +.. include:: flags-verbosity.gen.rst + +Alternative modes of operation +------------------------------ + +More details in :ref:`modes` + +.. include:: flags-modes.gen.rst + +Which phases to run +------------------- + +More details in :ref:`options-order` + +.. include:: flags-phases.gen.rst + +Redirecting output +------------------ + +More details in :ref:`options-output` + +.. include:: flags-redirecting-output.gen.rst + +Keeping intermediate files +-------------------------- + +More details in :ref:`keeping-intermediates` + +.. include:: flags-keeping-intermediates.gen.rst + +Temporary files +--------------- + +More details in :ref:`temp-files` + +.. include:: flags-temporary-files.gen.rst + +Finding imports +--------------- + +More details in :ref:`search-path` + +.. include:: flags-finding-imports.gen.rst + +Interface file options +---------------------- + +More details in :ref:`hi-options` + +.. include:: flags-interface-files.gen.rst + +Recompilation checking +---------------------- + +More details in :ref:`recomp` + +.. include:: flags-recompilation-checking.gen.rst + +.. _interactive-mode-options: + +Interactive-mode options +------------------------ + +More details in :ref:`ghci-dot-files` + +.. include:: flags-interactive.gen.rst + +Packages +-------- + +More details in :ref:`packages` + +.. include:: flags-packages.gen.rst + +Language options +---------------- + +Language options can be enabled either by a command-line option +``-Xblah``, or by a ``{-# LANGUAGE blah #-}`` pragma in the file itself. +See :ref:`options-language`. Some options are enabled using ``-f*`` +flags. + +.. include:: flags-language.gen.rst + +Warnings +-------- + +More details in :ref:`options-sanity` + +.. include:: flags-warnings.gen.rst + +Optimisation levels +------------------- + +These options are described in more detail in :ref:`options-optimise`. + +See :ref:`options-f-compact` for a list of optimisations enabled on +level 1 and level 2. + +.. include:: flags-optimization-levels.gen.rst + +.. _options-f-compact: + +Individual optimisations +------------------------ + +These options are described in more detail in :ref:`options-f`. If a +flag is implied by ``-O`` then it is also implied by ``-O2`` (unless +flag description explicitly says otherwise). If a flag is implied by +``-O0`` only then the flag is not implied by ``-O`` and ``-O2``. + +.. include:: flags-optimization.gen.rst + +Profiling options +----------------- + +More details in :ref:`profiling` + +.. include:: flags-profiling.gen.rst + +Program coverage options +------------------------ + +More details in :ref:`hpc` + +.. include:: flags-program-coverage.gen.rst + +C pre-processor options +----------------------- + +More details in :ref:`c-pre-processor` + +.. include:: flags-cpp.gen.rst + +Code generation options +----------------------- + +More details in :ref:`options-codegen` + +.. include:: flags-codegen.gen.rst + +Linking options +--------------- + +More details in :ref:`options-linker` + +.. include:: flags-linking.gen.rst + +Plugin options +-------------- + +More details in :ref:`compiler-plugins` + +.. include:: flags-plugin.gen.rst + +Replacing phases +---------------- + +More details in :ref:`replacing-phases` + +.. include:: flags-phase-programs.gen.rst + +.. index:: + single: -pgmL + single: -pgmP + single: -pgmc + single: -pgmlo + single: -pgmlc + single: -pgma + single: -pgml + single: -pgmdll + single: -pgmF + +Forcing options to particular phases +------------------------------------ + +More details in :ref:`forcing-options-through` + +.. include:: flags-phase-specific.gen.rst + +Platform-specific options +------------------------- + +More details in :ref:`options-platform` + +.. include:: flags-platform-specific.gen.rst + +Compiler debugging options +-------------------------- + +More details in :ref:`options-debugging` + +.. include:: flags-compiler-debugging.gen.rst + +Miscellaneous compiler options +------------------------------ + +.. include:: flags-misc.gen.rst diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml deleted file mode 100644 index 7bf8246b75..0000000000 --- a/docs/users_guide/flags.xml +++ /dev/null @@ -1,3564 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<sect1 id="flag-reference"> - <title>Flag reference</title> - - <para>This section is a quick-reference for GHC's command-line - flags. For each flag, we also list its static/dynamic status (see - <xref linkend="static-dynamic-flags"/>), and the flag's opposite - (if available).</para> - - <sect2> - <title>Verbosity options</title> - - <para>More details in <xref linkend="options-help"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-v</option></entry> - <entry>verbose mode (equivalent to <option>-v3</option>)</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-v</option><replaceable>n</replaceable></entry> - <entry>set verbosity level</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-fprint-potential-instances</option></entry> - <entry>display all available instances in type error messages</entry> - <entry>dynamic</entry> - <entry>-fno-print-potential-instances</entry> - </row> - <row> - <entry><option>-fprint-explicit-foralls</option></entry> - <entry>Print explicit <literal>forall</literal> quantification in types. See also <option>-XExplicitForAll</option></entry> - <entry>dynamic</entry> - <entry>-fno-print-explicit-foralls</entry> - </row> - <row> - <entry><option>-fprint-explicit-kinds</option></entry> - <entry>Print explicit kind foralls and kind arguments in types. See also <option>-XKindSignature</option></entry> - <entry>dynamic</entry> - <entry>-fno-print-explicit-kinds</entry> - </row> - <row> - <entry><option>-fprint-unicode-syntax</option></entry> - <entry>Use unicode syntax when printing expressions, types and kinds. See also <option>-XUnicodeSyntax</option></entry> - <entry>dynamic</entry> - <entry>-fno-print-unicode-syntax</entry> - </row> - <row> - <entry><option>-fprint-expanded-synonyms</option></entry> - <entry>In type errors, also print type-synonym-expanded types.</entry> - <entry>dynamic</entry> - <entry>-fno-print-expanded-synonyms</entry> - </row> - <row> - <entry><option>-ferror-spans</option></entry> - <entry>output full span in error messages</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-H</option><replaceable>size</replaceable></entry> - <entry>Set the minimum heap size to <replaceable>size</replaceable></entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-Rghc-timing</option></entry> - <entry>Summarise timing stats for GHC (same as <literal>+RTS -tstderr</literal>)</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - </sect2> - <sect2> - <title>Alternative modes of operation</title> - - <para>More details in <xref linkend="modes"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>--help</option>,<option>-?</option></entry> - <entry>Display help</entry> - <entry>mode</entry> - <entry>-</entry> - </row> - - <row> - <entry><option>--interactive</option></entry> - <entry>Interactive mode - normally used by just running <command>ghci</command>; - see <xref linkend="ghci"/> for details.</entry> - <entry>mode</entry> - <entry>-</entry> - </row> - <row> - <entry><option>--make</option></entry> - <entry>Build a multi-module Haskell program, automatically figuring out dependencies. Likely to be much easier, and faster, than using <command>make</command>; - see <xref linkend="make-mode"/> for details..</entry> - <entry>mode</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-e <replaceable>expr</replaceable></option></entry> - <entry>Evaluate <replaceable>expr</replaceable>; - see <xref linkend="eval-mode"/> for details.</entry> - <entry>mode</entry> - <entry>-</entry> - </row> - - <row> - <entry><option>--show-iface</option></entry> - <entry>Display the contents of an interface file.</entry> - <entry>mode</entry> - <entry>-</entry> - </row> - - <row> - <entry><option>-M</option></entry> - <entry>Generate dependency information suitable for use in a <filename>Makefile</filename>; - see <xref linkend="makefile-dependencies"/> for details.</entry> - <entry>mode</entry> - <entry>-</entry> - </row> - - - <row> - <entry><option>--supported-extensions</option>, <option>--supported-languages</option></entry> - <entry>display the supported language extensions</entry> - <entry>mode</entry> - <entry>-</entry> - </row> - <row> - <entry><option>--show-options</option></entry> - <entry>display the supported command line options</entry> - <entry>mode</entry> - <entry>-</entry> - </row> - <row> - <entry><option>--info</option></entry> - <entry>display information about the compiler</entry> - <entry>mode</entry> - <entry>-</entry> - </row> - <row> - <entry><option>--version, -V</option></entry> - <entry>display GHC version</entry> - <entry>mode</entry> - <entry>-</entry> - </row> - <row> - <entry><option>--numeric-version</option></entry> - <entry>display GHC version (numeric only)</entry> - <entry>mode</entry> - <entry>-</entry> - </row> - <row> - <entry><option>--print-libdir</option></entry> - <entry>display GHC library directory</entry> - <entry>mode</entry> - <entry>-</entry> - </row> - - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Which phases to run</title> - - <para><xref linkend="options-order"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-E</option></entry> - <entry>Stop after preprocessing (<literal>.hspp</literal> file)</entry> - <entry>mode</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-C</option></entry> - <entry>Stop after generating C (<literal>.hc</literal> file)</entry> - <entry>mode</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-S</option></entry> - <entry>Stop after generating assembly (<literal>.s</literal> file)</entry> - <entry>mode</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-c</option></entry> - <entry>Stop after generating object (<literal>.o</literal>) file</entry> - <entry>mode</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-x</option> <replaceable>suffix</replaceable></entry> - <entry>Override default behaviour for source files</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Redirecting output</title> - - <para><xref linkend="options-output"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-hcsuf</option> <replaceable>suffix</replaceable></entry> - <entry>set the suffix to use for intermediate C files</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-hidir</option> <replaceable>dir</replaceable></entry> - <entry>set directory for interface files</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-hisuf</option> <replaceable>suffix</replaceable></entry> - <entry>set the suffix to use for interface files</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-o</option> <replaceable>filename</replaceable></entry> - <entry>set output filename</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-odir</option> <replaceable>dir</replaceable></entry> - <entry>set directory for object files</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ohi</option> <replaceable>filename</replaceable></entry> - <entry>set the filename in which to put the interface</entry> - <entry>dynamic</entry> - <entry></entry> - </row> - <row> - <entry><option>-osuf</option> <replaceable>suffix</replaceable></entry> - <entry>set the output file suffix</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-stubdir</option> <replaceable>dir</replaceable></entry> - <entry>redirect FFI stub files</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dumpdir</option> <replaceable>dir</replaceable></entry> - <entry>redirect dump files</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-outputdir</option> <replaceable>dir</replaceable></entry> - <entry>set output directory</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Keeping intermediate files</title> - - <para><xref linkend="keeping-intermediates"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-keep-hc-file</option> or - <option>-keep-hc-files</option></entry> - <entry>retain intermediate <literal>.hc</literal> files</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-keep-llvm-file</option> or - <option>-keep-llvm-files</option></entry> - <entry>retain intermediate LLVM <literal>.ll</literal> files</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-keep-s-file</option> or - <option>-keep-s-files</option></entry> - <entry>retain intermediate <literal>.s</literal> files</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-keep-tmp-files</option></entry> - <entry>retain all intermediate temporary files</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Temporary files</title> - - <para><xref linkend="temp-files"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-tmpdir</option></entry> - <entry>set the directory for temporary files</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Finding imports</title> - - <para><xref linkend="search-path"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-i</option><replaceable>dir1</replaceable>:<replaceable>dir2</replaceable>:...</entry> - <entry>add <replaceable>dir</replaceable>, - <replaceable>dir2</replaceable>, etc. to import path</entry> - <entry>dynamic/<literal>:set</literal></entry> - <entry>-</entry> - </row> - <row> - <entry><option>-i</option></entry> - <entry>Empty the import directory list</entry> - <entry>dynamic/<literal>:set</literal></entry> - <entry>-</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Interface file options</title> - - <para><xref linkend="hi-options"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-ddump-hi</option></entry> - <entry>Dump the new interface to stdout</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-hi-diffs</option></entry> - <entry>Show the differences vs. the old interface</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-minimal-imports</option></entry> - <entry>Dump a minimal set of imports</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>--show-iface</option> <replaceable>file</replaceable></entry> - <entry>See <xref linkend="modes"/>.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Recompilation checking</title> - - <para><xref linkend="recomp"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-fforce-recomp</option></entry> - <entry>Turn off recompilation checking. This is implied by any - <option>-ddump-X</option> option when compiling a single - file (i.e. when using <literal>-c</literal>).</entry> - <entry>dynamic</entry> - <entry><option>-fno-force-recomp</option></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2 id="interactive-mode-options"> - <title>Interactive-mode options</title> - - <para><xref linkend="ghci-dot-files"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-ignore-dot-ghci</option></entry> - <entry>Disable reading of <filename>.ghci</filename> files</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ghci-script</option></entry> - <entry>Read additional <filename>.ghci</filename> files</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-fbreak-on-error</option></entry> - <entry><link linkend="ghci-debugger-exceptions">Break on uncaught exceptions and errors</link></entry> - <entry>dynamic</entry> - <entry><option>-fno-break-on-error</option></entry> - </row> - <row> - <entry><option>-fbreak-on-exception</option></entry> - <entry><link linkend="ghci-debugger-exceptions">Break on any exception thrown</link></entry> - <entry>dynamic</entry> - <entry><option>-fno-break-on-exception</option></entry> - </row> - <row> - <entry><option>-fghci-hist-size=<replaceable>n</replaceable></option></entry> - <entry><link linkend="ghci-debugger">Set the number of entries GHCi keeps for <literal>:history</literal></link></entry> - <entry>dynamic</entry> - <entry><option>(default is 50)</option></entry> - </row> - <row> - <entry><option>-fprint-evld-with-show</option></entry> - <entry><link linkend="breakpoints">Enable usage of Show instances in <literal>:print</literal></link></entry> - <entry>dynamic</entry> - <entry><option>-fno-print-evld-with-show</option></entry> - </row> - <row> - <entry><option>-fprint-bind-result</option></entry> - <entry><link linkend="ghci-stmts">Turn on printing of binding results in GHCi</link></entry> - <entry>dynamic</entry> - <entry><option>-fno-print-bind-result</option></entry> - </row> - <row> - <entry><option>-fno-print-bind-contents</option></entry> - <entry><link linkend="breakpoints">Turn off printing of binding contents in GHCi</link></entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-fno-implicit-import-qualified</option></entry> - <entry><link linkend="ghci-import-qualified">Turn off - implicit qualified import of everything in GHCi</link></entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-interactive-print</option></entry> - <entry><link linkend="ghci-interactive-print">Select the function - to use for printing evaluated expressions in GHCi</link></entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Packages</title> - - <para><xref linkend="packages"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-this-package-key</option> <replaceable>P</replaceable></entry> - <entry>Compile to be part of package <replaceable>P</replaceable></entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-package</option> <replaceable>P</replaceable></entry> - <entry>Expose package <replaceable>P</replaceable></entry> - <entry>dynamic/<literal>:set</literal></entry> - <entry>-</entry> - </row> - <row> - <entry><option>-hide-all-packages</option></entry> - <entry>Hide all packages by default</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-hide-package</option> <replaceable>name</replaceable></entry> - <entry>Hide package <replaceable>P</replaceable></entry> - <entry>dynamic/<literal>:set</literal></entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ignore-package</option> <replaceable>name</replaceable></entry> - <entry>Ignore package <replaceable>P</replaceable></entry> - <entry>dynamic/<literal>:set</literal></entry> - <entry>-</entry> - </row> - <row> - <entry><option>-package-db</option> <replaceable>file</replaceable></entry> - <entry>Add <replaceable>file</replaceable> to the package db stack.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-clear-package-db</option></entry> - <entry>Clear the package db stack.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-no-global-package-db</option></entry> - <entry>Remove the global package db from the stack.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-global-package-db</option></entry> - <entry>Add the global package db to the stack.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-no-user-package-db</option></entry> - <entry>Remove the user's package db from the stack.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-user-package-db</option></entry> - <entry>Add the user's package db to the stack.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-no-auto-link-packages</option></entry> - <entry>Don't automatically link in the base and rts packages.</entry> - <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>dynamic/<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>dynamic/<literal>:set</literal></entry> - <entry>-</entry> - </row> - <row> - <entry><option>-distrust-all</option> </entry> - <entry>Distrust all packages by default</entry> - <entry>dynamic/<literal>:set</literal></entry> - <entry>-</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Language options</title> - - <para>Language options can be enabled either by a command-line option - <option>-Xblah</option>, or by a <literal>{-# LANGUAGE blah #-}</literal> - pragma in the file itself. See <xref linkend="options-language"/>. Some - options are enabled using <option>-f*</option> flags.</para> - - <informaltable> - <tgroup cols="5" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - <entry>Since</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-fconstraint-solver-iterations=</option><replaceable>n</replaceable></entry> - <entry>Set the iteration limit for the type-constraint solver. - The default limit is 4. Typically one iteration - suffices; so please yell if you find you need to set - it higher than the default. Zero means infinity. </entry> - <entry>dynamic</entry> - <entry></entry> - </row> - <row> - <entry><option>-freduction-depth=</option><replaceable>n</replaceable></entry> - <entry>Set the <link linkend="undecidable-instances">limit for type simplification</link>. - Default is 200; zero means infinity.</entry> - <entry>dynamic</entry> - <entry></entry> - </row> - <row> - <entry><option>-fcontext-stack=</option><replaceable>n</replaceable></entry> - <entry>Deprecated. Use <option>-freduction-depth=</option><replaceable>n</replaceable> instead.</entry> - <entry>dynamic</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry><option>-fglasgow-exts</option></entry> - <entry>Deprecated. Enable most language extensions; see <xref linkend="options-language"/> for exactly which ones.</entry> - <entry>dynamic</entry> - <entry><option>-fno-glasgow-exts</option></entry> - <entry></entry> - </row> - <row> - <entry><option>-firrefutable-tuples</option></entry> - <entry>Make tuple pattern matching irrefutable</entry> - <entry>dynamic</entry> - <entry><option>-fno-irrefutable-tuples</option></entry> - <entry></entry> - </row> - <row> - <entry><option>-fpackage-trust</option></entry> - <entry>Enable <link linkend="safe-haskell">Safe Haskell</link> trusted package requirement for trustworthy modules.</entry> - <entry>dynamic</entry> - <entry><option>-</option></entry> - <entry></entry> - </row> - <row> - <entry><option>-ftype-function-depth=</option><replaceable>n</replaceable></entry> - <entry>Deprecated. Use <option>-freduction-depth=</option><replaceable>n</replaceable> instead.</entry> - <entry>dynamic</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry><option>-XAllowAmbiguousTypes</option></entry> - <entry>Allow the user to write <link linkend="ambiguity">ambiguous types</link>, - and the type inference engine to infer them. - </entry> - <entry>dynamic</entry> - <entry><option>-XNoAllowAmbiguousTypes</option></entry> - <entry>7.8.1</entry> - </row> - <row> - <entry><option>-XArrows</option></entry> - <entry>Enable <link linkend="arrow-notation">arrow - notation</link> extension</entry> - <entry>dynamic</entry> - <entry><option>-XNoArrows</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XApplicativeDo</option></entry> - <entry>Enable <link linkend="applicative-do">Applicative - do-notation desugaring</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoApplicativeDo</option></entry> - <entry>7.12.1</entry> - </row> - <row> - <entry><option>-XAutoDeriveTypeable</option></entry> - <entry>As of GHC 7.10, this option is not needed, and should - not be used. Automatically <link linkend="deriving-typeable">derive Typeable instances for every datatype and type class declaration</link>. - Implies <option>-XDeriveDataTypeable</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoAutoDeriveTypeable</option></entry> - <entry>7.8.1</entry> - </row> - <row> - <entry><option>-XBangPatterns</option></entry> - <entry>Enable <link linkend="bang-patterns">bang patterns</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoBangPatterns</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XBinaryLiterals</option></entry> - <entry>Enable support for <link linkend="binary-literals">binary literals</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoBinaryLiterals</option></entry> - <entry>7.10.1</entry> - </row> - <row> - <entry><option>-XCApiFFI</option></entry> - <entry>Enable <link linkend="ffi-capi">the CAPI calling convention</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoCAPIFFI</option></entry> - <entry>7.10.1</entry> - </row> - <row> - <entry><option>-XConstrainedClassMethods</option></entry> - <entry>Enable <link linkend="class-method-types">constrained class methods</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoConstrainedClassMethods</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XConstraintKinds</option></entry> - <entry>Enable a <link linkend="constraint-kind">kind of constraints</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoConstraintKinds</option></entry> - <entry>7.4.1</entry> - </row> - <row> - <entry><option>-XCPP</option></entry> - <entry>Enable the <link linkend="c-pre-processor">C preprocessor</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoCPP</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XDataKinds</option></entry> - <entry>Enable <link linkend="promotion">datatype promotion</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoDataKinds</option></entry> - <entry>7.4.1</entry> - </row> - <row> - <entry><option>-XDefaultSignatures</option></entry> - <entry>Enable <link linkend="class-default-signatures">default signatures</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoDefaultSignatures</option></entry> - <entry>7.2.1</entry> - </row> - <row> - <entry><option>-XDeriveAnyClass</option></entry> - <entry>Enable <link linkend="derive-any-class">deriving for any - class</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoDeriveAnyClass</option></entry> - <entry>7.10.1</entry> - </row> - <row> - <entry><option>-XDeriveDataTypeable</option></entry> - <entry>Enable <link linkend="deriving-typeable">deriving for the Data class</link>. - Implied by <option>-XAutoDeriveTypeable</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoDeriveDataTypeable</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XDeriveFunctor</option></entry> - <entry>Enable <link linkend="deriving-extra">deriving for the Functor class</link>. - Implied by <option>-XDeriveTraversable</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoDeriveFunctor</option></entry> - <entry>7.10.1</entry> - </row> - <row> - <entry><option>-XDeriveFoldable</option></entry> - <entry>Enable <link linkend="deriving-extra">deriving for the Foldable class</link>. - Implied by <option>-XDeriveTraversable</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoDeriveFoldable</option></entry> - <entry>7.10.1</entry> - </row> - <row> - <entry><option>-XDeriveGeneric</option></entry> - <entry>Enable <link linkend="deriving-typeable">deriving for the Generic class</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoDeriveGeneric</option></entry> - <entry>7.2.1</entry> - </row> - <row> - <entry><option>-XDeriveLift</option></entry> - <entry>Enable <link linkend="deriving-lift">deriving for the Lift class</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoDeriveLift</option></entry> - </row> - <row> - <entry><option>-XDeriveTraversable</option></entry> - <entry>Enable <link linkend="deriving-extra">deriving for the Traversable class</link>. - Implies <option>-XDeriveFunctor</option> and <option>-XDeriveFoldable</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoDeriveTraversable</option></entry> - <entry>7.10.1</entry> - </row> - <row> - <entry><option>-XDisambiguateRecordFields</option></entry> - <entry>Enable <link linkend="disambiguate-fields">record field disambiguation</link>. - Implied by <option>-XRecordWildCards</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoDisambiguateRecordFields</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XEmptyCase</option></entry> - <entry>Allow <link linkend="empty-case">empty case alternatives</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoEmptyCase</option></entry> - <entry>7.8.1</entry> - </row> - <row> - <entry><option>-XEmptyDataDecls</option></entry> - <entry>Enable empty data declarations.</entry> - <entry>dynamic</entry> - <entry><option>-XNoEmptyDataDecls</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XExistentialQuantification</option></entry> - <entry>Enable <link linkend="existential-quantification">existential quantification</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoExistentialQuantification</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XExplicitForAll</option></entry> - <entry>Enable <link linkend="explicit-foralls">explicit universal quantification</link>. - Implied by <option>-XScopedTypeVariables</option>, - <option>-XLiberalTypeSynonyms</option>, - <option>-XRankNTypes</option> and - <option>-XExistentialQuantification</option>. - </entry> - <entry>dynamic</entry> - <entry><option>-XNoExplicitForAll</option></entry> - <entry>6.12.1</entry> - </row> - <row> - <entry><option>-XExplicitNamespaces</option></entry> - <entry>Enable using the keyword <literal>type</literal> to specify the namespace of - entries in imports and exports (<xref linkend="explicit-namespaces"/>). - Implied by <option>-XTypeOperators</option> and <option>-XTypeFamilies</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoExplicitNamespaces</option></entry> - <entry>7.6.1</entry> - </row> - <row> - <entry><option>-XExtendedDefaultRules</option></entry> - <entry>Use GHCi's <link linkend="extended-default-rules">extended default rules</link> in a normal module.</entry> - <entry>dynamic</entry> - <entry><option>-XNoExtendedDefaultRules</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XFlexibleContexts</option></entry> - <entry>Enable <link linkend="flexible-contexts">flexible contexts</link>. - Implied by <option>-XImplicitParams</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoFlexibleContexts</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XFlexibleInstances</option></entry> - <entry>Enable <link linkend="instance-rules">flexible instances</link>. - Implies <option>-XTypeSynonymInstances</option>. Implied by <option>-XImplicitParams</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoFlexibleInstances</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XForeignFunctionInterface</option></entry> - <entry>Enable <link linkend="ffi">foreign function interface</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoForeignFunctionInterface</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XFunctionalDependencies</option></entry> - <entry>Enable <link linkend="functional-dependencies">functional dependencies</link>. - Implies <option>-XMultiParamTypeClasses</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoFunctionalDependencies</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XGADTs</option></entry> - <entry>Enable <link linkend="gadt">generalised algebraic data types</link>. - Implies <option>-XGADTSyntax</option> and <option>-XMonoLocalBinds</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoGADTs</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XGADTSyntax</option></entry> - <entry>Enable <link linkend="gadt-style">generalised algebraic data type syntax</link>. - </entry> - <entry>dynamic</entry> - <entry><option>-XNoGADTSyntax</option></entry> - <entry>7.2.1</entry> - </row> - <row> - <entry><option>-XGeneralizedNewtypeDeriving</option></entry> - <entry>Enable <link linkend="newtype-deriving">newtype deriving</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoGeneralizedNewtypeDeriving</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XGenerics</option></entry> - <entry>Deprecated, does nothing. No longer enables <link linkend="generic-classes">generic classes</link>. - See also GHC's support for - <link linkend="generic-programming">generic programming</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoGenerics</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XImplicitParams</option></entry> - <entry>Enable <link linkend="implicit-parameters">Implicit Parameters</link>. - Implies <option>-XFlexibleContexts</option> and <option>-XFlexibleInstances</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoImplicitParams</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XNoImplicitPrelude</option></entry> - <entry>Don't implicitly <literal>import Prelude</literal>. - Implied by <option>-XRebindableSyntax</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XImplicitPrelude</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XImpredicativeTypes</option></entry> - <entry>Enable <link linkend="impredicative-polymorphism">impredicative types</link>. - Implies <option>-XRankNTypes</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoImpredicativeTypes</option></entry> - <entry>6.10.1</entry> - </row> - <row> - <entry><option>-XIncoherentInstances</option></entry> - <entry>Enable <link linkend="instance-overlap">incoherent instances</link>. - Implies <option>-XOverlappingInstances</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoIncoherentInstances</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XInstanceSigs</option></entry> - <entry>Enable <link linkend="instance-sigs">instance signatures</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoInstanceSigs</option></entry> - <entry>7.10.1</entry> - </row> - <row> - <entry><option>-XInterruptibleFFI</option></entry> - <entry>Enable interruptible FFI.</entry> - <entry>dynamic</entry> - <entry><option>-XNoInterruptibleFFI</option></entry> - <entry>7.2.1</entry> - </row> - <row> - <entry><option>-XKindSignatures</option></entry> - <entry>Enable <link linkend="kinding">kind signatures</link>. - Implied by <option>-XTypeFamilies</option> and <option>-XPolyKinds</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoKindSignatures</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XLambdaCase</option></entry> - <entry>Enable <link linkend="lambda-case">lambda-case expressions</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoLambdaCase</option></entry> - <entry>7.6.1</entry> - </row> - <row> - <entry><option>-XLiberalTypeSynonyms</option></entry> - <entry>Enable <link linkend="type-synonyms">liberalised type synonyms</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoLiberalTypeSynonyms</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XMagicHash</option></entry> - <entry>Allow "#" as a <link linkend="magic-hash">postfix modifier on identifiers</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoMagicHash</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XMonadComprehensions</option></entry> - <entry>Enable <link linkend="monad-comprehensions">monad comprehensions</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoMonadComprehensions</option></entry> - <entry>7.2.1</entry> - </row> - <row> - <entry><option>-XMonoLocalBinds</option></entry> - <entry>Enable <link linkend="mono-local-binds">do not generalise local bindings</link>. - Implied by <option>-XTypeFamilies</option> and <option>-XGADTs</option>. - </entry> - <entry>dynamic</entry> - <entry><option>-XNoMonoLocalBinds</option></entry> - <entry>6.12.1</entry> - </row> - <row> - <entry><option>-XNoMonomorphismRestriction</option></entry> - <entry>Disable the <link linkend="monomorphism">monomorphism restriction</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XMonomorphismRestriction</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XMultiParamTypeClasses</option></entry> - <entry>Enable <link linkend="multi-param-type-classes">multi parameter type classes</link>. - Implied by <option>-XFunctionalDependencies</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoMultiParamTypeClasses</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XMultiWayIf</option></entry> - <entry>Enable <link linkend="multi-way-if">multi-way if-expressions</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoMultiWayIf</option></entry> - <entry>7.6.1</entry> - </row> - <row> - <entry><option>-XNamedFieldPuns</option></entry> - <entry>Enable <link linkend="record-puns">record puns</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoNamedFieldPuns</option></entry> - <entry>6.10.1</entry> - </row> - <row> - <entry><option>-XNamedWildCards</option></entry> - <entry>Enable <link linkend="named-wildcards">named wildcards</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoNamedWildCards</option></entry> - <entry>7.10.1</entry> - </row> - <row> - <entry><option>-XNegativeLiterals</option></entry> - <entry>Enable support for <link linkend="negative-literals">negative literals</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoNegativeLiterals</option></entry> - <entry>7.8.1</entry> - </row> - <row> - <entry><option>-XNoNPlusKPatterns</option></entry> - <entry>Disable support for <literal>n+k</literal> patterns.</entry> - <entry>dynamic</entry> - <entry><option>-XNPlusKPatterns</option></entry> - <entry>6.12.1</entry> - </row> - <row> - <entry><option>-XNullaryTypeClasses</option></entry> - <entry>Deprecated, does nothing. <link linkend="nullary-type-classes">nullary (no parameter) type classes</link> are now enabled using <option>-XMultiParamTypeClasses</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoNullaryTypeClasses</option></entry> - <entry>7.8.1</entry> - </row> - <row> - <entry><option>-XNumDecimals</option></entry> - <entry>Enable support for 'fractional' integer literals.</entry> - <entry>dynamic</entry> - <entry><option>-XNoNumDecimals</option></entry> - <entry>7.8.1</entry> - </row> - <row> - <entry><option>-XOverlappingInstances</option></entry> - <entry>Enable <link linkend="instance-overlap">overlapping instances</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoOverlappingInstances</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XOverloadedLists</option></entry> - <entry>Enable <link linkend="overloaded-lists">overloaded lists</link>. - </entry> - <entry>dynamic</entry> - <entry><option>-XNoOverloadedLists</option></entry> - <entry>7.8.1</entry> - </row> - <row> - <entry><option>-XOverloadedStrings</option></entry> - <entry>Enable <link linkend="overloaded-strings">overloaded string literals</link>. - </entry> - <entry>dynamic</entry> - <entry><option>-XNoOverloadedStrings</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XPackageImports</option></entry> - <entry>Enable <link linkend="package-imports">package-qualified imports</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoPackageImports</option></entry> - <entry>6.10.1</entry> - </row> - <row> - <entry><option>-XParallelArrays</option></entry> - <entry>Enable parallel arrays. - Implies <option>-XParallelListComp</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoParallelArrays</option></entry> - <entry>7.4.1</entry> - </row> - <row> - <entry><option>-XParallelListComp</option></entry> - <entry>Enable <link linkend="parallel-list-comprehensions">parallel list comprehensions</link>. - Implied by <option>-XParallelArrays</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoParallelListComp</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XPartialTypeSignatures</option></entry> - <entry>Enable <link linkend="partial-type-signatures">partial type signatures</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoPartialTypeSignatures</option></entry> - <entry>7.10.1</entry> - </row> - <row> - <entry><option>-XPatternGuards</option></entry> - <entry>Enable <link linkend="pattern-guards">pattern guards</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoPatternGuards</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XPatternSynonyms</option></entry> - <entry>Enable <link linkend="pattern-synonyms">pattern synonyms</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoPatternSynonyms</option></entry> - <entry>7.10.1</entry> - </row> - <row> - <entry><option>-XPolyKinds</option></entry> - <entry>Enable <link linkend="kind-polymorphism">kind polymorphism</link>. - Implies <option>-XKindSignatures</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoPolyKinds</option></entry> - <entry>7.4.1</entry> - </row> - <row> - <entry><option>-XPolymorphicComponents</option></entry> - <entry>Enable <link linkend="universal-quantification">polymorphic components for data constructors</link>.</entry> - <entry>dynamic, synonym for <option>-XRankNTypes</option></entry> - <entry><option>-XNoPolymorphicComponents</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XPostfixOperators</option></entry> - <entry>Enable <link linkend="postfix-operators">postfix operators</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoPostfixOperators</option></entry> - <entry>7.10.1</entry> - </row> - <row> - <entry><option>-XQuasiQuotes</option></entry> - <entry>Enable <link linkend="th-quasiquotation">quasiquotation</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoQuasiQuotes</option></entry> - <entry>6.10.1</entry> - </row> - <row> - <entry><option>-XRank2Types</option></entry> - <entry>Enable <link linkend="universal-quantification">rank-2 types</link>.</entry> - <entry>dynamic, synonym for <option>-XRankNTypes</option></entry> - <entry><option>-XNoRank2Types</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XRankNTypes</option></entry> - <entry>Enable <link linkend="universal-quantification">rank-N types</link>. - Implied by <option>-XImpredicativeTypes</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoRankNTypes</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XRebindableSyntax</option></entry> - <entry>Employ <link linkend="rebindable-syntax">rebindable syntax</link>. - Implies <option>-XNoImplicitPrelude</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoRebindableSyntax</option></entry> - <entry>7.0.1</entry> - </row> - <row> - <entry><option>-XRecordWildCards</option></entry> - <entry>Enable <link linkend="record-wildcards">record wildcards</link>. - Implies <option>-XDisambiguateRecordFields</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoRecordWildCards</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XRecursiveDo</option></entry> - <entry>Enable <link linkend="recursive-do-notation">recursive do (mdo) notation</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoRecursiveDo</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XRelaxedPolyRec</option></entry> - <entry><emphasis>(deprecated)</emphasis> Relaxed checking for - <link linkend="typing-binds">mutually-recursive polymorphic functions</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoRelaxedPolyRec</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XRoleAnnotations</option></entry> - <entry>Enable <link linkend="role-annotations">role annotations</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoRoleAnnotations</option></entry> - <entry>7.10.1</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> - <entry>7.2.1</entry> - </row> - <row> - <entry><option>-XScopedTypeVariables</option></entry> - <entry>Enable <link linkend="scoped-type-variables">lexically-scoped type variables</link>. - </entry> - <entry>dynamic</entry> - <entry><option>-XNoScopedTypeVariables</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XStandaloneDeriving</option></entry> - <entry>Enable <link linkend="stand-alone-deriving">standalone deriving</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoStandaloneDeriving</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XStrictData</option></entry> - <entry>Enable <link linkend="strict-data">default strict datatype fields</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoStrictData</option></entry> - </row> - <row> - <entry><option>-XTemplateHaskell</option></entry> - <entry>Enable <link linkend="template-haskell">Template Haskell</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoTemplateHaskell</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XNoTraditionalRecordSyntax</option></entry> - <entry>Disable support for traditional record syntax (as supported by Haskell 98) <literal>C {f = x}</literal></entry> - <entry>dynamic</entry> - <entry><option>-XTraditionalRecordSyntax</option></entry> - <entry>7.4.1</entry> - </row> - <row> - <entry><option>-XTransformListComp</option></entry> - <entry>Enable <link linkend="generalised-list-comprehensions">generalised list comprehensions</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoTransformListComp</option></entry> - <entry>6.10.1</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> - <entry>7.2.1</entry> - </row> - <row> - <entry><option>-XTupleSections</option></entry> - <entry>Enable <link linkend="tuple-sections">tuple sections</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoTupleSections</option></entry> - <entry>7.10.1</entry> - </row> - <row> - <entry><option>-XTypeFamilies</option></entry> - <entry>Enable <link linkend="type-families">type families</link>. - Implies <option>-XExplicitNamespaces</option>, <option>-XKindSignatures</option> - and <option>-XMonoLocalBinds</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoTypeFamilies</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XTypeOperators</option></entry> - <entry>Enable <link linkend="type-operators">type operators</link>. - Implies <option>-XExplicitNamespaces</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoTypeOperators</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XTypeSynonymInstances</option></entry> - <entry>Enable <link linkend="flexible-instance-head">type synonyms in instance heads</link>. - Implied by <option>-XFlexibleInstances</option>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoTypeSynonymInstances</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XUnboxedTuples</option></entry> - <entry>Enable <link linkend="unboxed-tuples">unboxed tuples</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoUnboxedTuples</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XUndecidableInstances</option></entry> - <entry>Enable <link linkend="undecidable-instances">undecidable instances</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoUndecidableInstances</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XUnicodeSyntax</option></entry> - <entry>Enable <link linkend="unicode-syntax">unicode syntax</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoUnicodeSyntax</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XUnliftedFFITypes</option></entry> - <entry>Enable unlifted FFI types.</entry> - <entry>dynamic</entry> - <entry><option>-XNoUnliftedFFITypes</option></entry> - <entry>6.8.1</entry> - </row> - <row> - <entry><option>-XUnsafe</option></entry> - <entry>Enable <link linkend="safe-haskell">Safe Haskell</link> Unsafe mode.</entry> - <entry>dynamic</entry> - <entry><option>-</option></entry> - <entry>7.4.1</entry> - </row> - <row> - <entry><option>-XViewPatterns</option></entry> - <entry>Enable <link linkend="view-patterns">view patterns</link>.</entry> - <entry>dynamic</entry> - <entry><option>-XNoViewPatterns</option></entry> - <entry>6.10.1</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Warnings</title> - - <para><xref linkend="options-sanity"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-W</option></entry> - <entry>enable normal warnings</entry> - <entry>dynamic</entry> - <entry><option>-w</option></entry> - </row> - <row> - <entry><option>-w</option></entry> - <entry>disable all warnings</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-Wall</option></entry> - <entry>enable almost all warnings (details in <xref linkend="options-sanity"/>)</entry> - <entry>dynamic</entry> - <entry><option>-w</option></entry> - </row> - <row> - <entry><option>-Werror</option></entry> - <entry>make warnings fatal</entry> - <entry>dynamic</entry> - <entry>-Wwarn</entry> - </row> - <row> - <entry><option>-Wwarn</option></entry> - <entry>make warnings non-fatal</entry> - <entry>dynamic</entry> - <entry>-Werror</entry> - </row> - - <row> - <entry><option>-fdefer-type-errors</option></entry> - <entry> - Turn type errors into warnings, <link linkend="defer-type-errors"> - deferring the error until runtime</link>. Implies - <option>-fdefer-typed-holes</option>. See also - <option>-fwarn-deferred-type-errors</option> - </entry> - <entry>dynamic</entry> - <entry><option>-fno-defer-type-errors</option></entry> - </row> - - <row> - <entry><option>-fdefer-typed-holes</option></entry> - <entry> - Convert <link linkend="typed-holes">typed hole</link> errors - into warnings, <link linkend="defer-type-errors">deferring the - error until runtime</link>. Implied by - <option>-fdefer-type-errors</option>. See also - <option>-fwarn-typed-holes</option>. - </entry> - <entry>dynamic</entry> - <entry><option>-fno-defer-typed-holes</option></entry> - </row> - - <row> - <entry><option>-fhelpful-errors</option></entry> - <entry>Make suggestions for mis-spelled names.</entry> - <entry>dynamic</entry> - <entry><option>-fno-helpful-errors</option></entry> - </row> - - <row> - <entry><option>-fwarn-deprecated-flags</option></entry> - <entry>warn about uses of commandline flags that are deprecated</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-deprecated-flags</option></entry> - </row> - - <row> - <entry><option>-fwarn-duplicate-constraints</option></entry> - <entry>warn when a constraint appears duplicated in a type signature</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-duplicate-constraints</option></entry> - </row> - - <row> - <entry><option>-fwarn-duplicate-exports</option></entry> - <entry>warn when an entity is exported multiple times</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-duplicate-exports</option></entry> - </row> - - <row> - <entry><option>-fwarn-hi-shadowing</option></entry> - <entry>warn when a <literal>.hi</literal> file in the - current directory shadows a library</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-hi-shadowing</option></entry> - </row> - - <row> - <entry><option>-fwarn-identities</option></entry> - <entry>warn about uses of Prelude numeric conversions that are probably - the identity (and hence could be omitted)</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-identities</option></entry> - </row> - - <row> - <entry><option>-fwarn-implicit-prelude</option></entry> - <entry>warn when the Prelude is implicitly imported</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-implicit-prelude</option></entry> - </row> - - <row> - <entry><option>-fwarn-incomplete-patterns</option></entry> - <entry>warn when a pattern match could fail</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-incomplete-patterns</option></entry> - </row> - - <row> - <entry><option>-fwarn-incomplete-uni-patterns</option></entry> - <entry>warn when a pattern match in a lambda expression or pattern binding could fail</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-incomplete-uni-patterns</option></entry> - </row> - - <row> - <entry><option>-fwarn-incomplete-record-updates</option></entry> - <entry>warn when a record update could fail</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-incomplete-record-updates</option></entry> - </row> - - <row> - <entry><option>-fwarn-lazy-unlifted-bindings</option></entry> - <entry><emphasis>(deprecated)</emphasis> warn when a pattern binding looks lazy but must be strict</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-lazy-unlifted-bindings</option></entry> - </row> - - <row> - <entry><option>-fwarn-missing-fields</option></entry> - <entry>warn when fields of a record are uninitialised</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-missing-fields</option></entry> - </row> - - <row> - <entry><option>-fwarn-missing-import-lists</option></entry> - <entry>warn when an import declaration does not explicitly - list all the names brought into scope</entry> - <entry>dynamic</entry> - <entry><option>-fnowarn-missing-import-lists</option></entry> - </row> - - <row> - <entry><option>-fwarn-missing-methods</option></entry> - <entry>warn when class methods are undefined</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-missing-methods</option></entry> - </row> - - <row> - <entry><option>-fwarn-missing-signatures</option></entry> - <entry>warn about top-level functions without signatures</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-missing-signatures</option></entry> - </row> - - <row> - <entry><option>-fwarn-missing-exported-sigs</option></entry> - <entry>warn about top-level functions without signatures, only if they are exported. takes precedence over -fwarn-missing-signatures</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-missing-exported-sigs</option></entry> - </row> - - <row> - <entry><option>-fwarn-missing-local-sigs</option></entry> - <entry>warn about polymorphic local bindings without signatures</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-missing-local-sigs</option></entry> - </row> - - <row> - <entry><option>-fwarn-monomorphism-restriction</option></entry> - <entry>warn when the Monomorphism Restriction is applied</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-monomorphism-restriction</option></entry> - </row> - - <row> - <entry><option>-fwarn-name-shadowing</option></entry> - <entry>warn when names are shadowed</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-name-shadowing</option></entry> - </row> - - <row> - <entry><option>-fwarn-orphans, -fwarn-auto-orphans</option></entry> - <entry>warn when the module contains <link linkend="orphan-modules">orphan instance declarations - or rewrite rules</link></entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-orphans, -fno-warn-auto-orphans</option></entry> - </row> - - <row> - <entry><option>-fwarn-overlapping-patterns</option></entry> - <entry>warn about overlapping patterns</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-overlapping-patterns</option></entry> - </row> - - <row> - <entry><option>-fwarn-tabs</option></entry> - <entry>warn if there are tabs in the source file</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-tabs</option></entry> - </row> - - <row> - <entry><option>-fwarn-type-defaults</option></entry> - <entry>warn when defaulting happens</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-type-defaults</option></entry> - </row> - - <row> - <entry><option>-fwarn-unrecognised-pragmas</option></entry> - <entry>warn about uses of pragmas that GHC doesn't recognise</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-unrecognised-pragmas</option></entry> - </row> - - <row> - <entry><option>-fwarn-unticked-promoted-constructors</option></entry> - <entry>warn if promoted constructors are not ticked </entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-unticked-promoted-constructors</option></entry> - </row> - - <row> - <entry><option>-fwarn-unused-binds</option></entry> - <entry>warn about bindings that are unused. - Alias for <option>-fwarn-unused-top-binds</option>, - <option>-fwarn-unused-local-binds</option> and - <option>-fwarn-unused-pattern-binds</option></entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-unused-binds</option></entry> - </row> - - <row> - <entry><option>-fwarn-unused-top-binds</option></entry> - <entry>warn about top-level bindings that are unused</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-unused-top-binds</option></entry> - </row> - - <row> - <entry><option>-fwarn-unused-local-binds</option></entry> - <entry>warn about local bindings that are unused</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-unused-local-binds</option></entry> - </row> - - <row> - <entry><option>-fwarn-unused-pattern-binds</option></entry> - <entry>warn about pattern match bindings that are unused</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-unused-pattern-binds</option></entry> - </row> - - <row> - <entry><option>-fwarn-unused-imports</option></entry> - <entry>warn about unnecessary imports</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-unused-imports</option></entry> - </row> - - <row> - <entry><option>-fwarn-unused-matches</option></entry> - <entry>warn about variables in patterns that aren't used</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-unused-matches</option></entry> - </row> - - <row> - <entry><option>-fwarn-unused-do-bind</option></entry> - <entry>warn about do bindings that appear to throw away values of types other than <literal>()</literal></entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-unused-do-bind</option></entry> - </row> - - <row> - <entry><option>-fwarn-wrong-do-bind</option></entry> - <entry>warn about do bindings that appear to throw away monadic values that you should have bound instead</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-wrong-do-bind</option></entry> - </row> - - <row> - <entry><option>-fwarn-unsafe</option></entry> - <entry>warn if the module being compiled is regarded to be unsafe. - Should be used to check the safety status of modules when using safe - inference. Works on all module types, even those using explicit - <link linkend="safe-haskell">Safe Haskell</link> modes (such as - <option>-XTrustworthy</option>) and so can be used to have the - compiler check any assumptions made.</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-unsafe</option></entry> - </row> - - <row> - <entry><option>-fwarn-safe</option></entry> - <entry>warn if the module being compiled is regarded to be safe. - Should be used to check the safety status of modules when using safe - inference. Works on all module types, even those using explicit - <link linkend="safe-haskell">Safe Haskell</link> modes (such as - <option>-XTrustworthy</option>) and so can be used to have the - compiler check any assumptions made.</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-safe</option></entry> - </row> - - <row> - <entry><option>-fwarn-trustworthy-safe</option></entry> - <entry>warn if the module being compiled is marked as - <option>-XTrustworthy</option> but it could instead be marked as - <option>-XSafe</option>, a more informative bound. Can be used to - detect once a Safe Haskell bound can be improved as dependencies - are updated.</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-safe</option></entry> - </row> - - <row> - <entry><option>-fwarn-warnings-deprecations</option></entry> - <entry>warn about uses of functions & types that have warnings or deprecated pragmas</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-warnings-deprecations</option></entry> - </row> - - <row> - <entry><option>-fwarn-amp</option></entry> - <entry><emphasis>(deprecated)</emphasis> warn on definitions conflicting with the Applicative-Monad Proposal (AMP)</entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-amp</option></entry> - </row> - - <row> - <entry><option>-fwarn-deferred-type-errors</option></entry> - <entry> - Report warnings when <link linkend="defer-type-errors">deferred type errors</link> - are enabled. This option is enabled by default. See <option>-fdefer-type-errors</option>. - </entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-deferred-type-errors</option></entry> - </row> - - <row> - <entry><option>-fwarn-typed-holes</option></entry> - <entry> - Report warnings when <link linkend="typed-holes">typed hole</link> - errors are <link linkend="defer-type-errors">deferred until - runtime</link>. See <option>-fdefer-typed-holes</option>. - </entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-typed-holes</option></entry> - </row> - - <row> - <entry><option>-fwarn-partial-type-signatures</option></entry> - <entry> - warn about holes in partial type signatures when - <option>-XPartialTypesignatures</option> is enabled. Not - applicable when <option>-XPartialTypesignatures</option> is not - enabled, in which case errors are generated for such holes. - See <xref linkend="partial-type-signatures"/>. - </entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-partial-type-signatures</option></entry> - </row> - - <row> - <entry><option>-fwarn-deriving-typeable</option></entry> - <entry> - warn when encountering a request to derive an instance of - class <literal>Typeable</literal>. As of GHC 7.10, such - declarations are unnecessary and are ignored by the compiler - because GHC has a custom solver for discharging this type of - constraint. - </entry> - <entry>dynamic</entry> - <entry><option>-fno-warn-deriving-typeable</option></entry> - </row> - - - </tbody> - </tgroup> - </informaltable> - - </sect2> - <sect2> - <title>Optimisation levels</title> - - <para>These options are described in more detail in <xref linkend="options-optimise"/>.</para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-O0</option></entry> - <entry>Disable optimisations (default)</entry> - <entry>dynamic</entry> - <entry><option>-O</option></entry> - </row> - <row> - <entry><option>-O</option> or <option>-O1</option></entry> - <entry>Enable level 1 optimisations</entry> - <entry>dynamic</entry> - <entry><option>-O0</option></entry> - </row> - <row> - <entry><option>-O2</option></entry> - <entry>Enable level 2 optimisations</entry> - <entry>dynamic</entry> - <entry><option>-O0</option></entry> - </row> - <row> - <entry><option>-Odph</option></entry> - <entry>Enable level 2 optimisations, set <option>-fmax-simplifier-iterations=20</option> - and <option>-fsimplifier-phases=3</option>.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>See <xref linkend="options-f-compact"/> for a list of optimisations enabled on level 1 and level 2.</para> - - </sect2> - <sect2 id="options-f-compact"> - <title>Individual optimisations</title> - - <para>These options are described in more detail in <xref linkend="options-f"/>. - If a flag is implied by <option>-O</option> then it is also implied by - <option>-O2</option> (unless flag description explicitly says otherwise). - If a flag is implied by <option>-O0</option> only then the flag is not - implied by <option>-O</option> and <option>-O2</option>. - </para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-fcall-arity</option></entry> - <entry>Enable call-arity optimisation. Implied by <option>-O</option>.</entry> - <entry>dynamic</entry> - <entry><option>-fno-call-arity</option></entry> - </row> - - <row> - <entry><option>-fcase-merge</option></entry> - <entry>Enable case-merging. Implied by <option>-O</option>.</entry> - <entry>dynamic</entry> - <entry><option>-fno-case-merge</option></entry> - </row> - - <row> - <entry><option>-fcmm-elim-common-blocks</option></entry> - <entry>Enable Cmm common block elimination. Implied by <option>-O</option>.</entry> - <entry>dynamic</entry> - <entry><option>-fno-cmm-elim-common-blocks</option></entry> - </row> - - <row> - <entry><option>-fcmm-sink</option></entry> - <entry>Enable Cmm sinking. Implied by <option>-O</option>.</entry> - <entry>dynamic</entry> - <entry><option>-fno-cmm-sink</option></entry> - </row> - - <row> - <entry><option>-fcpr-anal</option></entry> - <entry>Turn on CPR analysis in the demand analyser. Implied by - <option>-O</option>.</entry> - <entry>dynamic</entry> - <entry><option>-fno-cpr-anal</option></entry> - </row> - - <row> - <entry><option>-fcse</option></entry> - <entry>Enable common sub-expression elimination. Implied by <option>-O</option>.</entry> - <entry>dynamic</entry> - <entry><option>-fno-cse</option></entry> - </row> - - <row> - <entry><option>-fdicts-cheap</option></entry> - <entry>Make dictionary-valued expressions seem cheap to the optimiser.</entry> - <entry>dynamic</entry> - <entry><option>-fno-dicts-cheap</option></entry> - </row> - - <row> - <entry><option>-fdicts-strict</option></entry> - <entry>Make dictionaries strict</entry> - <entry>dynamic</entry> - <entry><option>-fno-dicts-strict</option></entry> - </row> - - <row> - <entry><option>-fdmd-tx-dict-sel</option> - </entry> - <entry>Use a special demand transformer for dictionary selectors. - Always enabled by default. - </entry> - <entry>dynamic</entry> - <entry><option>-fno-dmd-tx-dict-sel</option></entry> - </row> - - <row> - <entry><option>-fdo-eta-reduction</option></entry> - <entry>Enable eta-reduction. Implied by <option>-O</option>.</entry> - <entry>dynamic</entry> - <entry><option>-fno-do-eta-reduction</option></entry> - </row> - - <row> - <entry><option>-fdo-lambda-eta-expansion</option></entry> - <entry>Enable lambda eta-expansion. Always enabled by default.</entry> - <entry>dynamic</entry> - <entry><option>-fno-do-lambda-eta-expansion</option></entry> - </row> - - <row> - <entry><option>-feager-blackholing</option></entry> - <entry>Turn on <link linkend="parallel-compile-options">eager blackholing</link></entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - - <row> - <entry><option>-fenable-rewrite-rules</option></entry> - <entry>Switch on all rewrite rules (including rules - generated by automatic specialisation of overloaded functions). - Implied by <option>-O</option>. </entry> - <entry>dynamic</entry> - <entry><option>-fno-enable-rewrite-rules</option></entry> - </row> - - <row> - <entry><option>-fexcess-precision</option></entry> - <entry>Enable excess intermediate precision</entry> - <entry>dynamic</entry> - <entry><option>-fno-excess-precision</option></entry> - </row> - - <row> - <entry><option>-fexpose-all-unfoldings</option></entry> - <entry>Expose all unfoldings, even for very large or recursive functions.</entry> - <entry>dynamic</entry> - <entry><option>-fno-expose-all-unfoldings</option></entry> - </row> - - <row> - <entry><option>-ffloat-in</option></entry> - <entry>Turn on the float-in transformation. Implied by <option>-O</option>.</entry> - <entry>dynamic</entry> - <entry><option>-fno-float-in</option></entry> - </row> - - <row> - <entry><option>-ffull-laziness</option></entry> - <entry>Turn on full laziness (floating bindings outwards). Implied by <option>-O</option>.</entry> - <entry>dynamic</entry> - <entry><option>-fno-full-laziness</option></entry> - </row> - - <row> - <entry><option>-ffun-to-thunk</option></entry> - <entry>Allow worker-wrapper to convert a function closure into a - thunk if the function does not use any of its arguments. Off by - default.</entry> - <entry>dynamic</entry> - <entry><option>-fno-fun-to-thunk</option></entry> - </row> - - <row> - <entry><option>-fignore-asserts</option></entry> - <entry>Ignore assertions in the source. Implied by <option>-O</option>.</entry> - <entry>dynamic</entry> - <entry><option>-fno-ignore-asserts</option></entry> - </row> - - <row> - <entry><option>-fignore-interface-pragmas</option></entry> - <entry>Ignore pragmas in interface files. Implied by <option>-O0</option> only.</entry> - <entry>dynamic</entry> - <entry><option>-fno-ignore-interface-pragmas</option></entry> - </row> - - <row> - <entry><option>-flate-dmd-anal</option></entry> - <entry>Run demand analysis again, at the end of the simplification - pipeline</entry> - <entry>dynamic</entry> - <entry><option>-fno-late-dmd-anal</option></entry> - </row> - - <row> - <entry><option>-fliberate-case</option></entry> - <entry>Turn on the liberate-case transformation. Implied by <option>-O2</option>.</entry> - <entry>dynamic</entry> - <entry>-fno-liberate-case</entry> - </row> - - <row> - <entry><option>-fliberate-case-threshold</option>=<replaceable>n</replaceable></entry> - <entry>Set the size threshold for the liberate-case transformation to <replaceable>n</replaceable> (default: 2000)</entry> - <entry>dynamic</entry> - <entry><option>-fno-liberate-case-threshold</option></entry> - </row> - - <row> - <entry><option>-floopification</option></entry> - <entry>Turn saturated self-recursive tail-calls into local jumps in the generated assembly. - Implied by <option>-O</option>.</entry> - <entry>dynamic</entry> - <entry><option>-fno-loopification</option></entry> - </row> - - <row> - <entry><option>-fmax-inline-alloc-size</option>=<replaceable>n</replaceable></entry> - <entry>Set the maximum size of inline array allocations to - <replaceable>n</replaceable> bytes (default: 128). GHC - will allocate non-pinned arrays of statically known size - in the current nursery block if they're no bigger than - <replaceable>n</replaceable> bytes, ignoring GC overheap. - This value should be quite a bit smaller than the block - size (typically: 4096).</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - - <row> - <entry> - <option>-fmax-inline-memcpy-insns</option>=<replaceable>n</replaceable> - </entry> - <entry>Inline <literal>memcpy</literal> calls if they would generate no more - than <replaceable>n</replaceable> pseudo instructions - (default: 32). - </entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - - <row> - <entry> - <option>-fmax-inline-memset-insns</option>=<replaceable>n</replaceable> - </entry> - <entry>Inline <literal>memset</literal> calls if they would generate no more - than <replaceable>n</replaceable> pseudo instructions - (default: 32). - </entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - - <row> - <entry><option>-fmax-relevant-binds=<replaceable>n</replaceable></option></entry> - <entry>Set the maximum number of bindings to display in type error messages (default 6).</entry> - <entry>dynamic</entry> - <entry><option>-fno-max-relevant-bindings</option></entry> - </row> - - <row> - <entry><option>-fmax-simplifier-iterations=<replaceable>n</replaceable></option></entry> - <entry>Set the max iterations for the simplifier (default 4).</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - - <row> - <entry><option>-fmax-worker-args=<replaceable>n</replaceable></option></entry> - <entry>If a worker has that many arguments, none will be - unpacked anymore (default: 10)</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - - <row> - <entry><option>-fno-opt-coercion</option></entry> - <entry>Turn off the coercion optimiser</entry> - <entry>static</entry> - <entry>-</entry> - </row> - - <row> - <entry><option>-fno-pre-inlining</option></entry> - <entry>Turn off pre-inlining</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - - <row> - <entry><option>-fno-state-hack</option></entry> - <entry>Turn off the "state hack" whereby any lambda with a real-world state token - as argument is considered to be single-entry. Hence OK to inline things inside it.</entry> - <entry>static</entry> - <entry>-</entry> - </row> - - <row> - <entry><option>-fomit-interface-pragmas</option></entry> - <entry>Don't generate interface pragmas. Implied by <option>-O0</option> only.</entry> - <entry>dynamic</entry> - <entry><option>-fno-omit-interface-pragmas</option></entry> - </row> - - <row> - <entry><option>-fomit-yields</option></entry> - <entry>Omit heap checks when no allocation is being performed.</entry> - <entry>dynamic</entry> - <entry><option>-fno-omit-yields</option></entry> - </row> - - <row> - <entry><option>-fpedantic-bottoms</option></entry> - <entry>Make GHC be more precise about its treatment of bottom (but see also - <option>-fno-state-hack</option>). In particular, GHC will not - eta-expand through a case expression.</entry> - <entry>dynamic</entry> - <entry><option>-fno-pedantic-bottoms</option></entry> - </row> - - <row> - <entry><option>-fregs-graph</option></entry> - <entry>Use the graph colouring register allocator for register allocation - in the native code generator. Implied by <option>-O2</option>.</entry> - <entry>dynamic</entry> - <entry><option>-fno-regs-graph</option></entry> - </row> - - <row> - <entry><option>-fregs-iterative</option></entry> - <entry>Use the iterative coalescing graph colouring register allocator - in the native code generator.</entry> - <entry>dynamic</entry> - <entry><option>-fno-regs-iterative</option></entry> - </row> - - <row> - <entry><option>-fsimplifier-phases=<replaceable>n</replaceable></option></entry> - <entry>Set the number of phases for the simplifier (default 2). - Ignored with <option>-O0</option>.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - - <row> - <entry><option>-fsimpl-tick-factor=<replaceable>n</replaceable></option></entry> - <entry>Set the percentage factor for simplifier ticks (default 100)</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - - <row> - <entry><option>-fspec-constr</option></entry> - <entry>Turn on the SpecConstr transformation. Implied by <option>-O2</option>.</entry> - <entry>dynamic</entry> - <entry><option>-fno-spec-constr</option></entry> - </row> - - <row> - <entry><option>-fspec-constr-count</option>=<replaceable>n</replaceable></entry> - <entry>Set to <replaceable>n</replaceable> (default: 3) the maximum number of - specialisations that will be created for any one function - by the SpecConstr transformation</entry> - <entry>dynamic</entry> - <entry><option>-fno-spec-constr-count</option></entry> - </row> - - <row> - <entry><option>-fspec-constr-threshold</option>=<replaceable>n</replaceable></entry> - <entry>Set the size threshold for the SpecConstr transformation - to <replaceable>n</replaceable> (default: 2000)</entry> - <entry>dynamic</entry> - <entry><option>-fno-spec-constr-threshold</option></entry> - </row> - - <row> - <entry><option>-fspecialise</option></entry> - <entry>Turn on specialisation of overloaded functions. Implied by <option>-O</option>.</entry> - <entry>dynamic</entry> - <entry><option>-fno-specialise</option></entry> - </row> - - <row> - <entry><option>-fcross-module-specialise</option></entry> - <entry>Turn on specialisation of overloaded functions imported from other modules.</entry> - <entry>dynamic</entry> - <entry><option>-fno-cross-module-specialise</option></entry> - </row> - - <row> - <entry><option>-fstatic-argument-transformation</option></entry> - <entry>Turn on the static argument transformation.</entry> - <entry>dynamic</entry> - <entry><option>-fno-static-argument-transformation</option></entry> - </row> - - <row> - <entry><option>-fstrictness</option></entry> - <entry>Turn on strictness analysis. Implied by <option>-O</option>.</entry> - <entry>dynamic</entry> - <entry><option>-fno-strictness</option></entry> - </row> - - <row> - <entry><option>-fstrictness-before</option>=<replaceable>n</replaceable></entry> - <entry>Run an additional strictness analysis before simplifier - phase <replaceable>n</replaceable></entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - - <row> - <entry><option>-funbox-small-strict-fields</option></entry> - <entry>Flatten strict constructor fields with a - pointer-sized representation. Implied by <option>-O</option>.</entry> - <entry>dynamic</entry> - <entry><option>-fno-unbox-small-strict-fields</option></entry> - </row> - - <row> - <entry><option>-funbox-strict-fields</option></entry> - <entry>Flatten strict constructor fields</entry> - <entry>dynamic</entry> - <entry><option>-fno-unbox-strict-fields</option></entry> - </row> - - <row> - <entry><option>-funfolding-creation-threshold=<replaceable>n</replaceable></option></entry> - <entry>Tweak unfolding settings. Default: 750</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - - <row> - <entry><option>-funfolding-dict-discount=<replaceable>n</replaceable></option></entry> - <entry>Tweak unfolding settings. Default: 30</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - - <row> - <entry><option>-funfolding-fun-discount=<replaceable>n</replaceable></option></entry> - <entry>Tweak unfolding settings. Default: 60</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - - <row> - <entry><option>-funfolding-keeness-factor=<replaceable>n</replaceable></option></entry> - <entry>Tweak unfolding settings. Default: 1.5</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - - <row> - <entry><option>-funfolding-use-threshold=<replaceable>n</replaceable></option></entry> - <entry>Tweak unfolding settings. Default: 60</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - - <row> - <entry><option>-fvectorisation-avoidance</option></entry> - <entry>Enable vectorisation avoidance. Always enabled by default.</entry> - <entry>dynamic</entry> - <entry><option>-fno-vectorisation-avoidance</option></entry> - </row> - - <row> - <entry><option>-fvectorise</option></entry> - <entry>Enable vectorisation of nested data parallelism</entry> - <entry>dynamic</entry> - <entry><option>-fno-vectorise</option></entry> - </row> - - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Profiling options</title> - - <para><xref linkend="profiling"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-prof</option></entry> - <entry>Turn on profiling</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-fprof-auto</option></entry> - <entry>Auto-add <literal>SCC</literal>s to all bindings - not marked INLINE</entry> - <entry>dynamic</entry> - <entry><option>-fno-prof-auto</option></entry> - </row> - <row> - <entry><option>-fprof-auto-top</option></entry> - <entry>Auto-add <literal>SCC</literal>s to all top-level - bindings not marked INLINE</entry> - <entry>dynamic</entry> - <entry><option>-fno-prof-auto</option></entry> - </row> - <row> - <entry><option>-fprof-auto-exported</option></entry> - <entry>Auto-add <literal>SCC</literal>s to all exported - bindings not marked INLINE</entry> - <entry>dynamic</entry> - <entry><option>-fno-prof-auto</option></entry> - </row> - <row> - <entry><option>-fprof-cafs</option></entry> - <entry>Auto-add <literal>SCC</literal>s to all CAFs</entry> - <entry>dynamic</entry> - <entry><option>-fno-prof-cafs</option></entry> - </row> - <row> - <entry><option>-fno-prof-count-entries</option></entry> - <entry>Do not collect entry counts</entry> - <entry>dynamic</entry> - <entry><option>-fprof-count-entries</option></entry> - </row> - <row> - <entry><option>-ticky</option></entry> - <entry><link linkend="ticky-ticky">Turn on ticky-ticky profiling</link></entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Program coverage options</title> - - <para><xref linkend="hpc"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-fhpc</option></entry> - <entry>Turn on Haskell program coverage instrumentation</entry> - <entry>dynamic</entry> - <entry><option>-</option></entry> - </row> - <row> - <entry><option>-hpcdir dir</option></entry> - <entry>Directory to deposit .mix files during compilation (default is .hpc)</entry> - <entry>dynamic</entry> - <entry><option>-</option></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Haskell pre-processor options</title> - - <para><xref linkend="pre-processor"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-F</option></entry> - <entry> - Enable the use of a pre-processor - (set with <option>-pgmF</option>) - </entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>C pre-processor options</title> - - <para><xref linkend="c-pre-processor"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-cpp</option></entry> - <entry>Run the C pre-processor on Haskell source files</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional></entry> - <entry>Define a symbol in the C pre-processor</entry> - <entry>dynamic</entry> - <entry><option>-U</option><replaceable>symbol</replaceable></entry> - </row> - <row> - <entry><option>-U</option><replaceable>symbol</replaceable></entry> - <entry>Undefine a symbol in the C pre-processor</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-I</option><replaceable>dir</replaceable></entry> - <entry>Add <replaceable>dir</replaceable> to the - directory search list for <literal>#include</literal> files</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Code generation options</title> - - <para><xref linkend="options-codegen"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-fasm</option></entry> - <entry>Use the <link linkend="native-code-gen">native code - generator</link></entry> - <entry>dynamic</entry> - <entry>-fllvm</entry> - </row> - <row> - <entry><option>-fllvm</option></entry> - <entry>Compile using the <link linkend="llvm-code-gen">LLVM code - generator</link></entry> - <entry>dynamic</entry> - <entry>-fasm</entry> - </row> - <row> - <entry><option>-fno-code</option></entry> - <entry>Omit code generation</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-fwrite-interface</option></entry> - <entry>Always write interface files</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-fbyte-code</option></entry> - <entry>Generate byte-code</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-fobject-code</option></entry> - <entry>Generate object code</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Linking options</title> - - <para><xref linkend="options-linker"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-shared</option></entry> - <entry>Generate a shared library (as opposed to an executable)</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-staticlib</option></entry> - <entry>On Darwin/OS X/iOS only, generate a standalone static library - (as opposed to an executable). - This is the usual way to compile for iOS. - </entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-fPIC</option></entry> - <entry>Generate position-independent code (where available)</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dynamic</option></entry> - <entry>Use dynamic Haskell libraries (if available)</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dynamic-too</option></entry> - <entry>Build dynamic object files <emphasis>as well as</emphasis> static object files during compilation</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dyno</option></entry> - <entry>Set the output path for the <emphasis>dynamically</emphasis> linked objects</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dynosuf</option></entry> - <entry>Set the output suffix for dynamic object files</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dynload</option></entry> - <entry>Selects one of a number of modes for finding shared - libraries at runtime.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-framework</option> <replaceable>name</replaceable></entry> - <entry>On Darwin/OS X/iOS only, link in the framework <replaceable>name</replaceable>. - This option corresponds to the <option>-framework</option> option for Apple's Linker.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-framework-path</option> <replaceable>name</replaceable></entry> - <entry>On Darwin/OS X/iOS only, add <replaceable>dir</replaceable> to the list of - directories searched for frameworks. - This option corresponds to the <option>-F</option> option for Apple's Linker.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-l</option><replaceable>lib</replaceable></entry> - <entry>Link in library <replaceable>lib</replaceable></entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-L</option><replaceable>dir</replaceable></entry> - <entry>Add <replaceable>dir</replaceable> to the list of - directories searched for libraries</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-main-is</option></entry> - <entry>Set main module and function</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>--mk-dll</option></entry> - <entry>DLL-creation mode (Windows only)</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-no-hs-main</option></entry> - <entry>Don't assume this program contains <literal>main</literal></entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-rtsopts</option>, <option>-rtsopts={none,some,all}</option></entry> - <entry>Control whether the RTS behaviour can be tweaked via command-line - flags and the <literal>GHCRTS</literal> environment - variable. Using <literal>none</literal> means no RTS flags can be given; <literal>some</literal> means only a minimum of safe options can be given (the default), and <literal>all</literal> (or no argument at all) means that all RTS flags are permitted.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-with-rtsopts=<replaceable>opts</replaceable></option></entry> - <entry>Set the default RTS options to - <replaceable>opts</replaceable>.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-no-rtsopts-suggestions</option></entry> - <entry>Don't print RTS suggestions about linking with - <literal>-rtsopts</literal>. - </entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-no-link</option></entry> - <entry>Omit linking</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-split-objs</option></entry> - <entry>Split objects (for libraries)</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-static</option></entry> - <entry>Use static Haskell libraries</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-threaded</option></entry> - <entry>Use the threaded runtime</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-debug</option></entry> - <entry>Use the debugging runtime</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ticky</option></entry> - <entry>For linking, this simply implies <option>-debug</option>; - see <xref linkend="ticky-ticky"/>.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-eventlog</option></entry> - <entry>Enable runtime event tracing</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-fno-gen-manifest</option></entry> - <entry>Do not generate a manifest file (Windows only)</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-fno-embed-manifest</option></entry> - <entry>Do not embed the manifest in the executable (Windows only)</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-fno-shared-implib</option></entry> - <entry>Don't generate an import library for a DLL (Windows only)</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dylib-install-name</option> <replaceable>path</replaceable></entry> - <entry>Set the install name (via <literal>-install_name</literal> passed to Apple's - linker), specifying the full install path of the library file. Any libraries - or executables that link with it later will pick up that path as their - runtime search location for it. (Darwin/OS X only)</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-rdynamic</option></entry> - <entry>This instructs the linker to add all symbols, not only used ones, to the - dynamic symbol table. Currently Linux and Windows/MinGW32 only. - This is equivalent to using <literal>-optl -rdynamic</literal> on Linux, - and <literal>-optl -export-all-symbols</literal> on Windows.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Plugin options</title> - - <para><xref linkend="compiler-plugins"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-fplugin</option>=<replaceable>module</replaceable></entry> - <entry>Load a plugin exported by a given module</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-fplugin-opt</option>=<replaceable>module:args</replaceable></entry> - <entry>Give arguments to a plugin module; module must be specified with <option>-fplugin</option></entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - - <sect2> - <title>Replacing phases</title> - - <para><xref linkend="replacing-phases"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-pgmL</option> <replaceable>cmd</replaceable></entry> - <entry>Use <replaceable>cmd</replaceable> as the literate pre-processor</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-pgmP</option> <replaceable>cmd</replaceable></entry> - <entry>Use <replaceable>cmd</replaceable> as the C - pre-processor (with <option>-cpp</option> only)</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-pgmc</option> <replaceable>cmd</replaceable></entry> - <entry>Use <replaceable>cmd</replaceable> as the C compiler</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-pgmlo</option> <replaceable>cmd</replaceable></entry> - <entry>Use <replaceable>cmd</replaceable> as the LLVM optimiser</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-pgmlc</option> <replaceable>cmd</replaceable></entry> - <entry>Use <replaceable>cmd</replaceable> as the LLVM compiler</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-pgms</option> <replaceable>cmd</replaceable></entry> - <entry>Use <replaceable>cmd</replaceable> as the splitter</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-pgma</option> <replaceable>cmd</replaceable></entry> - <entry>Use <replaceable>cmd</replaceable> as the assembler</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-pgml</option> <replaceable>cmd</replaceable></entry> - <entry>Use <replaceable>cmd</replaceable> as the linker</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-pgmdll</option> <replaceable>cmd</replaceable></entry> - <entry>Use <replaceable>cmd</replaceable> as the DLL generator</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-pgmF</option> <replaceable>cmd</replaceable></entry> - <entry>Use <replaceable>cmd</replaceable> as the pre-processor - (with <option>-F</option> only)</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-pgmwindres</option> <replaceable>cmd</replaceable></entry> - <entry>Use <replaceable>cmd</replaceable> as the program for - embedding manifests on Windows.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-pgmlibtool</option> <replaceable>cmd</replaceable></entry> - <entry>Use <replaceable>cmd</replaceable> as the command for libtool - (with <option>-staticlib</option> only).</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - </tbody> - </tgroup> - </informaltable> - <indexterm><primary><option>-pgmL</option></primary></indexterm> - <indexterm><primary><option>-pgmP</option></primary></indexterm> - <indexterm><primary><option>-pgmc</option></primary></indexterm> - <indexterm><primary><option>-pgmlo</option></primary></indexterm> - <indexterm><primary><option>-pgmlc</option></primary></indexterm> - <indexterm><primary><option>-pgma</option></primary></indexterm> - <indexterm><primary><option>-pgml</option></primary></indexterm> - <indexterm><primary><option>-pgmdll</option></primary></indexterm> - <indexterm><primary><option>-pgmF</option></primary></indexterm> - - </sect2> - - <sect2> - <title>Forcing options to particular phases</title> - - <para><xref linkend="forcing-options-through"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-optL</option> <replaceable>option</replaceable></entry> - <entry>pass <replaceable>option</replaceable> to the literate pre-processor</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-optP</option> <replaceable>option</replaceable></entry> - <entry>pass <replaceable>option</replaceable> to cpp (with - <option>-cpp</option> only)</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-optF</option> <replaceable>option</replaceable></entry> - <entry>pass <replaceable>option</replaceable> to the - custom pre-processor</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-optc</option> <replaceable>option</replaceable></entry> - <entry>pass <replaceable>option</replaceable> to the C compiler</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-optlo</option> <replaceable>option</replaceable></entry> - <entry>pass <replaceable>option</replaceable> to the LLVM optimiser</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-optlc</option> <replaceable>option</replaceable></entry> - <entry>pass <replaceable>option</replaceable> to the LLVM compiler</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-opta</option> <replaceable>option</replaceable></entry> - <entry>pass <replaceable>option</replaceable> to the assembler</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-optl</option> <replaceable>option</replaceable></entry> - <entry>pass <replaceable>option</replaceable> to the linker</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-optdll</option> <replaceable>option</replaceable></entry> - <entry>pass <replaceable>option</replaceable> to the DLL generator</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-optwindres</option> <replaceable>option</replaceable></entry> - <entry>pass <replaceable>option</replaceable> to <literal>windres</literal>.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Platform-specific options</title> - - <para><xref linkend="options-platform"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-msse2</option></entry> - <entry>(x86 only) Use SSE2 for floating point</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - - <sect2> - <title>Compiler debugging options</title> - - <para><xref linkend="options-debugging"/></para> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-dcore-lint</option></entry> - <entry>Turn on internal sanity checking</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-to-file</option></entry> - <entry>Dump to files instead of stdout</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-asm</option></entry> - <entry>Dump assembly</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-bcos</option></entry> - <entry>Dump interpreter byte code</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-cmm</option></entry> - <entry>Dump C-- output</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-core-stats</option></entry> - <entry>Print a one-line summary of the size of the Core program - at the end of the optimisation pipeline </entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-cse</option></entry> - <entry>Dump CSE output</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-deriv</option></entry> - <entry>Dump deriving output</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-ds</option></entry> - <entry>Dump desugarer output</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-foreign</option></entry> - <entry>Dump <literal>foreign export</literal> stubs</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-hpc</option></entry> - <entry>Dump after instrumentation for program coverage</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-inlinings</option></entry> - <entry>Dump inlining info</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-llvm</option></entry> - <entry>Dump LLVM intermediate code</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-occur-anal</option></entry> - <entry>Dump occurrence analysis output</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-opt-cmm</option></entry> - <entry>Dump the results of C-- to C-- optimising passes</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-parsed</option></entry> - <entry>Dump parse tree</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-prep</option></entry> - <entry>Dump prepared core</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-rn</option></entry> - <entry>Dump renamer output</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-rule-firings</option></entry> - <entry>Dump rule firing info</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-rule-rewrites</option></entry> - <entry>Dump detailed rule firing info</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-rules</option></entry> - <entry>Dump rules</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-vect</option></entry> - <entry>Dump vectoriser input and output</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-simpl</option></entry> - <entry>Dump final simplifier output</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-simpl-iterations</option></entry> - <entry>Dump output from each simplifier iteration</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-spec</option></entry> - <entry>Dump specialiser output</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-splices</option></entry> - <entry>Dump TH spliced expressions, and what they evaluate to</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-stg</option></entry> - <entry>Dump final STG</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-stranal</option></entry> - <entry>Dump strictness analyser output</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-strsigs</option></entry> - <entry>Dump strictness signatures</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-tc</option></entry> - <entry>Dump typechecker output</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dth-dec-file</option></entry> - <entry>Show evaluated TH declarations in a .th.hs file</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-types</option></entry> - <entry>Dump type signatures</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-worker-wrapper</option></entry> - <entry>Dump worker-wrapper output</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-if-trace</option></entry> - <entry>Trace interface files</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-tc-trace</option></entry> - <entry>Trace typechecker</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-vt-trace</option></entry> - <entry>Trace vectoriser</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-rn-trace</option></entry> - <entry>Trace renamer</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-rn-stats</option></entry> - <entry>Renamer stats</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-ddump-simpl-stats</option></entry> - <entry>Dump simplifier stats</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dno-debug-output</option></entry> - <entry>Suppress unsolicited debugging output</entry> - <entry>static</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dppr-debug</option></entry> - <entry>Turn on debug printing (more verbose)</entry> - <entry>static</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dppr-user-length</option></entry> - <entry>Set the depth for printing expressions in error msgs</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dppr-colsNNN</option></entry> - <entry>Set the width of debugging output. For example <option>-dppr-cols200</option></entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dppr-case-as-let</option></entry> - <entry>Print single alternative case expressions as strict lets.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dsuppress-all</option></entry> - <entry>In core dumps, suppress everything (except for uniques) that is suppressible.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dsuppress-uniques</option></entry> - <entry>Suppress the printing of uniques in debug output (easier to use <command>diff</command>)</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dsuppress-idinfo</option></entry> - <entry>Suppress extended information about identifiers where they are bound</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dsuppress-unfoldings</option></entry> - <entry>Suppress the printing of the stable unfolding of a variable at its binding site</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dsuppress-module-prefixes</option></entry> - <entry>Suppress the printing of module qualification prefixes</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dsuppress-type-signatures</option></entry> - <entry>Suppress type signatures</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dsuppress-type-applications</option></entry> - <entry>Suppress type applications</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dsuppress-coercions</option></entry> - <entry>Suppress the printing of coercions in Core dumps to make them shorter</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dsource-stats</option></entry> - <entry>Dump haskell source stats</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dcmm-lint</option></entry> - <entry>C-- pass sanity checking</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dstg-lint</option></entry> - <entry>STG pass sanity checking</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dstg-stats</option></entry> - <entry>Dump STG stats</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dverbose-core2core</option></entry> - <entry>Show output from each core-to-core pass</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dverbose-stg2stg</option></entry> - <entry>Show output from each STG-to-STG pass</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dshow-passes</option></entry> - <entry>Print out each pass name as it happens</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-dfaststring-stats</option></entry> - <entry>Show statistics for fast string usage when finished</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-frule-check</option></entry> - <entry>Report sites with rules that could have fired but didn't. - Takes a string argument.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Misc compiler options</title> - - <informaltable> - <tgroup cols="4" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - <entry>Static/Dynamic</entry> - <entry>Reverse</entry> - </row> - </thead> - <tbody> - <row> - <entry><option>-j<replaceable>N</replaceable></option></entry> - <entry>When compiling with <literal>--make</literal>, compile <replaceable>N</replaceable> modules in parallel.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-fno-hi-version-check</option></entry> - <entry>Don't complain about <literal>.hi</literal> file mismatches</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-fhistory-size</option></entry> - <entry>Set simplification history size</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-fno-ghci-history</option></entry> - <entry>Do not use the load/store the GHCi command history from/to <literal>ghci_history</literal>.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - <row> - <entry><option>-fno-ghci-sandbox</option></entry> - <entry>Turn off the GHCi sandbox. Means computations are run in the main thread, rather than a forked thread.</entry> - <entry>dynamic</entry> - <entry>-</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> -</sect1> - - -<!-- -Still to document: - -Misc: - , ( "H" , HasArg (setHeapSize . fromIntegral . decodeSize) ) - - -Bdir ---> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> diff --git a/docs/users_guide/ghc-theme/layout.html b/docs/users_guide/ghc-theme/layout.html new file mode 100644 index 0000000000..0391543f27 --- /dev/null +++ b/docs/users_guide/ghc-theme/layout.html @@ -0,0 +1,21 @@ +{# + sphinxdoc/layout.html + ~~~~~~~~~~~~~~~~~~~~~ + + Sphinx layout template for the sphinxdoc theme. + + :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +#} +{% extends "basic/layout.html" %} + +{% block relbar1 %} +<div class="logo"> + <a href="{{ pathto('index') }}"><h1>Glasgow Haskell Compiler Users Guide</h1></a> +</div> +{{ super() }} +{% endblock %} + +{# put the sidebar before the body #} +{% block sidebar1 %}{{ sidebar() }}{% endblock %} +{% block sidebar2 %}{% endblock %} diff --git a/docs/users_guide/ghc-theme/static/ghc-theme.css b/docs/users_guide/ghc-theme/static/ghc-theme.css new file mode 100644 index 0000000000..9e301223b8 --- /dev/null +++ b/docs/users_guide/ghc-theme/static/ghc-theme.css @@ -0,0 +1,375 @@ +/* + * sphinxdoc.css_t + * ~~~~~~~~~~~~~~~ + * + * Sphinx stylesheet -- sphinxdoc theme. Originally created by + * Armin Ronacher for Werkzeug. + * + * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva', + 'Verdana', sans-serif; + font-size: 14px; + line-height: 150%; + text-align: center; + background-color: #D1CDDC; + color: black; + padding: 0; + border: 1px solid #aaa; + + margin: 0px 80px 0px 80px; + min-width: 740px; +} + +div.logo { + background-color: white; + text-align: left; + padding: 10px 10px 15px 15px; +} + +div.document { + background-color: white; + text-align: left; + background-image: url(contents.png); + background-repeat: repeat-x; +} + +div.bodywrapper { + margin: 0 240px 0 0; + border-right: 1px solid #ccc; +} + +div.body { + margin: 0; + padding: 0.5em 20px 20px 20px; +} + +div.related { + font-size: 1em; +} + +div.related ul { + background-color: #eee; + height: 2em; + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; +} + +div.related ul li { + margin: 0; + padding: 0; + height: 2em; + float: left; +} + +div.related ul li.right { + float: right; + margin-right: 5px; +} + +div.related ul li a { + margin: 0; + padding: 0 5px 0 5px; + line-height: 1.75em; +} + +div.sphinxsidebarwrapper { + padding: 0; +} + +div.sphinxsidebar { + margin: 0; + padding: 0.5em 15px 15px 0; + width: 210px; + float: right; + font-size: 1em; + text-align: left; +} + +div.sphinxsidebar h3, div.sphinxsidebar h4 { + margin: 1em 0 0.5em 0; + font-size: 1em; + padding: 0.1em 0 0.1em 0.5em; + color: white; + border: 1px solid #86989B; + background-color: #AFC1C4; +} + +div.sphinxsidebar h3 a { + color: white; +} + +div.sphinxsidebar ul { + padding-left: 1.5em; + margin-top: 7px; + padding: 0; + line-height: 130%; +} + +div.sphinxsidebar ul ul { + margin-left: 20px; +} + +div.footer { + background-color: #eee; + color: #86989B; + padding: 3px 8px 3px 0; + clear: both; + font-size: 0.8em; + text-align: right; +} + +div.footer a { + color: #86989B; + text-decoration: underline; +} + +/* -- body styles ----------------------------------------------------------- */ + +p { + margin: 0.8em 0 0.5em 0; +} + +a { + color: #428BCA; + text-decoration: none; +} + +a:hover { + color: #2A6496; +} + +div.body p a{ + text-decoration: underline; +} + +h1 { + margin: 0; + padding: 0.7em 0 0.3em 0; + font-size: 1.5em; + color: #6E618D; +} + +h2 { + margin: 1.3em 0 0.2em 0; + font-size: 1.35em; + padding: 0; +} + +h3 { + margin: 1em 0 -0.3em 0; + font-size: 1.2em; +} + +h3 a:hover { + text-decoration: underline; +} + +div.body h1 a, div.body h2 a, div.body h3 a, div.body h4 a, div.body h5 a, div.body h6 a { + color: black!important; +} + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + background-color: #f2f2f2; + font-weight: normal; + color: #20435c; + border-bottom: 1px solid #ccc; + margin: 20px -20px 10px -20px; + padding: 3px 0 3px 10px; +} + +div.body h1 { margin-top: 0; font-size: 200%; } +div.body h2 { font-size: 160%; } +div.body h3 { font-size: 140%; } +div.body h4 { font-size: 120%; } +div.body h5 { font-size: 110%; } +div.body h6 { font-size: 100%; } + +h1 a.anchor, h2 a.anchor, h3 a.anchor, h4 a.anchor, h5 a.anchor, h6 a.anchor { + display: none; + margin: 0 0 0 0.3em; + padding: 0 0.2em 0 0.2em; + color: #aaa!important; +} + +h1:hover a.anchor, h2:hover a.anchor, h3:hover a.anchor, h4:hover a.anchor, +h5:hover a.anchor, h6:hover a.anchor { + display: inline; +} + +h1 a.anchor:hover, h2 a.anchor:hover, h3 a.anchor:hover, h4 a.anchor:hover, +h5 a.anchor:hover, h6 a.anchor:hover { + color: #777; + background-color: #eee; +} + +a.headerlink { + color: #c60f0f!important; + font-size: 1em; + margin-left: 6px; + padding: 0 4px 0 4px; + text-decoration: none!important; +} + +a.headerlink:hover { + background-color: #ccc; + color: white!important; +} + +cite, code, tt { + font-family: 'Consolas', 'Deja Vu Sans Mono', + 'Bitstream Vera Sans Mono', monospace; + font-size: 0.95em; +} + +code { + background-color: #eee; + padding: 0 4px; +} + +:not(a.reference) > tt { + background-color: #f2f2f2; + border-bottom: 1px solid #ddd; + color: #333; +} + +tt.descname, tt.descclassname, tt.xref { + border: 0; +} + +hr { + border: 1px solid #abc; + margin: 2em; +} + +p a tt { + border: 0; + color: #CA7900; +} + +p a tt:hover { + color: #2491CF; +} + +a tt { + border: none; +} + +pre { + font-family: 'Consolas', 'Deja Vu Sans Mono', + 'Bitstream Vera Sans Mono', monospace; + line-height: 110%; + padding: 0.5em; + border: 1px solid #ccc; + background-color: #f8f8f8; +} + +pre a { + color: inherit; + text-decoration: underline; +} + +td.linenos pre { + padding: 0.5em 0; +} + +div.quotebar { + background-color: #f8f8f8; + max-width: 250px; + float: right; + padding: 2px 7px; + border: 1px solid #ccc; +} + +div.topic { + background-color: #f8f8f8; +} + +table { + border-collapse: collapse; + margin: 0 -0.5em 0 -0.5em; +} + +table td, table th { + padding: 0.2em 0.5em 0.2em 0.5em; +} + +div.admonition, div.warning { + font-size: 0.9em; + margin: 1em 0 1em 0; + border: 1px solid #86989B; + background-color: #f7f7f7; + padding: 0; +} + +div.admonition p, div.warning p { + margin: 0.5em 1em 0.5em 1em; + padding: 0; +} + +div.admonition pre, div.warning pre { + margin: 0.4em 1em 0.4em 1em; +} + +div.admonition p.admonition-title, +div.warning p.admonition-title { + margin: 0; + padding: 0.1em 0 0.1em 0.5em; + color: white; + border-bottom: 1px solid #86989B; + font-weight: bold; + background-color: #AFC1C4; +} + +div.warning { + border: 1px solid #940000; +} + +div.warning p.admonition-title { + background-color: #CF0000; + border-bottom-color: #940000; +} + +div.admonition ul, div.admonition ol, +div.warning ul, div.warning ol { + margin: 0.1em 0.5em 0.5em 3em; + padding: 0; +} + +div.versioninfo { + margin: 1em 0 0 0; + border: 1px solid #ccc; + background-color: #DDEAF0; + padding: 8px; + line-height: 1.3em; + font-size: 0.9em; +} + +.viewcode-back { + font-family: 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva', + 'Verdana', sans-serif; +} + +div.viewcode-block:target { + background-color: #f4debf; + border-top: 1px solid #ac9; + border-bottom: 1px solid #ac9; +} + +/* Hide bullets in toctree */ +.toctree-wrapper li { + list-style: none; +} diff --git a/docs/users_guide/ghc-theme/theme.conf b/docs/users_guide/ghc-theme/theme.conf new file mode 100644 index 0000000000..f2d9b761bc --- /dev/null +++ b/docs/users_guide/ghc-theme/theme.conf @@ -0,0 +1,4 @@ +[theme] +inherit = basic +stylesheet = ghc-theme.css +pygments_style = friendly diff --git a/docs/users_guide/ghc.mk b/docs/users_guide/ghc.mk index eb7eb6a673..1d48fa157a 100644 --- a/docs/users_guide/ghc.mk +++ b/docs/users_guide/ghc.mk @@ -10,28 +10,41 @@ # # ----------------------------------------------------------------------------- -docs/users_guide_GENERATED_DOCBOOK_SOURCES := \ - docs/users_guide/users_guide.xml \ - docs/users_guide/what_glasgow_exts_does.gen.xml -# sort remove duplicates -docs/users_guide_DOCBOOK_SOURCES := \ - $(sort $(docs/users_guide_GENERATED_DOCBOOK_SOURCES) \ - $(wildcard docs/users_guide/*.xml) \ - $(basename $(wildcard docs/users_guide/*.xml.in))) +docs/users_guide_RST_SOURCES := \ + $(utils/mkUserGuidePart_GENERATED_RST_SOURCES) \ + $(wildcard docs/users_guide/*.rst) -$(docs/users_guide_GENERATED_DOCBOOK_SOURCES): %.xml: $(mkUserGuidePart_INPLACE) - $(mkUserGuidePart_INPLACE) $@ +$(eval $(call sphinx,docs/users_guide,users_guide)) -$(eval $(call docbook,docs/users_guide,users_guide)) +html_docs/users_guide : docs/users_guide/images/prof_scc.svg -$(eval $(call clean-target,docs/users_guide,gen,$(docs/users_guide_GENERATED_DOCBOOK_SOURCES))) +# man page +docs/users_guide_MAN_RST_SOURCES := docs/users_guide/ghc.rst -html_docs/users_guide : docs/users_guide/users_guide/prof_scc.eps +MAN_SECTION := 1 +MAN_PAGES := docs/users_guide/ghc.1 -docs/users_guide/users_guide/prof_scc.eps : \ - docs/users_guide/prof_scc.eps \ - docs/users_guide/users_guide/index.html - $(CP) $< $@ -# dep. on d/u/u/index.html is to make sure that the d/u/u dir is created first +ifneq "$(BINDIST)" "YES" +$(MAN_PAGES): $(docs/users_guide_MAN_RST_SOURCES) $(utils/mkUserGuidePart_GENERATED_RST_SOURCES) + $(SPHINXBUILD) -b man docs/users_guide docs/users_guide +endif +man : $(MAN_PAGES) + +ifeq "$(BUILD_MAN)" "YES" +ifeq "$(phase)" "final" +$(eval $(call all-target,users_guide/man,$(MAN_PAGES))) +endif + +INSTALL_MANPAGES += $(MAN_PAGES) + +install: install_man + +.PHONY: install_man +install_man: $(MAN_PAGES) + $(INSTALL_DIR) "$(DESTDIR)$(mandir)" + $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man$(MAN_SECTION)" + $(INSTALL_MAN) $(INSTALL_OPTS) $(MAN_PAGES) "$(DESTDIR)$(mandir)/man$(MAN_SECTION)" + +endif diff --git a/docs/users_guide/ghc.rst b/docs/users_guide/ghc.rst new file mode 100644 index 0000000000..f2b9b70604 --- /dev/null +++ b/docs/users_guide/ghc.rst @@ -0,0 +1,69 @@ +GHC +=== + +Synopsis +-------- + +:: + + ghc [option|filename] + ghci [option|filename] + + +Description +----------- + +This manual page documents briefly the ``ghc`` and ``ghci`` commands. Note that +``ghci`` is not yet available on all architectures. Extensive documentation is +available in various other formats including PDF and HTML; see below. + +Each of GHC's command line options is classified as either *static* or +*dynamic*. A static flag may only be specified on the command line, whereas a +dynamic flag may also be given in an ``OPTIONS`` pragma in a source file or +set from the GHCi command-line with ``:set`` . + +As a rule of thumb, all the language options are dynamic, as are the +warning options and the debugging options. + +The rest are static, with the notable exceptions of +``-v``, ``-cpp``, ``-fasm``, ``-fvia-C``, ``-fllvm``, and +``-#include``. +The OPTIONS sections lists the status of each flag. + +Common suffixes of file names for Haskell are: + +``.hs`` + Haskell source code; preprocess, compile + +``.lhs`` + literate Haskell source; unlit, preprocess, compile + +``.hi`` + Interface file; contains information about exported symbols + +``.hc`` + intermediate C files + +``.⟨way⟩_o`` + object files for "way" ⟨way⟩; common ways are: + + ``dyn`` + dynamically-linked + ``p`` + built with profiling + +``.⟨way⟩_hi`` + interface files for "way" ⟨way⟩; common ways are: + +.. _options-ref: + +Options +------- + +.. include:: all-flags.gen.rst + +Copyright +--------- + +Copyright 2015. The University Court of the University of Glasgow. +All rights reserved. diff --git a/docs/users_guide/ghc_config.py.in b/docs/users_guide/ghc_config.py.in new file mode 100644 index 0000000000..8ff4aa92fb --- /dev/null +++ b/docs/users_guide/ghc_config.py.in @@ -0,0 +1,9 @@ +extlinks = { + 'base-ref': ('../libraries/base-@LIBRARY_base_VERSION@/%s', ''), + 'cabal-ref': ('../libraries/Cabal-@LIBRARY_Cabal_VERSION@/%s', ''), + 'ghc-prim-ref': ('../libraries/ghc-prim-@LIBRARY_ghc_prim_VERSION@/%s', ''), + 'ghc-ticket': ('http://ghc.haskell.org/trac/ghc/ticket/%s', 'Trac #'), + 'ghc-wiki': ('http://ghc.haskell.org/trac/ghc/wiki/%s', 'Trac #'), +} + +version = @GhcVersion@ diff --git a/docs/users_guide/ghci.rst b/docs/users_guide/ghci.rst new file mode 100644 index 0000000000..b52d9e979b --- /dev/null +++ b/docs/users_guide/ghci.rst @@ -0,0 +1,3014 @@ +.. _ghci: + +Using GHCi +========== + +.. index:: + single: GHCi + single: interpreter + single: interactive + single: Hugs + single: Foreign Function Interface; GHCi support + single: FFI; GHCi support + +GHCi [1]_ is GHC's interactive environment, in which Haskell expressions +can be interactively evaluated and programs can be interpreted. If +you're familiar with `Hugs <http://www.haskell.org/hugs/>`__, then +you'll be right at home with GHCi. However, GHCi also has support for +interactively loading compiled code, as well as supporting all [2]_ the +language extensions that GHC provides. GHCi also includes an interactive +debugger (see :ref:`ghci-debugger`). + +.. [1] + The ‘i’ stands for “Interactive” + +.. [2] + except ``foreign export``, at the moment + + +.. _ghci-introduction: + +Introduction to GHCi +-------------------- + +Let's start with an example GHCi session. You can fire up GHCi with the +command ``ghci``: + +:: + + $ ghci + GHCi, version 6.12.1: http://www.haskell.org/ghc/ :? for help + Loading package ghc-prim ... linking ... done. + Loading package integer-gmp ... linking ... done. + Loading package base ... linking ... done. + Loading package ffi-1.0 ... linking ... done. + Prelude> + +There may be a short pause while GHCi loads the prelude and standard +libraries, after which the prompt is shown. As the banner says, you can +type ``:?`` to see the list of commands available, and a half line +description of each of them. We'll explain most of these commands as we +go along, and there is complete documentation for all the commands in +:ref:`ghci-commands`. + +Haskell expressions can be typed at the prompt: + +.. index:: + single: prompt; GHCi + +:: + + Prelude> 1+2 + 3 + Prelude> let x = 42 in x / 9 + 4.666666666666667 + Prelude> + +GHCi interprets the whole line as an expression to evaluate. The +expression may not span several lines - as soon as you press enter, GHCi +will attempt to evaluate it. + +In Haskell, a ``let`` expression is followed by ``in``. However, in +GHCi, since the expression can also be interpreted in the ``IO`` monad, +a ``let`` binding with no accompanying ``in`` statement can be signalled +by an empty line, as in the above example. + +.. _loading-source-files: + +Loading source files +-------------------- + +Suppose we have the following Haskell source code, which we place in a +file ``Main.hs``: + +:: + + main = print (fac 20) + + fac 0 = 1 + fac n = n * fac (n-1) + +You can save ``Main.hs`` anywhere you like, but if you save it somewhere +other than the current directory [3]_ then we will need to change to the +right directory in GHCi: + +:: + + Prelude> :cd dir + +where ⟨dir⟩ is the directory (or folder) in which you saved ``Main.hs``. + +To load a Haskell source file into GHCi, use the ``:load`` command: + +.. index:: + single: :load + +:: + + Prelude> :load Main + Compiling Main ( Main.hs, interpreted ) + Ok, modules loaded: Main. + *Main> + +GHCi has loaded the ``Main`` module, and the prompt has changed to +“\ ``*Main>``\ ” to indicate that the current context for expressions +typed at the prompt is the ``Main`` module we just loaded (we'll explain +what the ``*`` means later in :ref:`ghci-scope`). So we can now type +expressions involving the functions from ``Main.hs``: + +:: + + *Main> fac 17 + 355687428096000 + +Loading a multi-module program is just as straightforward; just give the +name of the “topmost” module to the ``:load`` command (hint: ``:load`` +can be abbreviated to ``:l``). The topmost module will normally be +``Main``, but it doesn't have to be. GHCi will discover which modules +are required, directly or indirectly, by the topmost module, and load +them all in dependency order. + +.. [3] + If you started up GHCi from the command line then GHCi's current + directory is the same as the current directory of the shell from + which it was started. If you started GHCi from the “Start” menu in + Windows, then the current directory is probably something like + ``C:\Documents and Settings\user name``. + + +.. _ghci-modules-filenames: + +Modules vs. filenames +~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: modules; and filenames + single: filenames; of modules + +Question: How does GHC find the filename which contains module ⟨M⟩? +Answer: it looks for the file ``M.hs``, or ``M.lhs``. This means that +for most modules, the module name must match the filename. If it +doesn't, GHCi won't be able to find it. + +There is one exception to this general rule: when you load a program +with ``:load``, or specify it when you invoke ``ghci``, you can give a +filename rather than a module name. This filename is loaded if it +exists, and it may contain any module you like. This is particularly +convenient if you have several ``Main`` modules in the same directory +and you can't call them all ``Main.hs``. + +The search path for finding source files is specified with the ``-i`` +option on the GHCi command line, like so: + +:: + + ghci -idir1:...:dirn + +or it can be set using the ``:set`` command from within GHCi (see +:ref:`ghci-cmd-line-options`) [4]_ + +One consequence of the way that GHCi follows dependencies to find +modules to load is that every module must have a source file. The only +exception to the rule is modules that come from a package, including the +``Prelude`` and standard libraries such as ``IO`` and ``Complex``. If +you attempt to load a module for which GHCi can't find a source file, +even if there are object and interface files for the module, you'll get +an error message. + +.. [4] + Note that in GHCi, and ``--make`` mode, the ``-i`` option is used to + specify the search path for *source* files, whereas in standard + batch-compilation mode the ``-i`` option is used to specify the + search path for interface files, see :ref:`search-path`. + + +Making changes and recompilation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: :reload + +If you make some changes to the source code and want GHCi to recompile +the program, give the ``:reload`` command. The program will be +recompiled as necessary, with GHCi doing its best to avoid actually +recompiling modules if their external dependencies haven't changed. This +is the same mechanism we use to avoid re-compiling modules in the batch +compilation setting (see :ref:`recomp`). + +.. _ghci-compiled: + +Loading compiled code +--------------------- + +.. index:: + single: compiled code; in GHCi + +When you load a Haskell source module into GHCi, it is normally +converted to byte-code and run using the interpreter. However, +interpreted code can also run alongside compiled code in GHCi; indeed, +normally when GHCi starts, it loads up a compiled copy of the ``base`` +package, which contains the ``Prelude``. + +Why should we want to run compiled code? Well, compiled code is roughly +10x faster than interpreted code, but takes about 2x longer to produce +(perhaps longer if optimisation is on). So it pays to compile the parts +of a program that aren't changing very often, and use the interpreter +for the code being actively developed. + +When loading up source modules with ``:load``, GHCi normally looks for +any corresponding compiled object files, and will use one in preference +to interpreting the source if possible. For example, suppose we have a 4-module +program consisting of modules ``A``, ``B``, ``C``, and ``D``. Modules ``B`` and +``C`` both import ``D`` only, and ``A`` imports both ``B`` and ``C``: + +:: + + A + / \ + B C + \ / + D + +We can compile ``D``, then load the whole program, like this: + +:: + + Prelude> :! ghc -c -dynamic D.hs + Prelude> :load A + Compiling B ( B.hs, interpreted ) + Compiling C ( C.hs, interpreted ) + Compiling A ( A.hs, interpreted ) + Ok, modules loaded: A, B, C, D. + *Main> + +In the messages from the compiler, we see that there is no line for +``D``. This is because it isn't necessary to compile ``D``, because the +source and everything it depends on is unchanged since the last +compilation. + +Note the ``-dynamic`` flag to GHC: GHCi uses dynamically-linked object +code (if you are on a platform that supports it), and so in order to use +compiled code with GHCi it must be compiled for dynamic linking. + +At any time you can use the command ``:show modules`` to get a list of +the modules currently loaded into GHCi: + +:: + + *Main> :show modules + D ( D.hs, D.o ) + C ( C.hs, interpreted ) + B ( B.hs, interpreted ) + A ( A.hs, interpreted ) + *Main> + +If we now modify the source of ``D`` (or pretend to: using the Unix command +``touch`` on the source file is handy for this), the compiler will no +longer be able to use the object file, because it might be out of date: + +:: + + *Main> :! touch D.hs + *Main> :reload + Compiling D ( D.hs, interpreted ) + Ok, modules loaded: A, B, C, D. + *Main> + +Note that module ``D`` was compiled, but in this instance because its source +hadn't really changed, its interface remained the same, and the +recompilation checker determined that ``A``, ``B`` and ``C`` didn't need to be +recompiled. + +So let's try compiling one of the other modules: + +:: + + *Main> :! ghc -c C.hs + *Main> :load A + Compiling D ( D.hs, interpreted ) + Compiling B ( B.hs, interpreted ) + Compiling C ( C.hs, interpreted ) + Compiling A ( A.hs, interpreted ) + Ok, modules loaded: A, B, C, D. + +We didn't get the compiled version of ``C``! What happened? Well, in GHCi a +compiled module may only depend on other compiled modules, and in this +case ``C`` depends on ``D``, which doesn't have an object file, so GHCi also +rejected ``C``\'s object file. Ok, so let's also compile ``D``: + +:: + + *Main> :! ghc -c D.hs + *Main> :reload + Ok, modules loaded: A, B, C, D. + +Nothing happened! Here's another lesson: newly compiled modules aren't +picked up by ``:reload``, only ``:load``: + +:: + + *Main> :load A + Compiling B ( B.hs, interpreted ) + Compiling A ( A.hs, interpreted ) + Ok, modules loaded: A, B, C, D. + +The automatic loading of object files can sometimes lead to confusion, +because non-exported top-level definitions of a module are only +available for use in expressions at the prompt when the module is +interpreted (see :ref:`ghci-scope`). For this reason, you might +sometimes want to force GHCi to load a module using the interpreter. +This can be done by prefixing a ``*`` to the module name or filename +when using ``:load``, for example + +:: + + Prelude> :load *A + Compiling A ( A.hs, interpreted ) + *A> + +When the ``*`` is used, GHCi ignores any pre-compiled object code and +interprets the module. If you have already loaded a number of modules as +object code and decide that you wanted to interpret one of them, instead +of re-loading the whole set you can use ``:add *M`` to specify that you +want ``M`` to be interpreted (note that this might cause other modules +to be interpreted too, because compiled modules cannot depend on +interpreted ones). + +To always compile everything to object code and never use the +interpreter, use the ``-fobject-code`` option (see :ref:`ghci-obj`). + +.. hint:: + Since GHCi will only use a compiled object file if it can be sure + that the compiled version is up-to-date, a good technique when working + on a large program is to occasionally run ``ghc --make`` to compile the + whole project (say before you go for lunch :-), then continue working in + the interpreter. As you modify code, the changed modules will be + interpreted, but the rest of the project will remain compiled. + +.. _interactive-evaluation: + +Interactive evaluation at the prompt +------------------------------------ + +When you type an expression at the prompt, GHCi immediately evaluates +and prints the result: + +:: + + Prelude> reverse "hello" + "olleh" + Prelude> 5+5 + 10 + +.. _actions-at-prompt: + +I/O actions at the prompt +~~~~~~~~~~~~~~~~~~~~~~~~~ + +GHCi does more than simple expression evaluation at the prompt. If you +enter an expression of type ``IO a`` for some ``a``, then GHCi +*executes* it as an IO-computation. + +:: + + Prelude> "hello" + "hello" + Prelude> putStrLn "hello" + hello + +This works even if the type of the expression is more general, provided +it can be *instantiated* to ``IO a``. For example + +:: + + Prelude> return True + True + +Furthermore, GHCi will print the result of the I/O action if (and only +if): + +- The result type is an instance of ``Show``. + +- The result type is not ``()``. + +For example, remembering that ``putStrLn :: String -> IO ()``: + +:: + + Prelude> putStrLn "hello" + hello + Prelude> do { putStrLn "hello"; return "yes" } + hello + "yes" + +.. _ghci-stmts: + +Using ``do-``\ notation at the prompt +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: do-notation; in GHCi + single: statements; in GHCi + +GHCi actually accepts statements rather than just expressions at the +prompt. This means you can bind values and functions to names, and use +them in future expressions or statements. + +The syntax of a statement accepted at the GHCi prompt is exactly the +same as the syntax of a statement in a Haskell ``do`` expression. +However, there's no monad overloading here: statements typed at the +prompt must be in the ``IO`` monad. + +:: + + Prelude> x <- return 42 + Prelude> print x + 42 + Prelude> + +The statement ``x <- return 42`` means “execute ``return 42`` in the +``IO`` monad, and bind the result to ``x``\ ”. We can then use ``x`` in +future statements, for example to print it as we did above. + +If ``-fprint-bind-result`` is set then GHCi will print the result of a +statement if and only if: + +- The statement is not a binding, or it is a monadic binding + (``p <- e``) that binds exactly one variable. + +- The variable's type is not polymorphic, is not ``()``, and is an + instance of ``Show``. + +.. index:: + single: -fprint-bind-result + +Of course, you can also bind normal non-IO expressions using the +``let``\-statement: + +:: + + Prelude> let x = 42 + Prelude> x + 42 + Prelude> + +Another important difference between the two types of binding is that +the monadic bind (``p <- e``) is *strict* (it evaluates ``e``), whereas +with the ``let`` form, the expression isn't evaluated immediately: + +:: + + Prelude> let x = error "help!" + Prelude> print x + *** Exception: help! + Prelude> + +Note that ``let`` bindings do not automatically print the value bound, +unlike monadic bindings. + +You can also use ``let``-statements to define functions at the +prompt: + +:: + + Prelude> let add a b = a + b + Prelude> add 1 2 + 3 + Prelude> + +However, this quickly gets tedious when defining functions with multiple +clauses, or groups of mutually recursive functions, because the complete +definition has to be given on a single line, using explicit semicolons +instead of layout: + +:: + + Prelude> let f op n [] = n ; f op n (h:t) = h `op` f op n t + Prelude> f (+) 0 [1..3] + 6 + Prelude> + +To alleviate this issue, GHCi commands can be split over multiple lines, +by wrapping them in ``:{`` and ``:}`` (each on a single line of its +own): + +:: + + Prelude> :{ + Prelude| let g op n [] = n + Prelude| g op n (h:t) = h `op` g op n t + Prelude| :} + Prelude> g (*) 1 [1..3] + 6 + +Such multiline commands can be used with any GHCi command, and note that +the layout rule is in effect. The main purpose of multiline commands is +not to replace module loading but to make definitions in .ghci-files +(see :ref:`ghci-dot-files`) more readable and maintainable. + +Any exceptions raised during the evaluation or execution of the +statement are caught and printed by the GHCi command line interface (for +more information on exceptions, see the module ``Control.Exception`` in +the libraries documentation). + +Every new binding shadows any existing bindings of the same name, +including entities that are in scope in the current module context. + +.. warning:: + Temporary bindings introduced at the prompt only last until the + next ``:load`` or ``:reload`` command, at which time they will be simply + lost. However, they do survive a change of context with ``:module``: the + temporary bindings just move to the new location. + +.. hint:: + To get a list of the bindings currently in scope, use the + ``:show bindings`` command: + + :: + + Prelude> :show bindings + x :: Int + Prelude> + +.. hint:: + If you turn on the ``+t`` option, GHCi will show the type of each + variable bound by a statement. For example: + + :: + + Prelude> :set +t + Prelude> let (x:xs) = [1..] + x :: Integer + xs :: [Integer] + + .. index:: + single: +t option; in GHCi + + +.. _ghci-multiline: + +Multiline input +~~~~~~~~~~~~~~~ + +Apart from the ``:{ ... :}`` syntax for multi-line input mentioned +above, GHCi also has a multiline mode, enabled by ``:set +m``, +``:set +m`` in which GHCi detects automatically when the current +statement is unfinished and allows further lines to be added. A +multi-line input is terminated with an empty line. For example: + +:: + + Prelude> :set +m + Prelude> let x = 42 + Prelude| + +Further bindings can be added to this ``let`` statement, so GHCi +indicates that the next line continues the previous one by changing the +prompt. Note that layout is in effect, so to add more bindings to this +``let`` we have to line them up: + +:: + + Prelude> :set +m + Prelude> let x = 42 + Prelude| y = 3 + Prelude| + Prelude> + +Explicit braces and semicolons can be used instead of layout: + +:: + + Prelude> do { + Prelude| putStrLn "hello" + Prelude| ;putStrLn "world" + Prelude| } + hello + world + Prelude> + +Note that after the closing brace, GHCi knows that the current statement +is finished, so no empty line is required. + +Multiline mode is useful when entering monadic ``do`` statements: + +:: + + Control.Monad.State> flip evalStateT 0 $ do + Control.Monad.State| i <- get + Control.Monad.State| lift $ do + Control.Monad.State| putStrLn "Hello World!" + Control.Monad.State| print i + Control.Monad.State| + "Hello World!" + 0 + Control.Monad.State> + +During a multiline interaction, the user can interrupt and return to the +top-level prompt. + +:: + + Prelude> do + Prelude| putStrLn "Hello, World!" + Prelude| ^C + Prelude> + +.. _ghci-decls: + +Type, class and other declarations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +At the GHCi prompt you can also enter any top-level Haskell declaration, +including ``data``, ``type``, ``newtype``, ``class``, ``instance``, +``deriving``, and ``foreign`` declarations. For example: + +:: + + Prelude> data T = A | B | C deriving (Eq, Ord, Show, Enum) + Prelude> [A ..] + [A,B,C] + Prelude> :i T + data T = A | B | C -- Defined at <interactive>:2:6 + instance Enum T -- Defined at <interactive>:2:45 + instance Eq T -- Defined at <interactive>:2:30 + instance Ord T -- Defined at <interactive>:2:34 + instance Show T -- Defined at <interactive>:2:39 + +As with ordinary variable bindings, later definitions shadow earlier +ones, so you can re-enter a declaration to fix a problem with it or +extend it. But there's a gotcha: when a new type declaration shadows an +older one, there might be other declarations that refer to the old type. +The thing to remember is that the old type still exists, and these other +declarations still refer to the old type. However, while the old and the +new type have the same name, GHCi will treat them as distinct. For +example: + +:: + + Prelude> data T = A | B + Prelude> let f A = True; f B = False + Prelude> data T = A | B | C + Prelude> f A + + <interactive>:2:3: + Couldn't match expected type `main::Interactive.T' + with actual type `T' + In the first argument of `f', namely `A' + In the expression: f A + In an equation for `it': it = f A + Prelude> + +The old, shadowed, version of ``T`` is displayed as +``main::Interactive.T`` by GHCi in an attempt to distinguish it from the +new ``T``, which is displayed as simply ``T``. + +Class and type-family instance declarations are simply added to the list +of available instances, with one exception. Since you might want to +re-define one, a class or type-family instance *replaces* any earlier +instance with an identical head or left hand side (respectively). (See +:ref:`type-families`.) + +.. _ghci-scope: + +What's really in scope at the prompt? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When you type an expression at the prompt, what identifiers and types +are in scope? GHCi provides a flexible way to control exactly how the +context for an expression is constructed: + +- The ``:load``, ``:add``, and ``:reload`` commands + (:ref:`ghci-load-scope`). + +- The ``import`` declaration (:ref:`ghci-import-decl`). + +- The ``:module`` command (:ref:`ghci-module-cmd`). + +The command ``:show imports`` will show a summary of which modules +contribute to the top-level scope. + +.. hint:: + GHCi will tab-complete names that are in scope; for example, if + you run GHCi and type ``J<tab>`` then GHCi will expand it to + “\ ``Just``\ ”. + +.. _ghci-load-scope: + +The effect of ``:load`` on what is in scope +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``:load``, ``:add``, and ``:reload`` commands +(:ref:`loading-source-files` and :ref:`ghci-compiled`) affect the +top-level scope. Let's start with the simple cases; when you start GHCi +the prompt looks like this: + +:: + + Prelude> + +which indicates that everything from the module ``Prelude`` is currently +in scope; the visible identifiers are exactly those that would be +visible in a Haskell source file with no ``import`` declarations. + +If we now load a file into GHCi, the prompt will change: + +:: + + Prelude> :load Main.hs + Compiling Main ( Main.hs, interpreted ) + *Main> + +The new prompt is ``*Main``, which indicates that we are typing +expressions in the context of the top-level of the ``Main`` module. +Everything that is in scope at the top-level in the module ``Main`` we +just loaded is also in scope at the prompt (probably including +``Prelude``, as long as ``Main`` doesn't explicitly hide it). + +The syntax in the prompt ``*module`` indicates that it is the full +top-level scope of ⟨module⟩ that is contributing to the scope for +expressions typed at the prompt. Without the ``*``, just the exports of +the module are visible. + +.. note:: + For technical reasons, GHCi can only support the ``*``-form for + modules that are interpreted. Compiled modules and package modules can + only contribute their exports to the current scope. To ensure that GHCi + loads the interpreted version of a module, add the ``*`` when loading + the module, e.g. ``:load *M``. + +In general, after a ``:load`` command, an automatic import is added to +the scope for the most recently loaded "target" module, in a ``*``-form +if possible. For example, if you say ``:load foo.hs bar.hs`` and +``bar.hs`` contains module ``Bar``, then the scope will be set to +``*Bar`` if ``Bar`` is interpreted, or if ``Bar`` is compiled it will be +set to ``Prelude Bar`` (GHCi automatically adds ``Prelude`` if it isn't +present and there aren't any ``*``-form modules). These +automatically-added imports can be seen with ``:show imports``: + +:: + + Prelude> :load hello.hs + [1 of 1] Compiling Main ( hello.hs, interpreted ) + Ok, modules loaded: Main. + *Main> :show imports + :module +*Main -- added automatically + *Main> + +and the automatically-added import is replaced the next time you use +``:load``, ``:add``, or ``:reload``. It can also be removed by +``:module`` as with normal imports. + +.. _ghci-import-decl: + +Controlling what is in scope with ``import`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We are not limited to a single module: GHCi can combine scopes from +multiple modules, in any mixture of ``*`` and non-\ ``*`` forms. GHCi +combines the scopes from all of these modules to form the scope that is +in effect at the prompt. + +To add modules to the scope, use ordinary Haskell ``import`` syntax: + +:: + + Prelude> import System.IO + Prelude System.IO> hPutStrLn stdout "hello\n" + hello + Prelude System.IO> + +The full Haskell import syntax is supported, including ``hiding`` and +``as`` clauses. The prompt shows the modules that are currently +imported, but it omits details about ``hiding``, ``as``, and so on. To +see the full story, use ``:show imports``: + +:: + + Prelude> import System.IO + Prelude System.IO> import Data.Map as Map + Prelude System.IO Map> :show imports + import Prelude -- implicit + import System.IO + import Data.Map as Map + Prelude System.IO Map> + +Note that the ``Prelude`` import is marked as implicit. It can be +overridden with an explicit ``Prelude`` import, just like in a Haskell +module. + +With multiple modules in scope, especially multiple ``*``-form modules, +it is likely that name clashes will occur. Haskell specifies that name +clashes are only reported when an ambiguous identifier is used, and GHCi +behaves in the same way for expressions typed at the prompt. + +.. _ghci-module-cmd: + +Controlling what is in scope with the ``:module`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Another way to manipulate the scope is to use the ``:module`` command, +whose syntax is this: + +:: + + :module +|- *mod1 ... *modn + +Using the ``+`` form of the ``module`` commands adds modules to the +current scope, and ``-`` removes them. Without either ``+`` or ``-``, +the current scope is replaced by the set of modules specified. Note that +if you use this form and leave out ``Prelude``, an implicit ``Prelude`` +import will be added automatically. + +The ``:module`` command provides a way to do two things that cannot be +done with ordinary ``import`` declarations: + +- ``:module`` supports the ``*`` modifier on modules, which opens the + full top-level scope of a module, rather than just its exports. + +- Imports can be *removed* from the context, using the syntax + ``:module -M``. The ``import`` syntax is cumulative (as in a Haskell + module), so this is the only way to subtract from the scope. + +.. _ghci-import-qualified: + +Qualified names +^^^^^^^^^^^^^^^ + +To make life slightly easier, the GHCi prompt also behaves as if there +is an implicit ``import qualified`` declaration for every module in +every package, and every module currently loaded into GHCi. This +behaviour can be disabled with the ``-fno-implicit-import-qualified`` flag. + +.. index:: + single: -fno-implicit-import-qualified + +``:module`` and ``:load`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +It might seem that ``:module``/``import`` and +``:load``/``:add``/``:reload`` do similar things: you can use both to +bring a module into scope. However, there is a very important +difference. GHCi is concerned with two sets of modules: + +- The set of modules that are currently *loaded*. This set is modified + by ``:load``, ``:add`` and ``:reload``, and can be shown with + ``:show modules``. + +- The set of modules that are currently *in scope* at the prompt. This + set is modified by ``import`` and ``:module``, and it is also + modified automatically after ``:load``, ``:add``, and ``:reload``, as + described above. The set of modules in scope can be shown with + ``:show imports``. + +You can add a module to the scope (via ``:module`` or ``import``) only +if either (a) it is loaded, or (b) it is a module from a package that +GHCi knows about. Using ``:module`` or ``import`` to try bring into +scope a non-loaded module may result in the message +“\ ``module M is not loaded``\ ”. + +The ``:main`` and ``:run`` commands +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When a program is compiled and executed, it can use the ``getArgs`` +function to access the command-line arguments. However, we cannot simply +pass the arguments to the ``main`` function while we are testing in +ghci, as the ``main`` function doesn't take its directly. + +Instead, we can use the ``:main`` command. This runs whatever ``main`` +is in scope, with any arguments being treated the same as command-line +arguments, e.g.: + +:: + + Prelude> let main = System.Environment.getArgs >>= print + Prelude> :main foo bar + ["foo","bar"] + +We can also quote arguments which contains characters like spaces, and +they are treated like Haskell strings, or we can just use Haskell list +syntax: + +:: + + Prelude> :main foo "bar baz" + ["foo","bar baz"] + Prelude> :main ["foo", "bar baz"] + ["foo","bar baz"] + +Finally, other functions can be called, either with the ``-main-is`` +flag or the ``:run`` command: + +:: + + Prelude> let foo = putStrLn "foo" >> System.Environment.getArgs >>= print + Prelude> let bar = putStrLn "bar" >> System.Environment.getArgs >>= print + Prelude> :set -main-is foo + Prelude> :main foo "bar baz" + foo + ["foo","bar baz"] + Prelude> :run bar ["foo", "bar baz"] + bar + ["foo","bar baz"] + +The ``it`` variable +~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: it variable + +Whenever an expression (or a non-binding statement, to be precise) is +typed at the prompt, GHCi implicitly binds its value to the variable +``it``. For example: + +:: + + Prelude> 1+2 + 3 + Prelude> it * 2 + 6 + +What actually happens is that GHCi typechecks the expression, and if it +doesn't have an ``IO`` type, then it transforms it as follows: an +expression ``e`` turns into + +:: + + let it = e; + print it + +which is then run as an IO-action. + +Hence, the original expression must have a type which is an instance of +the ``Show`` class, or GHCi will complain: + +:: + + Prelude> id + + <interactive>:1:0: + No instance for (Show (a -> a)) + arising from use of `print' at <interactive>:1:0-1 + Possible fix: add an instance declaration for (Show (a -> a)) + In the expression: print it + In a 'do' expression: print it + +The error message contains some clues as to the transformation happening +internally. + +If the expression was instead of type ``IO a`` for some ``a``, then +``it`` will be bound to the result of the ``IO`` computation, which is +of type ``a``. eg.: + +:: + + Prelude> Time.getClockTime + Wed Mar 14 12:23:13 GMT 2001 + Prelude> print it + Wed Mar 14 12:23:13 GMT 2001 + +The corresponding translation for an IO-typed ``e`` is + +:: + + it <- e + +Note that ``it`` is shadowed by the new value each time you evaluate a +new expression, and the old value of ``it`` is lost. + +.. _extended-default-rules: + +Type defaulting in GHCi +~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: Type defaulting; in GHCi + single: Show class + +Consider this GHCi session: + +:: + + ghci> reverse [] + +What should GHCi do? Strictly speaking, the program is ambiguous. +``show (reverse [])`` (which is what GHCi computes here) has type +``Show a => String`` and how that displays depends on the type ``a``. +For example: + +:: + + ghci> reverse ([] :: String) + "" + ghci> reverse ([] :: [Int]) + [] + +However, it is tiresome for the user to have to specify the type, so +GHCi extends Haskell's type-defaulting rules (Section 4.3.4 of the +Haskell 2010 Report) as follows. The standard rules take each group of +constraints ``(C1 a, C2 a, ..., Cn a)`` for each type variable ``a``, +and defaults the type variable if + +1. The type variable ``a`` appears in no other constraints + +2. All the classes ``Ci`` are standard. + +3. At least one of the classes ``Ci`` is numeric. + +At the GHCi prompt, or with GHC if the ``-XExtendedDefaultRules`` flag +is given, the following additional differences apply: + +- Rule 2 above is relaxed thus: *All* of the classes ``Ci`` are + single-parameter type classes. + +- Rule 3 above is relaxed this: At least one of the classes ``Ci`` is + numeric, or is ``Show``, ``Eq``, or ``Ord``. + +- The unit type ``()`` is added to the start of the standard list of + types which are tried when doing type defaulting. + +The last point means that, for example, this program: + +:: + + main :: IO () + main = print def + + instance Num () + + def :: (Num a, Enum a) => a + def = toEnum 0 + +prints ``()`` rather than ``0`` as the type is defaulted to ``()`` +rather than ``Integer``. + +The motivation for the change is that it means ``IO a`` actions default +to ``IO ()``, which in turn means that ghci won't try to print a result +when running them. This is particularly important for ``printf``, which +has an instance that returns ``IO a``. However, it is only able to +return ``undefined`` (the reason for the instance having this type is so +that printf doesn't require extensions to the class system), so if the +type defaults to ``Integer`` then ghci gives an error when running a +printf. + +See also :ref:`actions-at-prompt` for how the monad of a computational +expression defaults to ``IO`` if possible. + +.. _ghci-interactive-print: + +Using a custom interactive printing function +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: Custom printing function; in GHCi + +[**New in version 7.6.1**] By default, GHCi prints the result of +expressions typed at the prompt using the function ``System.IO.print``. +Its type signature is ``Show a => a -> IO ()``, and it works by +converting the value to ``String`` using ``show``. + +This is not ideal in certain cases, like when the output is long, or +contains strings with non-ascii characters. + +The ``-interactive-print`` flag allows to specify any function of type +``C a => a -> IO ()``, for some constraint ``C``, as the function for +printing evaluated expressions. The function can reside in any loaded +module or any registered package. + +As an example, suppose we have following special printing module: + +:: + + module SpecPrinter where + import System.IO + + sprint a = putStrLn $ show a ++ "!" + +The ``sprint`` function adds an exclamation mark at the end of any +printed value. Running GHCi with the command: + +:: + + ghci -interactive-print=SpecPrinter.sprinter SpecPrinter + +will start an interactive session where values with be printed using +``sprint``: + +:: + + *SpecPrinter> [1,2,3] + [1,2,3]! + *SpecPrinter> 42 + 42! + +A custom pretty printing function can be used, for example, to format +tree-like and nested structures in a more readable way. + +The ``-interactive-print`` flag can also be used when running GHC in +``-e mode``: + +:: + + % ghc -e "[1,2,3]" -interactive-print=SpecPrinter.sprint SpecPrinter + [1,2,3]! + +.. _ghci-debugger: + +The GHCi Debugger +----------------- + +.. index:: + single: debugger; in GHCi + +GHCi contains a simple imperative-style debugger in which you can stop a +running computation in order to examine the values of variables. The +debugger is integrated into GHCi, and is turned on by default: no flags +are required to enable the debugging facilities. There is one major +restriction: breakpoints and single-stepping are only available in +interpreted modules; compiled code is invisible to the debugger [5]_. + +The debugger provides the following: + +- The ability to set a breakpoint on a function definition or + expression in the program. When the function is called, or the + expression evaluated, GHCi suspends execution and returns to the + prompt, where you can inspect the values of local variables before + continuing with the execution. + +- Execution can be single-stepped: the evaluator will suspend execution + approximately after every reduction, allowing local variables to be + inspected. This is equivalent to setting a breakpoint at every point + in the program. + +- Execution can take place in tracing mode, in which the evaluator + remembers each evaluation step as it happens, but doesn't suspend + execution until an actual breakpoint is reached. When this happens, + the history of evaluation steps can be inspected. + +- Exceptions (e.g. pattern matching failure and ``error``) can be + treated as breakpoints, to help locate the source of an exception in + the program. + +There is currently no support for obtaining a “stack trace”, but the +tracing and history features provide a useful second-best, which will +often be enough to establish the context of an error. For instance, it +is possible to break automatically when an exception is thrown, even if +it is thrown from within compiled code (see +:ref:`ghci-debugger-exceptions`). + +.. _breakpoints: + +Breakpoints and inspecting variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Let's use quicksort as a running example. Here's the code: + +:: + + qsort [] = [] + qsort (a:as) = qsort left ++ [a] ++ qsort right + where (left,right) = (filter (<=a) as, filter (>a) as) + + main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18]) + +First, load the module into GHCi: + +:: + + Prelude> :l qsort.hs + [1 of 1] Compiling Main ( qsort.hs, interpreted ) + Ok, modules loaded: Main. + *Main> + +Now, let's set a breakpoint on the right-hand-side of the second +equation of qsort: + +:: + + *Main> :break 2 + Breakpoint 0 activated at qsort.hs:2:15-46 + *Main> + +The command ``:break 2`` sets a breakpoint on line 2 of the most +recently-loaded module, in this case ``qsort.hs``. Specifically, it +picks the leftmost complete subexpression on that line on which to set +the breakpoint, which in this case is the expression +``(qsort left ++ [a] ++ qsort right)``. + +Now, we run the program: + +:: + + *Main> main + Stopped at qsort.hs:2:15-46 + _result :: [a] + a :: a + left :: [a] + right :: [a] + [qsort.hs:2:15-46] *Main> + +Execution has stopped at the breakpoint. The prompt has changed to +indicate that we are currently stopped at a breakpoint, and the +location: ``[qsort.hs:2:15-46]``. To further clarify the location, we +can use the ``:list`` command: + +:: + + [qsort.hs:2:15-46] *Main> :list + 1 qsort [] = [] + 2 qsort (a:as) = qsort left ++ [a] ++ qsort right + 3 where (left,right) = (filter (<=a) as, filter (>a) as) + +The ``:list`` command lists the source code around the current +breakpoint. If your output device supports it, then GHCi will highlight +the active subexpression in bold. + +GHCi has provided bindings for the free variables [6]_ of the expression +on which the breakpoint was placed (``a``, ``left``, ``right``), and +additionally a binding for the result of the expression (``_result``). +These variables are just like other variables that you might define in +GHCi; you can use them in expressions that you type at the prompt, you +can ask for their types with ``:type``, and so on. There is one +important difference though: these variables may only have partial +types. For example, if we try to display the value of ``left``: + +:: + + [qsort.hs:2:15-46] *Main> left + + <interactive>:1:0: + Ambiguous type variable `a' in the constraint: + `Show a' arising from a use of `print' at <interactive>:1:0-3 + Cannot resolve unknown runtime types: a + Use :print or :force to determine these types + +This is because ``qsort`` is a polymorphic function, and because GHCi +does not carry type information at runtime, it cannot determine the +runtime types of free variables that involve type variables. Hence, when +you ask to display ``left`` at the prompt, GHCi can't figure out which +instance of ``Show`` to use, so it emits the type error above. + +Fortunately, the debugger includes a generic printing command, +``:print``, which can inspect the actual runtime value of a variable and +attempt to reconstruct its type. If we try it on ``left``: + +:: + + [qsort.hs:2:15-46] *Main> :set -fprint-evld-with-show + [qsort.hs:2:15-46] *Main> :print left + left = (_t1::[a]) + +This isn't particularly enlightening. What happened is that ``left`` is +bound to an unevaluated computation (a suspension, or thunk), and +``:print`` does not force any evaluation. The idea is that ``:print`` +can be used to inspect values at a breakpoint without any unfortunate +side effects. It won't force any evaluation, which could cause the +program to give a different answer than it would normally, and hence it +won't cause any exceptions to be raised, infinite loops, or further +breakpoints to be triggered (see :ref:`nested-breakpoints`). Rather than +forcing thunks, ``:print`` binds each thunk to a fresh variable +beginning with an underscore, in this case ``_t1``. + +The flag ``-fprint-evld-with-show`` instructs ``:print`` to reuse +available ``Show`` instances when possible. This happens only when the +contents of the variable being inspected are completely evaluated. + +If we aren't concerned about preserving the evaluatedness of a variable, +we can use ``:force`` instead of ``:print``. The ``:force`` command +behaves exactly like ``:print``, except that it forces the evaluation of +any thunks it encounters: + +:: + + [qsort.hs:2:15-46] *Main> :force left + left = [4,0,3,1] + +Now, since ``:force`` has inspected the runtime value of ``left``, it +has reconstructed its type. We can see the results of this type +reconstruction: + +:: + + [qsort.hs:2:15-46] *Main> :show bindings + _result :: [Integer] + a :: Integer + left :: [Integer] + right :: [Integer] + _t1 :: [Integer] + +Not only do we now know the type of ``left``, but all the other partial +types have also been resolved. So we can ask for the value of ``a``, for +example: + +:: + + [qsort.hs:2:15-46] *Main> a + 8 + +You might find it useful to use Haskell's ``seq`` function to evaluate +individual thunks rather than evaluating the whole expression with +``:force``. For example: + +:: + + [qsort.hs:2:15-46] *Main> :print right + right = (_t1::[Integer]) + [qsort.hs:2:15-46] *Main> seq _t1 () + () + [qsort.hs:2:15-46] *Main> :print right + right = 23 : (_t2::[Integer]) + +We evaluated only the ``_t1`` thunk, revealing the head of the list, and +the tail is another thunk now bound to ``_t2``. The ``seq`` function is +a little inconvenient to use here, so you might want to use ``:def`` to +make a nicer interface (left as an exercise for the reader!). + +Finally, we can continue the current execution: + +:: + + [qsort.hs:2:15-46] *Main> :continue + Stopped at qsort.hs:2:15-46 + _result :: [a] + a :: a + left :: [a] + right :: [a] + [qsort.hs:2:15-46] *Main> + +The execution continued at the point it previously stopped, and has now +stopped at the breakpoint for a second time. + +.. _setting-breakpoints: + +Setting breakpoints +^^^^^^^^^^^^^^^^^^^ + +Breakpoints can be set in various ways. Perhaps the easiest way to set a +breakpoint is to name a top-level function: + +:: + + :break identifier + +Where ⟨identifier⟩ names any top-level function in an interpreted module +currently loaded into GHCi (qualified names may be used). The breakpoint +will be set on the body of the function, when it is fully applied but +before any pattern matching has taken place. + +Breakpoints can also be set by line (and optionally column) number: + +:: + + :break line + :break line column + :break module line + :break module line column + +When a breakpoint is set on a particular line, GHCi sets the breakpoint +on the leftmost subexpression that begins and ends on that line. If two +complete subexpressions start at the same column, the longest one is +picked. If there is no complete subexpression on the line, then the +leftmost expression starting on the line is picked, and failing that the +rightmost expression that partially or completely covers the line. + +When a breakpoint is set on a particular line and column, GHCi picks the +smallest subexpression that encloses that location on which to set the +breakpoint. Note: GHC considers the TAB character to have a width of 1, +wherever it occurs; in other words it counts characters, rather than +columns. This matches what some editors do, and doesn't match others. +The best advice is to avoid tab characters in your source code +altogether (see ``-fwarn-tabs`` in :ref:`options-sanity`). + +If the module is omitted, then the most recently-loaded module is used. + +Not all subexpressions are potential breakpoint locations. Single +variables are typically not considered to be breakpoint locations +(unless the variable is the right-hand-side of a function definition, +lambda, or case alternative). The rule of thumb is that all redexes are +breakpoint locations, together with the bodies of functions, lambdas, +case alternatives and binding statements. There is normally no +breakpoint on a let expression, but there will always be a breakpoint on +its body, because we are usually interested in inspecting the values of +the variables bound by the let. + +Listing and deleting breakpoints +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The list of breakpoints currently enabled can be displayed using +``:show breaks``: + +:: + + *Main> :show breaks + [0] Main qsort.hs:1:11-12 + [1] Main qsort.hs:2:15-46 + +To delete a breakpoint, use the ``:delete`` command with the number +given in the output from ``:show breaks``: + +:: + + *Main> :delete 0 + *Main> :show breaks + [1] Main qsort.hs:2:15-46 + +To delete all breakpoints at once, use ``:delete *``. + +.. _single-stepping: + +Single-stepping +~~~~~~~~~~~~~~~ + +Single-stepping is a great way to visualise the execution of your +program, and it is also a useful tool for identifying the source of a +bug. GHCi offers two variants of stepping. Use ``:step`` to enable all +the breakpoints in the program, and execute until the next breakpoint is +reached. Use ``:steplocal`` to limit the set of enabled breakpoints to +those in the current top level function. Similarly, use ``:stepmodule`` +to single step only on breakpoints contained in the current module. For +example: + +:: + + *Main> :step main + Stopped at qsort.hs:5:7-47 + _result :: IO () + +The command ``:step expr`` begins the evaluation of ⟨expr⟩ in +single-stepping mode. If ⟨expr⟩ is omitted, then it single-steps from +the current breakpoint. ``:steplocal`` and ``:stepmodule`` work +similarly. + +The ``:list`` command is particularly useful when single-stepping, to +see where you currently are: + +:: + + [qsort.hs:5:7-47] *Main> :list + 4 + 5 main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18]) + 6 + [qsort.hs:5:7-47] *Main> + +In fact, GHCi provides a way to run a command when a breakpoint is hit, +so we can make it automatically do ``:list``: + +:: + + [qsort.hs:5:7-47] *Main> :set stop :list + [qsort.hs:5:7-47] *Main> :step + Stopped at qsort.hs:5:14-46 + _result :: [Integer] + 4 + 5 main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18]) + 6 + [qsort.hs:5:14-46] *Main> + +.. _nested-breakpoints: + +Nested breakpoints +~~~~~~~~~~~~~~~~~~ + +When GHCi is stopped at a breakpoint, and an expression entered at the +prompt triggers a second breakpoint, the new breakpoint becomes the +"current" one, and the old one is saved on a stack. An arbitrary number +of breakpoint contexts can be built up in this way. For example: + +:: + + [qsort.hs:2:15-46] *Main> :st qsort [1,3] + Stopped at qsort.hs:(1,0)-(3,55) + _result :: [a] + ... [qsort.hs:(1,0)-(3,55)] *Main> + +While stopped at the breakpoint on line 2 that we set earlier, we +started a new evaluation with ``:step qsort [1,3]``. This new evaluation +stopped after one step (at the definition of ``qsort``). The prompt has +changed, now prefixed with ``...``, to indicate that there are saved +breakpoints beyond the current one. To see the stack of contexts, use +``:show context``: + +:: + + ... [qsort.hs:(1,0)-(3,55)] *Main> :show context + --> main + Stopped at qsort.hs:2:15-46 + --> qsort [1,3] + Stopped at qsort.hs:(1,0)-(3,55) + ... [qsort.hs:(1,0)-(3,55)] *Main> + +To abandon the current evaluation, use ``:abandon``: + +:: + + ... [qsort.hs:(1,0)-(3,55)] *Main> :abandon + [qsort.hs:2:15-46] *Main> :abandon + *Main> + +.. _ghci-debugger-result: + +The ``_result`` variable +~~~~~~~~~~~~~~~~~~~~~~~~ + +When stopped at a breakpoint or single-step, GHCi binds the variable +``_result`` to the value of the currently active expression. The value +of ``_result`` is presumably not available yet, because we stopped its +evaluation, but it can be forced: if the type is known and showable, +then just entering ``_result`` at the prompt will show it. However, +there's one caveat to doing this: evaluating ``_result`` will be likely +to trigger further breakpoints, starting with the breakpoint we are +currently stopped at (if we stopped at a real breakpoint, rather than +due to ``:step``). So it will probably be necessary to issue a +``:continue`` immediately when evaluating ``_result``. Alternatively, +you can use ``:force`` which ignores breakpoints. + +.. _tracing: + +Tracing and history +~~~~~~~~~~~~~~~~~~~ + +A question that we often want to ask when debugging a program is “how +did I get here?”. Traditional imperative debuggers usually provide some +kind of stack-tracing feature that lets you see the stack of active +function calls (sometimes called the “lexical call stack”), describing a +path through the code to the current location. Unfortunately this is +hard to provide in Haskell, because execution proceeds on a +demand-driven basis, rather than a depth-first basis as in strict +languages. The “stack“ in GHC's execution engine bears little +resemblance to the lexical call stack. Ideally GHCi would maintain a +separate lexical call stack in addition to the dynamic call stack, and +in fact this is exactly what our profiling system does +(:ref:`profiling`), and what some other Haskell debuggers do. For the +time being, however, GHCi doesn't maintain a lexical call stack (there +are some technical challenges to be overcome). Instead, we provide a way +to backtrack from a breakpoint to previous evaluation steps: essentially +this is like single-stepping backwards, and should in many cases provide +enough information to answer the "how did I get here?" question. + +To use tracing, evaluate an expression with the ``:trace`` command. For +example, if we set a breakpoint on the base case of ``qsort``: + +:: + + *Main> :list qsort + 1 qsort [] = [] + 2 qsort (a:as) = qsort left ++ [a] ++ qsort right + 3 where (left,right) = (filter (<=a) as, filter (>a) as) + 4 + *Main> :b 1 + Breakpoint 1 activated at qsort.hs:1:11-12 + *Main> + +and then run a small ``qsort`` with tracing: + +:: + + *Main> :trace qsort [3,2,1] + Stopped at qsort.hs:1:11-12 + _result :: [a] + [qsort.hs:1:11-12] *Main> + +We can now inspect the history of evaluation steps: + +:: + + [qsort.hs:1:11-12] *Main> :hist + -1 : qsort.hs:3:24-38 + -2 : qsort.hs:3:23-55 + -3 : qsort.hs:(1,0)-(3,55) + -4 : qsort.hs:2:15-24 + -5 : qsort.hs:2:15-46 + -6 : qsort.hs:3:24-38 + -7 : qsort.hs:3:23-55 + -8 : qsort.hs:(1,0)-(3,55) + -9 : qsort.hs:2:15-24 + -10 : qsort.hs:2:15-46 + -11 : qsort.hs:3:24-38 + -12 : qsort.hs:3:23-55 + -13 : qsort.hs:(1,0)-(3,55) + -14 : qsort.hs:2:15-24 + -15 : qsort.hs:2:15-46 + -16 : qsort.hs:(1,0)-(3,55) + <end of history> + +To examine one of the steps in the history, use ``:back``: + +:: + + [qsort.hs:1:11-12] *Main> :back + Logged breakpoint at qsort.hs:3:24-38 + _result :: [a] + as :: [a] + a :: a + [-1: qsort.hs:3:24-38] *Main> + +Note that the local variables at each step in the history have been +preserved, and can be examined as usual. Also note that the prompt has +changed to indicate that we're currently examining the first step in the +history: ``-1``. The command ``:forward`` can be used to traverse +forward in the history. + +The ``:trace`` command can be used with or without an expression. When +used without an expression, tracing begins from the current breakpoint, +just like ``:step``. + +The history is only available when using ``:trace``; the reason for this +is we found that logging each breakpoint in the history cuts performance +by a factor of 2 or more. By default, GHCi remembers the last 50 steps +in the history, but this can be changed with the ``-fghci-hist-size=n`` option). + +.. index:: + single: -fghci-hist-size + +.. _ghci-debugger-exceptions: + +Debugging exceptions +~~~~~~~~~~~~~~~~~~~~ + +Another common question that comes up when debugging is "where did this +exception come from?". Exceptions such as those raised by ``error`` or +``head []`` have no context information attached to them. Finding which +particular call to ``head`` in your program resulted in the error can be +a painstaking process, usually involving ``Debug.Trace.trace``, or +compiling with profiling and using ``Debug.Trace.traceStack`` or +``+RTS -xc`` (see :ref:`prof-time-options`). + +The GHCi debugger offers a way to hopefully shed some light on these +errors quickly and without modifying or recompiling the source code. One +way would be to set a breakpoint on the location in the source code that +throws the exception, and then use ``:trace`` and ``:history`` to +establish the context. However, ``head`` is in a library and we can't +set a breakpoint on it directly. For this reason, GHCi provides the +flags ``-fbreak-on-exception`` which causes the evaluator to stop when +an exception is thrown, and ``-fbreak-on-error``, which works similarly +but stops only on uncaught exceptions. When stopping at an exception, +GHCi will act just as it does when a breakpoint is hit, with the +deviation that it will not show you any source code location. Due to +this, these commands are only really useful in conjunction with +``:trace``, in order to log the steps leading up to the exception. For +example: + +:: + + *Main> :set -fbreak-on-exception + *Main> :trace qsort ("abc" ++ undefined) + “Stopped at <exception thrown> + _exception :: e + [<exception thrown>] *Main> :hist + -1 : qsort.hs:3:24-38 + -2 : qsort.hs:3:23-55 + -3 : qsort.hs:(1,0)-(3,55) + -4 : qsort.hs:2:15-24 + -5 : qsort.hs:2:15-46 + -6 : qsort.hs:(1,0)-(3,55) + <end of history> + [<exception thrown>] *Main> :back + Logged breakpoint at qsort.hs:3:24-38 + _result :: [a] + as :: [a] + a :: a + [-1: qsort.hs:3:24-38] *Main> :force as + *** Exception: Prelude.undefined + [-1: qsort.hs:3:24-38] *Main> :print as + as = 'b' : 'c' : (_t1::[Char]) + +The exception itself is bound to a new variable, ``_exception``. + +Breaking on exceptions is particularly useful for finding out what your +program was doing when it was in an infinite loop. Just hit Control-C, +and examine the history to find out what was going on. + +Example: inspecting functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is possible to use the debugger to examine function values. When we +are at a breakpoint and a function is in scope, the debugger cannot show +you the source code for it; however, it is possible to get some +information by applying it to some arguments and observing the result. + +The process is slightly complicated when the binding is polymorphic. We +show the process by means of an example. To keep things simple, we will +use the well known ``map`` function: + +:: + + import Prelude hiding (map) + + map :: (a->b) -> [a] -> [b] + map f [] = [] + map f (x:xs) = f x : map f xs + +We set a breakpoint on ``map``, and call it. + +:: + + *Main> :break 5 + Breakpoint 0 activated at map.hs:5:15-28 + *Main> map Just [1..5] + Stopped at map.hs:(4,0)-(5,12) + _result :: [b] + x :: a + f :: a -> b + xs :: [a] + +GHCi tells us that, among other bindings, ``f`` is in scope. However, +its type is not fully known yet, and thus it is not possible to apply it +to any arguments. Nevertheless, observe that the type of its first +argument is the same as the type of ``x``, and its result type is shared +with ``_result``. + +As we demonstrated earlier (:ref:`breakpoints`), the debugger has some +intelligence built-in to update the type of ``f`` whenever the types of +``x`` or ``_result`` are discovered. So what we do in this scenario is +force ``x`` a bit, in order to recover both its type and the argument +part of ``f``. + +:: + + *Main> seq x () + *Main> :print x + x = 1 + +We can check now that as expected, the type of ``x`` has been +reconstructed, and with it the type of ``f`` has been too: + +:: + + *Main> :t x + x :: Integer + *Main> :t f + f :: Integer -> b + +From here, we can apply f to any argument of type Integer and observe +the results. + +:: + + *Main> let b = f 10 + *Main> :t b + b :: b + *Main> b + <interactive>:1:0: + Ambiguous type variable `b' in the constraint: + `Show b' arising from a use of `print' at <interactive>:1:0 + *Main> :p b + b = (_t2::a) + *Main> seq b () + () + *Main> :t b + b :: a + *Main> :p b + b = Just 10 + *Main> :t b + b :: Maybe Integer + *Main> :t f + f :: Integer -> Maybe Integer + *Main> f 20 + Just 20 + *Main> map f [1..5] + [Just 1, Just 2, Just 3, Just 4, Just 5] + +In the first application of ``f``, we had to do some more type +reconstruction in order to recover the result type of ``f``. But after +that, we are free to use ``f`` normally. + +Limitations +~~~~~~~~~~~ + +- When stopped at a breakpoint, if you try to evaluate a variable that + is already under evaluation, the second evaluation will hang. The + reason is that GHC knows the variable is under evaluation, so the new + evaluation just waits for the result before continuing, but of course + this isn't going to happen because the first evaluation is stopped at + a breakpoint. Control-C can interrupt the hung evaluation and return + to the prompt. + + The most common way this can happen is when you're evaluating a CAF + (e.g. main), stop at a breakpoint, and ask for the value of the CAF + at the prompt again. + +- Implicit parameters (see :ref:`implicit-parameters`) are only + available at the scope of a breakpoint if there is an explicit type + signature. + +.. _ghci-invocation: + +Invoking GHCi +------------- + +.. index:: + single: invoking; GHCi + single: --interactive + +GHCi is invoked with the command ``ghci`` or ``ghc --interactive``. One +or more modules or filenames can also be specified on the command line; +this instructs GHCi to load the specified modules or filenames (and all +the modules they depend on), just as if you had said ``:load modules`` +at the GHCi prompt (see :ref:`ghci-commands`). For example, to start +GHCi and load the program whose topmost module is in the file +``Main.hs``, we could say: + +:: + + $ ghci Main.hs + +Most of the command-line options accepted by GHC (see :ref:`using-ghc`) +also make sense in interactive mode. The ones that don't make sense are +mostly obvious. + +Packages +~~~~~~~~ + +.. index:: + single: packages; with GHCi + +Most packages (see :ref:`using-packages`) are available without needing +to specify any extra flags at all: they will be automatically loaded the +first time they are needed. + +For hidden packages, however, you need to request the package be loaded +by using the ``-package`` flag: + +:: + + $ ghci -package readline + GHCi, version 6.8.1: http://www.haskell.org/ghc/ :? for help + Loading package base ... linking ... done. + Loading package readline-1.0 ... linking ... done. + Prelude> + +The following command works to load new packages into a running GHCi: + +:: + + Prelude> :set -package name + +But note that doing this will cause all currently loaded modules to be +unloaded, and you'll be dumped back into the ``Prelude``. + +Extra libraries +~~~~~~~~~~~~~~~ + +.. index:: + single: libraries; with GHCi + +Extra libraries may be specified on the command line using the normal +``-llib`` option. (The term *library* here refers to libraries of +foreign object code; for using libraries of Haskell source code, see +:ref:`ghci-modules-filenames`.) For example, to load the “m” library: + +:: + + $ ghci -lm + +On systems with ``.so``-style shared libraries, the actual library +loaded will the ``liblib.so``. GHCi searches the following places for +libraries, in this order: + +- Paths specified using the ``-Lpath`` command-line option, + +- the standard library search path for your system, which on some + systems may be overridden by setting the ``LD_LIBRARY_PATH`` + environment variable. + +On systems with ``.dll``-style shared libraries, the actual library +loaded will be ``lib.dll``. Again, GHCi will signal an error if it can't +find the library. + +GHCi can also load plain object files (``.o`` or ``.obj`` depending on +your platform) from the command-line. Just add the name the object file +to the command line. + +Ordering of ``-l`` options matters: a library should be mentioned +*before* the libraries it depends on (see :ref:`options-linker`). + +.. _ghci-commands: + +GHCi commands +------------- + +GHCi commands all begin with "``:``" and consist of a single command +name followed by zero or more parameters. The command name may be +abbreviated, with ambiguities being resolved in favour of the more +commonly used commands. + +``:abandon`` + .. index:: + single: :abandon + + Abandons the current evaluation (only available when stopped at a + breakpoint). + +``:add[*] ⟨module⟩`` + .. index:: + single: :add + + Add ⟨module⟩(s) to the current target set, and perform a reload. + Normally pre-compiled code for the module will be loaded if + available, or otherwise the module will be compiled to byte-code. + Using the ``*`` prefix forces the module to be loaded as byte-code. + +``:back ⟨n⟩`` + .. index:: + single: :back + + Travel back ⟨n⟩ steps in the history. ⟨n⟩ is one if omitted. See + :ref:`tracing` for more about GHCi's debugging facilities. See also: + ``:trace``, ``:history``, ``:forward``. + +``:break [⟨identifier⟩ | [⟨module⟩] ⟨line⟩ [⟨column⟩]]`` + .. index:: + single: :break + + Set a breakpoint on the specified function or line and column. See + :ref:`setting-breakpoints`. + +``:browse[!] [[*] ⟨module⟩]`` + .. index:: + single: :browse + + Displays the identifiers exported by the module ⟨module⟩, which must + be either loaded into GHCi or be a member of a package. If ⟨module⟩ + is omitted, the most recently-loaded module is used. + + Like all other GHCi commands, the output is always displayed in the + current GHCi scope (:ref:`ghci-scope`). + + There are two variants of the browse command: + + - If the ``*`` symbol is placed before the module name, then *all* + the identifiers in scope in ⟨module⟩ (rather that just its + exports) are shown. + + The ``*``-form is only available for modules which are + interpreted; for compiled modules (including modules from + packages) only the non-\ ``*`` form of ``:browse`` is available. + + - Data constructors and class methods are usually displayed in the + context of their data type or class declaration. However, if the + ``!`` symbol is appended to the command, thus ``:browse!``, they + are listed individually. The ``!``-form also annotates the + listing with comments giving possible imports for each group of + entries. Here is an example: + + :: + + Prelude> :browse! Data.Maybe + -- not currently imported + Data.Maybe.catMaybes :: [Maybe a] -> [a] + Data.Maybe.fromJust :: Maybe a -> a + Data.Maybe.fromMaybe :: a -> Maybe a -> a + Data.Maybe.isJust :: Maybe a -> Bool + Data.Maybe.isNothing :: Maybe a -> Bool + Data.Maybe.listToMaybe :: [a] -> Maybe a + Data.Maybe.mapMaybe :: (a -> Maybe b) -> [a] -> [b] + Data.Maybe.maybeToList :: Maybe a -> [a] + -- imported via Prelude + Just :: a -> Maybe a + data Maybe a = Nothing | Just a + Nothing :: Maybe a + maybe :: b -> (a -> b) -> Maybe a -> b + + This output shows that, in the context of the current session (ie + in the scope of ``Prelude``), the first group of items from + ``Data.Maybe`` are not in scope (althought they are available in + fully qualified form in the GHCi session - see + :ref:`ghci-scope`), whereas the second group of items are in + scope (via ``Prelude``) and are therefore available either + unqualified, or with a ``Prelude.`` qualifier. + +``:cd ⟨dir⟩`` + .. index:: + single: :cd + + Changes the current working directory to ⟨dir⟩. A "``~``" symbol + at the beginning of ⟨dir⟩ will be replaced by the contents of the + environment variable ``HOME``. See also the ``:show paths`` command + for showing the current working directory. + + Note: changing directories causes all currently loaded modules to be + unloaded. This is because the search path is usually expressed using + relative directories, and changing the search path in the middle of + a session is not supported. + +``:cmd ⟨expr⟩`` + .. index:: + single: :cmd + + Executes ⟨expr⟩ as a computation of type ``IO String``, and then + executes the resulting string as a list of GHCi commands. Multiple + commands are separated by newlines. The ``:cmd`` command is useful + with ``:def`` and ``:set stop``. + +``:complete ⟨type⟩ [⟨n⟩-][⟨m⟩] ⟨string-literal⟩`` + .. index:: + single: :complete + + This command allows to request command completions from GHCi even + when interacting over a pipe instead of a proper terminal and is + designed for integrating GHCi's completion with text editors and + IDEs. + + When called, ``:complete`` prints the ⟨n⟩\ :sup:`th` to + ⟨m⟩\ :sup:`th` completion candidates for the partial input + ⟨string-literal⟩ for the completion domain denoted by ⟨type⟩. + Currently, only the ``repl`` domain is supported which denotes the + kind of completion that would be provided interactively by GHCi at + the input prompt. + + If omitted, ⟨n⟩ and ⟨m⟩ default to the first or last available + completion candidate respectively. If there are less candidates than + requested via the range argument, ⟨n⟩ and ⟨m⟩ are implicitly capped + to the number of available completition candidates. + + The output of ``:complete`` begins with a header line containing + three space-delimited fields: + + - An integer denoting the number ``l`` of printed completions, + - an integer denoting the total number of completions available, + and finally + - a string literal denoting a common prefix to be added to the + returned completion candidates. + + The header line is followed by ⟨l⟩ lines each containing one + completion candidate encoded as (quoted) string literal. Here are + some example invocations showing the various cases: + + :: + + Prelude> :complete repl 0 "" + 0 470 "" + Prelude> :complete repl 5 "import For" + 5 21 "import " + "Foreign" + "Foreign.C" + "Foreign.C.Error" + "Foreign.C.String" + "Foreign.C.Types" + Prelude> :complete repl 5-10 "import For" + 6 21 "import " + "Foreign.C.Types" + "Foreign.Concurrent" + "Foreign.ForeignPtr" + "Foreign.ForeignPtr.Safe" + "Foreign.ForeignPtr.Unsafe" + "Foreign.Marshal" + Prelude> :complete repl 20- "import For" + 2 21 "import " + "Foreign.StablePtr" + "Foreign.Storable" + Prelude> :complete repl "map" + 3 3 "" + "map" + "mapM" + "mapM_" + Prelude> :complete repl 5-10 "map" + 0 3 "" + +``:continue`` + .. index:: + single: :continue + + Continue the current evaluation, when stopped at a breakpoint. + +``:ctags [⟨filename⟩]``, ``:etags [⟨filename⟩]`` + .. index:: + single: :ctags + single: :etags + + Generates a “tags” file for Vi-style editors (``:ctags``) or + Emacs-style editors (``:etags``). If no filename is specified, the + default ``tags`` or ``TAGS`` is used, respectively. Tags for all the + functions, constructors and types in the currently loaded modules + are created. All modules must be interpreted for these commands to + work. + +``:def! ⟨name⟩ ⟨expr⟩`` + .. index:: + single: :def + + ``:def`` is used to define new commands, or macros, in GHCi. The + command ``:def`` ⟨name⟩ ⟨expr⟩ defines a new GHCi command ``:name``, + implemented by the Haskell expression ⟨expr⟩, which must have type + ``String -> IO String``. When ``:name args`` is typed at the prompt, + GHCi will run the expression ``(name args)``, take the resulting + ``String``, and feed it back into GHCi as a new sequence of + commands. Separate commands in the result must be separated by + "``\n``". + + That's all a little confusing, so here's a few examples. To start + with, here's a new GHCi command which doesn't take any arguments or + produce any results, it just outputs the current date & time: + + :: + + Prelude> let date _ = Time.getClockTime >>= print >> return "" + Prelude> :def date date + Prelude> :date + Fri Mar 23 15:16:40 GMT 2001 + + Here's an example of a command that takes an argument. It's a + re-implementation of ``:cd``: + + :: + + Prelude> let mycd d = Directory.setCurrentDirectory d >> return "" + Prelude> :def mycd mycd + Prelude> :mycd .. + + Or I could define a simple way to invoke "``ghc --make Main``" + in the current directory: + + :: + + Prelude> :def make (\_ -> return ":! ghc --make Main") + + We can define a command that reads GHCi input from a file. This + might be useful for creating a set of bindings that we want to + repeatedly load into the GHCi session: + + :: + + Prelude> :def . readFile + Prelude> :. cmds.ghci + + Notice that we named the command ``:.``, by analogy with the + "``.``" Unix shell command that does the same thing. + + Typing ``:def`` on its own lists the currently-defined macros. + Attempting to redefine an existing command name results in an error + unless the ``:def!`` form is used, in which case the old command + with that name is silently overwritten. + +``:delete * | ⟨num⟩ ...`` + .. index:: + single: :delete + + Delete one or more breakpoints by number (use ``:show breaks`` to + see the number of each breakpoint). The ``*`` form deletes all the + breakpoints. + +``:edit ⟨file⟩`` + .. index:: + single: :edit + + Opens an editor to edit the file ⟨file⟩, or the most recently loaded + module if ⟨file⟩ is omitted. If there were errors during the last + loading, the cursor will be positioned at the line of the first + error. The editor to invoke is taken from the ``EDITOR`` environment + variable, or a default editor on your system if ``EDITOR`` is not + set. You can change the editor using ``:set editor``. + +``:etags`` + See ``:ctags``. + +``:force ⟨identifier⟩ ...`` + .. index:: + single: :force + + Prints the value of ⟨identifier⟩ in the same way as ``:print``. + Unlike ``:print``, ``:force`` evaluates each thunk that it + encounters while traversing the value. This may cause exceptions or + infinite loops, or further breakpoints (which are ignored, but + displayed). + +``:forward ⟨n⟩`` + .. index:: + single: :forward + + Move forward ⟨n⟩ steps in the history. ⟨n⟩ is one if omitted. See + :ref:`tracing` for more about GHCi's debugging facilities. See also: + ``:trace``, ``:history``, ``:back``. + +``:help``, ``:?`` + .. index:: + single: :help + single: :? + + Displays a list of the available commands. + +``:`` + .. index:: + single: : + + Repeat the previous command. + +``:history [num]`` + .. index:: + single: :history + + Display the history of evaluation steps. With a number, displays + that many steps (default: 20). For use with ``:trace``; see + :ref:`tracing`. To set the number of history entries stored by GHCi, + use ``-fghci-hist-size=n``. + +``:info[!] ⟨name⟩`` + .. index:: + single: :info + + Displays information about the given name(s). For example, if ⟨name⟩ + is a class, then the class methods and their types will be printed; + if ⟨name⟩ is a type constructor, then its definition will be + printed; if ⟨name⟩ is a function, then its type will be printed. If + ⟨name⟩ has been loaded from a source file, then GHCi will also + display the location of its definition in the source. + + For types and classes, GHCi also summarises instances that mention + them. To avoid showing irrelevant information, an instance is shown + only if (a) its head mentions ⟨name⟩, and (b) all the other things + mentioned in the instance are in scope (either qualified or + otherwise) as a result of a ``:load`` or ``:module`` commands. + + The command ``:info!`` works in a similar fashion but it removes + restriction (b), showing all instances that are in scope and mention + ⟨name⟩ in their head. + +``:issafe [⟨module⟩]`` + .. index:: + single: :issafe + + Displays Safe Haskell information about the given module (or the + current module if omitted). This includes the trust type of the + module and its containing package. + +``:kind[!] ⟨type⟩`` + .. index:: + single: :kind + + Infers and prints the kind of ⟨type⟩. The latter can be an arbitrary + type expression, including a partial application of a type + constructor, such as ``Either Int``. In fact, ``:kind`` even allows + you to write a partial application of a type synonym (usually + disallowed), so that this works: + + :: + + ghci> type T a b = (a,b,a) + ghci> :k T Int Bool + T Int Bool :: * + ghci> :k T + T :: * -> * -> * + ghci> :k T Int + T Int :: * -> * + + If you specify the optional "``!``", GHC will in addition normalise + the type by expanding out type synonyms and evaluating type-function + applications, and display the normalised result. + +``:list ⟨identifier⟩`` + .. index:: + single: :list + + Lists the source code around the definition of ⟨identifier⟩ or the + current breakpoint if not given. This requires that the identifier + be defined in an interpreted module. If your output device supports + it, then GHCi will highlight the active subexpression in bold. + +``:list [⟨module⟩] ⟨line⟩`` + .. index:: + single: :list + + Lists the source code around the given line number of ⟨module⟩. This + requires that the module be interpreted. If your output device + supports it, then GHCi will highlight the active subexpression in + bold. + +``:load[!] [*]⟨module⟩`` + .. index:: + single: :load + + Recursively loads the specified ⟨module⟩s, and all the modules they + depend on. Here, each ⟨module⟩ must be a module name or filename, + but may not be the name of a module in a package. + + All previously loaded modules, except package modules, are + forgotten. The new set of modules is known as the target set. Note + that ``:load`` can be used without any arguments to unload all the + currently loaded modules and bindings. + + Normally pre-compiled code for a module will be loaded if available, + or otherwise the module will be compiled to byte-code. Using the + ``*`` prefix forces a module to be loaded as byte-code. + + Adding the optional "``!``" turns type errors into warnings while + loading. This allows to use the portions of the module that are + correct, even if there are type errors in some definitions. + Effectively, the "-fdefer-type-errors" flag is set before loading + and unset after loading if the flag has not already been set before. + See :ref:`defer-type-errors` for further motivation and details. + + After a ``:load`` command, the current context is set to: + + - ⟨module⟩, if it was loaded successfully, or + + - the most recently successfully loaded module, if any other + modules were loaded as a result of the current ``:load``, or + + - ``Prelude`` otherwise. + +``:main ⟨arg1⟩ ... ⟨argn⟩`` + .. index:: + single: :main + + When a program is compiled and executed, it can use the ``getArgs`` + function to access the command-line arguments. However, we cannot + simply pass the arguments to the ``main`` function while we are + testing in ghci, as the ``main`` function doesn't take its arguments + directly. + + Instead, we can use the ``:main`` command. This runs whatever + ``main`` is in scope, with any arguments being treated the same as + command-line arguments, e.g.: + + :: + + Prelude> let main = System.Environment.getArgs >>= print + Prelude> :main foo bar + ["foo","bar"] + + We can also quote arguments which contains characters like spaces, + and they are treated like Haskell strings, or we can just use + Haskell list syntax: + + :: + + Prelude> :main foo "bar baz" + ["foo","bar baz"] + Prelude> :main ["foo", "bar baz"] + ["foo","bar baz"] + + Finally, other functions can be called, either with the ``-main-is`` + flag or the ``:run`` command: + + :: + + Prelude> let foo = putStrLn "foo" >> System.Environment.getArgs >>= print + Prelude> let bar = putStrLn "bar" >> System.Environment.getArgs >>= print + Prelude> :set -main-is foo + Prelude> :main foo "bar baz" + foo + ["foo","bar baz"] + Prelude> :run bar ["foo", "bar baz"] + bar + ["foo","bar baz"] + +``:module +|- [*]⟨mod1⟩ ...``, ``import mod`` + .. index:: + single: :module + + Sets or modifies the current context for statements typed at the + prompt. The form ``import mod`` is equivalent to ``:module +mod``. + See :ref:`ghci-scope` for more details. + +``:print ⟨names⟩`` + .. index:: + single: :print + + Prints a value without forcing its evaluation. ``:print`` may be + used on values whose types are unknown or partially known, which + might be the case for local variables with polymorphic types at a + breakpoint. While inspecting the runtime value, ``:print`` attempts + to reconstruct the type of the value, and will elaborate the type in + GHCi's environment if possible. If any unevaluated components + (thunks) are encountered, then ``:print`` binds a fresh variable + with a name beginning with ``_t`` to each thunk. See + :ref:`breakpoints` for more information. See also the ``:sprint`` + command, which works like ``:print`` but does not bind new + variables. + +``:quit`` + .. index:: + single: :quit + + Quits GHCi. You can also quit by typing control-D at the prompt. + +``:reload[!]`` + .. index:: + single: :reload + + Attempts to reload the current target set (see ``:load``) if any of + the modules in the set, or any dependent module, has changed. Note + that this may entail loading new modules, or dropping modules which + are no longer indirectly required by the target. + + Adding the optional "``!``" turns type errors into warnings while + loading. This allows to use the portions of the module that are + correct, even if there are type errors in some definitions. + Effectively, the "-fdefer-type-errors" flag is set before loading + and unset after loading if the flag has not already been set before. + See :ref:`defer-type-errors` for further motivation and details. + +``:run`` + .. index:: + single: :run + + See ``:main``. + +``:script [⟨n⟩] ⟨filename⟩`` + .. index:: + single: :script + + Executes the lines of a file as a series of GHCi commands. This + command is compatible with multiline statements as set by + ``:set +m`` + +``:set [⟨option⟩ ...]`` + .. index:: + single: :set + + Sets various options. See :ref:`ghci-set` for a list of available + options and :ref:`interactive-mode-options` for a list of + GHCi-specific flags. The ``:set`` command by itself shows which + options are currently set. It also lists the current dynamic flag + settings, with GHCi-specific flags listed separately. + +``:set args ⟨arg⟩`` + .. index:: + single: :set args + single: getArgs, behavior in GHCi + + Sets the list of arguments which are returned when the program calls + ``System.getArgs``. + +``:set editor ⟨cmd⟩`` + Sets the command used by ``:edit`` to ⟨cmd⟩. + +``:set prog ⟨prog⟩`` + .. index:: + single: :set prog + single: getProgName, behavior in GHCi + + Sets the string to be returned when the program calls + ``System.getProgName``. + +``:set prompt ⟨prompt⟩`` + .. index:: + single: GHCi prompt; setting + + Sets the string to be used as the prompt in GHCi. Inside ⟨prompt⟩, + the sequence ``%s`` is replaced by the names of the modules + currently in scope, ``%l`` is replaced by the line number (as + referenced in compiler messages) of the current prompt, and ``%%`` + is replaced by ``%``. If ⟨prompt⟩ starts with ``"`` then it is parsed as + a Haskell String; otherwise it is treated as a literal string. + +``:set prompt2 ⟨prompt⟩`` + Sets the string to be used as the continuation prompt (used when + using the ``:{`` command) in GHCi. + +``:set stop ⟨num⟩ ⟨cmd⟩`` + Set a command to be executed when a breakpoint is hit, or a new item + in the history is selected. The most common use of ``:set stop`` is + to display the source code at the current location, e.g. + ``:set stop :list``. + + If a number is given before the command, then the commands are run + when the specified breakpoint (only) is hit. This can be quite + useful: for example, ``:set stop 1 :continue`` effectively disables + breakpoint 1, by running ``:continue`` whenever it is hit (although + GHCi will still emit a message to say the breakpoint was hit). + What's more, with cunning use of ``:def`` and ``:cmd`` you can use + ``:set stop`` to implement conditional breakpoints: + + :: + + *Main> :def cond \expr -> return (":cmd if (" ++ expr ++ ") then return \"\" else return \":continue\"") + *Main> :set stop 0 :cond (x < 3) + + Ignoring breakpoints for a specified number of iterations is also + possible using similar techniques. + +``:seti [⟨option⟩ ...]`` + .. index:: + single: :seti + + Like ``:set``, but options set with ``:seti`` affect only + expressions and commands typed at the prompt, and not modules loaded + with ``:load`` (in contrast, options set with ``:set`` apply + everywhere). See :ref:`ghci-interactive-options`. + + Without any arguments, displays the current set of options that are + applied to expressions and commands typed at the prompt. + +``:show bindings`` + .. index:: + single: :show bindings + + Show the bindings made at the prompt and their types. + +``:show breaks`` + .. index:: + single: :show breaks + + List the active breakpoints. + +``:show context`` + .. index:: + single: :show context + + List the active evaluations that are stopped at breakpoints. + +``:show imports`` + .. index:: + single: :show imports + + Show the imports that are currently in force, as created by + ``import`` and ``:module`` commands. + +``:show modules`` + .. index:: + single: :show modules + + Show the list of modules currently loaded. + +``:show packages`` + .. index:: + single: :show packages + + Show the currently active package flags, as well as the list of + packages currently loaded. + +``:show paths`` + .. index:: + single: :show paths + + Show the current working directory (as set via ``:cd`` command), as + well as the list of directories searched for source files (as set by + the ``-i`` option). + +``:show language`` + .. index:: + single: :show language + + Show the currently active language flags for source files. + +``:showi language`` + .. index:: + single: :showi language + + Show the currently active language flags for expressions typed at + the prompt (see also ``:seti``). + +``:show [args|prog|prompt|editor|stop]`` + .. index:: + single: :show + + Displays the specified setting (see ``:set``). + +``:sprint`` + .. index:: + single: :sprint + + Prints a value without forcing its evaluation. ``:sprint`` is + similar to ``:print``, with the difference that unevaluated subterms + are not bound to new variables, they are simply denoted by ‘\_’. + +``:step [⟨expr⟩]`` + .. index:: + single: :step + + Enable all breakpoints and begin evaluating an expression in + single-stepping mode. In this mode evaluation will be stopped after + every reduction, allowing local variables to be inspected. If ⟨expr⟩ + is not given, evaluation will resume at the last breakpoint. See + :ref:`single-stepping`. + +``:steplocal`` + .. index:: + single: :steplocal + + Enable only breakpoints in the current top-level binding and resume + evaluation at the last breakpoint. + +``:stepmodule`` + .. index:: + single: :stepmodule + + Enable only breakpoints in the current module and resume evaluation + at the last breakpoint. + +``:trace expr`` + .. index:: + single: :trace + + Evaluates the given expression (or from the last breakpoint if no + expression is given), and additionally logs the evaluation steps for + later inspection using ``:history``. See :ref:`tracing`. + +``:type ⟨expression⟩`` + .. index:: + single: :type + + Infers and prints the type of ⟨expression⟩, including explicit + forall quantifiers for polymorphic types. The monomorphism + restriction is *not* applied to the expression during type + inference. + +``:undef ⟨name⟩`` + .. index:: + single: :undef + + Undefines the user-defined command ⟨name⟩ (see ``:def`` above). + +``:unset ⟨option⟩`` + .. index:: + single: :unset + + Unsets certain options. See :ref:`ghci-set` for a list of available + options. + +``:! ⟨command⟩`` + .. index:: + single: :! + single: shell commands; in GHCi + + Executes the shell command ⟨command⟩. + + +.. _ghci-set: + +The ``:set`` and ``:seti`` commands +----------------------------------- + +.. index:: + single: :set + single: :seti + +The ``:set`` command sets two types of options: GHCi options, which +begin with "``+``", and "command-line" options, which begin with +"``-``". + +.. note:: + At the moment, the ``:set`` command doesn't support any kind of + quoting in its arguments: quotes will not be removed and cannot be used + to group words together. For example, ``:set -DFOO='BAR BAZ'`` will not + do what you expect. + +GHCi options +~~~~~~~~~~~~ + +.. index:: + single: options; GHCi + +GHCi options may be set using ``:set`` and unset using ``:unset``. + +The available GHCi options are: + +``+m`` + .. index:: + single: +m + + Enable parsing of multiline commands. A multiline command is + prompted for when the current input line contains open layout + contexts (see :ref:`ghci-multiline`). + +``+r`` + .. index:: + single: +r + single: CAFs; in GHCi + single: Constant Applicative Form + + Normally, any evaluation of top-level expressions (otherwise known + as CAFs or Constant Applicative Forms) in loaded modules is retained + between evaluations. Turning on ``+r`` causes all evaluation of + top-level expressions to be discarded after each evaluation (they + are still retained *during* a single evaluation). + + This option may help if the evaluated top-level expressions are + consuming large amounts of space, or if you need repeatable + performance measurements. + +``+s`` + .. index:: + single: +s + + Display some stats after evaluating each expression, including the + elapsed time and number of bytes allocated. NOTE: the allocation + figure is only accurate to the size of the storage manager's + allocation area, because it is calculated at every GC. Hence, you + might see values of zero if no GC has occurred. + +``+t`` + .. index:: + single: +t + + Display the type of each variable bound after a statement is entered + at the prompt. If the statement is a single expression, then the + only variable binding will be for the variable ‘\ ``it``\ ’. + +.. _ghci-cmd-line-options: + +Setting GHC command-line options in GHCi +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Normal GHC command-line options may also be set using ``:set``. For +example, to turn on ``-fwarn-missing-signatures``, you would say: + +:: + + Prelude> :set -fwarn-missing-signatures + +Any GHC command-line option that is designated as dynamic (see the table +in :ref:`flag-reference`), may be set using ``:set``. To unset an +option, you can set the reverse option: + +.. index:: + single: dynamic; options + +:: + + Prelude> :set -fno-warn-incomplete-patterns -XNoMultiParamTypeClasses + +:ref:`flag-reference` lists the reverse for each option where +applicable. + +Certain static options (``-package``, ``-I``, ``-i``, and ``-l`` in +particular) will also work, but some may not take effect until the next +reload. + +.. index:: + single: static; options + +.. _ghci-interactive-options: + +Setting options for interactive evaluation only +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +GHCi actually maintains *two* sets of options: + +- The *loading options* apply when loading modules + +- The *interactive options* apply when evaluating expressions and + commands typed at the GHCi prompt. + +The ``:set`` command modifies both, but there is also a ``:seti`` +command (for "set interactive") that affects only the interactive +options set. + +It is often useful to change the interactive options, without having +that option apply to loaded modules too. For example + +:: + + :seti -XMonoLocalBinds + +It would be undesirable if ``-XMonoLocalBinds`` were to apply to loaded +modules too: that might cause a compilation error, but more commonly it +will cause extra recompilation, because GHC will think that it needs to +recompile the module because the flags have changed. + +If you are setting language options in your ``.ghci`` file, it is good +practice to use ``:seti`` rather than ``:set``, unless you really do +want them to apply to all modules you load in GHCi. + +The two sets of options can be inspected using the ``:set`` and +``:seti`` commands respectively, with no arguments. For example, in a +clean GHCi session we might see something like this: + +:: + + Prelude> :seti + base language is: Haskell2010 + with the following modifiers: + -XNoMonomorphismRestriction + -XNoDatatypeContexts + -XNondecreasingIndentation + -XExtendedDefaultRules + GHCi-specific dynamic flag settings: + other dynamic, non-language, flag settings: + -fimplicit-import-qualified + warning settings: + +The two sets of options are initialised as follows. First, both sets of +options are initialised as described in :ref:`ghci-dot-files`. Then the +interactive options are modified as follows: + +- The option ``-XExtendedDefaultRules`` is enabled, in order to apply + special defaulting rules to expressions typed at the prompt (see + :ref:`extended-default-rules`). + +- The Monomorphism Restriction is disabled (see :ref:`monomorphism`). + +.. _ghci-dot-files: + +The ``.ghci`` and ``.haskeline`` files +-------------------------------------- + +.. _dot-ghci-files: + +The ``.ghci`` files +~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: .ghci; file + single: startup; files, GHCi + +When it starts, unless the ``-ignore-dot-ghci`` flag is given, GHCi +reads and executes commands from the following files, in this order, if +they exist: + +1. ``./.ghci`` + +2. ``appdata/ghc/ghci.conf``, where ⟨appdata⟩ depends on your system, + but is usually something like + ``C:/Documents and Settings/user/Application Data`` + +3. On Unix: ``$HOME/.ghc/ghci.conf`` + +4. ``$HOME/.ghci`` + +The ``ghci.conf`` file is most useful for turning on favourite options +(eg. ``:set +s``), and defining useful macros. Note: when setting +language options in this file it is usually desirable to use ``:seti`` +rather than ``:set`` (see :ref:`ghci-interactive-options`). + +Placing a ``.ghci`` file in a directory with a Haskell project is a +useful way to set certain project-wide options so you don't have to type +them every time you start GHCi: eg. if your project uses multi-parameter +type classes, scoped type variables, and CPP, and has source files in +three subdirectories A, B and C, you might put the following lines in +``.ghci``: + +:: + + :set -XMultiParamTypeClasses -XScopedTypeVariables -cpp + :set -iA:B:C + +(Note that strictly speaking the ``-i`` flag is a static one, but in +fact it works to set it using ``:set`` like this. The changes won't take +effect until the next ``:load``, though.) + +Once you have a library of GHCi macros, you may want to source them from +separate files, or you may want to source your ``.ghci`` file into your +running GHCi session while debugging it + +:: + + :def source readFile + +With this macro defined in your ``.ghci`` file, you can use +``:source file`` to read GHCi commands from ``file``. You can find (and +contribute!-) other suggestions for ``.ghci`` files on this Haskell wiki +page: `GHC/GHCi <http://haskell.org/haskellwiki/GHC/GHCi>`__ + +Additionally, any files specified with ``-ghci-script`` flags will be +read after the standard files, allowing the use of custom .ghci files. + +Two command-line options control whether the startup files files are +read: + +``-ignore-dot-ghci`` + .. index:: + single: -ignore-dot-ghci + + Don't read either ``./.ghci`` or the other startup files when + starting up. + +``-ghci-script`` + .. index:: + single: -ghci-script + + Read a specific file after the usual startup files. Maybe be + specified repeatedly for multiple inputs. + +When defining GHCi macros, there is some important behavior you should +be aware of when names may conflict with built-in commands, especially +regarding tab completion. + +For example, consider if you had a macro named ``:time`` and in the +shell, typed ``:t 3`` - what should happen? The current algorithm we use +for completing commands is: + +1. First, look up an exact match on the name from the defined macros. + +2. Look for the exact match on the name in the built-in command list. + +3. Do a prefix lookup on the list of built-in commands - if a built-in + command matches, but a macro is defined with the same name as the + built-in defined, pick the macro. + +4. Do a prefix lookup on the list of built-in commands. + +5. Do a prefix lookup on the list of defined macros. + +Here are some examples: + +1. You have a macro ``:time`` and enter ``:t 3`` + + You get ``:type 3`` + +2. You have a macro ``:type`` and enter ``:t 3`` + + You get ``:type 3`` with your defined macro, not the builtin. + +3. You have a macro ``:time`` and a macro ``:type``, and enter ``:t 3`` + + You get ``:type 3`` with your defined macro. + +.. _dot-haskeline-file: + +The ``.haskeline`` file +~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: .haskeline; file + single: startup; files, GHCi + +GHCi uses `Haskeline <https://hackage.haskell.org/package/haskeline>`__ under +the hood. You can configure it to, among other +things, prune duplicates from GHCi history. See: +`Haskeline user preferences <http://trac.haskell.org/haskeline/wiki/UserPrefs>`__. + +.. _ghci-obj: + +Compiling to object code inside GHCi +------------------------------------ + +By default, GHCi compiles Haskell source code into byte-code that is +interpreted by the runtime system. GHCi can also compile Haskell code to +object code: to turn on this feature, use the ``-fobject-code`` flag +either on the command line or with ``:set`` (the option ``-fbyte-code`` +restores byte-code compilation again). Compiling to object code takes +longer, but typically the code will execute 10-20 times faster than +byte-code. + +Compiling to object code inside GHCi is particularly useful if you are +developing a compiled application, because the ``:reload`` command +typically runs much faster than restarting GHC with ``--make`` from the +command-line, because all the interface files are already cached in +memory. + +There are disadvantages to compiling to object-code: you can't set +breakpoints in object-code modules, for example. Only the exports of an +object-code module will be visible in GHCi, rather than all top-level +bindings as in interpreted modules. + +.. _ghci-faq: + +FAQ and Things To Watch Out For +------------------------------- + +The interpreter can't load modules with foreign export declarations! + Unfortunately not. We haven't implemented it yet. Please compile any + offending modules by hand before loading them into GHCi. + +``-O`` doesn't work with GHCi! + .. index:: + single: -O + + For technical reasons, the bytecode compiler doesn't interact well + with one of the optimisation passes, so we have disabled + optimisation when using the interpreter. This isn't a great loss: + you'll get a much bigger win by compiling the bits of your code that + need to go fast, rather than interpreting them with optimisation + turned on. + +Unboxed tuples don't work with GHCi + That's right. You can always compile a module that uses unboxed + tuples and load it into GHCi, however. (Incidentally the previous + point, namely that ``-O`` is incompatible with GHCi, is because the + bytecode compiler can't deal with unboxed tuples). + +Concurrent threads don't carry on running when GHCi is waiting for input. + This should work, as long as your GHCi was built with the + ``-threaded`` switch, which is the default. Consult whoever supplied + your GHCi installation. + + +After using ``getContents``, I can't use ``stdin``, until I do ``:load`` or ``:reload`` + This is the defined behaviour of ``getContents``: it puts the stdin + Handle in a state known as semi-closed, wherein any further I/O + operations on it are forbidden. Because I/O state is retained + between computations, the semi-closed state persists until the next + ``:load`` or ``:reload`` command. + + You can make ``stdin`` reset itself after every evaluation by giving + GHCi the command ``:set +r``. This works because ``stdin`` is just a + top-level expression that can be reverted to its unevaluated state + in the same way as any other top-level expression (CAF). + +I can't use Control-C to interrupt computations in GHCi on Windows. + See :ref:`ghci-windows`. + +The default buffering mode is different in GHCi to GHC. + In GHC, the stdout handle is line-buffered by default. However, in + GHCi we turn off the buffering on stdout, because this is normally + what you want in an interpreter: output appears as it is generated. + + If you want line-buffered behaviour, as in GHC, you can start your + program thus: + + :: + + main = do { hSetBuffering stdout LineBuffering; ... } + + +.. [5] + Note that packages only contain compiled code, so debugging a package + requires finding its source and loading that directly. + +.. [6] + We originally provided bindings for all variables in scope, rather + than just the free variables of the expression, but found that this + affected performance considerably, hence the current restriction to + just the free variables. diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml deleted file mode 100644 index 399cda90ea..0000000000 --- a/docs/users_guide/ghci.xml +++ /dev/null @@ -1,3709 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<chapter id="ghci"> - <title>Using GHCi</title> - <indexterm><primary>GHCi</primary></indexterm> - <indexterm><primary>interpreter</primary><see>GHCi</see></indexterm> - <indexterm><primary>interactive</primary><see>GHCi</see></indexterm> - - <para>GHCi<footnote> - <para>The ‘i’ stands for “Interactive”</para> - </footnote> - is GHC's interactive environment, in which Haskell expressions can - be interactively evaluated and programs can be interpreted. If - you're familiar with <ulink url="http://www.haskell.org/hugs/">Hugs</ulink><indexterm><primary>Hugs</primary> - </indexterm>, then you'll be right at home with GHCi. However, GHCi - also has support for interactively loading compiled code, as well as - supporting all<footnote><para>except <literal>foreign export</literal>, at the moment</para> - </footnote> the language extensions that GHC provides. - <indexterm><primary>FFI</primary><secondary>GHCi support</secondary></indexterm> - <indexterm><primary>Foreign Function - Interface</primary><secondary>GHCi support</secondary></indexterm> - GHCi also includes an interactive debugger (see <xref linkend="ghci-debugger"/>).</para> - - <sect1 id="ghci-introduction"> - <title>Introduction to GHCi</title> - - <para>Let's start with an example GHCi session. You can fire up - GHCi with the command <literal>ghci</literal>:</para> - -<screen> -$ ghci -GHCi, version 6.12.1: http://www.haskell.org/ghc/ :? for help -Loading package ghc-prim ... linking ... done. -Loading package integer-gmp ... linking ... done. -Loading package base ... linking ... done. -Loading package ffi-1.0 ... linking ... done. -Prelude> -</screen> - - <para>There may be a short pause while GHCi loads the prelude and - standard libraries, after which the prompt is shown. As the banner - says, you can type <literal>:?</literal> to see the list of - commands available, and a half line description of each of them. - We'll explain most of these commands as we go along, and there is - complete documentation for all the commands in - <xref linkend="ghci-commands" />.</para> - - <para>Haskell expressions can be typed at the prompt:</para> - <indexterm><primary>prompt</primary><secondary>GHCi</secondary> - </indexterm> - -<screen> -Prelude> 1+2 -3 -Prelude> let x = 42 in x / 9 -4.666666666666667 -Prelude> -</screen> - - <para>GHCi interprets the whole line as an expression to evaluate. - The expression may not span several lines - as soon as you press enter, - GHCi will attempt to evaluate it.</para> - - <para>In Haskell, a <literal>let</literal> expression is followed - by <literal>in</literal>. However, in GHCi, since the expression - can also be interpreted in the <literal>IO</literal> monad, - a <literal>let</literal> binding with no accompanying - <literal>in</literal> statement can be signalled by an empty line, - as in the above example.</para> - </sect1> - - <sect1 id="loading-source-files"> - <title>Loading source files</title> - - <para>Suppose we have the following Haskell source code, which we - place in a file <filename>Main.hs</filename>:</para> - -<programlisting> -main = print (fac 20) - -fac 0 = 1 -fac n = n * fac (n-1) -</programlisting> - - <para>You can save <filename>Main.hs</filename> anywhere you like, - but if you save it somewhere other than the current - directory<footnote><para>If you started up GHCi from the command - line then GHCi's current directory is the same as the current - directory of the shell from which it was started. If you started - GHCi from the “Start” menu in Windows, then the - current directory is probably something like - <filename>C:\Documents and Settings\<replaceable>user - name</replaceable></filename>.</para> </footnote> then we will - need to change to the right directory in GHCi:</para> - -<screen> -Prelude> :cd <replaceable>dir</replaceable> -</screen> - - <para>where <replaceable>dir</replaceable> is the directory (or - folder) in which you saved <filename>Main.hs</filename>.</para> - - <para>To load a Haskell source file into GHCi, use the - <literal>:load</literal> command:</para> - <indexterm><primary><literal>:load</literal></primary></indexterm> - -<screen> -Prelude> :load Main -Compiling Main ( Main.hs, interpreted ) -Ok, modules loaded: Main. -*Main> -</screen> - - <para>GHCi has loaded the <literal>Main</literal> module, and the - prompt has changed to “<literal>*Main></literal>” to - indicate that the current context for expressions typed at the - prompt is the <literal>Main</literal> module we just loaded (we'll - explain what the <literal>*</literal> means later in <xref - linkend="ghci-scope"/>). So we can now type expressions involving - the functions from <filename>Main.hs</filename>:</para> - -<screen> -*Main> fac 17 -355687428096000 -</screen> - - <para>Loading a multi-module program is just as straightforward; - just give the name of the “topmost” module to the - <literal>:load</literal> command (hint: <literal>:load</literal> - can be abbreviated to <literal>:l</literal>). The topmost module - will normally be <literal>Main</literal>, but it doesn't have to - be. GHCi will discover which modules are required, directly or - indirectly, by the topmost module, and load them all in dependency - order.</para> - - <sect2 id="ghci-modules-filenames"> - <title>Modules vs. filenames</title> - <indexterm><primary>modules</primary><secondary>and filenames</secondary></indexterm> - <indexterm><primary>filenames</primary><secondary>of modules</secondary></indexterm> - - <para>Question: How does GHC find the filename which contains - module <replaceable>M</replaceable>? Answer: it looks for the - file <literal><replaceable>M</replaceable>.hs</literal>, or - <literal><replaceable>M</replaceable>.lhs</literal>. This means - that for most modules, the module name must match the filename. - If it doesn't, GHCi won't be able to find it.</para> - - <para>There is one exception to this general rule: when you load - a program with <literal>:load</literal>, or specify it when you - invoke <literal>ghci</literal>, you can give a filename rather - than a module name. This filename is loaded if it exists, and - it may contain any module you like. This is particularly - convenient if you have several <literal>Main</literal> modules - in the same directory and you can't call them all - <filename>Main.hs</filename>.</para> - - <para>The search path for finding source files is specified with - the <option>-i</option> option on the GHCi command line, like - so:</para> -<screen>ghci -i<replaceable>dir<subscript>1</subscript></replaceable>:...:<replaceable>dir<subscript>n</subscript></replaceable></screen> - - <para>or it can be set using the <literal>:set</literal> command - from within GHCi (see <xref - linkend="ghci-cmd-line-options"/>)<footnote><para>Note that in - GHCi, and <option>--make</option> mode, the <option>-i</option> - option is used to specify the search path for - <emphasis>source</emphasis> files, whereas in standard - batch-compilation mode the <option>-i</option> option is used to - specify the search path for interface files, see <xref - linkend="search-path"/>.</para> </footnote></para> - - <para>One consequence of the way that GHCi follows dependencies - to find modules to load is that every module must have a source - file. The only exception to the rule is modules that come from - a package, including the <literal>Prelude</literal> and standard - libraries such as <literal>IO</literal> and - <literal>Complex</literal>. If you attempt to load a module for - which GHCi can't find a source file, even if there are object - and interface files for the module, you'll get an error - message.</para> - </sect2> - - <sect2> - <title>Making changes and recompilation</title> - <indexterm><primary><literal>:reload</literal></primary></indexterm> - - <para>If you make some changes to the source code and want GHCi - to recompile the program, give the <literal>:reload</literal> - command. The program will be recompiled as necessary, with GHCi - doing its best to avoid actually recompiling modules if their - external dependencies haven't changed. This is the same - mechanism we use to avoid re-compiling modules in the batch - compilation setting (see <xref linkend="recomp"/>).</para> - </sect2> - </sect1> - - <sect1 id="ghci-compiled"> - <title>Loading compiled code</title> - <indexterm><primary>compiled code</primary><secondary>in GHCi</secondary></indexterm> - - <para>When you load a Haskell source module into GHCi, it is - normally converted to byte-code and run using the interpreter. - However, interpreted code can also run alongside compiled code in - GHCi; indeed, normally when GHCi starts, it loads up a compiled - copy of the <literal>base</literal> package, which contains the - <literal>Prelude</literal>.</para> - - <para>Why should we want to run compiled code? Well, compiled - code is roughly 10x faster than interpreted code, but takes about - 2x longer to produce (perhaps longer if optimisation is on). So - it pays to compile the parts of a program that aren't changing - very often, and use the interpreter for the code being actively - developed.</para> - - <para>When loading up source modules with <literal>:load</literal>, - GHCi normally looks for any corresponding compiled object files, - and will use one in preference to interpreting the source if - possible. For example, suppose we have a 4-module program - consisting of modules A, B, C, and D. Modules B and C both import - D only, and A imports both B & C:</para> -<screen> - A - / \ - B C - \ / - D -</screen> - <para>We can compile D, then load the whole program, like this:</para> -<screen> -Prelude> :! ghc -c -dynamic D.hs -Prelude> :load A -Compiling B ( B.hs, interpreted ) -Compiling C ( C.hs, interpreted ) -Compiling A ( A.hs, interpreted ) -Ok, modules loaded: A, B, C, D. -*Main> -</screen> - - <para>In the messages from the compiler, we see that there is no line - for <literal>D</literal>. This is because - it isn't necessary to compile <literal>D</literal>, - because the source and everything it depends on - is unchanged since the last compilation.</para> - - <para>Note the <literal>-dynamic</literal> flag to GHC: GHCi uses - dynamically-linked object code (if you are on a platform that - supports it), and so in order to use compiled code with GHCi it - must be compiled for dynamic linking.</para> - - <para>At any time you can use the command - <literal>:show modules</literal> - to get a list of the modules currently loaded - into GHCi:</para> - -<screen> -*Main> :show modules -D ( D.hs, D.o ) -C ( C.hs, interpreted ) -B ( B.hs, interpreted ) -A ( A.hs, interpreted ) -*Main></screen> - - <para>If we now modify the source of D (or pretend to: using the Unix - command <literal>touch</literal> on the source file is handy for - this), the compiler will no longer be able to use the object file, - because it might be out of date:</para> - -<screen> -*Main> :! touch D.hs -*Main> :reload -Compiling D ( D.hs, interpreted ) -Ok, modules loaded: A, B, C, D. -*Main> -</screen> - - <para>Note that module D was compiled, but in this instance - because its source hadn't really changed, its interface remained - the same, and the recompilation checker determined that A, B and C - didn't need to be recompiled.</para> - - <para>So let's try compiling one of the other modules:</para> - -<screen> -*Main> :! ghc -c C.hs -*Main> :load A -Compiling D ( D.hs, interpreted ) -Compiling B ( B.hs, interpreted ) -Compiling C ( C.hs, interpreted ) -Compiling A ( A.hs, interpreted ) -Ok, modules loaded: A, B, C, D. -</screen> - - <para>We didn't get the compiled version of C! What happened? - Well, in GHCi a compiled module may only depend on other compiled - modules, and in this case C depends on D, which doesn't have an - object file, so GHCi also rejected C's object file. Ok, so let's - also compile D:</para> - -<screen> -*Main> :! ghc -c D.hs -*Main> :reload -Ok, modules loaded: A, B, C, D. -</screen> - - <para>Nothing happened! Here's another lesson: newly compiled - modules aren't picked up by <literal>:reload</literal>, only - <literal>:load</literal>:</para> - -<screen> -*Main> :load A -Compiling B ( B.hs, interpreted ) -Compiling A ( A.hs, interpreted ) -Ok, modules loaded: A, B, C, D. -</screen> - - <para>The automatic loading of object files can sometimes lead to - confusion, because non-exported top-level definitions of a module - are only available for use in expressions at the prompt when the - module is interpreted (see <xref linkend="ghci-scope" />). For - this reason, you might sometimes want to force GHCi to load a - module using the interpreter. This can be done by prefixing - a <literal>*</literal> to the module name or filename when - using <literal>:load</literal>, for example</para> - -<screen> -Prelude> :load *A -Compiling A ( A.hs, interpreted ) -*A> -</screen> - -<para>When the <literal>*</literal> is used, GHCi ignores any - pre-compiled object code and interprets the module. If you have - already loaded a number of modules as object code and decide that - you wanted to interpret one of them, instead of re-loading the whole - set you can use <literal>:add *M</literal> to specify that you want - <literal>M</literal> to be interpreted (note that this might cause - other modules to be interpreted too, because compiled modules cannot - depend on interpreted ones).</para> - -<para>To always compile everything to object code and never use the - interpreter, use the <literal>-fobject-code</literal> option (see - <xref linkend="ghci-obj" />).</para> - - <para>HINT: since GHCi will only use a compiled object file if it - can be sure that the compiled version is up-to-date, a good technique - when working on a large program is to occasionally run - <literal>ghc --make</literal> to compile the whole project (say - before you go for lunch :-), then continue working in the - interpreter. As you modify code, the changed modules will be - interpreted, but the rest of the project will remain - compiled.</para> - </sect1> - - <sect1 id="interactive-evaluation"> - <title>Interactive evaluation at the prompt</title> - - <para>When you type an expression at the prompt, GHCi immediately - evaluates and prints the result: -<screen> -Prelude> reverse "hello" -"olleh" -Prelude> 5+5 -10 -</screen> -</para> - -<sect2 id="actions-at-prompt"><title>I/O actions at the prompt</title> - -<para>GHCi does more than simple expression evaluation at the prompt. -If you enter an expression of type <literal>IO a</literal> for some - <literal>a</literal>, then GHCi <emphasis>executes</emphasis> it - as an IO-computation. -<screen> -Prelude> "hello" -"hello" -Prelude> putStrLn "hello" -hello -</screen> -This works even if the type of the expression is more general, -provided it can be <emphasis>instantiated</emphasis> to <literal>IO a</literal>. For example -<screen> -Prelude> return True -True -</screen> -Furthermore, GHCi will print the result of the I/O action if (and only -if): -<itemizedlist> - <listitem><para>The result type is an instance of <literal>Show</literal>.</para></listitem> - <listitem><para>The result type is not - <literal>()</literal>.</para></listitem> -</itemizedlist> -For example, remembering that <literal>putStrLn :: String -> IO ()</literal>: -<screen> -Prelude> putStrLn "hello" -hello -Prelude> do { putStrLn "hello"; return "yes" } -hello -"yes" -</screen> -</para></sect2> - - <sect2 id="ghci-stmts"> - <title>Using <literal>do-</literal>notation at the prompt</title> - <indexterm><primary>do-notation</primary><secondary>in GHCi</secondary></indexterm> - <indexterm><primary>statements</primary><secondary>in GHCi</secondary></indexterm> - - <para>GHCi actually accepts <firstterm>statements</firstterm> - rather than just expressions at the prompt. This means you can - bind values and functions to names, and use them in future - expressions or statements.</para> - - <para>The syntax of a statement accepted at the GHCi prompt is - exactly the same as the syntax of a statement in a Haskell - <literal>do</literal> expression. However, there's no monad - overloading here: statements typed at the prompt must be in the - <literal>IO</literal> monad. -<screen> -Prelude> x <- return 42 -Prelude> print x -42 -Prelude> -</screen> - The statement <literal>x <- return 42</literal> means - “execute <literal>return 42</literal> in the - <literal>IO</literal> monad, and bind the result to - <literal>x</literal>”. We can then use - <literal>x</literal> in future statements, for example to print - it as we did above.</para> - - <para>If <option>-fprint-bind-result</option> is set then - GHCi will print the result of a statement if and only if: - <itemizedlist> - <listitem> - <para>The statement is not a binding, or it is a monadic binding - (<literal>p <- e</literal>) that binds exactly one - variable.</para> - </listitem> - <listitem> - <para>The variable's type is not polymorphic, is not - <literal>()</literal>, and is an instance of - <literal>Show</literal>.</para> - </listitem> - </itemizedlist> - <indexterm><primary><option>-fprint-bind-result</option></primary></indexterm><indexterm><primary><option>-fno-print-bind-result</option></primary></indexterm> - </para> - - <para>Of course, you can also bind normal non-IO expressions - using the <literal>let</literal>-statement:</para> -<screen> -Prelude> let x = 42 -Prelude> x -42 -Prelude> -</screen> - <para>Another important difference between the two types of binding - is that the monadic bind (<literal>p <- e</literal>) is - <emphasis>strict</emphasis> (it evaluates <literal>e</literal>), - whereas with the <literal>let</literal> form, the expression - isn't evaluated immediately:</para> -<screen> -Prelude> let x = error "help!" -Prelude> print x -*** Exception: help! -Prelude> -</screen> - - <para>Note that <literal>let</literal> bindings do not automatically - print the value bound, unlike monadic bindings.</para> - - <para>Hint: you can also use <literal>let</literal>-statements - to define functions at the prompt:</para> -<screen> -Prelude> let add a b = a + b -Prelude> add 1 2 -3 -Prelude> -</screen> - <para>However, this quickly gets tedious when defining functions - with multiple clauses, or groups of mutually recursive functions, - because the complete definition has to be given on a single line, - using explicit semicolons instead of layout:</para> -<screen> -Prelude> let f op n [] = n ; f op n (h:t) = h `op` f op n t -Prelude> f (+) 0 [1..3] -6 -Prelude> -</screen> - <para>To alleviate this issue, GHCi commands can be split over - multiple lines, by wrapping them in <literal>:{</literal> and - <literal>:}</literal> (each on a single line of its own):</para> -<screen> -Prelude> :{ -Prelude| let g op n [] = n -Prelude| g op n (h:t) = h `op` g op n t -Prelude| :} -Prelude> g (*) 1 [1..3] -6 -</screen> - <para>Such multiline commands can be used with any GHCi command, - and note that the layout rule is in effect. - The main purpose of multiline commands is not to replace module - loading but to make definitions in .ghci-files (see <xref - linkend="ghci-dot-files"/>) more readable and maintainable.</para> - - <para>Any exceptions raised during the evaluation or execution - of the statement are caught and printed by the GHCi command line - interface (for more information on exceptions, see the module - <literal>Control.Exception</literal> in the libraries - documentation).</para> - - <para>Every new binding shadows any existing bindings of the - same name, including entities that are in scope in the current - module context.</para> - - <para>WARNING: temporary bindings introduced at the prompt only - last until the next <literal>:load</literal> or - <literal>:reload</literal> command, at which time they will be - simply lost. However, they do survive a change of context with - <literal>:module</literal>: the temporary bindings just move to - the new location.</para> - - <para>HINT: To get a list of the bindings currently in scope, use the - <literal>:show bindings</literal> command:</para> - -<screen> -Prelude> :show bindings -x :: Int -Prelude></screen> - - <para>HINT: if you turn on the <literal>+t</literal> option, - GHCi will show the type of each variable bound by a statement. - For example:</para> - <indexterm><primary><literal>+t</literal></primary></indexterm> -<screen> -Prelude> :set +t -Prelude> let (x:xs) = [1..] -x :: Integer -xs :: [Integer] -</screen> - - </sect2> - - <sect2 id="ghci-multiline"> - <title>Multiline input</title> - - <para>Apart from the <literal>:{ ... :}</literal> syntax for - multi-line input mentioned above, GHCi also has a multiline - mode, enabled by <literal>:set +m</literal>, - <indexterm><primary><literal>:set +m</literal></primary></indexterm> - in which GHCi detects automatically when the current statement - is unfinished and allows further lines to be added. A - multi-line input is terminated with an empty line. For example:</para> - -<screen> -Prelude> :set +m -Prelude> let x = 42 -Prelude| -</screen> - - <para>Further bindings can be added to - this <literal>let</literal> statement, so GHCi indicates that - the next line continues the previous one by changing the - prompt. Note that layout is in effect, so to add more bindings - to this <literal>let</literal> we have to line them up:</para> - -<screen> -Prelude> :set +m -Prelude> let x = 42 -Prelude| y = 3 -Prelude| -Prelude> -</screen> - - <para>Explicit braces and semicolons can be used instead of - layout:</para> - -<screen> -Prelude> do { -Prelude| putStrLn "hello" -Prelude| ;putStrLn "world" -Prelude| } -hello -world -Prelude> -</screen> - - <para>Note that after the closing brace, GHCi knows that the - current statement is finished, so no empty line is required.</para> - - <para>Multiline mode is useful when entering monadic - <literal>do</literal> statements:</para> - -<screen> -Control.Monad.State> flip evalStateT 0 $ do -Control.Monad.State| i <- get -Control.Monad.State| lift $ do -Control.Monad.State| putStrLn "Hello World!" -Control.Monad.State| print i -Control.Monad.State| -"Hello World!" -0 -Control.Monad.State> -</screen> - - <para>During a multiline interaction, the user can interrupt and - return to the top-level prompt.</para> - -<screen> -Prelude> do -Prelude| putStrLn "Hello, World!" -Prelude| ^C -Prelude> -</screen> - </sect2> - - <sect2 id="ghci-decls"> - <title>Type, class and other declarations</title> - - <para>At the GHCi - prompt you can also enter any top-level Haskell declaration, - including <literal>data</literal>, <literal>type</literal>, <literal>newtype</literal>, <literal>class</literal>, <literal>instance</literal>, <literal>deriving</literal>, - and <literal>foreign</literal> declarations. For - example:</para> - -<screen> -Prelude> data T = A | B | C deriving (Eq, Ord, Show, Enum) -Prelude> [A ..] -[A,B,C] -Prelude> :i T -data T = A | B | C -- Defined at <interactive>:2:6 -instance Enum T -- Defined at <interactive>:2:45 -instance Eq T -- Defined at <interactive>:2:30 -instance Ord T -- Defined at <interactive>:2:34 -instance Show T -- Defined at <interactive>:2:39 -</screen> - - <para>As with ordinary variable bindings, later definitions shadow - earlier ones, so you can re-enter a declaration to fix a problem - with it or extend it. But there's a gotcha: when a new type - declaration shadows an older one, there might be other - declarations that refer to the old type. The thing to remember is - that the old type still exists, and these other declarations still - refer to the old type. However, while the old and the new type - have the same name, GHCi will treat them as distinct. For - example:</para> - -<screen> -Prelude> data T = A | B -Prelude> let f A = True; f B = False -Prelude> data T = A | B | C -Prelude> f A - -<interactive>:2:3: - Couldn't match expected type `main::Interactive.T' - with actual type `T' - In the first argument of `f', namely `A' - In the expression: f A - In an equation for `it': it = f A -Prelude> -</screen> - - <para>The old, shadowed, version of <literal>T</literal> is - displayed as <literal>main::Interactive.T</literal> by GHCi in - an attempt to distinguish it from the new <literal>T</literal>, - which is displayed as simply <literal>T</literal>.</para> - - <para>Class and type-family instance declarations are simply added to the list of available instances, - with one exception. Since you might want to re-define one, - a class or type-family instance <emphasis>replaces</emphasis> any earlier instance with - an identical head or left hand side (respectively). - (See <xref linkend="type-families"/>.)</para> - </sect2> - - <sect2 id="ghci-scope"> - <title>What's really in scope at the prompt?</title> - - <para>When you type an expression at the prompt, what - identifiers and types are in scope? - GHCi provides a flexible - way to control exactly how the context for an expression is - constructed: - <itemizedlist> - <listitem><para> - The <literal>:load</literal>, <literal>:add</literal>, - and <literal>:reload</literal> commands (<xref linkend="ghci-load-scope"/>). - </para></listitem> - <listitem><para> - The <literal>import</literal> declaration (<xref linkend="ghci-import-decl"/>). - </para></listitem> - <listitem><para> - The <literal>:module</literal> command (<xref linkend="ghci-module-cmd"/>). - </para></listitem> - </itemizedlist> - </para> - <para>The command <literal>:show imports</literal> will show a summary of which modules - contribute to the top-level scope.</para> - <para> - Hint: GHCi will tab-complete names that are in scope; for - example, if you run GHCi and type <literal>J<tab></literal> - then GHCi will expand it to “<literal>Just </literal>”. - </para> - - <sect3 id="ghci-load-scope"> - <title>The effect of <literal>:load</literal> on what is in scope</title> - <para> - The <literal>:load</literal>, <literal>:add</literal>, and <literal>:reload</literal> - commands (<xref linkend="loading-source-files"/> - and <xref linkend="ghci-compiled"/>) affect the top-level scope. - Let's start with the simple cases; when you start - GHCi the prompt looks like this: - -<screen>Prelude></screen> - - which indicates that everything from the module - <literal>Prelude</literal> is currently in scope; the visible - identifiers are exactly those that would be visible in a Haskell - source file with no <literal>import</literal> - declarations.</para> - - <para>If we now load a file into GHCi, the prompt will change:</para> - -<screen> -Prelude> :load Main.hs -Compiling Main ( Main.hs, interpreted ) -*Main> -</screen> - - <para>The new prompt is <literal>*Main</literal>, which - indicates that we are typing expressions in the context of the - top-level of the <literal>Main</literal> module. Everything - that is in scope at the top-level in the module - <literal>Main</literal> we just loaded is also in scope at the - prompt (probably including <literal>Prelude</literal>, as long - as <literal>Main</literal> doesn't explicitly hide it).</para> - - <para>The syntax in the prompt - <literal>*<replaceable>module</replaceable></literal> indicates - that it is the full top-level scope of - <replaceable>module</replaceable> that is contributing to the - scope for expressions typed at the prompt. Without the - <literal>*</literal>, just the exports of the module are - visible.</para> - - <para>NOTE: for technical reasons, GHCi can only support the - <literal>*</literal>-form for modules that are interpreted. - Compiled modules and package modules can only contribute their - exports to the current scope. To ensure that GHCi loads the - interpreted version of a module, add the <literal>*</literal> - when loading the module, e.g. <literal>:load *M</literal>.</para> - - <para>In general, after a <literal>:load</literal> command, an automatic - import is added to the scope for the most recently loaded - "target" module, in a <literal>*</literal>-form if possible. - For example, if you say <literal>:load foo.hs bar.hs</literal> - and <filename>bar.hs</filename> contains module - <literal>Bar</literal>, then the scope will be set to - <literal>*Bar</literal> if <literal>Bar</literal> is - interpreted, or if <literal>Bar</literal> is compiled it will be - set to <literal>Prelude Bar</literal> (GHCi automatically adds - <literal>Prelude</literal> if it isn't present and there aren't - any <literal>*</literal>-form modules). These - automatically-added imports can be seen with - <literal>:show imports</literal>: - -<screen> -Prelude> :load hello.hs -[1 of 1] Compiling Main ( hello.hs, interpreted ) -Ok, modules loaded: Main. -*Main> :show imports -:module +*Main -- added automatically -*Main> -</screen> - - and the automatically-added import is replaced the next time you - use <literal>:load</literal>, <literal>:add</literal>, or - <literal>:reload</literal>. It can also be removed by - <literal>:module</literal> as with normal imports.</para> - </sect3> - - <sect3 id="ghci-import-decl"> - <title>Controlling what is in scope with <literal>import</literal></title> - - <para>We are not limited to a single module: GHCi can combine - scopes from multiple modules, in any mixture of - <literal>*</literal> and non-<literal>*</literal> forms. GHCi - combines the scopes from all of these modules to form the scope - that is in effect at the prompt.</para> - - <para>To add modules to the scope, use ordinary Haskell - <literal>import</literal> syntax:</para> - -<screen> -Prelude> import System.IO -Prelude System.IO> hPutStrLn stdout "hello\n" -hello -Prelude System.IO> -</screen> - - <para>The full Haskell import syntax is supported, including - <literal>hiding</literal> and <literal>as</literal> clauses. - The prompt shows the modules that are currently imported, but it - omits details about <literal>hiding</literal>, - <literal>as</literal>, and so on. To see the full story, use - <literal>:show imports</literal>:</para> - -<screen> -Prelude> import System.IO -Prelude System.IO> import Data.Map as Map -Prelude System.IO Map> :show imports -import Prelude -- implicit -import System.IO -import Data.Map as Map -Prelude System.IO Map> -</screen> - - <para>Note that the <literal>Prelude</literal> import is marked - as implicit. It can be overridden with an explicit - <literal>Prelude</literal> import, just like in a Haskell - module.</para> - - <para>With multiple modules in scope, especially multiple - <literal>*</literal>-form modules, it is likely that name - clashes will occur. Haskell specifies that name clashes are - only reported when an ambiguous identifier is used, and GHCi - behaves in the same way for expressions typed at the - prompt.</para> - - </sect3> - - <sect3 id="ghci-module-cmd"> - <title>Controlling what is in scope with the <literal>:module</literal> command</title> - - <para>Another way to manipulate the scope is to use the - <literal>:module</literal> command, whose syntax is this: - -<screen> -:module <optional>+|-</optional> <optional>*</optional><replaceable>mod<subscript>1</subscript></replaceable> ... <optional>*</optional><replaceable>mod<subscript>n</subscript></replaceable> -</screen> - - Using the <literal>+</literal> form of the - <literal>module</literal> commands adds modules to the current - scope, and <literal>-</literal> removes them. Without either - <literal>+</literal> or <literal>-</literal>, the current scope - is replaced by the set of modules specified. Note that if you - use this form and leave out <literal>Prelude</literal>, an - implicit <literal>Prelude</literal> import will be added - automatically.</para> - - <para>The <literal>:module</literal> command provides a way to do - two things that cannot be done with ordinary - <literal>import</literal> declarations: - <itemizedlist> - <listitem> - <para><literal>:module</literal> supports the - <literal>*</literal> modifier on modules, which opens the - full top-level scope of a module, rather than just its - exports.</para> - </listitem> - <listitem> - <para>Imports can be <emphasis>removed</emphasis> from the - context, using the syntax <literal>:module -M</literal>. - The <literal>import</literal> syntax is cumulative (as in a - Haskell module), so this is the only way to subtract from - the scope.</para> - </listitem> - </itemizedlist> - </para> - </sect3> - - <sect3 id="ghci-import-qualified"> - <title>Qualified names</title> - - <para>To make life slightly easier, the GHCi prompt also - behaves as if there is an implicit <literal>import - qualified</literal> declaration for every module in every - package, and every module currently loaded into GHCi. This - behaviour can be disabled with the flag <option>-fno-implicit-import-qualified</option><indexterm><primary><option>-fno-implicit-import-qualified</option></primary></indexterm>.</para> - </sect3> - - <sect3> - <title><literal>:module</literal> and - <literal>:load</literal></title> - - <para>It might seem that <literal>:module</literal>/<literal>import</literal> and - <literal>:load</literal>/<literal>:add</literal>/<literal>:reload</literal> - do similar things: you can use both - to bring a module into scope. However, there is a very important - difference. GHCi is concerned with two sets of modules:</para> - - <itemizedlist> - <listitem> - <para>The set of modules that are currently - <emphasis>loaded</emphasis>. This set is modified by - <literal>:load</literal>, <literal>:add</literal> and - <literal>:reload</literal>, and can be shown with - <literal>:show modules</literal>. - </para> - </listitem> - <listitem> - <para>The set of modules that are currently <emphasis>in - scope</emphasis> at the prompt. This set is modified by - <literal>import</literal> and <literal>:module</literal>, and - it is also modified automatically after - <literal>:load</literal>, <literal>:add</literal>, and - <literal>:reload</literal>, as described above. - The set of modules in scope can be shown with - <literal>:show imports</literal>.</para> - </listitem> - </itemizedlist> - - <para>You can add a module to the scope (via <literal>:module</literal> - or <literal>import</literal>) - only if either (a) it is loaded, or - (b) it is a module from a package that GHCi knows about. - Using <literal>:module</literal> or <literal>import</literal> - to try bring into scope a non-loaded module may result - in the message “<literal>module M is not - loaded</literal>”.</para> - </sect3> - - </sect2> - <sect2> - <title>The <literal>:main</literal> and <literal>:run</literal> commands</title> - - <para> - When a program is compiled and executed, it can use the - <literal>getArgs</literal> function to access the - command-line arguments. - However, we cannot simply pass the arguments to the - <literal>main</literal> function while we are testing in ghci, - as the <literal>main</literal> function doesn't take its - directly. - </para> - - <para> - Instead, we can use the <literal>:main</literal> command. - This runs whatever <literal>main</literal> is in scope, with - any arguments being treated the same as command-line arguments, - e.g.: - </para> - -<screen> -Prelude> let main = System.Environment.getArgs >>= print -Prelude> :main foo bar -["foo","bar"] -</screen> - - <para> - We can also quote arguments which contains characters like - spaces, and they are treated like Haskell strings, or we can - just use Haskell list syntax: - </para> - -<screen> -Prelude> :main foo "bar baz" -["foo","bar baz"] -Prelude> :main ["foo", "bar baz"] -["foo","bar baz"] -</screen> - - <para> - Finally, other functions can be called, either with the - <literal>-main-is</literal> flag or the <literal>:run</literal> - command: - </para> - -<screen> -Prelude> let foo = putStrLn "foo" >> System.Environment.getArgs >>= print -Prelude> let bar = putStrLn "bar" >> System.Environment.getArgs >>= print -Prelude> :set -main-is foo -Prelude> :main foo "bar baz" -foo -["foo","bar baz"] -Prelude> :run bar ["foo", "bar baz"] -bar -["foo","bar baz"] -</screen> - </sect2> - - - <sect2> - <title>The <literal>it</literal> variable</title> - <indexterm><primary><literal>it</literal></primary> - </indexterm> - - <para>Whenever an expression (or a non-binding statement, to be - precise) is typed at the prompt, GHCi implicitly binds its value - to the variable <literal>it</literal>. For example:</para> -<screen> -Prelude> 1+2 -3 -Prelude> it * 2 -6 -</screen> - <para>What actually happens is that GHCi typechecks the - expression, and if it doesn't have an <literal>IO</literal> type, - then it transforms it as follows: an expression - <replaceable>e</replaceable> turns into -<screen> -let it = <replaceable>e</replaceable>; -print it -</screen> - which is then run as an IO-action.</para> - - <para>Hence, the original expression must have a type which is an - instance of the <literal>Show</literal> class, or GHCi will - complain:</para> - -<screen> -Prelude> id - -<interactive>:1:0: - No instance for (Show (a -> a)) - arising from use of `print' at <interactive>:1:0-1 - Possible fix: add an instance declaration for (Show (a -> a)) - In the expression: print it - In a 'do' expression: print it -</screen> - - <para>The error message contains some clues as to the - transformation happening internally.</para> - - <para>If the expression was instead of type <literal>IO a</literal> for - some <literal>a</literal>, then <literal>it</literal> will be - bound to the result of the <literal>IO</literal> computation, - which is of type <literal>a</literal>. eg.:</para> -<screen> -Prelude> Time.getClockTime -Wed Mar 14 12:23:13 GMT 2001 -Prelude> print it -Wed Mar 14 12:23:13 GMT 2001 -</screen> - - <para>The corresponding translation for an IO-typed - <replaceable>e</replaceable> is -<screen> -it <- <replaceable>e</replaceable> -</screen> - </para> - - <para>Note that <literal>it</literal> is shadowed by the new - value each time you evaluate a new expression, and the old value - of <literal>it</literal> is lost.</para> - - </sect2> - - <sect2 id="extended-default-rules"> - <title>Type defaulting in GHCi</title> - <indexterm><primary>Type default</primary></indexterm> - <indexterm><primary><literal>Show</literal> class</primary></indexterm> - <para> - Consider this GHCi session: -<programlisting> - ghci> reverse [] -</programlisting> - What should GHCi do? Strictly speaking, the program is ambiguous. <literal>show (reverse [])</literal> - (which is what GHCi computes here) has type <literal>Show a => String</literal> and how that displays depends - on the type <literal>a</literal>. For example: -<programlisting> - ghci> reverse ([] :: String) - "" - ghci> reverse ([] :: [Int]) - [] -</programlisting> - However, it is tiresome for the user to have to specify the type, so GHCi extends Haskell's type-defaulting - rules (Section 4.3.4 of the Haskell 2010 Report) as follows. The - standard rules take each group of constraints <literal>(C1 a, C2 a, ..., Cn - a)</literal> for each type variable <literal>a</literal>, and defaults the - type variable if - <orderedlist> - <listitem> - <para> - The type variable <literal>a</literal> appears in no - other constraints - </para> - </listitem> - <listitem> - <para> - All the classes <literal>Ci</literal> are standard. - </para> - </listitem> - <listitem> - <para> - At least one of the classes <literal>Ci</literal> is - numeric. - </para> - </listitem> - </orderedlist> - At the GHCi prompt, or with GHC if the - <literal>-XExtendedDefaultRules</literal> flag is given, - the following additional differences apply: - <itemizedlist> - <listitem> - <para> - Rule 2 above is relaxed thus: - <emphasis>All</emphasis> of the classes - <literal>Ci</literal> are single-parameter type classes. - </para> - </listitem> - <listitem> - <para> - Rule 3 above is relaxed this: - At least one of the classes <literal>Ci</literal> is - numeric, <emphasis>or is <literal>Show</literal>, - <literal>Eq</literal>, or - <literal>Ord</literal></emphasis>. - </para> - </listitem> - <listitem> - <para> - The unit type <literal>()</literal> is added to the - start of the standard list of types which are tried when - doing type defaulting. - </para> - </listitem> - </itemizedlist> - The last point means that, for example, this program: -<programlisting> -main :: IO () -main = print def - -instance Num () - -def :: (Num a, Enum a) => a -def = toEnum 0 -</programlisting> - prints <literal>()</literal> rather than <literal>0</literal> as the - type is defaulted to <literal>()</literal> rather than - <literal>Integer</literal>. - </para> - <para> - The motivation for the change is that it means <literal>IO a</literal> - actions default to <literal>IO ()</literal>, which in turn means that - ghci won't try to print a result when running them. This is - particularly important for <literal>printf</literal>, which has an - instance that returns <literal>IO a</literal>. - However, it is only able to return - <literal>undefined</literal> - (the reason for the instance having this type is so that printf - doesn't require extensions to the class system), so if the type defaults to - <literal>Integer</literal> then ghci gives an error when running a - printf. - </para> - <para>See also <xref linkend="actions-at-prompt"/> for how the monad of a computational - expression defaults to <literal>IO</literal> if possible. - </para> - </sect2> - - <sect2 id="ghci-interactive-print"> - <title>Using a custom interactive printing function</title> - <para>[<emphasis role="bold">New in version 7.6.1</emphasis>] - By default, GHCi prints the result of expressions typed at the prompt - using the function <literal>System.IO.print</literal>. Its type - signature is <literal>Show a => a -> IO ()</literal>, and it works by - converting the value to <literal>String</literal> using - <literal>show</literal>. - </para> - <para> - This is not ideal in certain cases, like when the output is long, or - contains strings with non-ascii characters. - </para> - <para> - The <literal>-interactive-print</literal> flag allows to specify any - function of type <literal>C a => a -> IO ()</literal>, for some - constraint <literal>C</literal>, as the function for printing evaluated - expressions. The function can reside in any loaded module or any - registered package. - </para> - <para> - As an example, suppose we have following special printing module: - <programlisting> - module SpecPrinter where - import System.IO - - sprint a = putStrLn $ show a ++ "!" - </programlisting> - The <literal>sprint</literal> function adds an exclamation mark at the - end of any printed value. Running GHCi with the command: - <programlisting> - ghci -interactive-print=SpecPrinter.sprinter SpecPrinter - </programlisting> - will start an interactive session where values with be printed using - <literal>sprint</literal>: - <programlisting> - *SpecPrinter> [1,2,3] - [1,2,3]! - *SpecPrinter> 42 - 42! - </programlisting> - </para> - <para> - A custom pretty printing function can be used, for example, to format - tree-like and nested structures in a more readable way. - </para> - <para> - The <literal>-interactive-print</literal> flag can also be used when - running GHC in <literal>-e mode</literal>: - <programlisting> - % ghc -e "[1,2,3]" -interactive-print=SpecPrinter.sprint SpecPrinter - [1,2,3]! - </programlisting> - </para> - </sect2> - </sect1> - - <sect1 id="ghci-debugger"> - <title>The GHCi Debugger</title> - <indexterm><primary>debugger</primary><secondary>in GHCi</secondary> - </indexterm> - - <para>GHCi contains a simple imperative-style debugger in which you can - stop a running computation in order to examine the values of - variables. The debugger is integrated into GHCi, and is turned on by - default: no flags are required to enable the debugging - facilities. There is one major restriction: breakpoints and - single-stepping are only available in interpreted modules; - compiled code is invisible to the debugger<footnote><para>Note that packages - only contain compiled code, so debugging a package requires - finding its source and loading that directly.</para></footnote>.</para> - - <para>The debugger provides the following: - <itemizedlist> - <listitem> - <para>The ability to set a <firstterm>breakpoint</firstterm> on a - function definition or expression in the program. When the function - is called, or the expression evaluated, GHCi suspends - execution and returns to the prompt, where you can inspect the - values of local variables before continuing with the - execution.</para> - </listitem> - <listitem> - <para>Execution can be <firstterm>single-stepped</firstterm>: the - evaluator will suspend execution approximately after every - reduction, allowing local variables to be inspected. This is - equivalent to setting a breakpoint at every point in the - program.</para> - </listitem> - <listitem> - <para>Execution can take place in <firstterm>tracing - mode</firstterm>, in which the evaluator remembers each - evaluation step as it happens, but doesn't suspend execution until - an actual breakpoint is reached. When this happens, the history of - evaluation steps can be inspected.</para> - </listitem> - <listitem> - <para>Exceptions (e.g. pattern matching failure and - <literal>error</literal>) can be treated as breakpoints, to help - locate the source of an exception in the program.</para> - </listitem> - </itemizedlist> - </para> - - <para>There is currently no support for obtaining a “stack - trace”, but the tracing and history features provide a - useful second-best, which will often be enough to establish the - context of an error. For instance, it is possible to break - automatically when an exception is thrown, even if it is thrown - from within compiled code (see <xref - linkend="ghci-debugger-exceptions" />).</para> - - <sect2 id="breakpoints"> - <title>Breakpoints and inspecting variables</title> - - <para>Let's use quicksort as a running example. Here's the code:</para> - -<programlisting> -qsort [] = [] -qsort (a:as) = qsort left ++ [a] ++ qsort right - where (left,right) = (filter (<=a) as, filter (>a) as) - -main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18]) -</programlisting> - - <para>First, load the module into GHCi:</para> - -<screen> -Prelude> :l qsort.hs -[1 of 1] Compiling Main ( qsort.hs, interpreted ) -Ok, modules loaded: Main. -*Main> - </screen> - - <para>Now, let's set a breakpoint on the right-hand-side of the second - equation of qsort:</para> - -<programlisting> -*Main> :break 2 -Breakpoint 0 activated at qsort.hs:2:15-46 -*Main> -</programlisting> - - <para>The command <literal>:break 2</literal> sets a breakpoint on line - 2 of the most recently-loaded module, in this case - <literal>qsort.hs</literal>. Specifically, it picks the - leftmost complete subexpression on that line on which to set the - breakpoint, which in this case is the expression - <literal>(qsort left ++ [a] ++ qsort right)</literal>.</para> - - <para>Now, we run the program:</para> - -<programlisting> -*Main> main -Stopped at qsort.hs:2:15-46 -_result :: [a] -a :: a -left :: [a] -right :: [a] -[qsort.hs:2:15-46] *Main> -</programlisting> - - <para>Execution has stopped at the breakpoint. The prompt has changed to - indicate that we are currently stopped at a breakpoint, and the location: - <literal>[qsort.hs:2:15-46]</literal>. To further clarify the - location, we can use the <literal>:list</literal> command:</para> - -<programlisting> -[qsort.hs:2:15-46] *Main> :list -1 qsort [] = [] -2 qsort (a:as) = qsort left ++ [a] ++ qsort right -3 where (left,right) = (filter (<=a) as, filter (>a) as) -</programlisting> - - <para>The <literal>:list</literal> command lists the source code around - the current breakpoint. If your output device supports it, then GHCi - will highlight the active subexpression in bold.</para> - - <para>GHCi has provided bindings for the free variables<footnote><para>We - originally provided bindings for all variables in scope, rather - than just - the free variables of the expression, but found that this affected - performance considerably, hence the current restriction to just the - free variables.</para> - </footnote> of the expression - on which the - breakpoint was placed (<literal>a</literal>, <literal>left</literal>, - <literal>right</literal>), and additionally a binding for the result of - the expression (<literal>_result</literal>). These variables are just - like other variables that you might define in GHCi; you - can use them in expressions that you type at the prompt, you can ask - for their types with <literal>:type</literal>, and so on. There is one - important difference though: these variables may only have partial - types. For example, if we try to display the value of - <literal>left</literal>:</para> - -<screen> -[qsort.hs:2:15-46] *Main> left - -<interactive>:1:0: - Ambiguous type variable `a' in the constraint: - `Show a' arising from a use of `print' at <interactive>:1:0-3 - Cannot resolve unknown runtime types: a - Use :print or :force to determine these types -</screen> - - <para>This is because <literal>qsort</literal> is a polymorphic function, - and because GHCi does not carry type information at runtime, it cannot - determine the runtime types of free variables that involve type - variables. Hence, when you ask to display <literal>left</literal> at - the prompt, GHCi can't figure out which instance of - <literal>Show</literal> to use, so it emits the type error above.</para> - - <para>Fortunately, the debugger includes a generic printing command, - <literal>:print</literal>, which can inspect the actual runtime value of a - variable and attempt to reconstruct its type. If we try it on - <literal>left</literal>:</para> - -<screen> -[qsort.hs:2:15-46] *Main> :set -fprint-evld-with-show -[qsort.hs:2:15-46] *Main> :print left -left = (_t1::[a]) -</screen> - - <para>This isn't particularly enlightening. What happened is that - <literal>left</literal> is bound to an unevaluated computation (a - suspension, or <firstterm>thunk</firstterm>), and - <literal>:print</literal> does not force any evaluation. The idea is - that <literal>:print</literal> can be used to inspect values at a - breakpoint without any unfortunate side effects. It won't force any - evaluation, which could cause the program to give a different answer - than it would normally, and hence it won't cause any exceptions to be - raised, infinite loops, or further breakpoints to be triggered (see - <xref linkend="nested-breakpoints" />). - Rather than forcing thunks, <literal>:print</literal> - binds each thunk to a fresh variable beginning with an - underscore, in this case - <literal>_t1</literal>.</para> - - <para>The flag <literal>-fprint-evld-with-show</literal> instructs - <literal>:print</literal> to reuse - available <literal>Show</literal> instances when possible. This happens - only when the contents of the variable being inspected - are completely evaluated.</para> - - - <para>If we aren't concerned about preserving the evaluatedness of a - variable, we can use <literal>:force</literal> instead of - <literal>:print</literal>. The <literal>:force</literal> command - behaves exactly like <literal>:print</literal>, except that it forces - the evaluation of any thunks it encounters:</para> - -<screen> -[qsort.hs:2:15-46] *Main> :force left -left = [4,0,3,1] -</screen> - - <para>Now, since <literal>:force</literal> has inspected the runtime - value of <literal>left</literal>, it has reconstructed its type. We - can see the results of this type reconstruction:</para> - -<screen> -[qsort.hs:2:15-46] *Main> :show bindings -_result :: [Integer] -a :: Integer -left :: [Integer] -right :: [Integer] -_t1 :: [Integer] -</screen> - - <para>Not only do we now know the type of <literal>left</literal>, but - all the other partial types have also been resolved. So we can ask - for the value of <literal>a</literal>, for example:</para> - -<screen> -[qsort.hs:2:15-46] *Main> a -8 -</screen> - - <para>You might find it useful to use Haskell's - <literal>seq</literal> function to evaluate individual thunks rather - than evaluating the whole expression with <literal>:force</literal>. - For example:</para> - -<screen> -[qsort.hs:2:15-46] *Main> :print right -right = (_t1::[Integer]) -[qsort.hs:2:15-46] *Main> seq _t1 () -() -[qsort.hs:2:15-46] *Main> :print right -right = 23 : (_t2::[Integer]) -</screen> - - <para>We evaluated only the <literal>_t1</literal> thunk, revealing the - head of the list, and the tail is another thunk now bound to - <literal>_t2</literal>. The <literal>seq</literal> function is a - little inconvenient to use here, so you might want to use - <literal>:def</literal> to make a nicer interface (left as an exercise - for the reader!).</para> - - <para>Finally, we can continue the current execution:</para> - -<screen> -[qsort.hs:2:15-46] *Main> :continue -Stopped at qsort.hs:2:15-46 -_result :: [a] -a :: a -left :: [a] -right :: [a] -[qsort.hs:2:15-46] *Main> -</screen> - - <para>The execution continued at the point it previously stopped, and has - now stopped at the breakpoint for a second time.</para> - - - <sect3 id="setting-breakpoints"> - <title>Setting breakpoints</title> - - <para>Breakpoints can be set in various ways. Perhaps the easiest way to - set a breakpoint is to name a top-level function:</para> - -<screen> - :break <replaceable>identifier</replaceable> -</screen> - - <para>Where <replaceable>identifier</replaceable> names any top-level - function in an interpreted module currently loaded into GHCi (qualified - names may be used). The breakpoint will be set on the body of the - function, when it is fully applied but before any pattern matching has - taken place.</para> - - <para>Breakpoints can also be set by line (and optionally column) - number:</para> - -<screen> - :break <replaceable>line</replaceable> - :break <replaceable>line</replaceable> <replaceable>column</replaceable> - :break <replaceable>module</replaceable> <replaceable>line</replaceable> - :break <replaceable>module</replaceable> <replaceable>line</replaceable> <replaceable>column</replaceable> -</screen> - - <para>When a breakpoint is set on a particular line, GHCi sets the - breakpoint on the - leftmost subexpression that begins and ends on that line. If two - complete subexpressions start at the same - column, the longest one is picked. If there is no complete - subexpression on the line, then the leftmost expression starting on - the line is picked, and failing that the rightmost expression that - partially or completely covers the line.</para> - - <para>When a breakpoint is set on a particular line and column, GHCi - picks the smallest subexpression that encloses that location on which - to set the breakpoint. Note: GHC considers the TAB character to have a - width of 1, wherever it occurs; in other words it counts - characters, rather than columns. This matches what some editors do, - and doesn't match others. The best advice is to avoid tab - characters in your source code altogether (see - <option>-fwarn-tabs</option> in <xref linkend="options-sanity" - />).</para> - - <para>If the module is omitted, then the most recently-loaded module is - used.</para> - - <para>Not all subexpressions are potential breakpoint locations. Single - variables are typically not considered to be breakpoint locations - (unless the variable is the right-hand-side of a function definition, - lambda, or case alternative). The rule of thumb is that all redexes - are breakpoint locations, together with the bodies of functions, - lambdas, case alternatives and binding statements. There is normally - no breakpoint on a let expression, but there will always be a - breakpoint on its body, because we are usually interested in inspecting - the values of the variables bound by the let.</para> - - </sect3> - <sect3> - <title>Listing and deleting breakpoints</title> - - <para>The list of breakpoints currently enabled can be displayed using - <literal>:show breaks</literal>:</para> -<screen> -*Main> :show breaks -[0] Main qsort.hs:1:11-12 -[1] Main qsort.hs:2:15-46 -</screen> - - <para>To delete a breakpoint, use the <literal>:delete</literal> - command with the number given in the output from <literal>:show breaks</literal>:</para> - -<screen> -*Main> :delete 0 -*Main> :show breaks -[1] Main qsort.hs:2:15-46 -</screen> - - <para>To delete all breakpoints at once, use <literal>:delete *</literal>.</para> - - </sect3> - </sect2> - - <sect2 id="single-stepping"> - <title>Single-stepping</title> - - <para>Single-stepping is a great way to visualise the execution of your - program, and it is also a useful tool for identifying the source of a - bug. GHCi offers two variants of stepping. Use - <literal>:step</literal> to enable all the - breakpoints in the program, and execute until the next breakpoint is - reached. Use <literal>:steplocal</literal> to limit the set - of enabled breakpoints to those in the current top level function. - Similarly, use <literal>:stepmodule</literal> to single step only on - breakpoints contained in the current module. - For example:</para> - -<screen> -*Main> :step main -Stopped at qsort.hs:5:7-47 -_result :: IO () -</screen> - - <para>The command <literal>:step - <replaceable>expr</replaceable></literal> begins the evaluation of - <replaceable>expr</replaceable> in single-stepping mode. If - <replaceable>expr</replaceable> is omitted, then it single-steps from - the current breakpoint. <literal>:steplocal</literal> and - <literal>:stepmodule</literal> work similarly.</para> - - <para>The <literal>:list</literal> command is particularly useful when - single-stepping, to see where you currently are:</para> - -<screen> -[qsort.hs:5:7-47] *Main> :list -4 -5 main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18]) -6 -[qsort.hs:5:7-47] *Main> -</screen> - - <para>In fact, GHCi provides a way to run a command when a breakpoint is - hit, so we can make it automatically do - <literal>:list</literal>:</para> - -<screen> -[qsort.hs:5:7-47] *Main> :set stop :list -[qsort.hs:5:7-47] *Main> :step -Stopped at qsort.hs:5:14-46 -_result :: [Integer] -4 -5 main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18]) -6 -[qsort.hs:5:14-46] *Main> -</screen> - </sect2> - - <sect2 id="nested-breakpoints"> - <title>Nested breakpoints</title> - <para>When GHCi is stopped at a breakpoint, and an expression entered at - the prompt triggers a - second breakpoint, the new breakpoint becomes the “current” - one, and the old one is saved on a stack. An arbitrary number of - breakpoint contexts can be built up in this way. For example:</para> - -<screen> -[qsort.hs:2:15-46] *Main> :st qsort [1,3] -Stopped at qsort.hs:(1,0)-(3,55) -_result :: [a] -... [qsort.hs:(1,0)-(3,55)] *Main> -</screen> - - <para>While stopped at the breakpoint on line 2 that we set earlier, we - started a new evaluation with <literal>:step qsort [1,3]</literal>. - This new evaluation stopped after one step (at the definition of - <literal>qsort</literal>). The prompt has changed, now prefixed with - <literal>...</literal>, to indicate that there are saved breakpoints - beyond the current one. To see the stack of contexts, use - <literal>:show context</literal>:</para> - -<screen> -... [qsort.hs:(1,0)-(3,55)] *Main> :show context ---> main - Stopped at qsort.hs:2:15-46 ---> qsort [1,3] - Stopped at qsort.hs:(1,0)-(3,55) -... [qsort.hs:(1,0)-(3,55)] *Main> -</screen> - - <para>To abandon the current evaluation, use - <literal>:abandon</literal>:</para> - -<screen> -... [qsort.hs:(1,0)-(3,55)] *Main> :abandon -[qsort.hs:2:15-46] *Main> :abandon -*Main> -</screen> - </sect2> - - <sect2 id="ghci-debugger-result"> - <title>The <literal>_result</literal> variable</title> - <para>When stopped at a breakpoint or single-step, GHCi binds the - variable <literal>_result</literal> to the value of the currently - active expression. The value of <literal>_result</literal> is - presumably not available yet, because we stopped its evaluation, but it - can be forced: if the type is known and showable, then just entering - <literal>_result</literal> at the prompt will show it. However, - there's one caveat to doing this: evaluating <literal>_result</literal> - will be likely to trigger further breakpoints, starting with the - breakpoint we are currently stopped at (if we stopped at a real - breakpoint, rather than due to <literal>:step</literal>). So it will - probably be necessary to issue a <literal>:continue</literal> - immediately when evaluating <literal>_result</literal>. Alternatively, - you can use <literal>:force</literal> which ignores breakpoints.</para> - </sect2> - - <sect2 id="tracing"> - <title>Tracing and history</title> - - <para>A question that we often want to ask when debugging a program is - “how did I get here?”. Traditional imperative debuggers - usually provide some kind of stack-tracing feature that lets you see - the stack of active function calls (sometimes called the “lexical - call stack”), describing a path through the code - to the current location. Unfortunately this is hard to provide in - Haskell, because execution proceeds on a demand-driven basis, rather - than a depth-first basis as in strict languages. The - “stack“ in GHC's execution engine bears little - resemblance to the lexical call stack. Ideally GHCi would maintain a - separate lexical call stack in addition to the dynamic call stack, and - in fact this is exactly - what our profiling system does (<xref linkend="profiling" />), and what - some other Haskell debuggers do. For the time being, however, GHCi - doesn't maintain a lexical call stack (there are some technical - challenges to be overcome). Instead, we provide a way to backtrack from a - breakpoint to previous evaluation steps: essentially this is like - single-stepping backwards, and should in many cases provide enough - information to answer the “how did I get here?” - question.</para> - - <para>To use tracing, evaluate an expression with the - <literal>:trace</literal> command. For example, if we set a breakpoint - on the base case of <literal>qsort</literal>:</para> - -<screen> -*Main> :list qsort -1 qsort [] = [] -2 qsort (a:as) = qsort left ++ [a] ++ qsort right -3 where (left,right) = (filter (<=a) as, filter (>a) as) -4 -*Main> :b 1 -Breakpoint 1 activated at qsort.hs:1:11-12 -*Main> -</screen> - - <para>and then run a small <literal>qsort</literal> with - tracing:</para> - -<screen> -*Main> :trace qsort [3,2,1] -Stopped at qsort.hs:1:11-12 -_result :: [a] -[qsort.hs:1:11-12] *Main> -</screen> - - <para>We can now inspect the history of evaluation steps:</para> - -<screen> -[qsort.hs:1:11-12] *Main> :hist --1 : qsort.hs:3:24-38 --2 : qsort.hs:3:23-55 --3 : qsort.hs:(1,0)-(3,55) --4 : qsort.hs:2:15-24 --5 : qsort.hs:2:15-46 --6 : qsort.hs:3:24-38 --7 : qsort.hs:3:23-55 --8 : qsort.hs:(1,0)-(3,55) --9 : qsort.hs:2:15-24 --10 : qsort.hs:2:15-46 --11 : qsort.hs:3:24-38 --12 : qsort.hs:3:23-55 --13 : qsort.hs:(1,0)-(3,55) --14 : qsort.hs:2:15-24 --15 : qsort.hs:2:15-46 --16 : qsort.hs:(1,0)-(3,55) -<end of history> -</screen> - - <para>To examine one of the steps in the history, use - <literal>:back</literal>:</para> - -<screen> -[qsort.hs:1:11-12] *Main> :back -Logged breakpoint at qsort.hs:3:24-38 -_result :: [a] -as :: [a] -a :: a -[-1: qsort.hs:3:24-38] *Main> -</screen> - - <para>Note that the local variables at each step in the history have been - preserved, and can be examined as usual. Also note that the prompt has - changed to indicate that we're currently examining the first step in - the history: <literal>-1</literal>. The command - <literal>:forward</literal> can be used to traverse forward in the - history.</para> - - <para>The <literal>:trace</literal> command can be used with or without - an expression. When used without an expression, tracing begins from - the current breakpoint, just like <literal>:step</literal>.</para> - - <para>The history is only available when - using <literal>:trace</literal>; the reason for this is we found that - logging each breakpoint in the history cuts performance by a factor of - 2 or more. By default, GHCi remembers the last 50 steps in the history, but this can be changed with the <option>-fghci-hist-size=<replaceable>n</replaceable></option><indexterm><primary><option>-fghci-hist-size</option></primary></indexterm> option).</para> - </sect2> - - <sect2 id="ghci-debugger-exceptions"> - <title>Debugging exceptions</title> - <para>Another common question that comes up when debugging is - “where did this exception come from?”. Exceptions such as - those raised by <literal>error</literal> or <literal>head []</literal> - have no context information attached to them. Finding which - particular call to <literal>head</literal> in your program resulted in - the error can be a painstaking process, usually involving - <literal>Debug.Trace.trace</literal>, or compiling with - profiling and using <literal>Debug.Trace.traceStack</literal> - or <literal>+RTS -xc</literal> (see <xref - linkend="prof-time-options" />).</para> - - <para>The GHCi debugger offers a way to hopefully shed some light on - these errors quickly and without modifying or recompiling the source - code. One way would be to set a breakpoint on the location in the - source code that throws the exception, and then use - <literal>:trace</literal> and <literal>:history</literal> to establish - the context. However, <literal>head</literal> is in a library and - we can't set a breakpoint on it directly. For this reason, GHCi - provides the flags <literal>-fbreak-on-exception</literal> which causes - the evaluator to stop when an exception is thrown, and <literal> - -fbreak-on-error</literal>, which works similarly but stops only on - uncaught exceptions. When stopping at an exception, GHCi will act - just as it does when a breakpoint is hit, with the deviation that it - will not show you any source code location. Due to this, these - commands are only really useful in conjunction with - <literal>:trace</literal>, in order to log the steps leading up to the - exception. For example:</para> - -<screen> -*Main> :set -fbreak-on-exception -*Main> :trace qsort ("abc" ++ undefined) -“Stopped at <exception thrown> -_exception :: e -[<exception thrown>] *Main> :hist --1 : qsort.hs:3:24-38 --2 : qsort.hs:3:23-55 --3 : qsort.hs:(1,0)-(3,55) --4 : qsort.hs:2:15-24 --5 : qsort.hs:2:15-46 --6 : qsort.hs:(1,0)-(3,55) -<end of history> -[<exception thrown>] *Main> :back -Logged breakpoint at qsort.hs:3:24-38 -_result :: [a] -as :: [a] -a :: a -[-1: qsort.hs:3:24-38] *Main> :force as -*** Exception: Prelude.undefined -[-1: qsort.hs:3:24-38] *Main> :print as -as = 'b' : 'c' : (_t1::[Char]) -</screen> - - <para>The exception itself is bound to a new variable, - <literal>_exception</literal>.</para> - - <para>Breaking on exceptions is particularly useful for finding out what - your program was doing when it was in an infinite loop. Just hit - Control-C, and examine the history to find out what was going - on.</para> - </sect2> - - <sect2><title>Example: inspecting functions</title> - <para> - It is possible to use the debugger to examine function values. - When we are at a breakpoint and a function is in scope, the debugger - cannot show - you the source code for it; however, it is possible to get some - information by applying it to some arguments and observing the result. - </para> - - <para> - The process is slightly complicated when the binding is polymorphic. - We show the process by means of an example. - To keep things simple, we will use the well known <literal>map</literal> function: -<programlisting> -import Prelude hiding (map) - -map :: (a->b) -> [a] -> [b] -map f [] = [] -map f (x:xs) = f x : map f xs -</programlisting> - </para> - - <para> - We set a breakpoint on <literal>map</literal>, and call it. -<screen> -*Main> :break 5 -Breakpoint 0 activated at map.hs:5:15-28 -*Main> map Just [1..5] -Stopped at map.hs:(4,0)-(5,12) -_result :: [b] -x :: a -f :: a -> b -xs :: [a] -</screen> - GHCi tells us that, among other bindings, <literal>f</literal> is in scope. - However, its type is not fully known yet, - and thus it is not possible to apply it to any - arguments. Nevertheless, observe that the type of its first argument is the - same as the type of <literal>x</literal>, and its result type is shared - with <literal>_result</literal>. - </para> - - <para> - As we demonstrated earlier (<xref linkend="breakpoints" />), the - debugger has some intelligence built-in to update the type of - <literal>f</literal> whenever the types of <literal>x</literal> or - <literal>_result</literal> are discovered. So what we do in this - scenario is - force <literal>x</literal> a bit, in order to recover both its type - and the argument part of <literal>f</literal>. -<screen> -*Main> seq x () -*Main> :print x -x = 1 -</screen> - </para> - <para> - We can check now that as expected, the type of <literal>x</literal> - has been reconstructed, and with it the - type of <literal>f</literal> has been too:</para> -<screen> -*Main> :t x -x :: Integer -*Main> :t f -f :: Integer -> b -</screen> - <para> - From here, we can apply f to any argument of type Integer and observe - the results. -<screen><![CDATA[ -*Main> let b = f 10 -*Main> :t b -b :: b -*Main> b -<interactive>:1:0: - Ambiguous type variable `b' in the constraint: - `Show b' arising from a use of `print' at <interactive>:1:0 -*Main> :p b -b = (_t2::a) -*Main> seq b () -() -*Main> :t b -b :: a -*Main> :p b -b = Just 10 -*Main> :t b -b :: Maybe Integer -*Main> :t f -f :: Integer -> Maybe Integer -*Main> f 20 -Just 20 -*Main> map f [1..5] -[Just 1, Just 2, Just 3, Just 4, Just 5] -]]></screen> - In the first application of <literal>f</literal>, we had to do - some more type reconstruction - in order to recover the result type of <literal>f</literal>. - But after that, we are free to use - <literal>f</literal> normally. - </para> - </sect2> - - <sect2><title>Limitations</title> - <itemizedlist> - <listitem> - <para>When stopped at a breakpoint, if you try to evaluate a variable - that is already under evaluation, the second evaluation will hang. - The reason is - that GHC knows the variable is under evaluation, so the new - evaluation just waits for the result before continuing, but of - course this isn't going to happen because the first evaluation is - stopped at a breakpoint. Control-C can interrupt the hung - evaluation and return to the prompt.</para> - <para>The most common way this can happen is when you're evaluating a - CAF (e.g. main), stop at a breakpoint, and ask for the value of the - CAF at the prompt again.</para> - </listitem> - <listitem><para> - Implicit parameters (see <xref linkend="implicit-parameters"/>) are only available - at the scope of a breakpoint if there is an explicit type signature. - </para> - </listitem> - </itemizedlist> - </sect2> - </sect1> - - <sect1 id="ghci-invocation"> - <title>Invoking GHCi</title> - <indexterm><primary>invoking</primary><secondary>GHCi</secondary></indexterm> - <indexterm><primary><option>--interactive</option></primary></indexterm> - - <para>GHCi is invoked with the command <literal>ghci</literal> or - <literal>ghc --interactive</literal>. One or more modules or - filenames can also be specified on the command line; this - instructs GHCi to load the specified modules or filenames (and all - the modules they depend on), just as if you had said - <literal>:load <replaceable>modules</replaceable></literal> at the - GHCi prompt (see <xref linkend="ghci-commands" />). For example, to - start GHCi and load the program whose topmost module is in the - file <literal>Main.hs</literal>, we could say:</para> - -<screen> -$ ghci Main.hs -</screen> - - <para>Most of the command-line options accepted by GHC (see <xref - linkend="using-ghc"/>) also make sense in interactive mode. The ones - that don't make sense are mostly obvious.</para> - - <sect2> - <title>Packages</title> - <indexterm><primary>packages</primary><secondary>with GHCi</secondary></indexterm> - - <para>Most packages (see <xref linkend="using-packages"/>) are - available without needing to specify any extra flags at all: - they will be automatically loaded the first time they are - needed.</para> - - <para>For hidden packages, however, you need to request the - package be loaded by using the <literal>-package</literal> flag:</para> - -<screen> -$ ghci -package readline -GHCi, version 6.8.1: http://www.haskell.org/ghc/ :? for help -Loading package base ... linking ... done. -Loading package readline-1.0 ... linking ... done. -Prelude> -</screen> - - <para>The following command works to load new packages into a - running GHCi:</para> - -<screen> -Prelude> :set -package <replaceable>name</replaceable> -</screen> - - <para>But note that doing this will cause all currently loaded - modules to be unloaded, and you'll be dumped back into the - <literal>Prelude</literal>.</para> - </sect2> - - <sect2> - <title>Extra libraries</title> - <indexterm><primary>libraries</primary><secondary>with GHCi</secondary></indexterm> - - <para>Extra libraries may be specified on the command line using - the normal <literal>-l<replaceable>lib</replaceable></literal> - option. (The term <emphasis>library</emphasis> here refers to - libraries of foreign object code; for using libraries of Haskell - source code, see <xref linkend="ghci-modules-filenames"/>.) For - example, to load the “m” library:</para> - -<screen> -$ ghci -lm -</screen> - - <para>On systems with <literal>.so</literal>-style shared - libraries, the actual library loaded will the - <filename>lib<replaceable>lib</replaceable>.so</filename>. GHCi - searches the following places for libraries, in this order:</para> - - <itemizedlist> - <listitem> - <para>Paths specified using the - <literal>-L<replaceable>path</replaceable></literal> - command-line option,</para> - </listitem> - <listitem> - <para>the standard library search path for your system, - which on some systems may be overridden by setting the - <literal>LD_LIBRARY_PATH</literal> environment - variable.</para> - </listitem> - </itemizedlist> - - <para>On systems with <literal>.dll</literal>-style shared - libraries, the actual library loaded will be - <filename><replaceable>lib</replaceable>.dll</filename>. Again, - GHCi will signal an error if it can't find the library.</para> - - <para>GHCi can also load plain object files - (<literal>.o</literal> or <literal>.obj</literal> depending on - your platform) from the command-line. Just add the name the - object file to the command line.</para> - - <para>Ordering of <option>-l</option> options matters: a library - should be mentioned <emphasis>before</emphasis> the libraries it - depends on (see <xref linkend="options-linker"/>).</para> - </sect2> - - </sect1> - - <sect1 id="ghci-commands"> - <title>GHCi commands</title> - - <para>GHCi commands all begin with - ‘<literal>:</literal>’ and consist of a single command - name followed by zero or more parameters. The command name may be - abbreviated, with ambiguities being resolved in favour of the more - commonly used commands.</para> - - <variablelist> - <varlistentry> - <term> - <literal>:abandon</literal> - <indexterm><primary><literal>:abandon</literal></primary></indexterm> - </term> - <listitem> - <para>Abandons the current evaluation (only available when stopped at - a breakpoint).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:add</literal> <optional><literal>*</literal></optional><replaceable>module</replaceable> ... - <indexterm><primary><literal>:add</literal></primary></indexterm> - </term> - <listitem> - <para>Add <replaceable>module</replaceable>(s) to the - current <firstterm>target set</firstterm>, and perform a - reload. Normally pre-compiled code for the module will be - loaded if available, or otherwise the module will be - compiled to byte-code. Using the <literal>*</literal> - prefix forces the module to be loaded as byte-code.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:back <optional><replaceable>n</replaceable></optional></literal> - <indexterm><primary><literal>:back</literal></primary></indexterm> - </term> - <listitem> - <para>Travel back <replaceable>n</replaceable> steps in the - history. <replaceable>n</replaceable> is one if omitted. - See <xref linkend="tracing" /> for more about GHCi's debugging - facilities. See also: - <literal>:trace</literal>, <literal>:history</literal>, - <literal>:forward</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:break [<replaceable>identifier</replaceable> | - [<replaceable>module</replaceable>] <replaceable>line</replaceable> - [<replaceable>column</replaceable>]]</literal> - </term> - <indexterm><primary><literal>:break</literal></primary></indexterm> - <listitem> - <para>Set a breakpoint on the specified function or line and - column. See <xref linkend="setting-breakpoints" />.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:browse</literal><optional><literal>!</literal></optional> <optional><optional><literal>*</literal></optional><replaceable>module</replaceable></optional> ... - <indexterm><primary><literal>:browse</literal></primary></indexterm> - </term> - <listitem> - <para>Displays the identifiers exported by the module - <replaceable>module</replaceable>, which must be either - loaded into GHCi or be a member of a package. If - <replaceable>module</replaceable> is omitted, the most - recently-loaded module is used.</para> - - <para>Like all other GHCi commands, the output is always - displayed in the current GHCi scope (<xref linkend="ghci-scope"/>).</para> - - <para>There are two variants of the browse command: - <itemizedlist> - <listitem> - <para>If the <literal>*</literal> symbol is placed before - the module name, then <emphasis>all</emphasis> the - identifiers in scope in <replaceable>module</replaceable> - (rather that just its exports) are shown. </para> - - <para>The <literal>*</literal>-form is only available for modules - which are interpreted; for compiled modules (including - modules from packages) only the non-<literal>*</literal> - form of <literal>:browse</literal> is available.</para> - </listitem> - <listitem> - <para>Data constructors and class methods are usually - displayed in the context of their data type or class declaration. - However, if the <literal>!</literal> symbol is appended to the - command, thus <literal>:browse!</literal>, - they are listed individually. - The <literal>!</literal>-form also annotates the listing - with comments giving possible imports for each group of - entries. Here is an example: -<screen> -Prelude> :browse! Data.Maybe --- not currently imported -Data.Maybe.catMaybes :: [Maybe a] -> [a] -Data.Maybe.fromJust :: Maybe a -> a -Data.Maybe.fromMaybe :: a -> Maybe a -> a -Data.Maybe.isJust :: Maybe a -> Bool -Data.Maybe.isNothing :: Maybe a -> Bool -Data.Maybe.listToMaybe :: [a] -> Maybe a -Data.Maybe.mapMaybe :: (a -> Maybe b) -> [a] -> [b] -Data.Maybe.maybeToList :: Maybe a -> [a] --- imported via Prelude -Just :: a -> Maybe a -data Maybe a = Nothing | Just a -Nothing :: Maybe a -maybe :: b -> (a -> b) -> Maybe a -> b -</screen> - This output shows that, in the context of the current session (ie in the scope - of <literal>Prelude</literal>), the first group of items from - <literal>Data.Maybe</literal> are not in scope (althought they are available in - fully qualified form in the GHCi session - see <xref - linkend="ghci-scope"/>), whereas the second group of items are in scope - (via <literal>Prelude</literal>) and are therefore available either - unqualified, or with a <literal>Prelude.</literal> qualifier. - </para> - </listitem> - </itemizedlist> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:cd</literal> <replaceable>dir</replaceable> - <indexterm><primary><literal>:cd</literal></primary></indexterm> - </term> - <listitem> - <para>Changes the current working directory to - <replaceable>dir</replaceable>. A - ‘<literal>˜</literal>’ symbol at the - beginning of <replaceable>dir</replaceable> will be replaced - by the contents of the environment variable - <literal>HOME</literal>. - See also the <literal>:show paths</literal> command for - showing the current working directory.</para> - - <para>NOTE: changing directories causes all currently loaded - modules to be unloaded. This is because the search path is - usually expressed using relative directories, and changing - the search path in the middle of a session is not - supported.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:cmd</literal> <replaceable>expr</replaceable> - <indexterm><primary><literal>:cmd</literal></primary></indexterm> - </term> - <listitem> - <para>Executes <replaceable>expr</replaceable> as a computation of - type <literal>IO String</literal>, and then executes the resulting - string as a list of GHCi commands. Multiple commands are separated - by newlines. The <literal>:cmd</literal> command is useful with - <literal>:def</literal> and <literal>:set stop</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:complete</literal> <replaceable>type</replaceable> - <optional><replaceable>n</replaceable>-</optional><optional><replaceable>m</replaceable></optional> - <replaceable>string-literal</replaceable> - <indexterm><primary><literal>:complete</literal></primary></indexterm> - </term> - <listitem> - <para>This command allows to request command completions - from GHCi even when interacting over a pipe instead of a - proper terminal and is designed for integrating GHCi's - completion with text editors and IDEs.</para> - - <para>When called, <literal>:complete</literal> prints the - <replaceable>n</replaceable><superscript>th</superscript> to - <replaceable>m</replaceable><superscript>th</superscript> - completion candidates for the partial input - <replaceable>string-literal</replaceable> for the completion - domain denoted by - <replaceable>type</replaceable>. Currently, only the - <literal>repl</literal> domain is supported which denotes - the kind of completion that would be provided interactively - by GHCi at the input prompt.</para> - - <para>If omitted, <replaceable>n</replaceable> and - <replaceable>m</replaceable> default to the first or last - available completion candidate respectively. If there are - less candidates than requested via the range argument, - <replaceable>n</replaceable> and - <replaceable>m</replaceable> are implicitly capped to the - number of available completition candidates.</para> - - <para>The output of <literal>:complete</literal> begins with - a header line containing three space-delimited fields: - - <itemizedlist> - <listitem>An integer denoting the number - <replaceable>l</replaceable> of printed - completions,</listitem> - - <listitem>an integer denoting the total number of - completions available, and finally</listitem> - - <listitem>a string literal denoting a common - prefix to be added to the returned completion - candidates.</listitem> - </itemizedlist> - - The header line is followed by <replaceable>l</replaceable> - lines each containing one completion candidate encoded as - (quoted) string literal. Here are some example invocations - showing the various cases:</para> - -<screen> -Prelude> :complete repl 0 "" -0 470 "" -Prelude> :complete repl 5 "import For" -5 21 "import " -"Foreign" -"Foreign.C" -"Foreign.C.Error" -"Foreign.C.String" -"Foreign.C.Types" -Prelude> :complete repl 5-10 "import For" -6 21 "import " -"Foreign.C.Types" -"Foreign.Concurrent" -"Foreign.ForeignPtr" -"Foreign.ForeignPtr.Safe" -"Foreign.ForeignPtr.Unsafe" -"Foreign.Marshal" -Prelude> :complete repl 20- "import For" -2 21 "import " -"Foreign.StablePtr" -"Foreign.Storable" -Prelude> :complete repl "map" -3 3 "" -"map" -"mapM" -"mapM_" -Prelude> :complete repl 5-10 "map" -0 3 "" -</screen> - - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:continue</literal> - <indexterm><primary><literal>:continue</literal></primary></indexterm> - </term> - <listitem><para>Continue the current evaluation, when stopped at a - breakpoint.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:ctags</literal> <optional><replaceable>filename</replaceable></optional> - <literal>:etags</literal> <optional><replaceable>filename</replaceable></optional> - <indexterm><primary><literal>:etags</literal></primary> - </indexterm> - <indexterm><primary><literal>:etags</literal></primary> - </indexterm> - </term> - <listitem> - <para>Generates a “tags” file for Vi-style editors - (<literal>:ctags</literal>) or - Emacs-style editors (<literal>:etags</literal>). If - no filename is specified, the default <filename>tags</filename> or - <filename>TAGS</filename> is - used, respectively. Tags for all the functions, constructors and - types in the currently loaded modules are created. All modules must - be interpreted for these commands to work.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:def<optional>!</optional> <optional><replaceable>name</replaceable> <replaceable>expr</replaceable></optional></literal> - <indexterm><primary><literal>:def</literal></primary></indexterm> - </term> - <listitem> - <para><literal>:def</literal> is used to define new - commands, or macros, in GHCi. The command - <literal>:def</literal> <replaceable>name</replaceable> - <replaceable>expr</replaceable> defines a new GHCi command - <literal>:<replaceable>name</replaceable></literal>, - implemented by the Haskell expression - <replaceable>expr</replaceable>, which must have type - <literal>String -> IO String</literal>. When - <literal>:<replaceable>name</replaceable> - <replaceable>args</replaceable></literal> is typed at the - prompt, GHCi will run the expression - <literal>(<replaceable>name</replaceable> - <replaceable>args</replaceable>)</literal>, take the - resulting <literal>String</literal>, and feed it back into - GHCi as a new sequence of commands. Separate commands in - the result must be separated by - ‘<literal>\n</literal>’.</para> - - <para>That's all a little confusing, so here's a few - examples. To start with, here's a new GHCi command which - doesn't take any arguments or produce any results, it just - outputs the current date & time:</para> - -<screen> -Prelude> let date _ = Time.getClockTime >>= print >> return "" -Prelude> :def date date -Prelude> :date -Fri Mar 23 15:16:40 GMT 2001 -</screen> - - <para>Here's an example of a command that takes an argument. - It's a re-implementation of <literal>:cd</literal>:</para> - -<screen> -Prelude> let mycd d = Directory.setCurrentDirectory d >> return "" -Prelude> :def mycd mycd -Prelude> :mycd .. -</screen> - - <para>Or I could define a simple way to invoke - “<literal>ghc --make Main</literal>” in the - current directory:</para> - -<screen> -Prelude> :def make (\_ -> return ":! ghc --make Main") -</screen> - - <para>We can define a command that reads GHCi input from a - file. This might be useful for creating a set of bindings - that we want to repeatedly load into the GHCi session:</para> - -<screen> -Prelude> :def . readFile -Prelude> :. cmds.ghci -</screen> - - <para>Notice that we named the command - <literal>:.</literal>, by analogy with the - ‘<literal>.</literal>’ Unix shell command that - does the same thing.</para> - - <para>Typing <literal>:def</literal> on its own lists the - currently-defined macros. Attempting to redefine an - existing command name results in an error unless the - <literal>:def!</literal> form is used, in which case the old - command with that name is silently overwritten.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:delete * | <replaceable>num</replaceable> ...</literal> - <indexterm><primary><literal>:delete</literal></primary></indexterm> - </term> - <listitem> - <para>Delete one or more breakpoints by number (use <literal>:show - breaks</literal> to see the number of each breakpoint). The - <literal>*</literal> form deletes all the breakpoints.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:edit <optional><replaceable>file</replaceable></optional></literal> - <indexterm><primary><literal>:edit</literal></primary></indexterm> - </term> - <listitem> - <para>Opens an editor to edit the file - <replaceable>file</replaceable>, or the most recently loaded - module if <replaceable>file</replaceable> is omitted. - If there were errors during the last loading, - the cursor will be positioned at the line of the first error. The - editor to invoke is taken from the <literal>EDITOR</literal> - environment variable, or a default editor on your system if - <literal>EDITOR</literal> is not set. You can change the - editor using <literal>:set editor</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:etags</literal> - </term> - <listitem> - <para>See <literal>:ctags</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:force <replaceable>identifier</replaceable> ...</literal> - <indexterm><primary><literal>:force</literal></primary></indexterm> - </term> - <listitem> - <para>Prints the value of <replaceable>identifier</replaceable> in - the same way as <literal>:print</literal>. Unlike - <literal>:print</literal>, <literal>:force</literal> evaluates each - thunk that it encounters while traversing the value. This may - cause exceptions or infinite loops, or further breakpoints (which - are ignored, but displayed).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:forward <optional><replaceable>n</replaceable></optional></literal> - <indexterm><primary><literal>:forward</literal></primary></indexterm> - </term> - <listitem> - <para>Move forward <replaceable>n</replaceable> steps in the - history. <replaceable>n</replaceable> is one if omitted. - See <xref linkend="tracing" /> for more about GHCi's debugging - facilities. See also: - <literal>:trace</literal>, <literal>:history</literal>, - <literal>:back</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:help</literal> - <indexterm><primary><literal>:help</literal></primary></indexterm> - </term> - <term> - <literal>:?</literal> - <indexterm><primary><literal>:?</literal></primary></indexterm> - </term> - <listitem> - <para>Displays a list of the available commands.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:</literal> - <indexterm><primary><literal>:</literal></primary></indexterm> - </term> - <listitem> - <para>Repeat the previous command.</para> - </listitem> - </varlistentry> - - <varlistentry> - - <term> - <literal>:history [<replaceable>num</replaceable>]</literal> - <indexterm><primary><literal>:history</literal></primary></indexterm> - </term> - <listitem> - <para>Display the history of evaluation steps. With a - number, displays that many steps (default: 20). For use - with <literal>:trace</literal>; see <xref linkend="tracing" - />. To set the number of history entries stored by GHCi, - use - <option>-fghci-hist-size=<replaceable>n</replaceable></option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:info</literal><optional><literal>!</literal></optional><replaceable>name</replaceable> ... - <indexterm><primary><literal>:info</literal></primary></indexterm> - </term> - <listitem> - <para>Displays information about the given name(s). For - example, if <replaceable>name</replaceable> is a class, then - the class methods and their types will be printed; if - <replaceable>name</replaceable> is a type constructor, then - its definition will be printed; if - <replaceable>name</replaceable> is a function, then its type - will be printed. If <replaceable>name</replaceable> has - been loaded from a source file, then GHCi will also display - the location of its definition in the source.</para> - <para>For types and classes, GHCi also summarises instances that - mention them. To avoid showing irrelevant information, an instance - is shown only if (a) its head mentions <replaceable>name</replaceable>, - and (b) all the other things mentioned in the instance - are in scope (either qualified or otherwise) as a result of - a <literal>:load</literal> or <literal>:module</literal> commands. </para> - <para> - The command <literal>:info!</literal> works in a similar fashion - but it removes restriction (b), showing all instances that are in - scope and mention <replaceable>name</replaceable> in their head. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:issafe</literal><optional><replaceable>module</replaceable></optional> - <indexterm><primary><literal>:issafe</literal></primary></indexterm> - </term> - <listitem> - <para>Displays Safe Haskell information about the given - module (or the current module if omitted). This includes the trust - type of the module and its containing package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:kind</literal><optional><literal>!</literal></optional> - <replaceable>type</replaceable> - <indexterm><primary><literal>:kind</literal></primary></indexterm> - </term> - <listitem> - <para>Infers and prints the kind of - <replaceable>type</replaceable>. The latter can be an arbitrary - type expression, including a partial application of a type constructor, - such as <literal>Either Int</literal>. In fact, <literal>:kind</literal> - even allows you to write a partial application of a type synonym (usually disallowed), - so that this works: -<programlisting> -ghci> type T a b = (a,b,a) -ghci> :k T Int Bool -T Int Bool :: * -ghci> :k T -T :: * -> * -> * -ghci> :k T Int -T Int :: * -> * -</programlisting> - </para> - <para> - If you specify the - optional "<literal>!</literal>", GHC will in addition normalise the type - by expanding out type synonyms and evaluating type-function applications, - and display the normalised result.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:list</literal> <replaceable>identifier</replaceable> - <indexterm><primary><literal>:list</literal></primary></indexterm> - </term> - <listitem> - <para>Lists the source code around the definition of - <replaceable>identifier</replaceable> or the current - breakpoint if not given. This requires that the identifier be - defined in an interpreted module. If your output device - supports it, then GHCi will highlight the active - subexpression in bold.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:list</literal> <optional><replaceable>module</replaceable></optional> <replaceable>line</replaceable> - <indexterm><primary><literal>:list</literal></primary></indexterm> - </term> - <listitem> - <para>Lists the source code around the given line number of - <replaceable>module</replaceable>. This requires that the module be - interpreted. If your output device supports it, then GHCi will - highlight the active subexpression in bold.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:load</literal><optional><literal>!</literal></optional> <optional><literal>*</literal></optional><replaceable>module</replaceable> ... - <indexterm><primary><literal>:load</literal></primary></indexterm> - </term> - <listitem> - <para>Recursively loads the specified - <replaceable>module</replaceable>s, and all the modules they - depend on. Here, each <replaceable>module</replaceable> - must be a module name or filename, but may not be the name - of a module in a package.</para> - - <para>All previously loaded modules, except package modules, - are forgotten. The new set of modules is known as the - <firstterm>target set</firstterm>. Note that - <literal>:load</literal> can be used without any arguments - to unload all the currently loaded modules and - bindings.</para> - - <para>Normally pre-compiled code for a module will be loaded - if available, or otherwise the module will be compiled to - byte-code. Using the <literal>*</literal> prefix forces a - module to be loaded as byte-code.</para> - - <para>Adding the optional "<literal>!</literal>" turns type - errors into warnings while loading. This allows to use the - portions of the module that are correct, even if there are - type errors in some definitions. Effectively, the - "-fdefer-type-errors" flag is set before loading and unset - after loading if the flag has not already been set - before. See <xref linkend="defer-type-errors" /> for further - motivation and details.</para> - - <para>After a <literal>:load</literal> command, the current - context is set to:</para> - - <itemizedlist> - <listitem> - <para><replaceable>module</replaceable>, if it was loaded - successfully, or</para> - </listitem> - <listitem> - <para>the most recently successfully loaded module, if - any other modules were loaded as a result of the current - <literal>:load</literal>, or</para> - </listitem> - <listitem> - <para><literal>Prelude</literal> otherwise.</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:main <replaceable>arg<subscript>1</subscript></replaceable> ... <replaceable>arg<subscript>n</subscript></replaceable></literal> - <indexterm><primary><literal>:main</literal></primary></indexterm> - </term> - <listitem> - <para> - When a program is compiled and executed, it can use the - <literal>getArgs</literal> function to access the - command-line arguments. - However, we cannot simply pass the arguments to the - <literal>main</literal> function while we are testing in ghci, - as the <literal>main</literal> function doesn't take its - arguments directly. - </para> - - <para> - Instead, we can use the <literal>:main</literal> command. - This runs whatever <literal>main</literal> is in scope, with - any arguments being treated the same as command-line arguments, - e.g.: - </para> - -<screen> -Prelude> let main = System.Environment.getArgs >>= print -Prelude> :main foo bar -["foo","bar"] -</screen> - - <para> - We can also quote arguments which contains characters like - spaces, and they are treated like Haskell strings, or we can - just use Haskell list syntax: - </para> - -<screen> -Prelude> :main foo "bar baz" -["foo","bar baz"] -Prelude> :main ["foo", "bar baz"] -["foo","bar baz"] -</screen> - - <para> - Finally, other functions can be called, either with the - <literal>-main-is</literal> flag or the <literal>:run</literal> - command: - </para> - -<screen> -Prelude> let foo = putStrLn "foo" >> System.Environment.getArgs >>= print -Prelude> let bar = putStrLn "bar" >> System.Environment.getArgs >>= print -Prelude> :set -main-is foo -Prelude> :main foo "bar baz" -foo -["foo","bar baz"] -Prelude> :run bar ["foo", "bar baz"] -bar -["foo","bar baz"] -</screen> - - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:module <optional>+|-</optional> <optional>*</optional><replaceable>mod<subscript>1</subscript></replaceable> ... <optional>*</optional><replaceable>mod<subscript>n</subscript></replaceable></literal> - <indexterm><primary><literal>:module</literal></primary></indexterm> - </term> - <term> - <literal>import <replaceable>mod</replaceable></literal> - </term> - <listitem> - <para>Sets or modifies the current context for statements - typed at the prompt. The form <literal>import - <replaceable>mod</replaceable></literal> is equivalent to - <literal>:module +<replaceable>mod</replaceable></literal>. - See <xref linkend="ghci-scope"/> for - more details.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:print </literal> <replaceable>names</replaceable> ... - <indexterm><primary><literal>:print</literal></primary></indexterm> - </term> - <listitem> - <para>Prints a value without forcing its evaluation. - <literal>:print</literal> may be used on values whose types are - unknown or partially known, which might be the case for local - variables with polymorphic types at a breakpoint. While inspecting - the runtime value, <literal>:print</literal> attempts to - reconstruct the type of the value, and will elaborate the type in - GHCi's environment if possible. If any unevaluated components - (thunks) are encountered, then <literal>:print</literal> binds - a fresh variable with a name beginning with <literal>_t</literal> - to each thunk. See <xref linkend="breakpoints" /> for more - information. See also the <literal>:sprint</literal> command, - which works like <literal>:print</literal> but does not bind new - variables.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:quit</literal> - <indexterm><primary><literal>:quit</literal></primary></indexterm> - </term> - <listitem> - <para>Quits GHCi. You can also quit by typing control-D - at the prompt.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:reload</literal><optional><literal>!</literal></optional> - <indexterm><primary><literal>:reload</literal></primary></indexterm> - </term> - <listitem> - <para>Attempts to reload the current target set (see - <literal>:load</literal>) if any of the modules in the set, - or any dependent module, has changed. Note that this may - entail loading new modules, or dropping modules which are no - longer indirectly required by the target.</para> - - <para>Adding the optional "<literal>!</literal>" turns type - errors into warnings while loading. This allows to use the - portions of the module that are correct, even if there are - type errors in some definitions. Effectively, the - "-fdefer-type-errors" flag is set before loading and unset - after loading if the flag has not already been set - before. See <xref linkend="defer-type-errors" /> for further - motivation and details.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:run</literal> - <indexterm><primary><literal>:run</literal></primary></indexterm> - </term> - <listitem> - <para>See <literal>:main</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:script</literal> <optional><replaceable>n</replaceable></optional> - <literal>filename</literal> - <indexterm><primary><literal>:script</literal></primary></indexterm> - </term> - <listitem> - <para>Executes the lines of a file as a series of GHCi commands. This command - is compatible with multiline statements as set by <literal>:set +m</literal> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:set</literal> <optional><replaceable>option</replaceable>...</optional> - <indexterm><primary><literal>:set</literal></primary></indexterm> - </term> - <listitem> - <para>Sets various options. See <xref linkend="ghci-set"/> for a list of - available options and <xref linkend="interactive-mode-options"/> for a - list of GHCi-specific flags. The <literal>:set</literal> command by - itself shows which options are currently set. It also lists the current - dynamic flag settings, with GHCi-specific flags listed separately.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:set</literal> <literal>args</literal> <replaceable>arg</replaceable> ... - <indexterm><primary><literal>:set args</literal></primary></indexterm> - </term> - <listitem> - <para>Sets the list of arguments which are returned when the - program calls <literal>System.getArgs</literal><indexterm><primary>getArgs</primary> - </indexterm>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:set</literal> <literal>editor</literal> <replaceable>cmd</replaceable> - </term> - <listitem> - <para>Sets the command used by <literal>:edit</literal> to - <replaceable>cmd</replaceable>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:set</literal> <literal>prog</literal> <replaceable>prog</replaceable> - <indexterm><primary><literal>:set prog</literal></primary></indexterm> - </term> - <listitem> - <para>Sets the string to be returned when the program calls - <literal>System.getProgName</literal><indexterm><primary>getProgName</primary> - </indexterm>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:set</literal> <literal>prompt</literal> <replaceable>prompt</replaceable> - </term> - <listitem> - <para>Sets the string to be used as the prompt in GHCi. - Inside <replaceable>prompt</replaceable>, the sequence - <literal>%s</literal> is replaced by the names of the - modules currently in scope, <literal>%l</literal> is replaced - by the line number (as referenced in compiler messages) of the - current prompt, and <literal>%%</literal> is replaced by - <literal>%</literal>. If <replaceable>prompt</replaceable> - starts with " then it is parsed as a Haskell String; - otherwise it is treated as a literal string.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:set</literal> <literal>prompt2</literal> <replaceable>prompt</replaceable> - </term> - <listitem> - <para>Sets the string to be used as the continuation prompt - (used when using the <literal>:{</literal> command) in GHCi.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:set</literal> <literal>stop</literal> - [<replaceable>num</replaceable>] <replaceable>cmd</replaceable> - </term> - <listitem> - <para>Set a command to be executed when a breakpoint is hit, or a new - item in the history is selected. The most common use of - <literal>:set stop</literal> is to display the source code at the - current location, e.g. <literal>:set stop :list</literal>.</para> - - <para>If a number is given before the command, then the commands are - run when the specified breakpoint (only) is hit. This can be quite - useful: for example, <literal>:set stop 1 :continue</literal> - effectively disables breakpoint 1, by running - <literal>:continue</literal> whenever it is hit (although GHCi will - still emit a message to say the breakpoint was hit). What's more, - with cunning use of <literal>:def</literal> and - <literal>:cmd</literal> you can use <literal>:set stop</literal> to - implement conditional breakpoints:</para> -<screen> -*Main> :def cond \expr -> return (":cmd if (" ++ expr ++ ") then return \"\" else return \":continue\"") -*Main> :set stop 0 :cond (x < 3) -</screen> - <para>Ignoring breakpoints for a specified number of iterations is - also possible using similar techniques.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:seti</literal> <optional><replaceable>option</replaceable>...</optional> - <indexterm><primary><literal>:seti</literal></primary></indexterm> - </term> - <listitem> - <para> - Like <literal>:set</literal>, but options set with - <literal>:seti</literal> affect only expressions and - commands typed at the prompt, and not modules loaded with - <literal>:load</literal> (in contrast, options set with - <literal>:set</literal> apply everywhere). See <xref - linkend="ghci-interactive-options" />. - </para> - <para> - Without any arguments, displays the current set of options - that are applied to expressions and commands typed at the - prompt. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:show bindings</literal> - <indexterm><primary><literal>:show bindings</literal></primary></indexterm> - </term> - <listitem> - <para>Show the bindings made at the prompt and their - types.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:show breaks</literal> - <indexterm><primary><literal>:show breaks</literal></primary></indexterm> - </term> - <listitem> - <para>List the active breakpoints.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:show context</literal> - <indexterm><primary><literal>:show context</literal></primary></indexterm> - </term> - <listitem> - <para>List the active evaluations that are stopped at breakpoints.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:show imports</literal> - <indexterm><primary><literal>:show imports</literal></primary></indexterm> - </term> - <listitem> - <para>Show the imports that are currently in force, as - created by <literal>import</literal> and - <literal>:module</literal> commands.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:show modules</literal> - <indexterm><primary><literal>:show modules</literal></primary></indexterm> - </term> - <listitem> - <para>Show the list of modules currently loaded.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:show packages</literal> - <indexterm><primary><literal>:show packages</literal></primary></indexterm> - </term> - <listitem> - <para>Show the currently active package flags, as well as the list of - packages currently loaded.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:show paths</literal> - <indexterm><primary><literal>:show paths</literal></primary></indexterm> - </term> - <listitem> - <para>Show the current working directory (as set via - <literal>:cd</literal> command), as well as the list of - directories searched for source files (as set by the - <option>-i</option> option).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:show language</literal> - <indexterm><primary><literal>:show language</literal></primary></indexterm> - </term> - <listitem> - <para>Show the currently active language flags for source files.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:showi language</literal> - <indexterm><primary><literal>:showi language</literal></primary></indexterm> - </term> - <listitem> - <para>Show the currently active language flags for - expressions typed at the prompt (see also <literal>:seti</literal>).</para> - </listitem> - </varlistentry> - - - <varlistentry> - <term> - <literal>:show [args|prog|prompt|editor|stop]</literal> - <indexterm><primary><literal>:show</literal></primary></indexterm> - </term> - <listitem> - <para>Displays the specified setting (see - <literal>:set</literal>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:sprint</literal> - <indexterm><primary><literal>:sprint</literal></primary></indexterm> - </term> - <listitem> - <para>Prints a value without forcing its evaluation. - <literal>:sprint</literal> is similar to <literal>:print</literal>, - with the difference that unevaluated subterms are not bound to new - variables, they are simply denoted by ‘_’.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:step</literal> <optional><replaceable>expr</replaceable></optional> - <indexterm><primary><literal>:step</literal></primary></indexterm> - </term> - <listitem> - <para>Enable all breakpoints and begin evaluating an - expression in single-stepping mode. In this - mode evaluation will be stopped after every reduction, - allowing local variables to be inspected. - - If <replaceable>expr</replaceable> is not given, evaluation will - resume at the last breakpoint. - - See <xref linkend="single-stepping" />.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:steplocal</literal> - <indexterm><primary><literal>:steplocal</literal></primary></indexterm> - </term> - <listitem> - <para>Enable only breakpoints in the current top-level - binding and resume evaluation at the last breakpoint.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:stepmodule</literal> - <indexterm><primary><literal>:stepmodule</literal></primary></indexterm> - </term> - <listitem> - <para>Enable only breakpoints in the current module and - resume evaluation at the last breakpoint.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:trace <optional><replaceable>expr</replaceable></optional></literal> - <indexterm><primary><literal>:trace</literal></primary></indexterm> - </term> - <listitem> - <para>Evaluates the given expression (or from the last breakpoint if - no expression is given), and additionally logs the evaluation - steps for later inspection using <literal>:history</literal>. See - <xref linkend="tracing" />.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:type</literal> <replaceable>expression</replaceable> - <indexterm><primary><literal>:type</literal></primary></indexterm> - </term> - <listitem> - <para>Infers and prints the type of - <replaceable>expression</replaceable>, including explicit - forall quantifiers for polymorphic types. The monomorphism - restriction is <emphasis>not</emphasis> applied to the - expression during type inference.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:undef</literal> <replaceable>name</replaceable> - <indexterm><primary><literal>:undef</literal></primary></indexterm> - </term> - <listitem> - <para>Undefines the user-defined command - <replaceable>name</replaceable> (see <literal>:def</literal> - above).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:unset</literal> <replaceable>option</replaceable>... - <indexterm><primary><literal>:unset</literal></primary></indexterm> - </term> - <listitem> - <para>Unsets certain options. See <xref linkend="ghci-set"/> - for a list of available options.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:!</literal> <replaceable>command</replaceable>... - <indexterm><primary><literal>:!</literal></primary></indexterm> - <indexterm><primary>shell commands</primary><secondary>in GHCi</secondary></indexterm> - </term> - <listitem> - <para>Executes the shell command - <replaceable>command</replaceable>.</para> - </listitem> - </varlistentry> - - </variablelist> - </sect1> - - <sect1 id="ghci-set"> - <title>The <literal>:set</literal> and <literal>:seti</literal> commands</title> - <indexterm><primary><literal>:set</literal></primary></indexterm> - <indexterm><primary><literal>:seti</literal></primary></indexterm> - - <para>The <literal>:set</literal> command sets two types of - options: GHCi options, which begin with - ‘<literal>+</literal>’, and “command-line” - options, which begin with ‘-’. </para> - - <para>NOTE: at the moment, the <literal>:set</literal> command - doesn't support any kind of quoting in its arguments: quotes will - not be removed and cannot be used to group words together. For - example, <literal>:set -DFOO='BAR BAZ'</literal> will not do what - you expect.</para> - - <sect2> - <title>GHCi options</title> - <indexterm><primary>options</primary><secondary>GHCi</secondary> - </indexterm> - - <para>GHCi options may be set using <literal>:set</literal> and - unset using <literal>:unset</literal>.</para> - - <para>The available GHCi options are:</para> - - <variablelist> - <varlistentry> - <term> - <literal>+m</literal> - <indexterm><primary><literal>+m</literal></primary></indexterm> - </term> - <listitem> - <para>Enable parsing of multiline commands. A multiline command - is prompted for when the current input line contains open layout - contexts (see <xref linkend="ghci-multiline" />).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>+r</literal> - <indexterm><primary><literal>+r</literal></primary></indexterm> - <indexterm><primary>CAFs</primary><secondary>in GHCi</secondary></indexterm> - <indexterm><primary>Constant Applicative Form</primary><see>CAFs</see></indexterm> - </term> - <listitem> - <para>Normally, any evaluation of top-level expressions - (otherwise known as CAFs or Constant Applicative Forms) in - loaded modules is retained between evaluations. Turning - on <literal>+r</literal> causes all evaluation of - top-level expressions to be discarded after each - evaluation (they are still retained - <emphasis>during</emphasis> a single evaluation).</para> - - <para>This option may help if the evaluated top-level - expressions are consuming large amounts of space, or if - you need repeatable performance measurements.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>+s</literal> - <indexterm><primary><literal>+s</literal></primary></indexterm> - </term> - <listitem> - <para>Display some stats after evaluating each expression, - including the elapsed time and number of bytes allocated. - NOTE: the allocation figure is only accurate to the size - of the storage manager's allocation area, because it is - calculated at every GC. Hence, you might see values of - zero if no GC has occurred.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>+t</literal> - <indexterm><primary><literal>+t</literal></primary></indexterm> - </term> - <listitem> - <para>Display the type of each variable bound after a - statement is entered at the prompt. If the statement is a - single expression, then the only variable binding will be - for the variable - ‘<literal>it</literal>’.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="ghci-cmd-line-options"> - <title>Setting GHC command-line options in GHCi</title> - - <para>Normal GHC command-line options may also be set using - <literal>:set</literal>. For example, to turn on - <option>-fwarn-missing-signatures</option>, you would say:</para> - -<screen> -Prelude> :set -fwarn-missing-signatures -</screen> - - <para>Any GHC command-line option that is designated as - <firstterm>dynamic</firstterm> (see the table in <xref - linkend="flag-reference"/>), may be set using - <literal>:set</literal>. To unset an option, you can set the - reverse option:</para> - <indexterm><primary>dynamic</primary><secondary>options</secondary></indexterm> - -<screen> -Prelude> :set -fno-warn-incomplete-patterns -XNoMultiParamTypeClasses -</screen> - - <para><xref linkend="flag-reference"/> lists the reverse for each - option where applicable.</para> - - <para>Certain static options (<option>-package</option>, - <option>-I</option>, <option>-i</option>, and - <option>-l</option> in particular) will also work, but some may - not take effect until the next reload.</para> - <indexterm><primary>static</primary><secondary>options</secondary></indexterm> - </sect2> - - <sect2 id="ghci-interactive-options"> - <title>Setting options for interactive evaluation only</title> - - <para> - GHCi actually maintains <emphasis>two</emphasis> sets of options: -<itemizedlist> -<listitem><para> - The <emphasis>loading options</emphasis> apply when loading modules -</para></listitem> -<listitem><para> - The <emphasis>interactive options</emphasis> apply when evaluating expressions and commands typed at the GHCi prompt. -</para></listitem> -</itemizedlist> -The <literal>:set</literal> command modifies both, but there is - also a <literal>:seti</literal> command (for "set - interactive") that affects only the interactive options set. - </para> - - <para> - It is often useful to change the interactive options, - without having that option apply to loaded modules - too. For example -<screen> -:seti -XMonoLocalBinds -</screen> - It would be undesirable if <option>-XMonoLocalBinds</option> were to - apply to loaded modules too: that might cause a compilation error, but - more commonly it will cause extra recompilation, because GHC will think - that it needs to recompile the module because the flags have changed. - </para> - - <para> - If you are setting language options in your <literal>.ghci</literal> file, it is good practice - to use <literal>:seti</literal> rather than <literal>:set</literal>, - unless you really do want them to apply to all modules you - load in GHCi. - </para> - - <para> - The two sets of options can be inspected using the - <literal>:set</literal> and <literal>:seti</literal> commands - respectively, with no arguments. For example, in a clean GHCi - session we might see something like this: -<screen> -Prelude> :seti -base language is: Haskell2010 -with the following modifiers: - -XNoMonomorphismRestriction - -XNoDatatypeContexts - -XNondecreasingIndentation - -XExtendedDefaultRules -GHCi-specific dynamic flag settings: -other dynamic, non-language, flag settings: - -fimplicit-import-qualified -warning settings: -</screen> - </para> -<para> -The two sets of options are initialised as follows. First, both sets of options -are initialised as described in <xref linkend="ghci-dot-files"/>. -Then the interactive options are modified as follows: -<itemizedlist> -<listitem><para> - The option <option>-XExtendedDefaultRules</option> - is enabled, in order to apply special defaulting rules to - expressions typed at the prompt (see <xref - linkend="extended-default-rules" />). - </para></listitem> - -<listitem> <para> - The Monomorphism Restriction is disabled (see <xref linkend="monomorphism" />). - </para></listitem> -</itemizedlist> -</para> - </sect2> - </sect1> - - <sect1 id="ghci-dot-files"> - <title>The <filename>.ghci</filename> and <filename>.haskeline</filename> files</title> - - <sect2 id="dot-ghci-files"> - <title>The <filename>.ghci</filename> files</title> - - <indexterm><primary><filename>.ghci</filename></primary><secondary>file</secondary> - </indexterm> - <indexterm><primary>startup</primary><secondary>files, GHCi</secondary> - </indexterm> - - <para>When it starts, unless the <literal>-ignore-dot-ghci</literal> - flag is given, GHCi reads and executes commands from the following - files, in this order, if they exist:</para> - - <orderedlist> - <listitem> - <para><filename>./.ghci</filename></para> - </listitem> - <listitem> - <para><literal><replaceable>appdata</replaceable>/ghc/ghci.conf</literal>, - where <replaceable>appdata</replaceable> depends on your system, - but is usually something like <literal>C:/Documents and Settings/<replaceable>user</replaceable>/Application Data</literal></para> - </listitem> - <listitem> - <para>On Unix: <literal>$HOME/.ghc/ghci.conf</literal></para> - </listitem> - <listitem> - <para><literal>$HOME/.ghci</literal></para> - </listitem> - </orderedlist> - - <para>The <filename>ghci.conf</filename> file is most useful for - turning on favourite options (eg. <literal>:set +s</literal>), and - defining useful macros. Note: when setting language options in - this file it is usually desirable to use <literal>:seti</literal> - rather than <literal>:set</literal> (see <xref - linkend="ghci-interactive-options" />). - </para> - - <para> - Placing a <filename>.ghci</filename> file - in a directory with a Haskell project is a useful way to set - certain project-wide options so you don't have to type them - every time you start GHCi: eg. if your project uses multi-parameter - type classes, scoped type variables, - and CPP, and has source files in three subdirectories A, B and C, - you might put the following lines in - <filename>.ghci</filename>:</para> - -<screen> -:set -XMultiParamTypeClasses -XScopedTypeVariables -cpp -:set -iA:B:C -</screen> - - <para>(Note that strictly speaking the <option>-i</option> flag is - a static one, but in fact it works to set it using - <literal>:set</literal> like this. The changes won't take effect - until the next <literal>:load</literal>, though.)</para> - - <para>Once you have a library of GHCi macros, you may want - to source them from separate files, or you may want to source - your <filename>.ghci</filename> file into your running GHCi - session while debugging it</para> - -<screen> -:def source readFile -</screen> - - <para>With this macro defined in your <filename>.ghci</filename> - file, you can use <literal>:source file</literal> to read GHCi - commands from <literal>file</literal>. You can find (and contribute!-) - other suggestions for <filename>.ghci</filename> files on this Haskell - wiki page: <ulink - url="http://haskell.org/haskellwiki/GHC/GHCi">GHC/GHCi</ulink></para> - - <para>Additionally, any files specified with - <literal>-ghci-script</literal> flags will be read after the - standard files, allowing the use of custom .ghci files.</para> - - <para>Two command-line options control whether the - startup files files are read:</para> - - <variablelist> - <varlistentry> - <term> - <option>-ignore-dot-ghci</option> - <indexterm><primary><option>-ignore-dot-ghci</option></primary></indexterm> - </term> - <listitem> - <para>Don't read either <filename>./.ghci</filename> or the - other startup files when starting up.</para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>-ghci-script</option> - <indexterm><primary><option>-ghci-script</option></primary></indexterm> - </term> - <listitem> - <para>Read a specific file after the usual startup files. - Maybe be specified repeatedly for multiple inputs.</para> - </listitem> - </varlistentry> - </variablelist> - - <para> - When defining GHCi macros, there is some important behavior you - should be aware of when names may conflict with built-in - commands, especially regarding tab completion. - </para> - <para> - For example, consider if you had a macro named - <literal>:time</literal> and in the shell, typed <literal>:t - 3</literal> - what should happen? The current algorithm we use - for completing commands is: - - <orderedlist> - <listitem> - <para>First, look up an exact match on the name from the defined macros.</para> - </listitem> - <listitem> - <para>Look for the exact match on the name in the built-in command list.</para> - </listitem> - <listitem> - <para>Do a prefix lookup on the list of built-in commands - - if a built-in command matches, but a macro is defined with - the same name as the built-in defined, pick the - macro.</para> - </listitem> - <listitem> - <para>Do a prefix lookup on the list of built-in commands.</para> - </listitem> - <listitem> - <para>Do a prefix lookup on the list of defined macros.</para> - </listitem> - </orderedlist> - </para> - - <para> - Here are some examples: - - <orderedlist> - <listitem> - <para>You have a macro <literal>:time</literal> and enter <literal>:t 3</literal></para> - <para>You get <literal>:type 3</literal></para> - </listitem> - - <listitem> - <para>You have a macro <literal>:type</literal> and enter <literal>:t 3</literal></para> - <para>You get <literal>:type 3</literal> with your defined macro, not the builtin.</para> - </listitem> - - <listitem> - <para>You have a macro <literal>:time</literal> and a macro - <literal>:type</literal>, and enter <literal>:t - 3</literal></para> - <para>You get <literal>:type 3</literal> with your defined macro.</para> - </listitem> - </orderedlist> - </para> - </sect2> - - <sect2 id="dot-haskeline-file"> - <title>The <filename>.haskeline</filename> file</title> - - <indexterm><primary><filename>.haskeline</filename></primary><secondary>file</secondary> - </indexterm> - <indexterm><primary>startup</primary><secondary>files, GHCi</secondary> - </indexterm> - - GHCi uses <ulink url="https://hackage.haskell.org/package/haskeline">Haskeline</ulink> - under the hood. You can configure it to, among other things, prune - duplicates from ghci history. See: - <ulink url="http://trac.haskell.org/haskeline/wiki/UserPrefs">Haskeline user preferences</ulink>. - </sect2> - </sect1> - - <sect1 id="ghci-obj"> - <title>Compiling to object code inside GHCi</title> - - <para>By default, GHCi compiles Haskell source code into byte-code - that is interpreted by the runtime system. GHCi can also compile - Haskell code to object code: to turn on this feature, use the - <option>-fobject-code</option> flag either on the command line or - with <literal>:set</literal> (the option - <option>-fbyte-code</option> restores byte-code compilation - again). Compiling to object code takes longer, but typically the - code will execute 10-20 times faster than byte-code.</para> - - <para>Compiling to object code inside GHCi is particularly useful - if you are developing a compiled application, because the - <literal>:reload</literal> command typically runs much faster than - restarting GHC with <option>--make</option> from the command-line, - because all the interface files are already cached in - memory.</para> - - <para>There are disadvantages to compiling to object-code: you - can't set breakpoints in object-code modules, for example. Only - the exports of an object-code module will be visible in GHCi, - rather than all top-level bindings as in interpreted - modules.</para> - </sect1> - - <sect1 id="ghci-faq"> - <title>FAQ and Things To Watch Out For</title> - - <variablelist> - <varlistentry> - <term>The interpreter can't load modules with foreign export - declarations!</term> - <listitem> - <para>Unfortunately not. We haven't implemented it yet. - Please compile any offending modules by hand before loading - them into GHCi.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>-O</literal> doesn't work with GHCi! - <indexterm><primary><option>-O</option></primary></indexterm> - </term> - <listitem> - <para>For technical reasons, the bytecode compiler doesn't - interact well with one of the optimisation passes, so we - have disabled optimisation when using the interpreter. This - isn't a great loss: you'll get a much bigger win by - compiling the bits of your code that need to go fast, rather - than interpreting them with optimisation turned on.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Unboxed tuples don't work with GHCi</term> - <listitem> - <para>That's right. You can always compile a module that - uses unboxed tuples and load it into GHCi, however. - (Incidentally the previous point, namely that - <literal>-O</literal> is incompatible with GHCi, is because - the bytecode compiler can't deal with unboxed - tuples).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Concurrent threads don't carry on running when GHCi is - waiting for input.</term> - <listitem> - <para>This should work, as long as your GHCi was built with - the <option>-threaded</option> switch, which is the default. - Consult whoever supplied your GHCi installation.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>After using <literal>getContents</literal>, I can't use - <literal>stdin</literal> again until I do - <literal>:load</literal> or <literal>:reload</literal>.</term> - - <listitem> - <para>This is the defined behaviour of - <literal>getContents</literal>: it puts the stdin Handle in - a state known as <firstterm>semi-closed</firstterm>, wherein - any further I/O operations on it are forbidden. Because I/O - state is retained between computations, the semi-closed - state persists until the next <literal>:load</literal> or - <literal>:reload</literal> command.</para> - - <para>You can make <literal>stdin</literal> reset itself - after every evaluation by giving GHCi the command - <literal>:set +r</literal>. This works because - <literal>stdin</literal> is just a top-level expression that - can be reverted to its unevaluated state in the same way as - any other top-level expression (CAF).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>I can't use Control-C to interrupt computations in - GHCi on Windows.</term> - <listitem> - <para>See <xref linkend="ghci-windows"/>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>The default buffering mode is different in GHCi to GHC.</term> - <listitem> - <para> - In GHC, the stdout handle is line-buffered by default. - However, in GHCi we turn off the buffering on stdout, - because this is normally what you want in an interpreter: - output appears as it is generated. - </para> - <para> - If you want line-buffered behaviour, as in GHC, you can - start your program thus: - <programlisting> - main = do { hSetBuffering stdout LineBuffering; ... } - </programlisting> - </para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - -</chapter> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") *** - ;;; End: *** - --> diff --git a/docs/users_guide/glasgow_exts.rst b/docs/users_guide/glasgow_exts.rst new file mode 100644 index 0000000000..e2dd28e9f7 --- /dev/null +++ b/docs/users_guide/glasgow_exts.rst @@ -0,0 +1,12326 @@ +.. index:: + single: language, GHC extensions + +As with all known Haskell systems, GHC implements some extensions to the +standard Haskell language. They can all be enabled or disabled by command line +flags or language pragmas. By default GHC understands the most recent Haskell +version it supports, plus a handful of extensions. + +Some of the Glasgow extensions serve to give you access to the +underlying facilities with which we implement Haskell. Thus, you can get +at the Raw Iron, if you are willing to write some non-portable code at a +more primitive level. You need not be “stuck” on performance because of +the implementation costs of Haskell's "high-level" features—you can +always code "under" them. In an extreme case, you can write all your +time-critical code in C, and then just glue it together with Haskell! + +Before you get too carried away working at the lowest level (e.g., +sloshing ``MutableByteArray#``\ s around your program), you may wish to +check if there are libraries that provide a "Haskellised veneer" over +the features you want. The separate +`libraries documentation <../libraries/index.html>`__ describes all the +libraries that come with GHC. + +.. _options-language: + +Language options +================ + +.. index:: + single: language; option + single: options; language + single: extensions; options controlling + +The language option flags control what variation of the language are +permitted. + +Language options can be controlled in two ways: + +- Every language option can switched on by a command-line flag + "``-X...``" (e.g. ``-XTemplateHaskell``), and switched off by the + flag "``-XNo...``"; (e.g. ``-XNoTemplateHaskell``). + +- Language options recognised by Cabal can also be enabled using the + ``LANGUAGE`` pragma, thus ``{-# LANGUAGE TemplateHaskell #-}`` (see + :ref:`language-pragma`). + + +The flag ``-fglasgow-exts`` ``-fglasgow-exts`` is equivalent to enabling +the following extensions: + +.. include:: what_glasgow_exts_does.gen.rst + +Enabling these +options is the *only* effect of ``-fglasgow-exts``. We are trying to +move away from this portmanteau flag, and towards enabling features +individually. + +.. _primitives: + +Unboxed types and primitive operations +====================================== + +GHC is built on a raft of primitive data types and operations; +"primitive" in the sense that they cannot be defined in Haskell itself. +While you really can use this stuff to write fast code, we generally +find it a lot less painful, and more satisfying in the long run, to use +higher-level language features and libraries. With any luck, the code +you write will be optimised to the efficient unboxed version in any +case. And if it isn't, we'd like to know about it. + +All these primitive data types and operations are exported by the +library ``GHC.Prim``, for which there is +:ghc-prim-ref:`detailed online documentation <GHC-Prim.html>`. (This +documentation is generated from the file ``compiler/prelude/primops.txt.pp``.) + +If you want to mention any of the primitive data types or operations in +your program, you must first import ``GHC.Prim`` to bring them into +scope. Many of them have names ending in ``#``, and to mention such names +you need the ``-XMagicHash`` extension (:ref:`magic-hash`). + +The primops make extensive use of `unboxed types <#glasgow-unboxed>`__ +and `unboxed tuples <#unboxed-tuples>`__, which we briefly summarise +here. + +.. _glasgow-unboxed: + +Unboxed types +------------- + +Unboxed types (Glasgow extension) + +Most types in GHC are boxed, which means that values of that type are +represented by a pointer to a heap object. The representation of a +Haskell ``Int``, for example, is a two-word heap object. An unboxed +type, however, is represented by the value itself, no pointers or heap +allocation are involved. + +Unboxed types correspond to the “raw machine” types you would use in C: +``Int#`` (long int), ``Double#`` (double), ``Addr#`` (void \*), etc. The +*primitive operations* (PrimOps) on these types are what you might +expect; e.g., ``(+#)`` is addition on ``Int#``\ s, and is the +machine-addition that we all know and love—usually one instruction. + +Primitive (unboxed) types cannot be defined in Haskell, and are +therefore built into the language and compiler. Primitive types are +always unlifted; that is, a value of a primitive type cannot be bottom. +We use the convention (but it is only a convention) that primitive +types, values, and operations have a ``#`` suffix (see +:ref:`magic-hash`). For some primitive types we have special syntax for +literals, also described in the `same section <#magic-hash>`__. + +Primitive values are often represented by a simple bit-pattern, such as +``Int#``, ``Float#``, ``Double#``. But this is not necessarily the case: +a primitive value might be represented by a pointer to a heap-allocated +object. Examples include ``Array#``, the type of primitive arrays. A +primitive array is heap-allocated because it is too big a value to fit +in a register, and would be too expensive to copy around; in a sense, it +is accidental that it is represented by a pointer. If a pointer +represents a primitive value, then it really does point to that value: +no unevaluated thunks, no indirections…nothing can be at the other end +of the pointer than the primitive value. A numerically-intensive program +using unboxed types can go a *lot* faster than its “standard” +counterpart—we saw a threefold speedup on one example. + +There are some restrictions on the use of primitive types: + +- The main restriction is that you can't pass a primitive value to a + polymorphic function or store one in a polymorphic data type. This + rules out things like ``[Int#]`` (i.e. lists of primitive integers). + The reason for this restriction is that polymorphic arguments and + constructor fields are assumed to be pointers: if an unboxed integer + is stored in one of these, the garbage collector would attempt to + follow it, leading to unpredictable space leaks. Or a ``seq`` + operation on the polymorphic component may attempt to dereference the + pointer, with disastrous results. Even worse, the unboxed value might + be larger than a pointer (``Double#`` for instance). + +- You cannot define a newtype whose representation type (the argument + type of the data constructor) is an unboxed type. Thus, this is + illegal: + + :: + + newtype A = MkA Int# + +- You cannot bind a variable with an unboxed type in a *top-level* + binding. + +- You cannot bind a variable with an unboxed type in a *recursive* + binding. + +- You may bind unboxed variables in a (non-recursive, non-top-level) + pattern binding, but you must make any such pattern-match strict. For + example, rather than: + + :: + + data Foo = Foo Int Int# + + f x = let (Foo a b, w) = ..rhs.. in ..body.. + + you must write: + + :: + + data Foo = Foo Int Int# + + f x = let !(Foo a b, w) = ..rhs.. in ..body.. + + since ``b`` has type ``Int#``. + +.. _unboxed-tuples: + +Unboxed tuples +-------------- + +Unboxed tuples aren't really exported by ``GHC.Exts``; they are a +syntactic extension enabled by the language flag ``-XUnboxedTuples``. An +unboxed tuple looks like this: + +:: + + (# e_1, ..., e_n #) + +where ``e_1..e_n`` are expressions of any type (primitive or +non-primitive). The type of an unboxed tuple looks the same. + +Note that when unboxed tuples are enabled, ``(#`` is a single lexeme, so +for example when using operators like ``#`` and ``#-`` you need to write +``( # )`` and ``( #- )`` rather than ``(#)`` and ``(#-)``. + +Unboxed tuples are used for functions that need to return multiple +values, but they avoid the heap allocation normally associated with +using fully-fledged tuples. When an unboxed tuple is returned, the +components are put directly into registers or on the stack; the unboxed +tuple itself does not have a composite representation. Many of the +primitive operations listed in ``primops.txt.pp`` return unboxed tuples. +In particular, the ``IO`` and ``ST`` monads use unboxed tuples to avoid +unnecessary allocation during sequences of operations. + +There are some restrictions on the use of unboxed tuples: + +- Values of unboxed tuple types are subject to the same restrictions as + other unboxed types; i.e. they may not be stored in polymorphic data + structures or passed to polymorphic functions. + +- The typical use of unboxed tuples is simply to return multiple + values, binding those multiple results with a ``case`` expression, + thus: + + :: + + f x y = (# x+1, y-1 #) + g x = case f x x of { (# a, b #) -> a + b } + + You can have an unboxed tuple in a pattern binding, thus + + :: + + f x = let (# p,q #) = h x in ..body.. + + If the types of ``p`` and ``q`` are not unboxed, the resulting + binding is lazy like any other Haskell pattern binding. The above + example desugars like this: + + :: + + f x = let t = case h x of { (# p,q #) -> (p,q) } + p = fst t + q = snd t + in ..body.. + + Indeed, the bindings can even be recursive. + +.. _syntax-extns: + +Syntactic extensions +==================== + +.. _unicode-syntax: + +Unicode syntax +-------------- + +The language extension ``-XUnicodeSyntax``\ ``-XUnicodeSyntax`` enables +Unicode characters to be used to stand for certain ASCII character +sequences. The following alternatives are provided: + ++--------------+---------------+-------------+--------------------------------+ +| ASCII | Unicode | Code point | Name | +| | alternative | | | ++==============+===============+=============+================================+ +| ``::`` | ∷ | 0x2237 | PROPORTION | ++--------------+---------------+-------------+--------------------------------+ +| ``=>`` | ⇒ | 0x21D2 | RIGHTWARDS DOUBLE ARROW | ++--------------+---------------+-------------+--------------------------------+ +| ``->`` | → | 0x2192 | RIGHTWARDS ARROW | ++--------------+---------------+-------------+--------------------------------+ +| ``<-`` | ← | 0x2190 | LEFTWARDS ARROW | ++--------------+---------------+-------------+--------------------------------+ +| ``>-`` | ⤚ | 0x291a | RIGHTWARDS ARROW-TAIL | ++--------------+---------------+-------------+--------------------------------+ +| ``-<`` | ⤙ | 0x2919 | LEFTWARDS ARROW-TAIL | ++--------------+---------------+-------------+--------------------------------+ +| ``>>-`` | ⤜ | 0x291C | RIGHTWARDS DOUBLE ARROW-TAIL | ++--------------+---------------+-------------+--------------------------------+ +| ``-<<`` | ⤛ | 0x291B | LEFTWARDS DOUBLE ARROW-TAIL | ++--------------+---------------+-------------+--------------------------------+ +| ``*`` | ★ | 0x2605 | BLACK STAR | ++--------------+---------------+-------------+--------------------------------+ +| ``forall`` | ∀ | 0x2200 | FOR ALL | ++--------------+---------------+-------------+--------------------------------+ + +.. _magic-hash: + +The magic hash +-------------- + +The language extension ``-XMagicHash`` allows "#" as a postfix modifier +to identifiers. Thus, "x#" is a valid variable, and "T#" is a valid type +constructor or data constructor. + +The hash sign does not change semantics at all. We tend to use variable +names ending in "#" for unboxed values or types (e.g. ``Int#``), but +there is no requirement to do so; they are just plain ordinary +variables. Nor does the ``-XMagicHash`` extension bring anything into +scope. For example, to bring ``Int#`` into scope you must import +``GHC.Prim`` (see :ref:`primitives`); the ``-XMagicHash`` extension then +allows you to *refer* to the ``Int#`` that is now in scope. Note that +with this option, the meaning of ``x#y = 0`` is changed: it defines a +function ``x#`` taking a single argument ``y``; to define the operator +``#``, put a space: ``x # y = 0``. + +The ``-XMagicHash`` also enables some new forms of literals (see +:ref:`glasgow-unboxed`): + +- ``'x'#`` has type ``Char#`` + +- ``"foo"#`` has type ``Addr#`` + +- ``3#`` has type ``Int#``. In general, any Haskell integer lexeme + followed by a ``#`` is an ``Int#`` literal, e.g. ``-0x3A#`` as well as + ``32#``. + +- ``3##`` has type ``Word#``. In general, any non-negative Haskell + integer lexeme followed by ``##`` is a ``Word#``. + +- ``3.2#`` has type ``Float#``. + +- ``3.2##`` has type ``Double#`` + +.. _negative-literals: + +Negative literals +----------------- + +The literal ``-123`` is, according to Haskell98 and Haskell 2010, +desugared as ``negate (fromInteger 123)``. The language extension +``-XNegativeLiterals`` means that it is instead desugared as +``fromInteger (-123)``. + +This can make a difference when the positive and negative range of a +numeric data type don't match up. For example, in 8-bit arithmetic -128 +is representable, but +128 is not. So ``negate (fromInteger 128)`` will +elicit an unexpected integer-literal-overflow message. + +.. _num-decimals: + +Fractional looking integer literals +----------------------------------- + +Haskell 2010 and Haskell 98 define floating literals with the syntax +``1.2e6``. These literals have the type ``Fractional a => a``. + +The language extension ``-XNumDecimals`` allows you to also use the +floating literal syntax for instances of ``Integral``, and have values +like ``(1.2e6 :: Num a => a)`` + +.. _binary-literals: + +Binary integer literals +----------------------- + +Haskell 2010 and Haskell 98 allows for integer literals to be given in +decimal, octal (prefixed by ``0o`` or ``0O``), or hexadecimal notation +(prefixed by ``0x`` or ``0X``). + +The language extension ``-XBinaryLiterals`` adds support for expressing +integer literals in binary notation with the prefix ``0b`` or ``0B``. +For instance, the binary integer literal ``0b11001001`` will be +desugared into ``fromInteger 201`` when ``-XBinaryLiterals`` is enabled. + +.. _hierarchical-modules: + +Hierarchical Modules +-------------------- + +GHC supports a small extension to the syntax of module names: a module +name is allowed to contain a dot ``‘.’``. This is also known as the +“hierarchical module namespace” extension, because it extends the +normally flat Haskell module namespace into a more flexible hierarchy of +modules. + +This extension has very little impact on the language itself; modules +names are *always* fully qualified, so you can just think of the fully +qualified module name as “the module name”. In particular, this means +that the full module name must be given after the ``module`` keyword at +the beginning of the module; for example, the module ``A.B.C`` must +begin + +:: + + module A.B.C + +It is a common strategy to use the ``as`` keyword to save some typing +when using qualified names with hierarchical modules. For example: + +:: + + import qualified Control.Monad.ST.Strict as ST + +For details on how GHC searches for source and interface files in the +presence of hierarchical modules, see :ref:`search-path`. + +GHC comes with a large collection of libraries arranged hierarchically; +see the accompanying `library +documentation <../libraries/index.html>`__. More libraries to install +are available from +`HackageDB <http://hackage.haskell.org/packages/hackage.html>`__. + +.. _pattern-guards: + +Pattern guards +-------------- + +Pattern guards (Glasgow extension) The discussion that follows is an +abbreviated version of Simon Peyton Jones's original +`proposal <http://research.microsoft.com/~simonpj/Haskell/guards.html>`__. +(Note that the proposal was written before pattern guards were +implemented, so refers to them as unimplemented.) + +Suppose we have an abstract data type of finite maps, with a lookup +operation: + +:: + + lookup :: FiniteMap -> Int -> Maybe Int + +The lookup returns ``Nothing`` if the supplied key is not in the domain +of the mapping, and ``(Just v)`` otherwise, where ``v`` is the value +that the key maps to. Now consider the following definition: + +:: + + clunky env var1 var2 | ok1 && ok2 = val1 + val2 + | otherwise = var1 + var2 + where + m1 = lookup env var1 + m2 = lookup env var2 + ok1 = maybeToBool m1 + ok2 = maybeToBool m2 + val1 = expectJust m1 + val2 = expectJust m2 + +The auxiliary functions are + +:: + + maybeToBool :: Maybe a -> Bool + maybeToBool (Just x) = True + maybeToBool Nothing = False + + expectJust :: Maybe a -> a + expectJust (Just x) = x + expectJust Nothing = error "Unexpected Nothing" + +What is ``clunky`` doing? The guard ``ok1 && ok2`` checks that both +lookups succeed, using ``maybeToBool`` to convert the ``Maybe`` types to +booleans. The (lazily evaluated) ``expectJust`` calls extract the values +from the results of the lookups, and binds the returned values to +``val1`` and ``val2`` respectively. If either lookup fails, then clunky +takes the ``otherwise`` case and returns the sum of its arguments. + +This is certainly legal Haskell, but it is a tremendously verbose and +un-obvious way to achieve the desired effect. Arguably, a more direct +way to write clunky would be to use case expressions: + +:: + + clunky env var1 var2 = case lookup env var1 of + Nothing -> fail + Just val1 -> case lookup env var2 of + Nothing -> fail + Just val2 -> val1 + val2 + where + fail = var1 + var2 + +This is a bit shorter, but hardly better. Of course, we can rewrite any +set of pattern-matching, guarded equations as case expressions; that is +precisely what the compiler does when compiling equations! The reason +that Haskell provides guarded equations is because they allow us to +write down the cases we want to consider, one at a time, independently +of each other. This structure is hidden in the case version. Two of the +right-hand sides are really the same (``fail``), and the whole +expression tends to become more and more indented. + +Here is how I would write clunky: + +:: + + clunky env var1 var2 + | Just val1 <- lookup env var1 + , Just val2 <- lookup env var2 + = val1 + val2 + ...other equations for clunky... + +The semantics should be clear enough. The qualifiers are matched in +order. For a ``<-`` qualifier, which I call a pattern guard, the right +hand side is evaluated and matched against the pattern on the left. If +the match fails then the whole guard fails and the next equation is +tried. If it succeeds, then the appropriate binding takes place, and the +next qualifier is matched, in the augmented environment. Unlike list +comprehensions, however, the type of the expression to the right of the +``<-`` is the same as the type of the pattern to its left. The bindings +introduced by pattern guards scope over all the remaining guard +qualifiers, and over the right hand side of the equation. + +Just as with list comprehensions, boolean expressions can be freely +mixed with among the pattern guards. For example: + +:: + + f x | [y] <- x + , y > 3 + , Just z <- h y + = ... + +Haskell's current guards therefore emerge as a special case, in which +the qualifier list has just one element, a boolean expression. + +.. _view-patterns: + +View patterns +------------- + +View patterns are enabled by the flag ``-XViewPatterns``. More +information and examples of view patterns can be found on the +:ghc-wiki:`Wiki page <ViewPatterns>`. + +View patterns are somewhat like pattern guards that can be nested inside +of other patterns. They are a convenient way of pattern-matching against +values of abstract types. For example, in a programming language +implementation, we might represent the syntax of the types of the +language as follows: + +:: + + type Typ + + data TypView = Unit + | Arrow Typ Typ + + view :: Typ -> TypView + + -- additional operations for constructing Typ's ... + +The representation of Typ is held abstract, permitting implementations +to use a fancy representation (e.g., hash-consing to manage sharing). +Without view patterns, using this signature a little inconvenient: + +:: + + size :: Typ -> Integer + size t = case view t of + Unit -> 1 + Arrow t1 t2 -> size t1 + size t2 + +It is necessary to iterate the case, rather than using an equational +function definition. And the situation is even worse when the matching +against ``t`` is buried deep inside another pattern. + +View patterns permit calling the view function inside the pattern and +matching against the result: + +:: + + size (view -> Unit) = 1 + size (view -> Arrow t1 t2) = size t1 + size t2 + +That is, we add a new form of pattern, written ⟨expression⟩ ``->`` +⟨pattern⟩ that means "apply the expression to whatever we're trying to +match against, and then match the result of that application against the +pattern". The expression can be any Haskell expression of function type, +and view patterns can be used wherever patterns are used. + +The semantics of a pattern ``(`` ⟨exp⟩ ``->`` ⟨pat⟩ ``)`` are as +follows: + +- Scoping: + The variables bound by the view pattern are the variables bound by + ⟨pat⟩. + + Any variables in ⟨exp⟩ are bound occurrences, but variables bound "to + the left" in a pattern are in scope. This feature permits, for + example, one argument to a function to be used in the view of another + argument. For example, the function ``clunky`` from + :ref:`pattern-guards` can be written using view patterns as follows: + + :: + + clunky env (lookup env -> Just val1) (lookup env -> Just val2) = val1 + val2 + ...other equations for clunky... + + More precisely, the scoping rules are: + + - In a single pattern, variables bound by patterns to the left of a + view pattern expression are in scope. For example: + + :: + + example :: Maybe ((String -> Integer,Integer), String) -> Bool + example Just ((f,_), f -> 4) = True + + Additionally, in function definitions, variables bound by matching + earlier curried arguments may be used in view pattern expressions + in later arguments: + + :: + + example :: (String -> Integer) -> String -> Bool + example f (f -> 4) = True + + That is, the scoping is the same as it would be if the curried + arguments were collected into a tuple. + + - In mutually recursive bindings, such as ``let``, ``where``, or the + top level, view patterns in one declaration may not mention + variables bound by other declarations. That is, each declaration + must be self-contained. For example, the following program is not + allowed: + + :: + + let {(x -> y) = e1 ; + (y -> x) = e2 } in x + + (For some amplification on this design choice see :ghc-ticket:`4061`. + +- Typing: If ⟨exp⟩ has type ⟨T1⟩ ``->`` ⟨T2⟩ and ⟨pat⟩ matches a ⟨T2⟩, + then the whole view pattern matches a ⟨T1⟩. + +- Matching: To the equations in Section 3.17.3 of the `Haskell 98 + Report <http://www.haskell.org/onlinereport/>`__, add the following: + + :: + + case v of { (e -> p) -> e1 ; _ -> e2 } + = + case (e v) of { p -> e1 ; _ -> e2 } + + That is, to match a variable ⟨v⟩ against a pattern ``(`` ⟨exp⟩ ``->`` + ⟨pat⟩ ``)``, evaluate ``(`` ⟨exp⟩ ⟨v⟩ ``)`` and match the result + against ⟨pat⟩. + +- Efficiency: When the same view function is applied in multiple + branches of a function definition or a case expression (e.g., in + ``size`` above), GHC makes an attempt to collect these applications + into a single nested case expression, so that the view function is + only applied once. Pattern compilation in GHC follows the matrix + algorithm described in Chapter 4 of `The Implementation of Functional + Programming + Languages <http://research.microsoft.com/~simonpj/Papers/slpj-book-1987/>`__. + When the top rows of the first column of a matrix are all view + patterns with the "same" expression, these patterns are transformed + into a single nested case. This includes, for example, adjacent view + patterns that line up in a tuple, as in + + :: + + f ((view -> A, p1), p2) = e1 + f ((view -> B, p3), p4) = e2 + + The current notion of when two view pattern expressions are "the + same" is very restricted: it is not even full syntactic equality. + However, it does include variables, literals, applications, and + tuples; e.g., two instances of ``view ("hi", "there")`` will be + collected. However, the current implementation does not compare up to + alpha-equivalence, so two instances of ``(x, view x -> y)`` will not + be coalesced. + +.. _pattern-synonyms: + +Pattern synonyms +---------------- + +Pattern synonyms are enabled by the flag ``-XPatternSynonyms``, which is +required for defining them, but *not* for using them. More information +and examples of view patterns can be found on the +`Wiki page <PatternSynonyms>`. + +Pattern synonyms enable giving names to parametrized pattern schemes. +They can also be thought of as abstract constructors that don't have a +bearing on data representation. For example, in a programming language +implementation, we might represent types of the language as follows: + +:: + + data Type = App String [Type] + +Here are some examples of using said representation. Consider a few +types of the ``Type`` universe encoded like this: + +:: + + App "->" [t1, t2] -- t1 -> t2 + App "Int" [] -- Int + App "Maybe" [App "Int" []] -- Maybe Int + +This representation is very generic in that no types are given special +treatment. However, some functions might need to handle some known types +specially, for example the following two functions collect all argument +types of (nested) arrow types, and recognize the ``Int`` type, +respectively: + +:: + + collectArgs :: Type -> [Type] + collectArgs (App "->" [t1, t2]) = t1 : collectArgs t2 + collectArgs _ = [] + + isInt :: Type -> Bool + isInt (App "Int" []) = True + isInt _ = False + +Matching on ``App`` directly is both hard to read and error prone to +write. And the situation is even worse when the matching is nested: + +:: + + isIntEndo :: Type -> Bool + isIntEndo (App "->" [App "Int" [], App "Int" []]) = True + isIntEndo _ = False + +Pattern synonyms permit abstracting from the representation to expose +matchers that behave in a constructor-like manner with respect to +pattern matching. We can create pattern synonyms for the known types we +care about, without committing the representation to them (note that +these don't have to be defined in the same module as the ``Type`` type): + +:: + + pattern Arrow t1 t2 = App "->" [t1, t2] + pattern Int = App "Int" [] + pattern Maybe t = App "Maybe" [t] + +Which enables us to rewrite our functions in a much cleaner style: + +:: + + collectArgs :: Type -> [Type] + collectArgs (Arrow t1 t2) = t1 : collectArgs t2 + collectArgs _ = [] + + isInt :: Type -> Bool + isInt Int = True + isInt _ = False + + isIntEndo :: Type -> Bool + isIntEndo (Arrow Int Int) = True + isIntEndo _ = False + +Note that in this example, the pattern synonyms ``Int`` and ``Arrow`` +can also be used as expressions (they are *bidirectional*). This is not +necessarily the case: *unidirectional* pattern synonyms can also be +declared with the following syntax: + +:: + + pattern Head x <- x:xs + +In this case, ``Head`` ⟨x⟩ cannot be used in expressions, only patterns, +since it wouldn't specify a value for the ⟨xs⟩ on the right-hand side. +We can give an explicit inversion of a pattern synonym using the +following syntax: + +:: + + pattern Head x <- x:xs where + Head x = [x] + +The syntax and semantics of pattern synonyms are elaborated in the +following subsections. See the :ghc-wiki:`Wiki page <PatternSynonyms>` for more +details. + +Syntax and scoping of pattern synonyms +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A pattern synonym declaration can be either unidirectional or +bidirectional. The syntax for unidirectional pattern synonyms is: + +:: + + pattern Name args <- pat + +and the syntax for bidirectional pattern synonyms is: + +:: + + pattern Name args = pat + +or + +:: + + pattern Name args <- pat where + Name args = expr + +Either prefix or infix syntax can be used. + +Pattern synonym declarations can only occur in the top level of a +module. In particular, they are not allowed as local definitions. + +The variables in the left-hand side of the definition are bound by the +pattern on the right-hand side. For implicitly bidirectional pattern +synonyms, all the variables of the right-hand side must also occur on +the left-hand side; also, wildcard patterns and view patterns are not +allowed. For unidirectional and explicitly-bidirectional pattern +synonyms, there is no restriction on the right-hand side pattern. + +Pattern synonyms cannot be defined recursively. + +.. _patsyn-impexp: + +Import and export of pattern synonyms +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The name of the pattern synonym itself is in the same namespace as +proper data constructors. In an export or import specification, you must +prefix pattern names with the ``pattern`` keyword, e.g.: + +:: + + module Example (pattern Single) where + pattern Single x = [x] + +Without the ``pattern`` prefix, ``Single`` would be interpreted as a +type constructor in the export list. + +You may also use the ``pattern`` keyword in an import/export +specification to import or export an ordinary data constructor. For +example: + +:: + + import Data.Maybe( pattern Just ) + +would bring into scope the data constructor ``Just`` from the ``Maybe`` +type, without also bringing the type constructor ``Maybe`` into scope. + +Typing of pattern synonyms +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Given a pattern synonym definition of the form + +:: + + pattern P var1 var2 ... varN <- pat + +it is assigned a *pattern type* of the form + +:: + + pattern P :: CProv => CReq => t1 -> t2 -> ... -> tN -> t + +where ⟨CProv⟩ and ⟨CReq⟩ are type contexts, and ⟨t1⟩, ⟨t2⟩, ..., ⟨tN⟩ +and ⟨t⟩ are types. Notice the unusual form of the type, with two +contexts ⟨CProv⟩ and ⟨CReq⟩: + +- ⟨CReq⟩ are the constraints *required* to match the pattern. + +- ⟨CProv⟩ are the constraints *made available (provided)* by a + successful pattern match. + +For example, consider + +:: + + data T a where + MkT :: (Show b) => a -> b -> T a + + f1 :: (Eq a, Num a) => T a -> String + f1 (MkT 42 x) = show x + + pattern ExNumPat :: (Show b) => (Num a, Eq a) => b -> T a + pattern ExNumPat x = MkT 42 x + + f2 :: (Eq a, Num a) => T a -> String + f2 (ExNumPat x) = show x + +Here ``f1`` does not use pattern synonyms. To match against the numeric +pattern ``42`` *requires* the caller to satisfy the constraints +``(Num a, Eq a)``, so they appear in ``f1``'s type. The call to ``show`` +generates a ``(Show b)`` constraint, where ``b`` is an existentially +type variable bound by the pattern match on ``MkT``. But the same +pattern match also *provides* the constraint ``(Show b)`` (see ``MkT``'s +type), and so all is well. + +Exactly the same reasoning applies to ``ExNumPat``: matching against +``ExNumPat`` *requires* the constraints ``(Num a, Eq a)``, and +*provides* the constraint ``(Show b)``. + +Note also the following points + +- In the common case where ``CReq`` is empty, ``()``, it can be omitted + altogether. + +- You may specify an explicit *pattern signature*, as we did for + ``ExNumPat`` above, to specify the type of a pattern, just as you can + for a function. As usual, the type signature can be less polymorphic + than the inferred type. For example + + :: + + -- Inferred type would be 'a -> [a]' + pattern SinglePair :: (a, a) -> [(a, a)] + pattern SinglePair x = [x] + +- The GHCi ``:info`` command shows pattern types in this format. + +- For a bidirectional pattern synonym, a use of the pattern synonym as + an expression has the type + + :: + + (CProv, CReq) => t1 -> t2 -> ... -> tN -> t + + So in the previous example, when used in an expression, ``ExNumPat`` + has type + + :: + + ExNumPat :: (Show b, Num a, Eq a) => b -> T t + + Notice that this is a tiny bit more restrictive than the expression + ``MkT 42 x`` which would not require ``(Eq a)``. + +- Consider these two pattern synonyms: + + :: + + data S a where + S1 :: Bool -> S Bool + + pattern P1 b = Just b -- P1 :: Bool -> Maybe Bool + pattern P2 b = S1 b -- P2 :: (b~Bool) => Bool -> S b + + f :: Maybe a -> String + f (P1 x) = "no no no" -- Type-incorrect + + g :: S a -> String + g (P2 b) = "yes yes yes" -- Fine + + Pattern ``P1`` can only match against a value of type ``Maybe Bool``, + so function ``f`` is rejected because the type signature is + ``Maybe a``. (To see this, imagine expanding the pattern synonym.) + + On the other hand, function ``g`` works fine, because matching + against ``P2`` (which wraps the GADT ``S``) provides the local + equality ``(a~Bool)``. If you were to give an explicit pattern + signature ``P2 :: Bool -> S Bool``, then ``P2`` would become less + polymorphic, and would behave exactly like ``P1`` so that ``g`` would + then be rejected. + + In short, if you want GADT-like behaviour for pattern synonyms, then + (unlike unlike concrete data constructors like ``S1``) you must write + its type with explicit provided equalities. For a concrete data + constructor like ``S1`` you can write its type signature as either + ``S1 :: Bool -> S Bool`` or ``S1 :: (b~Bool) => Bool -> S b``; the + two are equivalent. Not so for pattern synonyms: the two forms are + different, in order to distinguish the two cases above. (See + :ghc-ticket:`9953` for discussion of this choice.) + +Matching of pattern synonyms +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A pattern synonym occurrence in a pattern is evaluated by first matching +against the pattern synonym itself, and then on the argument patterns. +For example, in the following program, ``f`` and ``f'`` are equivalent: + +:: + + pattern Pair x y <- [x, y] + + f (Pair True True) = True + f _ = False + + f' [x, y] | True <- x, True <- y = True + f' _ = False + +Note that the strictness of ``f`` differs from that of ``g`` defined +below: + +:: + + g [True, True] = True + g _ = False + + *Main> f (False:undefined) + *** Exception: Prelude.undefined + *Main> g (False:undefined) + False + +.. _n-k-patterns: + +n+k patterns +------------ + +.. index:: + single: -XNPlusKPatterns + +``n+k`` pattern support is disabled by default. To enable it, you can +use the ``-XNPlusKPatterns`` flag. + +.. _traditional-record-syntax: + +Traditional record syntax +------------------------- + +.. index:: + single: -XNoTraditionalRecordSyntax + +Traditional record syntax, such as ``C {f = x}``, is enabled by default. +To disable it, you can use the ``-XNoTraditionalRecordSyntax`` flag. + +.. _recursive-do-notation: + +The recursive do-notation +------------------------- + +The do-notation of Haskell 98 does not allow *recursive bindings*, that +is, the variables bound in a do-expression are visible only in the +textually following code block. Compare this to a let-expression, where +bound variables are visible in the entire binding group. + +It turns out that such recursive bindings do indeed make sense for a +variety of monads, but not all. In particular, recursion in this sense +requires a fixed-point operator for the underlying monad, captured by +the ``mfix`` method of the ``MonadFix`` class, defined in +``Control.Monad.Fix`` as follows: + +:: + + class Monad m => MonadFix m where + mfix :: (a -> m a) -> m a + +Haskell's ``Maybe``, ``[]`` (list), ``ST`` (both strict and lazy +versions), ``IO``, and many other monads have ``MonadFix`` instances. On +the negative side, the continuation monad, with the signature +``(a -> r) -> r``, does not. + +For monads that do belong to the ``MonadFix`` class, GHC provides an +extended version of the do-notation that allows recursive bindings. The +``-XRecursiveDo`` (language pragma: ``RecursiveDo``) provides the +necessary syntactic support, introducing the keywords ``mdo`` and +``rec`` for higher and lower levels of the notation respectively. Unlike +bindings in a ``do`` expression, those introduced by ``mdo`` and ``rec`` +are recursively defined, much like in an ordinary let-expression. Due to +the new keyword ``mdo``, we also call this notation the *mdo-notation*. + +Here is a simple (albeit contrived) example: + +:: + + {-# LANGUAGE RecursiveDo #-} + justOnes = mdo { xs <- Just (1:xs) + ; return (map negate xs) } + +or equivalently + +:: + + {-# LANGUAGE RecursiveDo #-} + justOnes = do { rec { xs <- Just (1:xs) } + ; return (map negate xs) } + +As you can guess ``justOnes`` will evaluate to ``Just [-1,-1,-1,...``. + +GHC's implementation the mdo-notation closely follows the original +translation as described in the paper `A recursive do for +Haskell <https://sites.google.com/site/leventerkok/recdo.pdf>`__, which +in turn is based on the work `Value Recursion in Monadic +Computations <http://sites.google.com/site/leventerkok/erkok-thesis.pdf>`__. +Furthermore, GHC extends the syntax described in the former paper with a +lower level syntax flagged by the ``rec`` keyword, as we describe next. + +Recursive binding groups +~~~~~~~~~~~~~~~~~~~~~~~~ + +The flag ``-XRecursiveDo`` also introduces a new keyword ``rec``, which +wraps a mutually-recursive group of monadic statements inside a ``do`` +expression, producing a single statement. Similar to a ``let`` statement +inside a ``do``, variables bound in the ``rec`` are visible throughout +the ``rec`` group, and below it. For example, compare + +:: + + do { a <- getChar do { a <- getChar + ; let { r1 = f a r2 ; rec { r1 <- f a r2 + ; ; r2 = g r1 } ; ; r2 <- g r1 } + ; return (r1 ++ r2) } ; return (r1 ++ r2) } + +In both cases, ``r1`` and ``r2`` are available both throughout the +``let`` or ``rec`` block, and in the statements that follow it. The +difference is that ``let`` is non-monadic, while ``rec`` is monadic. (In +Haskell ``let`` is really ``letrec``, of course.) + +The semantics of ``rec`` is fairly straightforward. Whenever GHC finds a +``rec`` group, it will compute its set of bound variables, and will +introduce an appropriate call to the underlying monadic value-recursion +operator ``mfix``, belonging to the ``MonadFix`` class. Here is an +example: + +:: + + rec { b <- f a c ===> (b,c) <- mfix (\ ~(b,c) -> do { b <- f a c + ; c <- f b a } ; c <- f b a + ; return (b,c) }) + +As usual, the meta-variables ``b``, ``c`` etc., can be arbitrary +patterns. In general, the statement ``rec ss`` is desugared to the +statement + +:: + + vs <- mfix (\ ~vs -> do { ss; return vs }) + +where ``vs`` is a tuple of the variables bound by ``ss``. + +Note in particular that the translation for a ``rec`` block only +involves wrapping a call to ``mfix``: it performs no other analysis on +the bindings. The latter is the task for the ``mdo`` notation, which is +described next. + +The ``mdo`` notation +~~~~~~~~~~~~~~~~~~~~ + +A ``rec``-block tells the compiler where precisely the recursive knot +should be tied. It turns out that the placement of the recursive knots +can be rather delicate: in particular, we would like the knots to be +wrapped around as minimal groups as possible. This process is known as +*segmentation*, and is described in detail in Section 3.2 of `A +recursive do for +Haskell <https://sites.google.com/site/leventerkok/recdo.pdf>`__. +Segmentation improves polymorphism and reduces the size of the recursive +knot. Most importantly, it avoids unnecessary interference caused by a +fundamental issue with the so-called *right-shrinking* axiom for monadic +recursion. In brief, most monads of interest (IO, strict state, etc.) do +*not* have recursion operators that satisfy this axiom, and thus not +performing segmentation can cause unnecessary interference, changing the +termination behavior of the resulting translation. (Details can be found +in Sections 3.1 and 7.2.2 of `Value Recursion in Monadic +Computations <http://sites.google.com/site/leventerkok/erkok-thesis.pdf>`__.) + +The ``mdo`` notation removes the burden of placing explicit ``rec`` +blocks in the code. Unlike an ordinary ``do`` expression, in which +variables bound by statements are only in scope for later statements, +variables bound in an ``mdo`` expression are in scope for all statements +of the expression. The compiler then automatically identifies minimal +mutually recursively dependent segments of statements, treating them as +if the user had wrapped a ``rec`` qualifier around them. + +The definition is syntactic: + +- A generator ⟨g⟩ *depends* on a textually following generator ⟨g'⟩, if + + - ⟨g'⟩ defines a variable that is used by ⟨g⟩, or + + - ⟨g'⟩ textually appears between ⟨g⟩ and ⟨g''⟩, where ⟨g⟩ depends on + ⟨g''⟩. + +- A *segment* of a given ``mdo``-expression is a minimal sequence of + generators such that no generator of the sequence depends on an + outside generator. As a special case, although it is not a generator, + the final expression in an ``mdo``-expression is considered to form a + segment by itself. + +Segments in this sense are related to *strongly-connected components* +analysis, with the exception that bindings in a segment cannot be +reordered and must be contiguous. + +Here is an example ``mdo``-expression, and its translation to ``rec`` +blocks: + +:: + + mdo { a <- getChar ===> do { a <- getChar + ; b <- f a c ; rec { b <- f a c + ; c <- f b a ; ; c <- f b a } + ; z <- h a b ; z <- h a b + ; d <- g d e ; rec { d <- g d e + ; e <- g a z ; ; e <- g a z } + ; putChar c } ; putChar c } + +Note that a given ``mdo`` expression can cause the creation of multiple +``rec`` blocks. If there are no recursive dependencies, ``mdo`` will +introduce no ``rec`` blocks. In this latter case an ``mdo`` expression +is precisely the same as a ``do`` expression, as one would expect. + +In summary, given an ``mdo`` expression, GHC first performs +segmentation, introducing ``rec`` blocks to wrap over minimal recursive +groups. Then, each resulting ``rec`` is desugared, using a call to +``Control.Monad.Fix.mfix`` as described in the previous section. The +original ``mdo``-expression typechecks exactly when the desugared +version would do so. + +Here are some other important points in using the recursive-do notation: + +- It is enabled with the flag ``-XRecursiveDo``, or the + ``LANGUAGE RecursiveDo`` pragma. (The same flag enables both + ``mdo``-notation, and the use of ``rec`` blocks inside ``do`` + expressions.) + +- ``rec`` blocks can also be used inside ``mdo``-expressions, which + will be treated as a single statement. However, it is good style to + either use ``mdo`` or ``rec`` blocks in a single expression. + +- If recursive bindings are required for a monad, then that monad must + be declared an instance of the ``MonadFix`` class. + +- The following instances of ``MonadFix`` are automatically provided: + List, Maybe, IO. Furthermore, the ``Control.Monad.ST`` and + ``Control.Monad.ST.Lazy`` modules provide the instances of the + ``MonadFix`` class for Haskell's internal state monad (strict and + lazy, respectively). + +- Like ``let`` and ``where`` bindings, name shadowing is not allowed + within an ``mdo``-expression or a ``rec``-block; that is, all the + names bound in a single ``rec`` must be distinct. (GHC will complain + if this is not the case.) + +.. _applicative-do: + +Applicative do-notation +----------------------- + +.. index:: + single: Applicative do-notation + single: do-notation; Applicative + single: -XApplicativeDo + +The language option ``-XApplicativeDo`` enables an alternative translation for +the do-notation, which uses the operators ``<$>``, ``<*>``, along with ``join`` +as far as possible. There are two main reasons for wanting to do this: + +- We can use do-notation with types that are an instance of ``Applicative`` and + ``Functor``, but not ``Monad`` +- In some monads, using the applicative operators is more efficient than monadic + bind. For example, it may enable more parallelism. + +Applicative do-notation desugaring preserves the original semantics, provided +that the ``Applicative`` instance satisfies ``<*> = ap`` and ``pure = return`` +(these are true of all the common monadic types). Thus, you can normally turn on +``-XApplicativeDo`` without fear of breaking your program. There is one pitfall +to watch out for; see :ref:`applicative-do-pitfall`. + +There are no syntactic changes with ``-XApplicativeDo``. The only way it shows +up at the source level is that you can have a ``do`` expression that doesn't +require a ``Monad`` constraint. For example, in GHCi: + +:: + + Prelude> :set -XApplicativeDo + Prelude> :t \m -> do { x <- m; return (not x) } + \m -> do { x <- m; return (not x) } + :: Functor f => f Bool -> f Bool + +This example only requires ``Functor``, because it is translated into ``(\x -> +not x) <$> m``. A more complex example requires ``Applicative``, + +:: + + Prelude> :t \m -> do { x <- m 'a'; y <- m 'b'; return (x || y) } + \m -> do { x <- m 'a'; y <- m 'b'; return (x || y) } + :: Applicative f => (Char -> f Bool) -> f Bool + +Here GHC has translated the expression into + +:: + + (\x y -> x || y) <$> m 'a' <*> m 'b' + +It is possible to see the actual translation by using ``-ddump-ds``, but be +warned, the output is quite verbose. + +Note that if the expression can't be translated into uses of ``<$>``, ``<*>`` +only, then it will incur a ``Monad`` constraint as usual. This happens when +there is a dependency on a value produced by an earlier statement in the +``do``-block: + +:: + + Prelude> :t \m -> do { x <- m True; y <- m x; return (x || y) } + \m -> do { x <- m True; y <- m x; return (x || y) } + :: Monad m => (Bool -> m Bool) -> m Bool + +Here, ``m x`` depends on the value of ``x`` produced by the first statement, so +the expression cannot be translated using ``<*>``. + +In general, the rule for when a ``do`` statement incurs a ``Monad`` constraint +is as follows. If the do-expression has the following form: + +:: + + do p1 <- E1; ...; pn <- En; return E + +where none of the variables defined by ``p1...pn`` are mentioned in ``E1...En``, +then the expression will only require ``Applicative``. Otherwise, the expression +will require ``Monad``. + + +.. _applicative-do-pitfall: + +Things to watch out for +~~~~~~~~~~~~~~~~~~~~~~~ + +Your code should just work as before when ``-XApplicativeDo`` is enabled, +provided you use conventional ``Applicative`` instances. However, if you define +a ``Functor`` or ``Applicative`` instance using do-notation, then it will likely +get turned into an infinite loop by GHC. For example, if you do this: + +:: + + instance Functor MyType where + fmap f m = do x <- m; return (f x) + +Then applicative desugaring will turn it into + +:: + + instance Functor MyType where + fmap f m = fmap (\x -> f x) m + +And the program will loop at runtime. Similarly, an ``Applicative`` instance +like this + +:: + + instance Applicative MyType where + pure = return + x <*> y = do f <- x; a <- y; return (f a) + +will result in an infinte loop when ``<*>`` is called. + +Just as you wouldn't define a ``Monad`` instance using the do-notation, you +shouldn't define ``Functor`` or ``Applicative`` instance using do-notation (when +using ``ApplicativeDo``) either. The correct way to define these instances in +terms of ``Monad`` is to use the ``Monad`` operations directly, e.g. + +:: + + instance Functor MyType where + fmap f m = m >>= return . f + + instance Applicative MyType where + pure = return + (<*>) = ap + + +.. _parallel-list-comprehensions: + +Parallel List Comprehensions +---------------------------- + +.. index:: + single: list comprehensions; parallel + single: parallel list comprehensions + +Parallel list comprehensions are a natural extension to list +comprehensions. List comprehensions can be thought of as a nice syntax +for writing maps and filters. Parallel comprehensions extend this to +include the ``zipWith`` family. + +A parallel list comprehension has multiple independent branches of +qualifier lists, each separated by a ``|`` symbol. For example, the +following zips together two lists: + +:: + + [ (x, y) | x <- xs | y <- ys ] + +The behaviour of parallel list comprehensions follows that of zip, in +that the resulting list will have the same length as the shortest +branch. + +We can define parallel list comprehensions by translation to regular +comprehensions. Here's the basic idea: + +Given a parallel comprehension of the form: + +:: + + [ e | p1 <- e11, p2 <- e12, ... + | q1 <- e21, q2 <- e22, ... + ... + ] + +This will be translated to: + +:: + + [ e | ((p1,p2), (q1,q2), ...) <- zipN [(p1,p2) | p1 <- e11, p2 <- e12, ...] + [(q1,q2) | q1 <- e21, q2 <- e22, ...] + ... + ] + +where ``zipN`` is the appropriate zip for the given number of branches. + +.. _generalised-list-comprehensions: + +Generalised (SQL-Like) List Comprehensions +------------------------------------------ + +.. index:: + single: list comprehensions; generalised + single: extended list comprehensions + single: group + single: SQL + +Generalised list comprehensions are a further enhancement to the list +comprehension syntactic sugar to allow operations such as sorting and +grouping which are familiar from SQL. They are fully described in the +paper `Comprehensive comprehensions: comprehensions with "order by" and +"group by" <http://research.microsoft.com/~simonpj/papers/list-comp>`__, +except that the syntax we use differs slightly from the paper. + +The extension is enabled with the flag ``-XTransformListComp``. + +Here is an example: + +:: + + employees = [ ("Simon", "MS", 80) + , ("Erik", "MS", 100) + , ("Phil", "Ed", 40) + , ("Gordon", "Ed", 45) + , ("Paul", "Yale", 60)] + + output = [ (the dept, sum salary) + | (name, dept, salary) <- employees + , then group by dept using groupWith + , then sortWith by (sum salary) + , then take 5 ] + +In this example, the list ``output`` would take on the value: + +:: + + [("Yale", 60), ("Ed", 85), ("MS", 180)] + +There are three new keywords: ``group``, ``by``, and ``using``. (The +functions ``sortWith`` and ``groupWith`` are not keywords; they are +ordinary functions that are exported by ``GHC.Exts``.) + +There are five new forms of comprehension qualifier, all introduced by +the (existing) keyword ``then``: + +- :: + + then f + + This statement requires that + f + have the type + forall a. [a] -> [a] + . You can see an example of its use in the motivating example, as + this form is used to apply + take 5 + . +- :: + + then f by e + + This form is similar to the previous one, but allows you to create a + function which will be passed as the first argument to f. As a + consequence f must have the type + ``forall a. (a -> t) -> [a] -> [a]``. As you can see from the type, + this function lets f "project out" some information from the elements + of the list it is transforming. + + An example is shown in the opening example, where ``sortWith`` is + supplied with a function that lets it find out the ``sum salary`` for + any item in the list comprehension it transforms. + +- :: + + then group by e using f + + This is the most general of the grouping-type statements. In this + form, f is required to have type + ``forall a. (a -> t) -> [a] -> [[a]]``. As with the ``then f by e`` + case above, the first argument is a function supplied to f by the + compiler which lets it compute e on every element of the list being + transformed. However, unlike the non-grouping case, f additionally + partitions the list into a number of sublists: this means that at + every point after this statement, binders occurring before it in the + comprehension refer to *lists* of possible values, not single values. + To help understand this, let's look at an example: + + :: + + -- This works similarly to groupWith in GHC.Exts, but doesn't sort its input first + groupRuns :: Eq b => (a -> b) -> [a] -> [[a]] + groupRuns f = groupBy (\x y -> f x == f y) + + output = [ (the x, y) + | x <- ([1..3] ++ [1..2]) + , y <- [4..6] + , then group by x using groupRuns ] + + This results in the variable ``output`` taking on the value below: + + :: + + [(1, [4, 5, 6]), (2, [4, 5, 6]), (3, [4, 5, 6]), (1, [4, 5, 6]), (2, [4, 5, 6])] + + Note that we have used the ``the`` function to change the type of x + from a list to its original numeric type. The variable y, in + contrast, is left unchanged from the list form introduced by the + grouping. + +- :: + + then group using f + + With this form of the group statement, f is required to simply have + the type ``forall a. [a] -> [[a]]``, which will be used to group up + the comprehension so far directly. An example of this form is as + follows: + + :: + + output = [ x + | y <- [1..5] + , x <- "hello" + , then group using inits] + + This will yield a list containing every prefix of the word "hello" + written out 5 times: + + :: + + ["","h","he","hel","hell","hello","helloh","hellohe","hellohel","hellohell","hellohello","hellohelloh",...] + +.. _monad-comprehensions: + +Monad comprehensions +-------------------- + +.. index:: + single: monad comprehensions + +Monad comprehensions generalise the list comprehension notation, +including parallel comprehensions (:ref:`parallel-list-comprehensions`) +and transform comprehensions (:ref:`generalised-list-comprehensions`) to +work for any monad. + +Monad comprehensions support: + +- Bindings: + + :: + + [ x + y | x <- Just 1, y <- Just 2 ] + + Bindings are translated with the ``(>>=)`` and ``return`` functions + to the usual do-notation: + + :: + + do x <- Just 1 + y <- Just 2 + return (x+y) + +- Guards: + + :: + + [ x | x <- [1..10], x <= 5 ] + + Guards are translated with the ``guard`` function, which requires a + ``MonadPlus`` instance: + + :: + + do x <- [1..10] + guard (x <= 5) + return x + +- Transform statements (as with ``-XTransformListComp``): + + :: + + [ x+y | x <- [1..10], y <- [1..x], then take 2 ] + + This translates to: + + :: + + do (x,y) <- take 2 (do x <- [1..10] + y <- [1..x] + return (x,y)) + return (x+y) + +- Group statements (as with ``-XTransformListComp``): + + :: + + [ x | x <- [1,1,2,2,3], then group by x using GHC.Exts.groupWith ] + [ x | x <- [1,1,2,2,3], then group using myGroup ] + +- Parallel statements (as with ``-XParallelListComp``): + + :: + + [ (x+y) | x <- [1..10] + | y <- [11..20] + ] + + Parallel statements are translated using the ``mzip`` function, which + requires a ``MonadZip`` instance defined in + :base-ref:`Control.Monad.Zip <Control-Monad-Zip.html>`: + + :: + + do (x,y) <- mzip (do x <- [1..10] + return x) + (do y <- [11..20] + return y) + return (x+y) + +All these features are enabled by default if the ``MonadComprehensions`` +extension is enabled. The types and more detailed examples on how to use +comprehensions are explained in the previous chapters +:ref:`generalised-list-comprehensions` and +:ref:`parallel-list-comprehensions`. In general you just have to replace +the type ``[a]`` with the type ``Monad m => m a`` for monad +comprehensions. + +Note: Even though most of these examples are using the list monad, monad +comprehensions work for any monad. The ``base`` package offers all +necessary instances for lists, which make ``MonadComprehensions`` +backward compatible to built-in, transform and parallel list +comprehensions. + +More formally, the desugaring is as follows. We write ``D[ e | Q]`` to +mean the desugaring of the monad comprehension ``[ e | Q]``: + +:: + + Expressions: e + Declarations: d + Lists of qualifiers: Q,R,S + + -- Basic forms + D[ e | ] = return e + D[ e | p <- e, Q ] = e >>= \p -> D[ e | Q ] + D[ e | e, Q ] = guard e >> \p -> D[ e | Q ] + D[ e | let d, Q ] = let d in D[ e | Q ] + + -- Parallel comprehensions (iterate for multiple parallel branches) + D[ e | (Q | R), S ] = mzip D[ Qv | Q ] D[ Rv | R ] >>= \(Qv,Rv) -> D[ e | S ] + + -- Transform comprehensions + D[ e | Q then f, R ] = f D[ Qv | Q ] >>= \Qv -> D[ e | R ] + + D[ e | Q then f by b, R ] = f (\Qv -> b) D[ Qv | Q ] >>= \Qv -> D[ e | R ] + + D[ e | Q then group using f, R ] = f D[ Qv | Q ] >>= \ys -> + case (fmap selQv1 ys, ..., fmap selQvn ys) of + Qv -> D[ e | R ] + + D[ e | Q then group by b using f, R ] = f (\Qv -> b) D[ Qv | Q ] >>= \ys -> + case (fmap selQv1 ys, ..., fmap selQvn ys) of + Qv -> D[ e | R ] + + where Qv is the tuple of variables bound by Q (and used subsequently) + selQvi is a selector mapping Qv to the ith component of Qv + + Operator Standard binding Expected type + -------------------------------------------------------------------- + return GHC.Base t1 -> m t2 + (>>=) GHC.Base m1 t1 -> (t2 -> m2 t3) -> m3 t3 + (>>) GHC.Base m1 t1 -> m2 t2 -> m3 t3 + guard Control.Monad t1 -> m t2 + fmap GHC.Base forall a b. (a->b) -> n a -> n b + mzip Control.Monad.Zip forall a b. m a -> m b -> m (a,b) + +The comprehension should typecheck when its desugaring would typecheck, +except that (as discussed in :ref:`generalised-list-comprehensions`) in the +"then ``f``" and "then group using ``f``" clauses, when the "by ``b``" qualifier +is omitted, argument ``f`` should have a polymorphic type. In particular, "then +``Data.List.sort``" and "then group using ``Data.List.group``" are +insufficiently polymorphic. + +Monad comprehensions support rebindable syntax +(:ref:`rebindable-syntax`). Without rebindable syntax, the operators +from the "standard binding" module are used; with rebindable syntax, the +operators are looked up in the current lexical scope. For example, +parallel comprehensions will be typechecked and desugared using whatever +"``mzip``" is in scope. + +The rebindable operators must have the "Expected type" given in the +table above. These types are surprisingly general. For example, you can +use a bind operator with the type + +:: + + (>>=) :: T x y a -> (a -> T y z b) -> T x z b + +In the case of transform comprehensions, notice that the groups are +parameterised over some arbitrary type ``n`` (provided it has an +``fmap``, as well as the comprehension being over an arbitrary monad. + +.. _rebindable-syntax: + +Rebindable syntax and the implicit Prelude import +------------------------------------------------- + +.. index:: + single: -XNoImplicitPrelude option + +GHC normally imports ``Prelude.hi`` files for +you. If you'd rather it didn't, then give it a ``-XNoImplicitPrelude`` +option. The idea is that you can then import a Prelude of your own. (But +don't call it ``Prelude``; the Haskell module namespace is flat, and you +must not conflict with any Prelude module.) + +Suppose you are importing a Prelude of your own in order to define your +own numeric class hierarchy. It completely defeats that purpose if the +literal "1" means "``Prelude.fromInteger 1``", which is what the Haskell +Report specifies. So the ``-XRebindableSyntax`` flag causes the +following pieces of built-in syntax to refer to *whatever is in scope*, +not the Prelude versions: + +- An integer literal ``368`` means "``fromInteger (368::Integer)``", + rather than "``Prelude.fromInteger (368::Integer)``". + +- Fractional literals are handed in just the same way, except that the + translation is ``fromRational (3.68::Rational)``. + +- The equality test in an overloaded numeric pattern uses whatever + ``(==)`` is in scope. + +- The subtraction operation, and the greater-than-or-equal test, in + ``n+k`` patterns use whatever ``(-)`` and ``(>=)`` are in scope. + +- Negation (e.g. "``- (f x)``") means "``negate (f x)``", both in + numeric patterns, and expressions. + +- Conditionals (e.g. "``if`` e1 ``then`` e2 ``else`` e3") means + "``ifThenElse`` e1 e2 e3". However ``case`` expressions are + unaffected. + +- "Do" notation is translated using whatever functions ``(>>=)``, + ``(>>)``, and ``fail``, are in scope (not the Prelude versions). List + comprehensions, ``mdo`` (:ref:`recursive-do-notation`), and parallel + array comprehensions, are unaffected. + +- Arrow notation (see :ref:`arrow-notation`) uses whatever ``arr``, + ``(>>>)``, ``first``, ``app``, ``(|||)`` and ``loop`` functions are + in scope. But unlike the other constructs, the types of these + functions must match the Prelude types very closely. Details are in + flux; if you want to use this, ask! + +``-XRebindableSyntax`` implies ``-XNoImplicitPrelude``. + +In all cases (apart from arrow notation), the static semantics should be +that of the desugared form, even if that is a little unexpected. For +example, the static semantics of the literal ``368`` is exactly that of +``fromInteger (368::Integer)``; it's fine for ``fromInteger`` to have +any of the types: + +:: + + fromInteger :: Integer -> Integer + fromInteger :: forall a. Foo a => Integer -> a + fromInteger :: Num a => a -> Integer + fromInteger :: Integer -> Bool -> Bool + +Be warned: this is an experimental facility, with fewer checks than +usual. Use ``-dcore-lint`` to typecheck the desugared program. If Core +Lint is happy you should be all right. + +.. _postfix-operators: + +Postfix operators +----------------- + +The ``-XPostfixOperators`` flag enables a small extension to the syntax +of left operator sections, which allows you to define postfix operators. +The extension is this: the left section + +:: + + (e !) + +is equivalent (from the point of view of both type checking and +execution) to the expression + +:: + + ((!) e) + +(for any expression ``e`` and operator ``(!)``. The strict Haskell 98 +interpretation is that the section is equivalent to + +:: + + (\y -> (!) e y) + +That is, the operator must be a function of two arguments. GHC allows it +to take only one argument, and that in turn allows you to write the +function postfix. + +The extension does not extend to the left-hand side of function +definitions; you must define such a function in prefix form. + +.. _tuple-sections: + +Tuple sections +-------------- + +The ``-XTupleSections`` flag enables Python-style partially applied +tuple constructors. For example, the following program + +:: + + (, True) + +is considered to be an alternative notation for the more unwieldy +alternative + +:: + + \x -> (x, True) + +You can omit any combination of arguments to the tuple, as in the +following + +:: + + (, "I", , , "Love", , 1337) + +which translates to + +:: + + \a b c d -> (a, "I", b, c, "Love", d, 1337) + +If you have `unboxed tuples <#unboxed-tuples>`__ enabled, tuple sections +will also be available for them, like so + +:: + + (# , True #) + +Because there is no unboxed unit tuple, the following expression + +:: + + (# #) + +continues to stand for the unboxed singleton tuple data constructor. + +.. _lambda-case: + +Lambda-case +----------- + +The ``-XLambdaCase`` flag enables expressions of the form + +:: + + \case { p1 -> e1; ...; pN -> eN } + +which is equivalent to + +:: + + \freshName -> case freshName of { p1 -> e1; ...; pN -> eN } + +Note that ``\case`` starts a layout, so you can write + +:: + + \case + p1 -> e1 + ... + pN -> eN + +.. _empty-case: + +Empty case alternatives +----------------------- + +The ``-XEmptyCase`` flag enables case expressions, or lambda-case +expressions, that have no alternatives, thus: + +:: + + case e of { } -- No alternatives + or + \case { } -- -XLambdaCase is also required + +This can be useful when you know that the expression being scrutinised +has no non-bottom values. For example: + +:: + + data Void + f :: Void -> Int + f x = case x of { } + +With dependently-typed features it is more useful (see :ghc-ticket:`2431``). For +example, consider these two candidate definitions of ``absurd``: + +:: + + data a :==: b where + Refl :: a :==: a + + absurd :: True :~: False -> a + absurd x = error "absurd" -- (A) + absurd x = case x of {} -- (B) + +We much prefer (B). Why? Because GHC can figure out that +``(True :~: False)`` is an empty type. So (B) has no partiality and GHC +should be able to compile with ``-fwarn-incomplete-patterns``. (Though +the pattern match checking is not yet clever enough to do that.) On the +other hand (A) looks dangerous, and GHC doesn't check to make sure that, +in fact, the function can never get called. + +.. _multi-way-if: + +Multi-way if-expressions +------------------------ + +With ``-XMultiWayIf`` flag GHC accepts conditional expressions with +multiple branches: + +:: + + if | guard1 -> expr1 + | ... + | guardN -> exprN + +which is roughly equivalent to + +:: + + case () of + _ | guard1 -> expr1 + ... + _ | guardN -> exprN + +Multi-way if expressions introduce a new layout context. So the example +above is equivalent to: + +:: + + if { | guard1 -> expr1 + ; | ... + ; | guardN -> exprN + } + +The following behaves as expected: + +:: + + if | guard1 -> if | guard2 -> expr2 + | guard3 -> expr3 + | guard4 -> expr4 + +because layout translates it as + +:: + + if { | guard1 -> if { | guard2 -> expr2 + ; | guard3 -> expr3 + } + ; | guard4 -> expr4 + } + +Layout with multi-way if works in the same way as other layout contexts, +except that the semi-colons between guards in a multi-way if are +optional. So it is not necessary to line up all the guards at the same +column; this is consistent with the way guards work in function +definitions and case expressions. + +.. _disambiguate-fields: + +Record field disambiguation +--------------------------- + +In record construction and record pattern matching it is entirely +unambiguous which field is referred to, even if there are two different +data types in scope with a common field name. For example: + +:: + + module M where + data S = MkS { x :: Int, y :: Bool } + + module Foo where + import M + + data T = MkT { x :: Int } + + ok1 (MkS { x = n }) = n+1 -- Unambiguous + ok2 n = MkT { x = n+1 } -- Unambiguous + + bad1 k = k { x = 3 } -- Ambiguous + bad2 k = x k -- Ambiguous + +Even though there are two ``x``'s in scope, it is clear that the ``x`` +in the pattern in the definition of ``ok1`` can only mean the field +``x`` from type ``S``. Similarly for the function ``ok2``. However, in +the record update in ``bad1`` and the record selection in ``bad2`` it is +not clear which of the two types is intended. + +Haskell 98 regards all four as ambiguous, but with the +``-XDisambiguateRecordFields`` flag, GHC will accept the former two. The +rules are precisely the same as those for instance declarations in +Haskell 98, where the method names on the left-hand side of the method +bindings in an instance declaration refer unambiguously to the method of +that class (provided they are in scope at all), even if there are other +variables in scope with the same name. This reduces the clutter of +qualified names when you import two records from different modules that +use the same field name. + +Some details: + +- Field disambiguation can be combined with punning (see + :ref:`record-puns`). For example: + + :: + + module Foo where + import M + x=True + ok3 (MkS { x }) = x+1 -- Uses both disambiguation and punning + +- With ``-XDisambiguateRecordFields`` you can use *unqualified* field + names even if the corresponding selector is only in scope *qualified* + For example, assuming the same module ``M`` as in our earlier + example, this is legal: + + :: + + module Foo where + import qualified M -- Note qualified + + ok4 (M.MkS { x = n }) = n+1 -- Unambiguous + + Since the constructor ``MkS`` is only in scope qualified, you must + name it ``M.MkS``, but the field ``x`` does not need to be qualified + even though ``M.x`` is in scope but ``x`` is not (In effect, it is + qualified by the constructor). + +.. _record-puns: + +Record puns +----------- + +Record puns are enabled by the flag ``-XNamedFieldPuns``. + +When using records, it is common to write a pattern that binds a +variable with the same name as a record field, such as: + +:: + + data C = C {a :: Int} + f (C {a = a}) = a + +Record punning permits the variable name to be elided, so one can simply +write + +:: + + f (C {a}) = a + +to mean the same pattern as above. That is, in a record pattern, the +pattern ``a`` expands into the pattern ``a = a`` for the same name +``a``. + +Note that: + +- Record punning can also be used in an expression, writing, for + example, + + :: + + let a = 1 in C {a} + + instead of + + :: + + let a = 1 in C {a = a} + + The expansion is purely syntactic, so the expanded right-hand side + expression refers to the nearest enclosing variable that is spelled + the same as the field name. + +- Puns and other patterns can be mixed in the same record: + + :: + + data C = C {a :: Int, b :: Int} + f (C {a, b = 4}) = a + +- Puns can be used wherever record patterns occur (e.g. in ``let`` + bindings or at the top-level). + +- A pun on a qualified field name is expanded by stripping off the + module qualifier. For example: + + :: + + f (C {M.a}) = a + + means + + :: + + f (M.C {M.a = a}) = a + + (This is useful if the field selector ``a`` for constructor ``M.C`` + is only in scope in qualified form.) + +.. _record-wildcards: + +Record wildcards +---------------- + +Record wildcards are enabled by the flag ``-XRecordWildCards``. This +flag implies ``-XDisambiguateRecordFields``. + +For records with many fields, it can be tiresome to write out each field +individually in a record pattern, as in + +:: + + data C = C {a :: Int, b :: Int, c :: Int, d :: Int} + f (C {a = 1, b = b, c = c, d = d}) = b + c + d + +Record wildcard syntax permits a "``..``" in a record pattern, where +each elided field ``f`` is replaced by the pattern ``f = f``. For +example, the above pattern can be written as + +:: + + f (C {a = 1, ..}) = b + c + d + +More details: + +- Record wildcards in patterns can be mixed with other patterns, + including puns (:ref:`record-puns`); for example, in a pattern + ``(C {a = 1, b, ..})``. Additionally, record wildcards can be used + wherever record patterns occur, including in ``let`` bindings and at + the top-level. For example, the top-level binding + + :: + + C {a = 1, ..} = e + + defines ``b``, ``c``, and ``d``. + +- Record wildcards can also be used in an expression, when constructing + a record. For example, + + :: + + let {a = 1; b = 2; c = 3; d = 4} in C {..} + + in place of + + :: + + let {a = 1; b = 2; c = 3; d = 4} in C {a=a, b=b, c=c, d=d} + + The expansion is purely syntactic, so the record wildcard expression + refers to the nearest enclosing variables that are spelled the same + as the omitted field names. + +- Record wildcards may *not* be used in record *updates*. For example + this is illegal: + + :: + + f r = r { x = 3, .. } + +- For both pattern and expression wildcards, the "``..``" expands to + the missing *in-scope* record fields. Specifically the expansion of + "``C {..}``" includes ``f`` if and only if: + + - ``f`` is a record field of constructor ``C``. + + - The record field ``f`` is in scope somehow (either qualified or + unqualified). + + - In the case of expressions (but not patterns), the variable ``f`` + is in scope unqualified, apart from the binding of the record + selector itself. + + These rules restrict record wildcards to the situations in which the + user could have written the expanded version. For example + + :: + + module M where + data R = R { a,b,c :: Int } + module X where + import M( R(a,c) ) + f b = R { .. } + + The ``R{..}`` expands to ``R{M.a=a}``, omitting ``b`` since the + record field is not in scope, and omitting ``c`` since the variable + ``c`` is not in scope (apart from the binding of the record selector + ``c``, of course). + +- Record wildcards cannot be used (a) in a record update construct, and + (b) for data constructors that are not declared with record fields. + For example: + + :: + + f x = x { v=True, .. } -- Illegal (a) + + data T = MkT Int Bool + g = MkT { .. } -- Illegal (b) + h (MkT { .. }) = True -- Illegal (b) + +.. _local-fixity-declarations: + +Local Fixity Declarations +------------------------- + +A careful reading of the Haskell 98 Report reveals that fixity +declarations (``infix``, ``infixl``, and ``infixr``) are permitted to +appear inside local bindings such those introduced by ``let`` and +``where``. However, the Haskell Report does not specify the semantics of +such bindings very precisely. + +In GHC, a fixity declaration may accompany a local binding: + +:: + + let f = ... + infixr 3 `f` + in + ... + +and the fixity declaration applies wherever the binding is in scope. For +example, in a ``let``, it applies in the right-hand sides of other +``let``-bindings and the body of the ``let``\ C. Or, in recursive ``do`` +expressions (:ref:`recursive-do-notation`), the local fixity +declarations of a ``let`` statement scope over other statements in the +group, just as the bound name does. + +Moreover, a local fixity declaration *must* accompany a local binding +of that name: it is not possible to revise the fixity of name bound +elsewhere, as in + +:: + + let infixr 9 $ in ... + +Because local fixity declarations are technically Haskell 98, no flag is +necessary to enable them. + +.. _package-imports: + +Import and export extensions +---------------------------- + +Hiding things the imported module doesn't export +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Technically in Haskell 2010 this is illegal: + +:: + + module A( f ) where + f = True + + module B where + import A hiding( g ) -- A does not export g + g = f + +The ``import A hiding( g )`` in module ``B`` is technically an error +(`Haskell Report, +5.3.1 <http://www.haskell.org/onlinereport/haskell2010/haskellch5.html#x11-1020005.3.1>`__) +because ``A`` does not export ``g``. However GHC allows it, in the +interests of supporting backward compatibility; for example, a newer +version of ``A`` might export ``g``, and you want ``B`` to work in +either case. + +The warning ``-fwarn-dodgy-imports``, which is off by default but +included with ``-W``, warns if you hide something that the imported +module does not export. + +.. _package-qualified-imports: + +Package-qualified imports +~~~~~~~~~~~~~~~~~~~~~~~~~ + +With the ``-XPackageImports`` flag, GHC allows import declarations to be +qualified by the package name that the module is intended to be imported +from. For example: + +:: + + import "network" Network.Socket + +would import the module ``Network.Socket`` from the package ``network`` +(any version). This may be used to disambiguate an import when the same +module is available from multiple packages, or is present in both the +current package being built and an external package. + +The special package name ``this`` can be used to refer to the current +package being built. + +.. note:: + You probably don't need to use this feature, it was added mainly so that we + can build backwards-compatible versions of packages when APIs change. It can + lead to fragile dependencies in the common case: modules occasionally move + from one package to another, rendering any package-qualified imports broken. + See also :ref:`package-thinning-and-renaming` for an alternative way of + disambiguating between module names. + +.. _safe-imports-ext: + +Safe imports +~~~~~~~~~~~~ + +With the ``-XSafe``, ``-XTrustworthy`` and ``-XUnsafe`` language flags, +GHC extends the import declaration syntax to take an optional ``safe`` +keyword after the ``import`` keyword. This feature is part of the Safe +Haskell GHC extension. For example: + +:: + + import safe qualified Network.Socket as NS + +would import the module ``Network.Socket`` with compilation only +succeeding if ``Network.Socket`` can be safely imported. For a description of +when a import is considered safe see :ref:`safe-haskell`. + +.. _explicit-namespaces: + +Explicit namespaces in import/export +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In an import or export list, such as + +:: + + module M( f, (++) ) where ... + import N( f, (++) ) + ... + +the entities ``f`` and ``(++)`` are *values*. However, with type +operators (:ref:`type-operators`) it becomes possible to declare +``(++)`` as a *type constructor*. In that case, how would you export or +import it? + +The ``-XExplicitNamespaces`` extension allows you to prefix the name of +a type constructor in an import or export list with "``type``" to +disambiguate this case, thus: + +:: + + module M( f, type (++) ) where ... + import N( f, type (++) ) + ... + module N( f, type (++) ) where + data family a ++ b = L a | R b + +The extension ``-XExplicitNamespaces`` is implied by ``-XTypeOperators`` +and (for some reason) by ``-XTypeFamilies``. + +In addition, with ``-XPatternSynonyms`` you can prefix the name of a +data constructor in an import or export list with the keyword +``pattern``, to allow the import or export of a data constructor without +its parent type constructor (see :ref:`patsyn-impexp`). + +.. _syntax-stolen: + +Summary of stolen syntax +------------------------ + +Turning on an option that enables special syntax *might* cause working +Haskell 98 code to fail to compile, perhaps because it uses a variable +name which has become a reserved word. This section lists the syntax +that is "stolen" by language extensions. We use notation and nonterminal +names from the Haskell 98 lexical syntax (see the Haskell 98 Report). We +only list syntax changes here that might affect existing working +programs (i.e. "stolen" syntax). Many of these extensions will also +enable new context-free syntax, but in all cases programs written to use +the new syntax would not be compilable without the option enabled. + +There are two classes of special syntax: + +- New reserved words and symbols: character sequences which are no + longer available for use as identifiers in the program. + +- Other special syntax: sequences of characters that have a different + meaning when this particular option is turned on. + +The following syntax is stolen: + +``forall`` + .. index:: + single: forall + + Stolen (in types) by: ``-XExplicitForAll``, and hence by + ``-XScopedTypeVariables``, ``-XLiberalTypeSynonyms``, + ``-XRankNTypes``, ``-XExistentialQuantification`` + +``mdo`` + .. index:: + single: mdo + + Stolen by: ``-XRecursiveDo`` + +``foreign`` + .. index:: + single: foreign + + Stolen by: ``-XForeignFunctionInterface`` + +``rec``, ``proc``, ``-<``, ``>-``, ``-<<``, ``>>-``, ``(|``, ``|)`` + .. index:: + single: proc + + Stolen by: ``-XArrows`` + +``?varid`` + .. index:: + single: implicit parameters + + Stolen by: ``-XImplicitParams`` + +``[|``, ``[e|``, ``[p|``, ``[d|``, ``[t|``, ``$(``, ``$$(``, ``[||``, ``[e||``, ``$varid``, ``$$varid`` + .. index:: + single: Template Haskell + + Stolen by: ``-XTemplateHaskell`` + +``[varid|`` + .. index:: + single: quasi-quotation + + Stolen by: ``-XQuasiQuotes`` + +⟨varid⟩, ``#``\ ⟨char⟩, ``#``, ⟨string⟩, ``#``, ⟨integer⟩, ``#``, ⟨float⟩, ``#``, ⟨float⟩, ``##`` + Stolen by: ``-XMagicHash`` + +``(#``, ``#)`` + Stolen by: ``-XUnboxedTuples`` + +⟨varid⟩, ``!``, ⟨varid⟩ + Stolen by: ``-XBangPatterns`` + +``pattern`` + Stolen by: ``-XPatternSynonyms`` + +.. _data-type-extensions: + +Extensions to data types and type synonyms +========================================== + +.. _nullary-types: + +Data types with no constructors +------------------------------- + +With the ``-XEmptyDataDecls`` flag (or equivalent ``LANGUAGE`` pragma), GHC +lets you declare a data type with no constructors. For example: + +:: + + data S -- S :: * + data T a -- T :: * -> * + +Syntactically, the declaration lacks the "= constrs" part. The type can +be parameterised over types of any kind, but if the kind is not ``*`` +then an explicit kind annotation must be used (see :ref:`kinding`). + +Such data types have only one value, namely bottom. Nevertheless, they +can be useful when defining "phantom types". + +.. _datatype-contexts: + +Data type contexts +------------------ + +Haskell allows datatypes to be given contexts, e.g. + +:: + + data Eq a => Set a = NilSet | ConsSet a (Set a) + +give constructors with types: + +:: + + NilSet :: Set a + ConsSet :: Eq a => a -> Set a -> Set a + +This is widely considered a misfeature, and is going to be removed from +the language. In GHC, it is controlled by the deprecated extension +``DatatypeContexts``. + +.. _infix-tycons: + +Infix type constructors, classes, and type variables +---------------------------------------------------- + +GHC allows type constructors, classes, and type variables to be +operators, and to be written infix, very much like expressions. More +specifically: + +- A type constructor or class can be any non-reserved operator. + Symbols used in types are always like capitalized identifiers; they + are never variables. Note that this is different from the lexical + syntax of data constructors, which are required to begin with a + ``:``. + +- Data type and type-synonym declarations can be written infix, + parenthesised if you want further arguments. E.g. + + :: + + data a :*: b = Foo a b + type a :+: b = Either a b + class a :=: b where ... + + data (a :**: b) x = Baz a b x + type (a :++: b) y = Either (a,b) y + +- Types, and class constraints, can be written infix. For example + + :: + + x :: Int :*: Bool + f :: (a :=: b) => a -> b + +- Back-quotes work as for expressions, both for type constructors and + type variables; e.g. ``Int `Either` Bool``, or ``Int `a` Bool``. + Similarly, parentheses work the same; e.g. ``(:*:) Int Bool``. + +- Fixities may be declared for type constructors, or classes, just as + for data constructors. However, one cannot distinguish between the + two in a fixity declaration; a fixity declaration sets the fixity for + a data constructor and the corresponding type constructor. For + example: + + :: + + infixl 7 T, :*: + + sets the fixity for both type constructor ``T`` and data constructor + ``T``, and similarly for ``:*:``. ``Int `a` Bool``. + +- Function arrow is ``infixr`` with fixity 0 (this might change; it's + not clear what it should be). + +.. _type-operators: + +Type operators +-------------- + +In types, an operator symbol like ``(+)`` is normally treated as a type +*variable*, just like ``a``. Thus in Haskell 98 you can say + +:: + + type T (+) = ((+), (+)) + -- Just like: type T a = (a,a) + + f :: T Int -> Int + f (x,y)= x + +As you can see, using operators in this way is not very useful, and +Haskell 98 does not even allow you to write them infix. + +The language ``-XTypeOperators`` changes this behaviour: + +- Operator symbols become type *constructors* rather than type + *variables*. + +- Operator symbols in types can be written infix, both in definitions + and uses. For example: + + :: + + data a + b = Plus a b + type Foo = Int + Bool + +- There is now some potential ambiguity in import and export lists; for + example if you write ``import M( (+) )`` do you mean the *function* + ``(+)`` or the *type constructor* ``(+)``? The default is the former, + but with ``-XExplicitNamespaces`` (which is implied by + ``-XTypeOperators``) GHC allows you to specify the latter by + preceding it with the keyword ``type``, thus: + + :: + + import M( type (+) ) + + See :ref:`explicit-namespaces`. + +- The fixity of a type operator may be set using the usual fixity + declarations but, as in :ref:`infix-tycons`, the function and type + constructor share a single fixity. + +.. _type-synonyms: + +Liberalised type synonyms +------------------------- + +Type synonyms are like macros at the type level, but Haskell 98 imposes +many rules on individual synonym declarations. With the +``-XLiberalTypeSynonyms`` extension, GHC does validity checking on types +*only after expanding type synonyms*. That means that GHC can be very +much more liberal about type synonyms than Haskell 98. + +- You can write a ``forall`` (including overloading) in a type synonym, + thus: + + :: + + type Discard a = forall b. Show b => a -> b -> (a, String) + + f :: Discard a + f x y = (x, show y) + + g :: Discard Int -> (Int,String) -- A rank-2 type + g f = f 3 True + +- If you also use ``-XUnboxedTuples``, you can write an unboxed tuple + in a type synonym: + + :: + + type Pr = (# Int, Int #) + + h :: Int -> Pr + h x = (# x, x #) + +- You can apply a type synonym to a forall type: + + :: + + type Foo a = a -> a -> Bool + + f :: Foo (forall b. b->b) + + After expanding the synonym, ``f`` has the legal (in GHC) type: + + :: + + f :: (forall b. b->b) -> (forall b. b->b) -> Bool + +- You can apply a type synonym to a partially applied type synonym: + + :: + + type Generic i o = forall x. i x -> o x + type Id x = x + + foo :: Generic Id [] + + After expanding the synonym, ``foo`` has the legal (in GHC) type: + + :: + + foo :: forall x. x -> [x] + +GHC currently does kind checking before expanding synonyms (though even +that could be changed).. + +After expanding type synonyms, GHC does validity checking on types, +looking for the following mal-formedness which isn't detected simply by +kind checking: + +- Type constructor applied to a type involving for-alls (if + ``XImpredicativeTypes`` is off) + +- Partially-applied type synonym. + +So, for example, this will be rejected: + +:: + + type Pr = forall a. a + + h :: [Pr] + h = ... + +because GHC does not allow type constructors applied to for-all types. + +.. _existential-quantification: + +Existentially quantified data constructors +------------------------------------------ + +The idea of using existential quantification in data type declarations +was suggested by Perry, and implemented in Hope+ (Nigel Perry, *The +Implementation of Practical Functional Programming Languages*, PhD +Thesis, University of London, 1991). It was later formalised by Laufer +and Odersky (*Polymorphic type inference and abstract data types*, +TOPLAS, 16(5), pp. 1411-1430, 1994). It's been in Lennart Augustsson's +``hbc`` Haskell compiler for several years, and proved very useful. +Here's the idea. Consider the declaration: + +:: + + data Foo = forall a. MkFoo a (a -> Bool) + | Nil + +The data type ``Foo`` has two constructors with types: + +:: + + MkFoo :: forall a. a -> (a -> Bool) -> Foo + Nil :: Foo + +Notice that the type variable ``a`` in the type of ``MkFoo`` does not +appear in the data type itself, which is plain ``Foo``. For example, the +following expression is fine: + +:: + + [MkFoo 3 even, MkFoo 'c' isUpper] :: [Foo] + +Here, ``(MkFoo 3 even)`` packages an integer with a function ``even`` +that maps an integer to ``Bool``; and ``MkFoo 'c' +isUpper`` packages a character with a compatible function. These two +things are each of type ``Foo`` and can be put in a list. + +What can we do with a value of type ``Foo``? In particular, what +happens when we pattern-match on ``MkFoo``? + +:: + + f (MkFoo val fn) = ??? + +Since all we know about ``val`` and ``fn`` is that they are compatible, +the only (useful) thing we can do with them is to apply ``fn`` to +``val`` to get a boolean. For example: + +:: + + f :: Foo -> Bool + f (MkFoo val fn) = fn val + +What this allows us to do is to package heterogeneous values together +with a bunch of functions that manipulate them, and then treat that +collection of packages in a uniform manner. You can express quite a bit +of object-oriented-like programming this way. + +.. _existential: + +Why existential? +~~~~~~~~~~~~~~~~ + +What has this to do with *existential* quantification? Simply that +``MkFoo`` has the (nearly) isomorphic type + +:: + + MkFoo :: (exists a . (a, a -> Bool)) -> Foo + +But Haskell programmers can safely think of the ordinary *universally* +quantified type given above, thereby avoiding adding a new existential +quantification construct. + +.. _existential-with-context: + +Existentials and type classes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An easy extension is to allow arbitrary contexts before the constructor. +For example: + +:: + + data Baz = forall a. Eq a => Baz1 a a + | forall b. Show b => Baz2 b (b -> b) + +The two constructors have the types you'd expect: + +:: + + Baz1 :: forall a. Eq a => a -> a -> Baz + Baz2 :: forall b. Show b => b -> (b -> b) -> Baz + +But when pattern matching on ``Baz1`` the matched values can be compared +for equality, and when pattern matching on ``Baz2`` the first matched +value can be converted to a string (as well as applying the function to +it). So this program is legal: + +:: + + f :: Baz -> String + f (Baz1 p q) | p == q = "Yes" + | otherwise = "No" + f (Baz2 v fn) = show (fn v) + +Operationally, in a dictionary-passing implementation, the constructors +``Baz1`` and ``Baz2`` must store the dictionaries for ``Eq`` and +``Show`` respectively, and extract it on pattern matching. + +.. _existential-records: + +Record Constructors +~~~~~~~~~~~~~~~~~~~ + +GHC allows existentials to be used with records syntax as well. For +example: + +:: + + data Counter a = forall self. NewCounter + { _this :: self + , _inc :: self -> self + , _display :: self -> IO () + , tag :: a + } + +Here ``tag`` is a public field, with a well-typed selector function +``tag :: Counter a -> a``. The ``self`` type is hidden from the outside; +any attempt to apply ``_this``, ``_inc`` or ``_display`` as functions +will raise a compile-time error. In other words, *GHC defines a record +selector function only for fields whose type does not mention the +existentially-quantified variables*. (This example used an underscore in +the fields for which record selectors will not be defined, but that is +only programming style; GHC ignores them.) + +To make use of these hidden fields, we need to create some helper +functions: + +:: + + inc :: Counter a -> Counter a + inc (NewCounter x i d t) = NewCounter + { _this = i x, _inc = i, _display = d, tag = t } + + display :: Counter a -> IO () + display NewCounter{ _this = x, _display = d } = d x + +Now we can define counters with different underlying implementations: + +:: + + counterA :: Counter String + counterA = NewCounter + { _this = 0, _inc = (1+), _display = print, tag = "A" } + + counterB :: Counter String + counterB = NewCounter + { _this = "", _inc = ('#':), _display = putStrLn, tag = "B" } + + main = do + display (inc counterA) -- prints "1" + display (inc (inc counterB)) -- prints "##" + +Record update syntax is supported for existentials (and GADTs): + +:: + + setTag :: Counter a -> a -> Counter a + setTag obj t = obj{ tag = t } + +The rule for record update is this: + + the types of the updated fields may + mention only the universally-quantified type variables of the data + constructor. For GADTs, the field may mention only types that appear as + a simple type-variable argument in the constructor's result type. + +For example: + +:: + + data T a b where { T1 { f1::a, f2::b, f3::(b,c) } :: T a b } -- c is existential + upd1 t x = t { f1=x } -- OK: upd1 :: T a b -> a' -> T a' b + upd2 t x = t { f3=x } -- BAD (f3's type mentions c, which is + -- existentially quantified) + + data G a b where { G1 { g1::a, g2::c } :: G a [c] } + upd3 g x = g { g1=x } -- OK: upd3 :: G a b -> c -> G c b + upd4 g x = g { g2=x } -- BAD (f2's type mentions c, which is not a simple + -- type-variable argument in G1's result type) + +Restrictions +~~~~~~~~~~~~ + +There are several restrictions on the ways in which existentially-quantified +constructors can be used. + +- When pattern matching, each pattern match introduces a new, distinct, + type for each existential type variable. These types cannot be + unified with any other type, nor can they escape from the scope of + the pattern match. For example, these fragments are incorrect: + + :: + + f1 (MkFoo a f) = a + + Here, the type bound by ``MkFoo`` "escapes", because ``a`` is the + result of ``f1``. One way to see why this is wrong is to ask what + type ``f1`` has: + + :: + + f1 :: Foo -> a -- Weird! + + What is this "``a``" in the result type? Clearly we don't mean this: + + :: + + f1 :: forall a. Foo -> a -- Wrong! + + The original program is just plain wrong. Here's another sort of + error + + :: + + f2 (Baz1 a b) (Baz1 p q) = a==q + + It's ok to say ``a==b`` or ``p==q``, but ``a==q`` is wrong because it + equates the two distinct types arising from the two ``Baz1`` + constructors. + +- You can't pattern-match on an existentially quantified constructor in + a ``let`` or ``where`` group of bindings. So this is illegal: + + :: + + f3 x = a==b where { Baz1 a b = x } + + Instead, use a ``case`` expression: + + :: + + f3 x = case x of Baz1 a b -> a==b + + In general, you can only pattern-match on an existentially-quantified + constructor in a ``case`` expression or in the patterns of a function + definition. The reason for this restriction is really an + implementation one. Type-checking binding groups is already a + nightmare without existentials complicating the picture. Also an + existential pattern binding at the top level of a module doesn't make + sense, because it's not clear how to prevent the + existentially-quantified type "escaping". So for now, there's a + simple-to-state restriction. We'll see how annoying it is. + +- You can't use existential quantification for ``newtype`` + declarations. So this is illegal: + + :: + + newtype T = forall a. Ord a => MkT a + + Reason: a value of type ``T`` must be represented as a pair of a + dictionary for ``Ord t`` and a value of type ``t``. That contradicts + the idea that ``newtype`` should have no concrete representation. You + can get just the same efficiency and effect by using ``data`` instead + of ``newtype``. If there is no overloading involved, then there is + more of a case for allowing an existentially-quantified ``newtype``, + because the ``data`` version does carry an implementation cost, but + single-field existentially quantified constructors aren't much use. + So the simple restriction (no existential stuff on ``newtype``) + stands, unless there are convincing reasons to change it. + +- You can't use ``deriving`` to define instances of a data type with + existentially quantified data constructors. Reason: in most cases it + would not make sense. For example:; + + :: + + data T = forall a. MkT [a] deriving( Eq ) + + To derive ``Eq`` in the standard way we would need to have equality + between the single component of two ``MkT`` constructors: + + :: + + instance Eq T where + (MkT a) == (MkT b) = ??? + + But ``a`` and ``b`` have distinct types, and so can't be compared. + It's just about possible to imagine examples in which the derived + instance would make sense, but it seems altogether simpler simply to + prohibit such declarations. Define your own instances! + +.. _gadt-style: + +Declaring data types with explicit constructor signatures +--------------------------------------------------------- + +When the ``GADTSyntax`` extension is enabled, GHC allows you to declare +an algebraic data type by giving the type signatures of constructors +explicitly. For example: + +:: + + data Maybe a where + Nothing :: Maybe a + Just :: a -> Maybe a + +The form is called a "GADT-style declaration" because Generalised +Algebraic Data Types, described in :ref:`gadt`, can only be declared +using this form. + +Notice that GADT-style syntax generalises existential types +(:ref:`existential-quantification`). For example, these two declarations +are equivalent: + +:: + + data Foo = forall a. MkFoo a (a -> Bool) + data Foo' where { MKFoo :: a -> (a->Bool) -> Foo' } + +Any data type that can be declared in standard Haskell 98 syntax can +also be declared using GADT-style syntax. The choice is largely +stylistic, but GADT-style declarations differ in one important respect: +they treat class constraints on the data constructors differently. +Specifically, if the constructor is given a type-class context, that +context is made available by pattern matching. For example: + +:: + + data Set a where + MkSet :: Eq a => [a] -> Set a + + makeSet :: Eq a => [a] -> Set a + makeSet xs = MkSet (nub xs) + + insert :: a -> Set a -> Set a + insert a (MkSet as) | a `elem` as = MkSet as + | otherwise = MkSet (a:as) + +A use of ``MkSet`` as a constructor (e.g. in the definition of +``makeSet``) gives rise to a ``(Eq a)`` constraint, as you would expect. +The new feature is that pattern-matching on ``MkSet`` (as in the +definition of ``insert``) makes *available* an ``(Eq a)`` context. In +implementation terms, the ``MkSet`` constructor has a hidden field that +stores the ``(Eq a)`` dictionary that is passed to ``MkSet``; so when +pattern-matching that dictionary becomes available for the right-hand +side of the match. In the example, the equality dictionary is used to +satisfy the equality constraint generated by the call to ``elem``, so +that the type of ``insert`` itself has no ``Eq`` constraint. + +For example, one possible application is to reify dictionaries: + +:: + + data NumInst a where + MkNumInst :: Num a => NumInst a + + intInst :: NumInst Int + intInst = MkNumInst + + plus :: NumInst a -> a -> a -> a + plus MkNumInst p q = p + q + +Here, a value of type ``NumInst a`` is equivalent to an explicit +``(Num a)`` dictionary. + +All this applies to constructors declared using the syntax of +:ref:`existential-with-context`. For example, the ``NumInst`` data type +above could equivalently be declared like this: + +:: + + data NumInst a + = Num a => MkNumInst (NumInst a) + +Notice that, unlike the situation when declaring an existential, there +is no ``forall``, because the ``Num`` constrains the data type's +universally quantified type variable ``a``. A constructor may have both +universal and existential type variables: for example, the following two +declarations are equivalent: + +:: + + data T1 a + = forall b. (Num a, Eq b) => MkT1 a b + data T2 a where + MkT2 :: (Num a, Eq b) => a -> b -> T2 a + +All this behaviour contrasts with Haskell 98's peculiar treatment of +contexts on a data type declaration (Section 4.2.1 of the Haskell 98 +Report). In Haskell 98 the definition + +:: + + data Eq a => Set' a = MkSet' [a] + +gives ``MkSet'`` the same type as ``MkSet`` above. But instead of +*making available* an ``(Eq a)`` constraint, pattern-matching on +``MkSet'`` *requires* an ``(Eq a)`` constraint! GHC faithfully +implements this behaviour, odd though it is. But for GADT-style +declarations, GHC's behaviour is much more useful, as well as much more +intuitive. + +The rest of this section gives further details about GADT-style data +type declarations. + +- The result type of each data constructor must begin with the type + constructor being defined. If the result type of all constructors has + the form ``T a1 ... an``, where ``a1 ... an`` are distinct type + variables, then the data type is *ordinary*; otherwise is a + *generalised* data type (:ref:`gadt`). + +- As with other type signatures, you can give a single signature for + several data constructors. In this example we give a single signature + for ``T1`` and ``T2``: + + :: + + data T a where + T1,T2 :: a -> T a + T3 :: T a + +- The type signature of each constructor is independent, and is + implicitly universally quantified as usual. In particular, the type + variable(s) in the "``data T a where``" header have no scope, and + different constructors may have different universally-quantified type + variables: + + :: + + data T a where -- The 'a' has no scope + T1,T2 :: b -> T b -- Means forall b. b -> T b + T3 :: T a -- Means forall a. T a + +- A constructor signature may mention type class constraints, which can + differ for different constructors. For example, this is fine: + + :: + + data T a where + T1 :: Eq b => b -> b -> T b + T2 :: (Show c, Ix c) => c -> [c] -> T c + + When pattern matching, these constraints are made available to + discharge constraints in the body of the match. For example: + + :: + + f :: T a -> String + f (T1 x y) | x==y = "yes" + | otherwise = "no" + f (T2 a b) = show a + + Note that ``f`` is not overloaded; the ``Eq`` constraint arising from + the use of ``==`` is discharged by the pattern match on ``T1`` and + similarly the ``Show`` constraint arising from the use of ``show``. + +- Unlike a Haskell-98-style data type declaration, the type variable(s) + in the "``data Set a where``" header have no scope. Indeed, one can + write a kind signature instead: + + :: + + data Set :: * -> * where ... + + or even a mixture of the two: + + :: + + data Bar a :: (* -> *) -> * where ... + + The type variables (if given) may be explicitly kinded, so we could + also write the header for ``Foo`` like this: + + :: + + data Bar a (b :: * -> *) where ... + +- You can use strictness annotations, in the obvious places in the + constructor type: + + :: + + data Term a where + Lit :: !Int -> Term Int + If :: Term Bool -> !(Term a) -> !(Term a) -> Term a + Pair :: Term a -> Term b -> Term (a,b) + +- You can use a ``deriving`` clause on a GADT-style data type + declaration. For example, these two declarations are equivalent + + :: + + data Maybe1 a where { + Nothing1 :: Maybe1 a ; + Just1 :: a -> Maybe1 a + } deriving( Eq, Ord ) + + data Maybe2 a = Nothing2 | Just2 a + deriving( Eq, Ord ) + +- The type signature may have quantified type variables that do not + appear in the result type: + + :: + + data Foo where + MkFoo :: a -> (a->Bool) -> Foo + Nil :: Foo + + Here the type variable ``a`` does not appear in the result type of + either constructor. Although it is universally quantified in the type + of the constructor, such a type variable is often called + "existential". Indeed, the above declaration declares precisely the + same type as the ``data Foo`` in :ref:`existential-quantification`. + + The type may contain a class context too, of course: + + :: + + data Showable where + MkShowable :: Show a => a -> Showable + +- You can use record syntax on a GADT-style data type declaration: + + :: + + data Person where + Adult :: { name :: String, children :: [Person] } -> Person + Child :: Show a => { name :: !String, funny :: a } -> Person + + As usual, for every constructor that has a field ``f``, the type of + field ``f`` must be the same (modulo alpha conversion). The ``Child`` + constructor above shows that the signature may have a context, + existentially-quantified variables, and strictness annotations, just + as in the non-record case. (NB: the "type" that follows the + double-colon is not really a type, because of the record syntax and + strictness annotations. A "type" of this form can appear only in a + constructor signature.) + +- Record updates are allowed with GADT-style declarations, only fields + that have the following property: the type of the field mentions no + existential type variables. + +- As in the case of existentials declared using the Haskell-98-like + record syntax (:ref:`existential-records`), record-selector functions + are generated only for those fields that have well-typed selectors. + Here is the example of that section, in GADT-style syntax: + + :: + + data Counter a where + NewCounter :: { _this :: self + , _inc :: self -> self + , _display :: self -> IO () + , tag :: a + } -> Counter a + + As before, only one selector function is generated here, that for + ``tag``. Nevertheless, you can still use all the field names in + pattern matching and record construction. + +- In a GADT-style data type declaration there is no obvious way to + specify that a data constructor should be infix, which makes a + difference if you derive ``Show`` for the type. (Data constructors + declared infix are displayed infix by the derived ``show``.) So GHC + implements the following design: a data constructor declared in a + GADT-style data type declaration is displayed infix by ``Show`` iff + (a) it is an operator symbol, (b) it has two arguments, (c) it has a + programmer-supplied fixity declaration. For example + + :: + + infix 6 (:--:) + data T a where + (:--:) :: Int -> Bool -> T Int + +.. _gadt: + +Generalised Algebraic Data Types (GADTs) +---------------------------------------- + +Generalised Algebraic Data Types generalise ordinary algebraic data +types by allowing constructors to have richer return types. Here is an +example: + +:: + + data Term a where + Lit :: Int -> Term Int + Succ :: Term Int -> Term Int + IsZero :: Term Int -> Term Bool + If :: Term Bool -> Term a -> Term a -> Term a + Pair :: Term a -> Term b -> Term (a,b) + +Notice that the return type of the constructors is not always +``Term a``, as is the case with ordinary data types. This generality +allows us to write a well-typed ``eval`` function for these ``Terms``: + +:: + + eval :: Term a -> a + eval (Lit i) = i + eval (Succ t) = 1 + eval t + eval (IsZero t) = eval t == 0 + eval (If b e1 e2) = if eval b then eval e1 else eval e2 + eval (Pair e1 e2) = (eval e1, eval e2) + +The key point about GADTs is that *pattern matching causes type +refinement*. For example, in the right hand side of the equation + +:: + + eval :: Term a -> a + eval (Lit i) = ... + +the type ``a`` is refined to ``Int``. That's the whole point! A precise +specification of the type rules is beyond what this user manual aspires +to, but the design closely follows that described in the paper `Simple +unification-based type inference for +GADTs <http://research.microsoft.com/%7Esimonpj/papers/gadt/>`__, (ICFP +2006). The general principle is this: *type refinement is only carried +out based on user-supplied type annotations*. So if no type signature is +supplied for ``eval``, no type refinement happens, and lots of obscure +error messages will occur. However, the refinement is quite general. For +example, if we had: + +:: + + eval :: Term a -> a -> a + eval (Lit i) j = i+j + +the pattern match causes the type ``a`` to be refined to ``Int`` +(because of the type of the constructor ``Lit``), and that refinement +also applies to the type of ``j``, and the result type of the ``case`` +expression. Hence the addition ``i+j`` is legal. + +These and many other examples are given in papers by Hongwei Xi, and Tim +Sheard. There is a longer introduction `on the +wiki <http://www.haskell.org/haskellwiki/GADT>`__, and Ralf Hinze's `Fun +with phantom +types <http://www.cs.ox.ac.uk/ralf.hinze/publications/With.pdf>`__ also +has a number of examples. Note that papers may use different notation to +that implemented in GHC. + +The rest of this section outlines the extensions to GHC that support +GADTs. The extension is enabled with ``-XGADTs``. The ``-XGADTs`` flag +also sets ``-XGADTSyntax`` and ``-XMonoLocalBinds``. + +- A GADT can only be declared using GADT-style syntax + (:ref:`gadt-style`); the old Haskell 98 syntax for data declarations + always declares an ordinary data type. The result type of each + constructor must begin with the type constructor being defined, but + for a GADT the arguments to the type constructor can be arbitrary + monotypes. For example, in the ``Term`` data type above, the type of + each constructor must end with ``Term ty``, but the ``ty`` need not + be a type variable (e.g. the ``Lit`` constructor). + +- It is permitted to declare an ordinary algebraic data type using + GADT-style syntax. What makes a GADT into a GADT is not the syntax, + but rather the presence of data constructors whose result type is not + just ``T a b``. + +- You cannot use a ``deriving`` clause for a GADT; only for an ordinary + data type. + +- As mentioned in :ref:`gadt-style`, record syntax is supported. For + example: + + :: + + data Term a where + Lit :: { val :: Int } -> Term Int + Succ :: { num :: Term Int } -> Term Int + Pred :: { num :: Term Int } -> Term Int + IsZero :: { arg :: Term Int } -> Term Bool + Pair :: { arg1 :: Term a + , arg2 :: Term b + } -> Term (a,b) + If :: { cnd :: Term Bool + , tru :: Term a + , fls :: Term a + } -> Term a + + However, for GADTs there is the following additional constraint: + every constructor that has a field ``f`` must have the same result + type (modulo alpha conversion) Hence, in the above example, we cannot + merge the ``num`` and ``arg`` fields above into a single name. + Although their field types are both ``Term Int``, their selector + functions actually have different types: + + :: + + num :: Term Int -> Term Int + arg :: Term Bool -> Term Int + +- When pattern-matching against data constructors drawn from a GADT, + for example in a ``case`` expression, the following rules apply: + + - The type of the scrutinee must be rigid. + + - The type of the entire ``case`` expression must be rigid. + + - The type of any free variable mentioned in any of the ``case`` + alternatives must be rigid. + + A type is "rigid" if it is completely known to the compiler at its + binding site. The easiest way to ensure that a variable a rigid type + is to give it a type signature. For more precise details see `Simple + unification-based type inference for + GADTs <http://research.microsoft.com/%7Esimonpj/papers/gadt>`__. The + criteria implemented by GHC are given in the Appendix. + +.. _deriving: + +Extensions to the "deriving" mechanism +====================================== + +.. _deriving-inferred: + +Inferred context for deriving clauses +------------------------------------- + +The Haskell Report is vague about exactly when a ``deriving`` clause is +legal. For example: + +:: + + data T0 f a = MkT0 a deriving( Eq ) + data T1 f a = MkT1 (f a) deriving( Eq ) + data T2 f a = MkT2 (f (f a)) deriving( Eq ) + +The natural generated ``Eq`` code would result in these instance +declarations: + +:: + + instance Eq a => Eq (T0 f a) where ... + instance Eq (f a) => Eq (T1 f a) where ... + instance Eq (f (f a)) => Eq (T2 f a) where ... + +The first of these is obviously fine. The second is still fine, although +less obviously. The third is not Haskell 98, and risks losing +termination of instances. + +GHC takes a conservative position: it accepts the first two, but not the +third. The rule is this: each constraint in the inferred instance +context must consist only of type variables, with no repetitions. + +This rule is applied regardless of flags. If you want a more exotic +context, you can write it yourself, using the `standalone deriving +mechanism <#stand-alone-deriving>`__. + +.. _stand-alone-deriving: + +Stand-alone deriving declarations +--------------------------------- + +GHC allows stand-alone ``deriving`` declarations, enabled by +``-XStandaloneDeriving``: + +:: + + data Foo a = Bar a | Baz String + + deriving instance Eq a => Eq (Foo a) + +The syntax is identical to that of an ordinary instance declaration +apart from (a) the keyword ``deriving``, and (b) the absence of the +``where`` part. + +However, standalone deriving differs from a ``deriving`` clause in a +number of important ways: + +- The standalone deriving declaration does not need to be in the same + module as the data type declaration. (But be aware of the dangers of + orphan instances (:ref:`orphan-modules`). + +- You must supply an explicit context (in the example the context is + ``(Eq a)``), exactly as you would in an ordinary instance + declaration. (In contrast, in a ``deriving`` clause attached to a + data type declaration, the context is inferred.) + +- Unlike a ``deriving`` declaration attached to a ``data`` declaration, + the instance can be more specific than the data type (assuming you + also use ``-XFlexibleInstances``, :ref:`instance-rules`). Consider + for example + + :: + + data Foo a = Bar a | Baz String + + deriving instance Eq a => Eq (Foo [a]) + deriving instance Eq a => Eq (Foo (Maybe a)) + + This will generate a derived instance for ``(Foo [a])`` and + ``(Foo (Maybe a))``, but other types such as ``(Foo (Int,Bool))`` + will not be an instance of ``Eq``. + +- Unlike a ``deriving`` declaration attached to a ``data`` declaration, + GHC does not restrict the form of the data type. Instead, GHC simply + generates the appropriate boilerplate code for the specified class, + and typechecks it. If there is a type error, it is your problem. (GHC + will show you the offending code if it has a type error.) + + The merit of this is that you can derive instances for GADTs and + other exotic data types, providing only that the boilerplate code + does indeed typecheck. For example: + + :: + + data T a where + T1 :: T Int + T2 :: T Bool + + deriving instance Show (T a) + + In this example, you cannot say ``... deriving( Show )`` on the data + type declaration for ``T``, because ``T`` is a GADT, but you *can* + generate the instance declaration using stand-alone deriving. + + The down-side is that, if the boilerplate code fails to typecheck, + you will get an error message about that code, which you did not + write. Whereas, with a ``deriving`` clause the side-conditions are + necessarily more conservative, but any error message may be more + comprehensible. + +In other ways, however, a standalone deriving obeys the same rules as +ordinary deriving: + +- A ``deriving instance`` declaration must obey the same rules + concerning form and termination as ordinary instance declarations, + controlled by the same flags; see :ref:`instance-decls`. + +- The stand-alone syntax is generalised for newtypes in exactly the + same way that ordinary ``deriving`` clauses are generalised + (:ref:`newtype-deriving`). For example: + + :: + + newtype Foo a = MkFoo (State Int a) + + deriving instance MonadState Int Foo + + GHC always treats the *last* parameter of the instance (``Foo`` in + this example) as the type whose instance is being derived. + +.. _deriving-extra: + +Deriving instances of extra classes (``Data``, etc.) +---------------------------------------------------- + +Haskell 98 allows the programmer to add "``deriving( Eq, Ord )``" to a +data type declaration, to generate a standard instance declaration for +classes specified in the ``deriving`` clause. In Haskell 98, the only +classes that may appear in the ``deriving`` clause are the standard +classes ``Eq``, ``Ord``, ``Enum``, ``Ix``, ``Bounded``, ``Read``, and +``Show``. + +GHC extends this list with several more classes that may be +automatically derived: + +- With ``-XDeriveGeneric``, you can derive instances of the classes + ``Generic`` and ``Generic1``, defined in ``GHC.Generics``. You can + use these to define generic functions, as described in + :ref:`generic-programming`. + +- With ``-XDeriveFunctor``, you can derive instances of the class + ``Functor``, defined in ``GHC.Base``. See :ref:`deriving-functor`. + +- With ``-XDeriveDataTypeable``, you can derive instances of the class + ``Data``, defined in ``Data.Data``. See :ref:`deriving-typeable` for + deriving ``Typeable``. + +- With ``-XDeriveFoldable``, you can derive instances of the class + ``Foldable``, defined in ``Data.Foldable``. See + :ref:`deriving-foldable`. + +- With ``-XDeriveTraversable``, you can derive instances of the class + ``Traversable``, defined in ``Data.Traversable``. Since the + ``Traversable`` instance dictates the instances of ``Functor`` and + ``Foldable``, you'll probably want to derive them too, so + ``-XDeriveTraversable`` implies ``-XDeriveFunctor`` and + ``-XDeriveFoldable``. See :ref:`deriving-traversable`. + +- With ``-XDeriveLift``, you can derive instances of the class ``Lift``, defined + in the ``Language.Haskell.TH.Syntax`` module of the ``template-haskell`` + package. See :ref:`deriving-lift`. + +You can also use a standalone deriving declaration instead (see +:ref:`stand-alone-deriving`). + +In each case the appropriate class must be in scope before it can be +mentioned in the ``deriving`` clause. + +.. _deriving-functor: + +Deriving ``Functor`` instances +------------------------------ + +With ``-XDeriveFunctor``, one can derive ``Functor`` instances for data +types of kind ``* -> *``. For example, this declaration: + +:: + + data Example a = Ex a Char (Example a) (Example Char) + deriving Functor + +would generate the following instance: + +:: + + instance Functor Example where + fmap f (Ex a1 a2 a3 a4) = Ex (f a1) a2 (fmap f a3) a4 + +The basic algorithm for ``-XDeriveFunctor`` walks the arguments of each +constructor of a data type, applying a mapping function depending on the +type of each argument. Suppose we are deriving ``Functor`` for a data +type whose last type parameter is ``a``. Then we write the derivation of +``fmap`` code over the type variable ``a`` for type ``b`` as +``$(fmap 'a 'b)``. + +- If the argument's type is ``a``, then map over it. + + :: + + $(fmap 'a 'a) = f + +- If the argument's type does not mention ``a``, then do nothing to it. + + :: + + $(fmap 'a 'b) = \x -> x -- when b does not contain a + +- If the argument has a tuple type, generate map code for each of its + arguments. + + :: + + $(fmap 'a '(b1,b2)) = \x -> case x of (x1,x2) -> ($(fmap 'a 'b1) x1, $(fmap 'a 'b2) x2) + +- If the argument's type is a data type that mentions ``a``, apply + ``fmap`` to it with the generated map code for the data type's last + type parameter. + + :: + + $(fmap 'a '(T b1 b2)) = fmap $(fmap 'a 'b2) -- when a only occurs in the last parameter, b2 + +- If the argument has a function type, apply generated ``$(fmap)`` code + to the result type, and apply generated ``$(cofmap)`` code to the + argument type. + + :: + + $(fmap 'a '(b -> c)) = \x b -> $(fmap 'a' 'c) (x ($(cofmap 'a 'b) b)) + + ``$(cofmap)`` is needed because the type parameter ``a`` can occur in + a contravariant position, which means we need to derive a function + like: + + :: + + cofmap :: (a -> b) -> f b -> f a + + This is pretty much the same as ``$(fmap)``, only without the + ``$(cofmap 'a 'a)`` case: + + :: + + $(cofmap 'a 'b) = \x -> x -- when b does not contain a + $(cofmap 'a 'a) = error "type variable in contravariant position" + $(cofmap 'a '(b1,b2)) = \x -> case x of (x1,x2) -> ($(cofmap 'a 'b1) x1, $(cofmap 'a 'b2) x2) + $(cofmap 'a '[b]) = map $(cofmap 'a 'b) + $(cofmap 'a '(T b1 b2)) = fmap $(cofmap 'a 'b2) -- when a only occurs in the last parameter, b2 + $(cofmap 'a '(b -> c)) = \x b -> $(cofmap 'a' 'c) (x ($(fmap 'a 'c) b)) + + For more information on contravariance, see + :ghc-wiki:`this wiki page <Commentary/Compiler/DeriveFunctor#Covariantandcontravariantpositions>`. + +A data type can have a derived ``Functor`` instance if: + +- It has at least one type parameter. + +- It does not use the last type parameter contravariantly. + +- It does not use the last type parameter in the "wrong place" in any + of the argument data types. For example, in: + + :: + + data Right a = Right [a] (Either Int a) + + the type parameter ``a`` is only ever used as the last type argument + in ``[]`` and ``Either``, so both ``[a]`` and ``Either Int a`` can be + ``fmap``\ ped. However, in: + + :: + + data Wrong a = Wrong (Either a a) + + the type variable ``a`` appears in a position other than the last, so + trying to ``fmap`` an ``Either a a`` value would not typecheck in a + ``Functor`` instance. Note that there are two exceptions to this + rule: tuple and function types, as described above. + +- Its last type variable cannot be used in a ``-XDatatypeContexts`` + constraint. + +- Its last type variable cannot be used in an + ``-XExistentialQuantification`` or ``-XGADTs`` constraint. + +.. _deriving-foldable: + +Deriving ``Foldable`` instances +------------------------------- + +With ``-XDeriveFoldable``, one can derive ``Foldable`` instances for +data types of kind ``* -> *``. For example, this declaration: + +:: + + data Example a = Ex a Char (Example a) (Example Char) + deriving Functor + +would generate the following instance: + +:: + + instance Foldable Example where + foldr f z (Ex a1 a2 a3 a4) = f a1 (foldr f z a3) + foldMap f (Ex a1 a2 a3 a4) = mappend (f a1) + (mappend mempty + (mappend (foldMap f a3) + mempty)) + +The algorithm for ``-XDeriveFoldable`` is very similar to that of +``-XDeriveFunctor``, except that ``Foldable`` instances are not possible +for function types. The cases are: + +:: + + $(foldr 'a 'b) = \x z -> z -- when b does not contain a + $(foldr 'a 'a) = f + $(foldr 'a '(b1,b2)) = \x z -> case x of (x1,x2) -> $(foldr 'a 'b1) x1 ( $(foldr 'a 'b2) x2 z ) + $(foldr 'a '(T b1 b2)) = \x z -> foldr $(foldr 'a 'b2) z x -- when a only occurs in the last parameter, b2 + +Another difference between ``-XDeriveFoldable`` and ``-XDeriveFunctor`` +is that ``-XDeriveFoldable`` instances can be derived for data types +with existential constraints. For example, the following data type: + +:: + + data E a where + E1 :: (a ~ Int) => a -> E a + E2 :: Int -> E Int + E3 :: (a ~ Int) => a -> E Int + E4 :: (a ~ Int) => Int -> E a + + deriving instance Foldable E + +would have the following ``Foldable`` instance: + +:: + + instance Foldable E where + foldr f z (E1 e) = f e z + foldr f z (E2 e) = z + foldr f z (E3 e) = z + foldr f z (E4 e) = z + + foldMap f (E1 e) = f e + foldMap f (E2 e) = mempty + foldMap f (E3 e) = mempty + foldMap f (E4 e) = mempty + +Notice that only the argument in ``E1`` is folded over. This is because +we only fold over constructor arguments (1) whose types are +syntactically equivalent to the last type parameter and (2) when the +last type parameter is not refined to a specific type. Only ``E1`` +satisfies both of these criteria. For more information, see `this wiki +page :ghc-wiki:<Commentary/Compiler/DeriveFunctor>`. + +.. _deriving-traversable: + +Deriving ``Traversable`` instances +---------------------------------- + +With ``-XDeriveTraversable``, one can derive ``Traversable`` instances +for data types of kind ``* -> *``. For example, this declaration: + +:: + + data Example a = Ex a Char (Example a) (Example Char) + deriving Functor + +would generate the following instance: + +:: + + instance Foldable Example where + traverse f (Ex a1 a2 a3 a4) + = fmap Ex (f a) + <*> pure a2 + <*> traverse f a3 + <*> pure a4 + +The algorithm for ``-XDeriveTraversable`` is very similar to that of +``-XDeriveTraversable``, except that ``Traversable`` instances are not +possible for function types. The cases are: + +:: + + 1812 $(traverse 'a 'b) = pure -- when b does not contain a + 1813 $(traverse 'a 'a) = f + 1814 $(traverse 'a '(b1,b2)) = \x -> case x of (x1,x2) -> fmap (,) $(traverse 'a 'b1) x1 <*> $(traverse 'a 'b2) x2 + 1815 $(traverse 'a '(T b1 b2)) = traverse $(traverse 'a 'b2) -- when a only occurs in the last parameter, b2 + +.. _deriving-typeable: + +Deriving ``Typeable`` instances +------------------------------- + +The class ``Typeable`` is very special: + +- ``Typeable`` is kind-polymorphic (see :ref:`kind-polymorphism`). + +- GHC has a custom solver for discharging constraints that involve + class ``Typeable``, and handwritten instances are forbidden. This + ensures that the programmer cannot subvert the type system by writing + bogus instances. + +- Derived instances of ``Typeable`` are ignored, and may be reported as + an error in a later version of the compiler. + +- The rules for solving \`Typeable\` constraints are as follows: + + - A concrete type constructor applied to some types. + + :: + + instance (Typeable t1, .., Typeable t_n) => + Typeable (T t1 .. t_n) + + This rule works for any concrete type constructor, including type + constructors with polymorphic kinds. The only restriction is that + if the type constructor has a polymorphic kind, then it has to be + applied to all of its kinds parameters, and these kinds need to be + concrete (i.e., they cannot mention kind variables). + + - :: + + A type variable applied to some types. + instance (Typeable f, Typeable t1, .., Typeable t_n) => + Typeable (f t1 .. t_n) + + - :: + + A concrete type literal. + instance Typeable 0 -- Type natural literals + instance Typeable "Hello" -- Type-level symbols + +.. _deriving-lift: + +Deriving ``Lift`` instances +--------------------------- + +The class ``Lift``, unlike other derivable classes, lives in +``template-haskell`` instead of ``base``. Having a data type be an instance of +``Lift`` permits its values to be promoted to Template Haskell expressions (of +type ``ExpQ``), which can then be spliced into Haskell source code. + +Here is an example of how one can derive ``Lift``: + +:: + + {-# LANGUAGE DeriveLift #-} + module Bar where + + import Language.Haskell.TH.Syntax + + data Foo a = Foo a | a :^: a deriving Lift + + {- + instance (Lift a) => Lift (Foo a) where + lift (Foo a) + = appE + (conE + (mkNameG_d "package-name" "Bar" "Foo")) + (lift a) + lift (u :^: v) + = infixApp + (lift u) + (conE + (mkNameG_d "package-name" "Bar" ":^:")) + (lift v) + -} + + ----- + {-# LANGUAGE TemplateHaskell #-} + module Baz where + + import Bar + import Language.Haskell.TH.Lift + + foo :: Foo String + foo = $(lift $ Foo "foo") + + fooExp :: Lift a => Foo a -> Q Exp + fooExp f = [| f |] + +``-XDeriveLift`` also works for certain unboxed types (``Addr#``, ``Char#``, +``Double#``, ``Float#``, ``Int#``, and ``Word#``): + +:: + + {-# LANGUAGE DeriveLift, MagicHash #-} + module Unboxed where + + import GHC.Exts + import Language.Haskell.TH.Syntax + + data IntHash = IntHash Int# deriving Lift + + {- + instance Lift IntHash where + lift (IntHash i) + = appE + (conE + (mkNameG_d "package-name" "Unboxed" "IntHash")) + (litE + (intPrimL (toInteger (I# i)))) + -} + + +.. _newtype-deriving: + +Generalised derived instances for newtypes +------------------------------------------ + +When you define an abstract type using ``newtype``, you may want the new +type to inherit some instances from its representation. In Haskell 98, +you can inherit instances of ``Eq``, ``Ord``, ``Enum`` and ``Bounded`` +by deriving them, but for any other classes you have to write an +explicit instance declaration. For example, if you define + +:: + + newtype Dollars = Dollars Int + +and you want to use arithmetic on ``Dollars``, you have to explicitly +define an instance of ``Num``: + +:: + + instance Num Dollars where + Dollars a + Dollars b = Dollars (a+b) + ... + +All the instance does is apply and remove the ``newtype`` constructor. +It is particularly galling that, since the constructor doesn't appear at +run-time, this instance declaration defines a dictionary which is +*wholly equivalent* to the ``Int`` dictionary, only slower! + +.. _generalized-newtype-deriving: + +Generalising the deriving clause +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +GHC now permits such instances to be derived instead, using the flag +``-XGeneralizedNewtypeDeriving``, so one can write + +:: + + newtype Dollars = Dollars Int deriving (Eq,Show,Num) + +and the implementation uses the *same* ``Num`` dictionary for +``Dollars`` as for ``Int``. Notionally, the compiler derives an instance +declaration of the form + +:: + + instance Num Int => Num Dollars + +which just adds or removes the ``newtype`` constructor according to the +type. + +We can also derive instances of constructor classes in a similar way. +For example, suppose we have implemented state and failure monad +transformers, such that + +:: + + instance Monad m => Monad (State s m) + instance Monad m => Monad (Failure m) + +In Haskell 98, we can define a parsing monad by + +:: + + type Parser tok m a = State [tok] (Failure m) a + +which is automatically a monad thanks to the instance declarations +above. With the extension, we can make the parser type abstract, without +needing to write an instance of class ``Monad``, via + +:: + + newtype Parser tok m a = Parser (State [tok] (Failure m) a) + deriving Monad + +In this case the derived instance declaration is of the form + +:: + + instance Monad (State [tok] (Failure m)) => Monad (Parser tok m) + +Notice that, since ``Monad`` is a constructor class, the instance is a +*partial application* of the new type, not the entire left hand side. We +can imagine that the type declaration is "eta-converted" to generate the +context of the instance declaration. + +We can even derive instances of multi-parameter classes, provided the +newtype is the last class parameter. In this case, a "partial +application" of the class appears in the ``deriving`` clause. For +example, given the class + +:: + + class StateMonad s m | m -> s where ... + instance Monad m => StateMonad s (State s m) where ... + +then we can derive an instance of ``StateMonad`` for ``Parser`` by + +:: + + newtype Parser tok m a = Parser (State [tok] (Failure m) a) + deriving (Monad, StateMonad [tok]) + +The derived instance is obtained by completing the application of the +class to the new type: + +:: + + instance StateMonad [tok] (State [tok] (Failure m)) => + StateMonad [tok] (Parser tok m) + +As a result of this extension, all derived instances in newtype +declarations are treated uniformly (and implemented just by reusing the +dictionary for the representation type), *except* ``Show`` and ``Read``, +which really behave differently for the newtype and its representation. + +A more precise specification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A derived instance is derived only for declarations of these forms +(after expansion of any type synonyms) + +:: + + newtype T v1..vn = MkT (t vk+1..vn) deriving (C t1..tj) + newtype instance T s1..sk vk+1..vn = MkT (t vk+1..vn) deriving (C t1..tj) + +where + +- ``v1..vn`` are type variables, and ``t``, ``s1..sk``, ``t1..tj`` are + types. + +- The ``(C t1..tj)`` is a partial applications of the class ``C``, + where the arity of ``C`` is exactly ``j+1``. That is, ``C`` lacks + exactly one type argument. + +- ``k`` is chosen so that ``C t1..tj (T v1...vk)`` is well-kinded. (Or, + in the case of a ``data instance``, so that ``C t1..tj (T s1..sk)`` + is well kinded.) + +- The type ``t`` is an arbitrary type. + +- The type variables ``vk+1...vn`` do not occur in the types ``t``, + ``s1..sk``, or ``t1..tj``. + +- ``C`` is not ``Read``, ``Show``, ``Typeable``, or ``Data``. These + classes should not "look through" the type or its constructor. You + can still derive these classes for a newtype, but it happens in the + usual way, not via this new mechanism. + +- It is safe to coerce each of the methods of ``C``. That is, the + missing last argument to ``C`` is not used at a nominal role in any + of the ``C``'s methods. (See :ref:`roles`.) + +Then the derived instance declaration is of the form + +:: + + instance C t1..tj t => C t1..tj (T v1...vk) + +As an example which does *not* work, consider + +:: + + newtype NonMonad m s = NonMonad (State s m s) deriving Monad + +Here we cannot derive the instance + +:: + + instance Monad (State s m) => Monad (NonMonad m) + +because the type variable ``s`` occurs in ``State s m``, and so cannot +be "eta-converted" away. It is a good thing that this ``deriving`` +clause is rejected, because ``NonMonad m`` is not, in fact, a monad --- +for the same reason. Try defining ``>>=`` with the correct type: you +won't be able to. + +Notice also that the *order* of class parameters becomes important, +since we can only derive instances for the last one. If the +``StateMonad`` class above were instead defined as + +:: + + class StateMonad m s | m -> s where ... + +then we would not have been able to derive an instance for the +``Parser`` type above. We hypothesise that multi-parameter classes +usually have one "main" parameter for which deriving new instances is +most interesting. + +Lastly, all of this applies only for classes other than ``Read``, +``Show``, ``Typeable``, and ``Data``, for which the built-in derivation +applies (section 4.3.3. of the Haskell Report). (For the standard +classes ``Eq``, ``Ord``, ``Ix``, and ``Bounded`` it is immaterial +whether the standard method is used or the one described here.) + +.. _derive-any-class: + +Deriving any other class +------------------------ + +With ``-XDeriveAnyClass`` you can derive any other class. The compiler +will simply generate an empty instance. The instance context will be +generated according to the same rules used when deriving ``Eq``. This is +mostly useful in classes whose `minimal set <#minimal-pragma>`__ is +empty, and especially when writing `generic +functions <#generic-programming>`__. In case you try to derive some +class on a newtype, and ``-XGeneralizedNewtypeDeriving`` is also on, +``-XDeriveAnyClass`` takes precedence. + +.. _type-class-extensions: + +Class and instances declarations +================================ + +.. _multi-param-type-classes: + +Class declarations +------------------ + +This section, and the next one, documents GHC's type-class extensions. +There's lots of background in the paper `Type classes: exploring the +design +space <http://research.microsoft.com/~simonpj/Papers/type-class-design-space/>`__ +(Simon Peyton Jones, Mark Jones, Erik Meijer). + +Multi-parameter type classes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Multi-parameter type classes are permitted, with flag +``-XMultiParamTypeClasses``. For example: + +:: + + class Collection c a where + union :: c a -> c a -> c a + ...etc. + +.. _superclass-rules: + +The superclasses of a class declaration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In Haskell 98 the context of a class declaration (which introduces +superclasses) must be simple; that is, each predicate must consist of a +class applied to type variables. The flag ``-XFlexibleContexts`` +(:ref:`flexible-contexts`) lifts this restriction, so that the only +restriction on the context in a class declaration is that the class +hierarchy must be acyclic. So these class declarations are OK: + +:: + + class Functor (m k) => FiniteMap m k where + ... + + class (Monad m, Monad (t m)) => Transform t m where + lift :: m a -> (t m) a + +As in Haskell 98, The class hierarchy must be acyclic. However, the +definition of "acyclic" involves only the superclass relationships. For +example, this is OK: + +:: + + class C a where { + op :: D b => a -> b -> b + } + + class C a => D a where { ... } + +Here, ``C`` is a superclass of ``D``, but it's OK for a class operation +``op`` of ``C`` to mention ``D``. (It would not be OK for ``D`` to be a +superclass of ``C``.) + +With the extension that adds a `kind of +constraints <#constraint-kind>`__, you can write more exotic superclass +definitions. The superclass cycle check is even more liberal in these +case. For example, this is OK: + +:: + + class A cls c where + meth :: cls c => c -> c + + class A B c => B c where + +A superclass context for a class ``C`` is allowed if, after expanding +type synonyms to their right-hand-sides, and uses of classes (other than +``C``) to their superclasses, ``C`` does not occur syntactically in the +context. + +.. _class-method-types: + +Class method types +~~~~~~~~~~~~~~~~~~ + +Haskell 98 prohibits class method types to mention constraints on the +class type variable, thus: + +:: + + class Seq s a where + fromList :: [a] -> s a + elem :: Eq a => a -> s a -> Bool + +The type of ``elem`` is illegal in Haskell 98, because it contains the +constraint ``Eq a``, which constrains only the class type variable (in +this case ``a``). + +GHC lifts this restriction with language extension +``-XConstrainedClassMethods``. The restriction is a pretty stupid one in +the first place, so ``-XConstrainedClassMethods`` is implied by +``-XMultiParamTypeClasses``. + +.. _class-default-signatures: + +Default method signatures +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Haskell 98 allows you to define a default implementation when declaring +a class: + +:: + + class Enum a where + enum :: [a] + enum = [] + +The type of the ``enum`` method is ``[a]``, and this is also the type of +the default method. You can lift this restriction and give another type +to the default method using the flag ``-XDefaultSignatures``. For +instance, if you have written a generic implementation of enumeration in +a class ``GEnum`` with method ``genum`` in terms of ``GHC.Generics``, +you can specify a default method that uses that generic implementation: + +:: + + class Enum a where + enum :: [a] + default enum :: (Generic a, GEnum (Rep a)) => [a] + enum = map to genum + +We reuse the keyword ``default`` to signal that a signature applies to +the default method only; when defining instances of the ``Enum`` class, +the original type ``[a]`` of ``enum`` still applies. When giving an +empty instance, however, the default implementation ``map to genum`` is +filled-in, and type-checked with the type +``(Generic a, GEnum (Rep a)) => [a]``. + +We use default signatures to simplify generic programming in GHC +(:ref:`generic-programming`). + +.. _nullary-type-classes: + +Nullary type classes +~~~~~~~~~~~~~~~~~~~~ + +Nullary (no parameter) type classes are enabled with ``-XMultiTypeClasses``; +historically, they were enabled with the (now deprecated) +``-XNullaryTypeClasses``. Since there are no available parameters, there can be +at most one instance of a nullary class. A nullary type class might be used to +document some assumption in a type signature (such as reliance on the Riemann +hypothesis) or add some globally configurable settings in a program. For +example, +:: + + class RiemannHypothesis where + assumeRH :: a -> a + + -- Deterministic version of the Miller test + -- correctness depends on the generalised Riemann hypothesis + isPrime :: RiemannHypothesis => Integer -> Bool + isPrime n = assumeRH (...) + +The type signature of ``isPrime`` informs users that its correctness depends on +an unproven conjecture. If the function is used, the user has to acknowledge the +dependence with: +:: + + instance RiemannHypothesis where + assumeRH = id + +.. _functional-dependencies: + +Functional dependencies +----------------------- + +Functional dependencies are implemented as described by Mark Jones in +“`Type Classes with Functional +Dependencies <http://citeseer.ist.psu.edu/jones00type.html>`__”, Mark +P. Jones, In Proceedings of the 9th European Symposium on Programming, +ESOP 2000, Berlin, Germany, March 2000, Springer-Verlag LNCS 1782, . + +Functional dependencies are introduced by a vertical bar in the syntax +of a class declaration; e.g. + +:: + + class (Monad m) => MonadState s m | m -> s where ... + + class Foo a b c | a b -> c where ... + +There should be more documentation, but there isn't (yet). Yell if you +need it. + +Rules for functional dependencies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In a class declaration, all of the class type variables must be +reachable (in the sense mentioned in :ref:`flexible-contexts`) from the +free variables of each method type. For example: + +:: + + class Coll s a where + empty :: s + insert :: s -> a -> s + +is not OK, because the type of ``empty`` doesn't mention ``a``. +Functional dependencies can make the type variable reachable: + +:: + + class Coll s a | s -> a where + empty :: s + insert :: s -> a -> s + +Alternatively ``Coll`` might be rewritten + +:: + + class Coll s a where + empty :: s a + insert :: s a -> a -> s a + +which makes the connection between the type of a collection of ``a``'s +(namely ``(s a)``) and the element type ``a``. Occasionally this really +doesn't work, in which case you can split the class like this: + +:: + + class CollE s where + empty :: s + + class CollE s => Coll s a where + insert :: s -> a -> s + +Background on functional dependencies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following description of the motivation and use of functional +dependencies is taken from the Hugs user manual, reproduced here (with +minor changes) by kind permission of Mark Jones. + +Consider the following class, intended as part of a library for +collection types: + +:: + + class Collects e ce where + empty :: ce + insert :: e -> ce -> ce + member :: e -> ce -> Bool + +The type variable ``e`` used here represents the element type, while ``ce`` is +the type of the container itself. Within this framework, we might want to define +instances of this class for lists or characteristic functions (both of which can +be used to represent collections of any equality type), bit sets (which can be +used to represent collections of characters), or hash tables (which can be used +to represent any collection whose elements have a hash function). Omitting +standard implementation details, this would lead to the following declarations: + +:: + + instance Eq e => Collects e [e] where ... + instance Eq e => Collects e (e -> Bool) where ... + instance Collects Char BitSet where ... + instance (Hashable e, Collects a ce) + => Collects e (Array Int ce) where ... + +All this looks quite promising; we have a class and a range of +interesting implementations. Unfortunately, there are some serious +problems with the class declaration. First, the empty function has an +ambiguous type: + +:: + + empty :: Collects e ce => ce + +By "ambiguous" we mean that there is a type variable ``e`` that appears on +the left of the ``=>`` symbol, but not on the right. The problem with +this is that, according to the theoretical foundations of Haskell +overloading, we cannot guarantee a well-defined semantics for any term +with an ambiguous type. + +We can sidestep this specific problem by removing the empty member from +the class declaration. However, although the remaining members, insert +and member, do not have ambiguous types, we still run into problems when +we try to use them. For example, consider the following two functions: + +:: + + f x y = insert x . insert y + g = f True 'a' + +for which GHC infers the following types: + +:: + + f :: (Collects a c, Collects b c) => a -> b -> c -> c + g :: (Collects Bool c, Collects Char c) => c -> c + +Notice that the type for ``f`` allows the two parameters ``x`` and ``y`` to be +assigned different types, even though it attempts to insert each of the +two values, one after the other, into the same collection. If we're +trying to model collections that contain only one type of value, then +this is clearly an inaccurate type. Worse still, the definition for g is +accepted, without causing a type error. As a result, the error in this +code will not be flagged at the point where it appears. Instead, it will +show up only when we try to use ``g``, which might even be in a different +module. + +An attempt to use constructor classes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Faced with the problems described above, some Haskell programmers might +be tempted to use something like the following version of the class +declaration: + +:: + + class Collects e c where + empty :: c e + insert :: e -> c e -> c e + member :: e -> c e -> Bool + +The key difference here is that we abstract over the type constructor ``c`` +that is used to form the collection type ``c e``, and not over that +collection type itself, represented by ``ce`` in the original class +declaration. This avoids the immediate problems that we mentioned above: +empty has type ``Collects e c => c e``, which is not ambiguous. + +The function ``f`` from the previous section has a more accurate type: + +:: + + f :: (Collects e c) => e -> e -> c e -> c e + +The function ``g`` from the previous section is now rejected with a type +error as we would hope because the type of ``f`` does not allow the two +arguments to have different types. This, then, is an example of a +multiple parameter class that does actually work quite well in practice, +without ambiguity problems. There is, however, a catch. This version of +the ``Collects`` class is nowhere near as general as the original class +seemed to be: only one of the four instances for ``Collects`` given +above can be used with this version of Collects because only one of them—the +instance for lists—has a collection type that can be written in the form ``c +e``, for some type constructor ``c``, and element type ``e``. + +Adding functional dependencies +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To get a more useful version of the ``Collects`` class, GHC provides a +mechanism that allows programmers to specify dependencies between the +parameters of a multiple parameter class (For readers with an interest +in theoretical foundations and previous work: The use of dependency +information can be seen both as a generalisation of the proposal for +"parametric type classes" that was put forward by Chen, Hudak, and +Odersky, or as a special case of Mark Jones's later framework for +"improvement" of qualified types. The underlying ideas are also +discussed in a more theoretical and abstract setting in a manuscript +[implparam], where they are identified as one point in a general design +space for systems of implicit parameterisation). To start with an +abstract example, consider a declaration such as: + +:: + + class C a b where ... + +which tells us simply that ``C`` can be thought of as a binary relation on +types (or type constructors, depending on the kinds of ``a`` and ``b``). Extra +clauses can be included in the definition of classes to add information +about dependencies between parameters, as in the following examples: + +:: + + class D a b | a -> b where ... + class E a b | a -> b, b -> a where ... + +The notation ``a -> b`` used here between the ``|`` and ``where`` symbols — +not to be confused with a function type — indicates that the a +parameter uniquely determines the ``b`` parameter, and might be read as "``a`` +determines ``b``." Thus ``D`` is not just a relation, but actually a (partial) +function. Similarly, from the two dependencies that are included in the +definition of ``E``, we can see that ``E`` represents a (partial) one-to-one +mapping between types. + +More generally, dependencies take the form ``x1 ... xn -> y1 ... ym``, +where ``x1``, ..., ``xn``, and ``y1``, ..., ``yn`` are type variables with n>0 and m>=0, +meaning that the ``y`` parameters are uniquely determined by the ``x`` +parameters. Spaces can be used as separators if more than one variable +appears on any single side of a dependency, as in ``t -> a b``. Note +that a class may be annotated with multiple dependencies using commas as +separators, as in the definition of ``E`` above. Some dependencies that we +can write in this notation are redundant, and will be rejected because +they don't serve any useful purpose, and may instead indicate an error +in the program. Examples of dependencies like this include ``a -> a``, +``a -> a a``, ``a ->``, etc. There can also be some redundancy if +multiple dependencies are given, as in ``a->b``, ``b->c``, ``a->c``, and +in which some subset implies the remaining dependencies. Examples like +this are not treated as errors. Note that dependencies appear only in +class declarations, and not in any other part of the language. In +particular, the syntax for instance declarations, class constraints, and +types is completely unchanged. + +By including dependencies in a class declaration, we provide a mechanism +for the programmer to specify each multiple parameter class more +precisely. The compiler, on the other hand, is responsible for ensuring +that the set of instances that are in scope at any given point in the +program is consistent with any declared dependencies. For example, the +following pair of instance declarations cannot appear together in the +same scope because they violate the dependency for ``D``, even though either +one on its own would be acceptable: + +:: + + instance D Bool Int where ... + instance D Bool Char where ... + +Note also that the following declaration is not allowed, even by itself: + +:: + + instance D [a] b where ... + +The problem here is that this instance would allow one particular choice +of ``[a]`` to be associated with more than one choice for ``b``, which +contradicts the dependency specified in the definition of ``D``. More +generally, this means that, in any instance of the form: + +:: + + instance D t s where ... + +for some particular types ``t`` and ``s``, the only variables that can appear in +``s`` are the ones that appear in ``t``, and hence, if the type ``t`` is known, +then ``s`` will be uniquely determined. + +The benefit of including dependency information is that it allows us to +define more general multiple parameter classes, without ambiguity +problems, and with the benefit of more accurate types. To illustrate +this, we return to the collection class example, and annotate the +original definition of ``Collects`` with a simple dependency: + +:: + + class Collects e ce | ce -> e where + empty :: ce + insert :: e -> ce -> ce + member :: e -> ce -> Bool + +The dependency ``ce -> e`` here specifies that the type ``e`` of elements is +uniquely determined by the type of the collection ``ce``. Note that both +parameters of Collects are of kind ``*``; there are no constructor classes +here. Note too that all of the instances of ``Collects`` that we gave +earlier can be used together with this new definition. + +What about the ambiguity problems that we encountered with the original +definition? The empty function still has type ``Collects e ce => ce``, but +it is no longer necessary to regard that as an ambiguous type: Although +the variable ``e`` does not appear on the right of the ``=>`` symbol, the +dependency for class ``Collects`` tells us that it is uniquely determined by +``ce``, which does appear on the right of the ``=>`` symbol. Hence the context +in which empty is used can still give enough information to determine +types for both ``ce`` and ``e``, without ambiguity. More generally, we need only +regard a type as ambiguous if it contains a variable on the left of the +``=>`` that is not uniquely determined (either directly or indirectly) by +the variables on the right. + +Dependencies also help to produce more accurate types for user defined +functions, and hence to provide earlier detection of errors, and less +cluttered types for programmers to work with. Recall the previous +definition for a function ``f``: + +:: + + f x y = insert x y = insert x . insert y + +for which we originally obtained a type: + +:: + + f :: (Collects a c, Collects b c) => a -> b -> c -> c + +Given the dependency information that we have for ``Collects``, however, we +can deduce that ``a`` and ``b`` must be equal because they both appear as the +second parameter in a ``Collects`` constraint with the same first parameter +``c``. Hence we can infer a shorter and more accurate type for ``f``: + +:: + + f :: (Collects a c) => a -> a -> c -> c + +In a similar way, the earlier definition of ``g`` will now be flagged as a +type error. + +Although we have given only a few examples here, it should be clear that +the addition of dependency information can help to make multiple +parameter classes more useful in practice, avoiding ambiguity problems, +and allowing more general sets of instance declarations. + +.. _instance-decls: + +Instance declarations +--------------------- + +An instance declaration has the form + +:: + + instance ( assertion1, ..., assertionn) => class type1 ... typem where ... + +The part before the "``=>``" is the *context*, while the part after the +"``=>``" is the *head* of the instance declaration. + +.. _instance-resolution: + +Instance resolution +~~~~~~~~~~~~~~~~~~~ + +When GHC tries to resolve, say, the constraint ``C Int Bool``, it tries +to match every instance declaration against the constraint, by +instantiating the head of the instance declaration. Consider these +declarations: + +:: + + instance context1 => C Int a where ... -- (A) + instance context2 => C a Bool where ... -- (B) + +GHC's default behaviour is that *exactly one instance must match the +constraint it is trying to resolve*. For example, the constraint +``C Int Bool`` matches instances (A) and (B), and hence would be +rejected; while ``C Int Char`` matches only (A) and hence (A) is chosen. + +Notice that + +- When matching, GHC takes no account of the context of the instance + declaration (``context1`` etc). + +- It is fine for there to be a *potential* of overlap (by including + both declarations (A) and (B), say); an error is only reported if a + particular constraint matches more than one. + +See also :ref:`instance-overlap` for flags that loosen the instance +resolution rules. + +.. _flexible-instance-head: + +Relaxed rules for the instance head +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In Haskell 98 the head of an instance declaration must be of the form +``C (T a1 ... an)``, where ``C`` is the class, ``T`` is a data type +constructor, and the ``a1 ... an`` are distinct type variables. In the +case of multi-parameter type classes, this rule applies to each +parameter of the instance head (Arguably it should be okay if just one +has this form and the others are type variables, but that's the rules at +the moment). + +GHC relaxes this rule in two ways: + +- With the ``-XTypeSynonymInstances`` flag, instance heads may use type + synonyms. As always, using a type synonym is just shorthand for + writing the RHS of the type synonym definition. For example: + + :: + + type Point a = (a,a) + instance C (Point a) where ... + + is legal. The instance declaration is equivalent to + + :: + + instance C (a,a) where ... + + As always, type synonyms must be fully applied. You cannot, for + example, write: + + :: + + instance Monad Point where ... + +- The ``-XFlexibleInstances`` flag allows the head of the instance + declaration to mention arbitrary nested types. For example, this + becomes a legal instance declaration + + :: + + instance C (Maybe Int) where ... + + See also the `rules on overlap <#instance-overlap>`__. + + The ``-XFlexibleInstances`` flag implies ``-XTypeSynonymInstances``. + +However, the instance declaration must still conform to the rules for +instance termination: see :ref:`instance-termination`. + +.. _instance-rules: + +Relaxed rules for instance contexts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In Haskell 98, the class constraints in the context of the instance +declaration must be of the form ``C a`` where ``a`` is a type variable +that occurs in the head. + +The ``-XFlexibleContexts`` flag relaxes this rule, as well as relaxing +the corresponding rule for type signatures (see +:ref:`flexible-contexts`). Specifically, ``-XFlexibleContexts``, allows +(well-kinded) class constraints of form ``(C t1 ... tn)`` in the context +of an instance declaration. + +Notice that the flag does not affect equality constraints in an instance +context; they are permitted by ``-XTypeFamilies`` or ``-XGADTs``. + +However, the instance declaration must still conform to the rules for +instance termination: see :ref:`instance-termination`. + +.. _instance-termination: + +Instance termination rules +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Regardless of ``-XFlexibleInstances`` and ``-XFlexibleContexts``, +instance declarations must conform to some rules that ensure that +instance resolution will terminate. The restrictions can be lifted with +``-XUndecidableInstances`` (see :ref:`undecidable-instances`). + +The rules are these: + +1. The Paterson Conditions: for each class constraint ``(C t1 ... tn)`` + in the context + + 1. No type variable has more occurrences in the constraint than in + the head + + 2. The constraint has fewer constructors and variables (taken + together and counting repetitions) than the head + + 3. The constraint mentions no type functions. A type function + application can in principle expand to a type of arbitrary size, + and so are rejected out of hand + +2. The Coverage Condition. For each functional dependency, + ⟨tvs⟩\ :sub:`left` ``->`` ⟨tvs⟩\ :sub:`right`, of the class, every + type variable in S(⟨tvs⟩\ :sub:`right`) must appear in + S(⟨tvs⟩\ :sub:`left`), where S is the substitution mapping each type + variable in the class declaration to the corresponding type in the + instance head. + +These restrictions ensure that instance resolution terminates: each +reduction step makes the problem smaller by at least one constructor. +You can find lots of background material about the reason for these +restrictions in the paper `Understanding functional dependencies via +Constraint Handling +Rules <http://research.microsoft.com/%7Esimonpj/papers/fd%2Dchr/>`__. + +For example, these are okay: + +:: + + instance C Int [a] -- Multiple parameters + instance Eq (S [a]) -- Structured type in head + + -- Repeated type variable in head + instance C4 a a => C4 [a] [a] + instance Stateful (ST s) (MutVar s) + + -- Head can consist of type variables only + instance C a + instance (Eq a, Show b) => C2 a b + + -- Non-type variables in context + instance Show (s a) => Show (Sized s a) + instance C2 Int a => C3 Bool [a] + instance C2 Int a => C3 [a] b + +But these are not: + +:: + + -- Context assertion no smaller than head + instance C a => C a where ... + -- (C b b) has more occurrences of b than the head + instance C b b => Foo [b] where ... + +The same restrictions apply to instances generated by ``deriving`` +clauses. Thus the following is accepted: + +:: + + data MinHeap h a = H a (h a) + deriving (Show) + +because the derived instance + +:: + + instance (Show a, Show (h a)) => Show (MinHeap h a) + +conforms to the above rules. + +A useful idiom permitted by the above rules is as follows. If one allows +overlapping instance declarations then it's quite convenient to have a +"default instance" declaration that applies if something more specific +does not: + +:: + + instance C a where + op = ... -- Default + +.. _undecidable-instances: + +Undecidable instances +~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: -XUndecidableInstances + +Sometimes even the termination rules of :ref:`instance-termination` are +too onerous. So GHC allows you to experiment with more liberal rules: if +you use the experimental flag ``-XUndecidableInstances``, both the Paterson +Conditions and the Coverage +Condition (described in :ref:`instance-termination`) are lifted. +Termination is still ensured by having a fixed-depth recursion stack. If +you exceed the stack depth you get a sort of backtrace, and the +opportunity to increase the stack depth with +``-freduction-depth=``\ *N*. However, if you should exceed the default +reduction depth limit, it is probably best just to disable depth +checking, with ``-freduction-depth=0``. The exact depth your program +requires depends on minutiae of your code, and it may change between +minor GHC releases. The safest bet for released code -- if you're sure +that it should compile in finite time -- is just to disable the check. + +For example, sometimes you might want to use the following to get the +effect of a "class synonym": + +:: + + class (C1 a, C2 a, C3 a) => C a where { } + + instance (C1 a, C2 a, C3 a) => C a where { } + +This allows you to write shorter signatures: + +:: + + f :: C a => ... + +instead of + +:: + + f :: (C1 a, C2 a, C3 a) => ... + +The restrictions on functional dependencies +(:ref:`functional-dependencies`) are particularly troublesome. It is +tempting to introduce type variables in the context that do not appear +in the head, something that is excluded by the normal rules. For +example: + +:: + + class HasConverter a b | a -> b where + convert :: a -> b + + data Foo a = MkFoo a + + instance (HasConverter a b,Show b) => Show (Foo a) where + show (MkFoo value) = show (convert value) + +This is dangerous territory, however. Here, for example, is a program +that would make the typechecker loop: + +:: + + class D a + class F a b | a->b + instance F [a] [[a]] + instance (D c, F a c) => D [a] -- 'c' is not mentioned in the head + +Similarly, it can be tempting to lift the coverage condition: + +:: + + class Mul a b c | a b -> c where + (.*.) :: a -> b -> c + + instance Mul Int Int Int where (.*.) = (*) + instance Mul Int Float Float where x .*. y = fromIntegral x * y + instance Mul a b c => Mul a [b] [c] where x .*. v = map (x.*.) v + +The third instance declaration does not obey the coverage condition; and +indeed the (somewhat strange) definition: + +:: + + f = \ b x y -> if b then x .*. [y] else y + +makes instance inference go into a loop, because it requires the +constraint ``(Mul a [b] b)``. + +The ``-XUndecidableInstances`` flag is also used to lift some of the +restrictions imposed on type family instances. See +:ref:`type-family-decidability`. + +.. _instance-overlap: + +Overlapping instances +~~~~~~~~~~~~~~~~~~~~~ + +In general, as discussed in :ref:`instance-resolution`, *GHC requires +that it be unambiguous which instance declaration should be used to +resolve a type-class constraint*. GHC also provides a way to to loosen +the instance resolution, by allowing more than one instance to match, +*provided there is a most specific one*. Moreover, it can be loosened +further, by allowing more than one instance to match irrespective of +whether there is a most specific one. This section gives the details. + +To control the choice of instance, it is possible to specify the overlap +behavior for individual instances with a pragma, written immediately +after the ``instance`` keyword. The pragma may be one of: +``{-# OVERLAPPING #-}``, ``{-# OVERLAPPABLE #-}``, ``{-# OVERLAPS #-}``, +or ``{-# INCOHERENT #-}``. + +The matching behaviour is also influenced by two module-level language +extension flags: ``-XOverlappingInstances`` -XOverlappingInstances and +``-XIncoherentInstances`` -XIncoherentInstances. These flags are now +deprecated (since GHC 7.10) in favour of the fine-grained per-instance +pragmas. + +A more precise specification is as follows. The willingness to be +overlapped or incoherent is a property of the *instance declaration* +itself, controlled as follows: + +- An instance is *incoherent* if: it has an ``INCOHERENT`` pragma; or + if the instance has no pragma and it appears in a module compiled + with ``-XIncoherentInstances``. + +- An instance is *overlappable* if: it has an ``OVERLAPPABLE`` or + ``OVERLAPS`` pragma; or if the instance has no pragma and it appears + in a module compiled with ``-XOverlappingInstances``; or if the + instance is incoherent. + +- An instance is *overlapping* if: it has an ``OVERLAPPING`` or + ``OVERLAPS`` pragma; or if the instance has no pragma and it appears + in a module compiled with ``-XOverlappingInstances``; or if the + instance is incoherent. + +Now suppose that, in some client module, we are searching for an +instance of the *target constraint* ``(C ty1 .. tyn)``. The search works +like this: + +- Find all instances I that *match* the target constraint; that is, the + target constraint is a substitution instance of I. These instance + declarations are the *candidates*. + +- Eliminate any candidate IX for which both of the following hold: + + - There is another candidate IY that is strictly more specific; that + is, IY is a substitution instance of IX but not vice versa. + + - Either IX is *overlappable*, or IY is *overlapping*. (This + "either/or" design, rather than a "both/and" design, allow a + client to deliberately override an instance from a library, + without requiring a change to the library.) + +- If exactly one non-incoherent candidate remains, select it. If all + remaining candidates are incoherent, select an arbitrary one. + Otherwise the search fails (i.e. when more than one surviving + candidate is not incoherent). + +- If the selected candidate (from the previous step) is incoherent, the + search succeeds, returning that candidate. + +- If not, find all instances that *unify* with the target constraint, + but do not *match* it. Such non-candidate instances might match when + the target constraint is further instantiated. If all of them are + incoherent, the search succeeds, returning the selected candidate; if + not, the search fails. + +Notice that these rules are not influenced by flag settings in the +client module, where the instances are *used*. These rules make it +possible for a library author to design a library that relies on +overlapping instances without the client having to know. + +Errors are reported *lazily* (when attempting to solve a constraint), +rather than *eagerly* (when the instances themselves are defined). +Consider, for example + +:: + + instance C Int b where .. + instance C a Bool where .. + +These potentially overlap, but GHC will not complain about the instance +declarations themselves, regardless of flag settings. If we later try to +solve the constraint ``(C Int Char)`` then only the first instance +matches, and all is well. Similarly with ``(C Bool Bool)``. But if we +try to solve ``(C Int Bool)``, both instances match and an error is +reported. + +As a more substantial example of the rules in action, consider + +:: + + instance {-# OVERLAPPABLE #-} context1 => C Int b where ... -- (A) + instance {-# OVERLAPPABLE #-} context2 => C a Bool where ... -- (B) + instance {-# OVERLAPPABLE #-} context3 => C a [b] where ... -- (C) + instance {-# OVERLAPPING #-} context4 => C Int [Int] where ... -- (D) + +Now suppose that the type inference engine needs to solve the constraint +``C Int [Int]``. This constraint matches instances (A), (C) and (D), but +the last is more specific, and hence is chosen. + +If (D) did not exist then (A) and (C) would still be matched, but +neither is most specific. In that case, the program would be rejected, +unless ``-XIncoherentInstances`` is enabled, in which case it would be +accepted and (A) or (C) would be chosen arbitrarily. + +An instance declaration is *more specific* than another iff the head of +former is a substitution instance of the latter. For example (D) is +"more specific" than (C) because you can get from (C) to (D) by +substituting ``a := Int``. + +GHC is conservative about committing to an overlapping instance. For +example: + +:: + + f :: [b] -> [b] + f x = ... + +Suppose that from the RHS of ``f`` we get the constraint ``C b [b]``. +But GHC does not commit to instance (C), because in a particular call of +``f``, ``b`` might be instantiate to ``Int``, in which case instance (D) +would be more specific still. So GHC rejects the program. + +If, however, you add the flag ``-XIncoherentInstances`` when compiling +the module that contains (D), GHC will instead pick (C), without +complaining about the problem of subsequent instantiations. + +Notice that we gave a type signature to ``f``, so GHC had to *check* +that ``f`` has the specified type. Suppose instead we do not give a type +signature, asking GHC to *infer* it instead. In this case, GHC will +refrain from simplifying the constraint ``C Int [b]`` (for the same +reason as before) but, rather than rejecting the program, it will infer +the type + +:: + + f :: C b [b] => [b] -> [b] + +That postpones the question of which instance to pick to the call site +for ``f`` by which time more is known about the type ``b``. You can +write this type signature yourself if you use the +`-XFlexibleContexts <#flexible-contexts>`__ flag. + +Exactly the same situation can arise in instance declarations +themselves. Suppose we have + +:: + + class Foo a where + f :: a -> a + instance Foo [b] where + f x = ... + +and, as before, the constraint ``C Int [b]`` arises from ``f``'s right +hand side. GHC will reject the instance, complaining as before that it +does not know how to resolve the constraint ``C Int [b]``, because it +matches more than one instance declaration. The solution is to postpone +the choice by adding the constraint to the context of the instance +declaration, thus: + +:: + + instance C Int [b] => Foo [b] where + f x = ... + +(You need `-XFlexibleInstances <#instance-rules>`__ to do this.) + +.. warning:: + Overlapping instances must be used with care. They can give + rise to incoherence (i.e. different instance choices are made in + different parts of the program) even without ``-XIncoherentInstances``. + Consider: + + :: + + {-# LANGUAGE OverlappingInstances #-} + module Help where + + class MyShow a where + myshow :: a -> String + + instance MyShow a => MyShow [a] where + myshow xs = concatMap myshow xs + + showHelp :: MyShow a => [a] -> String + showHelp xs = myshow xs + + {-# LANGUAGE FlexibleInstances, OverlappingInstances #-} + module Main where + import Help + + data T = MkT + + instance MyShow T where + myshow x = "Used generic instance" + + instance MyShow [T] where + myshow xs = "Used more specific instance" + + main = do { print (myshow [MkT]); print (showHelp [MkT]) } + + In function ``showHelp`` GHC sees no overlapping instances, and so uses + the ``MyShow [a]`` instance without complaint. In the call to ``myshow`` + in ``main``, GHC resolves the ``MyShow [T]`` constraint using the + overlapping instance declaration in module ``Main``. As a result, the + program prints + + :: + + "Used more specific instance" + "Used generic instance" + + (An alternative possible behaviour, not currently implemented, would be + to reject module ``Help`` on the grounds that a later instance + declaration might overlap the local one.) + +.. _instance-sigs: + +Instance signatures: type signatures in instance declarations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In Haskell, you can't write a type signature in an instance declaration, +but it is sometimes convenient to do so, and the language extension +``-XInstanceSigs`` allows you to do so. For example: + +:: + + data T a = MkT a a + instance Eq a => Eq (T a) where + (==) :: T a -> T a -> Bool -- The signature + (==) (MkT x1 x2) (MkTy y1 y2) = x1==y1 && x2==y2 + +Some details + +- The type signature in the instance declaration must be more + polymorphic than (or the same as) the one in the class declaration, + instantiated with the instance type. For example, this is fine: + + :: + + instance Eq a => Eq (T a) where + (==) :: forall b. b -> b -> Bool + (==) x y = True + + Here the signature in the instance declaration is more polymorphic + than that required by the instantiated class method. + +- The code for the method in the instance declaration is typechecked + against the type signature supplied in the instance declaration, as + you would expect. So if the instance signature is more polymorphic + than required, the code must be too. + +- One stylistic reason for wanting to write a type signature is simple + documentation. Another is that you may want to bring scoped type + variables into scope. For example: + + :: + + class C a where + foo :: b -> a -> (a, [b]) + + instance C a => C (T a) where + foo :: forall b. b -> T a -> (T a, [b]) + foo x (T y) = (T y, xs) + where + xs :: [b] + xs = [x,x,x] + + Provided that you also specify ``-XScopedTypeVariables`` + (:ref:`scoped-type-variables`), the ``forall b`` scopes over the + definition of ``foo``, and in particular over the type signature for + ``xs``. + +.. _overloaded-strings: + +Overloaded string literals +-------------------------- + +GHC supports *overloaded string literals*. Normally a string literal has +type ``String``, but with overloaded string literals enabled (with +``-XOverloadedStrings``) a string literal has type +``(IsString a) => a``. + +This means that the usual string syntax can be used, e.g., for +``ByteString``, ``Text``, and other variations of string like types. +String literals behave very much like integer literals, i.e., they can +be used in both expressions and patterns. If used in a pattern the +literal with be replaced by an equality test, in the same way as an +integer literal is. + +The class ``IsString`` is defined as: + +:: + + class IsString a where + fromString :: String -> a + +The only predefined instance is the obvious one to make strings work as +usual: + +:: + + instance IsString [Char] where + fromString cs = cs + +The class ``IsString`` is not in scope by default. If you want to +mention it explicitly (for example, to give an instance declaration for +it), you can import it from module ``GHC.Exts``. + +Haskell's defaulting mechanism (`Haskell Report, Section +4.3.4 <http://www.haskell.org/onlinereport/decls.html#sect4.3.4>`__) is +extended to cover string literals, when ``-XOverloadedStrings`` is +specified. Specifically: + +- Each type in a ``default`` declaration must be an instance of ``Num`` + *or* of ``IsString``. + +- If no ``default`` declaration is given, then it is just as if the + module contained the declaration + ``default( Integer, Double, String)``. + +- The standard defaulting rule is extended thus: defaulting applies + when all the unresolved constraints involve standard classes *or* + ``IsString``; and at least one is a numeric class *or* ``IsString``. + +So, for example, the expression ``length "foo"`` will give rise to an +ambiguous use of ``IsString a0`` which, because of the above rules, will +default to ``String``. + +A small example: + +:: + + module Main where + + import GHC.Exts( IsString(..) ) + + newtype MyString = MyString String deriving (Eq, Show) + instance IsString MyString where + fromString = MyString + + greet :: MyString -> MyString + greet "hello" = "world" + greet other = other + + main = do + print $ greet "hello" + print $ greet "fool" + +Note that deriving ``Eq`` is necessary for the pattern matching to work +since it gets translated into an equality comparison. + +.. _overloaded-lists: + +Overloaded lists +---------------- + +GHC supports *overloading of the list notation*. Let us recap the +notation for constructing lists. In Haskell, the list notation can be be +used in the following seven ways: + +:: + + [] -- Empty list + [x] -- x : [] + [x,y,z] -- x : y : z : [] + [x .. ] -- enumFrom x + [x,y ..] -- enumFromThen x y + [x .. y] -- enumFromTo x y + [x,y .. z] -- enumFromThenTo x y z + +When the ``OverloadedLists`` extension is turned on, the aforementioned +seven notations are desugared as follows: + +:: + + [] -- fromListN 0 [] + [x] -- fromListN 1 (x : []) + [x,y,z] -- fromListN 3 (x : y : z : []) + [x .. ] -- fromList (enumFrom x) + [x,y ..] -- fromList (enumFromThen x y) + [x .. y] -- fromList (enumFromTo x y) + [x,y .. z] -- fromList (enumFromThenTo x y z) + +This extension allows programmers to use the list notation for +construction of structures like: ``Set``, ``Map``, ``IntMap``, +``Vector``, ``Text`` and ``Array``. The following code listing gives a +few examples: + +:: + + ['0' .. '9'] :: Set Char + [1 .. 10] :: Vector Int + [("default",0), (k1,v1)] :: Map String Int + ['a' .. 'z'] :: Text + +List patterns are also overloaded. When the ``OverloadedLists`` +extension is turned on, these definitions are desugared as follows + +:: + + f [] = ... -- f (toList -> []) = ... + g [x,y,z] = ... -- g (toList -> [x,y,z]) = ... + +(Here we are using view-pattern syntax for the translation, see +:ref:`view-patterns`.) + +The ``IsList`` class +~~~~~~~~~~~~~~~~~~~~ + +In the above desugarings, the functions ``toList``, ``fromList`` and +``fromListN`` are all methods of the ``IsList`` class, which is itself +exported from the ``GHC.Exts`` module. The type class is defined as +follows: + +:: + + class IsList l where + type Item l + + fromList :: [Item l] -> l + toList :: l -> [Item l] + + fromListN :: Int -> [Item l] -> l + fromListN _ = fromList + +The ``IsList`` class and its methods are intended to be used in +conjunction with the ``OverloadedLists`` extension. + +- The type function ``Item`` returns the type of items of the structure + ``l``. + +- The function ``fromList`` constructs the structure ``l`` from the + given list of ``Item l``. + +- The function ``fromListN`` takes the input list's length as a hint. + Its behaviour should be equivalent to ``fromList``. The hint can be + used for more efficient construction of the structure ``l`` compared + to ``fromList``. If the given hint is not equal to the input list's + length the behaviour of ``fromListN`` is not specified. + +- The function ``toList`` should be the inverse of ``fromList``. + +It is perfectly fine to declare new instances of ``IsList``, so that +list notation becomes useful for completely new data types. Here are +several example instances: + +:: + + instance IsList [a] where + type Item [a] = a + fromList = id + toList = id + + instance (Ord a) => IsList (Set a) where + type Item (Set a) = a + fromList = Set.fromList + toList = Set.toList + + instance (Ord k) => IsList (Map k v) where + type Item (Map k v) = (k,v) + fromList = Map.fromList + toList = Map.toList + + instance IsList (IntMap v) where + type Item (IntMap v) = (Int,v) + fromList = IntMap.fromList + toList = IntMap.toList + + instance IsList Text where + type Item Text = Char + fromList = Text.pack + toList = Text.unpack + + instance IsList (Vector a) where + type Item (Vector a) = a + fromList = Vector.fromList + fromListN = Vector.fromListN + toList = Vector.toList + +Rebindable syntax +~~~~~~~~~~~~~~~~~ + +When desugaring list notation with ``-XOverloadedLists`` GHC uses the +``fromList`` (etc) methods from module ``GHC.Exts``. You do not need to +import ``GHC.Exts`` for this to happen. + +However if you use ``-XRebindableSyntax``, then GHC instead uses +whatever is in scope with the names of ``toList``, ``fromList`` and +``fromListN``. That is, these functions are rebindable; c.f. +:ref:`rebindable-syntax`. + +Defaulting +~~~~~~~~~~ + +Currently, the ``IsList`` class is not accompanied with defaulting +rules. Although feasible, not much thought has gone into how to specify +the meaning of the default declarations like: + +:: + + default ([a]) + +Speculation about the future +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The current implementation of the ``OverloadedLists`` extension can be +improved by handling the lists that are only populated with literals in +a special way. More specifically, the compiler could allocate such lists +statically using a compact representation and allow ``IsList`` instances +to take advantage of the compact representation. Equipped with this +capability the ``OverloadedLists`` extension will be in a good position +to subsume the ``OverloadedStrings`` extension (currently, as a special +case, string literals benefit from statically allocated compact +representation). + +.. _type-families: + +Type families +============= + +Indexed type families form an extension to facilitate type-level +programming. Type families are a generalisation of associated data types +[AssocDataTypes2005]_ and associated type synonyms +[AssocTypeSyn2005]_ Type families themselves are described in +Schrijvers 2008 [TypeFamilies2008]_. Type families essentially provide +type-indexed data types and named functions on types, which are useful for +generic programming and highly parameterised library interfaces as well as +interfaces with enhanced static information, much like dependent types. They +might also be regarded as an alternative to functional dependencies, but provide +a more functional style of type-level programming than the relational style of +functional dependencies. + +Indexed type families, or type families for short, are type constructors +that represent sets of types. Set members are denoted by supplying the +type family constructor with type parameters, which are called type +indices. The difference between vanilla parametrised type constructors +and family constructors is much like between parametrically polymorphic +functions and (ad-hoc polymorphic) methods of type classes. Parametric +polymorphic functions behave the same at all type instances, whereas +class methods can change their behaviour in dependence on the class type +parameters. Similarly, vanilla type constructors imply the same data +representation for all type instances, but family constructors can have +varying representation types for varying type indices. + +Indexed type families come in three flavours: data families, open type +synonym families, and closed type synonym families. They are the indexed +family variants of algebraic data types and type synonyms, respectively. +The instances of data families can be data types and newtypes. + +Type families are enabled by the flag ``-XTypeFamilies``. Additional +information on the use of type families in GHC is available on `the +Haskell wiki page on type +families <http://www.haskell.org/haskellwiki/GHC/Indexed_types>`__. + +.. [AssocDataTypes2005] + “`Associated Types with Class + <http://www.cse.unsw.edu.au/~chak/papers/CKPM05.html>`__\ ”, M. + Chakravarty, G. Keller, S. Peyton Jones, + and S. Marlow. In Proceedings of “The 32nd Annual + ACM SIGPLAN-SIGACT Symposium on Principles of + Programming Languages (POPL'05)”, pages 1-13, ACM + Press, 2005) + +.. [AssocTypeSyn2005] + “`Type Associated Type + Synonyms <http://www.cse.unsw.edu.au/~chak/papers/CKP05.html>`__\ ”. M. + Chakravarty, G. Keller, and S. Peyton Jones. In Proceedings of “The + Tenth ACM SIGPLAN International Conference on Functional Programming”, + ACM Press, pages 241-253, 2005). + +.. [TypeFamilies2008] + “\ `Type Checking with Open Type + Functions <http://www.cse.unsw.edu.au/~chak/papers/SPCS08.html>`__\ ”, + T. Schrijvers, S. Peyton-Jones, M. Chakravarty, and M. Sulzmann, in + Proceedings of “ICFP 2008: The 13th ACM SIGPLAN International Conference + on Functional Programming”, ACM Press, pages 51-62, 2008. + + +.. _data-families: + +Data families +------------- + +Data families appear in two flavours: (1) they can be defined on the +toplevel or (2) they can appear inside type classes (in which case they +are known as associated types). The former is the more general variant, +as it lacks the requirement for the type-indexes to coincide with the +class parameters. However, the latter can lead to more clearly +structured code and compiler warnings if some type instances were - +possibly accidentally - omitted. In the following, we always discuss the +general toplevel form first and then cover the additional constraints +placed on associated types. + +.. _data-family-declarations: + +Data family declarations +~~~~~~~~~~~~~~~~~~~~~~~~ + +Indexed data families are introduced by a signature, such as + +:: + + data family GMap k :: * -> * + +The special ``family`` distinguishes family from standard data +declarations. The result kind annotation is optional and, as usual, +defaults to ``*`` if omitted. An example is + +:: + + data family Array e + +Named arguments can also be given explicit kind signatures if needed. +Just as with +[http://www.haskell.org/ghc/docs/latest/html/users\_guide/gadt.html GADT +declarations] named arguments are entirely optional, so that we can +declare ``Array`` alternatively with + +:: + + data family Array :: * -> * + +.. _data-instance-declarations: + +Data instance declarations +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Instance declarations of data and newtype families are very similar to +standard data and newtype declarations. The only two differences are +that the keyword ``data`` or ``newtype`` is followed by ``instance`` and +that some or all of the type arguments can be non-variable types, but +may not contain forall types or type synonym families. However, data +families are generally allowed in type parameters, and type synonyms are +allowed as long as they are fully applied and expand to a type that is +itself admissible - exactly as this is required for occurrences of type +synonyms in class instance parameters. For example, the ``Either`` +instance for ``GMap`` is + +:: + + data instance GMap (Either a b) v = GMapEither (GMap a v) (GMap b v) + +In this example, the declaration has only one variant. In general, it +can be any number. + +When the name of a type argument of a data or newtype instance +declaration doesn't matter, it can be replaced with an underscore +(``_``). This is the same as writing a type variable with a unique name. + +:: + + data family F a b :: * + data instance F Int _ = Int + -- Equivalent to + data instance F Int b = Int + +This resembles the wildcards that can be used in +:ref:`partial-type-signatures`. However, there are some differences. +Only anonymous wildcards are allowed in these instance declarations, +named and extra-constraints wildcards are not. No error messages +reporting the inferred types are generated, nor does the flag +``-XPartialTypeSignatures`` have any effect. + +Data and newtype instance declarations are only permitted when an +appropriate family declaration is in scope - just as a class instance +declaration requires the class declaration to be visible. Moreover, each +instance declaration has to conform to the kind determined by its family +declaration. This implies that the number of parameters of an instance +declaration matches the arity determined by the kind of the family. + +A data family instance declaration can use the full expressiveness of +ordinary ``data`` or ``newtype`` declarations: + +- Although, a data family is *introduced* with the keyword "``data``", + a data family *instance* can use either ``data`` or ``newtype``. For + example: + + :: + + data family T a + data instance T Int = T1 Int | T2 Bool + newtype instance T Char = TC Bool + +- A ``data instance`` can use GADT syntax for the data constructors, + and indeed can define a GADT. For example: + + :: + + data family G a b + data instance G [a] b where + G1 :: c -> G [Int] b + G2 :: G [a] Bool + +- You can use a ``deriving`` clause on a ``data instance`` or + ``newtype instance`` declaration. + +Even if data families are defined as toplevel declarations, functions +that perform different computations for different family instances may +still need to be defined as methods of type classes. In particular, the +following is not possible: + +:: + + data family T a + data instance T Int = A + data instance T Char = B + foo :: T a -> Int + foo A = 1 -- WRONG: These two equations together... + foo B = 2 -- ...will produce a type error. + +Instead, you would have to write ``foo`` as a class operation, thus: + +:: + + class Foo a where + foo :: T a -> Int + instance Foo Int where + foo A = 1 + instance Foo Char where + foo B = 2 + +Given the functionality provided by GADTs (Generalised Algebraic Data +Types), it might seem as if a definition, such as the above, should be +feasible. However, type families are - in contrast to GADTs - are +*open;* i.e., new instances can always be added, possibly in other +modules. Supporting pattern matching across different data instances +would require a form of extensible case construct. + +.. _data-family-overlap: + +Overlap of data instances +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The instance declarations of a data family used in a single program may +not overlap at all, independent of whether they are associated or not. +In contrast to type class instances, this is not only a matter of +consistency, but one of type safety. + +.. _synonym-families: + +Synonym families +---------------- + +Type families appear in three flavours: (1) they can be defined as open +families on the toplevel, (2) they can be defined as closed families on +the toplevel, or (3) they can appear inside type classes (in which case +they are known as associated type synonyms). Toplevel families are more +general, as they lack the requirement for the type-indexes to coincide +with the class parameters. However, associated type synonyms can lead to +more clearly structured code and compiler warnings if some type +instances were - possibly accidentally - omitted. In the following, we +always discuss the general toplevel forms first and then cover the +additional constraints placed on associated types. Note that closed +associated type synonyms do not exist. + +.. _type-family-declarations: + +Type family declarations +~~~~~~~~~~~~~~~~~~~~~~~~ + +Open indexed type families are introduced by a signature, such as + +:: + + type family Elem c :: * + +The special ``family`` distinguishes family from standard type +declarations. The result kind annotation is optional and, as usual, +defaults to ``*`` if omitted. An example is + +:: + + type family Elem c + +Parameters can also be given explicit kind signatures if needed. We call +the number of parameters in a type family declaration, the family's +arity, and all applications of a type family must be fully saturated +with respect to to that arity. This requirement is unlike ordinary type synonyms +and it implies that the kind of a type family is not sufficient to +determine a family's arity, and hence in general, also insufficient to +determine whether a type family application is well formed. As an +example, consider the following declaration: + +:: + + type family F a b :: * -> * -- F's arity is 2, + -- although its overall kind is * -> * -> * -> * + +Given this declaration the following are examples of well-formed and +malformed types: + +:: + + F Char [Int] -- OK! Kind: * -> * + F Char [Int] Bool -- OK! Kind: * + F IO Bool -- WRONG: kind mismatch in the first argument + F Bool -- WRONG: unsaturated application + +The result kind annotation is optional and defaults to ``*`` (like +argument kinds) if omitted. Polykinded type families can be declared +using a parameter in the kind annotation: + +:: + + type family F a :: k + +In this case the kind parameter ``k`` is actually an implicit parameter +of the type family. + +.. _type-instance-declarations: + +Type instance declarations +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Instance declarations of type families are very similar to standard type +synonym declarations. The only two differences are that the keyword +``type`` is followed by ``instance`` and that some or all of the type +arguments can be non-variable types, but may not contain forall types or +type synonym families. However, data families are generally allowed, and +type synonyms are allowed as long as they are fully applied and expand +to a type that is admissible - these are the exact same requirements as +for data instances. For example, the ``[e]`` instance for ``Elem`` is + +:: + + type instance Elem [e] = e + +Type arguments can be replaced with underscores (``_``) if the names of +the arguments don't matter. This is the same as writing type variables +with unique names. The same rules apply as for +:ref:`data-instance-declarations`. + +Type family instance declarations are only legitimate when an +appropriate family declaration is in scope - just like class instances +require the class declaration to be visible. Moreover, each instance +declaration has to conform to the kind determined by its family +declaration, and the number of type parameters in an instance +declaration must match the number of type parameters in the family +declaration. Finally, the right-hand side of a type instance must be a +monotype (i.e., it may not include foralls) and after the expansion of +all saturated vanilla type synonyms, no synonyms, except family synonyms +may remain. + +.. _closed-type-families: + +Closed type families +~~~~~~~~~~~~~~~~~~~~ + +A type family can also be declared with a ``where`` clause, defining the +full set of equations for that family. For example: + +:: + + type family F a where + F Int = Double + F Bool = Char + F a = String + +A closed type family's equations are tried in order, from top to bottom, +when simplifying a type family application. In this example, we declare +an instance for ``F`` such that ``F Int`` simplifies to ``Double``, +``F Bool`` simplifies to ``Char``, and for any other type ``a`` that is +known not to be ``Int`` or ``Bool``, ``F a`` simplifies to ``String``. +Note that GHC must be sure that ``a`` cannot unify with ``Int`` or +``Bool`` in that last case; if a programmer specifies just ``F a`` in +their code, GHC will not be able to simplify the type. After all, ``a`` +might later be instantiated with ``Int``. + +A closed type family's equations have the same restrictions as the +equations for open type family instances. + +A closed type family may be declared with no equations. Such closed type +families are opaque type-level definitions that will never reduce, are +not necessarily injective (unlike empty data types), and cannot be given +any instances. This is different from omitting the equations of a closed +type family in a ``hs-boot`` file, which uses the syntax ``where ..``, +as in that case there may or may not be equations given in the ``hs`` +file. + +.. _type-family-examples: + +Type family examples +~~~~~~~~~~~~~~~~~~~~ + +Here are some examples of admissible and illegal type instances: + +:: + + type family F a :: * + type instance F [Int] = Int -- OK! + type instance F String = Char -- OK! + type instance F (F a) = a -- WRONG: type parameter mentions a type family + type instance + F (forall a. (a, b)) = b -- WRONG: a forall type appears in a type parameter + type instance + F Float = forall a.a -- WRONG: right-hand side may not be a forall type + type family H a where -- OK! + H Int = Int + H Bool = Bool + H a = String + type instance H Char = Char -- WRONG: cannot have instances of closed family + type family K a where -- OK! + + type family G a b :: * -> * + type instance G Int = (,) -- WRONG: must be two type parameters + type instance G Int Char Float = Double -- WRONG: must be two type parameters + +.. _type-family-overlap: + +Compatibility and apartness of type family equations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There must be some restrictions on the equations of type families, lest +we define an ambiguous rewrite system. So, equations of open type +families are restricted to be compatible. Two type patterns are +compatible if + +1. all corresponding types and implicit kinds in the patterns are apart, + or + +2. the two patterns unify producing a substitution, and the right-hand + sides are equal under that substitution. + +Two types are considered apart if, for all possible substitutions, the +types cannot reduce to a common reduct. + +The first clause of "compatible" is the more straightforward one. It +says that the patterns of two distinct type family instances cannot +overlap. For example, the following is disallowed: + +:: + + type instance F Int = Bool + type instance F Int = Char + +The second clause is a little more interesting. It says that two +overlapping type family instances are allowed if the right-hand sides +coincide in the region of overlap. Some examples help here: + +:: + + type instance F (a, Int) = [a] + type instance F (Int, b) = [b] -- overlap permitted + + type instance G (a, Int) = [a] + type instance G (Char, a) = [a] -- ILLEGAL overlap, as [Char] /= [Int] + +Note that this compatibility condition is independent of whether the +type family is associated or not, and it is not only a matter of +consistency, but one of type safety. + +For a polykinded type family, the kinds are checked for apartness just +like types. For example, the following is accepted: + +:: + + type family J a :: k + type instance J Int = Bool + type instance J Int = Maybe + +These instances are compatible because they differ in their implicit +kind parameter; the first uses ``*`` while the second uses ``* -> *``. + +The definition for "compatible" uses a notion of "apart", whose +definition in turn relies on type family reduction. This condition of +"apartness", as stated, is impossible to check, so we use this +conservative approximation: two types are considered to be apart when +the two types cannot be unified, even by a potentially infinite unifier. +Allowing the unifier to be infinite disallows the following pair of +instances: + +:: + + type instance H x x = Int + type instance H [x] x = Bool + +The type patterns in this pair equal if ``x`` is replaced by an infinite +nesting of lists. Rejecting instances such as these is necessary for +type soundness. + +Compatibility also affects closed type families. When simplifying an +application of a closed type family, GHC will select an equation only +when it is sure that no incompatible previous equation will ever apply. +Here are some examples: + +:: + + type family F a where + F Int = Bool + F a = Char + + type family G a where + G Int = Int + G a = a + +In the definition for ``F``, the two equations are incompatible -- their +patterns are not apart, and yet their right-hand sides do not coincide. +Thus, before GHC selects the second equation, it must be sure that the +first can never apply. So, the type ``F a`` does not simplify; only a +type such as ``F Double`` will simplify to ``Char``. In ``G``, on the +other hand, the two equations are compatible. Thus, GHC can ignore the +first equation when looking at the second. So, ``G a`` will simplify to +``a``. + +However see :ref:`ghci-decls` for the overlap rules in GHCi. + +.. _type-family-decidability: + +Decidability of type synonym instances +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In order to guarantee that type inference in the presence of type +families decidable, we need to place a number of additional restrictions +on the formation of type instance declarations (c.f., Definition 5 +(Relaxed Conditions) of “\ `Type Checking with Open Type +Functions <http://www.cse.unsw.edu.au/~chak/papers/SPCS08.html>`__\ ”). +Instance declarations have the general form + +:: + + type instance F t1 .. tn = t + +where we require that for every type family application ``(G s1 .. sm)`` +in ``t``, + +1. ``s1 .. sm`` do not contain any type family constructors, + +2. the total number of symbols (data type constructors and type + variables) in ``s1 .. sm`` is strictly smaller than in ``t1 .. tn``, + and + +3. for every type variable ``a``, ``a`` occurs in ``s1 .. sm`` at most + as often as in ``t1 .. tn``. + +These restrictions are easily verified and ensure termination of type +inference. However, they are not sufficient to guarantee completeness of +type inference in the presence of, so called, ''loopy equalities'', such +as ``a ~ [F a]``, where a recursive occurrence of a type variable is +underneath a family application and data constructor application - see +the above mentioned paper for details. + +If the option ``-XUndecidableInstances`` is passed to the compiler, the +above restrictions are not enforced and it is on the programmer to +ensure termination of the normalisation of type families during type +inference. + +.. _assoc-decl: + +Associated data and type families +--------------------------------- + +A data or type synonym family can be declared as part of a type class, +thus: + +:: + + class GMapKey k where + data GMap k :: * -> * + ... + + class Collects ce where + type Elem ce :: * + ... + +When doing so, we (optionally) may drop the "``family``" keyword. + +The type parameters must all be type variables, of course, and some (but +not necessarily all) of then can be the class parameters. Each class +parameter may only be used at most once per associated type, but some +may be omitted and they may be in an order other than in the class head. +Hence, the following contrived example is admissible: + +:: + + class C a b c where + type T c a x :: * + +Here ``c`` and ``a`` are class parameters, but the type is also indexed +on a third parameter ``x``. + +.. _assoc-data-inst: + +Associated instances +~~~~~~~~~~~~~~~~~~~~ + +When an associated data or type synonym family instance is declared +within a type class instance, we (optionally) may drop the ``instance`` +keyword in the family instance: + +:: + + instance (GMapKey a, GMapKey b) => GMapKey (Either a b) where + data GMap (Either a b) v = GMapEither (GMap a v) (GMap b v) + ... + + instance Eq (Elem [e]) => Collects [e] where + type Elem [e] = e + ... + +Note the following points: + +- The type indexes corresponding to class parameters must have + precisely the same shape the type given in the instance head. To have + the same "shape" means that the two types are identical modulo + renaming of type variables. For example: + + :: + + instance Eq (Elem [e]) => Collects [e] where + -- Choose one of the following alternatives: + type Elem [e] = e -- OK + type Elem [x] = x -- OK + type Elem x = x -- BAD; shape of 'x' is different to '[e]' + type Elem [Maybe x] = x -- BAD: shape of '[Maybe x]' is different to '[e]' + +- An instances for an associated family can only appear as part of an + instance declarations of the class in which the family was declared, + just as with the equations of the methods of a class. + +- The instance for an associated type can be omitted in class + instances. In that case, unless there is a default instance (see + :ref:`assoc-decl-defs`), the corresponding instance type is not + inhabited; i.e., only diverging expressions, such as ``undefined``, + can assume the type. + +- Although it is unusual, there (currently) can be *multiple* instances + for an associated family in a single instance declaration. For + example, this is legitimate: + + :: + + instance GMapKey Flob where + data GMap Flob [v] = G1 v + data GMap Flob Int = G2 Int + ... + + Here we give two data instance declarations, one in which the last + parameter is ``[v]``, and one for which it is ``Int``. Since you + cannot give any *subsequent* instances for ``(GMap Flob ...)``, this + facility is most useful when the free indexed parameter is of a kind + with a finite number of alternatives (unlike ``*``). WARNING: this + facility may be withdrawn in the future. + +.. _assoc-decl-defs: + +Associated type synonym defaults +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is possible for the class defining the associated type to specify a +default for associated type instances. So for example, this is OK: + +:: + + class IsBoolMap v where + type Key v + type instance Key v = Int + + lookupKey :: Key v -> v -> Maybe Bool + + instance IsBoolMap [(Int, Bool)] where + lookupKey = lookup + +In an ``instance`` declaration for the class, if no explicit +``type instance`` declaration is given for the associated type, the +default declaration is used instead, just as with default class methods. + +Note the following points: + +- The ``instance`` keyword is optional. + +- There can be at most one default declaration for an associated type + synonym. + +- A default declaration is not permitted for an associated *data* type. + +- The default declaration must mention only type *variables* on the + left hand side, and the right hand side must mention only type + variables bound on the left hand side. However, unlike the associated + type family declaration itself, the type variables of the default + instance are independent of those of the parent class. + +Here are some examples: + +:: + + class C a where + type F1 a :: * + type instance F1 a = [a] -- OK + type instance F1 a = a->a -- BAD; only one default instance is allowed + + type F2 b a -- OK; note the family has more type + -- variables than the class + type instance F2 c d = c->d -- OK; you don't have to use 'a' in the type instance + + type F3 a + type F3 [b] = b -- BAD; only type variables allowed on the LHS + + type F4 a + type F4 b = a -- BAD; 'a' is not in scope in the RHS + +.. _scoping-class-params: + +Scoping of class parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The visibility of class parameters in the right-hand side of associated +family instances depends *solely* on the parameters of the family. As an +example, consider the simple class declaration + +:: + + class C a b where + data T a + +Only one of the two class parameters is a parameter to the data family. +Hence, the following instance declaration is invalid: + +:: + + instance C [c] d where + data T [c] = MkT (c, d) -- WRONG!! 'd' is not in scope + +Here, the right-hand side of the data instance mentions the type +variable ``d`` that does not occur in its left-hand side. We cannot +admit such data instances as they would compromise type safety. + +Instance contexts and associated type and data instances +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Associated type and data instance declarations do not inherit any +context specified on the enclosing instance. For type instance +declarations, it is unclear what the context would mean. For data +instance declarations, it is unlikely a user would want the context +repeated for every data constructor. The only place where the context +might likely be useful is in a ``deriving`` clause of an associated data +instance. However, even here, the role of the outer instance context is +murky. So, for clarity, we just stick to the rule above: the enclosing +instance context is ignored. If you need to use a non-trivial context on +a derived instance, use a `standalone +deriving <#stand-alone-deriving>`__ clause (at the top level). + +.. _data-family-import-export: + +Import and export +----------------- + +The rules for export lists (Haskell Report `Section +5.2 <http://www.haskell.org/onlinereport/modules.html#sect5.2>`__) needs +adjustment for type families: + +- The form ``T(..)``, where ``T`` is a data family, names the family + ``T`` and all the in-scope constructors (whether in scope qualified + or unqualified) that are data instances of ``T``. + +- The form ``T(.., ci, .., fj, ..)``, where ``T`` is a data family, + names ``T`` and the specified constructors ``ci`` and fields ``fj`` + as usual. The constructors and field names must belong to some data + instance of ``T``, but are not required to belong to the *same* + instance. + +- The form ``C(..)``, where ``C`` is a class, names the class ``C`` and + all its methods *and associated types*. + +- The form ``C(.., mi, .., type Tj, ..)``, where ``C`` is a class, + names the class ``C``, and the specified methods ``mi`` and + associated types ``Tj``. The types need a keyword "``type``" to + distinguish them from data constructors. + +.. _data-family-impexp-examples: + +Examples +~~~~~~~~ + +Recall our running ``GMapKey`` class example: + +:: + + class GMapKey k where + data GMap k :: * -> * + insert :: GMap k v -> k -> v -> GMap k v + lookup :: GMap k v -> k -> Maybe v + empty :: GMap k v + + instance (GMapKey a, GMapKey b) => GMapKey (Either a b) where + data GMap (Either a b) v = GMapEither (GMap a v) (GMap b v) + ...method declarations... + +Here are some export lists and their meaning: + +- :: + + module GMap( GMapKey ) + + Exports just the class name. + +- :: + + module GMap( GMapKey(..) ) + + Exports the class, the associated type ``GMap`` and the member functions + ``empty``, ``lookup``, and ``insert``. The data constructors of ``GMap`` (in + this case ``GMapEither``) are not exported. + +- :: + + module GMap( GMapKey( type GMap, empty, lookup, insert ) ) + + Same as the previous item. Note the "``type``" keyword. + +- :: + + module GMap( GMapKey(..), GMap(..) ) + + Same as previous item, but also exports all the data constructors for + ``GMap``, namely + ``GMapEither``. + +- :: + + module GMap ( GMapKey( empty, lookup, insert), GMap(..) ) + + Same as previous item. + +- :: + + module GMap ( GMapKey, empty, lookup, insert, GMap(..) ) + + Same as previous item. + +Two things to watch out for: + +- You cannot write ``GMapKey(type GMap(..))`` — i.e., sub-component + specifications cannot be nested. To specify ``GMap``\ 's data + constructors, you have to list it separately. + +- Consider this example: + + :: + + module X where + data family D + + module Y where + import X + data instance D Int = D1 | D2 + + Module Y exports all the entities defined in Y, namely the data + constructors ``D1`` and ``D2``, *but not the data family* ``D``. That + (annoyingly) means that you cannot selectively import Y selectively, + thus "``import Y( D(D1,D2) )``", because Y does not export ``D``. + Instead you should list the exports explicitly, thus: + + :: + + module Y( D(..) ) where ... + or module Y( module Y, D ) where ... + +.. _data-family-impexp-instances: + +Instances +~~~~~~~~~ + +Family instances are implicitly exported, just like class instances. +However, this applies only to the heads of instances, not to the data +constructors an instance defines. + +.. _ty-fams-in-instances: + +Type families and instance declarations +--------------------------------------- + +Type families require us to extend the rules for the form of instance +heads, which are given in :ref:`flexible-instance-head`. Specifically: + +- Data type families may appear in an instance head + +- Type synonym families may not appear (at all) in an instance head + +The reason for the latter restriction is that there is no way to check +for instance matching. Consider + +:: + + type family F a + type instance F Bool = Int + + class C a + + instance C Int + instance C (F a) + +Now a constraint ``(C (F Bool))`` would match both instances. The +situation is especially bad because the type instance for ``F Bool`` +might be in another module, or even in a module that is not yet written. + +However, type class instances of instances of data families can be +defined much like any other data type. For example, we can say + +:: + + data instance T Int = T1 Int | T2 Bool + instance Eq (T Int) where + (T1 i) == (T1 j) = i==j + (T2 i) == (T2 j) = i==j + _ == _ = False + +Note that class instances are always for particular *instances* of a +data family and never for an entire family as a whole. This is for +essentially the same reasons that we cannot define a toplevel function +that performs pattern matching on the data constructors of *different* +instances of a single type family. It would require a form of extensible +case construct. + +Data instance declarations can also have ``deriving`` clauses. For +example, we can write + +:: + + data GMap () v = GMapUnit (Maybe v) + deriving Show + +which implicitly defines an instance of the form + +:: + + instance Show v => Show (GMap () v) where ... + +.. _injective-ty-fams: + +Injective type families +----------------------- + +Starting with GHC 7.12 type families can be annotated with injectivity +information. This information is then used by GHC during type checking +to resolve type ambiguities in situations where a type variable appears +only under type family applications. + +For full details on injective type families refer to Haskell Symposium +2015 paper `Injective type families for +Haskell <http://ics.p.lodz.pl/~stolarek/_media/pl:research:stolarek_peyton-jones_eisenberg_injectivity_extended.pdf>`__. + +.. _injective-ty-fams-syntax: + +Syntax of injectivity annotation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Injectivity annotation is added after type family head and consists of +two parts: + +- a type variable that names the result of a type family. Syntax: + ``= tyvar`` or ``= (tyvar :: kind)``. Type variable must be fresh. + +- an injectivity annotation of the form ``| A -> B``, where ``A`` is the + result type variable (see previous bullet) and ``B`` is a list of + argument type and kind variables in which type family is injective. + It is possible to omit some variables if type family is not injective + in them. + +Examples: + +:: + + type family Id a = result | result -> a where + type family F a b c = d | d -> a c b + type family G (a :: k) b c = foo | foo -> k b where + +For open and closed type families it is OK to name the result but skip +the injectivity annotation. This is not the case for associated type +synonyms, where the named result without injectivity annotation will be +interpreted as associated type synonym default. + +.. _injective-ty-fams-typecheck: + +Verifying injectivity annotation against type family equations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once the user declares type family to be injective GHC must verify that +this declaration is correct, ie. type family equations don't violate the +injectivity annotation. A general idea is that if at least one equation +(bullets (1), (2) and (3) below) or a pair of equations (bullets (4) and +(5) below) violates the injectivity annotation then a type family is not +injective in a way user claims and an error is reported. In the bullets +below *RHS* refers to the right-hand side of the type family equation +being checked for injectivity. *LHS* refers to the arguments of that +type family equation. Below are the rules followed when checking +injectivity of a type family: + +1. If a RHS of a type family equation is a type family application GHC + reports that the type family is not injective. + +2. If a RHS of a type family equation is a bare type variable we require + that all LHS variables (including implicit kind variables) are also + bare. In other words, this has to be a sole equation of that type + family and it has to cover all possible patterns. If the patterns are + not covering GHC reports that the type family is not injective. + +3. If a LHS type variable that is declared as injective is not mentioned + on injective position + in the RHS GHC reports that the type family is not injective. + Injective position means either argument to a type constructor or + injective argument to a type family. + +4. *Open type families*\ Open type families are typechecked + incrementally. This means that when a module is imported type family + instances contained in that module are checked against instances + present in already imported modules. + + A pair of an open type family equations is checked by attempting to + unify their RHSs. If the RHSs don't unify this pair does not violate + injectivity annotation. If unification succeeds with a substitution + then LHSs of unified equations must be identical under that + substitution. If they are not identical then GHC reports that the + type family is not injective. + +5. In a *closed type family* all equations are ordered and in one place. + Equations are also checked pair-wise but this time an equation has to + be paired with all the preceeding equations. Of course a + single-equation closed type family is trivially injective (unless + (1), (2) or (3) above holds). + + When checking a pair of closed type family equations GHC tried to + unify their RHSs. If they don't unify this pair of equations does not + violate injectivity annotation. If the RHSs can be unified under some + substitution (possibly empty) then either the LHSs unify under the + same substitution or the LHS of the latter equation is subsumed by + earlier equations. If neither condition is met GHC reports that a + type family is not injective. + +Note that for the purpose of injectivity check in bullets (4) and (5) +GHC uses a special variant of unification algorithm that treats type +family applications as possibly unifying with anything. + +.. _kind-polymorphism: + +Kind polymorphism +================= + +This section describes *kind polymorphism*, and extension enabled by +``-XPolyKinds``. It is described in more detail in the paper `Giving +Haskell a Promotion <http://dreixel.net/research/pdf/ghp.pdf>`__, which +appeared at TLDI 2012. + +Overview of kind polymorphism +----------------------------- + +Currently there is a lot of code duplication in the way ``Typeable`` is +implemented (:ref:`deriving-typeable`): + +:: + + class Typeable (t :: *) where + typeOf :: t -> TypeRep + + class Typeable1 (t :: * -> *) where + typeOf1 :: t a -> TypeRep + + class Typeable2 (t :: * -> * -> *) where + typeOf2 :: t a b -> TypeRep + +Kind polymorphism (with ``-XPolyKinds``) allows us to merge all these +classes into one: + +:: + + data Proxy t = Proxy + + class Typeable t where + typeOf :: Proxy t -> TypeRep + + instance Typeable Int where typeOf _ = TypeRep + instance Typeable [] where typeOf _ = TypeRep + +Note that the datatype ``Proxy`` has kind ``forall k. k -> *`` (inferred +by GHC), and the new ``Typeable`` class has kind +``forall k. k -> Constraint``. + +Note the following specific points: + +- Generally speaking, with ``-XPolyKinds``, GHC will infer a + polymorphic kind for un-decorated declarations, whenever possible. + For example, in GHCi + + :: + + ghci> :set -XPolyKinds + ghci> data T m a = MkT (m a) + ghci> :k T + T :: (k -> *) -> k -> * + +- GHC does not usually print explicit ``forall``\ s, including kind + ``forall``\ s. You can make GHC show them explicitly with + ``-fprint-explicit-foralls`` (see :ref:`options-help`): + + :: + + ghci> :set -XPolyKinds + ghci> :set -fprint-explicit-foralls + ghci> data T m a = MkT (m a) + ghci> :k T + T :: forall (k :: BOX). (k -> *) -> k -> * + + Here the kind variable ``k`` itself has a kind annotation "``BOX``". + This is just GHC's way of saying "``k`` is a kind variable". + +- Just as in the world of terms, you can restrict polymorphism using a + kind signature (sometimes called a kind annotation) + + :: + + data T m (a :: *) = MkT (m a) + -- GHC now infers kind T :: (* -> *) -> * -> * + + NB: ``-XPolyKinds`` implies ``-XKindSignatures`` (see + :ref:`kinding`). + +- The source language does not support an explicit ``forall`` for kind + variables. Instead, when binding a type variable, you can simply + mention a kind variable in a kind annotation for that type-variable + binding, thus: + + :: + + data T (m :: k -> *) a = MkT (m a) + -- GHC now infers kind T :: forall k. (k -> *) -> k -> * + +- The (implicit) kind "forall" is placed just outside the outermost + type-variable binding whose kind annotation mentions the kind + variable. For example + + :: + + f1 :: (forall a m. m a -> Int) -> Int + -- f1 :: forall (k::BOX). + -- (forall (a::k) (m::k->*). m a -> Int) + -- -> Int + + f2 :: (forall (a::k) m. m a -> Int) -> Int + -- f2 :: (forall (k::BOX) (a::k) (m::k->*). m a -> Int) + -- -> Int + + Here in ``f1`` there is no kind annotation mentioning the polymorphic + kind variable, so ``k`` is generalised at the top level of the + signature for ``f1``. But in the case of of ``f2`` we give a kind + annotation in the ``forall (a:k)`` binding, and GHC therefore puts + the kind ``forall`` right there too. This design decision makes + default case (``f1``) as polymorphic as possible; remember that a + *more* polymorphic argument type (as in ``f2`` makes the overall + function *less* polymorphic, because there are fewer acceptable + arguments. + +.. note:: + + These rules are a bit indirect and clumsy. Perhaps GHC should + allow explicit kind quantification. But the implicit quantification + (e.g. in the declaration for data type T above) is certainly very + convenient, and it is not clear what the syntax for explicit + quantification should be. + +Principles of kind inference +---------------------------- + +Generally speaking, when ``-XPolyKinds`` is on, GHC tries to infer the +most general kind for a declaration. For example: + +:: + + data T f a = MkT (f a) -- GHC infers: + -- T :: forall k. (k->*) -> k -> * + +In this case the definition has a right-hand side to inform kind +inference. But that is not always the case. Consider + +:: + + type family F a + +Type family declarations have no right-hand side, but GHC must still +infer a kind for ``F``. Since there are no constraints, it could infer +``F :: forall k1 k2. k1 -> k2``, but that seems *too* polymorphic. So +GHC defaults those entirely-unconstrained kind variables to ``*`` and we +get ``F :: * -> *``. You can still declare ``F`` to be kind-polymorphic +using kind signatures: + +:: + + type family F1 a -- F1 :: * -> * + type family F2 (a :: k) -- F2 :: forall k. k -> * + type family F3 a :: k -- F3 :: forall k. * -> k + type family F4 (a :: k1) :: k -- F4 :: forall k1 k2. k1 -> k2 + +The general principle is this: + +- *When there is a right-hand side, GHC infers the most polymorphic + kind consistent with the right-hand side.* Examples: ordinary data + type and GADT declarations, class declarations. In the case of a + class declaration the role of "right hand side" is played by the + class method signatures. + +- *When there is no right hand side, GHC defaults argument and result + kinds to ``*``, except when directed otherwise by a kind signature*. + Examples: data and type family declarations. + +This rule has occasionally-surprising consequences (see +:ghc-ticket:`10132`. + +:: + + class C a where -- Class declarations are generalised + -- so C :: forall k. k -> Constraint + data D1 a -- No right hand side for these two family + type F1 a -- declarations, but the class forces (a :: k) + -- so D1, F1 :: forall k. k -> * + + data D2 a -- No right-hand side so D2 :: * -> * + type F2 a -- No right-hand side so F2 :: * -> * + +The kind-polymorphism from the class declaration makes ``D1`` +kind-polymorphic, but not so ``D2``; and similarly ``F1``, ``F1``. + +.. _complete-kind-signatures: + +Polymorphic kind recursion and complete kind signatures +------------------------------------------------------- + +Just as in type inference, kind inference for recursive types can only +use *monomorphic* recursion. Consider this (contrived) example: + +:: + + data T m a = MkT (m a) (T Maybe (m a)) + -- GHC infers kind T :: (* -> *) -> * -> * + +The recursive use of ``T`` forced the second argument to have kind +``*``. However, just as in type inference, you can achieve polymorphic +recursion by giving a *complete kind signature* for ``T``. A complete +kind signature is present when all argument kinds and the result kind +are known, without any need for inference. For example: + +:: + + data T (m :: k -> *) :: k -> * where + MkT :: m a -> T Maybe (m a) -> T m a + +The complete user-supplied kind signature specifies the polymorphic kind +for ``T``, and this signature is used for all the calls to ``T`` +including the recursive ones. In particular, the recursive use of ``T`` +is at kind ``*``. + +What exactly is considered to be a "complete user-supplied kind +signature" for a type constructor? These are the forms: + +- For a datatype, every type variable must be annotated with a kind. In + a GADT-style declaration, there may also be a kind signature (with a + top-level ``::`` in the header), but the presence or absence of this + annotation does not affect whether or not the declaration has a + complete signature. + + :: + + data T1 :: (k -> *) -> k -> * where ... + -- Yes T1 :: forall k. (k->*) -> k -> * + + data T2 (a :: k -> *) :: k -> * where ... + -- Yes T2 :: forall k. (k->*) -> k -> * + + data T3 (a :: k -> *) (b :: k) :: * where ... + -- Yes T3 :: forall k. (k->*) -> k -> * + + data T4 (a :: k -> *) (b :: k) where ... + -- Yes T4 :: forall k. (k->*) -> k -> * + + data T5 a (b :: k) :: * where ... + -- No kind is inferred + + data T6 a b where ... + -- No kind is inferred + +- For a class, every type variable must be annotated with a kind. + +- For a type synonym, every type variable and the result type must all + be annotated with kinds. + + :: + + type S1 (a :: k) = (a :: k) -- Yes S1 :: forall k. k -> k + type S2 (a :: k) = a -- No kind is inferred + type S3 (a :: k) = Proxy a -- No kind is inferred + + Note that in ``S2`` and ``S3``, the kind of the right-hand side is + rather apparent, but it is still not considered to have a complete + signature -- no inference can be done before detecting the signature. + +- An open type or data family declaration *always* has a complete + user-specified kind signature; un-annotated type variables default to + kind ``*``. + + :: + + data family D1 a -- D1 :: * -> * + data family D2 (a :: k) -- D2 :: forall k. k -> * + data family D3 (a :: k) :: * -- D3 :: forall k. k -> * + type family S1 a :: k -> * -- S1 :: forall k. * -> k -> * + + class C a where -- C :: k -> Constraint + type AT a b -- AT :: k -> * -> * + + In the last example, the variable ``a`` has an implicit kind variable + annotation from the class declaration. It keeps its polymorphic kind + in the associated type declaration. The variable ``b``, however, gets + defaulted to ``*``. + +- A closed type family has a complete signature when all of its type + variables are annotated and a return kind (with a top-level ``::``) + is supplied. + +Kind inference in closed type families +-------------------------------------- + +Although all open type families are considered to have a complete +user-specified kind signature, we can relax this condition for closed +type families, where we have equations on which to perform kind +inference. GHC will infer kinds for the arguments and result types of a +closed type family. + +GHC supports *kind-indexed* type families, where the family matches both +on the kind and type. GHC will *not* infer this behaviour without a +complete user-supplied kind signature, as doing so would sometimes infer +non-principal types. + +For example: + +:: + + type family F1 a where + F1 True = False + F1 False = True + F1 x = x + -- F1 fails to compile: kind-indexing is not inferred + + type family F2 (a :: k) where + F2 True = False + F2 False = True + F2 x = x + -- F2 fails to compile: no complete signature + + type family F3 (a :: k) :: k where + F3 True = False + F3 False = True + F3 x = x + -- OK + +Kind inference in class instance declarations +--------------------------------------------- + +Consider the following example of a poly-kinded class and an instance +for it: + +:: + + class C a where + type F a + + instance C b where + type F b = b -> b + +In the class declaration, nothing constrains the kind of the type ``a``, +so it becomes a poly-kinded type variable ``(a :: k)``. Yet, in the +instance declaration, the right-hand side of the associated type +instance ``b -> b`` says that ``b`` must be of kind ``*``. GHC could +theoretically propagate this information back into the instance head, +and make that instance declaration apply only to type of kind ``*``, as +opposed to types of any kind. However, GHC does *not* do this. + +In short: GHC does *not* propagate kind information from the members of +a class instance declaration into the instance declaration head. + +This lack of kind inference is simply an engineering problem within GHC, +but getting it to work would make a substantial change to the inference +infrastructure, and it's not clear the payoff is worth it. If you want +to restrict ``b``\ 's kind in the instance above, just use a kind +signature in the instance head. + +.. _promotion: + +Datatype promotion +================== + +This section describes *data type promotion*, an extension to the kind +system that complements kind polymorphism. It is enabled by +``-XDataKinds``, and described in more detail in the paper `Giving +Haskell a Promotion <http://dreixel.net/research/pdf/ghp.pdf>`__, which +appeared at TLDI 2012. + +Motivation +---------- + +Standard Haskell has a rich type language. Types classify terms and +serve to avoid many common programming mistakes. The kind language, +however, is relatively simple, distinguishing only lifted types (kind +``*``), type constructors (e.g. kind ``* -> * -> *``), and unlifted +types (:ref:`glasgow-unboxed`). In particular when using advanced type +system features, such as type families (:ref:`type-families`) or GADTs +(:ref:`gadt`), this simple kind system is insufficient, and fails to +prevent simple errors. Consider the example of type-level natural +numbers, and length-indexed vectors: + +:: + + data Ze + data Su n + + data Vec :: * -> * -> * where + Nil :: Vec a Ze + Cons :: a -> Vec a n -> Vec a (Su n) + +The kind of ``Vec`` is ``* -> * -> *``. This means that eg. +``Vec Int Char`` is a well-kinded type, even though this is not what we +intend when defining length-indexed vectors. + +With ``-XDataKinds``, the example above can then be rewritten to: + +:: + + data Nat = Ze | Su Nat + + data Vec :: * -> Nat -> * where + Nil :: Vec a Ze + Cons :: a -> Vec a n -> Vec a (Su n) + +With the improved kind of ``Vec``, things like ``Vec Int Char`` are now +ill-kinded, and GHC will report an error. + +Overview +-------- + +With ``-XDataKinds``, GHC automatically promotes every suitable datatype +to be a kind, and its (value) constructors to be type constructors. The +following types + +:: + + data Nat = Ze | Su Nat + + data List a = Nil | Cons a (List a) + + data Pair a b = Pair a b + + data Sum a b = L a | R b + +give rise to the following kinds and type constructors: + +:: + + Nat :: BOX + Ze :: Nat + Su :: Nat -> Nat + + List k :: BOX + Nil :: List k + Cons :: k -> List k -> List k + + Pair k1 k2 :: BOX + Pair :: k1 -> k2 -> Pair k1 k2 + + Sum k1 k2 :: BOX + L :: k1 -> Sum k1 k2 + R :: k2 -> Sum k1 k2 + +where ``BOX`` is the (unique) sort that classifies kinds. Note that +``List``, for instance, does not get sort ``BOX -> BOX``, because we do +not further classify kinds; all kinds have sort ``BOX``. + +The following restrictions apply to promotion: + +- We promote ``data`` types and ``newtypes``, but not type synonyms, or + type/data families (:ref:`type-families`). + +- We only promote types whose kinds are of the form + ``* -> ... -> * -> *``. In particular, we do not promote + higher-kinded datatypes such as ``data Fix f = In (f (Fix f))``, or + datatypes whose kinds involve promoted types such as + ``Vec :: * -> Nat -> *``. + +- We do not promote data constructors that are kind polymorphic, + involve constraints, mention type or data families, or involve types + that are not promotable. + +.. _promotion-syntax: + +Distinguishing between types and constructors +--------------------------------------------- + +Since constructors and types share the same namespace, with promotion +you can get ambiguous type names: + +:: + + data P -- 1 + + data Prom = P -- 2 + + type T = P -- 1 or promoted 2? + +In these cases, if you want to refer to the promoted constructor, you +should prefix its name with a quote: + +:: + + type T1 = P -- 1 + + type T2 = 'P -- promoted 2 + +Note that promoted datatypes give rise to named kinds. Since these can +never be ambiguous, we do not allow quotes in kind names. + +Just as in the case of Template Haskell (:ref:`th-syntax`), there is no +way to quote a data constructor or type constructor whose second +character is a single quote. + +.. _promoted-lists-and-tuples: + +Promoted list and tuple types +----------------------------- + +With ``-XDataKinds``, Haskell's list and tuple types are natively +promoted to kinds, and enjoy the same convenient syntax at the type +level, albeit prefixed with a quote: + +:: + + data HList :: [*] -> * where + HNil :: HList '[] + HCons :: a -> HList t -> HList (a ': t) + + data Tuple :: (*,*) -> * where + Tuple :: a -> b -> Tuple '(a,b) + + foo0 :: HList '[] + foo0 = HNil + + foo1 :: HList '[Int] + foo1 = HCons (3::Int) HNil + + foo2 :: HList [Int, Bool] + foo2 = ... + +(Note: the declaration for ``HCons`` also requires ``-XTypeOperators`` +because of infix type operator ``(:')``.) For type-level lists of *two +or more elements*, such as the signature of ``foo2`` above, the quote +may be omitted because the meaning is unambiguous. But for lists of one +or zero elements (as in ``foo0`` and ``foo1``), the quote is required, +because the types ``[]`` and ``[Int]`` have existing meanings in +Haskell. + +.. _promotion-existentials: + +Promoting existential data constructors +--------------------------------------- + +Note that we do promote existential data constructors that are otherwise +suitable. For example, consider the following: + +:: + + data Ex :: * where + MkEx :: forall a. a -> Ex + +Both the type ``Ex`` and the data constructor ``MkEx`` get promoted, +with the polymorphic kind ``'MkEx :: forall k. k -> Ex``. Somewhat +surprisingly, you can write a type family to extract the member of a +type-level existential: + +:: + + type family UnEx (ex :: Ex) :: k + type instance UnEx (MkEx x) = x + +At first blush, ``UnEx`` seems poorly-kinded. The return kind ``k`` is +not mentioned in the arguments, and thus it would seem that an instance +would have to return a member of ``k`` *for any* ``k``. However, this is +not the case. The type family ``UnEx`` is a kind-indexed type family. +The return kind ``k`` is an implicit parameter to ``UnEx``. The +elaborated definitions are as follows: + +:: + + type family UnEx (k :: BOX) (ex :: Ex) :: k + type instance UnEx k (MkEx k x) = x + +Thus, the instance triggers only when the implicit parameter to ``UnEx`` +matches the implicit parameter to ``MkEx``. Because ``k`` is actually a +parameter to ``UnEx``, the kind is not escaping the existential, and the +above code is valid. + +See also :ghc-ticket:`7347`. + +Promoting type operators +------------------------ + +Type operators are *not* promoted to the kind level. Why not? Because +``*`` is a kind, parsed the way identifiers are. Thus, if a programmer +tried to write ``Either * Bool``, would it be ``Either`` applied to +``*`` and ``Bool``? Or would it be ``*`` applied to ``Either`` and +``Bool``. To avoid this quagmire, we simply forbid promoting type +operators to the kind level. + +.. _type-level-literals: + +Type-Level Literals +=================== + +GHC supports numeric and string literals at the type level, giving +convenient access to a large number of predefined type-level constants. +Numeric literals are of kind ``Nat``, while string literals are of kind +``Symbol``. This feature is enabled by the ``XDataKinds`` language +extension. + +The kinds of the literals and all other low-level operations for this +feature are defined in module ``GHC.TypeLits``. Note that the module +defines some type-level operators that clash with their value-level +counterparts (e.g. ``(+)``). Import and export declarations referring to +these operators require an explicit namespace annotation (see +:ref:`explicit-namespaces`). + +Here is an example of using type-level numeric literals to provide a +safe interface to a low-level function: + +:: + + import GHC.TypeLits + import Data.Word + import Foreign + + newtype ArrPtr (n :: Nat) a = ArrPtr (Ptr a) + + clearPage :: ArrPtr 4096 Word8 -> IO () + clearPage (ArrPtr p) = ... + +Here is an example of using type-level string literals to simulate +simple record operations: + +:: + + data Label (l :: Symbol) = Get + + class Has a l b | a l -> b where + from :: a -> Label l -> b + + data Point = Point Int Int deriving Show + + instance Has Point "x" Int where from (Point x _) _ = x + instance Has Point "y" Int where from (Point _ y) _ = y + + example = from (Point 1 2) (Get :: Label "x") + +.. _typelit-runtime: + +Runtime Values for Type-Level Literals +-------------------------------------- + +Sometimes it is useful to access the value-level literal associated with +a type-level literal. This is done with the functions ``natVal`` and +``symbolVal``. For example: + +:: + + GHC.TypeLits> natVal (Proxy :: Proxy 2) + 2 + +These functions are overloaded because they need to return a different +result, depending on the type at which they are instantiated. + +:: + + natVal :: KnownNat n => proxy n -> Integer + + -- instance KnownNat 0 + -- instance KnownNat 1 + -- instance KnownNat 2 + -- ... + +GHC discharges the constraint as soon as it knows what concrete +type-level literal is being used in the program. Note that this works +only for *literals* and not arbitrary type expressions. For example, a +constraint of the form ``KnownNat (a + b)`` will *not* be simplified to +``(KnownNat a, KnownNat b)``; instead, GHC will keep the constraint as +is, until it can simplify ``a + b`` to a constant value. + +It is also possible to convert a run-time integer or string value to the +corresponding type-level literal. Of course, the resulting type literal +will be unknown at compile-time, so it is hidden in an existential type. +The conversion may be performed using ``someNatVal`` for integers and +``someSymbolVal`` for strings: + +:: + + someNatVal :: Integer -> Maybe SomeNat + SomeNat :: KnownNat n => Proxy n -> SomeNat + +The operations on strings are similar. + +.. _typelit-tyfuns: + +Computing With Type-Level Naturals +---------------------------------- + +GHC 7.8 can evaluate arithmetic expressions involving type-level natural +numbers. Such expressions may be constructed using the type-families +``(+), (*), (^)`` for addition, multiplication, and exponentiation. +Numbers may be compared using ``(<=?)``, which returns a promoted +boolean value, or ``(<=)``, which compares numbers as a constraint. For +example: + +:: + + GHC.TypeLits> natVal (Proxy :: Proxy (2 + 3)) + 5 + +At present, GHC is quite limited in its reasoning about arithmetic: it +will only evaluate the arithmetic type functions and compare the +results--- in the same way that it does for any other type function. In +particular, it does not know more general facts about arithmetic, such +as the commutativity and associativity of ``(+)``, for example. + +However, it is possible to perform a bit of "backwards" evaluation. For +example, here is how we could get GHC to compute arbitrary logarithms at +the type level: + +:: + + lg :: Proxy base -> Proxy (base ^ pow) -> Proxy pow + lg _ _ = Proxy + + GHC.TypeLits> natVal (lg (Proxy :: Proxy 2) (Proxy :: Proxy 8)) + 3 + +.. _equality-constraints: + +Equality constraints +==================== + +A type context can include equality constraints of the form ``t1 ~ t2``, +which denote that the types ``t1`` and ``t2`` need to be the same. In +the presence of type families, whether two types are equal cannot +generally be decided locally. Hence, the contexts of function signatures +may include equality constraints, as in the following example: + +:: + + sumCollects :: (Collects c1, Collects c2, Elem c1 ~ Elem c2) => c1 -> c2 -> c2 + +where we require that the element type of ``c1`` and ``c2`` are the +same. In general, the types ``t1`` and ``t2`` of an equality constraint +may be arbitrary monotypes; i.e., they may not contain any quantifiers, +independent of whether higher-rank types are otherwise enabled. + +Equality constraints can also appear in class and instance contexts. The +former enable a simple translation of programs using functional +dependencies into programs using family synonyms instead. The general +idea is to rewrite a class declaration of the form + +:: + + class C a b | a -> b + +to + +:: + + class (F a ~ b) => C a b where + type F a + +That is, we represent every functional dependency (FD) ``a1 .. an -> b`` +by an FD type family ``F a1 .. an`` and a superclass context equality +``F a1 .. an ~ b``, essentially giving a name to the functional +dependency. In class instances, we define the type instances of FD +families in accordance with the class head. Method signatures are not +affected by that process. + +.. _coercible: + +The ``Coercible`` constraint +---------------------------- + +The constraint ``Coercible t1 t2`` is similar to ``t1 ~ t2``, but +denotes representational equality between ``t1`` and ``t2`` in the sense +of Roles (:ref:`roles`). It is exported by +:base-ref:`Data.Coerce <Data-Coerce.html>`, which also +contains the documentation. More details and discussion can be found in +the paper +`"Safe Coercions" <http://www.cis.upenn.edu/~eir/papers/2014/coercible/coercible.pdf>`__. + +.. _constraint-kind: + +The ``Constraint`` kind +======================= + +Normally, *constraints* (which appear in types to the left of the ``=>`` +arrow) have a very restricted syntax. They can only be: + +- Class constraints, e.g. ``Show a`` + +- `Implicit parameter <#implicit-parameters>`__ constraints, e.g. + ``?x::Int`` (with the ``-XImplicitParams`` flag) + +- `Equality constraints <#equality-constraints>`__, e.g. ``a ~ Int`` + (with the ``-XTypeFamilies`` or ``-XGADTs`` flag) + +With the ``-XConstraintKinds`` flag, GHC becomes more liberal in what it +accepts as constraints in your program. To be precise, with this flag +any *type* of the new kind ``Constraint`` can be used as a constraint. +The following things have kind ``Constraint``: + +- Anything which is already valid as a constraint without the flag: + saturated applications to type classes, implicit parameter and + equality constraints. + +- Tuples, all of whose component types have kind ``Constraint``. So for example + the type ``(Show a, Ord a)`` is of kind ``Constraint``. + +- Anything whose form is not yet known, but the user has declared to + have kind ``Constraint`` (for which they need to import it from + ``GHC.Exts``). So for example + ``type Foo (f :: \* -> Constraint) = forall b. f b => b -> b`` + is allowed, as well as examples involving type families: + + :: + + type family Typ a b :: Constraint + type instance Typ Int b = Show b + type instance Typ Bool b = Num b + + func :: Typ a b => a -> b -> b + func = ... + +Note that because constraints are just handled as types of a particular +kind, this extension allows type constraint synonyms: + +:: + + type Stringy a = (Read a, Show a) + foo :: Stringy a => a -> (String, String -> a) + foo x = (show x, read) + +Presently, only standard constraints, tuples and type synonyms for those +two sorts of constraint are permitted in instance contexts and +superclasses (without extra flags). The reason is that permitting more +general constraints can cause type checking to loop, as it would with +these two programs: + +:: + + type family Clsish u a + type instance Clsish () a = Cls a + class Clsish () a => Cls a where + +:: + + class OkCls a where + + type family OkClsish u a + type instance OkClsish () a = OkCls a + instance OkClsish () a => OkCls a where + +You may write programs that use exotic sorts of constraints in instance +contexts and superclasses, but to do so you must use +``-XUndecidableInstances`` to signal that you don't mind if the type +checker fails to terminate. + +.. _other-type-extensions: + +Other type system extensions +============================ + +.. _explicit-foralls: + +Explicit universal quantification (forall) +------------------------------------------ + +Haskell type signatures are implicitly quantified. When the language +option ``-XExplicitForAll`` is used, the keyword ``forall`` allows us to +say exactly what this means. For example: + +:: + + g :: b -> b + +means this: + +:: + + g :: forall b. (b -> b) + +The two are treated identically. + +Of course ``forall`` becomes a keyword; you can't use ``forall`` as a +type variable any more! + +.. _flexible-contexts: + +The context of a type signature +------------------------------- + +The ``-XFlexibleContexts`` flag lifts the Haskell 98 restriction that +the type-class constraints in a type signature must have the form +*(class type-variable)* or *(class (type-variable type1 type2 ... +typen))*. With ``-XFlexibleContexts`` these type signatures are +perfectly okay + +:: + + g :: Eq [a] => ... + g :: Ord (T a ()) => ... + +The flag ``-XFlexibleContexts`` also lifts the corresponding restriction +on class declarations (:ref:`superclass-rules`) and instance +declarations (:ref:`instance-rules`). + +.. _ambiguity: + +Ambiguous types and the ambiguity check +--------------------------------------- + +Each user-written type signature is subjected to an *ambiguity check*. +The ambiguity check rejects functions that can never be called; for +example: + +:: + + f :: C a => Int + +The idea is there can be no legal calls to ``f`` because every call will +give rise to an ambiguous constraint. Indeed, the *only* purpose of the +ambiguity check is to report functions that cannot possibly be called. +We could soundly omit the ambiguity check on type signatures entirely, +at the expense of delaying ambiguity errors to call sites. Indeed, the +language extension ``-XAllowAmbiguousTypes`` switches off the ambiguity +check. + +Ambiguity can be subtle. Consider this example which uses functional +dependencies: + +:: + + class D a b | a -> b where .. + h :: D Int b => Int + +The ``Int`` may well fix ``b`` at the call site, so that signature +should not be rejected. Moreover, the dependencies might be hidden. +Consider + +:: + + class X a b where ... + class D a b | a -> b where ... + instance D a b => X [a] b where... + h :: X a b => a -> a + +Here ``h``\ 's type looks ambiguous in ``b``, but here's a legal call: + +:: + + ...(h [True])... + +That gives rise to a ``(X [Bool] beta)`` constraint, and using the +instance means we need ``(D Bool beta)`` and that fixes ``beta`` via +``D``'s fundep! + +Behind all these special cases there is a simple guiding principle. +Consider + +:: + + f :: type + f = ...blah... + + g :: type + g = f + +You would think that the definition of ``g`` would surely typecheck! +After all ``f`` has exactly the same type, and ``g=f``. But in fact +``f``\ 's type is instantiated and the instantiated constraints are solved +against the constraints bound by ``g``\ 's signature. So, in the case an +ambiguous type, solving will fail. For example, consider the earlier +definition ``f :: C a => Int``: + +:: + + f :: C a => Int + f = ...blah... + + g :: C a => Int + g = f + +In ``g``'s definition, we'll instantiate to ``(C alpha)`` and try to +deduce ``(C alpha)`` from ``(C a)``, and fail. + +So in fact we use this as our *definition* of ambiguity: a type ``ty`` +is ambiguous if and only if ``((undefined :: ty) :: ty)`` would fail to +typecheck. We use a very similar test for *inferred* types, to ensure +that they too are unambiguous. + +*Switching off the ambiguity check.* Even if a function is has an +ambiguous type according the "guiding principle", it is possible that +the function is callable. For example: + +:: + + class D a b where ... + instance D Bool b where ... + + strange :: D a b => a -> a + strange = ...blah... + + foo = strange True + +Here ``strange``'s type is ambiguous, but the call in ``foo`` is OK +because it gives rise to a constraint ``(D Bool beta)``, which is +soluble by the ``(D Bool b)`` instance. So the language extension +``-XAllowAmbiguousTypes`` allows you to switch off the ambiguity check. +But even with ambiguity checking switched off, GHC will complain about a +function that can *never* be called, such as this one: + +:: + + f :: (Int ~ Bool) => a -> a + +.. note:: + *A historical note.* GHC used to impose some more restrictive and less + principled conditions on type signatures. For type type + ``forall tv1..tvn (c1, ...,cn) => type`` GHC used to require (a) that + each universally quantified type variable ``tvi`` must be "reachable" + from ``type``, and (b) that every constraint ``ci`` mentions at least + one of the universally quantified type variables ``tvi``. These ad-hoc + restrictions are completely subsumed by the new ambiguity check. + +.. _implicit-parameters: + +Implicit parameters +------------------- + +Implicit parameters are implemented as described in "Implicit +parameters: dynamic scoping with static types", J Lewis, MB Shields, E +Meijer, J Launchbury, 27th ACM Symposium on Principles of Programming +Languages (POPL'00), Boston, Jan 2000. (Most of the following, still +rather incomplete, documentation is due to Jeff Lewis.) + +Implicit parameter support is enabled with the option +``-XImplicitParams``. + +A variable is called *dynamically bound* when it is bound by the calling +context of a function and *statically bound* when bound by the callee's +context. In Haskell, all variables are statically bound. Dynamic binding +of variables is a notion that goes back to Lisp, but was later discarded +in more modern incarnations, such as Scheme. Dynamic binding can be very +confusing in an untyped language, and unfortunately, typed languages, in +particular Hindley-Milner typed languages like Haskell, only support +static scoping of variables. + +However, by a simple extension to the type class system of Haskell, we +can support dynamic binding. Basically, we express the use of a +dynamically bound variable as a constraint on the type. These +constraints lead to types of the form ``(?x::t') => t``, which says +"this function uses a dynamically-bound variable ``?x`` of type ``t'``". +For example, the following expresses the type of a sort function, +implicitly parameterised by a comparison function named ``cmp``. + +:: + + sort :: (?cmp :: a -> a -> Bool) => [a] -> [a] + +The dynamic binding constraints are just a new form of predicate in the +type class system. + +An implicit parameter occurs in an expression using the special form +``?x``, where ``x`` is any valid identifier (e.g. ``ord ?x`` is a valid +expression). Use of this construct also introduces a new dynamic-binding +constraint in the type of the expression. For example, the following +definition shows how we can define an implicitly parameterised sort +function in terms of an explicitly parameterised ``sortBy`` function: + +:: + + sortBy :: (a -> a -> Bool) -> [a] -> [a] + + sort :: (?cmp :: a -> a -> Bool) => [a] -> [a] + sort = sortBy ?cmp + +Implicit-parameter type constraints +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Dynamic binding constraints behave just like other type class +constraints in that they are automatically propagated. Thus, when a +function is used, its implicit parameters are inherited by the function +that called it. For example, our ``sort`` function might be used to pick +out the least value in a list: + +:: + + least :: (?cmp :: a -> a -> Bool) => [a] -> a + least xs = head (sort xs) + +Without lifting a finger, the ``?cmp`` parameter is propagated to become +a parameter of ``least`` as well. With explicit parameters, the default +is that parameters must always be explicit propagated. With implicit +parameters, the default is to always propagate them. + +An implicit-parameter type constraint differs from other type class +constraints in the following way: All uses of a particular implicit +parameter must have the same type. This means that the type of +``(?x, ?x)`` is ``(?x::a) => (a,a)``, and not +``(?x::a, ?x::b) => (a, b)``, as would be the case for type class +constraints. + +You can't have an implicit parameter in the context of a class or +instance declaration. For example, both these declarations are illegal: + +:: + + class (?x::Int) => C a where ... + instance (?x::a) => Foo [a] where ... + +Reason: exactly which implicit parameter you pick up depends on exactly +where you invoke a function. But the "invocation" of instance +declarations is done behind the scenes by the compiler, so it's hard to +figure out exactly where it is done. Easiest thing is to outlaw the +offending types. + +Implicit-parameter constraints do not cause ambiguity. For example, +consider: + +:: + + f :: (?x :: [a]) => Int -> Int + f n = n + length ?x + + g :: (Read a, Show a) => String -> String + g s = show (read s) + +Here, ``g`` has an ambiguous type, and is rejected, but ``f`` is fine. +The binding for ``?x`` at ``f``\ 's call site is quite unambiguous, and +fixes the type ``a``. + +Implicit-parameter bindings +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An implicit parameter is *bound* using the standard ``let`` or ``where`` +binding forms. For example, we define the ``min`` function by binding +``cmp``. + +:: + + min :: [a] -> a + min = let ?cmp = (<=) in least + +A group of implicit-parameter bindings may occur anywhere a normal group +of Haskell bindings can occur, except at top level. That is, they can +occur in a ``let`` (including in a list comprehension, or do-notation, +or pattern guards), or a ``where`` clause. Note the following points: + +- An implicit-parameter binding group must be a collection of simple + bindings to implicit-style variables (no function-style bindings, and + no type signatures); these bindings are neither polymorphic or + recursive. + +- You may not mix implicit-parameter bindings with ordinary bindings in + a single ``let`` expression; use two nested ``let``\ s instead. (In + the case of ``where`` you are stuck, since you can't nest ``where`` + clauses.) + +- You may put multiple implicit-parameter bindings in a single binding + group; but they are *not* treated as a mutually recursive group (as + ordinary ``let`` bindings are). Instead they are treated as a + non-recursive group, simultaneously binding all the implicit + parameter. The bindings are not nested, and may be re-ordered without + changing the meaning of the program. For example, consider: + + :: + + f t = let { ?x = t; ?y = ?x+(1::Int) } in ?x + ?y + + The use of ``?x`` in the binding for ``?y`` does not "see" the + binding for ``?x``, so the type of ``f`` is + + :: + + f :: (?x::Int) => Int -> Int + +Implicit parameters and polymorphic recursion +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Consider these two definitions: + +:: + + len1 :: [a] -> Int + len1 xs = let ?acc = 0 in len_acc1 xs + + len_acc1 [] = ?acc + len_acc1 (x:xs) = let ?acc = ?acc + (1::Int) in len_acc1 xs + + ------------ + + len2 :: [a] -> Int + len2 xs = let ?acc = 0 in len_acc2 xs + + len_acc2 :: (?acc :: Int) => [a] -> Int + len_acc2 [] = ?acc + len_acc2 (x:xs) = let ?acc = ?acc + (1::Int) in len_acc2 xs + +The only difference between the two groups is that in the second group +``len_acc`` is given a type signature. In the former case, ``len_acc1`` +is monomorphic in its own right-hand side, so the implicit parameter +``?acc`` is not passed to the recursive call. In the latter case, +because ``len_acc2`` has a type signature, the recursive call is made to +the *polymorphic* version, which takes ``?acc`` as an implicit +parameter. So we get the following results in GHCi: + +:: + + Prog> len1 "hello" + 0 + Prog> len2 "hello" + 5 + +Adding a type signature dramatically changes the result! This is a +rather counter-intuitive phenomenon, worth watching out for. + +Implicit parameters and monomorphism +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +GHC applies the dreaded Monomorphism Restriction (section 4.5.5 of the +Haskell Report) to implicit parameters. For example, consider: + +:: + + f :: Int -> Int + f v = let ?x = 0 in + let y = ?x + v in + let ?x = 5 in + y + +Since the binding for ``y`` falls under the Monomorphism Restriction it +is not generalised, so the type of ``y`` is simply ``Int``, not +``(?x::Int) => Int``. Hence, ``(f 9)`` returns result ``9``. If you add +a type signature for ``y``, then ``y`` will get type +``(?x::Int) => Int``, so the occurrence of ``y`` in the body of the +``let`` will see the inner binding of ``?x``, so ``(f 9)`` will return +``14``. + +.. _implicit-parameters-special: + +Special implicit parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +GHC treats implicit parameters of type ``GHC.Types.CallStack`` +specially, by resolving them to the current location in the program. +Consider: + +:: + + f :: String + f = show (?loc :: CallStack) + +GHC will automatically resolve ``?loc`` to its source location. If +another implicit parameter with type ``CallStack`` is in scope, GHC will +append the two locations, creating an explicit call-stack. For example: + +:: + + f :: (?stk :: CallStack) => String + f = show (?stk :: CallStack) + +will produce the location of ``?stk``, followed by ``f``\'s call-site. +Note that the name of the implicit parameter does not matter (we used +``?loc`` above), GHC will solve any implicit parameter with the right +type. The name does, however, matter when pushing new locations onto +existing stacks. Consider: + +:: + + f :: (?stk :: CallStack) => String + f = show (?loc :: CallStack) + +When we call ``f``, the stack will include the use of ``?loc``, but not +the call to ``f``; in this case the names must match. + +``CallStack`` is kept abstract, but GHC provides a function + +:: + + getCallStack :: CallStack -> [(String, SrcLoc)] + +to access the individual call-sites in the stack. The ``String`` is the +name of the function that was called, and the ``SrcLoc`` provides the +package, module, and file name, as well as the line and column numbers. +The stack will never be empty, as the first call-site will be the +location at which the implicit parameter was used. GHC will also never +infer ``?loc :: CallStack`` as a type constraint, which means that +functions must explicitly ask to be told about their call-sites. + +A potential "gotcha" when using implicit ``CallStack``\ s is that the +``:type`` command in GHCi will not report the ``?loc :: CallStack`` +constraint, as the typechecker will immediately solve it. Use ``:info`` +instead to print the unsolved type. + +.. _kinding: + +Explicitly-kinded quantification +-------------------------------- + +Haskell infers the kind of each type variable. Sometimes it is nice to +be able to give the kind explicitly as (machine-checked) documentation, +just as it is nice to give a type signature for a function. On some +occasions, it is essential to do so. For example, in his paper +"Restricted Data Types in Haskell" (Haskell Workshop 1999) John Hughes +had to define the data type: + +:: + + data Set cxt a = Set [a] + | Unused (cxt a -> ()) + +The only use for the ``Unused`` constructor was to force the correct +kind for the type variable ``cxt``. + +GHC now instead allows you to specify the kind of a type variable +directly, wherever a type variable is explicitly bound, with the flag +``-XKindSignatures``. + +This flag enables kind signatures in the following places: + +- ``data`` declarations: + + :: + + data Set (cxt :: * -> *) a = Set [a] + +- ``type`` declarations: + + :: + + type T (f :: * -> *) = f Int + +- ``class`` declarations: + + :: + + class (Eq a) => C (f :: * -> *) a where ... + +- ``forall``\'s in type signatures: + + :: + + f :: forall (cxt :: * -> *). Set cxt Int + +The parentheses are required. Some of the spaces are required too, to +separate the lexemes. If you write "``(f::*->*)``" you will get a parse +error, because "``::*->*``" is a single lexeme in Haskell. + +As part of the same extension, you can put kind annotations in types as +well. Thus: + +:: + + f :: (Int :: *) -> Int + g :: forall a. a -> (a :: *) + +The syntax is + +:: + + atype ::= '(' ctype '::' kind ') + +The parentheses are required. + +.. _universal-quantification: + +Arbitrary-rank polymorphism +--------------------------- + +GHC's type system supports *arbitrary-rank* explicit universal +quantification in types. For example, all the following types are legal: + +:: + + f1 :: forall a b. a -> b -> a + g1 :: forall a b. (Ord a, Eq b) => a -> b -> a + + f2 :: (forall a. a->a) -> Int -> Int + g2 :: (forall a. Eq a => [a] -> a -> Bool) -> Int -> Int + + f3 :: ((forall a. a->a) -> Int) -> Bool -> Bool + + f4 :: Int -> (forall a. a -> a) + +Here, ``f1`` and ``g1`` are rank-1 types, and can be written in standard +Haskell (e.g. ``f1 :: a->b->a``). The ``forall`` makes explicit the +universal quantification that is implicitly added by Haskell. + +The functions ``f2`` and ``g2`` have rank-2 types; the ``forall`` is on +the left of a function arrow. As ``g2`` shows, the polymorphic type on +the left of the function arrow can be overloaded. + +The function ``f3`` has a rank-3 type; it has rank-2 types on the left +of a function arrow. + +The language option ``-XRankNTypes`` (which implies +``-XExplicitForAll``, :ref:`explicit-foralls`) enables higher-rank +types. That is, you can nest ``forall``\ s arbitrarily deep in function +arrows. For example, a forall-type (also called a "type scheme"), +including a type-class context, is legal: + +- On the left or right (see ``f4``, for example) of a function arrow + +- As the argument of a constructor, or type of a field, in a data type + declaration. For example, any of the ``f1, f2, f3, g1, g2`` above would + be valid field type signatures. + +- As the type of an implicit parameter + +- In a pattern type signature (see :ref:`scoped-type-variables`) + +The ``-XRankNTypes`` option is also required for any type with a +``forall`` or context to the right of an arrow (e.g. +``f :: Int -> forall a. a->a``, or ``g :: Int -> Ord a => a -> a``). +Such types are technically rank 1, but are clearly not Haskell-98, and +an extra flag did not seem worth the bother. + +In particular, in ``data`` and ``newtype`` declarations the constructor +arguments may be polymorphic types of any rank; see examples in +:ref:`univ`. Note that the declared types are nevertheless always +monomorphic. This is important because by default GHC will not +instantiate type variables to a polymorphic type +(:ref:`impredicative-polymorphism`). + +The obsolete language options ``-XPolymorphicComponents`` and +``-XRank2Types`` are synonyms for ``-XRankNTypes``. They used to specify +finer distinctions that GHC no longer makes. (They should really elicit +a deprecation warning, but they don't, purely to avoid the need to +library authors to change their old flags specifications.) + +.. _univ: + +Examples +~~~~~~~~ + +These are examples of ``data`` and ``newtype`` declarations whose data +constructors have polymorphic argument types: + +:: + + data T a = T1 (forall b. b -> b -> b) a + + data MonadT m = MkMonad { return :: forall a. a -> m a, + bind :: forall a b. m a -> (a -> m b) -> m b + } + + newtype Swizzle = MkSwizzle (forall a. Ord a => [a] -> [a]) + +The constructors have rank-2 types: + +:: + + T1 :: forall a. (forall b. b -> b -> b) -> a -> T a + MkMonad :: forall m. (forall a. a -> m a) + -> (forall a b. m a -> (a -> m b) -> m b) + -> MonadT m + MkSwizzle :: (forall a. Ord a => [a] -> [a]) -> Swizzle + +In earlier versions of GHC, it was possible to omit the ``forall`` in +the type of the constructor if there was an explicit context. For +example: + +:: + + newtype Swizzle' = MkSwizzle' (Ord a => [a] -> [a]) + +As of GHC 7.10, this is deprecated. The +``-fwarn-context-quantification`` flag detects this situation and issues +a warning. In GHC 7.12, declarations such as ``MkSwizzle'`` will cause +an out-of-scope error. + +As for type signatures, implicit quantification happens for +non-overloaded types too. So if you write this: + +:: + + f :: (a -> a) -> a + +it's just as if you had written this: + +:: + + f :: forall a. (a -> a) -> a + +That is, since the type variable ``a`` isn't in scope, it's implicitly +universally quantified. + +You construct values of types ``T1, MonadT, Swizzle`` by applying the +constructor to suitable values, just as usual. For example, + +:: + + a1 :: T Int + a1 = T1 (\xy->x) 3 + + a2, a3 :: Swizzle + a2 = MkSwizzle sort + a3 = MkSwizzle reverse + + a4 :: MonadT Maybe + a4 = let r x = Just x + b m k = case m of + Just y -> k y + Nothing -> Nothing + in + MkMonad r b + + mkTs :: (forall b. b -> b -> b) -> a -> [T a] + mkTs f x y = [T1 f x, T1 f y] + +The type of the argument can, as usual, be more general than the type +required, as ``(MkSwizzle reverse)`` shows. (``reverse`` does not need +the ``Ord`` constraint.) + +When you use pattern matching, the bound variables may now have +polymorphic types. For example: + +:: + + f :: T a -> a -> (a, Char) + f (T1 w k) x = (w k x, w 'c' 'd') + + g :: (Ord a, Ord b) => Swizzle -> [a] -> (a -> b) -> [b] + g (MkSwizzle s) xs f = s (map f (s xs)) + + h :: MonadT m -> [m a] -> m [a] + h m [] = return m [] + h m (x:xs) = bind m x $ \y -> + bind m (h m xs) $ \ys -> + return m (y:ys) + +In the function ``h`` we use the record selectors ``return`` and +``bind`` to extract the polymorphic bind and return functions from the +``MonadT`` data structure, rather than using pattern matching. + +Type inference +~~~~~~~~~~~~~~ + +In general, type inference for arbitrary-rank types is undecidable. GHC +uses an algorithm proposed by Odersky and Laufer ("Putting type +annotations to work", POPL'96) to get a decidable algorithm by requiring +some help from the programmer. We do not yet have a formal specification +of "some help" but the rule is this: + +*For a lambda-bound or case-bound variable, x, either the programmer +provides an explicit polymorphic type for x, or GHC's type inference +will assume that x's type has no foralls in it*. + +What does it mean to "provide" an explicit type for x? You can do that +by giving a type signature for x directly, using a pattern type +signature (:ref:`scoped-type-variables`), thus: + +:: + + \ f :: (forall a. a->a) -> (f True, f 'c') + +Alternatively, you can give a type signature to the enclosing context, +which GHC can "push down" to find the type for the variable: + +:: + + (\ f -> (f True, f 'c')) :: (forall a. a->a) -> (Bool,Char) + +Here the type signature on the expression can be pushed inwards to give +a type signature for f. Similarly, and more commonly, one can give a +type signature for the function itself: + +:: + + h :: (forall a. a->a) -> (Bool,Char) + h f = (f True, f 'c') + +You don't need to give a type signature if the lambda bound variable is +a constructor argument. Here is an example we saw earlier: + +:: + + f :: T a -> a -> (a, Char) + f (T1 w k) x = (w k x, w 'c' 'd') + +Here we do not need to give a type signature to ``w``, because it is an +argument of constructor ``T1`` and that tells GHC all it needs to know. + +.. _implicit-quant: + +Implicit quantification +~~~~~~~~~~~~~~~~~~~~~~~ + +GHC performs implicit quantification as follows. At the top level +(only) of user-written types, if and only if there is no explicit +``forall``, GHC finds all the type variables mentioned in the type that +are not already in scope, and universally quantifies them. For example, +the following pairs are equivalent: + +:: + + f :: a -> a + f :: forall a. a -> a + + g (x::a) = let + h :: a -> b -> b + h x y = y + in ... + g (x::a) = let + h :: forall b. a -> b -> b + h x y = y + in ... + +Notice that GHC does *not* find the inner-most possible quantification +point. For example: + +:: + + f :: (a -> a) -> Int + -- MEANS + f :: forall a. (a -> a) -> Int + -- NOT + f :: (forall a. a -> a) -> Int + + + g :: (Ord a => a -> a) -> Int + -- MEANS the illegal type + g :: forall a. (Ord a => a -> a) -> Int + -- NOT + g :: (forall a. Ord a => a -> a) -> Int + +The latter produces an illegal type, which you might think is silly, but +at least the rule is simple. If you want the latter type, you can write +your ``forall``\s explicitly. Indeed, doing so is strongly advised for +rank-2 types. + +.. _impredicative-polymorphism: + +Impredicative polymorphism +-------------------------- + +In general, GHC will only instantiate a polymorphic function at a +monomorphic type (one with no foralls). For example, + +:: + + runST :: (forall s. ST s a) -> a + id :: forall b. b -> b + + foo = id runST -- Rejected + +The definition of ``foo`` is rejected because one would have to +instantiate ``id``\'s type with ``b := (forall s. ST s a) -> a``, and +that is not allowed. Instanting polymorpic type variables with +polymorphic types is called *impredicative polymorphism*. + +GHC has extremely flaky support for *impredicative polymorphism*, +enabled with ``-XImpredicativeTypes``. If it worked, this would mean +that you *could* call a polymorphic function at a polymorphic type, and +parameterise data structures over polymorphic types. For example: + +:: + + f :: Maybe (forall a. [a] -> [a]) -> Maybe ([Int], [Char]) + f (Just g) = Just (g [3], g "hello") + f Nothing = Nothing + +Notice here that the ``Maybe`` type is parameterised by the +*polymorphic* type ``(forall a. [a] -> [a])``. However *the extension +should be considered highly experimental, and certainly un-supported*. +You are welcome to try it, but please don't rely on it working +consistently, or working the same in subsequent releases. See +:ghc-wiki:`this wiki page <ImpredicativePolymorphism>` for more details. + +If you want impredicative polymorphism, the main workaround is to use a +newtype wrapper. The ``id runST`` example can be written using theis +workaround like this: + +:: + + runST :: (forall s. ST s a) -> a + id :: forall b. b -> b + + nwetype Wrap a = Wrap { unWrap :: (forall s. ST s a) -> a } + + foo :: (forall s. ST s a) -> a + foo = unWrap (id (Wrap runST)) + -- Here id is called at monomorphic type (Wrap a) + +.. _scoped-type-variables: + +Lexically scoped type variables +------------------------------- + +GHC supports *lexically scoped type variables*, without which some type +signatures are simply impossible to write. For example: + +:: + + f :: forall a. [a] -> [a] + f xs = ys ++ ys + where + ys :: [a] + ys = reverse xs + +The type signature for ``f`` brings the type variable ``a`` into scope, +because of the explicit ``forall`` (:ref:`decl-type-sigs`). The type +variables bound by a ``forall`` scope over the entire definition of the +accompanying value declaration. In this example, the type variable ``a`` +scopes over the whole definition of ``f``, including over the type +signature for ``ys``. In Haskell 98 it is not possible to declare a type +for ``ys``; a major benefit of scoped type variables is that it becomes +possible to do so. + +Lexically-scoped type variables are enabled by +``-XScopedTypeVariables``. This flag implies ``-XRelaxedPolyRec``. + +Overview +~~~~~~~~ + +The design follows the following principles + +- A scoped type variable stands for a type *variable*, and not for a + *type*. (This is a change from GHC's earlier design.) + +- Furthermore, distinct lexical type variables stand for distinct type + variables. This means that every programmer-written type signature + (including one that contains free scoped type variables) denotes a + *rigid* type; that is, the type is fully known to the type checker, + and no inference is involved. + +- Lexical type variables may be alpha-renamed freely, without changing + the program. + +A *lexically scoped type variable* can be bound by: + +- A declaration type signature (:ref:`decl-type-sigs`) + +- An expression type signature (:ref:`exp-type-sigs`) + +- A pattern type signature (:ref:`pattern-type-sigs`) + +- Class and instance declarations (:ref:`cls-inst-scoped-tyvars`) + +In Haskell, a programmer-written type signature is implicitly quantified +over its free type variables (`Section +4.1.2 <http://www.haskell.org/onlinereport/decls.html#sect4.1.2>`__ of +the Haskell Report). Lexically scoped type variables affect this +implicit quantification rules as follows: any type variable that is in +scope is *not* universally quantified. For example, if type variable +``a`` is in scope, then + +:: + + (e :: a -> a) means (e :: a -> a) + (e :: b -> b) means (e :: forall b. b->b) + (e :: a -> b) means (e :: forall b. a->b) + +.. _decl-type-sigs: + +Declaration type signatures +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A declaration type signature that has *explicit* quantification (using +``forall``) brings into scope the explicitly-quantified type variables, +in the definition of the named function. For example: + +:: + + f :: forall a. [a] -> [a] + f (x:xs) = xs ++ [ x :: a ] + +The "``forall a``" brings "``a``" into scope in the definition of +"``f``". + +This only happens if: + +- The quantification in ``f``\'s type signature is explicit. For + example: + + :: + + g :: [a] -> [a] + g (x:xs) = xs ++ [ x :: a ] + + This program will be rejected, because "``a``" does not scope over + the definition of "``g``", so "``x::a``" means "``x::forall a. a``" + by Haskell's usual implicit quantification rules. + +- The signature gives a type for a function binding or a bare variable + binding, not a pattern binding. For example: + + :: + + f1 :: forall a. [a] -> [a] + f1 (x:xs) = xs ++ [ x :: a ] -- OK + + f2 :: forall a. [a] -> [a] + f2 = \(x:xs) -> xs ++ [ x :: a ] -- OK + + f3 :: forall a. [a] -> [a] + Just f3 = Just (\(x:xs) -> xs ++ [ x :: a ]) -- Not OK! + + The binding for ``f3`` is a pattern binding, and so its type + signature does not bring ``a`` into scope. However ``f1`` is a + function binding, and ``f2`` binds a bare variable; in both cases the + type signature brings ``a`` into scope. + +.. _exp-type-sigs: + +Expression type signatures +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An expression type signature that has *explicit* quantification (using +``forall``) brings into scope the explicitly-quantified type variables, +in the annotated expression. For example: + +:: + + f = runST ( (op >>= \(x :: STRef s Int) -> g x) :: forall s. ST s Bool ) + +Here, the type signature ``forall s. ST s Bool`` brings the type +variable ``s`` into scope, in the annotated expression +``(op >>= \(x :: STRef s Int) -> g x)``. + +.. _pattern-type-sigs: + +Pattern type signatures +~~~~~~~~~~~~~~~~~~~~~~~ + +A type signature may occur in any pattern; this is a *pattern type +signature*. For example: + +:: + + -- f and g assume that 'a' is already in scope + f = \(x::Int, y::a) -> x + g (x::a) = x + h ((x,y) :: (Int,Bool)) = (y,x) + +In the case where all the type variables in the pattern type signature +are already in scope (i.e. bound by the enclosing context), matters are +simple: the signature simply constrains the type of the pattern in the +obvious way. + +Unlike expression and declaration type signatures, pattern type +signatures are not implicitly generalised. The pattern in a *pattern +binding* may only mention type variables that are already in scope. For +example: + +:: + + f :: forall a. [a] -> (Int, [a]) + f xs = (n, zs) + where + (ys::[a], n) = (reverse xs, length xs) -- OK + zs::[a] = xs ++ ys -- OK + + Just (v::b) = ... -- Not OK; b is not in scope + +Here, the pattern signatures for ``ys`` and ``zs`` are fine, but the one +for ``v`` is not because ``b`` is not in scope. + +However, in all patterns *other* than pattern bindings, a pattern type +signature may mention a type variable that is not in scope; in this +case, *the signature brings that type variable into scope*. This is +particularly important for existential data constructors. For example: + +:: + + data T = forall a. MkT [a] + + k :: T -> T + k (MkT [t::a]) = MkT t3 + where + t3::[a] = [t,t,t] + +Here, the pattern type signature ``(t::a)`` mentions a lexical type +variable that is not already in scope. Indeed, it *cannot* already be in +scope, because it is bound by the pattern match. GHC's rule is that in +this situation (and only then), a pattern type signature can mention a +type variable that is not already in scope; the effect is to bring it +into scope, standing for the existentially-bound type variable. + +When a pattern type signature binds a type variable in this way, GHC +insists that the type variable is bound to a *rigid*, or fully-known, +type variable. This means that any user-written type signature always +stands for a completely known type. + +If all this seems a little odd, we think so too. But we must have *some* +way to bring such type variables into scope, else we could not name +existentially-bound type variables in subsequent type signatures. + +This is (now) the *only* situation in which a pattern type signature is +allowed to mention a lexical variable that is not already in scope. For +example, both ``f`` and ``g`` would be illegal if ``a`` was not already +in scope. + +.. _cls-inst-scoped-tyvars: + +Class and instance declarations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The type variables in the head of a ``class`` or ``instance`` +declaration scope over the methods defined in the ``where`` part. You do +not even need an explicit ``forall``. For example: + +:: + + class C a where + op :: [a] -> a + + op xs = let ys::[a] + ys = reverse xs + in + head ys + + instance C b => C [b] where + op xs = reverse (head (xs :: [[b]])) + +Bindings and generalisation +--------------------------- + +.. _monomorphism: + +Switching off the dreaded Monomorphism Restriction +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: -XNoMonomorphismRestriction + +Haskell's monomorphism restriction (see `Section +4.5.5 <http://www.haskell.org/onlinereport/decls.html#sect4.5.5>`__ of +the Haskell Report) can be completely switched off by +``-XNoMonomorphismRestriction``. Since GHC 7.8.1, the monomorphism +restriction is switched off by default in GHCi's interactive options +(see :ref:`ghci-interactive-options`). + +.. _typing-binds: + +Generalised typing of mutually recursive bindings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Haskell Report specifies that a group of bindings (at top level, or +in a ``let`` or ``where``) should be sorted into strongly-connected +components, and then type-checked in dependency order +(`Haskell Report, Section +4.5.1 <http://www.haskell.org/onlinereport/decls.html#sect4.5.1>`__). As +each group is type-checked, any binders of the group that have an +explicit type signature are put in the type environment with the +specified polymorphic type, and all others are monomorphic until the +group is generalised (`Haskell Report, Section +4.5.2 <http://www.haskell.org/onlinereport/decls.html#sect4.5.2>`__). + +Following a suggestion of Mark Jones, in his paper `Typing Haskell in +Haskell <http://citeseer.ist.psu.edu/424440.html>`__, GHC implements a +more general scheme. If ``-XRelaxedPolyRec`` is specified: *the +dependency analysis ignores references to variables that have an +explicit type signature*. As a result of this refined dependency +analysis, the dependency groups are smaller, and more bindings will +typecheck. For example, consider: + +:: + + f :: Eq a => a -> Bool + f x = (x == x) || g True || g "Yes" + + g y = (y <= y) || f True + +This is rejected by Haskell 98, but under Jones's scheme the definition +for ``g`` is typechecked first, separately from that for ``f``, because +the reference to ``f`` in ``g``\'s right hand side is ignored by the +dependency analysis. Then ``g``\'s type is generalised, to get + +:: + + g :: Ord a => a -> Bool + +Now, the definition for ``f`` is typechecked, with this type for ``g`` +in the type environment. + +The same refined dependency analysis also allows the type signatures of +mutually-recursive functions to have different contexts, something that +is illegal in Haskell 98 (Section 4.5.2, last sentence). With +``-XRelaxedPolyRec`` GHC only insists that the type signatures of a +*refined* group have identical type signatures; in practice this means +that only variables bound by the same pattern binding must have the same +context. For example, this is fine: + +:: + + f :: Eq a => a -> Bool + f x = (x == x) || g True + + g :: Ord a => a -> Bool + g y = (y <= y) || f True + +.. _mono-local-binds: + +Let-generalisation +~~~~~~~~~~~~~~~~~~ + +An ML-style language usually generalises the type of any ``let``\-bound or +``where``\-bound variable, so that it is as polymorphic as possible. With the +flag ``-XMonoLocalBinds`` GHC implements a slightly more conservative +policy, using the following rules: + +- A variable is *closed* if and only if + + - the variable is let-bound + + - one of the following holds: + + - the variable has an explicit type signature that has no free + type variables, or + + - its binding group is fully generalised (see next bullet) + +- A binding group is *fully generalised* if and only if + + - each of its free variables is either imported or closed, and + + - the binding is not affected by the monomorphism restriction + (`Haskell Report, Section + 4.5.5 <http://www.haskell.org/onlinereport/decls.html#sect4.5.5>`__) + +For example, consider + +:: + + f x = x + 1 + g x = let h y = f y * 2 + k z = z+x + in h x + k x + +Here ``f`` is generalised because it has no free variables; and its +binding group is unaffected by the monomorphism restriction; and hence +``f`` is closed. The same reasoning applies to ``g``, except that it has +one closed free variable, namely ``f``. Similarly ``h`` is closed, *even +though it is not bound at top level*, because its only free variable +``f`` is closed. But ``k`` is not closed, because it mentions ``x`` +which is not closed (because it is not let-bound). + +Notice that a top-level binding that is affected by the monomorphism +restriction is not closed, and hence may in turn prevent generalisation +of bindings that mention it. + +The rationale for this more conservative strategy is given in `the +papers <http://research.microsoft.com/~simonpj/papers/constraints/index.htm>`__ +"Let should not be generalised" and "Modular type inference with local +assumptions", and a related `blog post <http://ghc.haskell.org/trac/ghc/blog/LetGeneralisationInGhc7>`__. + +The flag ``-XMonoLocalBinds`` is implied by ``-XTypeFamilies`` and +``-XGADTs``. You can switch it off again with ``-XNoMonoLocalBinds`` but +type inference becomes less predicatable if you do so. (Read the +papers!) + +.. _typed-holes: + +Typed Holes +=========== + +Typed holes are a feature of GHC that allows special placeholders +written with a leading underscore (e.g., "``_``", "``_foo``", +"``_bar``"), to be used as expressions. During compilation these holes +will generate an error message that describes which type is expected at +the hole's location, information about the origin of any free type +variables, and a list of local bindings that might help fill the hole +with actual code. Typed holes are always enabled in GHC. + +The goal of typed holes is to help with writing Haskell code rather than +to change the type system. Typed holes can be used to obtain extra +information from the type checker, which might otherwise be hard to get. +Normally, using GHCi, users can inspect the (inferred) type signatures +of all top-level bindings. However, this method is less convenient with +terms that are not defined on top-level or inside complex expressions. +Holes allow the user to check the type of the term they are about to +write. + +For example, compiling the following module with GHC: + +:: + + f :: a -> a + f x = _ + +will fail with the following error: + +:: + + hole.hs:2:7: + Found hole `_' with type: a + Where: `a' is a rigid type variable bound by + the type signature for f :: a -> a at hole.hs:1:6 + Relevant bindings include + f :: a -> a (bound at hole.hs:2:1) + x :: a (bound at hole.hs:2:3) + In the expression: _ + In an equation for `f': f x = _ + +Here are some more details: + +- A "``Found hole``" error usually terminates compilation, like any + other type error. After all, you have omitted some code from your + program. Nevertheless, you can run and test a piece of code + containing holes, by using the ``-fdefer-typed-holes`` flag. This + flag defers errors produced by typed holes until runtime, and + converts them into compile-time warnings. These warnings can in turn + be suppressed entirely by ``-fnowarn-typed-holes``). + + The result is that a hole will behave like ``undefined``, but with + the added benefits that it shows a warning at compile time, and will + show the same message if it gets evaluated at runtime. This behaviour + follows that of the ``-fdefer-type-errors`` option, which implies + ``-fdefer-typed-holes``. See :ref:`defer-type-errors`. + +- All unbound identifiers are treated as typed holes, *whether or not + they start with an underscore*. The only difference is in the error + message: + + :: + + cons z = z : True : _x : y + + yields the errors + + :: + + Foo.hs:5:15: error: + Found hole: _x :: Bool + Relevant bindings include + p :: Bool (bound at Foo.hs:3:6) + cons :: Bool -> [Bool] (bound at Foo.hs:3:1) + + Foo.hs:5:20: error: + Variable not in scope: y :: [Bool] + + More information is given for explicit holes (i.e. ones that start + with an underscore), than for out-of-scope variables, because the + latter are often unintended typos, so the extra information is + distracting. If you the detailed information, use a leading + underscore to make explicit your intent to use a hole. + +- Unbound identifiers with the same name are never unified, even within + the same function, but shown individually. For example: + + :: + + cons = _x : _x + + results in the following errors: + + :: + + unbound.hs:1:8: + Found hole '_x' with type: a + Where: `a' is a rigid type variable bound by + the inferred type of cons :: [a] at unbound.hs:1:1 + Relevant bindings include cons :: [a] (bound at unbound.hs:1:1) + In the first argument of `(:)', namely `_x' + In the expression: _x : _x + In an equation for `cons': cons = _x : _x + + unbound.hs:1:13: + Found hole '_x' with type: [a] + Arising from: an undeclared identifier `_x' at unbound.hs:1:13-14 + Where: `a' is a rigid type variable bound by + the inferred type of cons :: [a] at unbound.hs:1:1 + Relevant bindings include cons :: [a] (bound at unbound.hs:1:1) + In the second argument of `(:)', namely `_x' + In the expression: _x : _x + In an equation for `cons': cons = _x : _x + + Notice the two different types reported for the two different + occurrences of ``_x``. + +- No language extension is required to use typed holes. The lexeme + "``_``" was previously illegal in Haskell, but now has a more + informative error message. The lexeme "``_x``" is a perfectly legal + variable, and its behaviour is unchanged when it is in scope. For + example + + :: + + f _x = _x + 1 + + does not elict any errors. Only a variable *that is not in scope* + (whether or not it starts with an underscore) is treated as an error + (which it always was), albeit now with a more informative error + message. + +- Unbound data constructors used in expressions behave exactly as + above. However, unbound data constructors used in *patterns* cannot + be deferred, and instead bring compilation to a halt. (In + implementation terms, they are reported by the renamer rather than + the type checker.) + +.. _partial-type-signatures: + +Partial Type Signatures +======================= + +A partial type signature is a type signature containing special +placeholders written with a leading underscore (e.g., "``_``", +"``_foo``", "``_bar``") called *wildcards*. Partial type signatures are +to type signatures what :ref:`typed-holes` are to expressions. During +compilation these wildcards or holes will generate an error message that +describes which type was inferred at the hole's location, and +information about the origin of any free type variables. GHC reports +such error messages by default. + +Unlike :ref:`typed-holes`, which make the program incomplete and will +generate errors when they are evaluated, this needn't be the case for +holes in type signatures. The type checker is capable (in most cases) of +type-checking a binding with or without a type signature. A partial type +signature bridges the gap between the two extremes, the programmer can +choose which parts of a type to annotate and which to leave over to the +type-checker to infer. + +By default, the type-checker will report an error message for each hole +in a partial type signature, informing the programmer of the inferred +type. When the ``-XPartialTypeSignatures`` flag is enabled, the +type-checker will accept the inferred type for each hole, generating +warnings instead of errors. Additionally, these warnings can be silenced +with the ``-fno-warn-partial-type-signatures`` flag. + +.. _pts-syntax: + +Syntax +------ + +A (partial) type signature has the following form: +``forall a b .. . (C1, C2, ..) => tau``. It consists of three parts: + +- The type variables: + ``a b ..`` +- The constraints: + ``(C1, C2, ..)`` +- The (mono)type: + ``tau`` + +We distinguish three kinds of wildcards. + +.. _type-wildcards: + +Type Wildcards +~~~~~~~~~~~~~~ + +Wildcards occurring within the monotype (tau) part of the type signature +are *type wildcards* ("type" is often omitted as this is the default +kind of wildcard). Type wildcards can be instantiated to any monotype +like ``Bool`` or ``Maybe [Bool]``, including functions and higher-kinded +types like ``(Int -> Bool)`` or ``Maybe``. + +:: + + not' :: Bool -> _ + not' x = not x + -- Inferred: Bool -> Bool + + maybools :: _ + maybools = Just [True] + -- Inferred: Maybe [Bool] + + just1 :: _ Int + just1 = Just 1 + -- Inferred: Maybe Int + + filterInt :: _ -> _ -> [Int] + filterInt = filter -- has type forall a. (a -> Bool) -> [a] -> [a] + -- Inferred: (Int -> Bool) -> [Int] -> [Int] + +For instance, the first wildcard in the type signature ``not'`` would +produce the following error message: + +:: + + Test.hs:4:17: + Found hole ‘_’ with type: Bool + To use the inferred type, enable PartialTypeSignatures + In the type signature for ‘not'’: Bool -> _ + +When a wildcard is not instantiated to a monotype, it will be +generalised over, i.e. replaced by a fresh type variable (of which the +name will often start with ``w_``), e.g. + +:: + + foo :: _ -> _ + foo x = x + -- Inferred: forall w_. w_ -> w_ + + filter' :: _ + filter' = filter -- has type forall a. (a -> Bool) -> [a] -> [a] + -- Inferred: (a -> Bool) -> [a] -> [a] + +.. _named-wildcards: + +Named Wildcards +~~~~~~~~~~~~~~~ + +Type wildcards can also be named by giving the underscore an identifier +as suffix, i.e. ``_a``. These are called *named wildcards*. All +occurrences of the same named wildcard within one type signature will +unify to the same type. For example: + +:: + + f :: _x -> _x + f ('c', y) = ('d', error "Urk") + -- Inferred: forall t. (Char, t) -> (Char, t) + +The named wildcard forces the argument and result types to be the same. +Lacking a signature, GHC would have inferred +``forall a b. (Char, a) -> (Char, b)``. A named wildcard can be +mentioned in constraints, provided it also occurs in the monotype part +of the type signature to make sure that it unifies with something: + +:: + + somethingShowable :: Show _x => _x -> _ + somethingShowable x = show x + -- Inferred type: Show w_x => w_x -> String + + somethingShowable' :: Show _x => _x -> _ + somethingShowable' x = show (not x) + -- Inferred type: Bool -> String + +Besides an extra-constraints wildcard (see +:ref:`extra-constraints-wildcard`), only named wildcards can occur in +the constraints, e.g. the ``_x`` in ``Show _x``. + +Named wildcards *should not be confused with type variables*. Even +though syntactically similar, named wildcards can unify with monotypes +as well as be generalised over (and behave as type variables). + +In the first example above, ``_x`` is generalised over (and is +effectively replaced by a fresh type variable ``w_x``). In the second +example, ``_x`` is unified with the ``Bool`` type, and as ``Bool`` +implements the ``Show`` type class, the constraint ``Show Bool`` can be +simplified away. + +By default, GHC (as the Haskell 2010 standard prescribes) parses +identifiers starting with an underscore in a type as type variables. To +treat them as named wildcards, the ``-XNamedWildCards`` flag should be +enabled. The example below demonstrated the effect. + +:: + + foo :: _a -> _a + foo _ = False + +Compiling this program without enabling ``-XNamedWildCards`` produces +the following error message complaining about the type variable ``_a`` +no matching the actual type ``Bool``. + +:: + + Test.hs:5:9: + Couldn't match expected type ‘_a’ with actual type ‘Bool’ + ‘_a’ is a rigid type variable bound by + the type signature for foo :: _a -> _a at Test.hs:4:8 + Relevant bindings include foo :: _a -> _a (bound at Test.hs:4:1) + In the expression: False + In an equation for ‘foo’: foo _ = False + +Compiling this program with ``-XNamedWildCards`` enabled produces the +following error message reporting the inferred type of the named +wildcard ``_a``. + +:: + + Test.hs:4:8: Warning: + Found hole ‘_a’ with type: Bool + In the type signature for ‘foo’: _a -> _a + +.. _extra-constraints-wildcard: + +Extra-Constraints Wildcard +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The third kind of wildcard is the *extra-constraints wildcard*. The +presence of an extra-constraints wildcard indicates that an arbitrary +number of extra constraints may be inferred during type checking and +will be added to the type signature. In the example below, the +extra-constraints wildcard is used to infer three extra constraints. + +:: + + arbitCs :: _ => a -> String + arbitCs x = show (succ x) ++ show (x == x) + -- Inferred: + -- forall a. (Enum a, Eq a, Show a) => a -> String + -- Error: + Test.hs:5:12: + Found hole ‘_’ with inferred constraints: (Enum a, Eq a, Show a) + To use the inferred type, enable PartialTypeSignatures + In the type signature for ‘arbitCs’: _ => a -> String + +An extra-constraints wildcard shouldn't prevent the programmer from +already listing the constraints he knows or wants to annotate, e.g. + +:: + + -- Also a correct partial type signature: + arbitCs' :: (Enum a, _) => a -> String + arbitCs' x = arbitCs x + -- Inferred: + -- forall a. (Enum a, Show a, Eq a) => a -> String + -- Error: + Test.hs:9:22: + Found hole ‘_’ with inferred constraints: (Eq a, Show a) + To use the inferred type, enable PartialTypeSignatures + In the type signature for ‘arbitCs'’: (Enum a, _) => a -> String + +An extra-constraints wildcard can also lead to zero extra constraints to +be inferred, e.g. + +:: + + noCs :: _ => String + noCs = "noCs" + -- Inferred: String + -- Error: + Test.hs:13:9: + Found hole ‘_’ with inferred constraints: () + To use the inferred type, enable PartialTypeSignatures + In the type signature for ‘noCs’: _ => String + +As a single extra-constraints wildcard is enough to infer any number of +constraints, only one is allowed in a type signature and it should come +last in the list of constraints. + +Extra-constraints wildcards cannot be named. + +.. _pts-where: + +Where can they occur? +--------------------- + +Partial type signatures are allowed for bindings, pattern and expression +signatures. In all other contexts, e.g. type class or type family +declarations, they are disallowed. In the following example a wildcard +is used in each of the three possible contexts. Extra-constraints +wildcards are not supported in pattern or expression signatures. + +:: + + {-# LANGUAGE ScopedTypeVariables #-} + foo :: _ + foo (x :: _) = (x :: _) + -- Inferred: forall w_. w_ -> w_ + +Anonymous wildcards *can* occur in type or data instance declarations. +However, these declarations are not partial type signatures and +different rules apply. See :ref:`data-instance-declarations` for more +details. + +Partial type signatures can also be used in :ref:`template-haskell` +splices. + +- Declaration splices: partial type signature are fully supported. + :: + + {-# LANGUAGE TemplateHaskell, NamedWildCards #-} + $( [d| foo :: _ => _a -> _a -> _ + foo x y = x == y|] ) + +- Expression splices: anonymous and named wildcards can be used in + expression signatures. Extra-constraints wildcards are not supported, + just like in regular expression signatures. + :: + + {-# LANGUAGE TemplateHaskell, NamedWildCards #-} + $( [e| foo = (Just True :: _m _) |] ) + +- Typed expression splices: the same wildcards as in (untyped) + expression splices are supported. + +- Pattern splices: Template Haskell doesn't support type signatures in + pattern splices. Consequently, partial type signatures are not + supported either. + +- Type splices: only anonymous wildcards are supported in type splices. + Named and extra-constraints wildcards are not. + :: + + {-# LANGUAGE TemplateHaskell #-} + foo :: $( [t| _ |] ) -> a + foo x = x + +.. _defer-type-errors: + +Deferring type errors to runtime +================================ + +While developing, sometimes it is desirable to allow compilation to +succeed even if there are type errors in the code. Consider the +following case: + +:: + + module Main where + + a :: Int + a = 'a' + + main = print "b" + +Even though ``a`` is ill-typed, it is not used in the end, so if all +that we're interested in is ``main`` it can be useful to be able to +ignore the problems in ``a``. + +For more motivation and details please refer to the +:ghc-wiki:`Wiki <DeferErrorsToRuntime>` page or the `original +paper <http://research.microsoft.com/en-us/um/people/simonpj/papers/ext-f/>`__. + +Enabling deferring of type errors +--------------------------------- + +The flag ``-fdefer-type-errors`` controls whether type errors are +deferred to runtime. Type errors will still be emitted as warnings, but +will not prevent compilation. You can use +``-fno-warn-deferred-type-errors`` to suppress these warnings. + +This flag implies the ``-fdefer-typed-holes`` flag, which enables this +behaviour for `typed holes <#typed-holes>`__. Should you so wish, it is +possible to enable ``-fdefer-type-errors`` without enabling +``-fdefer-typed-holes``, by explicitly specifying +``-fno-defer-typed-holes`` on the command-line after the +``-fdefer-type-errors`` flag. + +At runtime, whenever a term containing a type error would need to be +evaluated, the error is converted into a runtime exception of type +``TypeError``. Note that type errors are deferred as much as possible +during runtime, but invalid coercions are never performed, even when +they would ultimately result in a value of the correct type. For +example, given the following code: + +:: + + x :: Int + x = 0 + + y :: Char + y = x + + z :: Int + z = y + +evaluating ``z`` will result in a runtime ``TypeError``. + +Deferred type errors in GHCi +---------------------------- + +The flag ``-fdefer-type-errors`` works in GHCi as well, with one +exception: for "naked" expressions typed at the prompt, type errors +don't get delayed, so for example: + +:: + + Prelude> fst (True, 1 == 'a') + + <interactive>:2:12: + No instance for (Num Char) arising from the literal `1' + Possible fix: add an instance declaration for (Num Char) + In the first argument of `(==)', namely `1' + In the expression: 1 == 'a' + In the first argument of `fst', namely `(True, 1 == 'a')' + +Otherwise, in the common case of a simple type error such as typing +``reverse True`` at the prompt, you would get a warning and then an +immediately-following type error when the expression is evaluated. + +This exception doesn't apply to statements, as the following example +demonstrates: + +:: + + Prelude> let x = (True, 1 == 'a') + + <interactive>:3:16: Warning: + No instance for (Num Char) arising from the literal `1' + Possible fix: add an instance declaration for (Num Char) + In the first argument of `(==)', namely `1' + In the expression: 1 == 'a' + In the expression: (True, 1 == 'a') + Prelude> fst x + True + +.. _template-haskell: + +Template Haskell +================ + +Template Haskell allows you to do compile-time meta-programming in +Haskell. The background to the main technical innovations is discussed +in "`Template Meta-programming for +Haskell <http://research.microsoft.com/~simonpj/papers/meta-haskell/>`__" +(Proc Haskell Workshop 2002). + +There is a Wiki page about Template Haskell at +http://www.haskell.org/haskellwiki/Template_Haskell, and that is the +best place to look for further details. You may also consult the `online +Haskell library reference +material <http://www.haskell.org/ghc/docs/latest/html/libraries/index.html>`__ +(look for module ``Language.Haskell.TH``). Many changes to the original +design are described in `Notes on Template Haskell version +2 <http://research.microsoft.com/~simonpj/papers/meta-haskell/notes2.ps>`__. +Not all of these changes are in GHC, however. + +The first example from that paper is set out below (:ref:`th-example`) +as a worked example to help get you started. + +The documentation here describes the realisation of Template Haskell in +GHC. It is not detailed enough to understand Template Haskell; see the +`Wiki page <http://haskell.org/haskellwiki/Template_Haskell>`__. + +.. _th-syntax: + +Syntax +------ + +.. index:: + single: -XTemplateHaskell + +Template Haskell has the following new syntactic constructions. You need +to use the flag ``-XTemplateHaskell`` to switch these syntactic extensions +on. + +- A splice is written ``$x``, where ``x`` is an identifier, or + ``$(...)``, where the "..." is an arbitrary expression. There must be + no space between the "$" and the identifier or parenthesis. This use + of "$" overrides its meaning as an infix operator, just as "M.x" + overrides the meaning of "." as an infix operator. If you want the + infix operator, put spaces around it. + + A splice can occur in place of + + - an expression; the spliced expression must have type ``Q Exp`` + + - a pattern; the spliced pattern must have type ``Q Pat`` + + - a type; the spliced expression must have type ``Q Type`` + + - a list of declarations at top level; the spliced expression must + have type ``Q [Dec]`` + + Inside a splice you can only call functions defined in imported + modules, not functions defined elsewhere in the same module. Note + that declaration splices are not allowed anywhere except at top level + (outside any other declarations). + +- A expression quotation is written in Oxford brackets, thus: + + - ``[| ... |]``, or ``[e| ... |]``, where the "..." is an + expression; the quotation has type ``Q Exp``. + + - ``[d| ... |]``, where the "..." is a list of top-level + declarations; the quotation has type ``Q [Dec]``. + + - ``[t| ... |]``, where the "..." is a type; the quotation has type + ``Q Type``. + + - ``[p| ... |]``, where the "..." is a pattern; the quotation has + type ``Q Pat``. + + See :ref:`pts-where` for using partial type signatures in quotations. + +- A *typed* expression splice is written ``$$x``, where ``x`` is an + identifier, or ``$$(...)``, where the "..." is an arbitrary + expression. + + A typed expression splice can occur in place of an expression; the + spliced expression must have type ``Q (TExp a)`` + +- A *typed* expression quotation is written as ``[|| ... ||]``, or + ``[e|| ... ||]``, where the "..." is an expression; if the "..." + expression has type ``a``, then the quotation has type + ``Q (TExp a)``. + + Values of type ``TExp a`` may be converted to values of type ``Exp`` + using the function ``unType :: TExp a -> Exp``. + +- A quasi-quotation can appear in a pattern, type, expression, or + declaration context and is also written in Oxford brackets: + + - ``[varid| ... |]``, where the "..." is an arbitrary string; a full + description of the quasi-quotation facility is given in + :ref:`th-quasiquotation`. + +- A name can be quoted with either one or two prefix single quotes: + + - ``'f`` has type ``Name``, and names the function ``f``. Similarly + ``'C`` has type ``Name`` and names the data constructor ``C``. In + general ``'``\ ⟨thing⟩ interprets ⟨thing⟩ in an expression + context. + + A name whose second character is a single quote (sadly) cannot be + quoted in this way, because it will be parsed instead as a quoted + character. For example, if the function is called ``f'7`` (which + is a legal Haskell identifier), an attempt to quote it as ``'f'7`` + would be parsed as the character literal ``'f'`` followed by the + numeric literal ``7``. There is no current escape mechanism in + this (unusual) situation. + + - ``''T`` has type ``Name``, and names the type constructor ``T``. + That is, ``''``\ ⟨thing⟩ interprets ⟨thing⟩ in a type context. + + These ``Names`` can be used to construct Template Haskell + expressions, patterns, declarations etc. They may also be given as an + argument to the ``reify`` function. + +- It is possible for a splice to expand to an expression that contain + names which are not in scope at the site of the splice. As an + example, consider the following code: + + :: + + module Bar where + + import Language.Haskell.TH + + add1 :: Int -> Q Exp + add1 x = [| x + 1 |] + + Now consider a splice using <literal>add1</literal> in a separate + module: + + :: + + module Foo where + + import Bar + + two :: Int + two = $(add1 1) + + Template Haskell cannot know what the argument to ``add1`` will be at the + function's definition site, so a lifting mechanism is used to promote + ``x`` into a value of type ``Q Exp``. This functionality is exposed to the + user as the ``Lift`` typeclass in the ``Language.Haskell.TH.Syntax`` + module. If a type has a ``Lift`` instance, then any of its values can be + lifted to a Template Haskell expression: + + :: + + class Lift t where + lift :: t -> Q Exp + + In general, if GHC sees an expression within Oxford brackets (e.g., ``[| + foo bar |]``, then GHC looks up each name within the brackets. If a name + is global (e.g., suppose ``foo`` comes from an import or a top-level + declaration), then the fully qualified name is used directly in the + quotation. If the name is local (e.g., suppose ``bar`` is bound locally in + the function definition ``mkFoo bar = [| foo bar |]``), then GHC uses + ``lift`` on it (so GHC pretends ``[| foo bar |]`` actually contains ``[| + foo $(lift bar) |]``). Local names, which are not in scope at splice + locations, are actually evaluated when the quotation is processed. + + The ``template-haskell`` library provides ``Lift`` instances for many + common data types. Furthermore, it is possible to derive ``Lift`` + instances automatically by using the ``-XDeriveLift`` language extension. + See :ref:`deriving-lift` for more information. + +- You may omit the ``$(...)`` in a top-level declaration splice. Simply + writing an expression (rather than a declaration) implies a splice. + For example, you can write + + :: + + module Foo where + import Bar + + f x = x + + $(deriveStuff 'f) -- Uses the $(...) notation + + g y = y+1 + + deriveStuff 'g -- Omits the $(...) + + h z = z-1 + + This abbreviation makes top-level declaration slices quieter and less + intimidating. + +- Outermost pattern splices may bind variables. By "outermost" here, we + refer to a pattern splice that occurs outside of any quotation + brackets. For example, + + :: + + mkPat :: Bool -> Q Pat + mkPat True = [p| (x, y) |] + mkPat False = [p| (y, x) |] + + -- in another module: + foo :: (Char, String) -> String + foo $(mkPat True) = x : y + + bar :: (String, Char) -> String + bar $(mkPat False) = x : y + +- Nested pattern splices do *not* bind variables. By "nested" here, we + refer to a pattern splice occurring within a quotation bracket. + Continuing the example from the last bullet: + + :: + + baz :: Bool -> Q Exp + baz b = [| quux $(mkPat b) = x + y |] + + would fail with ``x`` and ``y`` being out of scope. + + The difference in treatment of outermost and nested pattern splices + is because outermost splices are run at compile time. GHC can then + use the result of running the splice when analysing the expressions + within the pattern's scope. Nested splices, on the other hand, are + *not* run at compile time; they are run when the bracket is spliced + in, sometime later. Since nested pattern splices may refer to local + variables, there is no way for GHC to know, at splice compile time, + what variables are bound, so it binds none. + +- A pattern quasiquoter *may* generate binders that scope over the + right-hand side of a definition because these binders are in scope + lexically. For example, given a quasiquoter ``haskell`` that parses + Haskell, in the following code, the ``y`` in the right-hand side of + ``f`` refers to the ``y`` bound by the ``haskell`` pattern + quasiquoter, *not* the top-level ``y = 7``. + + :: + + y :: Int + y = 7 + + f :: Int -> Int -> Int + f n = \ [haskell|y|] -> y+n + +- Top-level declaration splices break up a source file into + *declaration groups*. A *declaration group* is the group of + declarations created by a top-level declaration splice, plus those + following it, down to but not including the next top-level + declaration splice. The first declaration group in a module includes + all top-level definitions down to but not including the first + top-level declaration splice. + + Each declaration group is mutually recursive only within the group. + Declaration groups can refer to definitions within previous groups, + but not later ones. + + Accordingly, the type environment seen by ``reify`` includes all the + top-level declarations up to the end of the immediately preceding + declaration group, but no more. + + Unlike normal declaration splices, declaration quasiquoters do not + cause a break. These quasiquoters are expanded before the rest of the + declaration group is processed, and the declarations they generate + are merged into the surrounding declaration group. Consequently, the + type environment seen by ``reify`` from a declaration quasiquoter + will not include anything from the quasiquoter's declaration group. + + Concretely, consider the following code + + :: + + module M where + import ... + f x = x + $(th1 4) + h y = k y y $(blah1) + [qq|blah|] + k x y = x + y + $(th2 10) + w z = $(blah2) + + In this example + + 1. The body of ``h`` would be unable to refer to the function ``w``. + + A ``reify`` inside the splice ``$(th1 ..)`` would see the + definition of ``f``. + + 2. A ``reify`` inside the splice ``$(blah1)`` would see the + definition of ``f``, but would not see the definition of ``h``. + + 3. A ``reify`` inside the splice ``$(th2..)`` would see the + definition of ``f``, all the bindings created by ``$(th1..)``, and + the definition of ``h``. + + 4. A ``reify`` inside the splice ``$(blah2)`` would see the same + definitions as the splice ``$(th2...)``. + + 5. The body of ``h`` *is* able to refer to the function ``k`` + appearing on the other side of the declaration quasiquoter, as + quasiquoters never cause a declaration group to be broken up. + + A ``reify`` inside the ``qq`` quasiquoter would be able to see the + definition of ``f`` from the preceding declaration group, but not + the definitions of ``h`` or ``k``, or any definitions from + subsequent declaration groups. + +- Expression quotations accept most Haskell language constructs. + However, there are some GHC-specific extensions which expression + quotations currently do not support, including + + - Recursive ``do``-statements (see :ghc-ticket:`1262`) + + - Pattern synonyms (see :ghc-ticket:`8761`) + + - Typed holes (see :ghc-ticket:`10267`) + +(Compared to the original paper, there are many differences of detail. +The syntax for a declaration splice uses "``$``" not "``splice``". The type of +the enclosed expression must be ``Q [Dec]``, not ``[Q Dec]``. Typed expression +splices and quotations are supported.) + +Using Template Haskell +---------------------- + +- The data types and monadic constructor functions for Template Haskell + are in the library ``Language.Haskell.THSyntax``. + +- You can only run a function at compile time if it is imported from + another module. That is, you can't define a function in a module, and + call it from within a splice in the same module. (It would make sense + to do so, but it's hard to implement.) + +- You can only run a function at compile time if it is imported from + another module *that is not part of a mutually-recursive group of + modules that includes the module currently being compiled*. + Furthermore, all of the modules of the mutually-recursive group must + be reachable by non-SOURCE imports from the module where the splice + is to be run. + + For example, when compiling module A, you can only run Template + Haskell functions imported from B if B does not import A (directly or + indirectly). The reason should be clear: to run B we must compile and + run A, but we are currently type-checking A. + +- If you are building GHC from source, you need at least a stage-2 + bootstrap compiler to run Template Haskell splices and quasi-quotes. + A stage-1 compiler will only accept regular quotes of Haskell. + Reason: TH splices and quasi-quotes compile and run a program, and + then looks at the result. So it's important that the program it + compiles produces results whose representations are identical to + those of the compiler itself. + +Template Haskell works in any mode (``--make``, ``--interactive``, or +file-at-a-time). There used to be a restriction to the former two, but +that restriction has been lifted. + +.. _th-view-gen-code: + +Viewing Template Haskell generated code +--------------------------------------- + +The flag ``-ddump-splices`` shows the expansion of all top-level +declaration splices, both typed and untyped, as they happen. As with all +dump flags, the default is for this output to be sent to stdout. For a +non-trivial program, you may be interested in combining this with the +``-ddump-to-file flag`` (see :ref:`dumping-output`. For each file using +Template Haskell, this will show the output in a ``.dump-splices`` file. + +The flag ``-dth-dec-file`` shows the expansions of all top-level TH +declaration splices, both typed and untyped, in the file ``M.th.hs`` +where M is the name of the module being compiled. Note that other types +of splices (expressions, types, and patterns) are not shown. Application +developers can check this into their repository so that they can grep +for identifiers that were defined in Template Haskell. This is similar +to using ``-ddump-to-file`` with ``-ddump-splices`` but it always +generates a file instead of being coupled to ``-ddump-to-file``. The +format is also different: it does not show code from the original file, +instead it only shows generated code and has a comment for the splice +location of the original file. + +Below is a sample output of ``-ddump-splices`` + +:: + + TH_pragma.hs:(6,4)-(8,26): Splicing declarations + [d| foo :: Int -> Int + foo x = x + 1 |] + ======> + foo :: Int -> Int + foo x = (x + 1) + +Below is the output of the same sample using ``-dth-dec-file`` + +:: + + -- TH_pragma.hs:(6,4)-(8,26): Splicing declarations + foo :: Int -> Int + foo x = (x + 1) + +.. _th-example: + +A Template Haskell Worked Example +--------------------------------- + +To help you get over the confidence barrier, try out this skeletal +worked example. First cut and paste the two modules below into "Main.hs" +and "Printf.hs": + +:: + + + {- Main.hs -} + module Main where + + -- Import our template "pr" + import Printf ( pr ) + + -- The splice operator $ takes the Haskell source code + -- generated at compile time by "pr" and splices it into + -- the argument of "putStrLn". + main = putStrLn ( $(pr "Hello") ) + + + {- Printf.hs -} + module Printf where + + -- Skeletal printf from the paper. + -- It needs to be in a separate module to the one where + -- you intend to use it. + + -- Import some Template Haskell syntax + import Language.Haskell.TH + + -- Describe a format string + data Format = D | S | L String + + -- Parse a format string. This is left largely to you + -- as we are here interested in building our first ever + -- Template Haskell program and not in building printf. + parse :: String -> [Format] + parse s = [ L s ] + + -- Generate Haskell source code from a parsed representation + -- of the format string. This code will be spliced into + -- the module which calls "pr", at compile time. + gen :: [Format] -> Q Exp + gen [D] = [| \n -> show n |] + gen [S] = [| \s -> s |] + gen [L s] = stringE s + + -- Here we generate the Haskell code for the splice + -- from an input format string. + pr :: String -> Q Exp + pr s = gen (parse s) + +Now run the compiler (here we are a Cygwin prompt on Windows): + +:: + + $ ghc --make -XTemplateHaskell main.hs -o main.exe + +Run "main.exe" and here is your output: + +:: + + $ ./main + Hello + +Using Template Haskell with Profiling +------------------------------------- + +.. index:: + single: profiling; with Template Haskell + +Template Haskell relies on GHC's built-in bytecode compiler and +interpreter to run the splice expressions. The bytecode interpreter runs +the compiled expression on top of the same runtime on which GHC itself +is running; this means that the compiled code referred to by the +interpreted expression must be compatible with this runtime, and in +particular this means that object code that is compiled for profiling +*cannot* be loaded and used by a splice expression, because profiled +object code is only compatible with the profiling version of the +runtime. + +This causes difficulties if you have a multi-module program containing +Template Haskell code and you need to compile it for profiling, because +GHC cannot load the profiled object code and use it when executing the +splices. Fortunately GHC provides a workaround. The basic idea is to +compile the program twice: + + +1. Compile the program or library first the normal way, without ``-prof``. + + .. index:: + single : ``-prof`` + +2. Then compile it again with ``-prof``, and additionally use ``-osuf p_o`` + to name the object files differently (you can + choose any suffix that isn't the normal object suffix here). GHC will + automatically load the object files built in the first step when + executing splice expressions. If you omit the ``-osuf`` flag when + building with ``-prof`` and Template Haskell is used, GHC will emit + an error message. + + .. index:: + single : ``-osuf`` + + +.. _th-quasiquotation: + +Template Haskell Quasi-quotation +-------------------------------- + +Quasi-quotation allows patterns and expressions to be written using +programmer-defined concrete syntax; the motivation behind the extension +and several examples are documented in "`Why It's Nice to be Quoted: +Quasiquoting for +Haskell <http://www.cs.tufts.edu/comp/150FP/archive/geoff-mainland/quasiquoting.pdf>`__" +(Proc Haskell Workshop 2007). The example below shows how to write a +quasiquoter for a simple expression language. + +Here are the salient features + +- A quasi-quote has the form ``[quoter| string |]``. + + - The ⟨quoter⟩ must be the name of an imported quoter, either + qualified or unqualified; it cannot be an arbitrary expression. + + - The ⟨quoter⟩ cannot be "``e``", "``t``", "``d``", or "``p``", + since those overlap with Template Haskell quotations. + + - There must be no spaces in the token ``[quoter|``. + + - The quoted ⟨string⟩ can be arbitrary, and may contain newlines. + + - The quoted ⟨string⟩ finishes at the first occurrence of the + two-character sequence ``"|]"``. Absolutely no escaping is + performed. If you want to embed that character sequence in the + string, you must invent your own escape convention (such as, say, + using the string ``"|~]"`` instead), and make your quoter function + interpret ``"|~]"`` as ``"|]"``. One way to implement this is to + compose your quoter with a pre-processing pass to perform your + escape conversion. See the discussion in :ghc-ticket:`5348` for details. + +- A quasiquote may appear in place of + + - An expression + + - A pattern + + - A type + + - A top-level declaration + + (Only the first two are described in the paper.) + +- A quoter is a value of type + ``Language.Haskell.TH.Quote.QuasiQuoter``, which is defined thus: + + :: + + data QuasiQuoter = QuasiQuoter { quoteExp :: String -> Q Exp, + quotePat :: String -> Q Pat, + quoteType :: String -> Q Type, + quoteDec :: String -> Q [Dec] } + + That is, a quoter is a tuple of four parsers, one for each of the + contexts in which a quasi-quote can occur. + +- A quasi-quote is expanded by applying the appropriate parser to the + string enclosed by the Oxford brackets. The context of the + quasi-quote (expression, pattern, type, declaration) determines which + of the parsers is called. + +- Unlike normal declaration splices of the form ``$(...)``, declaration + quasi-quotes do not cause a declaration group break. See + :ref:`th-syntax` for more information. + +The example below shows quasi-quotation in action. The quoter ``expr`` +is bound to a value of type ``QuasiQuoter`` defined in module ``Expr``. +The example makes use of an antiquoted variable ``n``, indicated by the +syntax ``'int:n`` (this syntax for anti-quotation was defined by the +parser's author, *not* by GHC). This binds ``n`` to the integer value +argument of the constructor ``IntExpr`` when pattern matching. Please +see the referenced paper for further details regarding anti-quotation as +well as the description of a technique that uses SYB to leverage a +single parser of type ``String -> a`` to generate both an expression +parser that returns a value of type ``Q Exp`` and a pattern parser that +returns a value of type ``Q Pat``. + +Quasiquoters must obey the same stage restrictions as Template Haskell, +e.g., in the example, ``expr`` cannot be defined in ``Main.hs`` where it +is used, but must be imported. + +:: + + {- ------------- file Main.hs --------------- -} + module Main where + + import Expr + + main :: IO () + main = do { print $ eval [expr|1 + 2|] + ; case IntExpr 1 of + { [expr|'int:n|] -> print n + ; _ -> return () + } + } + + + {- ------------- file Expr.hs --------------- -} + module Expr where + + import qualified Language.Haskell.TH as TH + import Language.Haskell.TH.Quote + + data Expr = IntExpr Integer + | AntiIntExpr String + | BinopExpr BinOp Expr Expr + | AntiExpr String + deriving(Show, Typeable, Data) + + data BinOp = AddOp + | SubOp + | MulOp + | DivOp + deriving(Show, Typeable, Data) + + eval :: Expr -> Integer + eval (IntExpr n) = n + eval (BinopExpr op x y) = (opToFun op) (eval x) (eval y) + where + opToFun AddOp = (+) + opToFun SubOp = (-) + opToFun MulOp = (*) + opToFun DivOp = div + + expr = QuasiQuoter { quoteExp = parseExprExp, quotePat = parseExprPat } + + -- Parse an Expr, returning its representation as + -- either a Q Exp or a Q Pat. See the referenced paper + -- for how to use SYB to do this by writing a single + -- parser of type String -> Expr instead of two + -- separate parsers. + + parseExprExp :: String -> Q Exp + parseExprExp ... + + parseExprPat :: String -> Q Pat + parseExprPat ... + +Now run the compiler: + +:: + + $ ghc --make -XQuasiQuotes Main.hs -o main + +Run "main" and here is your output: + +:: + + $ ./main + 3 + 1 + +.. _arrow-notation: + +Arrow notation +============== + +Arrows are a generalisation of monads introduced by John Hughes. For +more details, see + +- “Generalising Monads to Arrows”, John Hughes, in Science of Computer + Programming 37, pp. 67–111, May 2000. The paper that introduced arrows: + a friendly introduction, motivated with programming examples. + +- “\ `A New Notation for + Arrows <http://www.soi.city.ac.uk/~ross/papers/notation.html>`__\ ”, + Ross Paterson, in ICFP, Sep 2001. Introduced the notation described + here. + +- “\ `Arrows and + Computation <http://www.soi.city.ac.uk/~ross/papers/fop.html>`__\ ”, + Ross Paterson, in The Fun of Programming, Palgrave, 2003. + +- “\ `Programming with + Arrows <http://www.cse.chalmers.se/~rjmh/afp-arrows.pdf>`__\ ”, John + Hughes, in 5th International Summer School on Advanced Functional + Programming, Lecture Notes in Computer Science vol. 3622, Springer, + 2004. This paper includes another introduction to the notation, with + practical examples. + +- “\ `Type and Translation Rules for Arrow Notation in + GHC <http://www.haskell.org/ghc/docs/papers/arrow-rules.pdf>`__\ ”, + Ross Paterson and Simon Peyton Jones, September 16, 2004. A terse + enumeration of the formal rules used (extracted from comments in the + source code). + +- The arrows web page at + ```http://www.haskell.org/arrows/`` <http://www.haskell.org/arrows/>`__. + +With the ``-XArrows`` flag, GHC supports the arrow notation described in +the second of these papers, translating it using combinators from the +:base-ref:`Control.Arrow <Control-Arrow.html>` module. +What follows is a brief introduction to the notation; it won't make much +sense unless you've read Hughes's paper. + +The extension adds a new kind of expression for defining arrows: + +:: + + exp10 ::= ... + | proc apat -> cmd + +where ``proc`` is a new keyword. The variables of the pattern are bound +in the body of the ``proc``-expression, which is a new sort of thing +called a command. The syntax of commands is as follows: + +:: + + cmd ::= exp10 -< exp + | exp10 -<< exp + | cmd0 + +with ⟨cmd⟩\ :sup:`0` up to ⟨cmd⟩\ :sup:`9` defined using infix operators +as for expressions, and + +:: + + cmd10 ::= \ apat ... apat -> cmd + | let decls in cmd + | if exp then cmd else cmd + | case exp of { calts } + | do { cstmt ; ... cstmt ; cmd } + | fcmd + + fcmd ::= fcmd aexp + | ( cmd ) + | (| aexp cmd ... cmd |) + + cstmt ::= let decls + | pat <- cmd + | rec { cstmt ; ... cstmt [;] } + | cmd + +where ⟨calts⟩ are like ⟨alts⟩ except that the bodies are commands +instead of expressions. + +Commands produce values, but (like monadic computations) may yield more +than one value, or none, and may do other things as well. For the most +part, familiarity with monadic notation is a good guide to using +commands. However the values of expressions, even monadic ones, are +determined by the values of the variables they contain; this is not +necessarily the case for commands. + +A simple example of the new notation is the expression + +:: + + proc x -> f -< x+1 + +We call this a procedure or arrow abstraction. As with a lambda +expression, the variable ``x`` is a new variable bound within the +``proc``-expression. It refers to the input to the arrow. In the above +example, ``-<`` is not an identifier but an new reserved symbol used for +building commands from an expression of arrow type and an expression to +be fed as input to that arrow. (The weird look will make more sense +later.) It may be read as analogue of application for arrows. The above +example is equivalent to the Haskell expression + +:: + + arr (\ x -> x+1) >>> f + +That would make no sense if the expression to the left of ``-<`` +involves the bound variable ``x``. More generally, the expression to the +left of ``-<`` may not involve any local variable, i.e. a variable bound +in the current arrow abstraction. For such a situation there is a +variant ``-<<``, as in + +:: + + proc x -> f x -<< x+1 + +which is equivalent to + +:: + + arr (\ x -> (f x, x+1)) >>> app + +so in this case the arrow must belong to the ``ArrowApply`` class. Such +an arrow is equivalent to a monad, so if you're using this form you may +find a monadic formulation more convenient. + +do-notation for commands +------------------------ + +Another form of command is a form of ``do``-notation. For example, you +can write + +:: + + proc x -> do + y <- f -< x+1 + g -< 2*y + let z = x+y + t <- h -< x*z + returnA -< t+z + +You can read this much like ordinary ``do``-notation, but with commands +in place of monadic expressions. The first line sends the value of +``x+1`` as an input to the arrow ``f``, and matches its output against +``y``. In the next line, the output is discarded. The arrow ``returnA`` +is defined in the :base-ref:`Control.Arrow <Control-Arrow.html>` module as ``arr +id``. The above example is treated as an abbreviation for + +:: + + arr (\ x -> (x, x)) >>> + first (arr (\ x -> x+1) >>> f) >>> + arr (\ (y, x) -> (y, (x, y))) >>> + first (arr (\ y -> 2*y) >>> g) >>> + arr snd >>> + arr (\ (x, y) -> let z = x+y in ((x, z), z)) >>> + first (arr (\ (x, z) -> x*z) >>> h) >>> + arr (\ (t, z) -> t+z) >>> + returnA + +Note that variables not used later in the composition are projected out. +After simplification using rewrite rules (see :ref:`rewrite-rules`) +defined in the :base-ref:`Control.Arrow <Control-Arrow.html>` module, this +reduces to + +:: + + arr (\ x -> (x+1, x)) >>> + first f >>> + arr (\ (y, x) -> (2*y, (x, y))) >>> + first g >>> + arr (\ (_, (x, y)) -> let z = x+y in (x*z, z)) >>> + first h >>> + arr (\ (t, z) -> t+z) + +which is what you might have written by hand. With arrow notation, GHC +keeps track of all those tuples of variables for you. + +Note that although the above translation suggests that ``let``-bound +variables like ``z`` must be monomorphic, the actual translation +produces Core, so polymorphic variables are allowed. + +It's also possible to have mutually recursive bindings, using the new +``rec`` keyword, as in the following example: + +:: + + counter :: ArrowCircuit a => a Bool Int + counter = proc reset -> do + rec output <- returnA -< if reset then 0 else next + next <- delay 0 -< output+1 + returnA -< output + +The translation of such forms uses the ``loop`` combinator, so the arrow +concerned must belong to the ``ArrowLoop`` class. + +Conditional commands +-------------------- + +In the previous example, we used a conditional expression to construct +the input for an arrow. Sometimes we want to conditionally execute +different commands, as in + +:: + + proc (x,y) -> + if f x y + then g -< x+1 + else h -< y+2 + +which is translated to + +:: + + arr (\ (x,y) -> if f x y then Left x else Right y) >>> + (arr (\x -> x+1) >>> g) ||| (arr (\y -> y+2) >>> h) + +Since the translation uses ``|||``, the arrow concerned must belong to +the ``ArrowChoice`` class. + +There are also ``case`` commands, like + +:: + + case input of + [] -> f -< () + [x] -> g -< x+1 + x1:x2:xs -> do + y <- h -< (x1, x2) + ys <- k -< xs + returnA -< y:ys + +The syntax is the same as for ``case`` expressions, except that the +bodies of the alternatives are commands rather than expressions. The +translation is similar to that of ``if`` commands. + +Defining your own control structures +------------------------------------ + +As we're seen, arrow notation provides constructs, modelled on those for +expressions, for sequencing, value recursion and conditionals. But +suitable combinators, which you can define in ordinary Haskell, may also +be used to build new commands out of existing ones. The basic idea is +that a command defines an arrow from environments to values. These +environments assign values to the free local variables of the command. +Thus combinators that produce arrows from arrows may also be used to +build commands from commands. For example, the ``ArrowPlus`` class +includes a combinator + +:: + + ArrowPlus a => (<+>) :: a b c -> a b c -> a b c + +so we can use it to build commands: + +:: + + expr' = proc x -> do + returnA -< x + <+> do + symbol Plus -< () + y <- term -< () + expr' -< x + y + <+> do + symbol Minus -< () + y <- term -< () + expr' -< x - y + +(The ``do`` on the first line is needed to prevent the first ``<+> ...`` +from being interpreted as part of the expression on the previous line.) +This is equivalent to + +:: + + expr' = (proc x -> returnA -< x) + <+> (proc x -> do + symbol Plus -< () + y <- term -< () + expr' -< x + y) + <+> (proc x -> do + symbol Minus -< () + y <- term -< () + expr' -< x - y) + +We are actually using ``<+>`` here with the more specific type + +:: + + ArrowPlus a => (<+>) :: a (e,()) c -> a (e,()) c -> a (e,()) c + +It is essential that this operator be polymorphic in ``e`` (representing +the environment input to the command and thence to its subcommands) and +satisfy the corresponding naturality property + +:: + + arr (first k) >>> (f <+> g) = (arr (first k) >>> f) <+> (arr (first k) >>> g) + +at least for strict ``k``. (This should be automatic if you're not using +``seq``.) This ensures that environments seen by the subcommands are +environments of the whole command, and also allows the translation to +safely trim these environments. (The second component of the input pairs +can contain unnamed input values, as described in the next section.) The +operator must also not use any variable defined within the current arrow +abstraction. + +We could define our own operator + +:: + + untilA :: ArrowChoice a => a (e,s) () -> a (e,s) Bool -> a (e,s) () + untilA body cond = proc x -> + b <- cond -< x + if b then returnA -< () + else do + body -< x + untilA body cond -< x + +and use it in the same way. Of course this infix syntax only makes sense +for binary operators; there is also a more general syntax involving +special brackets: + +:: + + proc x -> do + y <- f -< x+1 + (|untilA (increment -< x+y) (within 0.5 -< x)|) + +Primitive constructs +-------------------- + +Some operators will need to pass additional inputs to their subcommands. +For example, in an arrow type supporting exceptions, the operator that +attaches an exception handler will wish to pass the exception that +occurred to the handler. Such an operator might have a type + +:: + + handleA :: ... => a (e,s) c -> a (e,(Ex,s)) c -> a (e,s) c + +where ``Ex`` is the type of exceptions handled. You could then use this +with arrow notation by writing a command + +:: + + body `handleA` \ ex -> handler + +so that if an exception is raised in the command ``body``, the variable +``ex`` is bound to the value of the exception and the command +``handler``, which typically refers to ``ex``, is entered. Though the +syntax here looks like a functional lambda, we are talking about +commands, and something different is going on. The input to the arrow +represented by a command consists of values for the free local variables +in the command, plus a stack of anonymous values. In all the prior +examples, we made no assumptions about this stack. In the second +argument to ``handleA``, the value of the exception has been added to +the stack input to the handler. The command form of lambda merely gives +this value a name. + +More concretely, the input to a command consists of a pair of an +environment and a stack. Each value on the stack is paired with the +remainder of the stack, with an empty stack being ``()``. So operators +like ``handleA`` that pass extra inputs to their subcommands can be +designed for use with the notation by placing the values on the stack +paired with the environment in this way. More precisely, the type of +each argument of the operator (and its result) should have the form + +:: + + a (e, (t1, ... (tn, ())...)) t + +where ⟨e⟩ is a polymorphic variable (representing the environment) and +⟨ti⟩ are the types of the values on the stack, with ⟨t1⟩ being the +"top". The polymorphic variable ⟨e⟩ must not occur in ⟨a⟩, ⟨ti⟩ or ⟨t⟩. +However the arrows involved need not be the same. Here are some more +examples of suitable operators: + +:: + + bracketA :: ... => a (e,s) b -> a (e,(b,s)) c -> a (e,(c,s)) d -> a (e,s) d + runReader :: ... => a (e,s) c -> a' (e,(State,s)) c + runState :: ... => a (e,s) c -> a' (e,(State,s)) (c,State) + +We can supply the extra input required by commands built with the last +two by applying them to ordinary expressions, as in + +:: + + proc x -> do + s <- ... + (|runReader (do { ... })|) s + +which adds ``s`` to the stack of inputs to the command built using +``runReader``. + +The command versions of lambda abstraction and application are analogous +to the expression versions. In particular, the beta and eta rules +describe equivalences of commands. These three features (operators, +lambda abstraction and application) are the core of the notation; +everything else can be built using them, though the results would be +somewhat clumsy. For example, we could simulate ``do``\-notation by +defining + +:: + + bind :: Arrow a => a (e,s) b -> a (e,(b,s)) c -> a (e,s) c + u `bind` f = returnA &&& u >>> f + + bind_ :: Arrow a => a (e,s) b -> a (e,s) c -> a (e,s) c + u `bind_` f = u `bind` (arr fst >>> f) + +We could simulate ``if`` by defining + +:: + + cond :: ArrowChoice a => a (e,s) b -> a (e,s) b -> a (e,(Bool,s)) b + cond f g = arr (\ (e,(b,s)) -> if b then Left (e,s) else Right (e,s)) >>> f ||| g + +Differences with the paper +-------------------------- + +- Instead of a single form of arrow application (arrow tail) with two + translations, the implementation provides two forms “``-<``” + (first-order) and “``-<<``” (higher-order). + +- User-defined operators are flagged with banana brackets instead of a + new ``form`` keyword. + +- In the paper and the previous implementation, values on the stack + were paired to the right of the environment in a single argument, but + now the environment and stack are separate arguments. + +Portability +----------- + +Although only GHC implements arrow notation directly, there is also a +preprocessor (available from the `arrows web +page <http://www.haskell.org/arrows/>`__) that translates arrow notation +into Haskell 98 for use with other Haskell systems. You would still want +to check arrow programs with GHC; tracing type errors in the +preprocessor output is not easy. Modules intended for both GHC and the +preprocessor must observe some additional restrictions: + +- The module must import :base-ref:`Control.Arrow <Control-Arrow.html>`. + +- The preprocessor cannot cope with other Haskell extensions. These + would have to go in separate modules. + +- Because the preprocessor targets Haskell (rather than Core), + ``let``\-bound variables are monomorphic. + +.. _bang-patterns: + +Bang patterns +============= + +.. index:: + single: Bang patterns + +GHC supports an extension of pattern matching called *bang patterns*, +written ``!pat``. Bang patterns are under consideration for Haskell +Prime. The `Haskell prime feature +description <http://ghc.haskell.org/trac/haskell-prime/wiki/BangPatterns>`__ +contains more discussion and examples than the material below. + +The key change is the addition of a new rule to the `semantics of +pattern matching in the Haskell 98 +report <http://haskell.org/onlinereport/exps.html#sect3.17.2>`__. Add +new bullet 10, saying: Matching the pattern ``!``\ ⟨pat⟩ against a value +⟨v⟩ behaves as follows: + +- if ⟨v⟩ is bottom, the match diverges + +- otherwise, ⟨pat⟩ is matched against ⟨v⟩ + +Bang patterns are enabled by the flag ``-XBangPatterns``. + +.. _bang-patterns-informal: + +Informal description of bang patterns +------------------------------------- + +The main idea is to add a single new production to the syntax of +patterns: + +:: + + pat ::= !pat + +Matching an expression ``e`` against a pattern ``!p`` is done by first +evaluating ``e`` (to WHNF) and then matching the result against ``p``. +Example: + +:: + + f1 !x = True + +This definition makes ``f1`` is strict in ``x``, whereas without the +bang it would be lazy. Bang patterns can be nested of course: + +:: + + f2 (!x, y) = [x,y] + +Here, ``f2`` is strict in ``x`` but not in ``y``. A bang only really has +an effect if it precedes a variable or wild-card pattern: + +:: + + f3 !(x,y) = [x,y] + f4 (x,y) = [x,y] + +Here, ``f3`` and ``f4`` are identical; putting a bang before a pattern +that forces evaluation anyway does nothing. + +There is one (apparent) exception to this general rule that a bang only +makes a difference when it precedes a variable or wild-card: a bang at +the top level of a ``let`` or ``where`` binding makes the binding +strict, regardless of the pattern. (We say "apparent" exception because +the Right Way to think of it is that the bang at the top of a binding is +not part of the *pattern*; rather it is part of the syntax of the +*binding*, creating a "bang-pattern binding".) For example: + +:: + + let ![x,y] = e in b + +is a bang-pattern binding. Operationally, it behaves just like a case +expression: + +:: + + case e of [x,y] -> b + +Like a case expression, a bang-pattern binding must be non-recursive, +and is monomorphic. However, *nested* bangs in a pattern binding behave +uniformly with all other forms of pattern matching. For example + +:: + + let (!x,[y]) = e in b + +is equivalent to this: + +:: + + let { t = case e of (x,[y]) -> x `seq` (x,y) + x = fst t + y = snd t } + in b + +The binding is lazy, but when either ``x`` or ``y`` is evaluated by +``b`` the entire pattern is matched, including forcing the evaluation of +``x``. + +Bang patterns work in ``case`` expressions too, of course: + +:: + + g5 x = let y = f x in body + g6 x = case f x of { y -> body } + g7 x = case f x of { !y -> body } + +The functions ``g5`` and ``g6`` mean exactly the same thing. But ``g7`` +evaluates ``(f x)``, binds ``y`` to the result, and then evaluates +``body``. + +.. _bang-patterns-sem: + +Syntax and semantics +-------------------- + +We add a single new production to the syntax of patterns: + +:: + + pat ::= !pat + +There is one problem with syntactic ambiguity. Consider: + +:: + + f !x = 3 + +Is this a definition of the infix function "``(!)``", or of the "``f``" +with a bang pattern? GHC resolves this ambiguity in favour of the +latter. If you want to define ``(!)`` with bang-patterns enabled, you +have to do so using prefix notation: + +:: + + (!) f x = 3 + +The semantics of Haskell pattern matching is described in `Section +3.17.2 <http://www.haskell.org/onlinereport/exps.html#sect3.17.2>`__ of +the Haskell Report. To this description add one extra item 10, saying: + +- Matching the pattern ``!pat`` against a value ``v`` behaves as + follows: + + - if ``v`` is bottom, the match diverges + + - otherwise, ``pat`` is matched against ``v`` + +Similarly, in Figure 4 of `Section +3.17.3 <http://www.haskell.org/onlinereport/exps.html#sect3.17.3>`__, +add a new case (t): + +:: + + case v of { !pat -> e; _ -> e' } + = v `seq` case v of { pat -> e; _ -> e' } + +That leaves let expressions, whose translation is given in `Section +3.12 <http://www.haskell.org/onlinereport/exps.html#sect3.12>`__ of the +Haskell Report. In the translation box, first apply the following +transformation: for each pattern ``pi`` that is of form ``!qi = ei``, +transform it to ``(xi,!qi) = ((),ei)``, and replace ``e0`` by +``(xi `seq` e0)``. Then, when none of the left-hand-side patterns have a +bang at the top, apply the rules in the existing box. + +The effect of the let rule is to force complete matching of the pattern +``qi`` before evaluation of the body is begun. The bang is retained in +the translated form in case ``qi`` is a variable, thus: + +:: + + let !y = f x in b + +The let-binding can be recursive. However, it is much more common for +the let-binding to be non-recursive, in which case the following law +holds: ``(let !p = rhs in body)`` is equivalent to +``(case rhs of !p -> body)`` + +A pattern with a bang at the outermost level is not allowed at the top +level of a module. + +.. _assertions: + +Assertions +========== + +.. index:: + single: Assertions + +If you want to make use of assertions in your standard Haskell code, you +could define a function like the following: + +:: + + assert :: Bool -> a -> a + assert False x = error "assertion failed!" + assert _ x = x + +which works, but gives you back a less than useful error message -- an +assertion failed, but which and where? + +One way out is to define an extended ``assert`` function which also +takes a descriptive string to include in the error message and perhaps +combine this with the use of a pre-processor which inserts the source +location where ``assert`` was used. + +GHC offers a helping hand here, doing all of this for you. For every use +of ``assert`` in the user's source: + +:: + + kelvinToC :: Double -> Double + kelvinToC k = assert (k >= 0.0) (k+273.15) + +GHC will rewrite this to also include the source location where the +assertion was made, + +:: + + assert pred val ==> assertError "Main.hs|15" pred val + +The rewrite is only performed by the compiler when it spots applications +of ``Control.Exception.assert``, so you can still define and use your +own versions of ``assert``, should you so wish. If not, import +``Control.Exception`` to make use ``assert`` in your code. + +.. index:: + single: -O flag + single: -fignore-asserts + +GHC ignores assertions when optimisation is turned on with the +``-O`` flag. That is, expressions of the form ``assert pred e`` +will be rewritten to ``e``. You can also disable assertions using the +``-fignore-asserts`` option. The option ``-fno-ignore-asserts`` allows enabling +assertions even when optimisation is turned on. + +Assertion failures can be caught, see the documentation for the +``Control.Exception`` library for the details. + +.. _static-pointers: + +Static pointers +=============== + +.. index:: + single: Static pointers + +The language extension ``-XStaticPointers`` adds a new syntactic form +``static e``, which stands for a reference to the closed expression ⟨e⟩. +This reference is stable and portable, in the sense that it remains +valid across different processes on possibly different machines. Thus, a +process can create a reference and send it to another process that can +resolve it to ⟨e⟩. + +With this extension turned on, ``static`` is no longer a valid +identifier. + +Static pointers were first proposed in the paper `Towards Haskell in the +cloud <http://research.microsoft.com/en-us/um/people/simonpj/papers/parallel/remote.pdf>`__, +Jeff Epstein, Andrew P. Black and Simon Peyton-Jones, Proceedings of the +4th ACM Symposium on Haskell, pp. 118-129, ACM, 2011. + +.. _using-static-pointers: + +Using static pointers +--------------------- + +Each reference is given a key which can be used to locate it at runtime +with +:base-ref:`unsafeLookupStaticPtr <GHC.StaticPtr.html#v%3AunsafeLookupStaticPtr>` +which uses a global and immutable table called the Static Pointer Table. +The compiler includes entries in this table for all static forms found +in the linked modules. The value can be obtained from the reference via +:base-ref:`deRefStaticPtr <GHC.StaticPtr.html#v%3AdeRefStaticPtr>`. + +The body ``e`` of a ``static e`` expression must be a closed expression. +That is, there can be no free variables occurring in ``e``, i.e. lambda- +or let-bound variables bound locally in the context of the expression. + +All of the following are permissible: + +:: + + inc :: Int -> Int + inc x = x + 1 + + ref1 = static 1 + ref2 = static inc + ref3 = static (inc 1) + ref4 = static ((\x -> x + 1) (1 :: Int)) + ref5 y = static (let x = 1 in x) + +While the following definitions are rejected: + +:: + + ref6 = let x = 1 in static x + ref7 y = static (let x = 1 in y) + +.. _typechecking-static-pointers: + +Static semantics of static pointers +----------------------------------- + +Informally, if we have a closed expression + +:: + + e :: forall a_1 ... a_n . t + +the static form is of type + +:: + + static e :: (Typeable a_1, ... , Typeable a_n) => StaticPtr t + +Furthermore, type ``t`` is constrained to have a ``Typeable`` instance. +The following are therefore illegal: + +:: + + static show -- No Typeable instance for (Show a => a -> String) + static Control.Monad.ST.runST -- No Typeable instance for ((forall s. ST s a) -> a) + +That being said, with the appropriate use of wrapper datatypes, the +above limitations induce no loss of generality: + +:: + + {-# LANGUAGE ConstraintKinds #-} + {-# LANGUAGE DeriveDataTypeable #-} + {-# LANGUAGE ExistentialQuantification #-} + {-# LANGUAGE Rank2Types #-} + {-# LANGUAGE StandaloneDeriving #-} + {-# LANGUAGE StaticPointers #-} + + import Control.Monad.ST + import Data.Typeable + import GHC.StaticPtr + + data Dict c = c => Dict + deriving Typeable + + g1 :: Typeable a => StaticPtr (Dict (Show a) -> a -> String) + g1 = static (\Dict -> show) + + data Rank2Wrapper f = R2W (forall s. f s) + deriving Typeable + newtype Flip f a s = Flip { unFlip :: f s a } + deriving Typeable + + g2 :: Typeable a => StaticPtr (Rank2Wrapper (Flip ST a) -> a) + g2 = static (\(R2W f) -> runST (unFlip f)) + +.. _pragmas: + +Pragmas +======= + +.. index:: + single: pragma + +GHC supports several pragmas, or instructions to the compiler placed in +the source code. Pragmas don't normally affect the meaning of the +program, but they might affect the efficiency of the generated code. + +Pragmas all take the form ``{-# word ... #-}`` where ⟨word⟩ indicates +the type of pragma, and is followed optionally by information specific +to that type of pragma. Case is ignored in ⟨word⟩. The various values +for ⟨word⟩ that GHC understands are described in the following sections; +any pragma encountered with an unrecognised ⟨word⟩ is ignored. The +layout rule applies in pragmas, so the closing ``#-}`` should start in a +column to the right of the opening ``{-#``. + +Certain pragmas are *file-header pragmas*: + +- A file-header pragma must precede the ``module`` keyword in the file. + +- There can be as many file-header pragmas as you please, and they can + be preceded or followed by comments. + +- File-header pragmas are read once only, before pre-processing the + file (e.g. with cpp). + +- The file-header pragmas are: ``{-# LANGUAGE #-}``, + ``{-# OPTIONS_GHC #-}``, and ``{-# INCLUDE #-}``. + +.. _language-pragma: + +LANGUAGE pragma +--------------- + +.. index:: + single: LANGUAGE; pragma + single: pragma; LANGUAGE + +The ``LANGUAGE`` pragma allows language extensions to be enabled in a +portable way. It is the intention that all Haskell compilers support the +``LANGUAGE`` pragma with the same syntax, although not all extensions +are supported by all compilers, of course. The ``LANGUAGE`` pragma +should be used instead of ``OPTIONS_GHC``, if possible. + +For example, to enable the FFI and preprocessing with CPP: + +:: + + {-# LANGUAGE ForeignFunctionInterface, CPP #-} + +``LANGUAGE`` is a file-header pragma (see :ref:`pragmas`). + +Every language extension can also be turned into a command-line flag by +prefixing it with "``-X``"; for example ``-XForeignFunctionInterface``. +(Similarly, all "``-X``" flags can be written as ``LANGUAGE`` pragmas.) + +A list of all supported language extensions can be obtained by invoking +``ghc --supported-extensions`` (see :ref:`modes`). + +Any extension from the ``Extension`` type defined in +:cabal-ref:`Language.Haskell.Extension <Language-Haskell-Extension.html>` +may be used. GHC will report an error if any of the requested extensions +are not supported. + +.. _options-pragma: + +``OPTIONS_GHC`` pragma +---------------------- + +.. index:: + single: OPTIONS_GHC + single: pragma; ``OPTIONS_GHC`` + +The ``OPTIONS_GHC`` pragma is used to specify additional options that +are given to the compiler when compiling this source file. See +:ref:`source-file-options` for details. + +Previous versions of GHC accepted ``OPTIONS`` rather than +``OPTIONS_GHC``, but that is now deprecated. + +``OPTIONS_GHC`` is a file-header pragma (see :ref:`pragmas`). + +.. _include-pragma: + +``INCLUDE`` pragma +------------------ + +The ``INCLUDE`` used to be necessary for specifying header files to be +included when using the FFI and compiling via C. It is no longer +required for GHC, but is accepted (and ignored) for compatibility with +other compilers. + +.. _warning-deprecated-pragma: + +``WARNING`` and ``DEPRECATED`` pragmas +-------------------------------------- + +.. index:: + single: WARNING + single: DEPRECATED + +The ``WARNING`` pragma allows you to attach an arbitrary warning to a +particular function, class, or type. A ``DEPRECATED`` pragma lets you +specify that a particular function, class, or type is deprecated. There +are two ways of using these pragmas. + +- You can work on an entire module thus: + + :: + + module Wibble {-# DEPRECATED "Use Wobble instead" #-} where + ... + + Or: + + :: + + module Wibble {-# WARNING "This is an unstable interface." #-} where + ... + + When you compile any module that import ``Wibble``, GHC will print + the specified message. + +- You can attach a warning to a function, class, type, or data + constructor, with the following top-level declarations: + + :: + + {-# DEPRECATED f, C, T "Don't use these" #-} + {-# WARNING unsafePerformIO "This is unsafe; I hope you know what you're doing" #-} + + When you compile any module that imports and uses any of the + specified entities, GHC will print the specified message. + + You can only attach to entities declared at top level in the module + being compiled, and you can only use unqualified names in the list of + entities. A capitalised name, such as ``T`` refers to *either* the + type constructor ``T`` *or* the data constructor ``T``, or both if + both are in scope. If both are in scope, there is currently no way to + specify one without the other (c.f. fixities :ref:`infix-tycons`). + +Warnings and deprecations are not reported for (a) uses within the +defining module, (b) defining a method in a class instance, and (c) uses +in an export list. The latter reduces spurious complaints within a +library in which one module gathers together and re-exports the exports +of several others. + +You can suppress the warnings with the flag +``-fno-warn-warnings-deprecations``. + +.. _minimal-pragma: + +MINIMAL pragma +-------------- + +.. index:: + single: MINIMAL + single: pragma; MINIMAL + +The ``MINIMAL`` pragma is used to specify the minimal complete definition of +a class, i.e. specify which methods must be implemented by all +instances. If an instance does not satisfy the minimal complete +definition, then a warning is generated. This can be useful when a class +has methods with circular defaults. For example + +:: + + class Eq a where + (==) :: a -> a -> Bool + (/=) :: a -> a -> Bool + x == y = not (x /= y) + x /= y = not (x == y) + {-# MINIMAL (==) | (/=) #-} + +Without the ``MINIMAL`` pragma no warning would be generated for an instance +that implements neither method. + +The syntax for minimal complete definition is: + +:: + + mindef ::= name + | '(' mindef ')' + | mindef '|' mindef + | mindef ',' mindef + +A vertical bar denotes disjunction, i.e. one of the two sides is +required. A comma denotes conjunction, i.e. both sides are required. +Conjunction binds stronger than disjunction. + +If no ``MINIMAL`` pragma is given in the class declaration, it is just as if +a pragma ``{-# MINIMAL op1, op2, ..., opn #-}`` was given, where the +``opi`` are the methods (a) that lack a default method in the class +declaration, and (b) whose name that does not start with an underscore +(c.f. ``-fwarn-missing-methods``, :ref:`options-sanity`). + +This warning can be turned off with the flag +``-fno-warn-missing-methods``. + +.. _inline-noinline-pragma: + +INLINE and NOINLINE pragmas +--------------------------- + +These pragmas control the inlining of function definitions. + +.. _inline-pragma: + +INLINE pragma +~~~~~~~~~~~~~ + +.. index:: + single: INLINE + single: pragma; ``INLINE`` + +GHC (with ``-O``, as always) tries to inline (or "unfold") +functions/values that are "small enough," thus avoiding the call +overhead and possibly exposing other more-wonderful optimisations. GHC +has a set of heuristics, tuned over a long period of time using many +benchmarks, that decide when it is beneficial to inline a function at +its call site. The heuristics are designed to inline functions when it +appears to be beneficial to do so, but without incurring excessive code +bloat. If a function looks too big, it won't be inlined, and functions +larger than a certain size will not even have their definition exported +in the interface file. Some of the thresholds that govern these +heuristic decisions can be changed using flags, see :ref:`options-f`. + +Normally GHC will do a reasonable job of deciding by itself when it is a +good idea to inline a function. However, sometimes you might want to +override the default behaviour. For example, if you have a key function +that is important to inline because it leads to further optimisations, +but GHC judges it to be too big to inline. + +The sledgehammer you can bring to bear is the ``INLINE`` pragma, used thusly: + +:: + + key_function :: Int -> String -> (Bool, Double) + {-# INLINE key_function #-} + +The major effect of an ``INLINE`` pragma is to declare a function's +"cost" to be very low. The normal unfolding machinery will then be very +keen to inline it. However, an ``INLINE`` pragma for a function "``f``" +has a number of other effects: + +- While GHC is keen to inline the function, it does not do so blindly. + For example, if you write + + :: + + map key_function xs + + there really isn't any point in inlining ``key_function`` to get + + :: + + map (\x -> body) xs + + In general, GHC only inlines the function if there is some reason (no + matter how slight) to suppose that it is useful to do so. + +- Moreover, GHC will only inline the function if it is *fully applied*, + where "fully applied" means applied to as many arguments as appear + (syntactically) on the LHS of the function definition. For example: + + :: + + comp1 :: (b -> c) -> (a -> b) -> a -> c + {-# INLINE comp1 #-} + comp1 f g = \x -> f (g x) + + comp2 :: (b -> c) -> (a -> b) -> a -> c + {-# INLINE comp2 #-} + comp2 f g x = f (g x) + + The two functions ``comp1`` and ``comp2`` have the same semantics, + but ``comp1`` will be inlined when applied to *two* arguments, while + ``comp2`` requires *three*. This might make a big difference if you + say + + :: + + map (not `comp1` not) xs + + which will optimise better than the corresponding use of ``comp2``. + +- It is useful for GHC to optimise the definition of an INLINE function + ``f`` just like any other non-INLINE function, in case the + non-inlined version of ``f`` is ultimately called. But we don't want + to inline the *optimised* version of ``f``; a major reason for INLINE + pragmas is to expose functions in ``f``\'s RHS that have rewrite + rules, and it's no good if those functions have been optimised away. + + So *GHC guarantees to inline precisely the code that you wrote*, no + more and no less. It does this by capturing a copy of the definition + of the function to use for inlining (we call this the "inline-RHS"), + which it leaves untouched, while optimising the ordinarily RHS as + usual. For externally-visible functions the inline-RHS (not the + optimised RHS) is recorded in the interface file. + +- An INLINE function is not worker/wrappered by strictness analysis. + It's going to be inlined wholesale instead. + +GHC ensures that inlining cannot go on forever: every mutually-recursive +group is cut by one or more *loop breakers* that is never inlined (see +`Secrets of the GHC inliner, JFP 12(4) July +2002 <http://research.microsoft.com/%7Esimonpj/Papers/inlining/index.htm>`__). +GHC tries not to select a function with an INLINE pragma as a loop +breaker, but when there is no choice even an INLINE function can be +selected, in which case the INLINE pragma is ignored. For example, for a +self-recursive function, the loop breaker can only be the function +itself, so an INLINE pragma is always ignored. + +Syntactically, an ``INLINE`` pragma for a function can be put anywhere +its type signature could be put. + +``INLINE`` pragmas are a particularly good idea for the +``then``/``return`` (or ``bind``/``unit``) functions in a monad. For +example, in GHC's own ``UniqueSupply`` monad code, we have: + +:: + + {-# INLINE thenUs #-} + {-# INLINE returnUs #-} + +See also the ``NOINLINE`` (:ref:`noinline-pragma`) and ``INLINABLE`` +(:ref:`inlinable-pragma`) pragmas. + +.. _inlinable-pragma: + +INLINABLE pragma +~~~~~~~~~~~~~~~~ + +An ``{-# INLINABLE f #-}`` pragma on a function ``f`` has the following +behaviour: + +- While ``INLINE`` says "please inline me", the ``INLINABLE`` says + "feel free to inline me; use your discretion". In other words the + choice is left to GHC, which uses the same rules as for pragma-free + functions. Unlike ``INLINE``, that decision is made at the *call + site*, and will therefore be affected by the inlining threshold, + optimisation level etc. + +- Like ``INLINE``, the ``INLINABLE`` pragma retains a copy of the + original RHS for inlining purposes, and persists it in the interface + file, regardless of the size of the RHS. + +- One way to use ``INLINABLE`` is in conjunction with the special + function ``inline`` (:ref:`special-ids`). The call ``inline f`` tries + very hard to inline ``f``. To make sure that ``f`` can be inlined, it + is a good idea to mark the definition of ``f`` as ``INLINABLE``, so + that GHC guarantees to expose an unfolding regardless of how big it + is. Moreover, by annotating ``f`` as ``INLINABLE``, you ensure that + ``f``\'s original RHS is inlined, rather than whatever random + optimised version of ``f`` GHC's optimiser has produced. + +- The ``INLINABLE`` pragma also works with ``SPECIALISE``: if you mark + function ``f`` as ``INLINABLE``, then you can subsequently + ``SPECIALISE`` in another module (see :ref:`specialize-pragma`). + +- Unlike ``INLINE``, it is OK to use an ``INLINABLE`` pragma on a + recursive function. The principal reason do to so to allow later use + of ``SPECIALISE`` + +.. _noinline-pragma: + +NOINLINE pragma +~~~~~~~~~~~~~~~ + +.. index:: + single: NOINLINE + single: NOTINLINE + +The ``NOINLINE`` pragma does exactly what you'd expect: it stops the +named function from being inlined by the compiler. You shouldn't ever +need to do this, unless you're very cautious about code size. + +``NOTINLINE`` is a synonym for ``NOINLINE`` (``NOINLINE`` is specified +by Haskell 98 as the standard way to disable inlining, so it should be +used if you want your code to be portable). + +.. _conlike-pragma: + +CONLIKE modifier +~~~~~~~~~~~~~~~~ + +.. index:: + single: CONLIKE + +An INLINE or NOINLINE pragma may have a CONLIKE modifier, which affects +matching in RULEs (only). See :ref:`conlike`. + +.. _phase-control: + +Phase control +~~~~~~~~~~~~~ + +Sometimes you want to control exactly when in GHC's pipeline the INLINE +pragma is switched on. Inlining happens only during runs of the +*simplifier*. Each run of the simplifier has a different *phase number*; +the phase number decreases towards zero. If you use +``-dverbose-core2core`` you'll see the sequence of phase numbers for +successive runs of the simplifier. In an INLINE pragma you can +optionally specify a phase number, thus: + +- "``INLINE[k] f``" means: do not inline ``f`` until phase ``k``, but + from phase ``k`` onwards be very keen to inline it. + +- "``INLINE[~k] f``" means: be very keen to inline ``f`` until phase + ``k``, but from phase ``k`` onwards do not inline it. + +- "``NOINLINE[k] f``" means: do not inline ``f`` until phase ``k``, but + from phase ``k`` onwards be willing to inline it (as if there was no + pragma). + +- "``NOINLINE[~k] f``" means: be willing to inline ``f`` until phase + ``k``, but from phase ``k`` onwards do not inline it. + +The same information is summarised here: + +:: + + -- Before phase 2 Phase 2 and later + {-# INLINE [2] f #-} -- No Yes + {-# INLINE [~2] f #-} -- Yes No + {-# NOINLINE [2] f #-} -- No Maybe + {-# NOINLINE [~2] f #-} -- Maybe No + + {-# INLINE f #-} -- Yes Yes + {-# NOINLINE f #-} -- No No + +By "Maybe" we mean that the usual heuristic inlining rules apply (if the +function body is small, or it is applied to interesting-looking +arguments etc). Another way to understand the semantics is this: + +- For both INLINE and NOINLINE, the phase number says when inlining is + allowed at all. + +- The INLINE pragma has the additional effect of making the function + body look small, so that when inlining is allowed it is very likely + to happen. + +The same phase-numbering control is available for RULES +(:ref:`rewrite-rules`). + +.. _line-pragma: + +``LINE`` pragma +--------------- + +.. index:: + single: LINE; pragma + single: pragma; LINE + +This pragma is similar to C's ``#line`` pragma, and is mainly for use in +automatically generated Haskell code. It lets you specify the line +number and filename of the original code; for example + +:: + + {-# LINE 42 "Foo.vhs" #-} + +if you'd generated the current file from something called ``Foo.vhs`` +and this line corresponds to line 42 in the original. GHC will adjust +its error messages to refer to the line/file named in the ``LINE`` +pragma. + +``LINE`` pragmas generated from Template Haskell set the file and line +position for the duration of the splice and are limited to the splice. +Note that because Template Haskell splices abstract syntax, the file +positions are not automatically advanced. + +.. _rules: + +``RULES`` pragma +---------------- + +The ``RULES`` pragma lets you specify rewrite rules. It is described in +:ref:`rewrite-rules`. + +.. _specialize-pragma: + +``SPECIALIZE`` pragma +--------------------- + +.. index:: + single: SPECIALIZE pragma + single: pragma, SPECIALIZE + single: overloading, death to + +(UK spelling also accepted.) For key overloaded functions, you can +create extra versions (NB: more code space) specialised to particular +types. Thus, if you have an overloaded function: + +:: + + hammeredLookup :: Ord key => [(key, value)] -> key -> value + +If it is heavily used on lists with ``Widget`` keys, you could +specialise it as follows: + +:: + + {-# SPECIALIZE hammeredLookup :: [(Widget, value)] -> Widget -> value #-} + +- A ``SPECIALIZE`` pragma for a function can be put anywhere its type + signature could be put. Moreover, you can also ``SPECIALIZE`` an + *imported* function provided it was given an ``INLINABLE`` pragma at + its definition site (:ref:`inlinable-pragma`). + +- A ``SPECIALIZE`` has the effect of generating (a) a specialised + version of the function and (b) a rewrite rule (see + :ref:`rewrite-rules`) that rewrites a call to the un-specialised + function into a call to the specialised one. Moreover, given a + ``SPECIALIZE`` pragma for a function ``f``, GHC will automatically + create specialisations for any type-class-overloaded functions called + by ``f``, if they are in the same module as the ``SPECIALIZE`` + pragma, or if they are ``INLINABLE``; and so on, transitively. + +- You can add phase control (:ref:`phase-control`) to the RULE + generated by a ``SPECIALIZE`` pragma, just as you can if you write a + ``RULE`` directly. For example: + + :: + + {-# SPECIALIZE [0] hammeredLookup :: [(Widget, value)] -> Widget -> value #-} + + generates a specialisation rule that only fires in Phase 0 (the final + phase). If you do not specify any phase control in the ``SPECIALIZE`` + pragma, the phase control is inherited from the inline pragma (if + any) of the function. For example: + + :: + + foo :: Num a => a -> a + foo = ...blah... + {-# NOINLINE [0] foo #-} + {-# SPECIALIZE foo :: Int -> Int #-} + + The ``NOINLINE`` pragma tells GHC not to inline ``foo`` until Phase + 0; and this property is inherited by the specialisation RULE, which + will therefore only fire in Phase 0. + + The main reason for using phase control on specialisations is so that + you can write optimisation RULES that fire early in the compilation + pipeline, and only *then* specialise the calls to the function. If + specialisation is done too early, the optimisation rules might fail + to fire. + +- The type in a SPECIALIZE pragma can be any type that is less + polymorphic than the type of the original function. In concrete + terms, if the original function is ``f`` then the pragma + + :: + + {-# SPECIALIZE f :: <type> #-} + + is valid if and only if the definition + + :: + + f_spec :: <type> + f_spec = f + + is valid. Here are some examples (where we only give the type + signature for the original function, not its code): + + :: + + f :: Eq a => a -> b -> b + {-# SPECIALISE f :: Int -> b -> b #-} + + g :: (Eq a, Ix b) => a -> b -> b + {-# SPECIALISE g :: (Eq a) => a -> Int -> Int #-} + + h :: Eq a => a -> a -> a + {-# SPECIALISE h :: (Eq a) => [a] -> [a] -> [a] #-} + + The last of these examples will generate a RULE with a + somewhat-complex left-hand side (try it yourself), so it might not + fire very well. If you use this kind of specialisation, let us know + how well it works. + +.. _specialize-inline: + +``SPECIALIZE INLINE`` +~~~~~~~~~~~~~~~~~~~~~ + +A ``SPECIALIZE`` pragma can optionally be followed with a ``INLINE`` or +``NOINLINE`` pragma, optionally followed by a phase, as described in +:ref:`inline-noinline-pragma`. The ``INLINE`` pragma affects the +specialised version of the function (only), and applies even if the +function is recursive. The motivating example is this: + +:: + + -- A GADT for arrays with type-indexed representation + data Arr e where + ArrInt :: !Int -> ByteArray# -> Arr Int + ArrPair :: !Int -> Arr e1 -> Arr e2 -> Arr (e1, e2) + + (!:) :: Arr e -> Int -> e + {-# SPECIALISE INLINE (!:) :: Arr Int -> Int -> Int #-} + {-# SPECIALISE INLINE (!:) :: Arr (a, b) -> Int -> (a, b) #-} + (ArrInt _ ba) !: (I# i) = I# (indexIntArray# ba i) + (ArrPair _ a1 a2) !: i = (a1 !: i, a2 !: i) + +Here, ``(!:)`` is a recursive function that indexes arrays of type +``Arr e``. Consider a call to ``(!:)`` at type ``(Int,Int)``. The second +specialisation will fire, and the specialised function will be inlined. +It has two calls to ``(!:)``, both at type ``Int``. Both these calls +fire the first specialisation, whose body is also inlined. The result is +a type-based unrolling of the indexing function. + +You can add explicit phase control (:ref:`phase-control`) to +``SPECIALISE INLINE`` pragma, just like on an ``INLINE`` pragma; if you +do so, the same phase is used for the rewrite rule and the INLINE +control of the specialised function. + +Warning: you can make GHC diverge by using ``SPECIALISE INLINE`` on an +ordinarily-recursive function. + +``SPECIALIZE`` for imported functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Generally, you can only give a ``SPECIALIZE`` pragma for a function +defined in the same module. However if a function ``f`` is given an +``INLINABLE`` pragma at its definition site, then it can subsequently be +specialised by importing modules (see :ref:`inlinable-pragma`). For +example + +:: + + module Map( lookup, blah blah ) where + lookup :: Ord key => [(key,a)] -> key -> Maybe a + lookup = ... + {-# INLINABLE lookup #-} + + module Client where + import Map( lookup ) + + data T = T1 | T2 deriving( Eq, Ord ) + {-# SPECIALISE lookup :: [(T,a)] -> T -> Maybe a + +Here, ``lookup`` is declared ``INLINABLE``, but it cannot be specialised +for type ``T`` at its definition site, because that type does not exist +yet. Instead a client module can define ``T`` and then specialise +``lookup`` at that type. + +Moreover, every module that imports ``Client`` (or imports a module that +imports ``Client``, transitively) will "see", and make use of, the +specialised version of ``lookup``. You don't need to put a +``SPECIALIZE`` pragma in every module. + +Moreover you often don't even need the ``SPECIALIZE`` pragma in the +first place. When compiling a module ``M``, GHC's optimiser (when given the +``-O`` flag) automatically considers each top-level overloaded function declared +in ``M``, and specialises it for the different types at which it is called in +``M``. The optimiser *also* considers each *imported* ``INLINABLE`` +overloaded function, and specialises it for the different types at which +it is called in ``M``. So in our example, it would be enough for ``lookup`` +to be called at type ``T``: + +:: + + module Client where + import Map( lookup ) + + data T = T1 | T2 deriving( Eq, Ord ) + + findT1 :: [(T,a)] -> Maybe a + findT1 m = lookup m T1 -- A call of lookup at type T + +However, sometimes there are no such calls, in which case the pragma can +be useful. + +Obsolete ``SPECIALIZE`` syntax +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In earlier versions of GHC, it was possible to provide your own +specialised function for a given type: + +:: + + {-# SPECIALIZE hammeredLookup :: [(Int, value)] -> Int -> value = intLookup #-} + +This feature has been removed, as it is now subsumed by the ``RULES`` +pragma (see :ref:`rule-spec`). + +.. _specialize-instance-pragma: + +``SPECIALIZE`` instance pragma +------------------------------ + +.. index:: + single: SPECIALIZE pragma + single: overloading, death to + +Same idea, except for instance declarations. For example: + +:: + + instance (Eq a) => Eq (Foo a) where { + {-# SPECIALIZE instance Eq (Foo [(Int, Bar)]) #-} + ... usual stuff ... + } + +The pragma must occur inside the ``where`` part of the instance +declaration. + +.. _unpack-pragma: + +``UNPACK`` pragma +----------------- + +.. index:: + single: UNPACK + +The ``UNPACK`` indicates to the compiler that it should unpack the +contents of a constructor field into the constructor itself, removing a +level of indirection. For example: + +:: + + data T = T {-# UNPACK #-} !Float + {-# UNPACK #-} !Float + +will create a constructor ``T`` containing two unboxed floats. This may +not always be an optimisation: if the ``T`` constructor is scrutinised +and the floats passed to a non-strict function for example, they will +have to be reboxed (this is done automatically by the compiler). + +Unpacking constructor fields should only be used in conjunction with +``-O`` [1]_, in order to expose unfoldings to the compiler so the +reboxing can be removed as often as possible. For example: + +:: + + f :: T -> Float + f (T f1 f2) = f1 + f2 + +The compiler will avoid reboxing ``f1`` and ``f2`` by inlining ``+`` on +floats, but only when ``-O`` is on. + +Any single-constructor data is eligible for unpacking; for example + +:: + + data T = T {-# UNPACK #-} !(Int,Int) + +will store the two ``Int``\ s directly in the ``T`` constructor, by +flattening the pair. Multi-level unpacking is also supported: + +:: + + data T = T {-# UNPACK #-} !S + data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int + +will store two unboxed ``Int#``\ s directly in the ``T`` constructor. +The unpacker can see through newtypes, too. + +See also the ``-funbox-strict-fields`` flag, which essentially has the +effect of adding ``{-# UNPACK #-}`` to every strict constructor field. + +.. [1] + in fact, UNPACK has no effect without + -O + , for technical reasons (see + tick 5252 + ) + +.. _nounpack-pragma: + +``NOUNPACK`` pragma +------------------- + +.. index:: + single: NOUNPACK + +The ``NOUNPACK`` pragma indicates to the compiler that it should not +unpack the contents of a constructor field. Example: + +:: + + data T = T {-# NOUNPACK #-} !(Int,Int) + +Even with the flags ``-funbox-strict-fields`` and ``-O``, the field of +the constructor ``T`` is not unpacked. + +.. _source-pragma: + +``SOURCE`` pragma +----------------- + +.. index:: + single: SOURCE + single: pragma; SOURCE + +The ``{-# SOURCE #-}`` pragma is used only in ``import`` declarations, +to break a module loop. It is described in detail in +:ref:`mutual-recursion`. + +.. _overlap-pragma: + +``OVERLAPPING``, ``OVERLAPPABLE``, ``OVERLAPS``, and ``INCOHERENT`` pragmas +--------------------------------------------------------------------------- + +.. index:: + single: OVERLAPPING + single: pragma; OVERLAPPING + single: OVERLAPPABLE + single: pragma; OVERLAPPABLE + single: OVERLAPS + single: pragma; OVERLAPS + single: INCOHERENT + single: pragma; INCOHERENT + +The pragmas ``OVERLAPPING``, ``OVERLAPPABLE``, ``OVERLAPS``, +``INCOHERENT`` are used to specify the overlap behavior for individual +instances, as described in Section :ref:`instance-overlap`. The pragmas +are written immediately after the ``instance`` keyword, like this: + +:: + + instance {-# OVERLAPPING #-} C t where ... + +.. _rewrite-rules: + +Rewrite rules +============= + +.. index:: + single: RULES pragma + single: pragma; RULES + single: rewrite rules + +The programmer can specify rewrite rules as part of the source program +(in a pragma). Here is an example: + +:: + + {-# RULES + "map/map" forall f g xs. map f (map g xs) = map (f.g) xs + #-} + +Use the debug flag ``-ddump-simpl-stats`` to see what rules fired. If +you need more information, then ``-ddump-rule-firings`` shows you each +individual rule firing and ``-ddump-rule-rewrites`` also shows what the +code looks like before and after the rewrite. + +Syntax +------ + +From a syntactic point of view: + +- There may be zero or more rules in a ``RULES`` pragma, separated by + semicolons (which may be generated by the layout rule). + +- The layout rule applies in a pragma. Currently no new indentation + level is set, so if you put several rules in single RULES pragma and + wish to use layout to separate them, you must lay out the starting in + the same column as the enclosing definitions. + + :: + + {-# RULES + "map/map" forall f g xs. map f (map g xs) = map (f.g) xs + "map/append" forall f xs ys. map f (xs ++ ys) = map f xs ++ map f ys + #-} + + Furthermore, the closing ``#-}`` should start in a column to the + right of the opening ``{-#``. + +- Each rule has a name, enclosed in double quotes. The name itself has + no significance at all. It is only used when reporting how many times + the rule fired. + +- A rule may optionally have a phase-control number (see + :ref:`phase-control`), immediately after the name of the rule. Thus: + + :: + + {-# RULES + "map/map" [2] forall f g xs. map f (map g xs) = map (f.g) xs + #-} + + The "[2]" means that the rule is active in Phase 2 and subsequent + phases. The inverse notation "[~2]" is also accepted, meaning that + the rule is active up to, but not including, Phase 2. + + Rules support the special phase-control notation "[~]", which means + the rule is never active. This feature supports plugins (see + :ref:`compiler-plugins`), by making it possible to define a RULE that + is never run by GHC, but is nevertheless parsed, typechecked etc, so + that it is available to the plugin. + +- Each variable mentioned in a rule must either be in scope (e.g. + ``map``), or bound by the ``forall`` (e.g. ``f``, ``g``, ``xs``). The + variables bound by the ``forall`` are called the *pattern* variables. + They are separated by spaces, just like in a type ``forall``. + +- A pattern variable may optionally have a type signature. If the type + of the pattern variable is polymorphic, it *must* have a type + signature. For example, here is the ``foldr/build`` rule: + + :: + + "fold/build" forall k z (g::forall b. (a->b->b) -> b -> b) . + foldr k z (build g) = g k z + + Since ``g`` has a polymorphic type, it must have a type signature. + +- The left hand side of a rule must consist of a top-level variable + applied to arbitrary expressions. For example, this is *not* OK: + + :: + + "wrong1" forall e1 e2. case True of { True -> e1; False -> e2 } = e1 + "wrong2" forall f. f True = True + + In ``"wrong1"``, the LHS is not an application; in ``"wrong2"``, the + LHS has a pattern variable in the head. + +- A rule does not need to be in the same module as (any of) the + variables it mentions, though of course they need to be in scope. + +- All rules are implicitly exported from the module, and are therefore + in force in any module that imports the module that defined the rule, + directly or indirectly. (That is, if A imports B, which imports C, + then C's rules are in force when compiling A.) The situation is very + similar to that for instance declarations. + +- Inside a RULE "``forall``" is treated as a keyword, regardless of any + other flag settings. Furthermore, inside a RULE, the language + extension ``-XScopedTypeVariables`` is automatically enabled; see + :ref:`scoped-type-variables`. + +- Like other pragmas, RULE pragmas are always checked for scope errors, + and are typechecked. Typechecking means that the LHS and RHS of a + rule are typechecked, and must have the same type. However, rules are + only *enabled* if the ``-fenable-rewrite-rules`` flag is on (see + :ref:`rule-semantics`). + +.. _rule-semantics: + +Semantics +--------- + +From a semantic point of view: + +- Rules are enabled (that is, used during optimisation) by the + ``-fenable-rewrite-rules`` flag. This flag is implied by ``-O``, and + may be switched off (as usual) by ``-fno-enable-rewrite-rules``. (NB: + enabling ``-fenable-rewrite-rules`` without ``-O`` may not do what + you expect, though, because without ``-O`` GHC ignores all + optimisation information in interface files; see + ``-fignore-interface-pragmas``, :ref:`options-f`.) Note that + ``-fenable-rewrite-rules`` is an *optimisation* flag, and has no + effect on parsing or typechecking. + +- Rules are regarded as left-to-right rewrite rules. When GHC finds an + expression that is a substitution instance of the LHS of a rule, it + replaces the expression by the (appropriately-substituted) RHS. By "a + substitution instance" we mean that the LHS can be made equal to the + expression by substituting for the pattern variables. + +- GHC makes absolutely no attempt to verify that the LHS and RHS of a + rule have the same meaning. That is undecidable in general, and + infeasible in most interesting cases. The responsibility is entirely + the programmer's! + +- GHC makes no attempt to make sure that the rules are confluent or + terminating. For example: + + :: + + "loop" forall x y. f x y = f y x + + This rule will cause the compiler to go into an infinite loop. + +- If more than one rule matches a call, GHC will choose one arbitrarily + to apply. + +- GHC currently uses a very simple, syntactic, matching algorithm for + matching a rule LHS with an expression. It seeks a substitution which + makes the LHS and expression syntactically equal modulo alpha + conversion. The pattern (rule), but not the expression, is + eta-expanded if necessary. (Eta-expanding the expression can lead to + laziness bugs.) But not beta conversion (that's called higher-order + matching). + + Matching is carried out on GHC's intermediate language, which + includes type abstractions and applications. So a rule only matches + if the types match too. See :ref:`rule-spec` below. + +- GHC keeps trying to apply the rules as it optimises the program. For + example, consider: + + :: + + let s = map f + t = map g + in + s (t xs) + + The expression ``s (t xs)`` does not match the rule ``"map/map"``, + but GHC will substitute for ``s`` and ``t``, giving an expression + which does match. If ``s`` or ``t`` was (a) used more than once, and + (b) large or a redex, then it would not be substituted, and the rule + would not fire. + +.. _rules-inline: + +How rules interact with ``INLINE``/``NOINLINE`` pragmas +------------------------------------------------------- + +Ordinary inlining happens at the same time as rule rewriting, which may +lead to unexpected results. Consider this (artificial) example + +:: + + f x = x + g y = f y + h z = g True + + {-# RULES "f" f True = False #-} + +Since ``f``\'s right-hand side is small, it is inlined into ``g``, to +give + +:: + + g y = y + +Now ``g`` is inlined into ``h``, but ``f``\'s RULE has no chance to fire. +If instead GHC had first inlined ``g`` into ``h`` then there would have +been a better chance that ``f``\'s RULE might fire. + +The way to get predictable behaviour is to use a NOINLINE pragma, or an +INLINE[⟨phase⟩] pragma, on ``f``, to ensure that it is not inlined until +its RULEs have had a chance to fire. The warning flag +``-fwarn-inline-rule-shadowing`` (see :ref:`options-sanity`) warns about +this situation. + +.. _conlike: + +How rules interact with CONLIKE pragmas +--------------------------------------- + +GHC is very cautious about duplicating work. For example, consider + +:: + + f k z xs = let xs = build g + in ...(foldr k z xs)...sum xs... + {-# RULES "foldr/build" forall k z g. foldr k z (build g) = g k z #-} + +Since ``xs`` is used twice, GHC does not fire the foldr/build rule. +Rightly so, because it might take a lot of work to compute ``xs``, which +would be duplicated if the rule fired. + +Sometimes, however, this approach is over-cautious, and we *do* want the +rule to fire, even though doing so would duplicate redex. There is no +way that GHC can work out when this is a good idea, so we provide the +CONLIKE pragma to declare it, thus: + +:: + + {-# INLINE CONLIKE [1] f #-} + f x = blah + +``CONLIKE`` is a modifier to an ``INLINE`` or ``NOINLINE`` pragma. It specifies that +an application of ``f`` to one argument (in general, the number of arguments +to the left of the ``=`` sign) should be considered cheap enough to +duplicate, if such a duplication would make rule fire. (The name +"CONLIKE" is short for "constructor-like", because constructors +certainly have such a property.) The CONLIKE pragma is a modifier to +INLINE/NOINLINE because it really only makes sense to match ``f`` on the +LHS of a rule if you are sure that ``f`` is not going to be inlined +before the rule has a chance to fire. + +.. _rules-class-methods: + +How rules interact with class methods +------------------------------------- + +Giving a RULE for a class method is a bad idea: + +:: + + class C a where + op :: a -> a -> a + + instance C Bool where + op x y = ...rhs for op at Bool... + + {-# RULES "f" op True y = False #-} + +In this example, ``op`` is not an ordinary top-level function; it is a +class method. GHC rapidly rewrites any occurrences of +``op``\-used-at-type-Bool to a specialised function, say ``opBool``, +where + +:: + + opBool :: Bool -> Bool -> Bool + opBool x y = ..rhs for op at Bool... + +So the RULE never has a chance to fire, for just the same reasons as in +:ref:`rules-inline`. + +The solution is to define the instance-specific function yourself, with +a pragma to prevent it being inlined too early, and give a RULE for it: + +:: + + instance C Bool where + op x y = opBool + + opBool :: Bool -> Bool -> Bool + {-# NOINLINE [1] opBool #-} + opBool x y = ..rhs for op at Bool... + + {-# RULES "f" opBool True y = False #-} + +If you want a RULE that truly applies to the overloaded class method, +the only way to do it is like this: + +:: + + class C a where + op_c :: a -> a -> a + + op :: C a => a -> a -> a + {-# NOINLINE [1] op #-} + op = op_c + + {-# RULES "reassociate" op (op x y) z = op x (op y z) #-} + +Now the inlining of ``op`` is delayed until the rule has a chance to +fire. The down-side is that instance declarations must define ``op_c``, +but all other uses should go via ``op``. + +List fusion +----------- + +The RULES mechanism is used to implement fusion (deforestation) of +common list functions. If a "good consumer" consumes an intermediate +list constructed by a "good producer", the intermediate list should be +eliminated entirely. + +The following are good producers: + +- List comprehensions + +- Enumerations of ``Int``, ``Integer`` and ``Char`` (e.g. + ``['a'..'z']``). + +- Explicit lists (e.g. ``[True, False]``) + +- The cons constructor (e.g ``3:4:[]``) + +- ``++`` + +- ``map`` + +- ``take``, ``filter`` + +- ``iterate``, ``repeat`` + +- ``zip``, ``zipWith`` + +The following are good consumers: + +- List comprehensions + +- ``array`` (on its second argument) + +- ``++`` (on its first argument) + +- ``foldr`` + +- ``map`` + +- ``take``, ``filter`` + +- ``concat`` + +- ``unzip``, ``unzip2``, ``unzip3``, ``unzip4`` + +- ``zip``, ``zipWith`` (but on one argument only; if both are good + producers, ``zip`` will fuse with one but not the other) + +- ``partition`` + +- ``head`` + +- ``and``, ``or``, ``any``, ``all`` + +- ``sequence_`` + +- ``msum`` + +So, for example, the following should generate no intermediate lists: + +:: + + array (1,10) [(i,i*i) | i <- map (+ 1) [0..9]] + +This list could readily be extended; if there are Prelude functions that +you use a lot which are not included, please tell us. + +If you want to write your own good consumers or producers, look at the +Prelude definitions of the above functions to see how to do so. + +.. _rule-spec: + +Specialisation +-------------- + +Rewrite rules can be used to get the same effect as a feature present in +earlier versions of GHC. For example, suppose that: + +:: + + genericLookup :: Ord a => Table a b -> a -> b + intLookup :: Table Int b -> Int -> b + +where ``intLookup`` is an implementation of ``genericLookup`` that works +very fast for keys of type ``Int``. You might wish to tell GHC to use +``intLookup`` instead of ``genericLookup`` whenever the latter was +called with type ``Table Int b -> Int -> b``. It used to be possible to +write + +:: + + {-# SPECIALIZE genericLookup :: Table Int b -> Int -> b = intLookup #-} + +This feature is no longer in GHC, but rewrite rules let you do the same +thing: + +:: + + {-# RULES "genericLookup/Int" genericLookup = intLookup #-} + +This slightly odd-looking rule instructs GHC to replace +``genericLookup`` by ``intLookup`` *whenever the types match*. What is +more, this rule does not need to be in the same file as +``genericLookup``, unlike the ``SPECIALIZE`` pragmas which currently do +(so that they have an original definition available to specialise). + +It is *Your Responsibility* to make sure that ``intLookup`` really +behaves as a specialised version of ``genericLookup``!!! + +An example in which using ``RULES`` for specialisation will Win Big: + +:: + + toDouble :: Real a => a -> Double + toDouble = fromRational . toRational + + {-# RULES "toDouble/Int" toDouble = i2d #-} + i2d (I# i) = D# (int2Double# i) -- uses Glasgow prim-op directly + +The ``i2d`` function is virtually one machine instruction; the default +conversion—via an intermediate ``Rational``\-is obscenely expensive by +comparison. + +.. _controlling-rules: + +Controlling what's going on in rewrite rules +-------------------------------------------- + +- Use ``-ddump-rules`` to see the rules that are defined *in this + module*. This includes rules generated by the specialisation pass, + but excludes rules imported from other modules. + +- Use ``-ddump-simpl-stats`` to see what rules are being fired. If you + add ``-dppr-debug`` you get a more detailed listing. + +- Use ``-ddump-rule-firings`` or ``-ddump-rule-rewrites`` to see in + great detail what rules are being fired. If you add ``-dppr-debug`` + you get a still more detailed listing. + +- The definition of (say) ``build`` in ``GHC/Base.lhs`` looks like + this: + + :: + + build :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a] + {-# INLINE build #-} + build g = g (:) [] + + Notice the ``INLINE``! That prevents ``(:)`` from being inlined when + compiling ``PrelBase``, so that an importing module will “see” the + ``(:)``, and can match it on the LHS of a rule. ``INLINE`` prevents + any inlining happening in the RHS of the ``INLINE`` thing. I regret + the delicacy of this. + +- In ``libraries/base/GHC/Base.lhs`` look at the rules for ``map`` to + see how to write rules that will do fusion and yet give an efficient + program even if fusion doesn't happen. More rules in + ``GHC/List.lhs``. + +.. _special-ids: + +Special built-in functions +========================== + +GHC has a few built-in functions with special behaviour. In particular: + +- :base-ref:`inline <GHC-Exts.html#v%3Ainline>` + allows control over inlining on a per-call-site basis. + +- :base-ref:`lazy <GHC-Exts.html#v%3Alazy>` restrains the strictness analyser. + +- :base-ref:`oneShot <GHC-Exts.html#v%3AoneShot>` + gives a hint to the compiler about how often a function is being + called. + +.. _generic-classes: + +Generic classes +=============== + +GHC used to have an implementation of generic classes as defined in the +paper "Derivable type classes", Ralf Hinze and Simon Peyton Jones, +Haskell Workshop, Montreal Sept 2000, pp. 94-105. These have been removed +and replaced by the more general `support for generic +programming <#generic-programming>`__. + +.. _generic-programming: + +Generic programming +=================== + +Using a combination of ``-XDeriveGeneric`` (:ref:`deriving-typeable`), +``-XDefaultSignatures`` (:ref:`class-default-signatures`), and +``-XDeriveAnyClass`` (:ref:`derive-any-class`), you can easily do +datatype-generic programming using the ``GHC.Generics`` framework. This +section gives a very brief overview of how to do it. + +Generic programming support in GHC allows defining classes with methods +that do not need a user specification when instantiating: the method +body is automatically derived by GHC. This is similar to what happens +for standard classes such as ``Read`` and ``Show``, for instance, but +now for user-defined classes. + +Deriving representations +------------------------ + +The first thing we need is generic representations. The ``GHC.Generics`` +module defines a couple of primitive types that are used to represent +Haskell datatypes: + +:: + + -- | Unit: used for constructors without arguments + data U1 p = U1 + + -- | Constants, additional parameters and recursion of kind * + newtype K1 i c p = K1 { unK1 :: c } + + -- | Meta-information (constructor names, etc.) + newtype M1 i c f p = M1 { unM1 :: f p } + + -- | Sums: encode choice between constructors + infixr 5 :+: + data (:+:) f g p = L1 (f p) | R1 (g p) + + -- | Products: encode multiple arguments to constructors + infixr 6 :*: + data (:*:) f g p = f p :*: g p + +The ``Generic`` and ``Generic1`` classes mediate between user-defined +datatypes and their internal representation as a sum-of-products: + +:: + + class Generic a where + -- Encode the representation of a user datatype + type Rep a :: * -> * + -- Convert from the datatype to its representation + from :: a -> (Rep a) x + -- Convert from the representation to the datatype + to :: (Rep a) x -> a + + class Generic1 f where + type Rep1 f :: * -> * + + from1 :: f a -> Rep1 f a + to1 :: Rep1 f a -> f a + +``Generic1`` is used for functions that can only be defined over type +containers, such as ``map``. Instances of these classes can be derived +by GHC with the ``-XDeriveGeneric`` (:ref:`deriving-typeable`), and are +necessary to be able to define generic instances automatically. + +For example, a user-defined datatype of trees + +:: + data UserTree a = Node a (UserTree a) (UserTree a) | Leaf + +will get the following representation: + +:: + + instance Generic (UserTree a) where + -- Representation type + type Rep (UserTree a) = + M1 D D1UserTree ( + M1 C C1_0UserTree ( + M1 S NoSelector (K1 R a) + :*: M1 S NoSelector (K1 R (UserTree a)) + :*: M1 S NoSelector (K1 R (UserTree a))) + :+: M1 C C1_1UserTree U1) + + -- Conversion functions + from (Node x l r) = M1 (L1 (M1 (M1 (K1 x) :*: M1 (K1 l) :*: M1 (K1 r)))) + from Leaf = M1 (R1 (M1 U1)) + to (M1 (L1 (M1 (M1 (K1 x) :*: M1 (K1 l) :*: M1 (K1 r))))) = Node x l r + to (M1 (R1 (M1 U1))) = Leaf + + -- Meta-information + data D1UserTree + data C1_0UserTree + data C1_1UserTree + + instance Datatype D1UserTree where + datatypeName _ = "UserTree" + moduleName _ = "Main" + packageName _ = "main" + + instance Constructor C1_0UserTree where + conName _ = "Node" + + instance Constructor C1_1UserTree where + conName _ = "Leaf" + +This representation is generated automatically if a ``deriving Generic`` +clause is attached to the datatype. `Standalone +deriving <#stand-alone-deriving>`__ can also be used. + +Writing generic functions +------------------------- + +A generic function is defined by creating a class and giving instances +for each of the representation types of ``GHC.Generics``. As an example +we show generic serialization: + +:: + + data Bin = O | I + + class GSerialize f where + gput :: f a -> [Bin] + + instance GSerialize U1 where + gput U1 = [] + + instance (GSerialize a, GSerialize b) => GSerialize (a :*: b) where + gput (x :*: y) = gput x ++ gput y + + instance (GSerialize a, GSerialize b) => GSerialize (a :+: b) where + gput (L1 x) = O : gput x + gput (R1 x) = I : gput x + + instance (GSerialize a) => GSerialize (M1 i c a) where + gput (M1 x) = gput x + + instance (Serialize a) => GSerialize (K1 i a) where + gput (K1 x) = put x + +Typically this class will not be exported, as it only makes sense to +have instances for the representation types. + +Generic defaults +---------------- + +The only thing left to do now is to define a "front-end" class, which is +exposed to the user: + +:: + + class Serialize a where + put :: a -> [Bin] + + default put :: (Generic a, GSerialize (Rep a)) => a -> [Bit] + put = gput . from + +Here we use a `default signature <#class-default-signatures>`__ to +specify that the user does not have to provide an implementation for +``put``, as long as there is a ``Generic`` instance for the type to +instantiate. For the ``UserTree`` type, for instance, the user can just +write: + +:: + + instance (Serialize a) => Serialize (UserTree a) + +The default method for ``put`` is then used, corresponding to the +generic implementation of serialization. If you are using +``-XDeriveAnyClass``, the same instance is generated by simply attaching +a ``deriving Serialize`` clause to the ``UserTree`` datatype +declaration. For more examples of generic functions please refer to the +`generic-deriving <http://hackage.haskell.org/package/generic-deriving>`__ +package on Hackage. + +More information +---------------- + +For more details please refer to the `HaskellWiki +page <http://www.haskell.org/haskellwiki/GHC.Generics>`__ or the +original paper [Generics2010]_. + +.. [Generics2010] Jose Pedro Magalhaes, Atze Dijkstra, Johan Jeuring, and Andres Loeh. + `A generic deriving mechanism for Haskell + <http://dreixel.net/research/pdf/gdmh.pdf>`__. Proceedings of + the third ACM Haskell symposium on Haskell (Haskell'2010), pp. 37-48, + ACM, 2010. + +.. _roles: + +Roles +===== + +.. index:: + single: roles + +Using ``-XGeneralizedNewtypeDeriving`` +(:ref:`generalized-newtype-deriving`), a programmer can take existing +instances of classes and "lift" these into instances of that class for a +newtype. However, this is not always safe. For example, consider the +following: + +:: + + newtype Age = MkAge { unAge :: Int } + + type family Inspect x + type instance Inspect Age = Int + type instance Inspect Int = Bool + + class BadIdea a where + bad :: a -> Inspect a + + instance BadIdea Int where + bad = (> 0) + + deriving instance BadIdea Age -- not allowed! + +If the derived instance were allowed, what would the type of its method +``bad`` be? It would seem to be ``Age -> Inspect Age``, which is +equivalent to ``Age -> Int``, according to the type family ``Inspect``. +Yet, if we simply adapt the implementation from the instance for +``Int``, the implementation for ``bad`` produces a ``Bool``, and we have +trouble. + +The way to identify such situations is to have *roles* assigned to type +variables of datatypes, classes, and type synonyms. + +Roles as implemented in GHC are a from a simplified version of the work +described in `Generative type abstraction and type-level +computation <http://www.seas.upenn.edu/~sweirich/papers/popl163af-weirich.pdf>`__, +published at POPL 2011. + +.. _nominal-representational-and-phantom: + +Nominal, Representational, and Phantom +-------------------------------------- + +.. index:: + single: representational; role + single: nominal; role + single: phantom; role + +The goal of the roles system is to track when two types have the same +underlying representation. In the example above, ``Age`` and ``Int`` +have the same representation. But, the corresponding instances of +``BadIdea`` would *not* have the same representation, because the types +of the implementations of ``bad`` would be different. + +Suppose we have two uses of a type constructor, each applied to the same +parameters except for one difference. (For example, ``T Age Bool c`` and +``T Int Bool c`` for some type ``T``.) The role of a type parameter says +what we need to know about the two differing type arguments in order to +know that the two outer types have the same representation (in the +example, what must be true about ``Age`` and ``Int`` in order to show +that ``T Age Bool c`` has the same representation as ``T Int Bool c``). + +GHC supports three different roles for type parameters: nominal, +representational, and phantom. If a type parameter has a nominal role, +then the two types that differ must not actually differ at all: they +must be identical (after type family reduction). If a type parameter has +a representational role, then the two types must have the same +representation. (If ``T``\'s first parameter's role is representational, +then ``T Age Bool c`` and ``T Int Bool c`` would have the same +representation, because ``Age`` and ``Int`` have the same +representation.) If a type parameter has a phantom role, then we need no +further information. + +Here are some examples: + +:: + + data Simple a = MkSimple a -- a has role representational + + type family F + type instance F Int = Bool + type instance F Age = Char + + data Complex a = MkComplex (F a) -- a has role nominal + + data Phant a = MkPhant Bool -- a has role phantom + +The type ``Simple`` has its parameter at role representational, which is +generally the most common case. ``Simple Age`` would have the same +representation as ``Simple Int``. The type ``Complex``, on the other +hand, has its parameter at role nominal, because ``Simple Age`` and +``Simple Int`` are *not* the same. Lastly, ``Phant Age`` and +``Phant Bool`` have the same representation, even though ``Age`` and +``Bool`` are unrelated. + +.. _role-inference: + +Role inference +-------------- + +What role should a given type parameter should have? GHC performs role +inference to determine the correct role for every parameter. It starts +with a few base facts: ``(->)`` has two representational parameters; +``(~)`` has two nominal parameters; all type families' parameters are +nominal; and all GADT-like parameters are nominal. Then, these facts are +propagated to all places where these types are used. The default role +for datatypes and synonyms is phantom; the default role for classes is +nominal. Thus, for datatypes and synonyms, any parameters unused in the +right-hand side (or used only in other types in phantom positions) will +be phantom. Whenever a parameter is used in a representational position +(that is, used as a type argument to a constructor whose corresponding +variable is at role representational), we raise its role from phantom to +representational. Similarly, when a parameter is used in a nominal +position, its role is upgraded to nominal. We never downgrade a role +from nominal to phantom or representational, or from representational to +phantom. In this way, we infer the most-general role for each parameter. + +Classes have their roles default to nominal to promote coherence of +class instances. If a ``C Int`` were stored in a datatype, it would be +quite bad if that were somehow changed into a ``C Age`` somewhere, +especially if another ``C Age`` had been declared! + +There is one particularly tricky case that should be explained: + +:: + + data Tricky a b = MkTricky (a b) + +What should ``Tricky``'s roles be? At first blush, it would seem that +both ``a`` and ``b`` should be at role representational, since both are +used in the right-hand side and neither is involved in a type family. +However, this would be wrong, as the following example shows: + +:: + + data Nom a = MkNom (F a) -- type family F from example above + +Is ``Tricky Nom Age`` representationally equal to ``Tricky Nom Int``? +No! The former stores a ``Char`` and the latter stores a ``Bool``. The +solution to this is to require all parameters to type variables to have +role nominal. Thus, GHC would infer role representational for ``a`` but +role nominal for ``b``. + +.. _role-annotations: + +Role annotations -XRoleAnnotations +---------------------------------- + +Sometimes the programmer wants to constrain the inference process. For +example, the base library contains the following definition: + +:: + + data Ptr a = Ptr Addr# + +The idea is that ``a`` should really be a representational parameter, +but role inference assigns it to phantom. This makes some level of +sense: a pointer to an ``Int`` really is representationally the same as +a pointer to a ``Bool``. But, that's not at all how we want to use +``Ptr``\ s! So, we want to be able to say + +:: + + type role Ptr representational + data Ptr a = Ptr Addr# + +The ``type role`` (enabled with ``-XRoleAnnotations``) declaration +forces the parameter ``a`` to be at role representational, not role +phantom. GHC then checks the user-supplied roles to make sure they don't +break any promises. It would be bad, for example, if the user could make +``BadIdea``\'s role be representational. + +As another example, we can consider a type ``Set a`` that represents a +set of data, ordered according to ``a``\'s ``Ord`` instance. While it +would generally be type-safe to consider ``a`` to be at role +representational, it is possible that a ``newtype`` and its base type +have *different* orderings encoded in their respective ``Ord`` +instances. This would lead to misbehavior at runtime. So, the author of +the ``Set`` datatype would like its parameter to be at role nominal. +This would be done with a declaration + +:: + + type role Set nominal + +Role annotations can also be used should a programmer wish to write a +class with a representational (or phantom) role. However, as a class +with non-nominal roles can quickly lead to class instance incoherence, +it is necessary to also specify ``-XIncoherentInstances`` to allow +non-nominal roles for classes. + +The other place where role annotations may be necessary are in +``hs-boot`` files (:ref:`mutual-recursion`), where the right-hand sides +of definitions can be omitted. As usual, the types/classes declared in +an ``hs-boot`` file must match up with the definitions in the ``hs`` +file, including down to the roles. The default role for datatypes is +representational in ``hs-boot`` files, corresponding to the common use +case. + +Role annotations are allowed on data, newtype, and class declarations. A +role annotation declaration starts with ``type role`` and is followed by +one role listing for each parameter of the type. (This parameter count +includes parameters implicitly specified by a kind signature in a +GADT-style data or newtype declaration.) Each role listing is a role +(``nominal``, ``representational``, or ``phantom``) or a ``_``. Using a +``_`` says that GHC should infer that role. The role annotation may go +anywhere in the same module as the datatype or class definition (much +like a value-level type signature). Here are some examples: + +:: + + type role T1 _ phantom + data T1 a b = MkT1 a -- b is not used; annotation is fine but unnecessary + + type role T2 _ phantom + data T2 a b = MkT2 b -- ERROR: b is used and cannot be phantom + + type role T3 _ nominal + data T3 a b = MkT3 a -- OK: nominal is higher than necessary, but safe + + type role T4 nominal + data T4 a = MkT4 (a Int) -- OK, but nominal is higher than necessary + + type role C representational _ -- OK, with -XIncoherentInstances + class C a b where ... -- OK, b will get a nominal role + + type role X nominal + type X a = ... -- ERROR: role annotations not allowed for type synonyms + +.. _strict-haskell: + +Strict Haskell +============== + +.. index:: + single: strict haskell + +High-performance Haskell code (e.g. numeric code) can sometimes be +littered with bang patterns, making it harder to read. The reason is +that lazy evaluation isn't the right default in this particular code but +the programmer has no way to say that except by repeatedly adding bang +patterns. Below ``-XStrictData`` is detailed that allows the programmer +to switch the default behavior on a per-module basis. + +.. _strict-data: + +Strict-by-default data types +---------------------------- + +Informally the ``StrictData`` language extension switches data type +declarations to be strict by default allowing fields to be lazy by +adding a ``~`` in front of the field. + +When the user writes + +:: + + data T = C a + data T' = C' ~a + +we interpret it as if she had written + +:: + + data T = C !a + data T' = C' a + +The extension only affects definitions in this module. diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml deleted file mode 100644 index 7554c4d064..0000000000 --- a/docs/users_guide/glasgow_exts.xml +++ /dev/null @@ -1,13867 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<para> -<indexterm><primary>language, GHC</primary></indexterm> -<indexterm><primary>extensions, GHC</primary></indexterm> -As with all known Haskell systems, GHC implements some extensions to -the language. They can all be enabled or disabled by command line flags -or language pragmas. By default GHC understands the most recent Haskell -version it supports, plus a handful of extensions. -</para> - -<para> -Some of the Glasgow extensions serve to give you access to the -underlying facilities with which we implement Haskell. Thus, you can -get at the Raw Iron, if you are willing to write some non-portable -code at a more primitive level. You need not be “stuck” -on performance because of the implementation costs of Haskell's -“high-level” features—you can always code -“under” them. In an extreme case, you can write all your -time-critical code in C, and then just glue it together with Haskell! -</para> - -<para> -Before you get too carried away working at the lowest level (e.g., -sloshing <literal>MutableByteArray#</literal>s around your -program), you may wish to check if there are libraries that provide a -“Haskellised veneer” over the features you want. The -separate <ulink url="../libraries/index.html">libraries -documentation</ulink> describes all the libraries that come with GHC. -</para> - -<!-- LANGUAGE OPTIONS --> - <sect1 id="options-language"> - <title>Language options</title> - - <indexterm><primary>language</primary><secondary>option</secondary> - </indexterm> - <indexterm><primary>options</primary><secondary>language</secondary> - </indexterm> - <indexterm><primary>extensions</primary><secondary>options controlling</secondary> - </indexterm> - - <para>The language option flags control what variation of the language are - permitted.</para> - - <para>Language options can be controlled in two ways: - <itemizedlist> - <listitem><para>Every language option can switched on by a command-line flag "<option>-X...</option>" - (e.g. <option>-XTemplateHaskell</option>), and switched off by the flag "<option>-XNo...</option>"; - (e.g. <option>-XNoTemplateHaskell</option>).</para></listitem> - <listitem><para> - Language options recognised by Cabal can also be enabled using the <literal>LANGUAGE</literal> pragma, - thus <literal>{-# LANGUAGE TemplateHaskell #-}</literal> (see <xref linkend="language-pragma"/>). </para> - </listitem> - </itemizedlist></para> - - <para>The flag <option>-fglasgow-exts</option> - <indexterm><primary><option>-fglasgow-exts</option></primary></indexterm> - is equivalent to enabling the following extensions: - &what_glasgow_exts_does; - Enabling these options is the <emphasis>only</emphasis> - effect of <option>-fglasgow-exts</option>. - We are trying to move away from this portmanteau flag, - and towards enabling features individually.</para> - - </sect1> - -<!-- UNBOXED TYPES AND PRIMITIVE OPERATIONS --> -<sect1 id="primitives"> - <title>Unboxed types and primitive operations</title> - -<para>GHC is built on a raft of primitive data types and operations; -"primitive" in the sense that they cannot be defined in Haskell itself. -While you really can use this stuff to write fast code, -we generally find it a lot less painful, and more satisfying in the -long run, to use higher-level language features and libraries. With -any luck, the code you write will be optimised to the efficient -unboxed version in any case. And if it isn't, we'd like to know -about it.</para> - -<para>All these primitive data types and operations are exported by the -library <literal>GHC.Prim</literal>, for which there is -<ulink url="&libraryGhcPrimLocation;/GHC-Prim.html">detailed online documentation</ulink>. -(This documentation is generated from the file <filename>compiler/prelude/primops.txt.pp</filename>.) -</para> - -<para> -If you want to mention any of the primitive data types or operations in your -program, you must first import <literal>GHC.Prim</literal> to bring them -into scope. Many of them have names ending in "#", and to mention such -names you need the <option>-XMagicHash</option> extension (<xref linkend="magic-hash"/>). -</para> - -<para>The primops make extensive use of <link linkend="glasgow-unboxed">unboxed types</link> -and <link linkend="unboxed-tuples">unboxed tuples</link>, which -we briefly summarise here. </para> - -<sect2 id="glasgow-unboxed"> -<title>Unboxed types</title> - -<para> -<indexterm><primary>Unboxed types (Glasgow extension)</primary></indexterm> -</para> - -<para>Most types in GHC are <firstterm>boxed</firstterm>, which means -that values of that type are represented by a pointer to a heap -object. The representation of a Haskell <literal>Int</literal>, for -example, is a two-word heap object. An <firstterm>unboxed</firstterm> -type, however, is represented by the value itself, no pointers or heap -allocation are involved. -</para> - -<para> -Unboxed types correspond to the “raw machine” types you -would use in C: <literal>Int#</literal> (long int), -<literal>Double#</literal> (double), <literal>Addr#</literal> -(void *), etc. The <emphasis>primitive operations</emphasis> -(PrimOps) on these types are what you might expect; e.g., -<literal>(+#)</literal> is addition on -<literal>Int#</literal>s, and is the machine-addition that we all -know and love—usually one instruction. -</para> - -<para> -Primitive (unboxed) types cannot be defined in Haskell, and are -therefore built into the language and compiler. Primitive types are -always unlifted; that is, a value of a primitive type cannot be -bottom. We use the convention (but it is only a convention) -that primitive types, values, and -operations have a <literal>#</literal> suffix (see <xref linkend="magic-hash"/>). -For some primitive types we have special syntax for literals, also -described in the <link linkend="magic-hash">same section</link>. -</para> - -<para> -Primitive values are often represented by a simple bit-pattern, such -as <literal>Int#</literal>, <literal>Float#</literal>, -<literal>Double#</literal>. But this is not necessarily the case: -a primitive value might be represented by a pointer to a -heap-allocated object. Examples include -<literal>Array#</literal>, the type of primitive arrays. A -primitive array is heap-allocated because it is too big a value to fit -in a register, and would be too expensive to copy around; in a sense, -it is accidental that it is represented by a pointer. If a pointer -represents a primitive value, then it really does point to that value: -no unevaluated thunks, no indirections…nothing can be at the -other end of the pointer than the primitive value. -A numerically-intensive program using unboxed types can -go a <emphasis>lot</emphasis> faster than its “standard” -counterpart—we saw a threefold speedup on one example. -</para> - -<para> -There are some restrictions on the use of primitive types: -<itemizedlist> -<listitem><para>The main restriction -is that you can't pass a primitive value to a polymorphic -function or store one in a polymorphic data type. This rules out -things like <literal>[Int#]</literal> (i.e. lists of primitive -integers). The reason for this restriction is that polymorphic -arguments and constructor fields are assumed to be pointers: if an -unboxed integer is stored in one of these, the garbage collector would -attempt to follow it, leading to unpredictable space leaks. Or a -<function>seq</function> operation on the polymorphic component may -attempt to dereference the pointer, with disastrous results. Even -worse, the unboxed value might be larger than a pointer -(<literal>Double#</literal> for instance). -</para> -</listitem> -<listitem><para> You cannot define a newtype whose representation type -(the argument type of the data constructor) is an unboxed type. Thus, -this is illegal: -<programlisting> - newtype A = MkA Int# -</programlisting> -</para></listitem> -<listitem><para> You cannot bind a variable with an unboxed type -in a <emphasis>top-level</emphasis> binding. -</para></listitem> -<listitem><para> You cannot bind a variable with an unboxed type -in a <emphasis>recursive</emphasis> binding. -</para></listitem> -<listitem><para> You may bind unboxed variables in a (non-recursive, -non-top-level) pattern binding, but you must make any such pattern-match -strict. For example, rather than: -<programlisting> - data Foo = Foo Int Int# - - f x = let (Foo a b, w) = ..rhs.. in ..body.. -</programlisting> -you must write: -<programlisting> - data Foo = Foo Int Int# - - f x = let !(Foo a b, w) = ..rhs.. in ..body.. -</programlisting> -since <literal>b</literal> has type <literal>Int#</literal>. -</para> -</listitem> -</itemizedlist> -</para> - -</sect2> - -<sect2 id="unboxed-tuples"> -<title>Unboxed tuples</title> - -<para> -Unboxed tuples aren't really exported by <literal>GHC.Exts</literal>; -they are a syntactic extension enabled by the language flag <option>-XUnboxedTuples</option>. An -unboxed tuple looks like this: -</para> - -<para> - -<programlisting> -(# e_1, ..., e_n #) -</programlisting> - -</para> - -<para> -where <literal>e_1..e_n</literal> are expressions of any -type (primitive or non-primitive). The type of an unboxed tuple looks -the same. -</para> - -<para> -Note that when unboxed tuples are enabled, -<literal>(#</literal> is a single lexeme, so for example when using -operators like <literal>#</literal> and <literal>#-</literal> you need -to write <literal>( # )</literal> and <literal>( #- )</literal> rather than -<literal>(#)</literal> and <literal>(#-)</literal>. -</para> - -<para> -Unboxed tuples are used for functions that need to return multiple -values, but they avoid the heap allocation normally associated with -using fully-fledged tuples. When an unboxed tuple is returned, the -components are put directly into registers or on the stack; the -unboxed tuple itself does not have a composite representation. Many -of the primitive operations listed in <literal>primops.txt.pp</literal> return unboxed -tuples. -In particular, the <literal>IO</literal> and <literal>ST</literal> monads use unboxed -tuples to avoid unnecessary allocation during sequences of operations. -</para> - -<para> -There are some restrictions on the use of unboxed tuples: -<itemizedlist> - -<listitem> -<para> -Values of unboxed tuple types are subject to the same restrictions as -other unboxed types; i.e. they may not be stored in polymorphic data -structures or passed to polymorphic functions. -</para> -</listitem> - -<listitem> -<para> -The typical use of unboxed tuples is simply to return multiple values, -binding those multiple results with a <literal>case</literal> expression, thus: -<programlisting> - f x y = (# x+1, y-1 #) - g x = case f x x of { (# a, b #) -> a + b } -</programlisting> -You can have an unboxed tuple in a pattern binding, thus -<programlisting> - f x = let (# p,q #) = h x in ..body.. -</programlisting> -If the types of <literal>p</literal> and <literal>q</literal> are not unboxed, -the resulting binding is lazy like any other Haskell pattern binding. The -above example desugars like this: -<programlisting> - f x = let t = case h x of { (# p,q #) -> (p,q) } - p = fst t - q = snd t - in ..body.. -</programlisting> -Indeed, the bindings can even be recursive. -</para> -</listitem> -</itemizedlist> - -</para> - -</sect2> -</sect1> - - -<!-- ====================== SYNTACTIC EXTENSIONS ======================= --> - -<sect1 id="syntax-extns"> -<title>Syntactic extensions</title> - - <sect2 id="unicode-syntax"> - <title>Unicode syntax</title> - <para>The language - extension <option>-XUnicodeSyntax</option><indexterm><primary><option>-XUnicodeSyntax</option></primary></indexterm> - enables Unicode characters to be used to stand for certain ASCII - character sequences. The following alternatives are provided:</para> - - <informaltable> - <tgroup cols="2" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>ASCII</entry> - <entry>Unicode alternative</entry> - <entry>Code point</entry> - <entry>Name</entry> - </row> - </thead> - -<!-- - to find the DocBook entities for these characters, find - the Unicode code point (e.g. 0x2237), and grep for it in - /usr/share/sgml/docbook/xml-dtd-*/ent/* (or equivalent on - your system. Some of these Unicode code points don't have - equivalent DocBook entities. - --> - - <tbody> - <row> - <entry><literal>::</literal></entry> - <entry>∷</entry> - <entry>0x2237</entry> - <entry>PROPORTION</entry> - </row> - </tbody> - <tbody> - <row> - <entry><literal>=></literal></entry> - <entry>⇒</entry> - <entry>0x21D2</entry> - <entry>RIGHTWARDS DOUBLE ARROW</entry> - </row> - </tbody> - <tbody> - <row> - <entry><literal>forall</literal></entry> - <entry>∀</entry> - <entry>0x2200</entry> - <entry>FOR ALL</entry> - </row> - </tbody> - <tbody> - <row> - <entry><literal>-></literal></entry> - <entry>→</entry> - <entry>0x2192</entry> - <entry>RIGHTWARDS ARROW</entry> - </row> - </tbody> - <tbody> - <row> - <entry><literal><-</literal></entry> - <entry>←</entry> - <entry>0x2190</entry> - <entry>LEFTWARDS ARROW</entry> - </row> - </tbody> - - <tbody> - <row> - <entry>-<</entry> - <entry>⤙</entry> - <entry>0x2919</entry> - <entry>LEFTWARDS ARROW-TAIL</entry> - </row> - </tbody> - - <tbody> - <row> - <entry>>-</entry> - <entry>⤚</entry> - <entry>0x291A</entry> - <entry>RIGHTWARDS ARROW-TAIL</entry> - </row> - </tbody> - - <tbody> - <row> - <entry>-<<</entry> - <entry>⤛</entry> - <entry>0x291B</entry> - <entry>LEFTWARDS DOUBLE ARROW-TAIL</entry> - </row> - </tbody> - - <tbody> - <row> - <entry>>>-</entry> - <entry>⤜</entry> - <entry>0x291C</entry> - <entry>RIGHTWARDS DOUBLE ARROW-TAIL</entry> - </row> - </tbody> - - <tbody> - <row> - <entry>*</entry> - <entry>★</entry> - <entry>0x2605</entry> - <entry>BLACK STAR</entry> - </row> - </tbody> - - </tgroup> - </informaltable> - </sect2> - - <sect2 id="magic-hash"> - <title>The magic hash</title> - <para>The language extension <option>-XMagicHash</option> allows "#" as a - postfix modifier to identifiers. Thus, "x#" is a valid variable, and "T#" is - a valid type constructor or data constructor.</para> - - <para>The hash sign does not change semantics at all. We tend to use variable - names ending in "#" for unboxed values or types (e.g. <literal>Int#</literal>), - but there is no requirement to do so; they are just plain ordinary variables. - Nor does the <option>-XMagicHash</option> extension bring anything into scope. - For example, to bring <literal>Int#</literal> into scope you must - import <literal>GHC.Prim</literal> (see <xref linkend="primitives"/>); - the <option>-XMagicHash</option> extension - then allows you to <emphasis>refer</emphasis> to the <literal>Int#</literal> - that is now in scope. Note that with this option, the meaning of <literal>x#y = 0</literal> - is changed: it defines a function <literal>x#</literal> taking a single argument <literal>y</literal>; - to define the operator <literal>#</literal>, put a space: <literal>x # y = 0</literal>. - -</para> - <para> The <option>-XMagicHash</option> also enables some new forms of literals (see <xref linkend="glasgow-unboxed"/>): - <itemizedlist> - <listitem><para> <literal>'x'#</literal> has type <literal>Char#</literal></para> </listitem> - <listitem><para> <literal>"foo"#</literal> has type <literal>Addr#</literal></para> </listitem> - <listitem><para> <literal>3#</literal> has type <literal>Int#</literal>. In general, - any Haskell integer lexeme followed by a <literal>#</literal> is an <literal>Int#</literal> literal, e.g. - <literal>-0x3A#</literal> as well as <literal>32#</literal>.</para></listitem> - <listitem><para> <literal>3##</literal> has type <literal>Word#</literal>. In general, - any non-negative Haskell integer lexeme followed by <literal>##</literal> - is a <literal>Word#</literal>. </para> </listitem> - <listitem><para> <literal>3.2#</literal> has type <literal>Float#</literal>.</para> </listitem> - <listitem><para> <literal>3.2##</literal> has type <literal>Double#</literal></para> </listitem> - </itemizedlist> - </para> - </sect2> - - <sect2 id="negative-literals"> - <title>Negative literals</title> - <para> - The literal <literal>-123</literal> is, according to - Haskell98 and Haskell 2010, desugared as - <literal>negate (fromInteger 123)</literal>. - The language extension <option>-XNegativeLiterals</option> - means that it is instead desugared as - <literal>fromInteger (-123)</literal>. - </para> - - <para> - This can make a difference when the positive and negative range of - a numeric data type don't match up. For example, - in 8-bit arithmetic -128 is representable, but +128 is not. - So <literal>negate (fromInteger 128)</literal> will elicit an - unexpected integer-literal-overflow message. - </para> - </sect2> - - <sect2 id="num-decimals"> - <title>Fractional looking integer literals</title> - <para> - Haskell 2010 and Haskell 98 define floating literals with - the syntax <literal>1.2e6</literal>. These literals have the - type <literal>Fractional a => a</literal>. - </para> - - <para> - The language extension <option>-XNumDecimals</option> allows - you to also use the floating literal syntax for instances of - <literal>Integral</literal>, and have values like - <literal>(1.2e6 :: Num a => a)</literal> - </para> - </sect2> - - <sect2 id="binary-literals"> - <title>Binary integer literals</title> - <para> - Haskell 2010 and Haskell 98 allows for integer literals to - be given in decimal, octal (prefixed by - <literal>0o</literal> or <literal>0O</literal>), or - hexadecimal notation (prefixed by <literal>0x</literal> or - <literal>0X</literal>). - </para> - - <para> - The language extension <option>-XBinaryLiterals</option> - adds support for expressing integer literals in binary - notation with the prefix <literal>0b</literal> or - <literal>0B</literal>. For instance, the binary integer - literal <literal>0b11001001</literal> will be desugared into - <literal>fromInteger 201</literal> when - <option>-XBinaryLiterals</option> is enabled. - </para> - </sect2> - - <!-- ====================== HIERARCHICAL MODULES ======================= --> - - - <sect2 id="hierarchical-modules"> - <title>Hierarchical Modules</title> - - <para>GHC supports a small extension to the syntax of module - names: a module name is allowed to contain a dot - <literal>‘.’</literal>. This is also known as the - “hierarchical module namespace” extension, because - it extends the normally flat Haskell module namespace into a - more flexible hierarchy of modules.</para> - - <para>This extension has very little impact on the language - itself; modules names are <emphasis>always</emphasis> fully - qualified, so you can just think of the fully qualified module - name as <quote>the module name</quote>. In particular, this - means that the full module name must be given after the - <literal>module</literal> keyword at the beginning of the - module; for example, the module <literal>A.B.C</literal> must - begin</para> - -<programlisting>module A.B.C</programlisting> - - - <para>It is a common strategy to use the <literal>as</literal> - keyword to save some typing when using qualified names with - hierarchical modules. For example:</para> - -<programlisting> -import qualified Control.Monad.ST.Strict as ST -</programlisting> - - <para>For details on how GHC searches for source and interface - files in the presence of hierarchical modules, see <xref - linkend="search-path"/>.</para> - - <para>GHC comes with a large collection of libraries arranged - hierarchically; see the accompanying <ulink - url="../libraries/index.html">library - documentation</ulink>. More libraries to install are available - from <ulink - url="http://hackage.haskell.org/packages/hackage.html">HackageDB</ulink>.</para> - </sect2> - - <!-- ====================== PATTERN GUARDS ======================= --> - -<sect2 id="pattern-guards"> -<title>Pattern guards</title> - -<para> -<indexterm><primary>Pattern guards (Glasgow extension)</primary></indexterm> -The discussion that follows is an abbreviated version of Simon Peyton Jones's original <ulink url="http://research.microsoft.com/~simonpj/Haskell/guards.html">proposal</ulink>. (Note that the proposal was written before pattern guards were implemented, so refers to them as unimplemented.) -</para> - -<para> -Suppose we have an abstract data type of finite maps, with a -lookup operation: - -<programlisting> -lookup :: FiniteMap -> Int -> Maybe Int -</programlisting> - -The lookup returns <function>Nothing</function> if the supplied key is not in the domain of the mapping, and <function>(Just v)</function> otherwise, -where <varname>v</varname> is the value that the key maps to. Now consider the following definition: -</para> - -<programlisting> -clunky env var1 var2 | ok1 && ok2 = val1 + val2 -| otherwise = var1 + var2 -where - m1 = lookup env var1 - m2 = lookup env var2 - ok1 = maybeToBool m1 - ok2 = maybeToBool m2 - val1 = expectJust m1 - val2 = expectJust m2 -</programlisting> - -<para> -The auxiliary functions are -</para> - -<programlisting> -maybeToBool :: Maybe a -> Bool -maybeToBool (Just x) = True -maybeToBool Nothing = False - -expectJust :: Maybe a -> a -expectJust (Just x) = x -expectJust Nothing = error "Unexpected Nothing" -</programlisting> - -<para> -What is <function>clunky</function> doing? The guard <literal>ok1 && -ok2</literal> checks that both lookups succeed, using -<function>maybeToBool</function> to convert the <function>Maybe</function> -types to booleans. The (lazily evaluated) <function>expectJust</function> -calls extract the values from the results of the lookups, and binds the -returned values to <varname>val1</varname> and <varname>val2</varname> -respectively. If either lookup fails, then clunky takes the -<literal>otherwise</literal> case and returns the sum of its arguments. -</para> - -<para> -This is certainly legal Haskell, but it is a tremendously verbose and -un-obvious way to achieve the desired effect. Arguably, a more direct way -to write clunky would be to use case expressions: -</para> - -<programlisting> -clunky env var1 var2 = case lookup env var1 of - Nothing -> fail - Just val1 -> case lookup env var2 of - Nothing -> fail - Just val2 -> val1 + val2 -where - fail = var1 + var2 -</programlisting> - -<para> -This is a bit shorter, but hardly better. Of course, we can rewrite any set -of pattern-matching, guarded equations as case expressions; that is -precisely what the compiler does when compiling equations! The reason that -Haskell provides guarded equations is because they allow us to write down -the cases we want to consider, one at a time, independently of each other. -This structure is hidden in the case version. Two of the right-hand sides -are really the same (<function>fail</function>), and the whole expression -tends to become more and more indented. -</para> - -<para> -Here is how I would write clunky: -</para> - -<programlisting> -clunky env var1 var2 - | Just val1 <- lookup env var1 - , Just val2 <- lookup env var2 - = val1 + val2 -...other equations for clunky... -</programlisting> - -<para> -The semantics should be clear enough. The qualifiers are matched in order. -For a <literal><-</literal> qualifier, which I call a pattern guard, the -right hand side is evaluated and matched against the pattern on the left. -If the match fails then the whole guard fails and the next equation is -tried. If it succeeds, then the appropriate binding takes place, and the -next qualifier is matched, in the augmented environment. Unlike list -comprehensions, however, the type of the expression to the right of the -<literal><-</literal> is the same as the type of the pattern to its -left. The bindings introduced by pattern guards scope over all the -remaining guard qualifiers, and over the right hand side of the equation. -</para> - -<para> -Just as with list comprehensions, boolean expressions can be freely mixed -with among the pattern guards. For example: -</para> - -<programlisting> -f x | [y] <- x - , y > 3 - , Just z <- h y - = ... -</programlisting> - -<para> -Haskell's current guards therefore emerge as a special case, in which the -qualifier list has just one element, a boolean expression. -</para> -</sect2> - - <!-- ===================== View patterns =================== --> - -<sect2 id="view-patterns"> -<title>View patterns -</title> - -<para> -View patterns are enabled by the flag <literal>-XViewPatterns</literal>. -More information and examples of view patterns can be found on the -<ulink url="http://ghc.haskell.org/trac/ghc/wiki/ViewPatterns">Wiki -page</ulink>. -</para> - -<para> -View patterns are somewhat like pattern guards that can be nested inside -of other patterns. They are a convenient way of pattern-matching -against values of abstract types. For example, in a programming language -implementation, we might represent the syntax of the types of the -language as follows: - -<programlisting> -type Typ - -data TypView = Unit - | Arrow Typ Typ - -view :: Typ -> TypView - --- additional operations for constructing Typ's ... -</programlisting> - -The representation of Typ is held abstract, permitting implementations -to use a fancy representation (e.g., hash-consing to manage sharing). - -Without view patterns, using this signature a little inconvenient: -<programlisting> -size :: Typ -> Integer -size t = case view t of - Unit -> 1 - Arrow t1 t2 -> size t1 + size t2 -</programlisting> - -It is necessary to iterate the case, rather than using an equational -function definition. And the situation is even worse when the matching -against <literal>t</literal> is buried deep inside another pattern. -</para> - -<para> -View patterns permit calling the view function inside the pattern and -matching against the result: -<programlisting> -size (view -> Unit) = 1 -size (view -> Arrow t1 t2) = size t1 + size t2 -</programlisting> - -That is, we add a new form of pattern, written -<replaceable>expression</replaceable> <literal>-></literal> -<replaceable>pattern</replaceable> that means "apply the expression to -whatever we're trying to match against, and then match the result of -that application against the pattern". The expression can be any Haskell -expression of function type, and view patterns can be used wherever -patterns are used. -</para> - -<para> -The semantics of a pattern <literal>(</literal> -<replaceable>exp</replaceable> <literal>-></literal> -<replaceable>pat</replaceable> <literal>)</literal> are as follows: - -<itemizedlist> - -<listitem> Scoping: - -<para>The variables bound by the view pattern are the variables bound by -<replaceable>pat</replaceable>. -</para> - -<para> -Any variables in <replaceable>exp</replaceable> are bound occurrences, -but variables bound "to the left" in a pattern are in scope. This -feature permits, for example, one argument to a function to be used in -the view of another argument. For example, the function -<literal>clunky</literal> from <xref linkend="pattern-guards" /> can be -written using view patterns as follows: - -<programlisting> -clunky env (lookup env -> Just val1) (lookup env -> Just val2) = val1 + val2 -...other equations for clunky... -</programlisting> -</para> - -<para> -More precisely, the scoping rules are: -<itemizedlist> -<listitem> -<para> -In a single pattern, variables bound by patterns to the left of a view -pattern expression are in scope. For example: -<programlisting> -example :: Maybe ((String -> Integer,Integer), String) -> Bool -example Just ((f,_), f -> 4) = True -</programlisting> - -Additionally, in function definitions, variables bound by matching earlier curried -arguments may be used in view pattern expressions in later arguments: -<programlisting> -example :: (String -> Integer) -> String -> Bool -example f (f -> 4) = True -</programlisting> -That is, the scoping is the same as it would be if the curried arguments -were collected into a tuple. -</para> -</listitem> - -<listitem> -<para> -In mutually recursive bindings, such as <literal>let</literal>, -<literal>where</literal>, or the top level, view patterns in one -declaration may not mention variables bound by other declarations. That -is, each declaration must be self-contained. For example, the following -program is not allowed: -<programlisting> -let {(x -> y) = e1 ; - (y -> x) = e2 } in x -</programlisting> - -(For some amplification on this design choice see -<ulink url="http://ghc.haskell.org/trac/ghc/ticket/4061">Trac #4061</ulink>.) - -</para> -</listitem> -</itemizedlist> - -</para> -</listitem> - -<listitem><para> Typing: If <replaceable>exp</replaceable> has type -<replaceable>T1</replaceable> <literal>-></literal> -<replaceable>T2</replaceable> and <replaceable>pat</replaceable> matches -a <replaceable>T2</replaceable>, then the whole view pattern matches a -<replaceable>T1</replaceable>. -</para></listitem> - -<listitem><para> Matching: To the equations in Section 3.17.3 of the -<ulink url="http://www.haskell.org/onlinereport/">Haskell 98 -Report</ulink>, add the following: -<programlisting> -case v of { (e -> p) -> e1 ; _ -> e2 } - = -case (e v) of { p -> e1 ; _ -> e2 } -</programlisting> -That is, to match a variable <replaceable>v</replaceable> against a pattern -<literal>(</literal> <replaceable>exp</replaceable> -<literal>-></literal> <replaceable>pat</replaceable> -<literal>)</literal>, evaluate <literal>(</literal> -<replaceable>exp</replaceable> <replaceable> v</replaceable> -<literal>)</literal> and match the result against -<replaceable>pat</replaceable>. -</para></listitem> - -<listitem><para> Efficiency: When the same view function is applied in -multiple branches of a function definition or a case expression (e.g., -in <literal>size</literal> above), GHC makes an attempt to collect these -applications into a single nested case expression, so that the view -function is only applied once. Pattern compilation in GHC follows the -matrix algorithm described in Chapter 4 of <ulink -url="http://research.microsoft.com/~simonpj/Papers/slpj-book-1987/">The -Implementation of Functional Programming Languages</ulink>. When the -top rows of the first column of a matrix are all view patterns with the -"same" expression, these patterns are transformed into a single nested -case. This includes, for example, adjacent view patterns that line up -in a tuple, as in -<programlisting> -f ((view -> A, p1), p2) = e1 -f ((view -> B, p3), p4) = e2 -</programlisting> -</para> - -<para> The current notion of when two view pattern expressions are "the -same" is very restricted: it is not even full syntactic equality. -However, it does include variables, literals, applications, and tuples; -e.g., two instances of <literal>view ("hi", "there")</literal> will be -collected. However, the current implementation does not compare up to -alpha-equivalence, so two instances of <literal>(x, view x -> -y)</literal> will not be coalesced. -</para> - -</listitem> - -</itemizedlist> -</para> - -</sect2> - - <!-- ===================== Pattern synonyms =================== --> - -<sect2 id="pattern-synonyms"> -<title>Pattern synonyms -</title> - -<para> -Pattern synonyms are enabled by the flag -<literal>-XPatternSynonyms</literal>, which is required for defining -them, but <emphasis>not</emphasis> for using them. More information -and examples of view patterns can be found on the <ulink -url="http://ghc.haskell.org/trac/ghc/wiki/PatternSynonyms">Wiki -page</ulink>. -</para> - -<para> -Pattern synonyms enable giving names to parametrized pattern -schemes. They can also be thought of as abstract constructors that -don't have a bearing on data representation. For example, in a -programming language implementation, we might represent types of the -language as follows: -</para> - -<programlisting> -data Type = App String [Type] -</programlisting> - -<para> -Here are some examples of using said representation. -Consider a few types of the <literal>Type</literal> universe encoded -like this: -</para> - -<programlisting> - App "->" [t1, t2] -- t1 -> t2 - App "Int" [] -- Int - App "Maybe" [App "Int" []] -- Maybe Int -</programlisting> - -<para> -This representation is very generic in that no types are given special -treatment. However, some functions might need to handle some known -types specially, for example the following two functions collect all -argument types of (nested) arrow types, and recognize the -<literal>Int</literal> type, respectively: -</para> - -<programlisting> - collectArgs :: Type -> [Type] - collectArgs (App "->" [t1, t2]) = t1 : collectArgs t2 - collectArgs _ = [] - - isInt :: Type -> Bool - isInt (App "Int" []) = True - isInt _ = False -</programlisting> - -<para> -Matching on <literal>App</literal> directly is both hard to read and -error prone to write. And the situation is even worse when the -matching is nested: -</para> - -<programlisting> - isIntEndo :: Type -> Bool - isIntEndo (App "->" [App "Int" [], App "Int" []]) = True - isIntEndo _ = False -</programlisting> - -<para> -Pattern synonyms permit abstracting from the representation to expose -matchers that behave in a constructor-like manner with respect to -pattern matching. We can create pattern synonyms for the known types -we care about, without committing the representation to them (note -that these don't have to be defined in the same module as the -<literal>Type</literal> type): -</para> - -<programlisting> - pattern Arrow t1 t2 = App "->" [t1, t2] - pattern Int = App "Int" [] - pattern Maybe t = App "Maybe" [t] -</programlisting> - -<para> -Which enables us to rewrite our functions in a much cleaner style: -</para> - -<programlisting> - collectArgs :: Type -> [Type] - collectArgs (Arrow t1 t2) = t1 : collectArgs t2 - collectArgs _ = [] - - isInt :: Type -> Bool - isInt Int = True - isInt _ = False - - isIntEndo :: Type -> Bool - isIntEndo (Arrow Int Int) = True - isIntEndo _ = False -</programlisting> - -<para> - Note that in this example, the pattern synonyms - <literal>Int</literal> and <literal>Arrow</literal> can also be used - as expressions (they are <emphasis>bidirectional</emphasis>). This - is not necessarily the case: <emphasis>unidirectional</emphasis> - pattern synonyms can also be declared with the following syntax: -</para> - -<programlisting> - pattern Head x <- x:xs -</programlisting> - -<para> -In this case, <literal>Head</literal> <replaceable>x</replaceable> -cannot be used in expressions, only patterns, since it wouldn't -specify a value for the <replaceable>xs</replaceable> on the -right-hand side. We can give an explicit inversion of a pattern -synonym using the following syntax: -</para> - -<programlisting> - pattern Head x <- x:xs where - Head x = [x] -</programlisting> - -<para> -The syntax and semantics of pattern synonyms are elaborated in the -following subsections. -See the <ulink -url="http://ghc.haskell.org/trac/ghc/wiki/PatternSynonyms">Wiki -page</ulink> for more details. -</para> - -<sect3> <title>Syntax and scoping of pattern synonyms</title> -<para> -A pattern synonym declaration can be either unidirectional or -bidirectional. The syntax for unidirectional pattern synonyms is: -<programlisting> - pattern Name args <- pat -</programlisting> - and the syntax for bidirectional pattern synonyms is: -<programlisting> - pattern Name args = pat -</programlisting> or -<programlisting> - pattern Name args <- pat where - Name args = expr -</programlisting> - Either prefix or infix syntax can be - used. -</para> -<para> - Pattern synonym declarations can only occur in the top level of a - module. In particular, they are not allowed as local - definitions. -</para> -<para> - The variables in the left-hand side of the definition are bound by - the pattern on the right-hand side. For implicitly bidirectional - pattern synonyms, all the variables of the right-hand side must also - occur on the left-hand side; also, wildcard patterns and view - patterns are not allowed. For unidirectional and - explicitly-bidirectional pattern synonyms, there is no restriction - on the right-hand side pattern. -</para> - -<para> - Pattern synonyms cannot be defined recursively. -</para> -</sect3> - -<sect3 id="patsyn-impexp"> <title>Import and export of pattern synonyms</title> - -<para> - The name of the pattern synonym itself is in the same namespace as - proper data constructors. In an export or import specification, - you must prefix pattern - names with the <literal>pattern</literal> keyword, e.g.: -<programlisting> - module Example (pattern Single) where - pattern Single x = [x] -</programlisting> -Without the <literal>pattern</literal> prefix, <literal>Single</literal> would -be interpreted as a type constructor in the export list. -</para> -<para> -You may also use the <literal>pattern</literal> keyword in an import/export -specification to import or export an ordinary data constructor. For example: -<programlisting> - import Data.Maybe( pattern Just ) -</programlisting> -would bring into scope the data constructor <literal>Just</literal> from the -<literal>Maybe</literal> type, without also bringing the type constructor -<literal>Maybe</literal> into scope. -</para> -</sect3> - -<sect3> <title>Typing of pattern synonyms</title> - -<para> - Given a pattern synonym definition of the form -<programlisting> - pattern P var1 var2 ... varN <- pat -</programlisting> - it is assigned a <emphasis>pattern type</emphasis> of the form -<programlisting> - pattern P :: CProv => CReq => t1 -> t2 -> ... -> tN -> t -</programlisting> - where <replaceable>CProv</replaceable> and - <replaceable>CReq</replaceable> are type contexts, and - <replaceable>t1</replaceable>, <replaceable>t2</replaceable>, ..., - <replaceable>tN</replaceable> and <replaceable>t</replaceable> are - types. -Notice the unusual form of the type, with two contexts <replaceable>CProv</replaceable> and <replaceable>CReq</replaceable>: -<itemizedlist> -<listitem><para><replaceable>CReq</replaceable> are the constraints <emphasis>required</emphasis> to match the pattern.</para></listitem> -<listitem><para><replaceable>CProv</replaceable> are the constraints <emphasis>made available (provided)</emphasis> -by a successful pattern match.</para></listitem> -</itemizedlist> -For example, consider -<programlisting> -data T a where - MkT :: (Show b) => a -> b -> T a - -f1 :: (Eq a, Num a) => T a -> String -f1 (MkT 42 x) = show x - -pattern ExNumPat :: (Show b) => (Num a, Eq a) => b -> T a -pattern ExNumPat x = MkT 42 x - -f2 :: (Eq a, Num a) => T a -> String -f2 (ExNumPat x) = show x -</programlisting> -Here <literal>f1</literal> does not use pattern synonyms. To match against the -numeric pattern <literal>42</literal> <emphasis>requires</emphasis> the caller to -satisfy the constraints <literal>(Num a, Eq a)</literal>, -so they appear in <literal>f1</literal>'s type. The call to <literal>show</literal> generates a <literal>(Show b)</literal> -constraint, where <literal>b</literal> is an existentially type variable bound by the pattern match -on <literal>MkT</literal>. But the same pattern match also <emphasis>provides</emphasis> the constraint -<literal>(Show b)</literal> (see <literal>MkT</literal>'s type), and so all is well. -</para> -<para> -Exactly the same reasoning applies to <literal>ExNumPat</literal>: -matching against <literal>ExNumPat</literal> <emphasis>requires</emphasis> -the constraints <literal>(Num a, Eq a)</literal>, and <emphasis>provides</emphasis> -the constraint <literal>(Show b)</literal>. -</para> -<para> -Note also the following points -<itemizedlist> -<listitem><para> -In the common case where <replaceable>CReq</replaceable> is empty, - <literal>()</literal>, it can be omitted altogether. -</para> </listitem> - -<listitem><para> -You may specify an explicit <emphasis>pattern signature</emphasis>, as -we did for <literal>ExNumPat</literal> above, to specify the type of a pattern, -just as you can for a function. As usual, the type signature can be less polymorphic -than the inferred type. For example -<programlisting> - -- Inferred type would be 'a -> [a]' - pattern SinglePair :: (a, a) -> [(a, a)] - pattern SinglePair x = [x] -</programlisting> -</para> </listitem> - -<listitem><para> -The GHCi <literal>:info</literal> command shows pattern types in this format. -</para> </listitem> - -<listitem><para> -For a bidirectional pattern synonym, a use of the pattern synonym as an expression has the type -<programlisting> - (CProv, CReq) => t1 -> t2 -> ... -> tN -> t -</programlisting> - So in the previous example, when used in an expression, <literal>ExNumPat</literal> has type -<programlisting> - ExNumPat :: (Show b, Num a, Eq a) => b -> T t -</programlisting> -Notice that this is a tiny bit more restrictive than the expression <literal>MkT 42 x</literal> -which would not require <literal>(Eq a)</literal>. -</para> </listitem> - -<listitem><para> -Consider these two pattern synonyms: -<programlisting> -data S a where - S1 :: Bool -> S Bool - -pattern P1 b = Just b -- P1 :: Bool -> Maybe Bool -pattern P2 b = S1 b -- P2 :: (b~Bool) => Bool -> S b - -f :: Maybe a -> String -f (P1 x) = "no no no" -- Type-incorrect - -g :: S a -> String -g (P2 b) = "yes yes yes" -- Fine -</programlisting> -Pattern <literal>P1</literal> can only match against a value of type <literal>Maybe Bool</literal>, -so function <literal>f</literal> is rejected because the type signature is <literal>Maybe a</literal>. -(To see this, imagine expanding the pattern synonym.) -</para> -<para> -On the other hand, function <literal>g</literal> works fine, because matching against <literal>P2</literal> -(which wraps the GADT <literal>S</literal>) provides the local equality <literal>(a~Bool)</literal>. -If you were to give an explicit pattern signature <literal>P2 :: Bool -> S Bool</literal>, then <literal>P2</literal> -would become less polymorphic, and would behave exactly like <literal>P1</literal> so that <literal>g</literal> -would then be rejected. -</para> -<para> -In short, if you want GADT-like behaviour for pattern synonyms, -then (unlike unlike concrete data constructors like <literal>S1</literal>) -you must write its type with explicit provided equalities. -For a concrete data constructor like <literal>S1</literal> you can write -its type signature as either <literal>S1 :: Bool -> S Bool</literal> or -<literal>S1 :: (b~Bool) => Bool -> S b</literal>; the two are equivalent. -Not so for pattern synonyms: the two forms are different, in order to -distinguish the two cases above. (See <ulink url="https://ghc.haskell.org/trac/ghc/ticket/9953">Trac #9953</ulink> for -discussion of this choice.) -</para></listitem> -</itemizedlist> -</para> -</sect3> - -<sect3><title>Matching of pattern synonyms</title> - -<para> -A pattern synonym occurrence in a pattern is evaluated by first -matching against the pattern synonym itself, and then on the argument -patterns. For example, in the following program, <literal>f</literal> -and <literal>f'</literal> are equivalent: -</para> - -<programlisting> -pattern Pair x y <- [x, y] - -f (Pair True True) = True -f _ = False - -f' [x, y] | True <- x, True <- y = True -f' _ = False -</programlisting> - -<para> - Note that the strictness of <literal>f</literal> differs from that - of <literal>g</literal> defined below: -<programlisting> -g [True, True] = True -g _ = False - -*Main> f (False:undefined) -*** Exception: Prelude.undefined -*Main> g (False:undefined) -False -</programlisting> -</para> -</sect3> - -</sect2> - - <!-- ===================== n+k patterns =================== --> - -<sect2 id="n-k-patterns"> -<title>n+k patterns</title> -<indexterm><primary><option>-XNPlusKPatterns</option></primary></indexterm> - -<para> -<literal>n+k</literal> pattern support is disabled by default. To enable -it, you can use the <option>-XNPlusKPatterns</option> flag. -</para> - -</sect2> - - <!-- ===================== Traditional record syntax =================== --> - -<sect2 id="traditional-record-syntax"> -<title>Traditional record syntax</title> -<indexterm><primary><option>-XNoTraditionalRecordSyntax</option></primary></indexterm> - -<para> -Traditional record syntax, such as <literal>C {f = x}</literal>, is enabled by default. -To disable it, you can use the <option>-XNoTraditionalRecordSyntax</option> flag. -</para> - -</sect2> - - <!-- ===================== Recursive do-notation =================== --> - -<sect2 id="recursive-do-notation"> -<title>The recursive do-notation -</title> - -<para> - The do-notation of Haskell 98 does not allow <emphasis>recursive bindings</emphasis>, - that is, the variables bound in a do-expression are visible only in the textually following - code block. Compare this to a let-expression, where bound variables are visible in the entire binding - group. -</para> - -<para> - It turns out that such recursive bindings do indeed make sense for a variety of monads, but - not all. In particular, recursion in this sense requires a fixed-point operator for the underlying - monad, captured by the <literal>mfix</literal> method of the <literal>MonadFix</literal> class, defined in <literal>Control.Monad.Fix</literal> as follows: -<programlisting> -class Monad m => MonadFix m where - mfix :: (a -> m a) -> m a -</programlisting> - Haskell's - <literal>Maybe</literal>, <literal>[]</literal> (list), <literal>ST</literal> (both strict and lazy versions), - <literal>IO</literal>, and many other monads have <literal>MonadFix</literal> instances. On the negative - side, the continuation monad, with the signature <literal>(a -> r) -> r</literal>, does not. -</para> - -<para> - For monads that do belong to the <literal>MonadFix</literal> class, GHC provides - an extended version of the do-notation that allows recursive bindings. - The <option>-XRecursiveDo</option> (language pragma: <literal>RecursiveDo</literal>) - provides the necessary syntactic support, introducing the keywords <literal>mdo</literal> and - <literal>rec</literal> for higher and lower levels of the notation respectively. Unlike - bindings in a <literal>do</literal> expression, those introduced by <literal>mdo</literal> and <literal>rec</literal> - are recursively defined, much like in an ordinary let-expression. Due to the new - keyword <literal>mdo</literal>, we also call this notation the <emphasis>mdo-notation</emphasis>. -</para> - -<para> - Here is a simple (albeit contrived) example: -<programlisting> -{-# LANGUAGE RecursiveDo #-} -justOnes = mdo { xs <- Just (1:xs) - ; return (map negate xs) } -</programlisting> -or equivalently -<programlisting> -{-# LANGUAGE RecursiveDo #-} -justOnes = do { rec { xs <- Just (1:xs) } - ; return (map negate xs) } -</programlisting> -As you can guess <literal>justOnes</literal> will evaluate to <literal>Just [-1,-1,-1,...</literal>. -</para> - -<para> - GHC's implementation the mdo-notation closely follows the original translation as described in the paper - <ulink url="https://sites.google.com/site/leventerkok/recdo.pdf">A recursive do for Haskell</ulink>, which - in turn is based on the work <ulink url="http://sites.google.com/site/leventerkok/erkok-thesis.pdf">Value Recursion - in Monadic Computations</ulink>. Furthermore, GHC extends the syntax described in the former paper - with a lower level syntax flagged by the <literal>rec</literal> keyword, as we describe next. -</para> - -<sect3> -<title>Recursive binding groups</title> - -<para> - The flag <option>-XRecursiveDo</option> also introduces a new keyword <literal>rec</literal>, which wraps a - mutually-recursive group of monadic statements inside a <literal>do</literal> expression, producing a single statement. - Similar to a <literal>let</literal> statement inside a <literal>do</literal>, variables bound in - the <literal>rec</literal> are visible throughout the <literal>rec</literal> group, and below it. For example, compare -<programlisting> - do { a <- getChar do { a <- getChar - ; let { r1 = f a r2 ; rec { r1 <- f a r2 - ; ; r2 = g r1 } ; ; r2 <- g r1 } - ; return (r1 ++ r2) } ; return (r1 ++ r2) } -</programlisting> - In both cases, <literal>r1</literal> and <literal>r2</literal> are available both throughout - the <literal>let</literal> or <literal>rec</literal> block, and in the statements that follow it. - The difference is that <literal>let</literal> is non-monadic, while <literal>rec</literal> is monadic. - (In Haskell <literal>let</literal> is really <literal>letrec</literal>, of course.) -</para> - -<para> - The semantics of <literal>rec</literal> is fairly straightforward. Whenever GHC finds a <literal>rec</literal> - group, it will compute its set of bound variables, and will introduce an appropriate call - to the underlying monadic value-recursion operator <literal>mfix</literal>, belonging to the - <literal>MonadFix</literal> class. Here is an example: -<programlisting> -rec { b <- f a c ===> (b,c) <- mfix (\ ~(b,c) -> do { b <- f a c - ; c <- f b a } ; c <- f b a - ; return (b,c) }) -</programlisting> - As usual, the meta-variables <literal>b</literal>, <literal>c</literal> etc., can be arbitrary patterns. - In general, the statement <literal>rec <replaceable>ss</replaceable></literal> is desugared to the statement -<programlisting> -<replaceable>vs</replaceable> <- mfix (\ ~<replaceable>vs</replaceable> -> do { <replaceable>ss</replaceable>; return <replaceable>vs</replaceable> }) -</programlisting> - where <replaceable>vs</replaceable> is a tuple of the variables bound by <replaceable>ss</replaceable>. -</para> - -<para> - Note in particular that the translation for a <literal>rec</literal> block only involves wrapping a call - to <literal>mfix</literal>: it performs no other analysis on the bindings. The latter is the task - for the <literal>mdo</literal> notation, which is described next. -</para> -</sect3> - -<sect3> -<title>The <literal>mdo</literal> notation</title> - -<para> - A <literal>rec</literal>-block tells the compiler where precisely the recursive knot should be tied. It turns out that - the placement of the recursive knots can be rather delicate: in particular, we would like the knots to be wrapped - around as minimal groups as possible. This process is known as <emphasis>segmentation</emphasis>, and is described - in detail in Section 3.2 of <ulink url="https://sites.google.com/site/leventerkok/recdo.pdf">A recursive do for - Haskell</ulink>. Segmentation improves polymorphism and reduces the size of the recursive knot. Most importantly, it avoids - unnecessary interference caused by a fundamental issue with the so-called <emphasis>right-shrinking</emphasis> - axiom for monadic recursion. In brief, most monads of interest (IO, strict state, etc.) do <emphasis>not</emphasis> - have recursion operators that satisfy this axiom, and thus not performing segmentation can cause unnecessary - interference, changing the termination behavior of the resulting translation. - (Details can be found in Sections 3.1 and 7.2.2 of - <ulink url="http://sites.google.com/site/leventerkok/erkok-thesis.pdf">Value Recursion in Monadic Computations</ulink>.) -</para> - -<para> - The <literal>mdo</literal> notation removes the burden of placing - explicit <literal>rec</literal> blocks in the code. Unlike an - ordinary <literal>do</literal> expression, in which variables bound by - statements are only in scope for later statements, variables bound in - an <literal>mdo</literal> expression are in scope for all statements - of the expression. The compiler then automatically identifies minimal - mutually recursively dependent segments of statements, treating them as - if the user had wrapped a <literal>rec</literal> qualifier around them. -</para> - -<para> - The definition is syntactic: -</para> -<itemizedlist> - <listitem> - <para> - A generator <replaceable>g</replaceable> - <emphasis>depends</emphasis> on a textually following generator - <replaceable>g'</replaceable>, if - </para> - <itemizedlist> - <listitem> - <para> - <replaceable>g'</replaceable> defines a variable that - is used by <replaceable>g</replaceable>, or - </para> - </listitem> - <listitem> - <para> - <replaceable>g'</replaceable> textually appears between - <replaceable>g</replaceable> and - <replaceable>g''</replaceable>, where <replaceable>g</replaceable> - depends on <replaceable>g''</replaceable>. - </para> - </listitem> - </itemizedlist> - </listitem> - <listitem> - <para> - A <emphasis>segment</emphasis> of a given - <literal>mdo</literal>-expression is a minimal sequence of generators - such that no generator of the sequence depends on an outside - generator. As a special case, although it is not a generator, - the final expression in an <literal>mdo</literal>-expression is - considered to form a segment by itself. - </para> - </listitem> -</itemizedlist> -<para> - Segments in this sense are - related to <emphasis>strongly-connected components</emphasis> analysis, - with the exception that bindings in a segment cannot be reordered and - must be contiguous. -</para> - -<para> - Here is an example <literal>mdo</literal>-expression, and its translation to <literal>rec</literal> blocks: -<programlisting> -mdo { a <- getChar ===> do { a <- getChar - ; b <- f a c ; rec { b <- f a c - ; c <- f b a ; ; c <- f b a } - ; z <- h a b ; z <- h a b - ; d <- g d e ; rec { d <- g d e - ; e <- g a z ; ; e <- g a z } - ; putChar c } ; putChar c } -</programlisting> -Note that a given <literal>mdo</literal> expression can cause the creation of multiple <literal>rec</literal> blocks. -If there are no recursive dependencies, <literal>mdo</literal> will introduce no <literal>rec</literal> blocks. In this -latter case an <literal>mdo</literal> expression is precisely the same as a <literal>do</literal> expression, as one -would expect. -</para> - -<para> - In summary, given an <literal>mdo</literal> expression, GHC first performs segmentation, introducing - <literal>rec</literal> blocks to wrap over minimal recursive groups. Then, each resulting - <literal>rec</literal> is desugared, using a call to <literal>Control.Monad.Fix.mfix</literal> as described - in the previous section. The original <literal>mdo</literal>-expression typechecks exactly when the desugared - version would do so. -</para> - -<para> -Here are some other important points in using the recursive-do notation: - -<itemizedlist> - <listitem> - <para> - It is enabled with the flag <literal>-XRecursiveDo</literal>, or the <literal>LANGUAGE RecursiveDo</literal> - pragma. (The same flag enables both <literal>mdo</literal>-notation, and the use of <literal>rec</literal> - blocks inside <literal>do</literal> expressions.) - </para> - </listitem> - <listitem> - <para> - <literal>rec</literal> blocks can also be used inside <literal>mdo</literal>-expressions, which will be - treated as a single statement. However, it is good style to either use <literal>mdo</literal> or - <literal>rec</literal> blocks in a single expression. - </para> - </listitem> - <listitem> - <para> - If recursive bindings are required for a monad, then that monad must be declared an instance of - the <literal>MonadFix</literal> class. - </para> - </listitem> - <listitem> - <para> - The following instances of <literal>MonadFix</literal> are automatically provided: List, Maybe, IO. - Furthermore, the <literal>Control.Monad.ST</literal> and <literal>Control.Monad.ST.Lazy</literal> - modules provide the instances of the <literal>MonadFix</literal> class for Haskell's internal - state monad (strict and lazy, respectively). - </para> - </listitem> - <listitem> - <para> - Like <literal>let</literal> and <literal>where</literal> bindings, name shadowing is not allowed within - an <literal>mdo</literal>-expression or a <literal>rec</literal>-block; that is, all the names bound in - a single <literal>rec</literal> must be distinct. (GHC will complain if this is not the case.) - </para> - </listitem> -</itemizedlist> -</para> -</sect3> -</sect2> - -<sect2 id="applicative-do"> - <title>Applicative do-notation</title> - <indexterm><primary>Applicative do-notation</primary> - </indexterm> - <indexterm><primary>do-notation</primary><secondary>Applicative</secondary> - </indexterm> - - <para> - The language option - <option>-XApplicativeDo</option><indexterm><primary><option>-XApplicativeDo</option></primary></indexterm> - enables an alternative translation for the do-notation, which - uses the operators <literal><$></literal>, - <literal><*></literal>, along with - <literal>join</literal>, as far as possible. There are two main - reasons for wanting to do this: - </para> - - <itemizedlist> - <listitem> - <para> - We can use do-notation with types that are an instance of - <literal>Applicative</literal> and - <literal>Functor</literal>, but not - <literal>Monad</literal>. - </para> - </listitem> - <listitem> - <para> - In some monads, using the applicative operators is more - efficient than monadic bind. For example, it may enable - more parallelism. - </para> - </listitem> - </itemizedlist> - - <para> - Applicative do-notation desugaring preserves the original - semantics, provided that the <literal>Applicative</literal> - instance satisfies <literal><*> = ap</literal> and - <literal>pure = return</literal> (these are true of all the - common monadic types). Thus, you can normally turn on - <option>-XApplicativeDo</option> without fear of breaking your - program. There is one pitfall to watch out for; see <xref - linkend="applicative-do-pitfall" />. - </para> - - <para> - There are no syntactic changes with - <option>-XApplicativeDo</option>. The only way it shows up at - the source level is that you can have a <literal>do</literal> - expression that doesn't require a <literal>Monad</literal> - constraint. For example, in GHCi: - </para> - -<programlisting> -Prelude> :set -XApplicativeDo -Prelude> :t \m -> do { x <- m; return (not x) } -\m -> do { x <- m; return (not x) } - :: Functor f => f Bool -> f Bool -</programlisting> - - <para> - This example only requires <literal>Functor</literal>, because it - is translated into <literal>(\x -> not x) <$> m</literal>. A - more complex example requires <literal>Applicative</literal>: - -<programlisting> -Prelude> :t \m -> do { x <- m 'a'; y <- m 'b'; return (x || y) } -\m -> do { x <- m 'a'; y <- m 'b'; return (x || y) } - :: Applicative f => (Char -> f Bool) -> f Bool -</programlisting> - </para> - - <para> - Here GHC has translated the expression into - -<programlisting> -(\x y -> x || y) <$> m 'a' <*> m 'b' -</programlisting> - - It is possible to see the actual translation by using - <option>-ddump-ds</option>, but be warned, the output is quite - verbose. - </para> - - <para> - Note that if the expression can't be translated into uses of - <literal><$></literal>, <literal><*></literal> - only, then it will incur a <literal>Monad</literal> constraint as - usual. This happens when there is a dependency on a value - produced by an earlier statement in the do-block: - -<programlisting> -Prelude> :t \m -> do { x <- m True; y <- m x; return (x || y) } -\m -> do { x <- m True; y <- m x; return (x || y) } - :: Monad m => (Bool -> m Bool) -> m Bool -</programlisting> - - Here, <literal>m x</literal> depends on the value of - <literal>x</literal> produced by the first statement, so the - expression cannot be translated using <literal><*></literal>. - </para> - - <para>In general, the rule for when a <literal>do</literal> - statement incurs a <literal>Monad</literal> constraint is as - follows. If the do-expression has the following form: - -<programlisting> -do p1 <- E1; ...; pn <- En; return E -</programlisting> - - where none of the variables defined by <literal>p1...pn</literal> - are mentioned in <literal>E1...En</literal>, then the expression - will only require <literal>Applicative</literal>. Otherwise, the - expression will require <literal>Monad</literal>. - </para> - - <sect3 id="applicative-do-pitfall"> - <title>Things to watch out for</title> - - <para> - Your code should just work as before when - <option>-XApplicativeDo</option> is enabled, provided you use - conventional <literal>Applicative</literal> instances. However, if - you define a <literal>Functor</literal> or - <literal>Applicative</literal> instance using do-notation, then - it will likely get turned into an infinite loop by GHC. For - example, if you do this: - -<programlisting> -instance Functor MyType where - fmap f m = do x <- m; return (f x) -</programlisting> - - Then applicative desugaring will turn it into - -<programlisting> -instance Functor MyType where - fmap f m = fmap (\x -> f x) m -</programlisting> - - And the program will loop at runtime. Similarly, an - <literal>Applicative</literal> instance like this - -<programlisting> -instance Applicative MyType where - pure = return - x <*> y = do f <- x; a <- y; return (f a) -</programlisting> - will result in an infinte loop when <literal><*></literal> - is called. - </para> - - <para>Just as you wouldn't define a <literal>Monad</literal> - instance using the do-notation, you shouldn't define - <literal>Functor</literal> or <literal>Applicative</literal> - instance using do-notation (when using - <literal>ApplicativeDo</literal>) either. The correct way to - define these instances in terms of <literal>Monad</literal> is to - use the <literal>Monad</literal> operations directly, e.g. - -<programlisting> -instance Functor MyType where - fmap f m = m >>= return . f - -instance Applicative MyType where - pure = return - (<*>) = ap -</programlisting> - </para> - </sect3> - -</sect2> - - - <!-- ===================== PARALLEL LIST COMPREHENSIONS =================== --> - - <sect2 id="parallel-list-comprehensions"> - <title>Parallel List Comprehensions</title> - <indexterm><primary>list comprehensions</primary><secondary>parallel</secondary> - </indexterm> - <indexterm><primary>parallel list comprehensions</primary> - </indexterm> - - <para>Parallel list comprehensions are a natural extension to list - comprehensions. List comprehensions can be thought of as a nice - syntax for writing maps and filters. Parallel comprehensions - extend this to include the <literal>zipWith</literal> family.</para> - - <para>A parallel list comprehension has multiple independent - branches of qualifier lists, each separated by a `|' symbol. For - example, the following zips together two lists:</para> - -<programlisting> - [ (x, y) | x <- xs | y <- ys ] -</programlisting> - - <para>The behaviour of parallel list comprehensions follows that of - zip, in that the resulting list will have the same length as the - shortest branch.</para> - - <para>We can define parallel list comprehensions by translation to - regular comprehensions. Here's the basic idea:</para> - - <para>Given a parallel comprehension of the form: </para> - -<programlisting> - [ e | p1 <- e11, p2 <- e12, ... - | q1 <- e21, q2 <- e22, ... - ... - ] -</programlisting> - - <para>This will be translated to: </para> - -<programlisting> - [ e | ((p1,p2), (q1,q2), ...) <- zipN [(p1,p2) | p1 <- e11, p2 <- e12, ...] - [(q1,q2) | q1 <- e21, q2 <- e22, ...] - ... - ] -</programlisting> - - <para>where `zipN' is the appropriate zip for the given number of - branches.</para> - - </sect2> - - <!-- ===================== TRANSFORM LIST COMPREHENSIONS =================== --> - - <sect2 id="generalised-list-comprehensions"> - <title>Generalised (SQL-Like) List Comprehensions</title> - <indexterm><primary>list comprehensions</primary><secondary>generalised</secondary> - </indexterm> - <indexterm><primary>extended list comprehensions</primary> - </indexterm> - <indexterm><primary>group</primary></indexterm> - <indexterm><primary>sql</primary></indexterm> - - - <para>Generalised list comprehensions are a further enhancement to the - list comprehension syntactic sugar to allow operations such as sorting - and grouping which are familiar from SQL. They are fully described in the - paper <ulink url="http://research.microsoft.com/~simonpj/papers/list-comp"> - Comprehensive comprehensions: comprehensions with "order by" and "group by"</ulink>, - except that the syntax we use differs slightly from the paper.</para> -<para>The extension is enabled with the flag <option>-XTransformListComp</option>.</para> -<para>Here is an example: -<programlisting> -employees = [ ("Simon", "MS", 80) -, ("Erik", "MS", 100) -, ("Phil", "Ed", 40) -, ("Gordon", "Ed", 45) -, ("Paul", "Yale", 60)] - -output = [ (the dept, sum salary) -| (name, dept, salary) <- employees -, then group by dept using groupWith -, then sortWith by (sum salary) -, then take 5 ] -</programlisting> -In this example, the list <literal>output</literal> would take on - the value: - -<programlisting> -[("Yale", 60), ("Ed", 85), ("MS", 180)] -</programlisting> -</para> -<para>There are three new keywords: <literal>group</literal>, <literal>by</literal>, and <literal>using</literal>. -(The functions <literal>sortWith</literal> and <literal>groupWith</literal> are not keywords; they are ordinary -functions that are exported by <literal>GHC.Exts</literal>.)</para> - -<para>There are five new forms of comprehension qualifier, -all introduced by the (existing) keyword <literal>then</literal>: - <itemizedlist> - <listitem> - -<programlisting> -then f -</programlisting> - - This statement requires that <literal>f</literal> have the type <literal> - forall a. [a] -> [a]</literal>. You can see an example of its use in the - motivating example, as this form is used to apply <literal>take 5</literal>. - - </listitem> - - - <listitem> -<para> -<programlisting> -then f by e -</programlisting> - - This form is similar to the previous one, but allows you to create a function - which will be passed as the first argument to f. As a consequence f must have - the type <literal>forall a. (a -> t) -> [a] -> [a]</literal>. As you can see - from the type, this function lets f "project out" some information - from the elements of the list it is transforming.</para> - - <para>An example is shown in the opening example, where <literal>sortWith</literal> - is supplied with a function that lets it find out the <literal>sum salary</literal> - for any item in the list comprehension it transforms.</para> - - </listitem> - - - <listitem> - -<programlisting> -then group by e using f -</programlisting> - - <para>This is the most general of the grouping-type statements. In this form, - f is required to have type <literal>forall a. (a -> t) -> [a] -> [[a]]</literal>. - As with the <literal>then f by e</literal> case above, the first argument - is a function supplied to f by the compiler which lets it compute e on every - element of the list being transformed. However, unlike the non-grouping case, - f additionally partitions the list into a number of sublists: this means that - at every point after this statement, binders occurring before it in the comprehension - refer to <emphasis>lists</emphasis> of possible values, not single values. To help understand - this, let's look at an example:</para> - -<programlisting> --- This works similarly to groupWith in GHC.Exts, but doesn't sort its input first -groupRuns :: Eq b => (a -> b) -> [a] -> [[a]] -groupRuns f = groupBy (\x y -> f x == f y) - -output = [ (the x, y) -| x <- ([1..3] ++ [1..2]) -, y <- [4..6] -, then group by x using groupRuns ] -</programlisting> - - <para>This results in the variable <literal>output</literal> taking on the value below:</para> - -<programlisting> -[(1, [4, 5, 6]), (2, [4, 5, 6]), (3, [4, 5, 6]), (1, [4, 5, 6]), (2, [4, 5, 6])] -</programlisting> - - <para>Note that we have used the <literal>the</literal> function to change the type - of x from a list to its original numeric type. The variable y, in contrast, is left - unchanged from the list form introduced by the grouping.</para> - - </listitem> - - <listitem> - -<programlisting> -then group using f -</programlisting> - - <para>With this form of the group statement, f is required to simply have the type - <literal>forall a. [a] -> [[a]]</literal>, which will be used to group up the - comprehension so far directly. An example of this form is as follows:</para> - -<programlisting> -output = [ x -| y <- [1..5] -, x <- "hello" -, then group using inits] -</programlisting> - - <para>This will yield a list containing every prefix of the word "hello" written out 5 times:</para> - -<programlisting> -["","h","he","hel","hell","hello","helloh","hellohe","hellohel","hellohell","hellohello","hellohelloh",...] -</programlisting> - - </listitem> -</itemizedlist> -</para> - </sect2> - - <!-- ===================== MONAD COMPREHENSIONS ===================== --> - -<sect2 id="monad-comprehensions"> - <title>Monad comprehensions</title> - <indexterm><primary>monad comprehensions</primary></indexterm> - - <para> - Monad comprehensions generalise the list comprehension notation, - including parallel comprehensions - (<xref linkend="parallel-list-comprehensions"/>) and - transform comprehensions (<xref linkend="generalised-list-comprehensions"/>) - to work for any monad. - </para> - - <para>Monad comprehensions support:</para> - - <itemizedlist> - <listitem> - <para> - Bindings: - </para> - -<programlisting> -[ x + y | x <- Just 1, y <- Just 2 ] -</programlisting> - - <para> - Bindings are translated with the <literal>(>>=)</literal> and - <literal>return</literal> functions to the usual do-notation: - </para> - -<programlisting> -do x <- Just 1 - y <- Just 2 - return (x+y) -</programlisting> - - </listitem> - <listitem> - <para> - Guards: - </para> - -<programlisting> -[ x | x <- [1..10], x <= 5 ] -</programlisting> - - <para> - Guards are translated with the <literal>guard</literal> function, - which requires a <literal>MonadPlus</literal> instance: - </para> - -<programlisting> -do x <- [1..10] - guard (x <= 5) - return x -</programlisting> - - </listitem> - <listitem> - <para> - Transform statements (as with <literal>-XTransformListComp</literal>): - </para> - -<programlisting> -[ x+y | x <- [1..10], y <- [1..x], then take 2 ] -</programlisting> - - <para> - This translates to: - </para> - -<programlisting> -do (x,y) <- take 2 (do x <- [1..10] - y <- [1..x] - return (x,y)) - return (x+y) -</programlisting> - - </listitem> - <listitem> - <para> - Group statements (as with <literal>-XTransformListComp</literal>): - </para> - -<programlisting> -[ x | x <- [1,1,2,2,3], then group by x using GHC.Exts.groupWith ] -[ x | x <- [1,1,2,2,3], then group using myGroup ] -</programlisting> - - </listitem> - <listitem> - <para> - Parallel statements (as with <literal>-XParallelListComp</literal>): - </para> - -<programlisting> -[ (x+y) | x <- [1..10] - | y <- [11..20] - ] -</programlisting> - - <para> - Parallel statements are translated using the - <literal>mzip</literal> function, which requires a - <literal>MonadZip</literal> instance defined in - <ulink url="&libraryBaseLocation;/Control-Monad-Zip.html"><literal>Control.Monad.Zip</literal></ulink>: - </para> - -<programlisting> -do (x,y) <- mzip (do x <- [1..10] - return x) - (do y <- [11..20] - return y) - return (x+y) -</programlisting> - - </listitem> - </itemizedlist> - - <para> - All these features are enabled by default if the - <literal>MonadComprehensions</literal> extension is enabled. The types - and more detailed examples on how to use comprehensions are explained - in the previous chapters <xref - linkend="generalised-list-comprehensions"/> and <xref - linkend="parallel-list-comprehensions"/>. In general you just have - to replace the type <literal>[a]</literal> with the type - <literal>Monad m => m a</literal> for monad comprehensions. - </para> - - <para> - Note: Even though most of these examples are using the list monad, - monad comprehensions work for any monad. - The <literal>base</literal> package offers all necessary instances for - lists, which make <literal>MonadComprehensions</literal> backward - compatible to built-in, transform and parallel list comprehensions. - </para> -<para> More formally, the desugaring is as follows. We write <literal>D[ e | Q]</literal> -to mean the desugaring of the monad comprehension <literal>[ e | Q]</literal>: -<programlisting> -Expressions: e -Declarations: d -Lists of qualifiers: Q,R,S - --- Basic forms -D[ e | ] = return e -D[ e | p <- e, Q ] = e >>= \p -> D[ e | Q ] -D[ e | e, Q ] = guard e >> \p -> D[ e | Q ] -D[ e | let d, Q ] = let d in D[ e | Q ] - --- Parallel comprehensions (iterate for multiple parallel branches) -D[ e | (Q | R), S ] = mzip D[ Qv | Q ] D[ Rv | R ] >>= \(Qv,Rv) -> D[ e | S ] - --- Transform comprehensions -D[ e | Q then f, R ] = f D[ Qv | Q ] >>= \Qv -> D[ e | R ] - -D[ e | Q then f by b, R ] = f (\Qv -> b) D[ Qv | Q ] >>= \Qv -> D[ e | R ] - -D[ e | Q then group using f, R ] = f D[ Qv | Q ] >>= \ys -> - case (fmap selQv1 ys, ..., fmap selQvn ys) of - Qv -> D[ e | R ] - -D[ e | Q then group by b using f, R ] = f (\Qv -> b) D[ Qv | Q ] >>= \ys -> - case (fmap selQv1 ys, ..., fmap selQvn ys) of - Qv -> D[ e | R ] - -where Qv is the tuple of variables bound by Q (and used subsequently) - selQvi is a selector mapping Qv to the ith component of Qv - -Operator Standard binding Expected type --------------------------------------------------------------------- -return GHC.Base t1 -> m t2 -(>>=) GHC.Base m1 t1 -> (t2 -> m2 t3) -> m3 t3 -(>>) GHC.Base m1 t1 -> m2 t2 -> m3 t3 -guard Control.Monad t1 -> m t2 -fmap GHC.Base forall a b. (a->b) -> n a -> n b -mzip Control.Monad.Zip forall a b. m a -> m b -> m (a,b) -</programlisting> -The comprehension should typecheck when its desugaring would typecheck, -except that (as discussed in <xref linkend="generalised-list-comprehensions"/>) -in the "then f" and "then group using f" clauses, -when the "by b" qualifier is omitted, argument f should have a polymorphic type. -In particular, "then Data.List.sort" and -"then group using Data.List.group" are insufficiently polymorphic. -</para> -<para> -Monad comprehensions support rebindable syntax (<xref linkend="rebindable-syntax"/>). -Without rebindable -syntax, the operators from the "standard binding" module are used; with -rebindable syntax, the operators are looked up in the current lexical scope. -For example, parallel comprehensions will be typechecked and desugared -using whatever "<literal>mzip</literal>" is in scope. -</para> -<para> -The rebindable operators must have the "Expected type" given in the -table above. These types are surprisingly general. For example, you can -use a bind operator with the type -<programlisting> -(>>=) :: T x y a -> (a -> T y z b) -> T x z b -</programlisting> -In the case of transform comprehensions, notice that the groups are -parameterised over some arbitrary type <literal>n</literal> (provided it -has an <literal>fmap</literal>, as well as -the comprehension being over an arbitrary monad. -</para> -</sect2> - - <!-- ===================== REBINDABLE SYNTAX =================== --> - -<sect2 id="rebindable-syntax"> -<title>Rebindable syntax and the implicit Prelude import</title> - - <para><indexterm><primary>-XNoImplicitPrelude - option</primary></indexterm> GHC normally imports - <filename>Prelude.hi</filename> files for you. If you'd - rather it didn't, then give it a - <option>-XNoImplicitPrelude</option> option. The idea is - that you can then import a Prelude of your own. (But don't - call it <literal>Prelude</literal>; the Haskell module - namespace is flat, and you must not conflict with any - Prelude module.)</para> - - <para>Suppose you are importing a Prelude of your own - in order to define your own numeric class - hierarchy. It completely defeats that purpose if the - literal "1" means "<literal>Prelude.fromInteger - 1</literal>", which is what the Haskell Report specifies. - So the <option>-XRebindableSyntax</option> - flag causes - the following pieces of built-in syntax to refer to - <emphasis>whatever is in scope</emphasis>, not the Prelude - versions: - <itemizedlist> - <listitem> - <para>An integer literal <literal>368</literal> means - "<literal>fromInteger (368::Integer)</literal>", rather than - "<literal>Prelude.fromInteger (368::Integer)</literal>". -</para> </listitem> - - <listitem><para>Fractional literals are handed in just the same way, - except that the translation is - <literal>fromRational (3.68::Rational)</literal>. -</para> </listitem> - - <listitem><para>The equality test in an overloaded numeric pattern - uses whatever <literal>(==)</literal> is in scope. -</para> </listitem> - - <listitem><para>The subtraction operation, and the - greater-than-or-equal test, in <literal>n+k</literal> patterns - use whatever <literal>(-)</literal> and <literal>(>=)</literal> are in scope. - </para></listitem> - - <listitem> - <para>Negation (e.g. "<literal>- (f x)</literal>") - means "<literal>negate (f x)</literal>", both in numeric - patterns, and expressions. - </para></listitem> - - <listitem> - <para>Conditionals (e.g. "<literal>if</literal> e1 <literal>then</literal> e2 <literal>else</literal> e3") - means "<literal>ifThenElse</literal> e1 e2 e3". However <literal>case</literal> expressions are unaffected. - </para></listitem> - - <listitem> - <para>"Do" notation is translated using whatever - functions <literal>(>>=)</literal>, - <literal>(>>)</literal>, and <literal>fail</literal>, - are in scope (not the Prelude - versions). List comprehensions, <literal>mdo</literal> - (<xref linkend="recursive-do-notation"/>), and parallel array - comprehensions, are unaffected. </para></listitem> - - <listitem> - <para>Arrow - notation (see <xref linkend="arrow-notation"/>) - uses whatever <literal>arr</literal>, - <literal>(>>>)</literal>, <literal>first</literal>, - <literal>app</literal>, <literal>(|||)</literal> and - <literal>loop</literal> functions are in scope. But unlike the - other constructs, the types of these functions must match the - Prelude types very closely. Details are in flux; if you want - to use this, ask! - </para></listitem> - </itemizedlist> -<option>-XRebindableSyntax</option> implies <option>-XNoImplicitPrelude</option>. -</para> -<para> -In all cases (apart from arrow notation), the static semantics should be that of the desugared form, -even if that is a little unexpected. For example, the -static semantics of the literal <literal>368</literal> -is exactly that of <literal>fromInteger (368::Integer)</literal>; it's fine for -<literal>fromInteger</literal> to have any of the types: -<programlisting> -fromInteger :: Integer -> Integer -fromInteger :: forall a. Foo a => Integer -> a -fromInteger :: Num a => a -> Integer -fromInteger :: Integer -> Bool -> Bool -</programlisting> -</para> - - <para>Be warned: this is an experimental facility, with - fewer checks than usual. Use <literal>-dcore-lint</literal> - to typecheck the desugared program. If Core Lint is happy - you should be all right.</para> - -</sect2> - -<sect2 id="postfix-operators"> -<title>Postfix operators</title> - -<para> - The <option>-XPostfixOperators</option> flag enables a small -extension to the syntax of left operator sections, which allows you to -define postfix operators. The extension is this: the left section -<programlisting> - (e !) -</programlisting> -is equivalent (from the point of view of both type checking and execution) to the expression -<programlisting> - ((!) e) -</programlisting> -(for any expression <literal>e</literal> and operator <literal>(!)</literal>. -The strict Haskell 98 interpretation is that the section is equivalent to -<programlisting> - (\y -> (!) e y) -</programlisting> -That is, the operator must be a function of two arguments. GHC allows it to -take only one argument, and that in turn allows you to write the function -postfix. -</para> -<para>The extension does not extend to the left-hand side of function -definitions; you must define such a function in prefix form.</para> - -</sect2> - -<sect2 id="tuple-sections"> -<title>Tuple sections</title> - -<para> - The <option>-XTupleSections</option> flag enables Python-style partially applied - tuple constructors. For example, the following program -<programlisting> - (, True) -</programlisting> - is considered to be an alternative notation for the more unwieldy alternative -<programlisting> - \x -> (x, True) -</programlisting> -You can omit any combination of arguments to the tuple, as in the following -<programlisting> - (, "I", , , "Love", , 1337) -</programlisting> -which translates to -<programlisting> - \a b c d -> (a, "I", b, c, "Love", d, 1337) -</programlisting> -</para> - -<para> - If you have <link linkend="unboxed-tuples">unboxed tuples</link> enabled, tuple sections - will also be available for them, like so -<programlisting> - (# , True #) -</programlisting> -Because there is no unboxed unit tuple, the following expression -<programlisting> - (# #) -</programlisting> -continues to stand for the unboxed singleton tuple data constructor. -</para> - -</sect2> - -<sect2 id="lambda-case"> -<title>Lambda-case</title> -<para> -The <option>-XLambdaCase</option> flag enables expressions of the form -<programlisting> - \case { p1 -> e1; ...; pN -> eN } -</programlisting> -which is equivalent to -<programlisting> - \freshName -> case freshName of { p1 -> e1; ...; pN -> eN } -</programlisting> -Note that <literal>\case</literal> starts a layout, so you can write -<programlisting> - \case - p1 -> e1 - ... - pN -> eN -</programlisting> -</para> -</sect2> - -<sect2 id="empty-case"> -<title>Empty case alternatives</title> -<para> -The <option>-XEmptyCase</option> flag enables -case expressions, or lambda-case expressions, that have no alternatives, -thus: -<programlisting> - case e of { } -- No alternatives -or - \case { } -- -XLambdaCase is also required -</programlisting> -This can be useful when you know that the expression being scrutinised -has no non-bottom values. For example: -<programlisting> - data Void - f :: Void -> Int - f x = case x of { } -</programlisting> -With dependently-typed features it is more useful -(see <ulink url="http://ghc.haskell.org/trac/ghc/ticket/2431">Trac</ulink>). -For example, consider these two candidate definitions of <literal>absurd</literal>: -<programlisting> -data a :==: b where - Refl :: a :==: a - -absurd :: True :~: False -> a -absurd x = error "absurd" -- (A) -absurd x = case x of {} -- (B) -</programlisting> -We much prefer (B). Why? Because GHC can figure out that <literal>(True :~: False)</literal> -is an empty type. So (B) has no partiality and GHC should be able to compile with -<option>-fwarn-incomplete-patterns</option>. (Though the pattern match checking is not -yet clever enough to do that.) -On the other hand (A) looks dangerous, and GHC doesn't check to make -sure that, in fact, the function can never get called. -</para> -</sect2> - -<sect2 id="multi-way-if"> -<title>Multi-way if-expressions</title> -<para> -With <option>-XMultiWayIf</option> flag GHC accepts conditional expressions -with multiple branches: -<programlisting> - if | guard1 -> expr1 - | ... - | guardN -> exprN -</programlisting> -which is roughly equivalent to -<programlisting> - case () of - _ | guard1 -> expr1 - ... - _ | guardN -> exprN -</programlisting> -</para> - -<para>Multi-way if expressions introduce a new layout context. So the -example above is equivalent to: -<programlisting> - if { | guard1 -> expr1 - ; | ... - ; | guardN -> exprN - } -</programlisting> -The following behaves as expected: -<programlisting> - if | guard1 -> if | guard2 -> expr2 - | guard3 -> expr3 - | guard4 -> expr4 -</programlisting> -because layout translates it as -<programlisting> - if { | guard1 -> if { | guard2 -> expr2 - ; | guard3 -> expr3 - } - ; | guard4 -> expr4 - } -</programlisting> -Layout with multi-way if works in the same way as other layout -contexts, except that the semi-colons between guards in a multi-way if -are optional. So it is not necessary to line up all the guards at the -same column; this is consistent with the way guards work in function -definitions and case expressions. -</para> -</sect2> - -<sect2 id="disambiguate-fields"> -<title>Record field disambiguation</title> -<para> -In record construction and record pattern matching -it is entirely unambiguous which field is referred to, even if there are two different -data types in scope with a common field name. For example: -<programlisting> -module M where - data S = MkS { x :: Int, y :: Bool } - -module Foo where - import M - - data T = MkT { x :: Int } - - ok1 (MkS { x = n }) = n+1 -- Unambiguous - ok2 n = MkT { x = n+1 } -- Unambiguous - - bad1 k = k { x = 3 } -- Ambiguous - bad2 k = x k -- Ambiguous -</programlisting> -Even though there are two <literal>x</literal>'s in scope, -it is clear that the <literal>x</literal> in the pattern in the -definition of <literal>ok1</literal> can only mean the field -<literal>x</literal> from type <literal>S</literal>. Similarly for -the function <literal>ok2</literal>. However, in the record update -in <literal>bad1</literal> and the record selection in <literal>bad2</literal> -it is not clear which of the two types is intended. -</para> -<para> -Haskell 98 regards all four as ambiguous, but with the -<option>-XDisambiguateRecordFields</option> flag, GHC will accept -the former two. The rules are precisely the same as those for instance -declarations in Haskell 98, where the method names on the left-hand side -of the method bindings in an instance declaration refer unambiguously -to the method of that class (provided they are in scope at all), even -if there are other variables in scope with the same name. -This reduces the clutter of qualified names when you import two -records from different modules that use the same field name. -</para> -<para> -Some details: -<itemizedlist> -<listitem><para> -Field disambiguation can be combined with punning (see <xref linkend="record-puns"/>). For example: -<programlisting> -module Foo where - import M - x=True - ok3 (MkS { x }) = x+1 -- Uses both disambiguation and punning -</programlisting> -</para></listitem> - -<listitem><para> -With <option>-XDisambiguateRecordFields</option> you can use <emphasis>unqualified</emphasis> -field names even if the corresponding selector is only in scope <emphasis>qualified</emphasis> -For example, assuming the same module <literal>M</literal> as in our earlier example, this is legal: -<programlisting> -module Foo where - import qualified M -- Note qualified - - ok4 (M.MkS { x = n }) = n+1 -- Unambiguous -</programlisting> -Since the constructor <literal>MkS</literal> is only in scope qualified, you must -name it <literal>M.MkS</literal>, but the field <literal>x</literal> does not need -to be qualified even though <literal>M.x</literal> is in scope but <literal>x</literal> -is not. (In effect, it is qualified by the constructor.) -</para></listitem> -</itemizedlist> -</para> - -</sect2> - - <!-- ===================== Record puns =================== --> - -<sect2 id="record-puns"> -<title>Record puns -</title> - -<para> -Record puns are enabled by the flag <literal>-XNamedFieldPuns</literal>. -</para> - -<para> -When using records, it is common to write a pattern that binds a -variable with the same name as a record field, such as: - -<programlisting> -data C = C {a :: Int} -f (C {a = a}) = a -</programlisting> -</para> - -<para> -Record punning permits the variable name to be elided, so one can simply -write - -<programlisting> -f (C {a}) = a -</programlisting> - -to mean the same pattern as above. That is, in a record pattern, the -pattern <literal>a</literal> expands into the pattern <literal>a = -a</literal> for the same name <literal>a</literal>. -</para> - -<para> -Note that: -<itemizedlist> -<listitem><para> -Record punning can also be used in an expression, writing, for example, -<programlisting> -let a = 1 in C {a} -</programlisting> -instead of -<programlisting> -let a = 1 in C {a = a} -</programlisting> -The expansion is purely syntactic, so the expanded right-hand side -expression refers to the nearest enclosing variable that is spelled the -same as the field name. -</para></listitem> - -<listitem><para> -Puns and other patterns can be mixed in the same record: -<programlisting> -data C = C {a :: Int, b :: Int} -f (C {a, b = 4}) = a -</programlisting> -</para></listitem> - -<listitem><para> -Puns can be used wherever record patterns occur (e.g. in -<literal>let</literal> bindings or at the top-level). -</para></listitem> - -<listitem><para> -A pun on a qualified field name is expanded by stripping off the module qualifier. -For example: -<programlisting> -f (C {M.a}) = a -</programlisting> -means -<programlisting> -f (M.C {M.a = a}) = a -</programlisting> -(This is useful if the field selector <literal>a</literal> for constructor <literal>M.C</literal> -is only in scope in qualified form.) -</para></listitem> -</itemizedlist> -</para> - - -</sect2> - - <!-- ===================== Record wildcards =================== --> - -<sect2 id="record-wildcards"> -<title>Record wildcards -</title> - -<para> -Record wildcards are enabled by the flag <literal>-XRecordWildCards</literal>. -This flag implies <literal>-XDisambiguateRecordFields</literal>. -</para> - -<para> -For records with many fields, it can be tiresome to write out each field -individually in a record pattern, as in -<programlisting> -data C = C {a :: Int, b :: Int, c :: Int, d :: Int} -f (C {a = 1, b = b, c = c, d = d}) = b + c + d -</programlisting> -</para> - -<para> -Record wildcard syntax permits a "<literal>..</literal>" in a record -pattern, where each elided field <literal>f</literal> is replaced by the -pattern <literal>f = f</literal>. For example, the above pattern can be -written as -<programlisting> -f (C {a = 1, ..}) = b + c + d -</programlisting> -</para> - -<para> -More details: -<itemizedlist> -<listitem><para> -Record wildcards in patterns can be mixed with other patterns, including puns -(<xref linkend="record-puns"/>); for example, in a pattern <literal>(C {a -= 1, b, ..})</literal>. Additionally, record wildcards can be used -wherever record patterns occur, including in <literal>let</literal> -bindings and at the top-level. For example, the top-level binding -<programlisting> -C {a = 1, ..} = e -</programlisting> -defines <literal>b</literal>, <literal>c</literal>, and -<literal>d</literal>. -</para></listitem> - -<listitem><para> -Record wildcards can also be used in an expression, when constructing a record. For example, -<programlisting> -let {a = 1; b = 2; c = 3; d = 4} in C {..} -</programlisting> -in place of -<programlisting> -let {a = 1; b = 2; c = 3; d = 4} in C {a=a, b=b, c=c, d=d} -</programlisting> -The expansion is purely syntactic, so the record wildcard -expression refers to the nearest enclosing variables that are spelled -the same as the omitted field names. -</para></listitem> - -<listitem><para> -Record wildcards may <emphasis>not</emphasis> be used in record <emphasis>updates</emphasis>. For example this -is illegal: -<programlisting> -f r = r { x = 3, .. } -</programlisting> -</para></listitem> - -<listitem><para> -For both pattern and expression wildcards, the "<literal>..</literal>" expands to the missing -<emphasis>in-scope</emphasis> record fields. -Specifically the expansion of "<literal>C {..}</literal>" includes -<literal>f</literal> if and only if: -<itemizedlist> -<listitem><para> -<literal>f</literal> is a record field of constructor <literal>C</literal>. -</para></listitem> -<listitem><para> -The record field <literal>f</literal> is in scope somehow (either qualified or unqualified). -</para></listitem> -<listitem><para> -In the case of expressions (but not patterns), -the variable <literal>f</literal> is in scope unqualified, -apart from the binding of the record selector itself. -</para></listitem> -</itemizedlist> -These rules restrict record wildcards to the situations in which the user -could have written the expanded version. -For example -<programlisting> -module M where - data R = R { a,b,c :: Int } -module X where - import M( R(a,c) ) - f b = R { .. } -</programlisting> -The <literal>R{..}</literal> expands to <literal>R{M.a=a}</literal>, -omitting <literal>b</literal> since the record field is not in scope, -and omitting <literal>c</literal> since the variable <literal>c</literal> -is not in scope (apart from the binding of the -record selector <literal>c</literal>, of course). -</para></listitem> - -<listitem><para> -Record wildcards cannot be used (a) in a record update construct, and (b) for data -constructors that are not declared with record fields. For example: -<programlisting> -f x = x { v=True, .. } -- Illegal (a) - -data T = MkT Int Bool -g = MkT { .. } -- Illegal (b) -h (MkT { .. }) = True -- Illegal (b) -</programlisting> -</para></listitem> -</itemizedlist> -</para> - -</sect2> - - <!-- ===================== Local fixity declarations =================== --> - -<sect2 id="local-fixity-declarations"> -<title>Local Fixity Declarations -</title> - -<para>A careful reading of the Haskell 98 Report reveals that fixity -declarations (<literal>infix</literal>, <literal>infixl</literal>, and -<literal>infixr</literal>) are permitted to appear inside local bindings -such those introduced by <literal>let</literal> and -<literal>where</literal>. However, the Haskell Report does not specify -the semantics of such bindings very precisely. -</para> - -<para>In GHC, a fixity declaration may accompany a local binding: -<programlisting> -let f = ... - infixr 3 `f` -in - ... -</programlisting> -and the fixity declaration applies wherever the binding is in scope. -For example, in a <literal>let</literal>, it applies in the right-hand -sides of other <literal>let</literal>-bindings and the body of the -<literal>let</literal>C. Or, in recursive <literal>do</literal> -expressions (<xref linkend="recursive-do-notation"/>), the local fixity -declarations of a <literal>let</literal> statement scope over other -statements in the group, just as the bound name does. -</para> - -<para> -Moreover, a local fixity declaration *must* accompany a local binding of -that name: it is not possible to revise the fixity of name bound -elsewhere, as in -<programlisting> -let infixr 9 $ in ... -</programlisting> - -Because local fixity declarations are technically Haskell 98, no flag is -necessary to enable them. -</para> -</sect2> - -<sect2 id="package-imports"> -<title>Import and export extensions</title> - -<sect3> - <title>Hiding things the imported module doesn't export</title> - -<para> -Technically in Haskell 2010 this is illegal: -<programlisting> -module A( f ) where - f = True - -module B where - import A hiding( g ) -- A does not export g - g = f -</programlisting> -The <literal>import A hiding( g )</literal> in module <literal>B</literal> -is technically an error (<ulink url="http://www.haskell.org/onlinereport/haskell2010/haskellch5.html#x11-1020005.3.1">Haskell Report, 5.3.1</ulink>) -because <literal>A</literal> does not export <literal>g</literal>. -However GHC allows it, in the interests of supporting backward compatibility; for example, a newer version of -<literal>A</literal> might export <literal>g</literal>, and you want <literal>B</literal> to work -in either case. -</para> -<para> -The warning <literal>-fwarn-dodgy-imports</literal>, which is off by default but included with <literal>-W</literal>, -warns if you hide something that the imported module does not export. -</para> -</sect3> - -<sect3> - <title id="package-qualified-imports">Package-qualified imports</title> - - <para>With the <option>-XPackageImports</option> flag, GHC allows - import declarations to be qualified by the package name that the - module is intended to be imported from. For example:</para> - -<programlisting> -import "network" Network.Socket -</programlisting> - - <para>would import the module <literal>Network.Socket</literal> from - the package <literal>network</literal> (any version). This may - be used to disambiguate an import when the same module is - available from multiple packages, or is present in both the - current package being built and an external package.</para> - - <para>The special package name <literal>this</literal> can be used to - refer to the current package being built.</para> - - <para>Note: you probably don't need to use this feature, it was - added mainly so that we can build backwards-compatible versions of - packages when APIs change. It can lead to fragile dependencies in - the common case: modules occasionally move from one package to - another, rendering any package-qualified imports broken. - See also <xref linkend="package-thinning-and-renaming" /> for - an alternative way of disambiguating between module names.</para> -</sect3> - -<sect3 id="safe-imports-ext"> - <title>Safe imports</title> - - <para>With the <option>-XSafe</option>, <option>-XTrustworthy</option> - and <option>-XUnsafe</option> language flags, 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> - -</sect3> - -<sect3 id="explicit-namespaces"> -<title>Explicit namespaces in import/export</title> - -<para> In an import or export list, such as -<programlisting> - module M( f, (++) ) where ... - import N( f, (++) ) - ... -</programlisting> -the entities <literal>f</literal> and <literal>(++)</literal> are <emphasis>values</emphasis>. -However, with type operators (<xref linkend="type-operators"/>) it becomes possible -to declare <literal>(++)</literal> as a <emphasis>type constructor</emphasis>. In that -case, how would you export or import it? -</para> -<para> -The <option>-XExplicitNamespaces</option> extension allows you to prefix the name of -a type constructor in an import or export list with "<literal>type</literal>" to -disambiguate this case, thus: -<programlisting> - module M( f, type (++) ) where ... - import N( f, type (++) ) - ... - module N( f, type (++) ) where - data family a ++ b = L a | R b -</programlisting> -The extension <option>-XExplicitNamespaces</option> -is implied by <option>-XTypeOperators</option> and (for some reason) by <option>-XTypeFamilies</option>. -</para> -<para> -In addition, with <option>-XPatternSynonyms</option> you can prefix the name of -a data constructor in an import or export list with the keyword <literal>pattern</literal>, -to allow the import or export of a data constructor without its parent type constructor -(see <xref linkend="patsyn-impexp"/>). -</para> -</sect3> - -</sect2> - -<sect2 id="syntax-stolen"> -<title>Summary of stolen syntax</title> - - <para>Turning on an option that enables special syntax - <emphasis>might</emphasis> cause working Haskell 98 code to fail - to compile, perhaps because it uses a variable name which has - become a reserved word. This section lists the syntax that is - "stolen" by language extensions. - We use - notation and nonterminal names from the Haskell 98 lexical syntax - (see the Haskell 98 Report). - We only list syntax changes here that might affect - existing working programs (i.e. "stolen" syntax). Many of these - extensions will also enable new context-free syntax, but in all - cases programs written to use the new syntax would not be - compilable without the option enabled.</para> - -<para>There are two classes of special - syntax: - - <itemizedlist> - <listitem> - <para>New reserved words and symbols: character sequences - which are no longer available for use as identifiers in the - program.</para> - </listitem> - <listitem> - <para>Other special syntax: sequences of characters that have - a different meaning when this particular option is turned - on.</para> - </listitem> - </itemizedlist> - -The following syntax is stolen: - - <variablelist> - <varlistentry> - <term> - <literal>forall</literal> - <indexterm><primary><literal>forall</literal></primary></indexterm> - </term> - <listitem><para> - Stolen (in types) by: <option>-XExplicitForAll</option>, and hence by - <option>-XScopedTypeVariables</option>, - <option>-XLiberalTypeSynonyms</option>, - <option>-XRankNTypes</option>, - <option>-XExistentialQuantification</option> - </para></listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>mdo</literal> - <indexterm><primary><literal>mdo</literal></primary></indexterm> - </term> - <listitem><para> - Stolen by: <option>-XRecursiveDo</option> - </para></listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>foreign</literal> - <indexterm><primary><literal>foreign</literal></primary></indexterm> - </term> - <listitem><para> - Stolen by: <option>-XForeignFunctionInterface</option> - </para></listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>rec</literal>, - <literal>proc</literal>, <literal>-<</literal>, - <literal>>-</literal>, <literal>-<<</literal>, - <literal>>>-</literal>, and <literal>(|</literal>, - <literal>|)</literal> brackets - <indexterm><primary><literal>proc</literal></primary></indexterm> - </term> - <listitem><para> - Stolen by: <option>-XArrows</option> - </para></listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>?<replaceable>varid</replaceable></literal> - <indexterm><primary>implicit parameters</primary></indexterm> - </term> - <listitem><para> - Stolen by: <option>-XImplicitParams</option> - </para></listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>[|</literal>, - <literal>[e|</literal>, <literal>[p|</literal>, - <literal>[d|</literal>, <literal>[t|</literal>, - <literal>$(</literal>, - <literal>$$(</literal>, - <literal>[||</literal>, - <literal>[e||</literal>, - <literal>$<replaceable>varid</replaceable></literal>, - <literal>$$<replaceable>varid</replaceable></literal> - <indexterm><primary>Template Haskell</primary></indexterm> - </term> - <listitem><para> - Stolen by: <option>-XTemplateHaskell</option> - </para></listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>[<replaceable>varid</replaceable>|</literal> - <indexterm><primary>quasi-quotation</primary></indexterm> - </term> - <listitem><para> - Stolen by: <option>-XQuasiQuotes</option> - </para></listitem> - </varlistentry> - - <varlistentry> - <term> - <replaceable>varid</replaceable>{<literal>#</literal>}, - <replaceable>char</replaceable><literal>#</literal>, - <replaceable>string</replaceable><literal>#</literal>, - <replaceable>integer</replaceable><literal>#</literal>, - <replaceable>float</replaceable><literal>#</literal>, - <replaceable>float</replaceable><literal>##</literal> - </term> - <listitem><para> - Stolen by: <option>-XMagicHash</option> - </para></listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>(#</literal>, <literal>#)</literal> - </term> - <listitem><para> - Stolen by: <option>-XUnboxedTuples</option> - </para></listitem> - </varlistentry> - - <varlistentry> - <term> - <replaceable>varid</replaceable><literal>!</literal><replaceable>varid</replaceable> - </term> - <listitem><para> - Stolen by: <option>-XBangPatterns</option> - </para></listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>pattern</literal> - </term> - <listitem><para> - Stolen by: <option>-XPatternSynonyms</option> - </para></listitem> - </varlistentry> - </variablelist> -</para> -</sect2> -</sect1> - - -<!-- TYPE SYSTEM EXTENSIONS --> -<sect1 id="data-type-extensions"> -<title>Extensions to data types and type synonyms</title> - -<sect2 id="nullary-types"> -<title>Data types with no constructors</title> - -<para>With the <option>-XEmptyDataDecls</option> flag (or equivalent LANGUAGE pragma), -GHC lets you declare a data type with no constructors. For example:</para> - -<programlisting> - data S -- S :: * - data T a -- T :: * -> * -</programlisting> - -<para>Syntactically, the declaration lacks the "= constrs" part. The -type can be parameterised over types of any kind, but if the kind is -not <literal>*</literal> then an explicit kind annotation must be used -(see <xref linkend="kinding"/>).</para> - -<para>Such data types have only one value, namely bottom. -Nevertheless, they can be useful when defining "phantom types".</para> -</sect2> - -<sect2 id="datatype-contexts"> -<title>Data type contexts</title> - -<para>Haskell allows datatypes to be given contexts, e.g.</para> - -<programlisting> -data Eq a => Set a = NilSet | ConsSet a (Set a) -</programlisting> - -<para>give constructors with types:</para> - -<programlisting> -NilSet :: Set a -ConsSet :: Eq a => a -> Set a -> Set a -</programlisting> - -<para>This is widely considered a misfeature, and is going to be removed from -the language. In GHC, it is controlled by the deprecated extension -<literal>DatatypeContexts</literal>.</para> -</sect2> - -<sect2 id="infix-tycons"> -<title>Infix type constructors, classes, and type variables</title> - -<para> -GHC allows type constructors, classes, and type variables to be operators, and -to be written infix, very much like expressions. More specifically: -<itemizedlist> -<listitem><para> - A type constructor or class can be any non-reserved operator. - Symbols used in types are always like capitalized identifiers; they - are never variables. Note that this is different from the lexical - syntax of data constructors, which are required to begin with a - <literal>:</literal>. - </para></listitem> -<listitem><para> - Data type and type-synonym declarations can be written infix, parenthesised - if you want further arguments. E.g. -<screen> - data a :*: b = Foo a b - type a :+: b = Either a b - class a :=: b where ... - - data (a :**: b) x = Baz a b x - type (a :++: b) y = Either (a,b) y -</screen> - </para></listitem> -<listitem><para> - Types, and class constraints, can be written infix. For example -<screen> - x :: Int :*: Bool - f :: (a :=: b) => a -> b -</screen> - </para></listitem> -<listitem><para> - Back-quotes work - as for expressions, both for type constructors and type variables; e.g. <literal>Int `Either` Bool</literal>, or - <literal>Int `a` Bool</literal>. Similarly, parentheses work the same; e.g. <literal>(:*:) Int Bool</literal>. - </para></listitem> -<listitem><para> - Fixities may be declared for type constructors, or classes, just as for data constructors. However, - one cannot distinguish between the two in a fixity declaration; a fixity declaration - sets the fixity for a data constructor and the corresponding type constructor. For example: -<screen> - infixl 7 T, :*: -</screen> - sets the fixity for both type constructor <literal>T</literal> and data constructor <literal>T</literal>, - and similarly for <literal>:*:</literal>. - <literal>Int `a` Bool</literal>. - </para></listitem> -<listitem><para> - Function arrow is <literal>infixr</literal> with fixity 0. (This might change; I'm not sure what it should be.) - </para></listitem> - -</itemizedlist> -</para> -</sect2> - -<sect2 id="type-operators"> -<title>Type operators</title> -<para> -In types, an operator symbol like <literal>(+)</literal> is normally treated as a type -<emphasis>variable</emphasis>, just like <literal>a</literal>. Thus in Haskell 98 you can say -<programlisting> -type T (+) = ((+), (+)) --- Just like: type T a = (a,a) - -f :: T Int -> Int -f (x,y)= x -</programlisting> -As you can see, using operators in this way is not very useful, and Haskell 98 does not even -allow you to write them infix. -</para> -<para> -The language <option>-XTypeOperators</option> changes this behaviour: -<itemizedlist> -<listitem><para> -Operator symbols become type <emphasis>constructors</emphasis> rather than -type <emphasis>variables</emphasis>. -</para></listitem> -<listitem><para> -Operator symbols in types can be written infix, both in definitions and uses. -for example: -<programlisting> -data a + b = Plus a b -type Foo = Int + Bool -</programlisting> -</para></listitem> -<listitem><para> -There is now some potential ambiguity in import and export lists; for example -if you write <literal>import M( (+) )</literal> do you mean the -<emphasis>function</emphasis> <literal>(+)</literal> or the -<emphasis>type constructor</emphasis> <literal>(+)</literal>? -The default is the former, but with <option>-XExplicitNamespaces</option> (which is implied -by <option>-XTypeOperators</option>) GHC allows you to specify the latter -by preceding it with the keyword <literal>type</literal>, thus: -<programlisting> -import M( type (+) ) -</programlisting> -See <xref linkend="explicit-namespaces"/>. -</para></listitem> -<listitem><para> -The fixity of a type operator may be set using the usual fixity declarations -but, as in <xref linkend="infix-tycons"/>, the function and type constructor share -a single fixity. -</para></listitem> -</itemizedlist> -</para> -</sect2> - -<sect2 id="type-synonyms"> -<title>Liberalised type synonyms</title> - -<para> -Type synonyms are like macros at the type level, but Haskell 98 imposes many rules -on individual synonym declarations. -With the <option>-XLiberalTypeSynonyms</option> extension, -GHC does validity checking on types <emphasis>only after expanding type synonyms</emphasis>. -That means that GHC can be very much more liberal about type synonyms than Haskell 98. - -<itemizedlist> -<listitem> <para>You can write a <literal>forall</literal> (including overloading) -in a type synonym, thus: -<programlisting> - type Discard a = forall b. Show b => a -> b -> (a, String) - - f :: Discard a - f x y = (x, show y) - - g :: Discard Int -> (Int,String) -- A rank-2 type - g f = f 3 True -</programlisting> -</para> -</listitem> - -<listitem><para> -If you also use <option>-XUnboxedTuples</option>, -you can write an unboxed tuple in a type synonym: -<programlisting> - type Pr = (# Int, Int #) - - h :: Int -> Pr - h x = (# x, x #) -</programlisting> -</para></listitem> - -<listitem><para> -You can apply a type synonym to a forall type: -<programlisting> - type Foo a = a -> a -> Bool - - f :: Foo (forall b. b->b) -</programlisting> -After expanding the synonym, <literal>f</literal> has the legal (in GHC) type: -<programlisting> - f :: (forall b. b->b) -> (forall b. b->b) -> Bool -</programlisting> -</para></listitem> - -<listitem><para> -You can apply a type synonym to a partially applied type synonym: -<programlisting> - type Generic i o = forall x. i x -> o x - type Id x = x - - foo :: Generic Id [] -</programlisting> -After expanding the synonym, <literal>foo</literal> has the legal (in GHC) type: -<programlisting> - foo :: forall x. x -> [x] -</programlisting> -</para></listitem> - -</itemizedlist> -</para> - -<para> -GHC currently does kind checking before expanding synonyms (though even that -could be changed.) -</para> -<para> -After expanding type synonyms, GHC does validity checking on types, looking for -the following mal-formedness which isn't detected simply by kind checking: -<itemizedlist> -<listitem><para> -Type constructor applied to a type involving for-alls (if <literal>XImpredicativeTypes</literal> -is off) -</para></listitem> -<listitem><para> -Partially-applied type synonym. -</para></listitem> -</itemizedlist> -So, for example, this will be rejected: -<programlisting> - type Pr = forall a. a - - h :: [Pr] - h = ... -</programlisting> -because GHC does not allow type constructors applied to for-all types. -</para> -</sect2> - - -<sect2 id="existential-quantification"> -<title>Existentially quantified data constructors -</title> - -<para> -The idea of using existential quantification in data type declarations -was suggested by Perry, and implemented in Hope+ (Nigel Perry, <emphasis>The Implementation -of Practical Functional Programming Languages</emphasis>, PhD Thesis, University of -London, 1991). It was later formalised by Laufer and Odersky -(<emphasis>Polymorphic type inference and abstract data types</emphasis>, -TOPLAS, 16(5), pp1411-1430, 1994). -It's been in Lennart -Augustsson's <command>hbc</command> Haskell compiler for several years, and -proved very useful. Here's the idea. Consider the declaration: -</para> - -<para> - -<programlisting> - data Foo = forall a. MkFoo a (a -> Bool) - | Nil -</programlisting> - -</para> - -<para> -The data type <literal>Foo</literal> has two constructors with types: -</para> - -<para> - -<programlisting> - MkFoo :: forall a. a -> (a -> Bool) -> Foo - Nil :: Foo -</programlisting> - -</para> - -<para> -Notice that the type variable <literal>a</literal> in the type of <function>MkFoo</function> -does not appear in the data type itself, which is plain <literal>Foo</literal>. -For example, the following expression is fine: -</para> - -<para> - -<programlisting> - [MkFoo 3 even, MkFoo 'c' isUpper] :: [Foo] -</programlisting> - -</para> - -<para> -Here, <literal>(MkFoo 3 even)</literal> packages an integer with a function -<function>even</function> that maps an integer to <literal>Bool</literal>; and <function>MkFoo 'c' -isUpper</function> packages a character with a compatible function. These -two things are each of type <literal>Foo</literal> and can be put in a list. -</para> - -<para> -What can we do with a value of type <literal>Foo</literal>?. In particular, -what happens when we pattern-match on <function>MkFoo</function>? -</para> - -<para> - -<programlisting> - f (MkFoo val fn) = ??? -</programlisting> - -</para> - -<para> -Since all we know about <literal>val</literal> and <function>fn</function> is that they -are compatible, the only (useful) thing we can do with them is to -apply <function>fn</function> to <literal>val</literal> to get a boolean. For example: -</para> - -<para> - -<programlisting> - f :: Foo -> Bool - f (MkFoo val fn) = fn val -</programlisting> - -</para> - -<para> -What this allows us to do is to package heterogeneous values -together with a bunch of functions that manipulate them, and then treat -that collection of packages in a uniform manner. You can express -quite a bit of object-oriented-like programming this way. -</para> - -<sect3 id="existential"> -<title>Why existential? -</title> - -<para> -What has this to do with <emphasis>existential</emphasis> quantification? -Simply that <function>MkFoo</function> has the (nearly) isomorphic type -</para> - -<para> - -<programlisting> - MkFoo :: (exists a . (a, a -> Bool)) -> Foo -</programlisting> - -</para> - -<para> -But Haskell programmers can safely think of the ordinary -<emphasis>universally</emphasis> quantified type given above, thereby avoiding -adding a new existential quantification construct. -</para> - -</sect3> - -<sect3 id="existential-with-context"> -<title>Existentials and type classes</title> - -<para> -An easy extension is to allow -arbitrary contexts before the constructor. For example: -</para> - -<para> - -<programlisting> -data Baz = forall a. Eq a => Baz1 a a - | forall b. Show b => Baz2 b (b -> b) -</programlisting> - -</para> - -<para> -The two constructors have the types you'd expect: -</para> - -<para> - -<programlisting> -Baz1 :: forall a. Eq a => a -> a -> Baz -Baz2 :: forall b. Show b => b -> (b -> b) -> Baz -</programlisting> - -</para> - -<para> -But when pattern matching on <function>Baz1</function> the matched values can be compared -for equality, and when pattern matching on <function>Baz2</function> the first matched -value can be converted to a string (as well as applying the function to it). -So this program is legal: -</para> - -<para> - -<programlisting> - f :: Baz -> String - f (Baz1 p q) | p == q = "Yes" - | otherwise = "No" - f (Baz2 v fn) = show (fn v) -</programlisting> - -</para> - -<para> -Operationally, in a dictionary-passing implementation, the -constructors <function>Baz1</function> and <function>Baz2</function> must store the -dictionaries for <literal>Eq</literal> and <literal>Show</literal> respectively, and -extract it on pattern matching. -</para> - -</sect3> - -<sect3 id="existential-records"> -<title>Record Constructors</title> - -<para> -GHC allows existentials to be used with records syntax as well. For example: - -<programlisting> -data Counter a = forall self. NewCounter - { _this :: self - , _inc :: self -> self - , _display :: self -> IO () - , tag :: a - } -</programlisting> -Here <literal>tag</literal> is a public field, with a well-typed selector -function <literal>tag :: Counter a -> a</literal>. The <literal>self</literal> -type is hidden from the outside; any attempt to apply <literal>_this</literal>, -<literal>_inc</literal> or <literal>_display</literal> as functions will raise a -compile-time error. In other words, <emphasis>GHC defines a record selector function -only for fields whose type does not mention the existentially-quantified variables</emphasis>. -(This example used an underscore in the fields for which record selectors -will not be defined, but that is only programming style; GHC ignores them.) -</para> - -<para> -To make use of these hidden fields, we need to create some helper functions: - -<programlisting> -inc :: Counter a -> Counter a -inc (NewCounter x i d t) = NewCounter - { _this = i x, _inc = i, _display = d, tag = t } - -display :: Counter a -> IO () -display NewCounter{ _this = x, _display = d } = d x -</programlisting> - -Now we can define counters with different underlying implementations: - -<programlisting> -counterA :: Counter String -counterA = NewCounter - { _this = 0, _inc = (1+), _display = print, tag = "A" } - -counterB :: Counter String -counterB = NewCounter - { _this = "", _inc = ('#':), _display = putStrLn, tag = "B" } - -main = do - display (inc counterA) -- prints "1" - display (inc (inc counterB)) -- prints "##" -</programlisting> - -Record update syntax is supported for existentials (and GADTs): -<programlisting> -setTag :: Counter a -> a -> Counter a -setTag obj t = obj{ tag = t } -</programlisting> -The rule for record update is this: <emphasis> -the types of the updated fields may -mention only the universally-quantified type variables -of the data constructor. For GADTs, the field may mention only types -that appear as a simple type-variable argument in the constructor's result -type</emphasis>. For example: -<programlisting> -data T a b where { T1 { f1::a, f2::b, f3::(b,c) } :: T a b } -- c is existential -upd1 t x = t { f1=x } -- OK: upd1 :: T a b -> a' -> T a' b -upd2 t x = t { f3=x } -- BAD (f3's type mentions c, which is - -- existentially quantified) - -data G a b where { G1 { g1::a, g2::c } :: G a [c] } -upd3 g x = g { g1=x } -- OK: upd3 :: G a b -> c -> G c b -upd4 g x = g { g2=x } -- BAD (f2's type mentions c, which is not a simple - -- type-variable argument in G1's result type) -</programlisting> -</para> - -</sect3> - - -<sect3> -<title>Restrictions</title> - -<para> -There are several restrictions on the ways in which existentially-quantified -constructors can be use. -</para> - -<para> - -<itemizedlist> -<listitem> - -<para> - When pattern matching, each pattern match introduces a new, -distinct, type for each existential type variable. These types cannot -be unified with any other type, nor can they escape from the scope of -the pattern match. For example, these fragments are incorrect: - - -<programlisting> -f1 (MkFoo a f) = a -</programlisting> - - -Here, the type bound by <function>MkFoo</function> "escapes", because <literal>a</literal> -is the result of <function>f1</function>. One way to see why this is wrong is to -ask what type <function>f1</function> has: - - -<programlisting> - f1 :: Foo -> a -- Weird! -</programlisting> - - -What is this "<literal>a</literal>" in the result type? Clearly we don't mean -this: - - -<programlisting> - f1 :: forall a. Foo -> a -- Wrong! -</programlisting> - - -The original program is just plain wrong. Here's another sort of error - - -<programlisting> - f2 (Baz1 a b) (Baz1 p q) = a==q -</programlisting> - - -It's ok to say <literal>a==b</literal> or <literal>p==q</literal>, but -<literal>a==q</literal> is wrong because it equates the two distinct types arising -from the two <function>Baz1</function> constructors. - - -</para> -</listitem> -<listitem> - -<para> -You can't pattern-match on an existentially quantified -constructor in a <literal>let</literal> or <literal>where</literal> group of -bindings. So this is illegal: - - -<programlisting> - f3 x = a==b where { Baz1 a b = x } -</programlisting> - -Instead, use a <literal>case</literal> expression: - -<programlisting> - f3 x = case x of Baz1 a b -> a==b -</programlisting> - -In general, you can only pattern-match -on an existentially-quantified constructor in a <literal>case</literal> expression or -in the patterns of a function definition. - -The reason for this restriction is really an implementation one. -Type-checking binding groups is already a nightmare without -existentials complicating the picture. Also an existential pattern -binding at the top level of a module doesn't make sense, because it's -not clear how to prevent the existentially-quantified type "escaping". -So for now, there's a simple-to-state restriction. We'll see how -annoying it is. - -</para> -</listitem> -<listitem> - -<para> -You can't use existential quantification for <literal>newtype</literal> -declarations. So this is illegal: - - -<programlisting> - newtype T = forall a. Ord a => MkT a -</programlisting> - - -Reason: a value of type <literal>T</literal> must be represented as a -pair of a dictionary for <literal>Ord t</literal> and a value of type -<literal>t</literal>. That contradicts the idea that -<literal>newtype</literal> should have no concrete representation. -You can get just the same efficiency and effect by using -<literal>data</literal> instead of <literal>newtype</literal>. If -there is no overloading involved, then there is more of a case for -allowing an existentially-quantified <literal>newtype</literal>, -because the <literal>data</literal> version does carry an -implementation cost, but single-field existentially quantified -constructors aren't much use. So the simple restriction (no -existential stuff on <literal>newtype</literal>) stands, unless there -are convincing reasons to change it. - - -</para> -</listitem> -<listitem> - -<para> - You can't use <literal>deriving</literal> to define instances of a -data type with existentially quantified data constructors. - -Reason: in most cases it would not make sense. For example:; - -<programlisting> -data T = forall a. MkT [a] deriving( Eq ) -</programlisting> - -To derive <literal>Eq</literal> in the standard way we would need to have equality -between the single component of two <function>MkT</function> constructors: - -<programlisting> -instance Eq T where - (MkT a) == (MkT b) = ??? -</programlisting> - -But <varname>a</varname> and <varname>b</varname> have distinct types, and so can't be compared. -It's just about possible to imagine examples in which the derived instance -would make sense, but it seems altogether simpler simply to prohibit such -declarations. Define your own instances! -</para> -</listitem> - -</itemizedlist> - -</para> - -</sect3> -</sect2> - -<!-- ====================== Generalised algebraic data types ======================= --> - -<sect2 id="gadt-style"> -<title>Declaring data types with explicit constructor signatures</title> - -<para>When the <literal>GADTSyntax</literal> extension is enabled, -GHC allows you to declare an algebraic data type by -giving the type signatures of constructors explicitly. For example: -<programlisting> - data Maybe a where - Nothing :: Maybe a - Just :: a -> Maybe a -</programlisting> -The form is called a "GADT-style declaration" -because Generalised Algebraic Data Types, described in <xref linkend="gadt"/>, -can only be declared using this form.</para> -<para>Notice that GADT-style syntax generalises existential types (<xref linkend="existential-quantification"/>). -For example, these two declarations are equivalent: -<programlisting> - data Foo = forall a. MkFoo a (a -> Bool) - data Foo' where { MKFoo :: a -> (a->Bool) -> Foo' } -</programlisting> -</para> -<para>Any data type that can be declared in standard Haskell-98 syntax -can also be declared using GADT-style syntax. -The choice is largely stylistic, but GADT-style declarations differ in one important respect: -they treat class constraints on the data constructors differently. -Specifically, if the constructor is given a type-class context, that -context is made available by pattern matching. For example: -<programlisting> - data Set a where - MkSet :: Eq a => [a] -> Set a - - makeSet :: Eq a => [a] -> Set a - makeSet xs = MkSet (nub xs) - - insert :: a -> Set a -> Set a - insert a (MkSet as) | a `elem` as = MkSet as - | otherwise = MkSet (a:as) -</programlisting> -A use of <literal>MkSet</literal> as a constructor (e.g. in the definition of <literal>makeSet</literal>) -gives rise to a <literal>(Eq a)</literal> -constraint, as you would expect. The new feature is that pattern-matching on <literal>MkSet</literal> -(as in the definition of <literal>insert</literal>) makes <emphasis>available</emphasis> an <literal>(Eq a)</literal> -context. In implementation terms, the <literal>MkSet</literal> constructor has a hidden field that stores -the <literal>(Eq a)</literal> dictionary that is passed to <literal>MkSet</literal>; so -when pattern-matching that dictionary becomes available for the right-hand side of the match. -In the example, the equality dictionary is used to satisfy the equality constraint -generated by the call to <literal>elem</literal>, so that the type of -<literal>insert</literal> itself has no <literal>Eq</literal> constraint. -</para> -<para> -For example, one possible application is to reify dictionaries: -<programlisting> - data NumInst a where - MkNumInst :: Num a => NumInst a - - intInst :: NumInst Int - intInst = MkNumInst - - plus :: NumInst a -> a -> a -> a - plus MkNumInst p q = p + q -</programlisting> -Here, a value of type <literal>NumInst a</literal> is equivalent -to an explicit <literal>(Num a)</literal> dictionary. -</para> -<para> -All this applies to constructors declared using the syntax of <xref linkend="existential-with-context"/>. -For example, the <literal>NumInst</literal> data type above could equivalently be declared -like this: -<programlisting> - data NumInst a - = Num a => MkNumInst (NumInst a) -</programlisting> -Notice that, unlike the situation when declaring an existential, there is -no <literal>forall</literal>, because the <literal>Num</literal> constrains the -data type's universally quantified type variable <literal>a</literal>. -A constructor may have both universal and existential type variables: for example, -the following two declarations are equivalent: -<programlisting> - data T1 a - = forall b. (Num a, Eq b) => MkT1 a b - data T2 a where - MkT2 :: (Num a, Eq b) => a -> b -> T2 a -</programlisting> -</para> -<para>All this behaviour contrasts with Haskell 98's peculiar treatment of -contexts on a data type declaration (Section 4.2.1 of the Haskell 98 Report). -In Haskell 98 the definition -<programlisting> - data Eq a => Set' a = MkSet' [a] -</programlisting> -gives <literal>MkSet'</literal> the same type as <literal>MkSet</literal> above. But instead of -<emphasis>making available</emphasis> an <literal>(Eq a)</literal> constraint, pattern-matching -on <literal>MkSet'</literal> <emphasis>requires</emphasis> an <literal>(Eq a)</literal> constraint! -GHC faithfully implements this behaviour, odd though it is. But for GADT-style declarations, -GHC's behaviour is much more useful, as well as much more intuitive. -</para> - -<para> -The rest of this section gives further details about GADT-style data -type declarations. - -<itemizedlist> -<listitem><para> -The result type of each data constructor must begin with the type constructor being defined. -If the result type of all constructors -has the form <literal>T a1 ... an</literal>, where <literal>a1 ... an</literal> -are distinct type variables, then the data type is <emphasis>ordinary</emphasis>; -otherwise is a <emphasis>generalised</emphasis> data type (<xref linkend="gadt"/>). -</para></listitem> - -<listitem><para> -As with other type signatures, you can give a single signature for several data constructors. -In this example we give a single signature for <literal>T1</literal> and <literal>T2</literal>: -<programlisting> - data T a where - T1,T2 :: a -> T a - T3 :: T a -</programlisting> -</para></listitem> - -<listitem><para> -The type signature of -each constructor is independent, and is implicitly universally quantified as usual. -In particular, the type variable(s) in the "<literal>data T a where</literal>" header -have no scope, and different constructors may have different universally-quantified type variables: -<programlisting> - data T a where -- The 'a' has no scope - T1,T2 :: b -> T b -- Means forall b. b -> T b - T3 :: T a -- Means forall a. T a -</programlisting> -</para></listitem> - -<listitem><para> -A constructor signature may mention type class constraints, which can differ for -different constructors. For example, this is fine: -<programlisting> - data T a where - T1 :: Eq b => b -> b -> T b - T2 :: (Show c, Ix c) => c -> [c] -> T c -</programlisting> -When pattern matching, these constraints are made available to discharge constraints -in the body of the match. For example: -<programlisting> - f :: T a -> String - f (T1 x y) | x==y = "yes" - | otherwise = "no" - f (T2 a b) = show a -</programlisting> -Note that <literal>f</literal> is not overloaded; the <literal>Eq</literal> constraint arising -from the use of <literal>==</literal> is discharged by the pattern match on <literal>T1</literal> -and similarly the <literal>Show</literal> constraint arising from the use of <literal>show</literal>. -</para></listitem> - -<listitem><para> -Unlike a Haskell-98-style -data type declaration, the type variable(s) in the "<literal>data Set a where</literal>" header -have no scope. Indeed, one can write a kind signature instead: -<programlisting> - data Set :: * -> * where ... -</programlisting> -or even a mixture of the two: -<programlisting> - data Bar a :: (* -> *) -> * where ... -</programlisting> -The type variables (if given) may be explicitly kinded, so we could also write the header for <literal>Foo</literal> -like this: -<programlisting> - data Bar a (b :: * -> *) where ... -</programlisting> -</para></listitem> - - -<listitem><para> -You can use strictness annotations, in the obvious places -in the constructor type: -<programlisting> - data Term a where - Lit :: !Int -> Term Int - If :: Term Bool -> !(Term a) -> !(Term a) -> Term a - Pair :: Term a -> Term b -> Term (a,b) -</programlisting> -</para></listitem> - -<listitem><para> -You can use a <literal>deriving</literal> clause on a GADT-style data type -declaration. For example, these two declarations are equivalent -<programlisting> - data Maybe1 a where { - Nothing1 :: Maybe1 a ; - Just1 :: a -> Maybe1 a - } deriving( Eq, Ord ) - - data Maybe2 a = Nothing2 | Just2 a - deriving( Eq, Ord ) -</programlisting> -</para></listitem> - -<listitem><para> -The type signature may have quantified type variables that do not appear -in the result type: -<programlisting> - data Foo where - MkFoo :: a -> (a->Bool) -> Foo - Nil :: Foo -</programlisting> -Here the type variable <literal>a</literal> does not appear in the result type -of either constructor. -Although it is universally quantified in the type of the constructor, such -a type variable is often called "existential". -Indeed, the above declaration declares precisely the same type as -the <literal>data Foo</literal> in <xref linkend="existential-quantification"/>. -</para><para> -The type may contain a class context too, of course: -<programlisting> - data Showable where - MkShowable :: Show a => a -> Showable -</programlisting> -</para></listitem> - -<listitem><para> -You can use record syntax on a GADT-style data type declaration: - -<programlisting> - data Person where - Adult :: { name :: String, children :: [Person] } -> Person - Child :: Show a => { name :: !String, funny :: a } -> Person -</programlisting> -As usual, for every constructor that has a field <literal>f</literal>, the type of -field <literal>f</literal> must be the same (modulo alpha conversion). -The <literal>Child</literal> constructor above shows that the signature -may have a context, existentially-quantified variables, and strictness annotations, -just as in the non-record case. (NB: the "type" that follows the double-colon -is not really a type, because of the record syntax and strictness annotations. -A "type" of this form can appear only in a constructor signature.) -</para></listitem> - -<listitem><para> -Record updates are allowed with GADT-style declarations, -only fields that have the following property: the type of the field -mentions no existential type variables. -</para></listitem> - -<listitem><para> -As in the case of existentials declared using the Haskell-98-like record syntax -(<xref linkend="existential-records"/>), -record-selector functions are generated only for those fields that have well-typed -selectors. -Here is the example of that section, in GADT-style syntax: -<programlisting> -data Counter a where - NewCounter :: { _this :: self - , _inc :: self -> self - , _display :: self -> IO () - , tag :: a - } -> Counter a -</programlisting> -As before, only one selector function is generated here, that for <literal>tag</literal>. -Nevertheless, you can still use all the field names in pattern matching and record construction. -</para></listitem> - -<listitem><para> -In a GADT-style data type declaration there is no obvious way to specify that a data constructor -should be infix, which makes a difference if you derive <literal>Show</literal> for the type. -(Data constructors declared infix are displayed infix by the derived <literal>show</literal>.) -So GHC implements the following design: a data constructor declared in a GADT-style data type -declaration is displayed infix by <literal>Show</literal> iff (a) it is an operator symbol, -(b) it has two arguments, (c) it has a programmer-supplied fixity declaration. For example -<programlisting> - infix 6 (:--:) - data T a where - (:--:) :: Int -> Bool -> T Int -</programlisting> -</para></listitem> -</itemizedlist></para> -</sect2> - -<sect2 id="gadt"> -<title>Generalised Algebraic Data Types (GADTs)</title> - -<para>Generalised Algebraic Data Types generalise ordinary algebraic data types -by allowing constructors to have richer return types. Here is an example: -<programlisting> - data Term a where - Lit :: Int -> Term Int - Succ :: Term Int -> Term Int - IsZero :: Term Int -> Term Bool - If :: Term Bool -> Term a -> Term a -> Term a - Pair :: Term a -> Term b -> Term (a,b) -</programlisting> -Notice that the return type of the constructors is not always <literal>Term a</literal>, as is the -case with ordinary data types. This generality allows us to -write a well-typed <literal>eval</literal> function -for these <literal>Terms</literal>: -<programlisting> - eval :: Term a -> a - eval (Lit i) = i - eval (Succ t) = 1 + eval t - eval (IsZero t) = eval t == 0 - eval (If b e1 e2) = if eval b then eval e1 else eval e2 - eval (Pair e1 e2) = (eval e1, eval e2) -</programlisting> -The key point about GADTs is that <emphasis>pattern matching causes type refinement</emphasis>. -For example, in the right hand side of the equation -<programlisting> - eval :: Term a -> a - eval (Lit i) = ... -</programlisting> -the type <literal>a</literal> is refined to <literal>Int</literal>. That's the whole point! -A precise specification of the type rules is beyond what this user manual aspires to, -but the design closely follows that described in -the paper <ulink -url="http://research.microsoft.com/%7Esimonpj/papers/gadt/">Simple -unification-based type inference for GADTs</ulink>, -(ICFP 2006). -The general principle is this: <emphasis>type refinement is only carried out -based on user-supplied type annotations</emphasis>. -So if no type signature is supplied for <literal>eval</literal>, no type refinement happens, -and lots of obscure error messages will -occur. However, the refinement is quite general. For example, if we had: -<programlisting> - eval :: Term a -> a -> a - eval (Lit i) j = i+j -</programlisting> -the pattern match causes the type <literal>a</literal> to be refined to <literal>Int</literal> (because of the type -of the constructor <literal>Lit</literal>), and that refinement also applies to the type of <literal>j</literal>, and -the result type of the <literal>case</literal> expression. Hence the addition <literal>i+j</literal> is legal. -</para> -<para> -These and many other examples are given in papers by Hongwei Xi, and -Tim Sheard. There is a longer introduction -<ulink url="http://www.haskell.org/haskellwiki/GADT">on the wiki</ulink>, -and Ralf Hinze's -<ulink url="http://www.cs.ox.ac.uk/ralf.hinze/publications/With.pdf">Fun with phantom types</ulink> also has a number of examples. Note that papers -may use different notation to that implemented in GHC. -</para> -<para> -The rest of this section outlines the extensions to GHC that support GADTs. The extension is enabled with -<option>-XGADTs</option>. The <option>-XGADTs</option> flag also sets <option>-XGADTSyntax</option> -and <option>-XMonoLocalBinds</option>. -<itemizedlist> -<listitem><para> -A GADT can only be declared using GADT-style syntax (<xref linkend="gadt-style"/>); -the old Haskell-98 syntax for data declarations always declares an ordinary data type. -The result type of each constructor must begin with the type constructor being defined, -but for a GADT the arguments to the type constructor can be arbitrary monotypes. -For example, in the <literal>Term</literal> data -type above, the type of each constructor must end with <literal>Term ty</literal>, but -the <literal>ty</literal> need not be a type variable (e.g. the <literal>Lit</literal> -constructor). -</para></listitem> - -<listitem><para> -It is permitted to declare an ordinary algebraic data type using GADT-style syntax. -What makes a GADT into a GADT is not the syntax, but rather the presence of data constructors -whose result type is not just <literal>T a b</literal>. -</para></listitem> - -<listitem><para> -You cannot use a <literal>deriving</literal> clause for a GADT; only for -an ordinary data type. -</para></listitem> - -<listitem><para> -As mentioned in <xref linkend="gadt-style"/>, record syntax is supported. -For example: -<programlisting> - data Term a where - Lit :: { val :: Int } -> Term Int - Succ :: { num :: Term Int } -> Term Int - Pred :: { num :: Term Int } -> Term Int - IsZero :: { arg :: Term Int } -> Term Bool - Pair :: { arg1 :: Term a - , arg2 :: Term b - } -> Term (a,b) - If :: { cnd :: Term Bool - , tru :: Term a - , fls :: Term a - } -> Term a -</programlisting> -However, for GADTs there is the following additional constraint: -every constructor that has a field <literal>f</literal> must have -the same result type (modulo alpha conversion) -Hence, in the above example, we cannot merge the <literal>num</literal> -and <literal>arg</literal> fields above into a -single name. Although their field types are both <literal>Term Int</literal>, -their selector functions actually have different types: - -<programlisting> - num :: Term Int -> Term Int - arg :: Term Bool -> Term Int -</programlisting> -</para></listitem> - -<listitem><para> -When pattern-matching against data constructors drawn from a GADT, -for example in a <literal>case</literal> expression, the following rules apply: -<itemizedlist> -<listitem><para>The type of the scrutinee must be rigid.</para></listitem> -<listitem><para>The type of the entire <literal>case</literal> expression must be rigid.</para></listitem> -<listitem><para>The type of any free variable mentioned in any of -the <literal>case</literal> alternatives must be rigid.</para></listitem> -</itemizedlist> -A type is "rigid" if it is completely known to the compiler at its binding site. The easiest -way to ensure that a variable a rigid type is to give it a type signature. -For more precise details see <ulink url="http://research.microsoft.com/%7Esimonpj/papers/gadt"> -Simple unification-based type inference for GADTs -</ulink>. The criteria implemented by GHC are given in the Appendix. - -</para></listitem> - -</itemizedlist> -</para> - -</sect2> -</sect1> - -<!-- ====================== End of Generalised algebraic data types ======================= --> - -<sect1 id="deriving"> -<title>Extensions to the "deriving" mechanism</title> - -<sect2 id="deriving-inferred"> -<title>Inferred context for deriving clauses</title> - -<para> -The Haskell Report is vague about exactly when a <literal>deriving</literal> clause is -legal. For example: -<programlisting> - data T0 f a = MkT0 a deriving( Eq ) - data T1 f a = MkT1 (f a) deriving( Eq ) - data T2 f a = MkT2 (f (f a)) deriving( Eq ) -</programlisting> -The natural generated <literal>Eq</literal> code would result in these instance declarations: -<programlisting> - instance Eq a => Eq (T0 f a) where ... - instance Eq (f a) => Eq (T1 f a) where ... - instance Eq (f (f a)) => Eq (T2 f a) where ... -</programlisting> -The first of these is obviously fine. The second is still fine, although less obviously. -The third is not Haskell 98, and risks losing termination of instances. -</para> -<para> -GHC takes a conservative position: it accepts the first two, but not the third. The rule is this: -each constraint in the inferred instance context must consist only of type variables, -with no repetitions. -</para> -<para> -This rule is applied regardless of flags. If you want a more exotic context, you can write -it yourself, using the <link linkend="stand-alone-deriving">standalone deriving mechanism</link>. -</para> -</sect2> - -<sect2 id="stand-alone-deriving"> -<title>Stand-alone deriving declarations</title> - -<para> -GHC now allows stand-alone <literal>deriving</literal> declarations, enabled by <literal>-XStandaloneDeriving</literal>: -<programlisting> - data Foo a = Bar a | Baz String - - deriving instance Eq a => Eq (Foo a) -</programlisting> -The syntax is identical to that of an ordinary instance declaration apart from (a) the keyword -<literal>deriving</literal>, and (b) the absence of the <literal>where</literal> part. -</para> -<para> -However, standalone deriving differs from a <literal>deriving</literal> clause in a number -of important ways: -<itemizedlist> -<listitem><para>The standalone deriving declaration does not need to be in the -same module as the data type declaration. (But be aware of the dangers of -orphan instances (<xref linkend="orphan-modules"/>). -</para></listitem> - -<listitem><para> -You must supply an explicit context (in the example the context is <literal>(Eq a)</literal>), -exactly as you would in an ordinary instance declaration. -(In contrast, in a <literal>deriving</literal> clause -attached to a data type declaration, the context is inferred.) -</para></listitem> - -<listitem><para> -Unlike a <literal>deriving</literal> -declaration attached to a <literal>data</literal> declaration, the instance can be more specific -than the data type (assuming you also use -<literal>-XFlexibleInstances</literal>, <xref linkend="instance-rules"/>). Consider -for example -<programlisting> - data Foo a = Bar a | Baz String - - deriving instance Eq a => Eq (Foo [a]) - deriving instance Eq a => Eq (Foo (Maybe a)) -</programlisting> -This will generate a derived instance for <literal>(Foo [a])</literal> and <literal>(Foo (Maybe a))</literal>, -but other types such as <literal>(Foo (Int,Bool))</literal> will not be an instance of <literal>Eq</literal>. -</para></listitem> - -<listitem><para> -Unlike a <literal>deriving</literal> -declaration attached to a <literal>data</literal> declaration, -GHC does not restrict the form of the data type. Instead, GHC simply generates the appropriate -boilerplate code for the specified class, and typechecks it. If there is a type error, it is -your problem. (GHC will show you the offending code if it has a type error.) -</para> -<para> -The merit of this is that you can derive instances for GADTs and other exotic -data types, providing only that the boilerplate code does indeed typecheck. For example: -<programlisting> - data T a where - T1 :: T Int - T2 :: T Bool - - deriving instance Show (T a) -</programlisting> -In this example, you cannot say <literal>... deriving( Show )</literal> on the -data type declaration for <literal>T</literal>, -because <literal>T</literal> is a GADT, but you <emphasis>can</emphasis> generate -the instance declaration using stand-alone deriving. -</para> -<para> -The down-side is that, -if the boilerplate code fails to typecheck, you will get an error message about that -code, which you did not write. Whereas, with a <literal>deriving</literal> clause -the side-conditions are necessarily more conservative, but any error message -may be more comprehensible. -</para> -</listitem> -</itemizedlist></para> - -<para> -In other ways, however, a standalone deriving obeys the same rules as ordinary deriving: -<itemizedlist> -<listitem><para> -A <literal>deriving instance</literal> declaration -must obey the same rules concerning form and termination as ordinary instance declarations, -controlled by the same flags; see <xref linkend="instance-decls"/>. -</para></listitem> - -<listitem> -<para>The stand-alone syntax is generalised for newtypes in exactly the same -way that ordinary <literal>deriving</literal> clauses are generalised (<xref linkend="newtype-deriving"/>). -For example: -<programlisting> - newtype Foo a = MkFoo (State Int a) - - deriving instance MonadState Int Foo -</programlisting> -GHC always treats the <emphasis>last</emphasis> parameter of the instance -(<literal>Foo</literal> in this example) as the type whose instance is being derived. -</para></listitem> -</itemizedlist></para> - -</sect2> - -<sect2 id="deriving-extra"> -<title>Deriving instances of extra classes (<literal>Data</literal>, etc)</title> - -<para> -Haskell 98 allows the programmer to add "<literal>deriving( Eq, Ord )</literal>" to a data type -declaration, to generate a standard instance declaration for classes specified in the <literal>deriving</literal> clause. -In Haskell 98, the only classes that may appear in the <literal>deriving</literal> clause are the standard -classes <literal>Eq</literal>, <literal>Ord</literal>, -<literal>Enum</literal>, <literal>Ix</literal>, <literal>Bounded</literal>, <literal>Read</literal>, and <literal>Show</literal>. -</para> -<para> -GHC extends this list with several more classes that may be automatically derived: -<itemizedlist> -<listitem><para> With <option>-XDeriveGeneric</option>, you can derive -instances of the classes <literal>Generic</literal> and -<literal>Generic1</literal>, defined in <literal>GHC.Generics</literal>. -You can use these to define generic functions, -as described in <xref linkend="generic-programming"/>. -</para></listitem> - -<listitem><para> With <option>-XDeriveFunctor</option>, you can derive instances of -the class <literal>Functor</literal>, -defined in <literal>GHC.Base</literal>. See <xref linkend="deriving-functor"/>. -</para></listitem> - -<listitem><para> With <option>-XDeriveDataTypeable</option>, you can derive instances of -the class <literal>Data</literal>, -defined in <literal>Data.Data</literal>. See <xref linkend="deriving-typeable"/> for -deriving <literal>Typeable</literal>. -</para></listitem> - -<listitem><para> With <option>-XDeriveFoldable</option>, you can derive instances of -the class <literal>Foldable</literal>, -defined in <literal>Data.Foldable</literal>. See <xref linkend="deriving-foldable"/>. -</para></listitem> - -<listitem><para> With <option>-XDeriveTraversable</option>, you can derive instances of -the class <literal>Traversable</literal>, -defined in <literal>Data.Traversable</literal>. Since the <literal>Traversable</literal> -instance dictates the instances of <literal>Functor</literal> and -<literal>Foldable</literal>, you'll probably want to derive them too, so -<option>-XDeriveTraversable</option> implies -<option>-XDeriveFunctor</option> and <option>-XDeriveFoldable</option>. -See <xref linkend="deriving-traversable"/>. -</para></listitem> - -<listitem><para> With <option>-XDeriveLift</option>, you can derive instances -of the class <literal>Lift</literal>, defined in the -<literal>Language.Haskell.TH.Syntax</literal> module of the -<literal>template-haskell</literal> package. -See <xref linkend="deriving-lift"/>. -</para></listitem> -</itemizedlist> -You can also use a standalone deriving declaration instead -(see <xref linkend="stand-alone-deriving"/>). -</para> -<para> -In each case the appropriate class must be in scope before it -can be mentioned in the <literal>deriving</literal> clause. -</para> -</sect2> - -<sect2 id="deriving-functor"> -<title>Deriving <literal>Functor</literal> instances</title> - -<para>With <option>-XDeriveFunctor</option>, one can derive -<literal>Functor</literal> instances for data types of kind -<literal>* -> *</literal>. For example, this declaration: - -<programlisting> -data Example a = Ex a Char (Example a) (Example Char) - deriving Functor -</programlisting> - -would generate the following instance: - -<programlisting> -instance Functor Example where - fmap f (Ex a1 a2 a3 a4) = Ex (f a1) a2 (fmap f a3) a4 -</programlisting> -</para> - -<para>The basic algorithm for <option>-XDeriveFunctor</option> walks the -arguments of each constructor of a data type, applying a mapping function -depending on the type of each argument. Suppose we are deriving -<literal>Functor</literal> for a data type whose last type parameter is -<literal>a</literal>. Then we write the derivation of <literal>fmap</literal> -code over the type variable <literal>a</literal> for type -<literal>b</literal> as <literal>$(fmap 'a 'b)</literal>. - -<itemizedlist> -<listitem><para>If the argument's type is <literal>a</literal>, then -map over it. - -<programlisting> -$(fmap 'a 'a) = f -</programlisting> -</para></listitem> - -<listitem><para>If the argument's type does not mention <literal>a</literal>, -then do nothing to it. - -<programlisting> -$(fmap 'a 'b) = \x -> x -- when b does not contain a -</programlisting> -</para></listitem> - -<listitem><para>If the argument has a tuple type, generate map code for each -of its arguments. - -<programlisting> -$(fmap 'a '(b1,b2)) = \x -> case x of (x1,x2) -> ($(fmap 'a 'b1) x1, $(fmap 'a 'b2) x2) -</programlisting> -</para></listitem> - -<listitem><para>If the argument's type is a data type that mentions -<literal>a</literal>, apply <literal>fmap</literal> to it with the generated -map code for the data type's last type parameter. - -<programlisting> -$(fmap 'a '(T b1 b2)) = fmap $(fmap 'a 'b2) -- when a only occurs in the last parameter, b2 -</programlisting> -</para></listitem> - -<listitem><para>If the argument has a function type, apply generated -<literal>$(fmap)</literal> code to the result type, and apply generated -<literal>$(cofmap)</literal> code to the argument type. - -<programlisting> -$(fmap 'a '(b -> c)) = \x b -> $(fmap 'a' 'c) (x ($(cofmap 'a 'b) b)) -</programlisting> - -<literal>$(cofmap)</literal> is needed because the type parameter -<literal>a</literal> can occur in a contravariant position, which means we -need to derive a function like: - -<programlisting> -cofmap :: (a -> b) -> f b -> f a -</programlisting> - -This is pretty much the same as <literal>$(fmap)</literal>, only without the -<literal>$(cofmap 'a 'a)</literal> case: - -<programlisting> -$(cofmap 'a 'b) = \x -> x -- when b does not contain a -$(cofmap 'a 'a) = error "type variable in contravariant position" -$(cofmap 'a '(b1,b2)) = \x -> case x of (x1,x2) -> ($(cofmap 'a 'b1) x1, $(cofmap 'a 'b2) x2) -$(cofmap 'a '[b]) = map $(cofmap 'a 'b) -$(cofmap 'a '(T b1 b2)) = fmap $(cofmap 'a 'b2) -- when a only occurs in the last parameter, b2 -$(cofmap 'a '(b -> c)) = \x b -> $(cofmap 'a' 'c) (x ($(fmap 'a 'c) b)) -</programlisting> - -For more information on contravariance, see -<ulink url="https://ghc.haskell.org/trac/ghc/wiki/Commentary/Compiler/DeriveFunctor#Covariantandcontravariantpositions"> -this wiki page</ulink>. -</para></listitem> -</itemizedlist> -</para> - -<para>A data type can have a derived <literal>Functor</literal> instance if: - -<itemizedlist> -<listitem><para>It has at least one type parameter. -</para></listitem> - -<listitem><para>It does not use the last type parameter contravariantly. -</para></listitem> - -<listitem><para>It does not use the last type parameter in the "wrong place" -in any of the argument data types. For example, in: - -<programlisting> -data Right a = Right [a] (Either Int a) -</programlisting> - -the type parameter <literal>a</literal> is only ever used as the last type -argument in <literal>[]</literal> and <literal>Either</literal>, so both -<literal>[a]</literal> and <literal>Either Int a</literal> can be -<literal>fmap</literal>ped. However, in: - -<programlisting> -data Wrong a = Wrong (Either a a) -</programlisting> - -the type variable <literal>a</literal> appears in a position other than the -last, so trying to <literal>fmap</literal> an <literal>Either a a</literal> -value would not typecheck in a <literal>Functor</literal> instance. - -Note that there are two exceptions to this rule: tuple and function types, as -described above. -</para></listitem> - -<listitem><para>Its last type variable cannot be used in a -<option>-XDatatypeContexts</option> constraint. -</para></listitem> - -<listitem><para>Its last type variable cannot be used in an -<option>-XExistentialQuantification</option> or <option>-XGADTs</option> -constraint. -</para></listitem> -</itemizedlist> - -</para> -</sect2> - -<sect2 id="deriving-foldable"> -<title>Deriving <literal>Foldable</literal> instances</title> - -<para>With <option>-XDeriveFoldable</option>, one can derive -<literal>Foldable</literal> instances for data types of kind -<literal>* -> *</literal>. For example, this declaration: - -<programlisting> -data Example a = Ex a Char (Example a) (Example Char) - deriving Functor -</programlisting> - -would generate the following instance: - -<programlisting> -instance Foldable Example where - foldr f z (Ex a1 a2 a3 a4) = f a1 (foldr f z a3) - foldMap f (Ex a1 a2 a3 a4) = mappend (f a1) - (mappend mempty - (mappend (foldMap f a3) - mempty)) -</programlisting> - -The algorithm for <option>-XDeriveFoldable</option> is very similar to that of -<option>-XDeriveFunctor</option>, except that <literal>Foldable</literal> -instances are not possible for function types. The cases are: - -<programlisting> -$(foldr 'a 'b) = \x z -> z -- when b does not contain a -$(foldr 'a 'a) = f -$(foldr 'a '(b1,b2)) = \x z -> case x of (x1,x2) -> $(foldr 'a 'b1) x1 ( $(foldr 'a 'b2) x2 z ) -$(foldr 'a '(T b1 b2)) = \x z -> foldr $(foldr 'a 'b2) z x -- when a only occurs in the last parameter, b2 -</programlisting> - -Another difference between <option>-XDeriveFoldable</option> and -<option>-XDeriveFunctor</option> is that <option>-XDeriveFoldable</option> -instances can be derived for data types with existential constraints. For -example, the following data type: - -<programlisting> -data E a where - E1 :: (a ~ Int) => a -> E a - E2 :: Int -> E Int - E3 :: (a ~ Int) => a -> E Int - E4 :: (a ~ Int) => Int -> E a - -deriving instance Foldable E -</programlisting> - -would have the following <literal>Foldable</literal> instance: - -<programlisting> -instance Foldable E where - foldr f z (E1 e) = f e z - foldr f z (E2 e) = z - foldr f z (E3 e) = z - foldr f z (E4 e) = z - - foldMap f (E1 e) = f e - foldMap f (E2 e) = mempty - foldMap f (E3 e) = mempty - foldMap f (E4 e) = mempty -</programlisting> - -Notice that only the argument in <literal>E1</literal> is folded over. This is -because we only fold over constructor arguments (1) whose types are -syntactically equivalent to the last type parameter and (2) when the last type -parameter is not refined to a specific type. Only <literal>E1</literal> -satisfies both of these criteria. For more information, see -<ulink url="https://ghc.haskell.org/trac/ghc/wiki/Commentary/Compiler/DeriveFunctor"> -this wiki page</ulink>. -</para> -</sect2> - -<sect2 id="deriving-traversable"> -<title>Deriving <literal>Traversable</literal> instances</title> - -<para>With <option>-XDeriveTraversable</option>, one can derive -<literal>Traversable</literal> instances for data types of kind -<literal>* -> *</literal>. For example, this declaration: - -<programlisting> -data Example a = Ex a Char (Example a) (Example Char) - deriving Functor -</programlisting> - -would generate the following instance: - -<programlisting> -instance Foldable Example where - traverse f (Ex a1 a2 a3 a4) - = fmap Ex (f a) - <*> pure a2 - <*> traverse f a3 - <*> pure a4 -</programlisting> - -The algorithm for <option>-XDeriveTraversable</option> is very similar to that -of <option>-XDeriveTraversable</option>, except that -<literal>Traversable</literal> instances are not possible for function types. -The cases are: - -<programlisting> -1812 $(traverse 'a 'b) = pure -- when b does not contain a -1813 $(traverse 'a 'a) = f -1814 $(traverse 'a '(b1,b2)) = \x -> case x of (x1,x2) -> fmap (,) $(traverse 'a 'b1) x1 <*> $(traverse 'a 'b2) x2 -1815 $(traverse 'a '(T b1 b2)) = traverse $(traverse 'a 'b2) -- when a only occurs in the last parameter, b2 -</programlisting> -</para> -</sect2> - -<sect2 id="deriving-typeable"> -<title>Deriving <literal>Typeable</literal> instances</title> - -<para>The class <literal>Typeable</literal> is very special: -<itemizedlist> -<listitem><para> -<literal>Typeable</literal> is kind-polymorphic (see -<xref linkend="kind-polymorphism"/>). -</para></listitem> - -<listitem><para> -GHC has a custom solver for discharging constraints that involve -class <literal>Typeable</literal>, and handwritten instances are forbidden. -This ensures that the programmer cannot subvert the type system by -writing bogus instances. -</para></listitem> - -<listitem><para> -Derived instances of <literal>Typeable</literal> are ignored, -and may be reported as an error in a later version of the compiler. -</para></listitem> - -<listitem><para> -The rules for solving `Typeable` constraints are as follows: -<itemizedlist> -<listitem><para>A concrete type constructor applied to some types. -<programlisting> -instance (Typeable t1, .., Typeable t_n) => - Typeable (T t1 .. t_n) -</programlisting> -This rule works for any concrete type constructor, including type -constructors with polymorphic kinds. The only restriction is that -if the type constructor has a polymorphic kind, then it has to be applied -to all of its kinds parameters, and these kinds need to be concrete -(i.e., they cannot mention kind variables). -</para></listitem> - -<listitem><para> -<programlisting>A type variable applied to some types. -instance (Typeable f, Typeable t1, .., Typeable t_n) => - Typeable (f t1 .. t_n) -</programlisting> -</para></listitem> - -<listitem><para> -<programlisting>A concrete type literal. -instance Typeable 0 -- Type natural literals -instance Typeable "Hello" -- Type-level symbols -</programlisting> -</para></listitem> -</itemizedlist> -</para></listitem> - - -</itemizedlist> - -</para> - -</sect2> - -<sect2 id="deriving-lift"> -<title>Deriving <literal>Lift</literal> instances</title> - -<para>The class <literal>Lift</literal>, unlike other derivable classes, lives -in <literal>template-haskell</literal> instead of <literal>base</literal>. -Having a data type be an instance of <literal>Lift</literal> permits its values -to be promoted to Template Haskell expressions (of type -<literal>ExpQ</literal>), which can then be spliced into Haskell source code. -</para> - -<para>Here is an example of how one can derive <literal>Lift</literal>: - -<programlisting> -{-# LANGUAGE DeriveLift #-} -module Bar where - -import Language.Haskell.TH.Syntax - -data Foo a = Foo a | a :^: a deriving Lift - -{- -instance (Lift a) => Lift (Foo a) where - lift (Foo a) - = appE - (conE - (mkNameG_d "package-name" "Bar" "Foo")) - (lift a) - lift (u :^: v) - = infixApp - (lift u) - (conE - (mkNameG_d "package-name" "Bar" ":^:")) - (lift v) --} - ------ -{-# LANGUAGE TemplateHaskell #-} -module Baz where - -import Bar -import Language.Haskell.TH.Lift - -foo :: Foo String -foo = $(lift $ Foo "foo") - -fooExp :: Lift a => Foo a -> Q Exp -fooExp f = [| f |] -</programlisting> - -<option>-XDeriveLift</option> also works for certain unboxed types -(<literal>Addr#</literal>, <literal>Char#</literal>, -<literal>Double#</literal>, <literal>Float#</literal>, -<literal>Int#</literal>, and <literal>Word#</literal>): - -<programlisting> -{-# LANGUAGE DeriveLift, MagicHash #-} -module Unboxed where - -import GHC.Exts -import Language.Haskell.TH.Syntax - -data IntHash = IntHash Int# deriving Lift - -{- -instance Lift IntHash where - lift (IntHash i) - = appE - (conE - (mkNameG_d "package-name" "Unboxed" "IntHash")) - (litE - (intPrimL (toInteger (I# i)))) --} -</programlisting> - -</para> - -</sect2> - -<sect2 id="newtype-deriving"> -<title>Generalised derived instances for newtypes</title> - -<para> -When you define an abstract type using <literal>newtype</literal>, you may want -the new type to inherit some instances from its representation. In -Haskell 98, you can inherit instances of <literal>Eq</literal>, <literal>Ord</literal>, -<literal>Enum</literal> and <literal>Bounded</literal> by deriving them, but for any -other classes you have to write an explicit instance declaration. For -example, if you define - -<programlisting> - newtype Dollars = Dollars Int -</programlisting> - -and you want to use arithmetic on <literal>Dollars</literal>, you have to -explicitly define an instance of <literal>Num</literal>: - -<programlisting> - instance Num Dollars where - Dollars a + Dollars b = Dollars (a+b) - ... -</programlisting> -All the instance does is apply and remove the <literal>newtype</literal> -constructor. It is particularly galling that, since the constructor -doesn't appear at run-time, this instance declaration defines a -dictionary which is <emphasis>wholly equivalent</emphasis> to the <literal>Int</literal> -dictionary, only slower! -</para> - - -<sect3 id="generalized-newtype-deriving"> <title> Generalising the deriving clause </title> -<para> -GHC now permits such instances to be derived instead, -using the flag <option>-XGeneralizedNewtypeDeriving</option>, -so one can write -<programlisting> - newtype Dollars = Dollars Int deriving (Eq,Show,Num) -</programlisting> - -and the implementation uses the <emphasis>same</emphasis> <literal>Num</literal> dictionary -for <literal>Dollars</literal> as for <literal>Int</literal>. Notionally, the compiler -derives an instance declaration of the form - -<programlisting> - instance Num Int => Num Dollars -</programlisting> - -which just adds or removes the <literal>newtype</literal> constructor according to the type. -</para> -<para> - -We can also derive instances of constructor classes in a similar -way. For example, suppose we have implemented state and failure monad -transformers, such that - -<programlisting> - instance Monad m => Monad (State s m) - instance Monad m => Monad (Failure m) -</programlisting> -In Haskell 98, we can define a parsing monad by -<programlisting> - type Parser tok m a = State [tok] (Failure m) a -</programlisting> - -which is automatically a monad thanks to the instance declarations -above. With the extension, we can make the parser type abstract, -without needing to write an instance of class <literal>Monad</literal>, via - -<programlisting> - newtype Parser tok m a = Parser (State [tok] (Failure m) a) - deriving Monad -</programlisting> -In this case the derived instance declaration is of the form -<programlisting> - instance Monad (State [tok] (Failure m)) => Monad (Parser tok m) -</programlisting> - -Notice that, since <literal>Monad</literal> is a constructor class, the -instance is a <emphasis>partial application</emphasis> of the new type, not the -entire left hand side. We can imagine that the type declaration is -"eta-converted" to generate the context of the instance -declaration. -</para> -<para> - -We can even derive instances of multi-parameter classes, provided the -newtype is the last class parameter. In this case, a ``partial -application'' of the class appears in the <literal>deriving</literal> -clause. For example, given the class - -<programlisting> - class StateMonad s m | m -> s where ... - instance Monad m => StateMonad s (State s m) where ... -</programlisting> -then we can derive an instance of <literal>StateMonad</literal> for <literal>Parser</literal>s by -<programlisting> - newtype Parser tok m a = Parser (State [tok] (Failure m) a) - deriving (Monad, StateMonad [tok]) -</programlisting> - -The derived instance is obtained by completing the application of the -class to the new type: - -<programlisting> - instance StateMonad [tok] (State [tok] (Failure m)) => - StateMonad [tok] (Parser tok m) -</programlisting> -</para> -<para> - -As a result of this extension, all derived instances in newtype - declarations are treated uniformly (and implemented just by reusing -the dictionary for the representation type), <emphasis>except</emphasis> -<literal>Show</literal> and <literal>Read</literal>, which really behave differently for -the newtype and its representation. -</para> -</sect3> - -<sect3> <title> A more precise specification </title> -<para> -A derived instance is derived only for declarations of these forms (after expansion of any type synonyms) - -<programlisting> - newtype T v1..vn = MkT (t vk+1..vn) deriving (C t1..tj) - newtype instance T s1..sk vk+1..vn = MkT (t vk+1..vn) deriving (C t1..tj) -</programlisting> -where - <itemizedlist> -<listitem><para> -<literal>v1..vn</literal> are type variables, and <literal>t</literal>, -<literal>s1..sk</literal>, <literal>t1..tj</literal> are types. -</para></listitem> -<listitem><para> - The <literal>(C t1..tj)</literal> is a partial applications of the class <literal>C</literal>, - where the arity of <literal>C</literal> - is exactly <literal>j+1</literal>. That is, <literal>C</literal> lacks exactly one type argument. -</para></listitem> -<listitem><para> - <literal>k</literal> is chosen so that <literal>C t1..tj (T v1...vk)</literal> is well-kinded. -(Or, in the case of a <literal>data instance</literal>, so that <literal>C t1..tj (T s1..sk)</literal> is -well kinded.) -</para></listitem> -<listitem><para> - The type <literal>t</literal> is an arbitrary type. -</para></listitem> -<listitem><para> - The type variables <literal>vk+1...vn</literal> do not occur in the types <literal>t</literal>, - <literal>s1..sk</literal>, or <literal>t1..tj</literal>. -</para></listitem> -<listitem><para> - <literal>C</literal> is not <literal>Read</literal>, <literal>Show</literal>, - <literal>Typeable</literal>, or <literal>Data</literal>. These classes - should not "look through" the type or its constructor. You can still - derive these classes for a newtype, but it happens in the usual way, not - via this new mechanism. -</para></listitem> -<listitem><para> - It is safe to coerce each of the methods of <literal>C</literal>. That is, - the missing last argument to <literal>C</literal> is not used - at a nominal role in any of the <literal>C</literal>'s methods. - (See <xref linkend="roles"/>.)</para></listitem> -</itemizedlist> -Then the derived instance is of form -declaration is: -<programlisting> - instance C t1..tj t => C t1..tj (T v1...vk) -</programlisting> -As an example which does <emphasis>not</emphasis> work, consider -<programlisting> - newtype NonMonad m s = NonMonad (State s m s) deriving Monad -</programlisting> -Here we cannot derive the instance -<programlisting> - instance Monad (State s m) => Monad (NonMonad m) -</programlisting> - -because the type variable <literal>s</literal> occurs in <literal>State s m</literal>, -and so cannot be "eta-converted" away. It is a good thing that this -<literal>deriving</literal> clause is rejected, because <literal>NonMonad m</literal> is -not, in fact, a monad --- for the same reason. Try defining -<literal>>>=</literal> with the correct type: you won't be able to. -</para> -<para> - -Notice also that the <emphasis>order</emphasis> of class parameters becomes -important, since we can only derive instances for the last one. If the -<literal>StateMonad</literal> class above were instead defined as - -<programlisting> - class StateMonad m s | m -> s where ... -</programlisting> - -then we would not have been able to derive an instance for the -<literal>Parser</literal> type above. We hypothesise that multi-parameter -classes usually have one "main" parameter for which deriving new -instances is most interesting. -</para> -<para>Lastly, all of this applies only for classes other than -<literal>Read</literal>, <literal>Show</literal>, <literal>Typeable</literal>, -and <literal>Data</literal>, for which the built-in derivation applies (section -4.3.3. of the Haskell Report). -(For the standard classes <literal>Eq</literal>, <literal>Ord</literal>, -<literal>Ix</literal>, and <literal>Bounded</literal> it is immaterial whether -the standard method is used or the one described here.) -</para> -</sect3> -</sect2> - -<sect2 id="derive-any-class"> -<title>Deriving any other class</title> - -<para> -With <option>-XDeriveAnyClass</option> you can derive any other class. The -compiler will simply generate an empty instance. The instance context will be -generated according to the same rules used when deriving <literal>Eq</literal>. -This is mostly useful in classes whose <link linkend="minimal-pragma">minimal -set</link> is empty, and especially when writing -<link linkend="generic-programming">generic functions</link>. - -In case you try to derive some class on a newtype, and -<option>-XGeneralizedNewtypeDeriving</option> is also on, -<option>-XDeriveAnyClass</option> takes precedence. -</para> - -</sect2> - -</sect1> - - -<!-- TYPE SYSTEM EXTENSIONS --> -<sect1 id="type-class-extensions"> -<title>Class and instances declarations</title> - -<sect2 id="multi-param-type-classes"> -<title>Class declarations</title> - -<para> -This section, and the next one, documents GHC's type-class extensions. -There's lots of background in the paper <ulink -url="http://research.microsoft.com/~simonpj/Papers/type-class-design-space/">Type -classes: exploring the design space</ulink> (Simon Peyton Jones, Mark -Jones, Erik Meijer). -</para> - -<sect3> -<title>Multi-parameter type classes</title> -<para> -Multi-parameter type classes are permitted, with flag <option>-XMultiParamTypeClasses</option>. -For example: - - -<programlisting> - class Collection c a where - union :: c a -> c a -> c a - ...etc. -</programlisting> - -</para> -</sect3> - -<sect3 id="superclass-rules"> -<title>The superclasses of a class declaration</title> - -<para> -In Haskell 98 the context of a class declaration (which introduces superclasses) -must be simple; that is, each predicate must consist of a class applied to -type variables. The flag <option>-XFlexibleContexts</option> -(<xref linkend="flexible-contexts"/>) -lifts this restriction, -so that the only restriction on the context in a class declaration is -that the class hierarchy must be acyclic. So these class declarations are OK: - - -<programlisting> - class Functor (m k) => FiniteMap m k where - ... - - class (Monad m, Monad (t m)) => Transform t m where - lift :: m a -> (t m) a -</programlisting> - - -</para> -<para> -As in Haskell 98, The class hierarchy must be acyclic. However, the definition -of "acyclic" involves only the superclass relationships. For example, -this is OK: - - -<programlisting> - class C a where { - op :: D b => a -> b -> b - } - - class C a => D a where { ... } -</programlisting> - - -Here, <literal>C</literal> is a superclass of <literal>D</literal>, but it's OK for a -class operation <literal>op</literal> of <literal>C</literal> to mention <literal>D</literal>. (It -would not be OK for <literal>D</literal> to be a superclass of <literal>C</literal>.) -</para> -<para> -With the extension that adds a <link linkend="constraint-kind">kind of constraints</link>, -you can write more exotic superclass definitions. The superclass cycle check is even more -liberal in these case. For example, this is OK: - -<programlisting> - class A cls c where - meth :: cls c => c -> c - - class A B c => B c where -</programlisting> - -A superclass context for a class <literal>C</literal> is allowed if, after expanding -type synonyms to their right-hand-sides, and uses of classes (other than <literal>C</literal>) -to their superclasses, <literal>C</literal> does not occur syntactically in the context. -</para> -</sect3> - - - - -<sect3 id="class-method-types"> -<title>Class method types</title> - -<para> -Haskell 98 prohibits class method types to mention constraints on the -class type variable, thus: -<programlisting> - class Seq s a where - fromList :: [a] -> s a - elem :: Eq a => a -> s a -> Bool -</programlisting> -The type of <literal>elem</literal> is illegal in Haskell 98, because it -contains the constraint <literal>Eq a</literal>, which constrains only the -class type variable (in this case <literal>a</literal>). -</para> -<para> -GHC lifts this restriction with language extension <option>-XConstrainedClassMethods</option>. -The restriction is a pretty stupid one in the first place, -so <option>-XConstrainedClassMethods</option> is implied by <option>-XMultiParamTypeClasses</option>. -</para> -</sect3> - -<sect3 id="class-default-signatures"> -<title>Default method signatures</title> - -<para> -Haskell 98 allows you to define a default implementation when declaring a class: -<programlisting> - class Enum a where - enum :: [a] - enum = [] -</programlisting> -The type of the <literal>enum</literal> method is <literal>[a]</literal>, and -this is also the type of the default method. You can lift this restriction -and give another type to the default method using the flag -<option>-XDefaultSignatures</option>. For instance, if you have written a -generic implementation of enumeration in a class <literal>GEnum</literal> -with method <literal>genum</literal> in terms of <literal>GHC.Generics</literal>, -you can specify a default method that uses that generic implementation: -<programlisting> - class Enum a where - enum :: [a] - default enum :: (Generic a, GEnum (Rep a)) => [a] - enum = map to genum -</programlisting> -We reuse the keyword <literal>default</literal> to signal that a signature -applies to the default method only; when defining instances of the -<literal>Enum</literal> class, the original type <literal>[a]</literal> of -<literal>enum</literal> still applies. When giving an empty instance, however, -the default implementation <literal>map to genum</literal> is filled-in, -and type-checked with the type -<literal>(Generic a, GEnum (Rep a)) => [a]</literal>. -</para> - -<para> -We use default signatures to simplify generic programming in GHC -(<xref linkend="generic-programming"/>). -</para> - - -</sect3> - -<sect3 id="nullary-type-classes"> -<title>Nullary type classes</title> -Nullary (no parameter) type classes are enabled with -<option>-XMultiTypeClasses</option>; historically, they were enabled with the -(now deprecated) <option>-XNullaryTypeClasses</option>. -Since there are no available parameters, there can be at most one instance -of a nullary class. A nullary type class might be used to document some assumption -in a type signature (such as reliance on the Riemann hypothesis) or add some -globally configurable settings in a program. For example, - -<programlisting> - class RiemannHypothesis where - assumeRH :: a -> a - - -- Deterministic version of the Miller test - -- correctness depends on the generalised Riemann hypothesis - isPrime :: RiemannHypothesis => Integer -> Bool - isPrime n = assumeRH (...) -</programlisting> - -The type signature of <literal>isPrime</literal> informs users that its correctness -depends on an unproven conjecture. If the function is used, the user has -to acknowledge the dependence with: - -<programlisting> - instance RiemannHypothesis where - assumeRH = id -</programlisting> - -</sect3> -</sect2> - -<sect2 id="functional-dependencies"> -<title>Functional dependencies -</title> - -<para> Functional dependencies are implemented as described by Mark Jones -in “<ulink url="http://citeseer.ist.psu.edu/jones00type.html">Type Classes with Functional Dependencies</ulink>”, Mark P. Jones, -In Proceedings of the 9th European Symposium on Programming, -ESOP 2000, Berlin, Germany, March 2000, Springer-Verlag LNCS 1782, -. -</para> -<para> -Functional dependencies are introduced by a vertical bar in the syntax of a -class declaration; e.g. -<programlisting> - class (Monad m) => MonadState s m | m -> s where ... - - class Foo a b c | a b -> c where ... -</programlisting> -There should be more documentation, but there isn't (yet). Yell if you need it. -</para> - -<sect3><title>Rules for functional dependencies </title> -<para> -In a class declaration, all of the class type variables must be reachable (in the sense -mentioned in <xref linkend="flexible-contexts"/>) -from the free variables of each method type. -For example: - -<programlisting> - class Coll s a where - empty :: s - insert :: s -> a -> s -</programlisting> - -is not OK, because the type of <literal>empty</literal> doesn't mention -<literal>a</literal>. Functional dependencies can make the type variable -reachable: -<programlisting> - class Coll s a | s -> a where - empty :: s - insert :: s -> a -> s -</programlisting> - -Alternatively <literal>Coll</literal> might be rewritten - -<programlisting> - class Coll s a where - empty :: s a - insert :: s a -> a -> s a -</programlisting> - - -which makes the connection between the type of a collection of -<literal>a</literal>'s (namely <literal>(s a)</literal>) and the element type <literal>a</literal>. -Occasionally this really doesn't work, in which case you can split the -class like this: - - -<programlisting> - class CollE s where - empty :: s - - class CollE s => Coll s a where - insert :: s -> a -> s -</programlisting> -</para> -</sect3> - - -<sect3> -<title>Background on functional dependencies</title> - -<para>The following description of the motivation and use of functional dependencies is taken -from the Hugs user manual, reproduced here (with minor changes) by kind -permission of Mark Jones. -</para> -<para> -Consider the following class, intended as part of a -library for collection types: -<programlisting> - class Collects e ce where - empty :: ce - insert :: e -> ce -> ce - member :: e -> ce -> Bool -</programlisting> -The type variable e used here represents the element type, while ce is the type -of the container itself. Within this framework, we might want to define -instances of this class for lists or characteristic functions (both of which -can be used to represent collections of any equality type), bit sets (which can -be used to represent collections of characters), or hash tables (which can be -used to represent any collection whose elements have a hash function). Omitting -standard implementation details, this would lead to the following declarations: -<programlisting> - instance Eq e => Collects e [e] where ... - instance Eq e => Collects e (e -> Bool) where ... - instance Collects Char BitSet where ... - instance (Hashable e, Collects a ce) - => Collects e (Array Int ce) where ... -</programlisting> -All this looks quite promising; we have a class and a range of interesting -implementations. Unfortunately, there are some serious problems with the class -declaration. First, the empty function has an ambiguous type: -<programlisting> - empty :: Collects e ce => ce -</programlisting> -By "ambiguous" we mean that there is a type variable e that appears on the left -of the <literal>=></literal> symbol, but not on the right. The problem with -this is that, according to the theoretical foundations of Haskell overloading, -we cannot guarantee a well-defined semantics for any term with an ambiguous -type. -</para> -<para> -We can sidestep this specific problem by removing the empty member from the -class declaration. However, although the remaining members, insert and member, -do not have ambiguous types, we still run into problems when we try to use -them. For example, consider the following two functions: -<programlisting> - f x y = insert x . insert y - g = f True 'a' -</programlisting> -for which GHC infers the following types: -<programlisting> - f :: (Collects a c, Collects b c) => a -> b -> c -> c - g :: (Collects Bool c, Collects Char c) => c -> c -</programlisting> -Notice that the type for f allows the two parameters x and y to be assigned -different types, even though it attempts to insert each of the two values, one -after the other, into the same collection. If we're trying to model collections -that contain only one type of value, then this is clearly an inaccurate -type. Worse still, the definition for g is accepted, without causing a type -error. As a result, the error in this code will not be flagged at the point -where it appears. Instead, it will show up only when we try to use g, which -might even be in a different module. -</para> - -<sect4><title>An attempt to use constructor classes</title> - -<para> -Faced with the problems described above, some Haskell programmers might be -tempted to use something like the following version of the class declaration: -<programlisting> - class Collects e c where - empty :: c e - insert :: e -> c e -> c e - member :: e -> c e -> Bool -</programlisting> -The key difference here is that we abstract over the type constructor c that is -used to form the collection type c e, and not over that collection type itself, -represented by ce in the original class declaration. This avoids the immediate -problems that we mentioned above: empty has type <literal>Collects e c => c -e</literal>, which is not ambiguous. -</para> -<para> -The function f from the previous section has a more accurate type: -<programlisting> - f :: (Collects e c) => e -> e -> c e -> c e -</programlisting> -The function g from the previous section is now rejected with a type error as -we would hope because the type of f does not allow the two arguments to have -different types. -This, then, is an example of a multiple parameter class that does actually work -quite well in practice, without ambiguity problems. -There is, however, a catch. This version of the Collects class is nowhere near -as general as the original class seemed to be: only one of the four instances -for <literal>Collects</literal> -given above can be used with this version of Collects because only one of -them---the instance for lists---has a collection type that can be written in -the form c e, for some type constructor c, and element type e. -</para> -</sect4> - -<sect4><title>Adding functional dependencies</title> - -<para> -To get a more useful version of the Collects class, Hugs provides a mechanism -that allows programmers to specify dependencies between the parameters of a -multiple parameter class (For readers with an interest in theoretical -foundations and previous work: The use of dependency information can be seen -both as a generalisation of the proposal for `parametric type classes' that was -put forward by Chen, Hudak, and Odersky, or as a special case of Mark Jones's -later framework for "improvement" of qualified types. The -underlying ideas are also discussed in a more theoretical and abstract setting -in a manuscript [implparam], where they are identified as one point in a -general design space for systems of implicit parameterisation.). - -To start with an abstract example, consider a declaration such as: -<programlisting> - class C a b where ... -</programlisting> -which tells us simply that C can be thought of as a binary relation on types -(or type constructors, depending on the kinds of a and b). Extra clauses can be -included in the definition of classes to add information about dependencies -between parameters, as in the following examples: -<programlisting> - class D a b | a -> b where ... - class E a b | a -> b, b -> a where ... -</programlisting> -The notation <literal>a -> b</literal> used here between the | and where -symbols --- not to be -confused with a function type --- indicates that the a parameter uniquely -determines the b parameter, and might be read as "a determines b." Thus D is -not just a relation, but actually a (partial) function. Similarly, from the two -dependencies that are included in the definition of E, we can see that E -represents a (partial) one-one mapping between types. -</para> -<para> -More generally, dependencies take the form <literal>x1 ... xn -> y1 ... ym</literal>, -where x1, ..., xn, and y1, ..., yn are type variables with n>0 and -m>=0, meaning that the y parameters are uniquely determined by the x -parameters. Spaces can be used as separators if more than one variable appears -on any single side of a dependency, as in <literal>t -> a b</literal>. Note that a class may be -annotated with multiple dependencies using commas as separators, as in the -definition of E above. Some dependencies that we can write in this notation are -redundant, and will be rejected because they don't serve any useful -purpose, and may instead indicate an error in the program. Examples of -dependencies like this include <literal>a -> a </literal>, -<literal>a -> a a </literal>, -<literal>a -> </literal>, etc. There can also be -some redundancy if multiple dependencies are given, as in -<literal>a->b</literal>, - <literal>b->c </literal>, <literal>a->c </literal>, and -in which some subset implies the remaining dependencies. Examples like this are -not treated as errors. Note that dependencies appear only in class -declarations, and not in any other part of the language. In particular, the -syntax for instance declarations, class constraints, and types is completely -unchanged. -</para> -<para> -By including dependencies in a class declaration, we provide a mechanism for -the programmer to specify each multiple parameter class more precisely. The -compiler, on the other hand, is responsible for ensuring that the set of -instances that are in scope at any given point in the program is consistent -with any declared dependencies. For example, the following pair of instance -declarations cannot appear together in the same scope because they violate the -dependency for D, even though either one on its own would be acceptable: -<programlisting> - instance D Bool Int where ... - instance D Bool Char where ... -</programlisting> -Note also that the following declaration is not allowed, even by itself: -<programlisting> - instance D [a] b where ... -</programlisting> -The problem here is that this instance would allow one particular choice of [a] -to be associated with more than one choice for b, which contradicts the -dependency specified in the definition of D. More generally, this means that, -in any instance of the form: -<programlisting> - instance D t s where ... -</programlisting> -for some particular types t and s, the only variables that can appear in s are -the ones that appear in t, and hence, if the type t is known, then s will be -uniquely determined. -</para> -<para> -The benefit of including dependency information is that it allows us to define -more general multiple parameter classes, without ambiguity problems, and with -the benefit of more accurate types. To illustrate this, we return to the -collection class example, and annotate the original definition of <literal>Collects</literal> -with a simple dependency: -<programlisting> - class Collects e ce | ce -> e where - empty :: ce - insert :: e -> ce -> ce - member :: e -> ce -> Bool -</programlisting> -The dependency <literal>ce -> e</literal> here specifies that the type e of elements is uniquely -determined by the type of the collection ce. Note that both parameters of -Collects are of kind *; there are no constructor classes here. Note too that -all of the instances of Collects that we gave earlier can be used -together with this new definition. -</para> -<para> -What about the ambiguity problems that we encountered with the original -definition? The empty function still has type Collects e ce => ce, but it is no -longer necessary to regard that as an ambiguous type: Although the variable e -does not appear on the right of the => symbol, the dependency for class -Collects tells us that it is uniquely determined by ce, which does appear on -the right of the => symbol. Hence the context in which empty is used can still -give enough information to determine types for both ce and e, without -ambiguity. More generally, we need only regard a type as ambiguous if it -contains a variable on the left of the => that is not uniquely determined -(either directly or indirectly) by the variables on the right. -</para> -<para> -Dependencies also help to produce more accurate types for user defined -functions, and hence to provide earlier detection of errors, and less cluttered -types for programmers to work with. Recall the previous definition for a -function f: -<programlisting> - f x y = insert x y = insert x . insert y -</programlisting> -for which we originally obtained a type: -<programlisting> - f :: (Collects a c, Collects b c) => a -> b -> c -> c -</programlisting> -Given the dependency information that we have for Collects, however, we can -deduce that a and b must be equal because they both appear as the second -parameter in a Collects constraint with the same first parameter c. Hence we -can infer a shorter and more accurate type for f: -<programlisting> - f :: (Collects a c) => a -> a -> c -> c -</programlisting> -In a similar way, the earlier definition of g will now be flagged as a type error. -</para> -<para> -Although we have given only a few examples here, it should be clear that the -addition of dependency information can help to make multiple parameter classes -more useful in practice, avoiding ambiguity problems, and allowing more general -sets of instance declarations. -</para> -</sect4> -</sect3> -</sect2> - -<sect2 id="instance-decls"> -<title>Instance declarations</title> - -<para>An instance declaration has the form -<screen> - instance ( <replaceable>assertion</replaceable><subscript>1</subscript>, ..., <replaceable>assertion</replaceable><subscript>n</subscript>) => <replaceable>class</replaceable> <replaceable>type</replaceable><subscript>1</subscript> ... <replaceable>type</replaceable><subscript>m</subscript> where ... -</screen> -The part before the "<literal>=></literal>" is the -<emphasis>context</emphasis>, while the part after the -"<literal>=></literal>" is the <emphasis>head</emphasis> of the instance declaration. -</para> - -<sect3 id="instance-resolution"> -<title>Instance resolution</title> - -<para> -When GHC tries to resolve, say, the constraint <literal>C Int Bool</literal>, -it tries to match every instance declaration against the -constraint, -by instantiating the head of the instance declaration. Consider -these declarations: -<programlisting> - instance context1 => C Int a where ... -- (A) - instance context2 => C a Bool where ... -- (B) -</programlisting> -GHC's default behaviour is that <emphasis>exactly one instance must match the -constraint it is trying to resolve</emphasis>. -For example, the constraint <literal>C Int Bool</literal> matches instances (A) and (B), -and hence would be rejected; while <literal>C Int Char</literal> matches only (A) -and hence (A) is chosen.</para> - -<para> -Notice that -<itemizedlist> -<listitem><para> -When matching, GHC takes -no account of the context of the instance declaration -(<literal>context1</literal> etc). -</para></listitem> -<listitem><para> -It is fine for there to be a <emphasis>potential</emphasis> of overlap (by -including both declarations (A) and (B), say); an error is only reported if a -particular constraint matches more than one. -</para></listitem> -</itemizedlist> -See also <xref linkend="instance-overlap"/> for flags that loosen the -instance resolution rules. -</para> - -</sect3> - -<sect3 id="flexible-instance-head"> -<title>Relaxed rules for the instance head</title> - -<para> -In Haskell 98 the head of an instance declaration -must be of the form <literal>C (T a1 ... an)</literal>, where -<literal>C</literal> is the class, <literal>T</literal> is a data type constructor, -and the <literal>a1 ... an</literal> are distinct type variables. -In the case of multi-parameter type classes, this rule applies to each parameter of -the instance head. (Arguably it should be OK if just one has this form and the others -are type variables, but that's the rules at the moment.)</para> - -<para>GHC relaxes this rule in two ways. -<itemizedlist> -<listitem><para> -With the <option>-XTypeSynonymInstances</option> flag, instance heads may use type -synonyms. As always, using a type synonym is just shorthand for -writing the RHS of the type synonym definition. For example: -<programlisting> - type Point a = (a,a) - instance C (Point a) where ... -</programlisting> -is legal. The instance declaration is equivalent to -<programlisting> - instance C (a,a) where ... -</programlisting> -As always, type synonyms -must be fully applied. You cannot, for example, write: -<programlisting> - instance Monad Point where ... -</programlisting> -</para></listitem> - -<listitem> -<para> -The <option>-XFlexibleInstances</option> flag allows the head of the instance -declaration to mention arbitrary nested types. -For example, this becomes a legal instance declaration -<programlisting> - instance C (Maybe Int) where ... -</programlisting> -See also the <link linkend="instance-overlap">rules on overlap</link>. -</para> -<para> -The <option>-XFlexibleInstances</option> flag implies <option>-XTypeSynonymInstances</option>. -</para></listitem> -</itemizedlist> -</para> -<para> -However, the instance declaration must still conform to the rules for instance -termination: see <xref linkend="instance-termination"/>. -</para> -</sect3> - -<sect3 id="instance-rules"> -<title>Relaxed rules for instance contexts</title> - -<para>In Haskell 98, the class constraints in the context of the instance declaration -must be of the form <literal>C a</literal> where <literal>a</literal> -is a type variable that occurs in the head. -</para> - -<para> -The <option>-XFlexibleContexts</option> flag relaxes this rule, as well -as relaxing the corresponding rule for type signatures (see <xref linkend="flexible-contexts"/>). -Specifically, <option>-XFlexibleContexts</option>, allows (well-kinded) class constraints -of form <literal>(C t1 ... tn)</literal> in the context of an instance declaration. -</para> -<para> -Notice that the flag does not affect equality constraints in an instance context; -they are permitted by <option>-XTypeFamilies</option> or <option>-XGADTs</option>. -</para> -<para> -However, the instance declaration must still conform to the rules for instance -termination: see <xref linkend="instance-termination"/>. -</para> - -</sect3> - -<sect3 id="instance-termination"> -<title>Instance termination rules</title> - -<para> -Regardless of <option>-XFlexibleInstances</option> and <option>-XFlexibleContexts</option>, -instance declarations must conform to some rules that ensure that instance resolution -will terminate. The restrictions can be lifted with <option>-XUndecidableInstances</option> -(see <xref linkend="undecidable-instances"/>). -</para> -<para> -The rules are these: -<orderedlist> -<listitem><para> -The Paterson Conditions: for each class constraint <literal>(C t1 ... tn)</literal> in the context -<orderedlist> -<listitem><para>No type variable has more occurrences in the constraint than in the head</para></listitem> -<listitem><para>The constraint has fewer constructors and variables (taken together - and counting repetitions) than the head -</para></listitem> -<listitem><para>The constraint mentions no type functions. -A type function application can in principle expand to a -type of arbitrary size, and so are rejected out of hand -</para></listitem> -</orderedlist> -</para></listitem> - -<listitem><para>The Coverage Condition. For each functional dependency, -<replaceable>tvs</replaceable><subscript>left</subscript> <literal>-></literal> -<replaceable>tvs</replaceable><subscript>right</subscript>, of the class, -every type variable in -S(<replaceable>tvs</replaceable><subscript>right</subscript>) must appear in -S(<replaceable>tvs</replaceable><subscript>left</subscript>), where S is the -substitution mapping each type variable in the class declaration to the -corresponding type in the instance head. -</para></listitem> -</orderedlist> -These restrictions ensure that instance resolution terminates: each reduction -step makes the problem smaller by at least one -constructor. -You can find lots of background material about the reason for these -restrictions in the paper <ulink -url="http://research.microsoft.com/%7Esimonpj/papers/fd%2Dchr/"> -Understanding functional dependencies via Constraint Handling Rules</ulink>. -</para> -<para> -For example, these are OK: -<programlisting> - instance C Int [a] -- Multiple parameters - instance Eq (S [a]) -- Structured type in head - - -- Repeated type variable in head - instance C4 a a => C4 [a] [a] - instance Stateful (ST s) (MutVar s) - - -- Head can consist of type variables only - instance C a - instance (Eq a, Show b) => C2 a b - - -- Non-type variables in context - instance Show (s a) => Show (Sized s a) - instance C2 Int a => C3 Bool [a] - instance C2 Int a => C3 [a] b -</programlisting> -But these are not: -<programlisting> - -- Context assertion no smaller than head - instance C a => C a where ... - -- (C b b) has more occurrences of b than the head - instance C b b => Foo [b] where ... -</programlisting> -</para> - -<para> -The same restrictions apply to instances generated by -<literal>deriving</literal> clauses. Thus the following is accepted: -<programlisting> - data MinHeap h a = H a (h a) - deriving (Show) -</programlisting> -because the derived instance -<programlisting> - instance (Show a, Show (h a)) => Show (MinHeap h a) -</programlisting> -conforms to the above rules. -</para> - -<para> -A useful idiom permitted by the above rules is as follows. -If one allows overlapping instance declarations then it's quite -convenient to have a "default instance" declaration that applies if -something more specific does not: -<programlisting> - instance C a where - op = ... -- Default -</programlisting> -</para> -</sect3> - -<sect3 id="undecidable-instances"> -<title>Undecidable instances</title> - -<para> -Sometimes even the termination rules of <xref linkend="instance-termination"/> are too onerous. -So GHC allows you to experiment with more liberal rules: if you use -the experimental flag <option>-XUndecidableInstances</option> -<indexterm><primary>-XUndecidableInstances</primary></indexterm>, -both the Paterson Conditions and the Coverage Condition -(described in <xref linkend="instance-termination"/>) are lifted. -Termination is still ensured by having a -fixed-depth recursion stack. If you exceed the stack depth you get a -sort of backtrace, and the opportunity to increase the stack depth -with <option>-freduction-depth=</option><emphasis>N</emphasis>. -However, if you should exceed the default reduction depth limit, -it is probably best just to disable depth checking, with -<option>-freduction-depth=0</option>. The exact depth your program -requires depends on minutiae of your code, and it may change between -minor GHC releases. The safest bet for released code -- if you're sure -that it should compile in finite time -- is just to disable the check. -</para> - -<para> -For example, sometimes you might want to use the following to get the -effect of a "class synonym": -<programlisting> - class (C1 a, C2 a, C3 a) => C a where { } - - instance (C1 a, C2 a, C3 a) => C a where { } -</programlisting> -This allows you to write shorter signatures: -<programlisting> - f :: C a => ... -</programlisting> -instead of -<programlisting> - f :: (C1 a, C2 a, C3 a) => ... -</programlisting> -The restrictions on functional dependencies (<xref -linkend="functional-dependencies"/>) are particularly troublesome. -It is tempting to introduce type variables in the context that do not appear in -the head, something that is excluded by the normal rules. For example: -<programlisting> - class HasConverter a b | a -> b where - convert :: a -> b - - data Foo a = MkFoo a - - instance (HasConverter a b,Show b) => Show (Foo a) where - show (MkFoo value) = show (convert value) -</programlisting> -This is dangerous territory, however. Here, for example, is a program that would make the -typechecker loop: -<programlisting> - class D a - class F a b | a->b - instance F [a] [[a]] - instance (D c, F a c) => D [a] -- 'c' is not mentioned in the head -</programlisting> -Similarly, it can be tempting to lift the coverage condition: -<programlisting> - class Mul a b c | a b -> c where - (.*.) :: a -> b -> c - - instance Mul Int Int Int where (.*.) = (*) - instance Mul Int Float Float where x .*. y = fromIntegral x * y - instance Mul a b c => Mul a [b] [c] where x .*. v = map (x.*.) v -</programlisting> -The third instance declaration does not obey the coverage condition; -and indeed the (somewhat strange) definition: -<programlisting> - f = \ b x y -> if b then x .*. [y] else y -</programlisting> -makes instance inference go into a loop, because it requires the constraint -<literal>(Mul a [b] b)</literal>. -</para> - -<para> -The <option>-XUndecidableInstances</option> flag is also used to lift some of the -restrictions imposed on type family instances. See <xref linkend="type-family-decidability"/>. -</para> - -</sect3> - - -<sect3 id="instance-overlap"> -<title>Overlapping instances</title> - -<para> -In general, as discussed in <xref linkend="instance-resolution"/>, -<emphasis>GHC requires that it be unambiguous which instance -declaration -should be used to resolve a type-class constraint</emphasis>. -GHC also provides a way to to loosen -the instance resolution, by -allowing more than one instance to match, <emphasis>provided there is a most -specific one</emphasis>. Moreover, it can be loosened further, by allowing more than one instance to match -irrespective of whether there is a most specific one. -This section gives the details. -</para> -<para> -To control the choice of instance, it is possible to specify the overlap behavior for individual -instances with a pragma, written immediately after the -<literal>instance</literal> keyword. The pragma may be one of: -<literal>{-# OVERLAPPING #-}</literal>, -<literal>{-# OVERLAPPABLE #-}</literal>, -<literal>{-# OVERLAPS #-}</literal>, -or <literal>{-# INCOHERENT #-}</literal>. -</para> -<para> -The matching behaviour is also influenced by two module-level language extension flags: <option>-XOverlappingInstances</option> -<indexterm><primary>-XOverlappingInstances -</primary></indexterm> -and <option>-XIncoherentInstances</option> -<indexterm><primary>-XIncoherentInstances -</primary></indexterm>. These flags are now deprecated (since GHC 7.10) in favour of -the fine-grained per-instance pragmas. -</para> - -<para> -A more precise specification is as follows. -The willingness to be overlapped or incoherent is a property of -the <emphasis>instance declaration</emphasis> itself, controlled as follows: -<itemizedlist> -<listitem><para>An instance is <emphasis>incoherent</emphasis> if: it has an <literal>INCOHERENT</literal> pragma; or if the instance has no pragma and it appears in a module compiled with <literal>-XIncoherentInstances</literal>. -</para></listitem> -<listitem><para>An instance is <emphasis>overlappable</emphasis> if: it has an <literal>OVERLAPPABLE</literal> or <literal>OVERLAPS</literal> pragma; or if the instance has no pragma and it appears in a module compiled with <literal>-XOverlappingInstances</literal>; or if the instance is incoherent. -</para></listitem> -<listitem><para>An instance is <emphasis>overlapping</emphasis> if: it has an <literal>OVERLAPPING</literal> or <literal>OVERLAPS</literal> pragma; or if the instance has no pragma and it appears in a module compiled with <literal>-XOverlappingInstances</literal>; or if the instance is incoherent. -</para></listitem> -</itemizedlist> -</para> - -<para> -Now suppose that, in some client module, we are searching for an instance of the -<emphasis>target constraint</emphasis> <literal>(C ty1 .. tyn)</literal>. -The search works like this. -<itemizedlist> -<listitem><para> -Find all instances I that <emphasis>match</emphasis> the target constraint; -that is, the target constraint is a substitution instance of I. These -instance declarations are the <emphasis>candidates</emphasis>. -</para></listitem> - -<listitem><para> -Eliminate any candidate IX for which both of the following hold: - -<itemizedlist> - <listitem><para>There is another candidate IY that is strictly more specific; - that is, IY is a substitution instance of IX but not vice versa. - </para></listitem> - <listitem><para> - Either IX is <emphasis>overlappable</emphasis>, or IY is - <emphasis>overlapping</emphasis>. (This "either/or" design, rather than a "both/and" design, - allow a client to deliberately override an instance from a library, without requiring a change to the library.) - </para></listitem> - </itemizedlist> -</para> -</listitem> - -<listitem><para> -If exactly one non-incoherent candidate remains, select it. If all -remaining candidates are incoherent, select an arbitrary -one. Otherwise the search fails (i.e. when more than one surviving candidate is not incoherent). -</para></listitem> - -<listitem><para> -If the selected candidate (from the previous step) is incoherent, the search succeeds, returning that candidate. -</para></listitem> - -<listitem><para> -If not, find all instances that <emphasis>unify</emphasis> with the target -constraint, but do not <emphasis>match</emphasis> it. -Such non-candidate instances might match when the target constraint is further -instantiated. If all of them are incoherent, the search succeeds, returning the selected candidate; -if not, the search fails. -</para></listitem> - -</itemizedlist> -Notice that these rules are not influenced by flag settings in the client module, where -the instances are <emphasis>used</emphasis>. -These rules make it possible for a library author to design a library that relies on -overlapping instances without the client having to know. -</para> -<para> -Errors are reported <emphasis>lazily</emphasis> (when attempting to solve a constraint), rather than <emphasis>eagerly</emphasis> -(when the instances themselves are defined). Consider, for example -<programlisting> - instance C Int b where .. - instance C a Bool where .. -</programlisting> -These potentially overlap, but GHC will not complain about the instance declarations -themselves, regardless of flag settings. If we later try to solve the constraint -<literal>(C Int Char)</literal> then only the first instance matches, and all is well. -Similarly with <literal>(C Bool Bool)</literal>. But if we try to solve <literal>(C Int Bool)</literal>, -both instances match and an error is reported. -</para> - -<para> -As a more substantial example of the rules in action, consider -<programlisting> - instance {-# OVERLAPPABLE #-} context1 => C Int b where ... -- (A) - instance {-# OVERLAPPABLE #-} context2 => C a Bool where ... -- (B) - instance {-# OVERLAPPABLE #-} context3 => C a [b] where ... -- (C) - instance {-# OVERLAPPING #-} context4 => C Int [Int] where ... -- (D) -</programlisting> -Now suppose that the type inference -engine needs to solve the constraint -<literal>C Int [Int]</literal>. This constraint matches instances (A), (C) and (D), but the last -is more specific, and hence is chosen. -</para> -<para>If (D) did not exist then (A) and (C) would still be matched, but neither is -most specific. In that case, the program would be rejected, unless -<option>-XIncoherentInstances</option> is enabled, in which case it would be accepted and (A) or -(C) would be chosen arbitrarily. -</para> -<para> -An instance declaration is <emphasis>more specific</emphasis> than another iff -the head of former is a substitution instance of the latter. For example -(D) is "more specific" than (C) because you can get from (C) to (D) by -substituting <literal>a:=Int</literal>. -</para> -<para> -GHC is conservative about committing to an overlapping instance. For example: -<programlisting> - f :: [b] -> [b] - f x = ... -</programlisting> -Suppose that from the RHS of <literal>f</literal> we get the constraint -<literal>C b [b]</literal>. But -GHC does not commit to instance (C), because in a particular -call of <literal>f</literal>, <literal>b</literal> might be instantiate -to <literal>Int</literal>, in which case instance (D) would be more specific still. -So GHC rejects the program.</para> -<para> -If, however, you add the flag <option>-XIncoherentInstances</option> when -compiling the module that contains (D), GHC will instead pick (C), without -complaining about the problem of subsequent instantiations. -</para> -<para> -Notice that we gave a type signature to <literal>f</literal>, so GHC had to -<emphasis>check</emphasis> that <literal>f</literal> has the specified type. -Suppose instead we do not give a type signature, asking GHC to <emphasis>infer</emphasis> -it instead. In this case, GHC will refrain from -simplifying the constraint <literal>C Int [b]</literal> (for the same reason -as before) but, rather than rejecting the program, it will infer the type -<programlisting> - f :: C b [b] => [b] -> [b] -</programlisting> -That postpones the question of which instance to pick to the -call site for <literal>f</literal> -by which time more is known about the type <literal>b</literal>. -You can write this type signature yourself if you use the -<link linkend="flexible-contexts"><option>-XFlexibleContexts</option></link> -flag. -</para> -<para> -Exactly the same situation can arise in instance declarations themselves. Suppose we have -<programlisting> - class Foo a where - f :: a -> a - instance Foo [b] where - f x = ... -</programlisting> -and, as before, the constraint <literal>C Int [b]</literal> arises from <literal>f</literal>'s -right hand side. GHC will reject the instance, complaining as before that it does not know how to resolve -the constraint <literal>C Int [b]</literal>, because it matches more than one instance -declaration. The solution is to postpone the choice by adding the constraint to the context -of the instance declaration, thus: -<programlisting> - instance C Int [b] => Foo [b] where - f x = ... -</programlisting> -(You need <link linkend="instance-rules"><option>-XFlexibleInstances</option></link> to do this.) -</para> -<para> -Warning: overlapping instances must be used with care. They -can give rise to incoherence (i.e. different instance choices are made -in different parts of the program) even without <option>-XIncoherentInstances</option>. Consider: -<programlisting> -{-# LANGUAGE OverlappingInstances #-} -module Help where - - class MyShow a where - myshow :: a -> String - - instance MyShow a => MyShow [a] where - myshow xs = concatMap myshow xs - - showHelp :: MyShow a => [a] -> String - showHelp xs = myshow xs - -{-# LANGUAGE FlexibleInstances, OverlappingInstances #-} -module Main where - import Help - - data T = MkT - - instance MyShow T where - myshow x = "Used generic instance" - - instance MyShow [T] where - myshow xs = "Used more specific instance" - - main = do { print (myshow [MkT]); print (showHelp [MkT]) } -</programlisting> -In function <literal>showHelp</literal> GHC sees no overlapping -instances, and so uses the <literal>MyShow [a]</literal> instance -without complaint. In the call to <literal>myshow</literal> in <literal>main</literal>, -GHC resolves the <literal>MyShow [T]</literal> constraint using the overlapping -instance declaration in module <literal>Main</literal>. As a result, -the program prints -<programlisting> - "Used more specific instance" - "Used generic instance" -</programlisting> -(An alternative possible behaviour, not currently implemented, -would be to reject module <literal>Help</literal> -on the grounds that a later instance declaration might overlap the local one.) -</para> -</sect3> - -<sect3 id="instance-sigs"> -<title>Instance signatures: type signatures in instance declarations</title> -<para>In Haskell, you can't write a type signature in an instance declaration, but it -is sometimes convenient to do so, and the language extension <option>-XInstanceSigs</option> -allows you to do so. For example: -<programlisting> - data T a = MkT a a - instance Eq a => Eq (T a) where - (==) :: T a -> T a -> Bool -- The signature - (==) (MkT x1 x2) (MkTy y1 y2) = x1==y1 && x2==y2 -</programlisting> -</para> -Some details -<itemizedlist> -<listitem><para> -The type signature in the instance declaration must be more polymorphic than (or the same as) -the one in the class declaration, instantiated with the instance type. -For example, this is fine: -<programlisting> - instance Eq a => Eq (T a) where - (==) :: forall b. b -> b -> Bool - (==) x y = True -</programlisting> -Here the signature in the instance declaration is more polymorphic than that -required by the instantiated class method. -</para> -</listitem> - -<listitem><para> -The code for the method in the instance declaration is typechecked against the type signature -supplied in the instance declaration, as you would expect. So if the instance signature -is more polymorphic than required, the code must be too. -</para></listitem> - -<listitem><para> -One stylistic reason for wanting to write a type signature is simple documentation. Another -is that you may want to bring scoped type variables into scope. For example: -<programlisting> -class C a where - foo :: b -> a -> (a, [b]) - -instance C a => C (T a) where - foo :: forall b. b -> T a -> (T a, [b]) - foo x (T y) = (T y, xs) - where - xs :: [b] - xs = [x,x,x] -</programlisting> -Provided that you also specify <option>-XScopedTypeVariables</option> -(<xref linkend="scoped-type-variables"/>), -the <literal>forall b</literal> scopes over the definition of <literal>foo</literal>, -and in particular over the type signature for <literal>xs</literal>. -</para></listitem> -</itemizedlist> -</sect3> - -</sect2> - -<sect2 id="overloaded-strings"> -<title>Overloaded string literals -</title> - -<para> -GHC supports <emphasis>overloaded string literals</emphasis>. Normally a -string literal has type <literal>String</literal>, but with overloaded string -literals enabled (with <literal>-XOverloadedStrings</literal>) - a string literal has type <literal>(IsString a) => a</literal>. -</para> -<para> - This means that the usual string syntax can be used, e.g., - for <literal>ByteString</literal>, <literal>Text</literal>, -and other variations of string like types. String literals behave very much -like integer literals, i.e., they can be used in both expressions and patterns. -If used in a pattern the literal with be replaced by an equality test, in the same -way as an integer literal is. -</para> -<para> -The class <literal>IsString</literal> is defined as: -<programlisting> -class IsString a where - fromString :: String -> a -</programlisting> -The only predefined instance is the obvious one to make strings work as usual: -<programlisting> -instance IsString [Char] where - fromString cs = cs -</programlisting> -The class <literal>IsString</literal> is not in scope by default. If you want to mention -it explicitly (for example, to give an instance declaration for it), you can import it -from module <literal>GHC.Exts</literal>. -</para> -<para> -Haskell's defaulting mechanism (<ulink url="http://www.haskell.org/onlinereport/decls.html#sect4.3.4">Haskell Report, Section 4.3.4</ulink>) -is extended to cover string literals, when <option>-XOverloadedStrings</option> is specified. -Specifically: -<itemizedlist> -<listitem><para> -Each type in a <literal>default</literal> declaration must be an -instance of <literal>Num</literal> <emphasis>or</emphasis> of <literal>IsString</literal>. -</para></listitem> - -<listitem><para> -If no <literal>default</literal> declaration is given, then it is just as if the module -contained the declaration <literal>default( Integer, Double, String)</literal>. -</para></listitem> - -<listitem><para> -The standard defaulting rule -is extended thus: defaulting applies when all the unresolved constraints involve standard classes -<emphasis>or</emphasis> <literal>IsString</literal>; and at least one is a numeric class -<emphasis>or</emphasis> <literal>IsString</literal>. -</para></listitem> -</itemizedlist> -So, for example, the expression <literal>length "foo"</literal> will give rise -to an ambiguous use of <literal>IsString a0</literal> which, because of the above -rules, will default to <literal>String</literal>. -</para> -<para> -A small example: -<programlisting> -module Main where - -import GHC.Exts( IsString(..) ) - -newtype MyString = MyString String deriving (Eq, Show) -instance IsString MyString where - fromString = MyString - -greet :: MyString -> MyString -greet "hello" = "world" -greet other = other - -main = do - print $ greet "hello" - print $ greet "fool" -</programlisting> -</para> -<para> -Note that deriving <literal>Eq</literal> is necessary for the pattern matching -to work since it gets translated into an equality comparison. -</para> -</sect2> - -<sect2 id="overloaded-lists"> -<title>Overloaded lists</title> - -<para> GHC supports <emphasis>overloading of the list notation</emphasis>. -Let us recap the notation for -constructing lists. In Haskell, the list notation can be be used in the -following seven ways: - -<programlisting> -[] -- Empty list -[x] -- x : [] -[x,y,z] -- x : y : z : [] -[x .. ] -- enumFrom x -[x,y ..] -- enumFromThen x y -[x .. y] -- enumFromTo x y -[x,y .. z] -- enumFromThenTo x y z -</programlisting> - -When the <option>OverloadedLists</option> extension is turned on, the -aforementioned seven notations are desugared as follows: </para> - -<programlisting> -[] -- fromListN 0 [] -[x] -- fromListN 1 (x : []) -[x,y,z] -- fromListN 3 (x : y : z : []) -[x .. ] -- fromList (enumFrom x) -[x,y ..] -- fromList (enumFromThen x y) -[x .. y] -- fromList (enumFromTo x y) -[x,y .. z] -- fromList (enumFromThenTo x y z) -</programlisting> - -<para> This extension allows programmers to use the list notation for -construction of structures like: <literal>Set</literal>, -<literal>Map</literal>, <literal>IntMap</literal>, <literal>Vector</literal>, -<literal>Text</literal> and <literal>Array</literal>. The following code -listing gives a few examples:</para> - -<programlisting> -['0' .. '9'] :: Set Char -[1 .. 10] :: Vector Int -[("default",0), (k1,v1)] :: Map String Int -['a' .. 'z'] :: Text -</programlisting> -<para> -List patterns are also overloaded. When the <option>OverloadedLists</option> -extension is turned on, these definitions are desugared as follows -<programlisting> -f [] = ... -- f (toList -> []) = ... -g [x,y,z] = ... -- g (toList -> [x,y,z]) = ... -</programlisting> -(Here we are using view-pattern syntax for the translation, see <xref linkend="view-patterns"/>.) -</para> - -<sect3> -<title>The <literal>IsList</literal> class</title> - -<para>In the above desugarings, the functions <literal>toList</literal>, -<literal>fromList</literal> and <literal>fromListN</literal> are all -methods of -the <literal>IsList</literal> class, which is itself exported from -the <literal>GHC.Exts</literal> module. -The type class is defined as follows:</para> - -<programlisting> -class IsList l where - type Item l - - fromList :: [Item l] -> l - toList :: l -> [Item l] - - fromListN :: Int -> [Item l] -> l - fromListN _ = fromList -</programlisting> - -<para>The <literal>IsList</literal> class and its methods are intended to be -used in conjunction with the <option>OverloadedLists</option> extension. -<itemizedlist> -<listitem> <para> The type function -<literal>Item</literal> returns the type of items of the -structure <literal>l</literal>. -</para></listitem> -<listitem><para> -The function <literal>fromList</literal> -constructs the structure <literal>l</literal> from the given list of -<literal>Item l</literal>. -</para></listitem> -<listitem><para> -The function <literal>fromListN</literal> takes the -input list's length as a hint. Its behaviour should be equivalent to -<literal>fromList</literal>. The hint can be used for more efficient -construction of the structure <literal>l</literal> compared to -<literal>fromList</literal>. If the given hint is not equal to the input -list's length the behaviour of <literal>fromListN</literal> is not -specified. -</para></listitem> -<listitem><para> -The function <literal>toList</literal> should be -the inverse of <literal>fromList</literal>. -</para></listitem> -</itemizedlist> -</para> -<para>It is perfectly fine to declare new instances -of <literal>IsList</literal>, so that list notation becomes -useful for completely new data types. -Here are several example instances: -<programlisting> -instance IsList [a] where - type Item [a] = a - fromList = id - toList = id - -instance (Ord a) => IsList (Set a) where - type Item (Set a) = a - fromList = Set.fromList - toList = Set.toList - -instance (Ord k) => IsList (Map k v) where - type Item (Map k v) = (k,v) - fromList = Map.fromList - toList = Map.toList - -instance IsList (IntMap v) where - type Item (IntMap v) = (Int,v) - fromList = IntMap.fromList - toList = IntMap.toList - -instance IsList Text where - type Item Text = Char - fromList = Text.pack - toList = Text.unpack - -instance IsList (Vector a) where - type Item (Vector a) = a - fromList = Vector.fromList - fromListN = Vector.fromListN - toList = Vector.toList -</programlisting> -</para> -</sect3> - -<sect3> -<title>Rebindable syntax</title> - -<para> When desugaring list notation with <option>-XOverloadedLists</option> -GHC uses the <literal>fromList</literal> (etc) methods from module <literal>GHC.Exts</literal>. -You do not need to import <literal>GHC.Exts</literal> for this to happen. -</para> -<para> However if you use <option>-XRebindableSyntax</option>, then -GHC instead uses whatever is in -scope with the names of <literal>toList</literal>, <literal>fromList</literal> and -<literal>fromListN</literal>. That is, these functions are rebindable; -c.f. <xref linkend="rebindable-syntax"/>. </para> -</sect3> - -<sect3> -<title>Defaulting</title> - -<para>Currently, the <literal>IsList</literal> class is not accompanied with -defaulting rules. Although feasible, not much thought has gone into how to -specify the meaning of the default declarations like:</para> - -<programlisting> -default ([a]) -</programlisting> -</sect3> - -<sect3> -<title>Speculation about the future</title> - - -<para>The current implementation of the <option>OverloadedLists</option> -extension can be improved by handling the lists that are only populated with -literals in a special way. More specifically, the compiler could allocate such -lists statically using a compact representation and allow -<literal>IsList</literal> instances to take advantage of the compact -representation. Equipped with this capability the -<option>OverloadedLists</option> extension will be in a good position to -subsume the <option>OverloadedStrings</option> extension (currently, as a -special case, string literals benefit from statically allocated compact -representation).</para> -</sect3> -</sect2> - -</sect1> - -<sect1 id="type-families"> -<title>Type families</title> - -<para> - <firstterm>Indexed type families</firstterm> form an extension to - facilitate type-level - programming. Type families are a generalisation of <firstterm>associated - data types</firstterm> - (“<ulink url="http://www.cse.unsw.edu.au/~chak/papers/CKPM05.html">Associated - Types with Class</ulink>”, M. Chakravarty, G. Keller, S. Peyton Jones, - and S. Marlow. In Proceedings of “The 32nd Annual ACM SIGPLAN-SIGACT - Symposium on Principles of Programming Languages (POPL'05)”, pages - 1-13, ACM Press, 2005) and <firstterm>associated type synonyms</firstterm> - (“<ulink url="http://www.cse.unsw.edu.au/~chak/papers/CKP05.html">Type - Associated Type Synonyms</ulink>”. M. Chakravarty, G. Keller, and - S. Peyton Jones. - In Proceedings of “The Tenth ACM SIGPLAN International Conference on - Functional Programming”, ACM Press, pages 241-253, 2005). Type families - themselves are described in the paper “<ulink - url="http://www.cse.unsw.edu.au/~chak/papers/SPCS08.html">Type - Checking with Open Type Functions</ulink>”, T. Schrijvers, - S. Peyton-Jones, - M. Chakravarty, and M. Sulzmann, in Proceedings of “ICFP 2008: The - 13th ACM SIGPLAN International Conference on Functional - Programming”, ACM Press, pages 51-62, 2008. Type families - essentially provide type-indexed data types and named functions on types, - which are useful for generic programming and highly parameterised library - interfaces as well as interfaces with enhanced static information, much like - dependent types. They might also be regarded as an alternative to functional - dependencies, but provide a more functional style of type-level programming - than the relational style of functional dependencies. -</para> -<para> - Indexed type families, or type families for short, are type constructors that - represent sets of types. Set members are denoted by supplying the type family - constructor with type parameters, which are called <firstterm>type - indices</firstterm>. The - difference between vanilla parametrised type constructors and family - constructors is much like between parametrically polymorphic functions and - (ad-hoc polymorphic) methods of type classes. Parametric polymorphic functions - behave the same at all type instances, whereas class methods can change their - behaviour in dependence on the class type parameters. Similarly, vanilla type - constructors imply the same data representation for all type instances, but - family constructors can have varying representation types for varying type - indices. -</para> -<para> - Indexed type families come in three flavours: <firstterm>data - families</firstterm>, <firstterm>open type synonym families</firstterm>, and - <firstterm>closed type synonym families</firstterm>. They are the indexed - family variants of algebraic data types and type synonyms, respectively. The - instances of data families can be data types and newtypes. -</para> -<para> - Type families are enabled by the flag <option>-XTypeFamilies</option>. - Additional information on the use of type families in GHC is available on - <ulink url="http://www.haskell.org/haskellwiki/GHC/Indexed_types">the - Haskell wiki page on type families</ulink>. -</para> - -<sect2 id="data-families"> - <title>Data families</title> - - <para> - Data families appear in two flavours: (1) they can be defined on the - toplevel - or (2) they can appear inside type classes (in which case they are known as - associated types). The former is the more general variant, as it lacks the - requirement for the type-indexes to coincide with the class - parameters. However, the latter can lead to more clearly structured code and - compiler warnings if some type instances were - possibly accidentally - - omitted. In the following, we always discuss the general toplevel form first - and then cover the additional constraints placed on associated types. - </para> - - <sect3 id="data-family-declarations"> - <title>Data family declarations</title> - - <para> - Indexed data families are introduced by a signature, such as -<programlisting> -data family GMap k :: * -> * -</programlisting> - The special <literal>family</literal> distinguishes family from standard - data declarations. The result kind annotation is optional and, as - usual, defaults to <literal>*</literal> if omitted. An example is -<programlisting> -data family Array e -</programlisting> - Named arguments can also be given explicit kind signatures if needed. - Just as with - [http://www.haskell.org/ghc/docs/latest/html/users_guide/gadt.html GADT - declarations] named arguments are entirely optional, so that we can - declare <literal>Array</literal> alternatively with -<programlisting> -data family Array :: * -> * -</programlisting> - </para> - </sect3> - - <sect3 id="data-instance-declarations"> - <title>Data instance declarations</title> - - <para> - Instance declarations of data and newtype families are very similar to - standard data and newtype declarations. The only two differences are - that the keyword <literal>data</literal> or <literal>newtype</literal> - is followed by <literal>instance</literal> and that some or all of the - type arguments can be non-variable types, but may not contain forall - types or type synonym families. However, data families are generally - allowed in type parameters, and type synonyms are allowed as long as - they are fully applied and expand to a type that is itself admissible - - exactly as this is required for occurrences of type synonyms in class - instance parameters. For example, the <literal>Either</literal> - instance for <literal>GMap</literal> is -<programlisting> -data instance GMap (Either a b) v = GMapEither (GMap a v) (GMap b v) -</programlisting> - In this example, the declaration has only one variant. In general, it - can be any number. - </para> - <para> - When the name of a type argument of a data or newtype instance - declaration doesn't matter, it can be replaced with an underscore - (<literal>_</literal>). This is the same as writing a type variable with - a unique name. -<programlisting> -data family F a b :: * -data instance F Int _ = Int --- Equivalent to -data instance F Int b = Int -</programlisting> - This resembles the wildcards that can be used in <xref - linkend="partial-type-signatures"/>. However, there are some - differences. Only anonymous wildcards are allowed in these instance - declarations, named and extra-constraints wildcards are not. No error - messages reporting the inferred types are generated, nor does the flag - <option>-XPartialTypeSignatures</option> have any effect. - </para> - <para> - Data and newtype instance declarations are only permitted when an - appropriate family declaration is in scope - just as a class instance declaration - requires the class declaration to be visible. Moreover, each instance - declaration has to conform to the kind determined by its family - declaration. This implies that the number of parameters of an instance - declaration matches the arity determined by the kind of the family. - </para> - <para> - A data family instance declaration can use the full expressiveness of - ordinary <literal>data</literal> or <literal>newtype</literal> declarations: - <itemizedlist> - <listitem><para> Although, a data family is <emphasis>introduced</emphasis> with - the keyword "<literal>data</literal>", a data family <emphasis>instance</emphasis> can - use either <literal>data</literal> or <literal>newtype</literal>. For example: -<programlisting> -data family T a -data instance T Int = T1 Int | T2 Bool -newtype instance T Char = TC Bool -</programlisting> - </para></listitem> - <listitem><para> A <literal>data instance</literal> can use GADT syntax for the data constructors, - and indeed can define a GADT. For example: -<programlisting> -data family G a b -data instance G [a] b where - G1 :: c -> G [Int] b - G2 :: G [a] Bool -</programlisting> - </para></listitem> - <listitem><para> You can use a <literal>deriving</literal> clause on a - <literal>data instance</literal> or <literal>newtype instance</literal> - declaration. - </para></listitem> - </itemizedlist> - </para> - - <para> - Even if data families are defined as toplevel declarations, functions - that perform different computations for different family instances may still - need to be defined as methods of type classes. In particular, the - following is not possible: -<programlisting> -data family T a -data instance T Int = A -data instance T Char = B -foo :: T a -> Int -foo A = 1 -- WRONG: These two equations together... -foo B = 2 -- ...will produce a type error. -</programlisting> -Instead, you would have to write <literal>foo</literal> as a class operation, thus: -<programlisting> -class Foo a where - foo :: T a -> Int -instance Foo Int where - foo A = 1 -instance Foo Char where - foo B = 2 -</programlisting> - (Given the functionality provided by GADTs (Generalised Algebraic Data - Types), it might seem as if a definition, such as the above, should be - feasible. However, type families are - in contrast to GADTs - are - <emphasis>open;</emphasis> i.e., new instances can always be added, - possibly in other - modules. Supporting pattern matching across different data instances - would require a form of extensible case construct.) - </para> - </sect3> - - <sect3 id="data-family-overlap"> - <title>Overlap of data instances</title> - <para> - The instance declarations of a data family used in a single program - may not overlap at all, independent of whether they are associated or - not. In contrast to type class instances, this is not only a matter - of consistency, but one of type safety. - </para> - </sect3> -</sect2> - -<sect2 id="synonym-families"> - <title>Synonym families</title> - - <para> - Type families appear in three flavours: (1) they can be defined as open - families on the toplevel, (2) they can be defined as closed families on - the toplevel, or (3) they can appear inside type classes (in which case - they are known as associated type synonyms). Toplevel families are more - general, as they lack the requirement for the type-indexes to coincide - with the class parameters. However, associated type synonyms can lead to - more clearly structured code and compiler warnings if some type instances - were - possibly accidentally - omitted. In the following, we always - discuss the general toplevel forms first and then cover the additional - constraints placed on associated types. Note that closed associated type - synonyms do not exist. - </para> - - <sect3 id="type-family-declarations"> - <title>Type family declarations</title> - - <para> - Open indexed type families are introduced by a signature, such as -<programlisting> -type family Elem c :: * -</programlisting> - The special <literal>family</literal> distinguishes family from standard - type declarations. The result kind annotation is optional and, as - usual, defaults to <literal>*</literal> if omitted. An example is -<programlisting> -type family Elem c -</programlisting> - Parameters can also be given explicit kind signatures if needed. We - call the number of parameters in a type family declaration, the family's - arity, and all applications of a type family must be fully saturated - w.r.t. to that arity. This requirement is unlike ordinary type synonyms - and it implies that the kind of a type family is not sufficient to - determine a family's arity, and hence in general, also insufficient to - determine whether a type family application is well formed. As an - example, consider the following declaration: -<programlisting> -type family F a b :: * -> * -- F's arity is 2, - -- although its overall kind is * -> * -> * -> * -</programlisting> - Given this declaration the following are examples of well-formed and - malformed types: -<programlisting> -F Char [Int] -- OK! Kind: * -> * -F Char [Int] Bool -- OK! Kind: * -F IO Bool -- WRONG: kind mismatch in the first argument -F Bool -- WRONG: unsaturated application -</programlisting> - </para> - - <para> - The result kind annotation is optional and defaults to - <literal>*</literal> (like argument kinds) if - omitted. Polykinded type families can be - declared using a parameter in the kind annotation: -<programlisting> -type family F a :: k -</programlisting> -In this case the kind parameter <literal>k</literal> is actually an implicit -parameter of the type family. - </para> - </sect3> - - <sect3 id="type-instance-declarations"> - <title>Type instance declarations</title> - <para> - Instance declarations of type families are very similar to - standard type synonym declarations. The only two differences are that - the keyword <literal>type</literal> is followed by - <literal>instance</literal> and that some or all of the type arguments - can be non-variable types, but may not contain forall types or type - synonym families. However, data families are generally allowed, and type - synonyms are allowed as long as they are fully applied and expand to a - type that is admissible - these are the exact same requirements as for - data instances. For example, the <literal>[e]</literal> instance for - <literal>Elem</literal> is -<programlisting> -type instance Elem [e] = e -</programlisting> - </para> - - <para> - Type arguments can be replaced with underscores (<literal>_</literal>) - if the names of the arguments don't matter. This is the same as writing - type variables with unique names. The same rules apply as for <xref - linkend="data-instance-declarations"/>. - </para> - - <para> - Type family instance declarations are only legitimate when an - appropriate family declaration is in scope - just like class instances - require the class declaration to be visible. Moreover, each instance - declaration has to conform to the kind determined by its family - declaration, and the number of type parameters in an instance - declaration must match the number of type parameters in the family - declaration. Finally, the right-hand side of a type instance must be a - monotype (i.e., it may not include foralls) and after the expansion of - all saturated vanilla type synonyms, no synonyms, except family synonyms - may remain. - </para> - </sect3> - - <sect3 id="closed-type-families"> - <title>Closed type families</title> - <para> - A type family can also be declared with a <literal>where</literal> clause, - defining the full set of equations for that family. For example: -<programlisting> -type family F a where - F Int = Double - F Bool = Char - F a = String -</programlisting> - A closed type family's equations are tried in order, from top to bottom, - when simplifying a type family application. In this example, we declare - an instance for <literal>F</literal> such that <literal>F Int</literal> - simplifies to <literal>Double</literal>, <literal>F Bool</literal> - simplifies to <literal>Char</literal>, and for any other type - <literal>a</literal> that is known not to be <literal>Int</literal> or - <literal>Bool</literal>, <literal>F a</literal> simplifies to - <literal>String</literal>. Note that GHC must be sure that - <literal>a</literal> cannot unify with <literal>Int</literal> or - <literal>Bool</literal> in that last case; if a programmer specifies - just <literal>F a</literal> in their code, GHC will not be able to - simplify the type. After all, <literal>a</literal> might later be - instantiated with <literal>Int</literal>. - </para> - - <para> - A closed type family's equations have the same restrictions as the - equations for open type family instances. - </para> - - <para> - A closed type family may be declared with no equations. Such - closed type families are opaque type-level definitions that will - never reduce, are not necessarily injective (unlike empty data - types), and cannot be given any instances. This is different - from omitting the equations of a closed type family in a - <filename>hs-boot</filename> file, which uses the syntax - <literal>where ..</literal>, as in that case there may or may - not be equations given in the <filename>hs</filename> file. - </para> - </sect3> - - <sect3 id="type-family-examples"> - <title>Type family examples</title> - <para> -Here are some examples of admissible and illegal type - instances: -<programlisting> -type family F a :: * -type instance F [Int] = Int -- OK! -type instance F String = Char -- OK! -type instance F (F a) = a -- WRONG: type parameter mentions a type family -type instance F (forall a. (a, b)) = b -- WRONG: a forall type appears in a type parameter -type instance F Float = forall a.a -- WRONG: right-hand side may not be a forall type -type family H a where -- OK! - H Int = Int - H Bool = Bool - H a = String -type instance H Char = Char -- WRONG: cannot have instances of closed family -type family K a where -- OK! - -type family G a b :: * -> * -type instance G Int = (,) -- WRONG: must be two type parameters -type instance G Int Char Float = Double -- WRONG: must be two type parameters -</programlisting> - </para> - </sect3> - <sect3 id="type-family-overlap"> - <title>Compatibility and apartness of type family equations</title> - <para> - There must be some restrictions on the equations of type families, lest - we define an ambiguous rewrite system. So, equations of open type families - are restricted to be <firstterm>compatible</firstterm>. Two type patterns - are compatible if -<orderedlist> -<listitem><para>all corresponding types and implicit kinds in the patterns are <firstterm>apart</firstterm>, or</para></listitem> -<listitem><para>the two patterns unify producing a substitution, and the right-hand sides are equal under that substitution.</para></listitem> -</orderedlist> - Two types are considered <firstterm>apart</firstterm> if, for all possible - substitutions, the types cannot reduce to a common reduct. - </para> - - <para> - The first clause of "compatible" is the more straightforward one. It says - that the patterns of two distinct type family instances cannot overlap. - For example, the following is disallowed: -<programlisting> -type instance F Int = Bool -type instance F Int = Char -</programlisting> - The second clause is a little more interesting. It says that two - overlapping type family instances are allowed if the right-hand - sides coincide in the region of overlap. Some examples help here: -<programlisting> -type instance F (a, Int) = [a] -type instance F (Int, b) = [b] -- overlap permitted - -type instance G (a, Int) = [a] -type instance G (Char, a) = [a] -- ILLEGAL overlap, as [Char] /= [Int] -</programlisting> - Note that this compatibility condition is independent of whether the type family - is associated or not, and it is not only a matter of consistency, but - one of type safety. </para> - - <para>For a polykinded type family, the kinds are checked for - apartness just like types. For example, the following is accepted: -<programlisting> -type family J a :: k -type instance J Int = Bool -type instance J Int = Maybe -</programlisting> - These instances are compatible because they differ in their implicit kind parameter; the first uses <literal>*</literal> while the second uses <literal>* -> *</literal>.</para> - - - <para> - The definition for "compatible" uses a notion of "apart", whose definition - in turn relies on type family reduction. This condition of "apartness", as - stated, is impossible to check, so we use this conservative approximation: - two types are considered to be apart when the two types cannot be unified, - even by a potentially infinite unifier. Allowing the unifier to be infinite - disallows the following pair of instances: -<programlisting> -type instance H x x = Int -type instance H [x] x = Bool -</programlisting> - The type patterns in this pair equal if <literal>x</literal> is replaced - by an infinite nesting of lists. Rejecting instances such as these is - necessary for type soundness. - </para> - - <para> - Compatibility also affects closed type families. When simplifying an - application of a closed type family, GHC will select an equation only - when it is sure that no incompatible previous equation will ever apply. - Here are some examples: -<programlisting> -type family F a where - F Int = Bool - F a = Char - -type family G a where - G Int = Int - G a = a -</programlisting> - In the definition for <literal>F</literal>, the two equations are - incompatible -- their patterns are not apart, and yet their - right-hand sides do not coincide. Thus, before GHC selects the - second equation, it must be sure that the first can never apply. So, - the type <literal>F a</literal> does not simplify; only a type such - as <literal>F Double</literal> will simplify to - <literal>Char</literal>. In <literal>G</literal>, on the other hand, - the two equations are compatible. Thus, GHC can ignore the first - equation when looking at the second. So, <literal>G a</literal> will - simplify to <literal>a</literal>.</para> - - <para> However see <xref linkend="ghci-decls"/> for the overlap rules in GHCi.</para> - </sect3> - - <sect3 id="type-family-decidability"> - <title>Decidability of type synonym instances</title> - <para> - In order to guarantee that type inference in the presence of type - families decidable, we need to place a number of additional - restrictions on the formation of type instance declarations (c.f., - Definition 5 (Relaxed Conditions) of “<ulink - url="http://www.cse.unsw.edu.au/~chak/papers/SPCS08.html">Type - Checking with Open Type Functions</ulink>”). Instance - declarations have the general form -<programlisting> -type instance F t1 .. tn = t -</programlisting> - where we require that for every type family application <literal>(G s1 - .. sm)</literal> in <literal>t</literal>, - <orderedlist> - <listitem> - <para><literal>s1 .. sm</literal> do not contain any type family - constructors,</para> - </listitem> - <listitem> - <para>the total number of symbols (data type constructors and type - variables) in <literal>s1 .. sm</literal> is strictly smaller than - in <literal>t1 .. tn</literal>, and</para> - </listitem> - <listitem> - <para>for every type - variable <literal>a</literal>, <literal>a</literal> occurs - in <literal>s1 .. sm</literal> at most as often as in <literal>t1 - .. tn</literal>.</para> - </listitem> - </orderedlist> - These restrictions are easily verified and ensure termination of type - inference. However, they are not sufficient to guarantee completeness - of type inference in the presence of, so called, ''loopy equalities'', - such as <literal>a ~ [F a]</literal>, where a recursive occurrence of - a type variable is underneath a family application and data - constructor application - see the above mentioned paper for details. - </para> - <para> - If the option <option>-XUndecidableInstances</option> is passed to the - compiler, the above restrictions are not enforced and it is on the - programmer to ensure termination of the normalisation of type families - during type inference. - </para> - </sect3> - </sect2> - - -<sect2 id="assoc-decl"> -<title>Associated data and type families</title> -<para> -A data or type synonym family can be declared as part of a type class, thus: -<programlisting> -class GMapKey k where - data GMap k :: * -> * - ... - -class Collects ce where - type Elem ce :: * - ... -</programlisting> -When doing so, we (optionally) may drop the "<literal>family</literal>" keyword. -</para> -<para> - The type parameters must all be type variables, of course, - and some (but not necessarily all) of then can be the class - parameters. Each class parameter may - only be used at most once per associated type, but some may be omitted - and they may be in an order other than in the class head. Hence, the - following contrived example is admissible: -<programlisting> - class C a b c where - type T c a x :: * -</programlisting> - Here <literal>c</literal> and <literal>a</literal> are class parameters, - but the type is also indexed on a third parameter <literal>x</literal>. - </para> - - <sect3 id="assoc-data-inst"> - <title>Associated instances</title> - <para> - When an associated data or type synonym family instance is declared within a type - class instance, we (optionally) may drop the <literal>instance</literal> keyword in the - family instance: -<programlisting> -instance (GMapKey a, GMapKey b) => GMapKey (Either a b) where - data GMap (Either a b) v = GMapEither (GMap a v) (GMap b v) - ... - -instance Eq (Elem [e]) => Collects [e] where - type Elem [e] = e - ... -</programlisting> -Note the following points: -<itemizedlist> -<listitem><para> - The type indexes corresponding to class parameters must have precisely the same shape - the type given in the instance head. To have the same "shape" means that - the two types are identical modulo renaming of type variables. For example: -<programlisting> -instance Eq (Elem [e]) => Collects [e] where - -- Choose one of the following alternatives: - type Elem [e] = e -- OK - type Elem [x] = x -- OK - type Elem x = x -- BAD; shape of 'x' is different to '[e]' - type Elem [Maybe x] = x -- BAD: shape of '[Maybe x]' is different to '[e]' -</programlisting> -</para></listitem> -<listitem><para> - An instances for an associated family can only appear as part of - an instance declarations of the class in which the family was declared, - just as with the equations of the methods of a class. -</para></listitem> -<listitem><para> - The instance for an associated type can be omitted in class instances. In that case, - unless there is a default instance (see <xref linkend="assoc-decl-defs"/>), - the corresponding instance type is not inhabited; - i.e., only diverging expressions, such - as <literal>undefined</literal>, can assume the type. -</para></listitem> -<listitem><para> - Although it is unusual, there (currently) can be <emphasis>multiple</emphasis> - instances for an associated family in a single instance declaration. - For example, this is legitimate: -<programlisting> -instance GMapKey Flob where - data GMap Flob [v] = G1 v - data GMap Flob Int = G2 Int - ... -</programlisting> - Here we give two data instance declarations, one in which the last - parameter is <literal>[v]</literal>, and one for which it is <literal>Int</literal>. - Since you cannot give any <emphasis>subsequent</emphasis> instances for - <literal>(GMap Flob ...)</literal>, this facility is most useful when - the free indexed parameter is of a kind with a finite number of alternatives - (unlike <literal>*</literal>). WARNING: this facility may be withdrawn in the future. -</para></listitem> -</itemizedlist> -</para> - </sect3> - - <sect3 id="assoc-decl-defs"> - <title>Associated type synonym defaults</title> - <para> - It is possible for the class defining the associated type to specify a - default for associated type instances. So for example, this is OK: -<programlisting> -class IsBoolMap v where - type Key v - type instance Key v = Int - - lookupKey :: Key v -> v -> Maybe Bool - -instance IsBoolMap [(Int, Bool)] where - lookupKey = lookup -</programlisting> -In an <literal>instance</literal> declaration for the class, if no explicit -<literal>type instance</literal> declaration is given for the associated type, the default declaration -is used instead, just as with default class methods. -</para> -<para> -Note the following points: -<itemizedlist> -<listitem><para> - The <literal>instance</literal> keyword is optional. -</para></listitem> -<listitem><para> - There can be at most one default declaration for an associated type synonym. -</para></listitem> -<listitem><para> - A default declaration is not permitted for an associated - <emphasis>data</emphasis> type. -</para></listitem> -<listitem><para> - The default declaration must mention only type <emphasis>variables</emphasis> on the left hand side, - and the right hand side must mention only type variables bound on the left hand side. - However, unlike the associated type family declaration itself, - the type variables of the default instance are independent of those of the parent class. -</para></listitem> -</itemizedlist> -Here are some examples: -<programlisting> - class C a where - type F1 a :: * - type instance F1 a = [a] -- OK - type instance F1 a = a->a -- BAD; only one default instance is allowed - - type F2 b a -- OK; note the family has more type - -- variables than the class - type instance F2 c d = c->d -- OK; you don't have to use 'a' in the type instance - - type F3 a - type F3 [b] = b -- BAD; only type variables allowed on the LHS - - type F4 a - type F4 b = a -- BAD; 'a' is not in scope in the RHS -</programlisting> -</para> - -</sect3> - - <sect3 id="scoping-class-params"> - <title>Scoping of class parameters</title> - <para> - The visibility of class - parameters in the right-hand side of associated family instances - depends <emphasis>solely</emphasis> on the parameters of the - family. As an example, consider the simple class declaration -<programlisting> -class C a b where - data T a -</programlisting> - Only one of the two class parameters is a parameter to the data - family. Hence, the following instance declaration is invalid: -<programlisting> -instance C [c] d where - data T [c] = MkT (c, d) -- WRONG!! 'd' is not in scope -</programlisting> - Here, the right-hand side of the data instance mentions the type - variable <literal>d</literal> that does not occur in its left-hand - side. We cannot admit such data instances as they would compromise - type safety. - </para> - </sect3> - - <sect3><title>Instance contexts and associated type and data instances</title> - <para>Associated type and data instance declarations do not inherit any - context specified on the enclosing instance. For type instance declarations, - it is unclear what the context would mean. For data instance declarations, - it is unlikely a user would want the context repeated for every data constructor. - The only place where the context might likely be useful is in a - <literal>deriving</literal> clause of an associated data instance. However, - even here, the role of the outer instance context is murky. So, for - clarity, we just stick to the rule above: the enclosing instance context - is ignored. If you need to use - a non-trivial context on a derived instance, - use a <link linkend="stand-alone-deriving">standalone - deriving</link> clause (at the top level). - </para> - </sect3> - - </sect2> - - <sect2 id="data-family-import-export"> - <title>Import and export</title> - - <para> -The rules for export lists -(Haskell Report - <ulink url="http://www.haskell.org/onlinereport/modules.html#sect5.2">Section 5.2</ulink>) -needs adjustment for type families: -<itemizedlist> -<listitem><para> - The form <literal>T(..)</literal>, where <literal>T</literal> - is a data family, names the family <literal>T</literal> and all the in-scope - constructors (whether in scope qualified or unqualified) that are data - instances of <literal>T</literal>. - </para></listitem> -<listitem><para> - The form <literal>T(.., ci, .., fj, ..)</literal>, where <literal>T</literal> is - a data family, names <literal>T</literal> and the specified constructors <literal>ci</literal> - and fields <literal>fj</literal> as usual. The constructors and field names must - belong to some data instance of <literal>T</literal>, but are not required to belong - to the <emphasis>same</emphasis> instance. - </para></listitem> -<listitem><para> - The form <literal>C(..)</literal>, where <literal>C</literal> - is a class, names the class <literal>C</literal> and all its methods - <emphasis>and associated types</emphasis>. - </para></listitem> -<listitem><para> - The form <literal>C(.., mi, .., type Tj, ..)</literal>, where <literal>C</literal> is a class, - names the class <literal>C</literal>, and the specified methods <literal>mi</literal> - and associated types <literal>Tj</literal>. The types need a keyword "<literal>type</literal>" - to distinguish them from data constructors. - </para></listitem> -</itemizedlist> -</para> - - <sect3 id="data-family-impexp-examples"> - <title>Examples</title> - <para> - Recall our running <literal>GMapKey</literal> class example: -<programlisting> -class GMapKey k where - data GMap k :: * -> * - insert :: GMap k v -> k -> v -> GMap k v - lookup :: GMap k v -> k -> Maybe v - empty :: GMap k v - -instance (GMapKey a, GMapKey b) => GMapKey (Either a b) where - data GMap (Either a b) v = GMapEither (GMap a v) (GMap b v) - ...method declarations... -</programlisting> -Here are some export lists and their meaning: - <itemizedlist> - <listitem> - <para><literal>module GMap( GMapKey )</literal>: Exports - just the class name.</para> - </listitem> - <listitem> - <para><literal>module GMap( GMapKey(..) )</literal>: - Exports the class, the associated type <literal>GMap</literal> - and the member - functions <literal>empty</literal>, <literal>lookup</literal>, - and <literal>insert</literal>. The data constructors of <literal>GMap</literal> - (in this case <literal>GMapEither</literal>) are not exported.</para> - </listitem> - <listitem> - <para><literal>module GMap( GMapKey( type GMap, empty, lookup, insert ) )</literal>: - Same as the previous item. Note the "<literal>type</literal>" keyword.</para> - </listitem> - <listitem> - <para><literal>module GMap( GMapKey(..), GMap(..) )</literal>: - Same as previous item, but also exports all the data - constructors for <literal>GMap</literal>, namely <literal>GMapEither</literal>. - </para> - </listitem> - <listitem> - <para><literal>module GMap ( GMapKey( empty, lookup, insert), GMap(..) )</literal>: - Same as previous item.</para> - </listitem> - <listitem> - <para><literal>module GMap ( GMapKey, empty, lookup, insert, GMap(..) )</literal>: - Same as previous item.</para> - </listitem> - </itemizedlist> - </para> - <para> -Two things to watch out for: - <itemizedlist> - <listitem><para> - You cannot write <literal>GMapKey(type GMap(..))</literal> — i.e., - sub-component specifications cannot be nested. To - specify <literal>GMap</literal>'s data constructors, you have to list - it separately. - </para></listitem> - <listitem><para> - Consider this example: -<programlisting> - module X where - data family D - - module Y where - import X - data instance D Int = D1 | D2 -</programlisting> - Module Y exports all the entities defined in Y, namely the data constructors <literal>D1</literal> - and <literal>D2</literal>, <emphasis>but not the data family <literal>D</literal></emphasis>. - That (annoyingly) means that you cannot selectively import Y selectively, - thus "<literal>import Y( D(D1,D2) )</literal>", because Y does not export <literal>D</literal>. - Instead you should list the exports explicitly, thus: -<programlisting> - module Y( D(..) ) where ... -or module Y( module Y, D ) where ... -</programlisting> - </para></listitem> - </itemizedlist> -</para> -</sect3> - - <sect3 id="data-family-impexp-instances"> - <title>Instances</title> - <para> - Family instances are implicitly exported, just like class instances. - However, this applies only to the heads of instances, not to the data - constructors an instance defines. - </para> - </sect3> - - </sect2> - - <sect2 id="ty-fams-in-instances"> - <title>Type families and instance declarations</title> - - <para>Type families require us to extend the rules for - the form of instance heads, which are given - in <xref linkend="flexible-instance-head"/>. - Specifically: -<itemizedlist> - <listitem><para>Data type families may appear in an instance head</para></listitem> - <listitem><para>Type synonym families may not appear (at all) in an instance head</para></listitem> -</itemizedlist> -The reason for the latter restriction is that there is no way to check for instance -matching. Consider -<programlisting> - type family F a - type instance F Bool = Int - - class C a - - instance C Int - instance C (F a) -</programlisting> -Now a constraint <literal>(C (F Bool))</literal> would match both instances. -The situation is especially bad because the type instance for <literal>F Bool</literal> -might be in another module, or even in a module that is not yet written. -</para> -<para> -However, type class instances of instances of data families can be defined -much like any other data type. For example, we can say -<programlisting> -data instance T Int = T1 Int | T2 Bool -instance Eq (T Int) where - (T1 i) == (T1 j) = i==j - (T2 i) == (T2 j) = i==j - _ == _ = False -</programlisting> - Note that class instances are always for - particular <emphasis>instances</emphasis> of a data family and never - for an entire family as a whole. This is for essentially the same - reasons that we cannot define a toplevel function that performs - pattern matching on the data constructors - of <emphasis>different</emphasis> instances of a single type family. - It would require a form of extensible case construct. - </para> -<para> -Data instance declarations can also - have <literal>deriving</literal> clauses. For example, we can write -<programlisting> -data GMap () v = GMapUnit (Maybe v) - deriving Show -</programlisting> - which implicitly defines an instance of the form -<programlisting> -instance Show v => Show (GMap () v) where ... -</programlisting> - </para> - -</sect2> - - <sect2 id="injective-ty-fams"> - <title>Injective type families</title> - <para>Starting with GHC 7.12 type families can be annotated with injectivity - information. This information is then used by GHC during type checking to - resolve type ambiguities in situations where a type variable appears only - under type family applications. - </para> - - <para>For full details on injective type families refer to Haskell Symposium - 2015 paper <ulink - url="http://ics.p.lodz.pl/~stolarek/_media/pl:research:stolarek_peyton-jones_eisenberg_injectivity_extended.pdf">Injective - type families for Haskell</ulink>.</para> - - <sect3 id="injective-ty-fams-syntax"> - <title>Syntax of injectivity annotation</title> - <para>Injectivity annotation is added after type family head and consists of - two parts: - <itemizedlist> - <listitem><para>type variable that names the result of a type family. - Syntax: <literal>= tyvar</literal> or <literal>= (tyvar :: - kind)</literal>. Type variable must be fresh. - </para> - </listitem> - <listitem><para>injectivity annotation of the form <literal>| A -> - B</literal>, where <literal>A</literal> is the result type variable (see - previous bullet) and <literal>B</literal> is a list of argument type and - kind variables in which type family is injective. It is possible to omit - some variables if type family is not injective in them.</para></listitem> - </itemizedlist> - Examples: - <programlisting> -type family Id a = result | result -> a where -type family F a b c = d | d -> a c b -type family G (a :: k) b c = foo | foo -> k b where - </programlisting> - </para> - <para>For open and closed type families it is OK to name the result but - skip the injectivity annotation. This is not the case for associated type - synonyms, where the named result without injectivity annotation will be - interpreted as associated type synonym default.</para> - </sect3> - - <sect3 id="injective-ty-fams-typecheck"> - <title>Verifying injectivity annotation against type family equations - </title> - <para>Once the user declares type family to be injective GHC must verify - that this declaration is correct, ie. type family equations don't violate - the injectivity annotation. A general idea is that if at least one - equation (bullets (1), (2) and (3) below) or a pair of equations (bullets - (4) and (5) below) violates the injectivity annotation then a type family - is not injective in a way user claims and an error is reported. In the - bullets below <emphasis>RHS</emphasis> refers to the right-hand side of the - type family equation being checked for injectivity. - <emphasis>LHS</emphasis> refers to the arguments of that type family - equation. Below are the rules followed when checking injectivity of a type - family: - <orderedlist> - <listitem><para>If a RHS of a type family equation is a type family - application GHC reports that the type family is not injective.</para> - </listitem> - <listitem>If a RHS of a type family equation is a bare type variable we - require that all LHS variables (including implicit kind variables) are - also bare. In other words, this has to be a sole equation of that type - family and it has to cover all possible patterns. If the patterns are - not covering GHC reports that the type family is not injective. - </listitem> - <listitem>If a LHS type variable that is declared as injective is not - mentioned on <emphasis>injective position</emphasis> in the RHS GHC - reports that the type family is not injective. Injective position means - either argument to a type constructor or injective argument to a type - family.</listitem> - <listitem><para><emphasis>Open type families</emphasis>Open type families - are typechecked incrementally. This means that when a module is imported - type family instances contained in that module are checked against - instances present in already imported modules.</para> - <para>A pair of an open type family equations is checked by attempting to - unify their RHSs. If the RHSs don't unify this pair does not violate - injectivity annotation. If unification succeeds with a substitution then - LHSs of unified equations must be identical under that substitution. If - they are not identical then GHC reports that the type family is not - injective.</para> - </listitem> - <listitem><para>In a <emphasis>closed type family</emphasis> all - equations are ordered and in one place. Equations are also checked - pair-wise but this time an equation has to be paired with all the - preceeding equations. Of course a single-equation closed type family is - trivially injective (unless (1), (2) or (3) above holds). - </para> - <para>When checking a pair of closed type family equations GHC tried to - unify their RHSs. If they don't unify this pair of equations does not - violate injectivity annotation. If the RHSs can be unified under some - substitution (possibly empty) then either the LHSs unify under the same - substitution or the LHS of the latter equation is subsumed by earlier - equations. If neither condition is met GHC reports that a type family is - not injective. - </para> - </listitem> - </orderedlist> - </para> - <para>Note that for the purpose of injectivity check in bullets (4) and (5) - GHC uses a special variant of unification algorithm that treats type family - applications as possibly unifying with anything.</para> - </sect3> - </sect2> - -</sect1> - - -<sect1 id="kind-polymorphism"> -<title>Kind polymorphism</title> -<para> -This section describes <emphasis>kind polymorphism</emphasis>, and extension -enabled by <option>-XPolyKinds</option>. -It is described in more detail in the paper -<ulink url="http://dreixel.net/research/pdf/ghp.pdf">Giving Haskell a -Promotion</ulink>, which appeared at TLDI 2012. -</para> - -<sect2> <title>Overview of kind polymorphism</title> - -<para> -Currently there is a lot of code duplication in the way Typeable is implemented -(<xref linkend="deriving-typeable"/>): -<programlisting> -class Typeable (t :: *) where - typeOf :: t -> TypeRep - -class Typeable1 (t :: * -> *) where - typeOf1 :: t a -> TypeRep - -class Typeable2 (t :: * -> * -> *) where - typeOf2 :: t a b -> TypeRep -</programlisting> -</para> - -<para> -Kind polymorphism (with <option>-XPolyKinds</option>) -allows us to merge all these classes into one: -<programlisting> -data Proxy t = Proxy - -class Typeable t where - typeOf :: Proxy t -> TypeRep - -instance Typeable Int where typeOf _ = TypeRep -instance Typeable [] where typeOf _ = TypeRep -</programlisting> -Note that the datatype <literal>Proxy</literal> has kind -<literal>forall k. k -> *</literal> (inferred by GHC), and the new -<literal>Typeable</literal> class has kind -<literal>forall k. k -> Constraint</literal>. -</para> - -<para> -Note the following specific points: -<itemizedlist> -<listitem><para> -Generally speaking, with <option>-XPolyKinds</option>, GHC will infer a polymorphic -kind for un-decorated declarations, whenever possible. For example, in GHCi -<programlisting> -ghci> :set -XPolyKinds -ghci> data T m a = MkT (m a) -ghci> :k T -T :: (k -> *) -> k -> * -</programlisting> -</para></listitem> - -<listitem><para> -GHC does not usually print explicit <literal>forall</literal>s, including kind <literal>forall</literal>s. -You can make GHC show them explicitly with <option>-fprint-explicit-foralls</option> -(see <xref linkend="options-help"/>): -<programlisting> -ghci> :set -XPolyKinds -ghci> :set -fprint-explicit-foralls -ghci> data T m a = MkT (m a) -ghci> :k T -T :: forall (k :: BOX). (k -> *) -> k -> * -</programlisting> -Here the kind variable <literal>k</literal> itself has a -kind annotation "<literal>BOX</literal>". This is just GHC's way of -saying "<literal>k</literal> is a kind variable". -</para></listitem> - -<listitem><para> -Just as in the world of terms, you can restrict polymorphism using a -kind signature (sometimes called a kind annotation) -<programlisting> -data T m (a :: *) = MkT (m a) --- GHC now infers kind T :: (* -> *) -> * -> * -</programlisting> -NB: <option>-XPolyKinds</option> implies <option>-XKindSignatures</option> (see <xref linkend="kinding"/>). -</para></listitem> - -<listitem><para> -The source language does not support an explicit <literal>forall</literal> for kind variables. Instead, when binding a type variable, -you can simply mention a kind -variable in a kind annotation for that type-variable binding, thus: -<programlisting> -data T (m :: k -> *) a = MkT (m a) --- GHC now infers kind T :: forall k. (k -> *) -> k -> * -</programlisting> -</para></listitem> - -<listitem><para> -The (implicit) kind "forall" is placed -just outside the outermost type-variable binding whose kind annotation mentions -the kind variable. For example -<programlisting> -f1 :: (forall a m. m a -> Int) -> Int - -- f1 :: forall (k::BOX). - -- (forall (a::k) (m::k->*). m a -> Int) - -- -> Int - -f2 :: (forall (a::k) m. m a -> Int) -> Int - -- f2 :: (forall (k::BOX) (a::k) (m::k->*). m a -> Int) - -- -> Int -</programlisting> -Here in <literal>f1</literal> there is no kind annotation mentioning the polymorphic -kind variable, so <literal>k</literal> is generalised at the top -level of the signature for <literal>f1</literal>. -But in the case of of <literal>f2</literal> we give a kind annotation in the <literal>forall (a:k)</literal> -binding, and GHC therefore puts the kind <literal>forall</literal> right there too. -This design decision makes default case (<literal>f1</literal>) -as polymorphic as possible; remember that a <emphasis>more</emphasis> polymorphic argument type (as in <literal>f2</literal> -makes the overall function <emphasis>less</emphasis> polymorphic, because there are fewer acceptable arguments. -</para></listitem> -</itemizedlist> -</para> -<para> -(Note: These rules are a bit indirect and clumsy. Perhaps GHC should allow explicit kind quantification. -But the implicit quantification (e.g. in the declaration for data type T above) is certainly -very convenient, and it is not clear what the syntax for explicit quantification should be.) -</para> -</sect2> - -<sect2> <title>Principles of kind inference</title> - -<para> -Generally speaking, when <option>-XPolyKinds</option> is on, GHC tries to infer the most -general kind for a declaration. For example: -<programlisting> -data T f a = MkT (f a) -- GHC infers: - -- T :: forall k. (k->*) -> k -> * -</programlisting> -In this case the definition has a right-hand side to inform kind inference. -But that is not always the case. Consider -<programlisting> -type family F a -</programlisting> -Type family declarations have no right-hand side, but GHC must still infer a kind -for <literal>F</literal>. Since there are no constraints, it could infer -<literal>F :: forall k1 k2. k1 -> k2</literal>, but that seems <emphasis>too</emphasis> -polymorphic. So GHC defaults those entirely-unconstrained kind variables to <literal>*</literal> and -we get <literal>F :: * -> *</literal>. You can still declare <literal>F</literal> to be -kind-polymorphic using kind signatures: -<programlisting> -type family F1 a -- F1 :: * -> * -type family F2 (a :: k) -- F2 :: forall k. k -> * -type family F3 a :: k -- F3 :: forall k. * -> k -type family F4 (a :: k1) :: k -- F4 :: forall k1 k2. k1 -> k2 -</programlisting> -</para> -<para> -The general principle is this: -<itemizedlist> -<listitem><para> -<emphasis>When there is a right-hand side, GHC -infers the most polymorphic kind consistent with the right-hand side.</emphasis> -Examples: ordinary data type and GADT declarations, class declarations. -In the case of a class declaration the role of "right hand side" is played -by the class method signatures. -</para></listitem> -<listitem><para> -<emphasis>When there is no right hand side, GHC defaults argument and result kinds to <literal>*</literal>, -except when directed otherwise by a kind signature</emphasis>. -Examples: data and type family declarations. -</para></listitem> -</itemizedlist> -This rule has occasionally-surprising consequences -(see <ulink url="https://ghc.haskell.org/trac/ghc/ticket/10132">Trac 10132</ulink>). -<programlisting> -class C a where -- Class declarations are generalised - -- so C :: forall k. k -> Constraint - data D1 a -- No right hand side for these two family - type F1 a -- declarations, but the class forces (a :: k) - -- so D1, F1 :: forall k. k -> * - -data D2 a -- No right-hand side so D2 :: * -> * -type F2 a -- No right-hand side so F2 :: * -> * -</programlisting> -The kind-polymorphism from the class declaration makes <literal>D1</literal> -kind-polymorphic, but not so <literal>D2</literal>; and similarly <literal>F1</literal>, <literal>F1</literal>. -</para> -</sect2> - -<sect2 id="complete-kind-signatures"> <title>Polymorphic kind recursion and complete kind signatures</title> - -<para> -Just as in type inference, kind inference for recursive types can only use <emphasis>monomorphic</emphasis> recursion. -Consider this (contrived) example: -<programlisting> -data T m a = MkT (m a) (T Maybe (m a)) --- GHC infers kind T :: (* -> *) -> * -> * -</programlisting> -The recursive use of <literal>T</literal> forced the second argument to have kind <literal>*</literal>. -However, just as in type inference, you can achieve polymorphic recursion by giving a -<emphasis>complete kind signature</emphasis> for <literal>T</literal>. A complete -kind signature is present when all argument kinds and the result kind are known, without -any need for inference. For example: -<programlisting> -data T (m :: k -> *) :: k -> * where - MkT :: m a -> T Maybe (m a) -> T m a -</programlisting> -The complete user-supplied kind signature specifies the polymorphic kind for <literal>T</literal>, -and this signature is used for all the calls to <literal>T</literal> including the recursive ones. -In particular, the recursive use of <literal>T</literal> is at kind <literal>*</literal>. -</para> - -<para> -What exactly is considered to be a "complete user-supplied kind signature" for a type constructor? -These are the forms: -<itemizedlist> -<listitem><para>For a datatype, every type variable must be annotated with a kind. In a -GADT-style declaration, there may also be a kind signature (with a top-level -<literal>::</literal> in the header), but the presence or absence of this annotation -does not affect whether or not the declaration has a complete signature. -<programlisting> -data T1 :: (k -> *) -> k -> * where ... -- Yes T1 :: forall k. (k->*) -> k -> * -data T2 (a :: k -> *) :: k -> * where ... -- Yes T2 :: forall k. (k->*) -> k -> * -data T3 (a :: k -> *) (b :: k) :: * where ... -- Yes T3 :: forall k. (k->*) -> k -> * -data T4 (a :: k -> *) (b :: k) where ... -- Yes T4 :: forall k. (k->*) -> k -> * - -data T5 a (b :: k) :: * where ... -- NO kind is inferred -data T6 a b where ... -- NO kind is inferred -</programlisting></para> -</listitem> - -<listitem><para> -For a class, every type variable must be annotated with a kind. -</para></listitem> - -<listitem><para> -For a type synonym, every type variable and the result type must all be annotated -with kinds. -<programlisting> -type S1 (a :: k) = (a :: k) -- Yes S1 :: forall k. k -> k -type S2 (a :: k) = a -- No kind is inferred -type S3 (a :: k) = Proxy a -- No kind is inferred -</programlisting> -Note that in <literal>S2</literal> and <literal>S3</literal>, the kind of the -right-hand side is rather apparent, but it is still not considered to have a complete -signature -- no inference can be done before detecting the signature.</para></listitem> - -<listitem><para> -An open type or data family declaration <emphasis>always</emphasis> has a -complete user-specified kind signature; un-annotated type variables default to -kind <literal>*</literal>. -<programlisting> -data family D1 a -- D1 :: * -> * -data family D2 (a :: k) -- D2 :: forall k. k -> * -data family D3 (a :: k) :: * -- D3 :: forall k. k -> * -type family S1 a :: k -> * -- S1 :: forall k. * -> k -> * - -class C a where -- C :: k -> Constraint - type AT a b -- AT :: k -> * -> * -</programlisting> -In the last example, the variable <literal>a</literal> has an implicit kind -variable annotation from the class declaration. It keeps its polymorphic kind -in the associated type declaration. The variable <literal>b</literal>, however, -gets defaulted to <literal>*</literal>. -</para></listitem> - -<listitem><para> -A closed type family has a complete signature when all of its type variables -are annotated and a return kind (with a top-level <literal>::</literal>) is supplied. -</para></listitem> -</itemizedlist> -</para> - -</sect2> - -<sect2><title>Kind inference in closed type families</title> - -<para>Although all open type families are considered to have a complete -user-specified kind signature, we can relax this condition for closed type -families, where we have equations on which to perform kind inference. GHC will -infer kinds for the arguments and result types of a closed type family.</para> - -<para>GHC supports <emphasis>kind-indexed</emphasis> type families, where the -family matches both on the kind and type. GHC will <emphasis>not</emphasis> infer -this behaviour without a complete user-supplied kind signature, as doing so would -sometimes infer non-principal types.</para> - -<para>For example: -<programlisting> -type family F1 a where - F1 True = False - F1 False = True - F1 x = x --- F1 fails to compile: kind-indexing is not inferred - -type family F2 (a :: k) where - F2 True = False - F2 False = True - F2 x = x --- F2 fails to compile: no complete signature - -type family F3 (a :: k) :: k where - F3 True = False - F3 False = True - F3 x = x --- OK -</programlisting></para> - -</sect2> - -<sect2><title>Kind inference in class instance declarations</title> - -<para>Consider the following example of a poly-kinded class and an instance for it:</para> - -<programlisting> -class C a where - type F a - -instance C b where - type F b = b -> b -</programlisting> - -<para>In the class declaration, nothing constrains the kind of the type -<literal>a</literal>, so it becomes a poly-kinded type variable <literal>(a :: k)</literal>. -Yet, in the instance declaration, the right-hand side of the associated type instance -<literal>b -> b</literal> says that <literal>b</literal> must be of kind <literal>*</literal>. GHC could theoretically propagate this information back into the instance head, and -make that instance declaration apply only to type of kind <literal>*</literal>, as opposed -to types of any kind. However, GHC does <emphasis>not</emphasis> do this.</para> - -<para>In short: GHC does <emphasis>not</emphasis> propagate kind information from -the members of a class instance declaration into the instance declaration head.</para> - -<para>This lack of kind inference is simply an engineering problem within GHC, but -getting it to work would make a substantial change to the inference infrastructure, -and it's not clear the payoff is worth it. If you want to restrict <literal>b</literal>'s -kind in the instance above, just use a kind signature in the instance head.</para> - -</sect2> -</sect1> - -<sect1 id="promotion"> -<title>Datatype promotion</title> - -<para> -This section describes <emphasis>data type promotion</emphasis>, an extension -to the kind system that complements kind polymorphism. It is enabled by <option>-XDataKinds</option>, -and described in more detail in the paper -<ulink url="http://dreixel.net/research/pdf/ghp.pdf">Giving Haskell a -Promotion</ulink>, which appeared at TLDI 2012. -</para> - -<sect2> <title>Motivation</title> - -<para> -Standard Haskell has a rich type language. Types classify terms and serve to -avoid many common programming mistakes. The kind language, however, is -relatively simple, distinguishing only lifted types (kind <literal>*</literal>), -type constructors (e.g. kind <literal>* -> * -> *</literal>), and unlifted -types (<xref linkend="glasgow-unboxed"/>). In particular when using advanced -type system features, such as type families (<xref linkend="type-families"/>) -or GADTs (<xref linkend="gadt"/>), this simple kind system is insufficient, -and fails to prevent simple errors. Consider the example of type-level natural -numbers, and length-indexed vectors: -<programlisting> -data Ze -data Su n - -data Vec :: * -> * -> * where - Nil :: Vec a Ze - Cons :: a -> Vec a n -> Vec a (Su n) -</programlisting> -The kind of <literal>Vec</literal> is <literal>* -> * -> *</literal>. This means -that eg. <literal>Vec Int Char</literal> is a well-kinded type, even though this -is not what we intend when defining length-indexed vectors. -</para> - -<para> -With <option>-XDataKinds</option>, the example above can then be -rewritten to: -<programlisting> -data Nat = Ze | Su Nat - -data Vec :: * -> Nat -> * where - Nil :: Vec a Ze - Cons :: a -> Vec a n -> Vec a (Su n) -</programlisting> -With the improved kind of <literal>Vec</literal>, things like -<literal>Vec Int Char</literal> are now ill-kinded, and GHC will report an -error. -</para> -</sect2> - -<sect2><title>Overview</title> -<para> -With <option>-XDataKinds</option>, GHC automatically promotes every suitable -datatype to be a kind, and its (value) constructors to be type constructors. -The following types -<programlisting> -data Nat = Ze | Su Nat - -data List a = Nil | Cons a (List a) - -data Pair a b = Pair a b - -data Sum a b = L a | R b -</programlisting> -give rise to the following kinds and type constructors: -<programlisting> -Nat :: BOX -Ze :: Nat -Su :: Nat -> Nat - -List k :: BOX -Nil :: List k -Cons :: k -> List k -> List k - -Pair k1 k2 :: BOX -Pair :: k1 -> k2 -> Pair k1 k2 - -Sum k1 k2 :: BOX -L :: k1 -> Sum k1 k2 -R :: k2 -> Sum k1 k2 -</programlisting> -where <literal>BOX</literal> is the (unique) sort that classifies kinds. -Note that <literal>List</literal>, for instance, does not get sort -<literal>BOX -> BOX</literal>, because we do not further classify kinds; all -kinds have sort <literal>BOX</literal>. -</para> - -<para> -The following restrictions apply to promotion: -<itemizedlist> - <listitem><para>We promote <literal>data</literal> types and <literal>newtypes</literal>, - but not type synonyms, or type/data families (<xref linkend="type-families"/>). - </para></listitem> - <listitem><para>We only promote types whose kinds are of the form - <literal>* -> ... -> * -> *</literal>. In particular, we do not promote - higher-kinded datatypes such as <literal>data Fix f = In (f (Fix f))</literal>, - or datatypes whose kinds involve promoted types such as - <literal>Vec :: * -> Nat -> *</literal>.</para></listitem> - <listitem><para>We do not promote data constructors that are kind - polymorphic, involve constraints, mention type or data families, or involve types that - are not promotable. - </para></listitem> -</itemizedlist> -</para> -</sect2> - -<sect2 id="promotion-syntax"> -<title>Distinguishing between types and constructors</title> -<para> -Since constructors and types share the same namespace, with promotion you can -get ambiguous type names: -<programlisting> -data P -- 1 - -data Prom = P -- 2 - -type T = P -- 1 or promoted 2? -</programlisting> -In these cases, if you want to refer to the promoted constructor, you should -prefix its name with a quote: -<programlisting> -type T1 = P -- 1 - -type T2 = 'P -- promoted 2 -</programlisting> -Note that promoted datatypes give rise to named kinds. Since these can never be -ambiguous, we do not allow quotes in kind names. -</para> -<para>Just as in the case of Template Haskell (<xref linkend="th-syntax"/>), there is -no way to quote a data constructor or type constructor whose second character -is a single quote.</para> -</sect2> - -<sect2 id="promoted-lists-and-tuples"> -<title>Promoted list and tuple types</title> -<para> -With <option>-XDataKinds</option>, Haskell's list and tuple types are natively promoted to kinds, and enjoy the -same convenient syntax at the type level, albeit prefixed with a quote: -<programlisting> -data HList :: [*] -> * where - HNil :: HList '[] - HCons :: a -> HList t -> HList (a ': t) - -data Tuple :: (*,*) -> * where - Tuple :: a -> b -> Tuple '(a,b) - -foo0 :: HList '[] -foo0 = HNil - -foo1 :: HList '[Int] -foo1 = HCons (3::Int) HNil - -foo2 :: HList [Int, Bool] -foo2 = ... -</programlisting> -(Note: the declaration for <literal>HCons</literal> also requires <option>-XTypeOperators</option> -because of infix type operator <literal>(:')</literal>.) -For type-level lists of <emphasis>two or more elements</emphasis>, -such as the signature of <literal>foo2</literal> above, the quote may be omitted because the meaning is -unambiguous. But for lists of one or zero elements (as in <literal>foo0</literal> -and <literal>foo1</literal>), the quote is required, because the types <literal>[]</literal> -and <literal>[Int]</literal> have existing meanings in Haskell. -</para> -</sect2> - -<sect2 id="promotion-existentials"> -<title>Promoting existential data constructors</title> -<para> -Note that we do promote existential data constructors that are otherwise suitable. -For example, consider the following: -<programlisting> -data Ex :: * where - MkEx :: forall a. a -> Ex -</programlisting> -Both the type <literal>Ex</literal> and the data constructor <literal>MkEx</literal> -get promoted, with the polymorphic kind <literal>'MkEx :: forall k. k -> Ex</literal>. -Somewhat surprisingly, you can write a type family to extract the member -of a type-level existential: -<programlisting> -type family UnEx (ex :: Ex) :: k -type instance UnEx (MkEx x) = x -</programlisting> -At first blush, <literal>UnEx</literal> seems poorly-kinded. The return kind -<literal>k</literal> is not mentioned in the arguments, and thus it would seem -that an instance would have to return a member of <literal>k</literal> -<emphasis>for any</emphasis> <literal>k</literal>. However, this is not the -case. The type family <literal>UnEx</literal> is a kind-indexed type family. -The return kind <literal>k</literal> is an implicit parameter to <literal>UnEx</literal>. -The elaborated definitions are as follows: -<programlisting> -type family UnEx (k :: BOX) (ex :: Ex) :: k -type instance UnEx k (MkEx k x) = x -</programlisting> -Thus, the instance triggers only when the implicit parameter to <literal>UnEx</literal> -matches the implicit parameter to <literal>MkEx</literal>. Because <literal>k</literal> -is actually a parameter to <literal>UnEx</literal>, the kind is not escaping the -existential, and the above code is valid. -</para> - -<para> -See also <ulink url="http://ghc.haskell.org/trac/ghc/ticket/7347">Trac #7347</ulink>. -</para> -</sect2> - -<sect2> -<title>Promoting type operators</title> -<para> -Type operators are <emphasis>not</emphasis> promoted to the kind level. Why not? Because -<literal>*</literal> is a kind, parsed the way identifiers are. Thus, if a programmer -tried to write <literal>Either * Bool</literal>, would it be <literal>Either</literal> -applied to <literal>*</literal> and <literal>Bool</literal>? Or would it be -<literal>*</literal> applied to <literal>Either</literal> and <literal>Bool</literal>. -To avoid this quagmire, we simply forbid promoting type operators to the kind level. -</para> -</sect2> - - -</sect1> - -<sect1 id="type-level-literals"> -<title>Type-Level Literals</title> -<para> -GHC supports numeric and string literals at the type level, giving convenient -access to a large number of predefined type-level constants. -Numeric literals are of kind <literal>Nat</literal>, while string literals -are of kind <literal>Symbol</literal>. -This feature is enabled by the <literal>XDataKinds</literal> -language extension. -</para> - -<para> -The kinds of the literals and all other low-level operations for this feature -are defined in module <literal>GHC.TypeLits</literal>. Note that the module -defines some type-level operators that clash with their value-level -counterparts (e.g. <literal>(+)</literal>). Import and export declarations -referring to these operators require an explicit namespace -annotation (see <xref linkend="explicit-namespaces"/>). -</para> - -<para> -Here is an example of using type-level numeric literals to provide a safe -interface to a low-level function: -<programlisting> -import GHC.TypeLits -import Data.Word -import Foreign - -newtype ArrPtr (n :: Nat) a = ArrPtr (Ptr a) - -clearPage :: ArrPtr 4096 Word8 -> IO () -clearPage (ArrPtr p) = ... -</programlisting> -</para> - -<para> -Here is an example of using type-level string literals to simulate -simple record operations: -<programlisting> -data Label (l :: Symbol) = Get - -class Has a l b | a l -> b where - from :: a -> Label l -> b - -data Point = Point Int Int deriving Show - -instance Has Point "x" Int where from (Point x _) _ = x -instance Has Point "y" Int where from (Point _ y) _ = y - -example = from (Point 1 2) (Get :: Label "x") -</programlisting> -</para> - -<sect2 id="typelit-runtime"> -<title>Runtime Values for Type-Level Literals</title> -<para> -Sometimes it is useful to access the value-level literal associated with -a type-level literal. This is done with the functions -<literal>natVal</literal> and <literal>symbolVal</literal>. For example: -<programlisting> -GHC.TypeLits> natVal (Proxy :: Proxy 2) -2 -</programlisting> -These functions are overloaded because they need to return a different -result, depending on the type at which they are instantiated. -<programlisting> -natVal :: KnownNat n => proxy n -> Integer - --- instance KnownNat 0 --- instance KnownNat 1 --- instance KnownNat 2 --- ... -</programlisting> -GHC discharges the constraint as soon as it knows what concrete -type-level literal is being used in the program. Note that this works -only for <emphasis>literals</emphasis> and not arbitrary type expressions. -For example, a constraint of the form <literal>KnownNat (a + b)</literal> -will <emphasis>not</emphasis> be simplified to -<literal>(KnownNat a, KnownNat b)</literal>; instead, GHC will keep the -constraint as is, until it can simplify <literal>a + b</literal> to -a constant value. -</para> -</sect2> - -<para> -It is also possible to convert a run-time integer or string value to -the corresponding type-level literal. Of course, the resulting type -literal will be unknown at compile-time, so it is hidden in an existential -type. The conversion may be performed using <literal>someNatVal</literal> -for integers and <literal>someSymbolVal</literal> for strings: -<programlisting> -someNatVal :: Integer -> Maybe SomeNat -SomeNat :: KnownNat n => Proxy n -> SomeNat -</programlisting> -The operations on strings are similar. -</para> - -<sect2 id="typelit-tyfuns"> -<title>Computing With Type-Level Naturals</title> -<para> -GHC 7.8 can evaluate arithmetic expressions involving type-level natural -numbers. Such expressions may be constructed using the type-families -<literal>(+), (*), (^)</literal> for addition, multiplication, -and exponentiation. Numbers may be compared using <literal>(<=?)</literal>, -which returns a promoted boolean value, or <literal>(<=)</literal>, which -compares numbers as a constraint. For example: -<programlisting> -GHC.TypeLits> natVal (Proxy :: Proxy (2 + 3)) -5 -</programlisting> -</para> -<para> -At present, GHC is quite limited in its reasoning about arithmetic: -it will only evaluate the arithmetic type functions and compare the results--- -in the same way that it does for any other type function. In particular, -it does not know more general facts about arithmetic, such as the commutativity -and associativity of <literal>(+)</literal>, for example. -</para> - -<para> -However, it is possible to perform a bit of "backwards" evaluation. -For example, here is how we could get GHC to compute arbitrary logarithms -at the type level: -<programlisting> -lg :: Proxy base -> Proxy (base ^ pow) -> Proxy pow -lg _ _ = Proxy - -GHC.TypeLits> natVal (lg (Proxy :: Proxy 2) (Proxy :: Proxy 8)) -3 -</programlisting> -</para> -</sect2> - - -</sect1> - - - <sect1 id="equality-constraints"> - <title>Equality constraints</title> - <para> - A type context can include equality constraints of the form <literal>t1 ~ - t2</literal>, which denote that the types <literal>t1</literal> - and <literal>t2</literal> need to be the same. In the presence of type - families, whether two types are equal cannot generally be decided - locally. Hence, the contexts of function signatures may include - equality constraints, as in the following example: -<programlisting> -sumCollects :: (Collects c1, Collects c2, Elem c1 ~ Elem c2) => c1 -> c2 -> c2 -</programlisting> - where we require that the element type of <literal>c1</literal> - and <literal>c2</literal> are the same. In general, the - types <literal>t1</literal> and <literal>t2</literal> of an equality - constraint may be arbitrary monotypes; i.e., they may not contain any - quantifiers, independent of whether higher-rank types are otherwise - enabled. - </para> - <para> - Equality constraints can also appear in class and instance contexts. - The former enable a simple translation of programs using functional - dependencies into programs using family synonyms instead. The general - idea is to rewrite a class declaration of the form -<programlisting> -class C a b | a -> b -</programlisting> - to -<programlisting> -class (F a ~ b) => C a b where - type F a -</programlisting> - That is, we represent every functional dependency (FD) <literal>a1 .. an - -> b</literal> by an FD type family <literal>F a1 .. an</literal> and a - superclass context equality <literal>F a1 .. an ~ b</literal>, - essentially giving a name to the functional dependency. In class - instances, we define the type instances of FD families in accordance - with the class head. Method signatures are not affected by that - process. - </para> - - <sect2 id="coercible"> - <title>The <literal>Coercible</literal> constraint</title> - <para> - The constraint <literal>Coercible t1 t2</literal> is similar to <literal>t1 ~ - t2</literal>, but denotes representational equality between - <literal>t1</literal> and <literal>t2</literal> in the sense of Roles - (<xref linkend="roles"/>). It is exported by - <ulink url="&libraryBaseLocation;/Data-Coerce.html"><literal>Data.Coerce</literal></ulink>, - which also contains the documentation. More details and discussion can be found in - the paper - <ulink href="http://www.cis.upenn.edu/~eir/papers/2014/coercible/coercible.pdf">Safe Coercions"</ulink>. - </para> - </sect2> - - </sect1> - -<sect1 id="constraint-kind"> -<title>The <literal>Constraint</literal> kind</title> - -<para> - Normally, <emphasis>constraints</emphasis> (which appear in types to the left of the - <literal>=></literal> arrow) have a very restricted syntax. They can only be: - <itemizedlist> - <listitem> - <para>Class constraints, e.g. <literal>Show a</literal></para> - </listitem> - <listitem> - <para><link linkend="implicit-parameters">Implicit parameter</link> constraints, - e.g. <literal>?x::Int</literal> (with the <option>-XImplicitParams</option> flag)</para> - </listitem> - <listitem> - <para><link linkend="equality-constraints">Equality constraints</link>, - e.g. <literal>a ~ Int</literal> (with the <option>-XTypeFamilies</option> or - <option>-XGADTs</option> flag)</para> - </listitem> - </itemizedlist> -</para> - -<para> - With the <option>-XConstraintKinds</option> flag, GHC becomes more liberal in - what it accepts as constraints in your program. To be precise, with this flag any - <emphasis>type</emphasis> of the new kind <literal>Constraint</literal> can be used as a constraint. - The following things have kind <literal>Constraint</literal>: - - <itemizedlist> - <listitem> - Anything which is already valid as a constraint without the flag: saturated applications to type classes, - implicit parameter and equality constraints. - </listitem> - <listitem> - Tuples, all of whose component types have kind <literal>Constraint</literal>. So for example the - type <literal>(Show a, Ord a)</literal> is of kind <literal>Constraint</literal>. - </listitem> - <listitem> - Anything whose form is not yet known, but the user has declared to have kind <literal>Constraint</literal> - (for which they need to import it from <literal>GHC.Exts</literal>). So for example - <literal>type Foo (f :: * -> Constraint) = forall b. f b => b -> b</literal> is allowed, as well as - examples involving type families: -<programlisting> -type family Typ a b :: Constraint -type instance Typ Int b = Show b -type instance Typ Bool b = Num b - -func :: Typ a b => a -> b -> b -func = ... -</programlisting> - </listitem> - </itemizedlist> -</para> - -<para> - Note that because constraints are just handled as types of a particular kind, this extension allows type - constraint synonyms: -</para> - -<programlisting> -type Stringy a = (Read a, Show a) -foo :: Stringy a => a -> (String, String -> a) -foo x = (show x, read) -</programlisting> - -<para> - Presently, only standard constraints, tuples and type synonyms for those two sorts of constraint are - permitted in instance contexts and superclasses (without extra flags). The reason is that permitting more general - constraints can cause type checking to loop, as it would with these two programs: -</para> - -<programlisting> -type family Clsish u a -type instance Clsish () a = Cls a -class Clsish () a => Cls a where -</programlisting> - -<programlisting> -class OkCls a where - -type family OkClsish u a -type instance OkClsish () a = OkCls a -instance OkClsish () a => OkCls a where -</programlisting> - -<para> - You may write programs that use exotic sorts of constraints in instance contexts and superclasses, but - to do so you must use <option>-XUndecidableInstances</option> to signal that you don't mind if the type checker - fails to terminate. -</para> - -</sect1> - -<sect1 id="other-type-extensions"> -<title>Other type system extensions</title> - -<sect2 id="explicit-foralls"><title>Explicit universal quantification (forall)</title> -<para> -Haskell type signatures are implicitly quantified. When the language option <option>-XExplicitForAll</option> -is used, the keyword <literal>forall</literal> -allows us to say exactly what this means. For example: -</para> -<para> -<programlisting> - g :: b -> b -</programlisting> -means this: -<programlisting> - g :: forall b. (b -> b) -</programlisting> -The two are treated identically. -</para> -<para> -Of course <literal>forall</literal> becomes a keyword; you can't use <literal>forall</literal> as -a type variable any more! -</para> -</sect2> - - -<sect2 id="flexible-contexts"><title>The context of a type signature</title> -<para> -The <option>-XFlexibleContexts</option> flag lifts the Haskell 98 restriction -that the type-class constraints in a type signature must have the -form <emphasis>(class type-variable)</emphasis> or -<emphasis>(class (type-variable type1 type2 ... typen))</emphasis>. -With <option>-XFlexibleContexts</option> -these type signatures are perfectly OK -<programlisting> - g :: Eq [a] => ... - g :: Ord (T a ()) => ... -</programlisting> -The flag <option>-XFlexibleContexts</option> also lifts the corresponding -restriction on class declarations (<xref linkend="superclass-rules"/>) and instance declarations -(<xref linkend="instance-rules"/>). -</para> -</sect2> - -<sect2 id="ambiguity"><title>Ambiguous types and the ambiguity check</title> - -<para> -Each user-written type signature is subjected to an -<emphasis>ambiguity check</emphasis>. -The ambiguity check rejects functions that can never be called; for example: -<programlisting> - f :: C a => Int -</programlisting> -The idea is there can be no legal calls to <literal>f</literal> because every call will -give rise to an ambiguous constraint. -Indeed, the <emphasis>only</emphasis> purpose of the -ambiguity check is to report functions that cannot possibly be called. -We could soundly omit the -ambiguity check on type signatures entirely, at the expense of -delaying ambiguity errors to call sites. Indeed, the language extension -<option>-XAllowAmbiguousTypes</option> switches off the ambiguity check. -</para> -<para> -Ambiguity can be subtle. Consider this example which uses functional dependencies: -<programlisting> - class D a b | a -> b where .. - h :: D Int b => Int -</programlisting> -The <literal>Int</literal> may well fix <literal>b</literal> at the call site, so that signature should -not be rejected. Moreover, the dependencies might be hidden. Consider -<programlisting> - class X a b where ... - class D a b | a -> b where ... - instance D a b => X [a] b where... - h :: X a b => a -> a -</programlisting> -Here <literal>h</literal>'s type looks ambiguous in <literal>b</literal>, but here's a legal call: -<programlisting> - ...(h [True])... -</programlisting> -That gives rise to a <literal>(X [Bool] beta)</literal> constraint, and using the -instance means we need <literal>(D Bool beta)</literal> and that -fixes <literal>beta</literal> via <literal>D</literal>'s -fundep! -</para> -<para> -Behind all these special cases there is a simple guiding principle. -Consider -<programlisting> - f :: <replaceable>type</replaceable> - f = ...blah... - - g :: <replaceable>type</replaceable> - g = f -</programlisting> -You would think that the definition of <literal>g</literal> would surely typecheck! -After all <literal>f</literal> has exactly the same type, and <literal>g=f</literal>. -But in fact <literal>f</literal>'s type -is instantiated and the instantiated constraints are solved against -the constraints bound by <literal>g</literal>'s signature. So, in the case an ambiguous type, solving will fail. -For example, consider the earlier definition <literal>f :: C a => Int</literal>: -<programlisting> - f :: C a => Int - f = ...blah... - - g :: C a => Int - g = f -</programlisting> -In <literal>g</literal>'s definition, -we'll instantiate to <literal>(C alpha)</literal> and try to -deduce <literal>(C alpha)</literal> from <literal>(C a)</literal>, -and fail. -</para> -<para> -So in fact we use this as our <emphasis>definition</emphasis> of ambiguity: a type -<literal><replaceable>ty</replaceable></literal> is -ambiguous if and only if <literal>((undefined :: <replaceable>ty</replaceable>) -:: <replaceable>ty</replaceable>)</literal> would fail to typecheck. We use a -very similar test for <emphasis>inferred</emphasis> types, to ensure that they too are -unambiguous. -</para> -<para><emphasis>Switching off the ambiguity check.</emphasis> -Even if a function is has an ambiguous type according the "guiding principle", -it is possible that the function is callable. For example: -<programlisting> - class D a b where ... - instance D Bool b where ... - - strange :: D a b => a -> a - strange = ...blah... - - foo = strange True -</programlisting> -Here <literal>strange</literal>'s type is ambiguous, but the call in <literal>foo</literal> -is OK because it gives rise to a constraint <literal>(D Bool beta)</literal>, which is -soluble by the <literal>(D Bool b)</literal> instance. So the language extension -<option>-XAllowAmbiguousTypes</option> allows you to switch off the ambiguity check. -But even with ambiguity checking switched off, GHC will complain about a function -that can <emphasis>never</emphasis> be called, such as this one: -<programlisting> - f :: (Int ~ Bool) => a -> a -</programlisting> -</para> - -<para> -<emphasis>A historical note.</emphasis> -GHC used to impose some more restrictive and less principled conditions -on type signatures. For type type -<literal>forall tv1..tvn (c1, ...,cn) => type</literal> -GHC used to require (a) that each universally quantified type variable -<literal>tvi</literal> must be "reachable" from <literal>type</literal>, -and (b) that every constraint <literal>ci</literal> mentions at least one of the -universally quantified type variables <literal>tvi</literal>. -These ad-hoc restrictions are completely subsumed by the new ambiguity check. -<emphasis>End of historical note.</emphasis> -</para> - -</sect2> - -<sect2 id="implicit-parameters"> -<title>Implicit parameters</title> - -<para> Implicit parameters are implemented as described in -"Implicit parameters: dynamic scoping with static types", -J Lewis, MB Shields, E Meijer, J Launchbury, -27th ACM Symposium on Principles of Programming Languages (POPL'00), -Boston, Jan 2000. -(Most of the following, still rather incomplete, documentation is -due to Jeff Lewis.)</para> - -<para>Implicit parameter support is enabled with the option -<option>-XImplicitParams</option>.</para> - -<para> -A variable is called <emphasis>dynamically bound</emphasis> when it is bound by the calling -context of a function and <emphasis>statically bound</emphasis> when bound by the callee's -context. In Haskell, all variables are statically bound. Dynamic -binding of variables is a notion that goes back to Lisp, but was later -discarded in more modern incarnations, such as Scheme. Dynamic binding -can be very confusing in an untyped language, and unfortunately, typed -languages, in particular Hindley-Milner typed languages like Haskell, -only support static scoping of variables. -</para> -<para> -However, by a simple extension to the type class system of Haskell, we -can support dynamic binding. Basically, we express the use of a -dynamically bound variable as a constraint on the type. These -constraints lead to types of the form <literal>(?x::t') => t</literal>, which says "this -function uses a dynamically-bound variable <literal>?x</literal> -of type <literal>t'</literal>". For -example, the following expresses the type of a sort function, -implicitly parameterised by a comparison function named <literal>cmp</literal>. -<programlisting> - sort :: (?cmp :: a -> a -> Bool) => [a] -> [a] -</programlisting> -The dynamic binding constraints are just a new form of predicate in the type class system. -</para> -<para> -An implicit parameter occurs in an expression using the special form <literal>?x</literal>, -where <literal>x</literal> is -any valid identifier (e.g. <literal>ord ?x</literal> is a valid expression). -Use of this construct also introduces a new -dynamic-binding constraint in the type of the expression. -For example, the following definition -shows how we can define an implicitly parameterised sort function in -terms of an explicitly parameterised <literal>sortBy</literal> function: -<programlisting> - sortBy :: (a -> a -> Bool) -> [a] -> [a] - - sort :: (?cmp :: a -> a -> Bool) => [a] -> [a] - sort = sortBy ?cmp -</programlisting> -</para> - -<sect3> -<title>Implicit-parameter type constraints</title> -<para> -Dynamic binding constraints behave just like other type class -constraints in that they are automatically propagated. Thus, when a -function is used, its implicit parameters are inherited by the -function that called it. For example, our <literal>sort</literal> function might be used -to pick out the least value in a list: -<programlisting> - least :: (?cmp :: a -> a -> Bool) => [a] -> a - least xs = head (sort xs) -</programlisting> -Without lifting a finger, the <literal>?cmp</literal> parameter is -propagated to become a parameter of <literal>least</literal> as well. With explicit -parameters, the default is that parameters must always be explicit -propagated. With implicit parameters, the default is to always -propagate them. -</para> -<para> -An implicit-parameter type constraint differs from other type class constraints in the -following way: All uses of a particular implicit parameter must have -the same type. This means that the type of <literal>(?x, ?x)</literal> -is <literal>(?x::a) => (a,a)</literal>, and not -<literal>(?x::a, ?x::b) => (a, b)</literal>, as would be the case for type -class constraints. -</para> - -<para> You can't have an implicit parameter in the context of a class or instance -declaration. For example, both these declarations are illegal: -<programlisting> - class (?x::Int) => C a where ... - instance (?x::a) => Foo [a] where ... -</programlisting> -Reason: exactly which implicit parameter you pick up depends on exactly where -you invoke a function. But the ``invocation'' of instance declarations is done -behind the scenes by the compiler, so it's hard to figure out exactly where it is done. -Easiest thing is to outlaw the offending types.</para> -<para> -Implicit-parameter constraints do not cause ambiguity. For example, consider: -<programlisting> - f :: (?x :: [a]) => Int -> Int - f n = n + length ?x - - g :: (Read a, Show a) => String -> String - g s = show (read s) -</programlisting> -Here, <literal>g</literal> has an ambiguous type, and is rejected, but <literal>f</literal> -is fine. The binding for <literal>?x</literal> at <literal>f</literal>'s call site is -quite unambiguous, and fixes the type <literal>a</literal>. -</para> -</sect3> - -<sect3> -<title>Implicit-parameter bindings</title> - -<para> -An implicit parameter is <emphasis>bound</emphasis> using the standard -<literal>let</literal> or <literal>where</literal> binding forms. -For example, we define the <literal>min</literal> function by binding -<literal>cmp</literal>. -<programlisting> - min :: [a] -> a - min = let ?cmp = (<=) in least -</programlisting> -</para> -<para> -A group of implicit-parameter bindings may occur anywhere a normal group of Haskell -bindings can occur, except at top level. That is, they can occur in a <literal>let</literal> -(including in a list comprehension, or do-notation, or pattern guards), -or a <literal>where</literal> clause. -Note the following points: -<itemizedlist> -<listitem><para> -An implicit-parameter binding group must be a -collection of simple bindings to implicit-style variables (no -function-style bindings, and no type signatures); these bindings are -neither polymorphic or recursive. -</para></listitem> -<listitem><para> -You may not mix implicit-parameter bindings with ordinary bindings in a -single <literal>let</literal> -expression; use two nested <literal>let</literal>s instead. -(In the case of <literal>where</literal> you are stuck, since you can't nest <literal>where</literal> clauses.) -</para></listitem> - -<listitem><para> -You may put multiple implicit-parameter bindings in a -single binding group; but they are <emphasis>not</emphasis> treated -as a mutually recursive group (as ordinary <literal>let</literal> bindings are). -Instead they are treated as a non-recursive group, simultaneously binding all the implicit -parameter. The bindings are not nested, and may be re-ordered without changing -the meaning of the program. -For example, consider: -<programlisting> - f t = let { ?x = t; ?y = ?x+(1::Int) } in ?x + ?y -</programlisting> -The use of <literal>?x</literal> in the binding for <literal>?y</literal> does not "see" -the binding for <literal>?x</literal>, so the type of <literal>f</literal> is -<programlisting> - f :: (?x::Int) => Int -> Int -</programlisting> -</para></listitem> -</itemizedlist> -</para> - -</sect3> - -<sect3><title>Implicit parameters and polymorphic recursion</title> - -<para> -Consider these two definitions: -<programlisting> - len1 :: [a] -> Int - len1 xs = let ?acc = 0 in len_acc1 xs - - len_acc1 [] = ?acc - len_acc1 (x:xs) = let ?acc = ?acc + (1::Int) in len_acc1 xs - - ------------ - - len2 :: [a] -> Int - len2 xs = let ?acc = 0 in len_acc2 xs - - len_acc2 :: (?acc :: Int) => [a] -> Int - len_acc2 [] = ?acc - len_acc2 (x:xs) = let ?acc = ?acc + (1::Int) in len_acc2 xs -</programlisting> -The only difference between the two groups is that in the second group -<literal>len_acc</literal> is given a type signature. -In the former case, <literal>len_acc1</literal> is monomorphic in its own -right-hand side, so the implicit parameter <literal>?acc</literal> is not -passed to the recursive call. In the latter case, because <literal>len_acc2</literal> -has a type signature, the recursive call is made to the -<emphasis>polymorphic</emphasis> version, which takes <literal>?acc</literal> -as an implicit parameter. So we get the following results in GHCi: -<programlisting> - Prog> len1 "hello" - 0 - Prog> len2 "hello" - 5 -</programlisting> -Adding a type signature dramatically changes the result! This is a rather -counter-intuitive phenomenon, worth watching out for. -</para> -</sect3> - -<sect3><title>Implicit parameters and monomorphism</title> - -<para>GHC applies the dreaded Monomorphism Restriction (section 4.5.5 of the -Haskell Report) to implicit parameters. For example, consider: -<programlisting> - f :: Int -> Int - f v = let ?x = 0 in - let y = ?x + v in - let ?x = 5 in - y -</programlisting> -Since the binding for <literal>y</literal> falls under the Monomorphism -Restriction it is not generalised, so the type of <literal>y</literal> is -simply <literal>Int</literal>, not <literal>(?x::Int) => Int</literal>. -Hence, <literal>(f 9)</literal> returns result <literal>9</literal>. -If you add a type signature for <literal>y</literal>, then <literal>y</literal> -will get type <literal>(?x::Int) => Int</literal>, so the occurrence of -<literal>y</literal> in the body of the <literal>let</literal> will see the -inner binding of <literal>?x</literal>, so <literal>(f 9)</literal> will return -<literal>14</literal>. -</para> -</sect3> - -<sect3 id="implicit-parameters-special"><title>Special implicit parameters</title> -<para> -GHC treats implicit parameters of type <literal>GHC.Types.CallStack</literal> -specially, by resolving them to the current location in the program. Consider: -<programlisting> - f :: String - f = show (?loc :: CallStack) -</programlisting> -GHC will automatically resolve <literal>?loc</literal> to its source -location. If another implicit parameter with type <literal>CallStack</literal> is -in scope, GHC will append the two locations, creating an explicit call-stack. For example: -<programlisting> - f :: (?stk :: CallStack) => String - f = show (?stk :: CallStack) -</programlisting> -will produce the location of <literal>?stk</literal>, followed by -<literal>f</literal>'s call-site. Note that the name of the implicit parameter does not -matter (we used <literal>?loc</literal> above), GHC will solve any implicit parameter -with the right type. The name does, however, matter when pushing new locations onto -existing stacks. Consider: -<programlisting> - f :: (?stk :: CallStack) => String - f = show (?loc :: CallStack) -</programlisting> -When we call <literal>f</literal>, the stack will include the use of <literal>?loc</literal>, -but not the call to <literal>f</literal>; in this case the names must match. -</para> -<para> -<literal>CallStack</literal> is kept abstract, but -GHC provides a function -<programlisting> - getCallStack :: CallStack -> [(String, SrcLoc)] -</programlisting> -to access the individual call-sites in the stack. The <literal>String</literal> -is the name of the function that was called, and the <literal>SrcLoc</literal> -provides the package, module, and file name, as well as the line and column -numbers. The stack will never be empty, as the first call-site -will be the location at which the implicit parameter was used. GHC will also -never infer <literal>?loc :: CallStack</literal> as a type constraint, which -means that functions must explicitly ask to be told about their call-sites. -</para> -<para> -A potential "gotcha" when using implicit <literal>CallStack</literal>s is that -the <literal>:type</literal> command in GHCi will not report the -<literal>?loc :: CallStack</literal> constraint, as the typechecker will -immediately solve it. Use <literal>:info</literal> instead to print the -unsolved type. -</para> -</sect3> -</sect2> - -<sect2 id="kinding"> -<title>Explicitly-kinded quantification</title> - -<para> -Haskell infers the kind of each type variable. Sometimes it is nice to be able -to give the kind explicitly as (machine-checked) documentation, -just as it is nice to give a type signature for a function. On some occasions, -it is essential to do so. For example, in his paper "Restricted Data Types in Haskell" (Haskell Workshop 1999) -John Hughes had to define the data type: -<screen> - data Set cxt a = Set [a] - | Unused (cxt a -> ()) -</screen> -The only use for the <literal>Unused</literal> constructor was to force the correct -kind for the type variable <literal>cxt</literal>. -</para> -<para> -GHC now instead allows you to specify the kind of a type variable directly, wherever -a type variable is explicitly bound, with the flag <option>-XKindSignatures</option>. -</para> -<para> -This flag enables kind signatures in the following places: -<itemizedlist> -<listitem><para><literal>data</literal> declarations: -<screen> - data Set (cxt :: * -> *) a = Set [a] -</screen></para></listitem> -<listitem><para><literal>type</literal> declarations: -<screen> - type T (f :: * -> *) = f Int -</screen></para></listitem> -<listitem><para><literal>class</literal> declarations: -<screen> - class (Eq a) => C (f :: * -> *) a where ... -</screen></para></listitem> -<listitem><para><literal>forall</literal>'s in type signatures: -<screen> - f :: forall (cxt :: * -> *). Set cxt Int -</screen></para></listitem> -</itemizedlist> -</para> - -<para> -The parentheses are required. Some of the spaces are required too, to -separate the lexemes. If you write <literal>(f::*->*)</literal> you -will get a parse error, because "<literal>::*->*</literal>" is a -single lexeme in Haskell. -</para> - -<para> -As part of the same extension, you can put kind annotations in types -as well. Thus: -<screen> - f :: (Int :: *) -> Int - g :: forall a. a -> (a :: *) -</screen> -The syntax is -<screen> - atype ::= '(' ctype '::' kind ') -</screen> -The parentheses are required. -</para> -</sect2> - - -<sect2 id="universal-quantification"> -<title>Arbitrary-rank polymorphism -</title> - -<para> -GHC's type system supports <emphasis>arbitrary-rank</emphasis> -explicit universal quantification in -types. -For example, all the following types are legal: -<programlisting> - f1 :: forall a b. a -> b -> a - g1 :: forall a b. (Ord a, Eq b) => a -> b -> a - - f2 :: (forall a. a->a) -> Int -> Int - g2 :: (forall a. Eq a => [a] -> a -> Bool) -> Int -> Int - - f3 :: ((forall a. a->a) -> Int) -> Bool -> Bool - - f4 :: Int -> (forall a. a -> a) -</programlisting> -Here, <literal>f1</literal> and <literal>g1</literal> are rank-1 types, and -can be written in standard Haskell (e.g. <literal>f1 :: a->b->a</literal>). -The <literal>forall</literal> makes explicit the universal quantification that -is implicitly added by Haskell. -</para> -<para> -The functions <literal>f2</literal> and <literal>g2</literal> have rank-2 types; -the <literal>forall</literal> is on the left of a function arrow. As <literal>g2</literal> -shows, the polymorphic type on the left of the function arrow can be overloaded. -</para> -<para> -The function <literal>f3</literal> has a rank-3 type; -it has rank-2 types on the left of a function arrow. -</para> -<para> -The language option <option>-XRankNTypes</option> (which implies <option>-XExplicitForAll</option>, <xref linkend="explicit-foralls"/>) -enables higher-rank types. -That is, you can nest <literal>forall</literal>s -arbitrarily deep in function arrows. -For example, a forall-type (also called a "type scheme"), -including a type-class context, is legal: -<itemizedlist> -<listitem> <para> On the left or right (see <literal>f4</literal>, for example) -of a function arrow </para> </listitem> -<listitem> <para> As the argument of a constructor, or type of a field, in a data type declaration. For -example, any of the <literal>f1,f2,f3,g1,g2</literal> above would be valid -field type signatures.</para> </listitem> -<listitem> <para> As the type of an implicit parameter </para> </listitem> -<listitem> <para> In a pattern type signature (see <xref linkend="scoped-type-variables"/>) </para> </listitem> -</itemizedlist> -The <option>-XRankNTypes</option> option is also required for any -type with a <literal>forall</literal> or -context to the right of an arrow (e.g. <literal>f :: Int -> forall a. a->a</literal>, or -<literal>g :: Int -> Ord a => a -> a</literal>). Such types are technically rank 1, but -are clearly not Haskell-98, and an extra flag did not seem worth the bother. -</para> - -<para> -In particular, in <literal>data</literal> and -<literal>newtype</literal> declarations the constructor arguments may -be polymorphic types of any rank; see examples in <xref linkend="univ"/>. -Note that the declared types are -nevertheless always monomorphic. This is important because by default -GHC will not instantiate type variables to a polymorphic type -(<xref linkend="impredicative-polymorphism"/>). -</para> -<para> -The obsolete language options <option>-XPolymorphicComponents</option> -and <option>-XRank2Types</option> are synonyms for -<option>-XRankNTypes</option>. They used to specify finer -distinctions that GHC no longer makes. (They should really elicit a -deprecation warning, but they don't, purely to avoid the need to -library authors to change their old flags specifications.) -</para> - -<sect3 id="univ"> -<title>Examples -</title> - -<para> -These are examples of <literal>data</literal> and <literal>newtype</literal> -declarations whose data constructors have polymorphic argument types: -<programlisting> -data T a = T1 (forall b. b -> b -> b) a - -data MonadT m = MkMonad { return :: forall a. a -> m a, - bind :: forall a b. m a -> (a -> m b) -> m b - } - -newtype Swizzle = MkSwizzle (forall a. Ord a => [a] -> [a]) -</programlisting> - -</para> - -<para> -The constructors have rank-2 types: -</para> - -<para> - -<programlisting> -T1 :: forall a. (forall b. b -> b -> b) -> a -> T a -MkMonad :: forall m. (forall a. a -> m a) - -> (forall a b. m a -> (a -> m b) -> m b) - -> MonadT m -MkSwizzle :: (forall a. Ord a => [a] -> [a]) -> Swizzle -</programlisting> - -</para> - -<para> -In earlier versions of GHC, it was possible to omit the <literal>forall</literal> -in the type of the constructor if there was an explicit context. For example: - -<programlisting> -newtype Swizzle' = MkSwizzle' (Ord a => [a] -> [a]) -</programlisting> - -As of GHC 7.10, this is deprecated. The <literal>-fwarn-context-quantification</literal> -flag detects this situation and issues a warning. In GHC 7.12, declarations -such as <literal>MkSwizzle'</literal> will cause an out-of-scope error. -</para> - -<para> -As for type signatures, implicit quantification happens for non-overloaded -types too. So if you write this: - -<programlisting> - f :: (a -> a) -> a -</programlisting> - -it's just as if you had written this: - -<programlisting> - f :: forall a. (a -> a) -> a -</programlisting> - -That is, since the type variable <literal>a</literal> isn't in scope, it's -implicitly universally quantified. -</para> - -<para> -You construct values of types <literal>T1, MonadT, Swizzle</literal> by applying -the constructor to suitable values, just as usual. For example, -</para> - -<para> - -<programlisting> - a1 :: T Int - a1 = T1 (\xy->x) 3 - - a2, a3 :: Swizzle - a2 = MkSwizzle sort - a3 = MkSwizzle reverse - - a4 :: MonadT Maybe - a4 = let r x = Just x - b m k = case m of - Just y -> k y - Nothing -> Nothing - in - MkMonad r b - - mkTs :: (forall b. b -> b -> b) -> a -> [T a] - mkTs f x y = [T1 f x, T1 f y] -</programlisting> - -</para> - -<para> -The type of the argument can, as usual, be more general than the type -required, as <literal>(MkSwizzle reverse)</literal> shows. (<function>reverse</function> -does not need the <literal>Ord</literal> constraint.) -</para> - -<para> -When you use pattern matching, the bound variables may now have -polymorphic types. For example: -</para> - -<para> - -<programlisting> - f :: T a -> a -> (a, Char) - f (T1 w k) x = (w k x, w 'c' 'd') - - g :: (Ord a, Ord b) => Swizzle -> [a] -> (a -> b) -> [b] - g (MkSwizzle s) xs f = s (map f (s xs)) - - h :: MonadT m -> [m a] -> m [a] - h m [] = return m [] - h m (x:xs) = bind m x $ \y -> - bind m (h m xs) $ \ys -> - return m (y:ys) -</programlisting> - -</para> - -<para> -In the function <function>h</function> we use the record selectors <literal>return</literal> -and <literal>bind</literal> to extract the polymorphic bind and return functions -from the <literal>MonadT</literal> data structure, rather than using pattern -matching. -</para> -</sect3> - -<sect3> -<title>Type inference</title> - -<para> -In general, type inference for arbitrary-rank types is undecidable. -GHC uses an algorithm proposed by Odersky and Laufer ("Putting type annotations to work", POPL'96) -to get a decidable algorithm by requiring some help from the programmer. -We do not yet have a formal specification of "some help" but the rule is this: -</para> -<para> -<emphasis>For a lambda-bound or case-bound variable, x, either the programmer -provides an explicit polymorphic type for x, or GHC's type inference will assume -that x's type has no foralls in it</emphasis>. -</para> -<para> -What does it mean to "provide" an explicit type for x? You can do that by -giving a type signature for x directly, using a pattern type signature -(<xref linkend="scoped-type-variables"/>), thus: -<programlisting> - \ f :: (forall a. a->a) -> (f True, f 'c') -</programlisting> -Alternatively, you can give a type signature to the enclosing -context, which GHC can "push down" to find the type for the variable: -<programlisting> - (\ f -> (f True, f 'c')) :: (forall a. a->a) -> (Bool,Char) -</programlisting> -Here the type signature on the expression can be pushed inwards -to give a type signature for f. Similarly, and more commonly, -one can give a type signature for the function itself: -<programlisting> - h :: (forall a. a->a) -> (Bool,Char) - h f = (f True, f 'c') -</programlisting> -You don't need to give a type signature if the lambda bound variable -is a constructor argument. Here is an example we saw earlier: -<programlisting> - f :: T a -> a -> (a, Char) - f (T1 w k) x = (w k x, w 'c' 'd') -</programlisting> -Here we do not need to give a type signature to <literal>w</literal>, because -it is an argument of constructor <literal>T1</literal> and that tells GHC all -it needs to know. -</para> - -</sect3> - - -<sect3 id="implicit-quant"> -<title>Implicit quantification</title> - -<para> -GHC performs implicit quantification as follows. <emphasis>At the top level (only) of -user-written types, if and only if there is no explicit <literal>forall</literal>, -GHC finds all the type variables mentioned in the type that are not already -in scope, and universally quantifies them.</emphasis> For example, the following pairs are -equivalent: -<programlisting> - f :: a -> a - f :: forall a. a -> a - - g (x::a) = let - h :: a -> b -> b - h x y = y - in ... - g (x::a) = let - h :: forall b. a -> b -> b - h x y = y - in ... -</programlisting> -</para> -<para> -Notice that GHC does <emphasis>not</emphasis> find the innermost possible quantification -point. For example: -<programlisting> - f :: (a -> a) -> Int - -- MEANS - f :: forall a. (a -> a) -> Int - -- NOT - f :: (forall a. a -> a) -> Int - - - g :: (Ord a => a -> a) -> Int - -- MEANS the illegal type - g :: forall a. (Ord a => a -> a) -> Int - -- NOT - g :: (forall a. Ord a => a -> a) -> Int -</programlisting> -The latter produces an illegal type, which you might think is silly, -but at least the rule is simple. If you want the latter type, you -can write your for-alls explicitly. Indeed, doing so is strongly advised -for rank-2 types. -</para> -</sect3> -</sect2> - - -<sect2 id="impredicative-polymorphism"> -<title>Impredicative polymorphism -</title> -<para>In general, GHC will only instantiate a polymorphic function at -a monomorphic type (one with no foralls). For example, -<programlisting> -runST :: (forall s. ST s a) -> a -id :: forall b. b -> b - -foo = id runST -- Rejected -</programlisting> -The definition of <literal>foo</literal> is rejected because one would have to instantiate -<literal>id</literal>'s type with <literal>b := (forall s. ST s a) -> a</literal>, and -that is not allowed. -Instanting polymorpic type variables with polymorphic types is called <emphasis>impredicative polymorphism</emphasis>. -</para> - -<para>GHC has extremely flaky support for <emphasis>impredicative polymorphism</emphasis>, -enabled with <option>-XImpredicativeTypes</option>. -If it worked, this would mean -that you <emphasis>could</emphasis> call a polymorphic function at a polymorphic type, and -parameterise data structures over polymorphic types. For example: -<programlisting> - f :: Maybe (forall a. [a] -> [a]) -> Maybe ([Int], [Char]) - f (Just g) = Just (g [3], g "hello") - f Nothing = Nothing -</programlisting> -Notice here that the <literal>Maybe</literal> type is parameterised by the -<emphasis>polymorphic</emphasis> type <literal>(forall a. [a] -> [a])</literal>. -However <emphasis>the extension should be considered highly experimental, and certainly un-supported</emphasis>. -You are welcome to try it, but please don't rely on it working consistently, or -working the same in subsequent releases. See -<ulink url="https://ghc.haskell.org/trac/ghc/wiki/ImpredicativePolymorphism">this wiki page</ulink> -for more details. -</para> -<para>If you want impredicative polymorphism, the main workaround is to use a newtype wrapper. -The <literal>id runST</literal> example can be written using theis workaround like this: -<programlisting> -runST :: (forall s. ST s a) -> a -id :: forall b. b -> b - -nwetype Wrap a = Wrap { unWrap :: (forall s. ST s a) -> a } - -foo :: (forall s. ST s a) -> a -foo = unWrap (id (Wrap runST)) - -- Here id is called at monomorphic type (Wrap a) -</programlisting> -</para> - -</sect2> - -<sect2 id="scoped-type-variables"> -<title>Lexically scoped type variables -</title> - -<para> -GHC supports <emphasis>lexically scoped type variables</emphasis>, without -which some type signatures are simply impossible to write. For example: -<programlisting> -f :: forall a. [a] -> [a] -f xs = ys ++ ys - where - ys :: [a] - ys = reverse xs -</programlisting> -The type signature for <literal>f</literal> brings the type variable <literal>a</literal> into scope, -because of the explicit <literal>forall</literal> (<xref linkend="decl-type-sigs"/>). -The type variables bound by a <literal>forall</literal> scope over -the entire definition of the accompanying value declaration. -In this example, the type variable <literal>a</literal> scopes over the whole -definition of <literal>f</literal>, including over -the type signature for <varname>ys</varname>. -In Haskell 98 it is not possible to declare -a type for <varname>ys</varname>; a major benefit of scoped type variables is that -it becomes possible to do so. -</para> -<para>Lexically-scoped type variables are enabled by -<option>-XScopedTypeVariables</option>. This flag implies <option>-XRelaxedPolyRec</option>. -</para> - -<sect3> -<title>Overview</title> - -<para>The design follows the following principles -<itemizedlist> -<listitem><para>A scoped type variable stands for a type <emphasis>variable</emphasis>, and not for -a <emphasis>type</emphasis>. (This is a change from GHC's earlier -design.)</para></listitem> -<listitem><para>Furthermore, distinct lexical type variables stand for distinct -type variables. This means that every programmer-written type signature -(including one that contains free scoped type variables) denotes a -<emphasis>rigid</emphasis> type; that is, the type is fully known to the type -checker, and no inference is involved.</para></listitem> -<listitem><para>Lexical type variables may be alpha-renamed freely, without -changing the program.</para></listitem> -</itemizedlist> -</para> -<para> -A <emphasis>lexically scoped type variable</emphasis> can be bound by: -<itemizedlist> -<listitem><para>A declaration type signature (<xref linkend="decl-type-sigs"/>)</para></listitem> -<listitem><para>An expression type signature (<xref linkend="exp-type-sigs"/>)</para></listitem> -<listitem><para>A pattern type signature (<xref linkend="pattern-type-sigs"/>)</para></listitem> -<listitem><para>Class and instance declarations (<xref linkend="cls-inst-scoped-tyvars"/>)</para></listitem> -</itemizedlist> -</para> -<para> -In Haskell, a programmer-written type signature is implicitly quantified over -its free type variables (<ulink -url="http://www.haskell.org/onlinereport/decls.html#sect4.1.2">Section -4.1.2</ulink> -of the Haskell Report). -Lexically scoped type variables affect this implicit quantification rules -as follows: any type variable that is in scope is <emphasis>not</emphasis> universally -quantified. For example, if type variable <literal>a</literal> is in scope, -then -<programlisting> - (e :: a -> a) means (e :: a -> a) - (e :: b -> b) means (e :: forall b. b->b) - (e :: a -> b) means (e :: forall b. a->b) -</programlisting> -</para> - - -</sect3> - - -<sect3 id="decl-type-sigs"> -<title>Declaration type signatures</title> -<para>A declaration type signature that has <emphasis>explicit</emphasis> -quantification (using <literal>forall</literal>) brings into scope the -explicitly-quantified -type variables, in the definition of the named function. For example: -<programlisting> - f :: forall a. [a] -> [a] - f (x:xs) = xs ++ [ x :: a ] -</programlisting> -The "<literal>forall a</literal>" brings "<literal>a</literal>" into scope in -the definition of "<literal>f</literal>". -</para> -<para>This only happens if: -<itemizedlist> -<listitem><para> The quantification in <literal>f</literal>'s type -signature is explicit. For example: -<programlisting> - g :: [a] -> [a] - g (x:xs) = xs ++ [ x :: a ] -</programlisting> -This program will be rejected, because "<literal>a</literal>" does not scope -over the definition of "<literal>g</literal>", so "<literal>x::a</literal>" -means "<literal>x::forall a. a</literal>" by Haskell's usual implicit -quantification rules. -</para></listitem> -<listitem><para> The signature gives a type for a function binding or a bare variable binding, -not a pattern binding. -For example: -<programlisting> - f1 :: forall a. [a] -> [a] - f1 (x:xs) = xs ++ [ x :: a ] -- OK - - f2 :: forall a. [a] -> [a] - f2 = \(x:xs) -> xs ++ [ x :: a ] -- OK - - f3 :: forall a. [a] -> [a] - Just f3 = Just (\(x:xs) -> xs ++ [ x :: a ]) -- Not OK! -</programlisting> -The binding for <literal>f3</literal> is a pattern binding, and so its type signature -does not bring <literal>a</literal> into scope. However <literal>f1</literal> is a -function binding, and <literal>f2</literal> binds a bare variable; in both cases -the type signature brings <literal>a</literal> into scope. -</para></listitem> -</itemizedlist> -</para> -</sect3> - -<sect3 id="exp-type-sigs"> -<title>Expression type signatures</title> - -<para>An expression type signature that has <emphasis>explicit</emphasis> -quantification (using <literal>forall</literal>) brings into scope the -explicitly-quantified -type variables, in the annotated expression. For example: -<programlisting> - f = runST ( (op >>= \(x :: STRef s Int) -> g x) :: forall s. ST s Bool ) -</programlisting> -Here, the type signature <literal>forall s. ST s Bool</literal> brings the -type variable <literal>s</literal> into scope, in the annotated expression -<literal>(op >>= \(x :: STRef s Int) -> g x)</literal>. -</para> - -</sect3> - -<sect3 id="pattern-type-sigs"> -<title>Pattern type signatures</title> -<para> -A type signature may occur in any pattern; this is a <emphasis>pattern type -signature</emphasis>. -For example: -<programlisting> - -- f and g assume that 'a' is already in scope - f = \(x::Int, y::a) -> x - g (x::a) = x - h ((x,y) :: (Int,Bool)) = (y,x) -</programlisting> -In the case where all the type variables in the pattern type signature are -already in scope (i.e. bound by the enclosing context), matters are simple: the -signature simply constrains the type of the pattern in the obvious way. -</para> -<para> -Unlike expression and declaration type signatures, pattern type signatures are not implicitly generalised. -The pattern in a <emphasis>pattern binding</emphasis> may only mention type variables -that are already in scope. For example: -<programlisting> - f :: forall a. [a] -> (Int, [a]) - f xs = (n, zs) - where - (ys::[a], n) = (reverse xs, length xs) -- OK - zs::[a] = xs ++ ys -- OK - - Just (v::b) = ... -- Not OK; b is not in scope -</programlisting> -Here, the pattern signatures for <literal>ys</literal> and <literal>zs</literal> -are fine, but the one for <literal>v</literal> is not because <literal>b</literal> is -not in scope. -</para> -<para> -However, in all patterns <emphasis>other</emphasis> than pattern bindings, a pattern -type signature may mention a type variable that is not in scope; in this case, -<emphasis>the signature brings that type variable into scope</emphasis>. -This is particularly important for existential data constructors. For example: -<programlisting> - data T = forall a. MkT [a] - - k :: T -> T - k (MkT [t::a]) = MkT t3 - where - t3::[a] = [t,t,t] -</programlisting> -Here, the pattern type signature <literal>(t::a)</literal> mentions a lexical type -variable that is not already in scope. Indeed, it <emphasis>cannot</emphasis> already be in scope, -because it is bound by the pattern match. GHC's rule is that in this situation -(and only then), a pattern type signature can mention a type variable that is -not already in scope; the effect is to bring it into scope, standing for the -existentially-bound type variable. -</para> -<para> -When a pattern type signature binds a type variable in this way, GHC insists that the -type variable is bound to a <emphasis>rigid</emphasis>, or fully-known, type variable. -This means that any user-written type signature always stands for a completely known type. -</para> -<para> -If all this seems a little odd, we think so too. But we must have -<emphasis>some</emphasis> way to bring such type variables into scope, else we -could not name existentially-bound type variables in subsequent type signatures. -</para> -<para> -This is (now) the <emphasis>only</emphasis> situation in which a pattern type -signature is allowed to mention a lexical variable that is not already in -scope. -For example, both <literal>f</literal> and <literal>g</literal> would be -illegal if <literal>a</literal> was not already in scope. -</para> - - -</sect3> - -<!-- ==================== Commented out part about result type signatures - -<sect3 id="result-type-sigs"> -<title>Result type signatures</title> - -<para> -The result type of a function, lambda, or case expression alternative can be given a signature, thus: - -<programlisting> - {- f assumes that 'a' is already in scope -} - f x y :: [a] = [x,y,x] - - g = \ x :: [Int] -> [3,4] - - h :: forall a. [a] -> a - h xs = case xs of - (y:ys) :: a -> y -</programlisting> -The final <literal>:: [a]</literal> after the patterns of <literal>f</literal> gives the type of -the result of the function. Similarly, the body of the lambda in the RHS of -<literal>g</literal> is <literal>[Int]</literal>, and the RHS of the case -alternative in <literal>h</literal> is <literal>a</literal>. -</para> -<para> A result type signature never brings new type variables into scope.</para> -<para> -There are a couple of syntactic wrinkles. First, notice that all three -examples would parse quite differently with parentheses: -<programlisting> - {- f assumes that 'a' is already in scope -} - f x (y :: [a]) = [x,y,x] - - g = \ (x :: [Int]) -> [3,4] - - h :: forall a. [a] -> a - h xs = case xs of - ((y:ys) :: a) -> y -</programlisting> -Now the signature is on the <emphasis>pattern</emphasis>; and -<literal>h</literal> would certainly be ill-typed (since the pattern -<literal>(y:ys)</literal> cannot have the type <literal>a</literal>. - -Second, to avoid ambiguity, the type after the “<literal>::</literal>” in a result -pattern signature on a lambda or <literal>case</literal> must be atomic (i.e. a single -token or a parenthesised type of some sort). To see why, -consider how one would parse this: -<programlisting> - \ x :: a -> b -> x -</programlisting> -</para> -</sect3> - - --> - -<sect3 id="cls-inst-scoped-tyvars"> -<title>Class and instance declarations</title> -<para> - -The type variables in the head of a <literal>class</literal> or <literal>instance</literal> declaration -scope over the methods defined in the <literal>where</literal> part. You do not even need -an explicit <literal>forall</literal>. For example: -<programlisting> - class C a where - op :: [a] -> a - - op xs = let ys::[a] - ys = reverse xs - in - head ys - - instance C b => C [b] where - op xs = reverse (head (xs :: [[b]])) -</programlisting> -</para> -</sect3> - -</sect2> - -<sect2> -<title>Bindings and generalisation</title> - -<sect3 id="monomorphism"> -<title>Switching off the dreaded Monomorphism Restriction</title> - <indexterm><primary><option>-XNoMonomorphismRestriction</option></primary></indexterm> - -<para>Haskell's monomorphism restriction (see -<ulink url="http://www.haskell.org/onlinereport/decls.html#sect4.5.5">Section -4.5.5</ulink> -of the Haskell Report) -can be completely switched off by -<option>-XNoMonomorphismRestriction</option>. Since GHC 7.8.1, the monomorphism -restriction is switched off by default in GHCi's interactive options (see <xref linkend="ghci-interactive-options"/>). -</para> -</sect3> - - -<sect3 id="typing-binds"> -<title>Generalised typing of mutually recursive bindings</title> - -<para> -The Haskell Report specifies that a group of bindings (at top level, or in a -<literal>let</literal> or <literal>where</literal>) should be sorted into -strongly-connected components, and then type-checked in dependency order -(<ulink url="http://www.haskell.org/onlinereport/decls.html#sect4.5.1">Haskell -Report, Section 4.5.1</ulink>). -As each group is type-checked, any binders of the group that -have -an explicit type signature are put in the type environment with the specified -polymorphic type, -and all others are monomorphic until the group is generalised -(<ulink url="http://www.haskell.org/onlinereport/decls.html#sect4.5.2">Haskell Report, Section 4.5.2</ulink>). -</para> - -<para>Following a suggestion of Mark Jones, in his paper -<ulink url="http://citeseer.ist.psu.edu/424440.html">Typing Haskell in -Haskell</ulink>, -GHC implements a more general scheme. If <option>-XRelaxedPolyRec</option> is -specified: -<emphasis>the dependency analysis ignores references to variables that have an explicit -type signature</emphasis>. -As a result of this refined dependency analysis, the dependency groups are smaller, and more bindings will -typecheck. For example, consider: -<programlisting> - f :: Eq a => a -> Bool - f x = (x == x) || g True || g "Yes" - - g y = (y <= y) || f True -</programlisting> -This is rejected by Haskell 98, but under Jones's scheme the definition for -<literal>g</literal> is typechecked first, separately from that for -<literal>f</literal>, -because the reference to <literal>f</literal> in <literal>g</literal>'s right -hand side is ignored by the dependency analysis. Then <literal>g</literal>'s -type is generalised, to get -<programlisting> - g :: Ord a => a -> Bool -</programlisting> -Now, the definition for <literal>f</literal> is typechecked, with this type for -<literal>g</literal> in the type environment. -</para> - -<para> -The same refined dependency analysis also allows the type signatures of -mutually-recursive functions to have different contexts, something that is illegal in -Haskell 98 (Section 4.5.2, last sentence). With -<option>-XRelaxedPolyRec</option> -GHC only insists that the type signatures of a <emphasis>refined</emphasis> group have identical -type signatures; in practice this means that only variables bound by the same -pattern binding must have the same context. For example, this is fine: -<programlisting> - f :: Eq a => a -> Bool - f x = (x == x) || g True - - g :: Ord a => a -> Bool - g y = (y <= y) || f True -</programlisting> -</para> -</sect3> - -<sect3 id="mono-local-binds"> -<title>Let-generalisation</title> -<para> -An ML-style language usually generalises the type of any let-bound or where-bound variable, -so that it is as polymorphic as possible. -With the flag <option>-XMonoLocalBinds</option> GHC implements a slightly more conservative policy, -using the following rules: -<itemizedlist> - <listitem><para> - A variable is <emphasis>closed</emphasis> if and only if - <itemizedlist> - <listitem><para> the variable is let-bound</para></listitem> - <listitem><para> one of the following holds: - <itemizedlist> - <listitem><para>the variable has an explicit type signature that has no free type variables, or</para></listitem> - <listitem><para>its binding group is fully generalised (see next bullet) </para></listitem> - </itemizedlist> - </para></listitem> - </itemizedlist> - </para></listitem> - - <listitem><para> - A binding group is <emphasis>fully generalised</emphasis> if and only if - <itemizedlist> - <listitem><para>each of its free variables is either imported or closed, and</para></listitem> - <listitem><para>the binding is not affected by the monomorphism restriction - (<ulink url="http://www.haskell.org/onlinereport/decls.html#sect4.5.5">Haskell Report, Section 4.5.5</ulink>)</para></listitem> - </itemizedlist> - </para></listitem> -</itemizedlist> -For example, consider -<programlisting> -f x = x + 1 -g x = let h y = f y * 2 - k z = z+x - in h x + k x -</programlisting> -Here <literal>f</literal> is generalised because it has no free variables; and its binding group -is unaffected by the monomorphism restriction; and hence <literal>f</literal> is closed. -The same reasoning applies to <literal>g</literal>, except that it has one closed free variable, namely <literal>f</literal>. -Similarly <literal>h</literal> is closed, <emphasis>even though it is not bound at top level</emphasis>, -because its only free variable <literal>f</literal> is closed. -But <literal>k</literal> is not closed, because it mentions <literal>x</literal> which is not closed (because it is not let-bound). -</para> -<para> -Notice that a top-level binding that is affected by the monomorphism restriction is not closed, and hence may -in turn prevent generalisation of bindings that mention it. -</para> -<para> -The rationale for this more conservative strategy is given in -<ulink url="http://research.microsoft.com/~simonpj/papers/constraints/index.htm">the papers</ulink> "Let should not be generalised" and "Modular type inference with local assumptions", and -a related <ulink url="http://ghc.haskell.org/trac/ghc/blog/LetGeneralisationInGhc7">blog post</ulink>. -</para><para> -The flag <option>-XMonoLocalBinds</option> is implied by <option>-XTypeFamilies</option> and <option>-XGADTs</option>. You can switch it off again -with <option>-XNoMonoLocalBinds</option> but type inference becomes less predicatable if you do so. (Read the papers!) -</para> -</sect3> -</sect2> - -</sect1> -<!-- ==================== End of type system extensions ================= --> - -<sect1 id="typed-holes"> -<title>Typed Holes</title> - -<para> -Typed holes are a feature of GHC that allows special placeholders written with -a leading underscore (e.g., "<literal>_</literal>", "<literal>_foo</literal>", -"<literal>_bar</literal>"), to be used as expressions. During compilation these -holes will generate an error message that describes which type is expected at -the hole's location, information about the origin of any free type variables, -and a list of local bindings that might help fill the hole with actual code. -Typed holes are always enabled in GHC. -</para> - -<para> -The goal of typed holes is to help with writing Haskell code rather than to -change the type system. Typed holes can be used to obtain extra information -from the type checker, which might otherwise be hard to get. Normally, using -GHCi, users can inspect the (inferred) type signatures of all top-level -bindings. However, this method is less convenient with terms that are not -defined on top-level or inside complex expressions. Holes allow the user to -check the type of the term they are about to write. -</para> - -<para> -For example, compiling the following module with GHC: -<programlisting> -f :: a -> a -f x = _ -</programlisting> -will fail with the following error: -<programlisting> -hole.hs:2:7: - Found hole `_' with type: a - Where: `a' is a rigid type variable bound by - the type signature for f :: a -> a at hole.hs:1:6 - Relevant bindings include - f :: a -> a (bound at hole.hs:2:1) - x :: a (bound at hole.hs:2:3) - In the expression: _ - In an equation for `f': f x = _ -</programlisting> -</para> - -<para> -Here are some more details: -<itemizedlist> -<listitem> -<para> -A "<literal>Found hole</literal>" error usually terminates compilation, like -any other type error. After all, you have omitted some code from your program. -Nevertheless, you can run and test a piece of code containing holes, by using the flag -<option>-fdefer-typed-holes</option> flag. This flag defers errors -produced by typed holes until runtime, and converts them into compile-time warnings. -These warnings can in turn -be suppressed entirely by <option>-fnowarn-typed-holes</option>). -</para> -<para> -The result is that a hole will behave -like <literal>undefined</literal>, but with the added benefits that it shows a -warning at compile time, and will show the same message if it gets -evaluated at runtime. This behaviour follows that of the -<literal>-fdefer-type-errors</literal> option, which implies -<literal>-fdefer-typed-holes</literal>. See <xref linkend="defer-type-errors"/>. -</para> -</listitem> - -<listitem><para> -All unbound identifiers are treated as typed holes, <emphasis>whether or not they -start with an underscore</emphasis>. The only difference is in the error message: -<programlisting> -cons z = z : True : _x : y -</programlisting> -yields the errors -<programlisting> -Foo.hs:5:15: error: - Found hole: _x :: Bool - Relevant bindings include - p :: Bool (bound at Foo.hs:3:6) - cons :: Bool -> [Bool] (bound at Foo.hs:3:1) - -Foo.hs:5:20: error: - Variable not in scope: y :: [Bool] -</programlisting> -More information is given for explicit holes (i.e. ones that start with an underscore), -than for out-of-scope variables, because the latter are often -unintended typos, so the extra information is distracting. -If you the detailed information, use a leading underscore to -make explicit your intent to use a hole. -</para></listitem> - -<listitem><para> -Unbound identifiers with the same name are never unified, even within the -same function, but shown individually. -For example: -<programlisting> -cons = _x : _x -</programlisting> -results in the following errors: -<programlisting> -unbound.hs:1:8: - Found hole '_x' with type: a - Where: `a' is a rigid type variable bound by - the inferred type of cons :: [a] at unbound.hs:1:1 - Relevant bindings include cons :: [a] (bound at unbound.hs:1:1) - In the first argument of `(:)', namely `_x' - In the expression: _x : _x - In an equation for `cons': cons = _x : _x - -unbound.hs:1:13: - Found hole '_x' with type: [a] - Arising from: an undeclared identifier `_x' at unbound.hs:1:13-14 - Where: `a' is a rigid type variable bound by - the inferred type of cons :: [a] at unbound.hs:1:1 - Relevant bindings include cons :: [a] (bound at unbound.hs:1:1) - In the second argument of `(:)', namely `_x' - In the expression: _x : _x - In an equation for `cons': cons = _x : _x -</programlisting> -Notice the two different types reported for the two different occurrences of <literal>_x</literal>. -</para></listitem> - -<listitem><para> -No language extension is required to use typed holes. The lexeme "<literal>_</literal>" was previously -illegal in Haskell, but now has a more informative error message. The lexeme "<literal>_x</literal>" -is a perfectly legal variable, and its behaviour is unchanged when it is in scope. For example -<programlisting> -f _x = _x + 1 -</programlisting> -does not elict any errors. Only a variable <emphasis>that is not in scope</emphasis> -(whether or not it starts with an underscore) -is treated as an error (which it always was), albeit now with a more informative error message. -</para></listitem> - -<listitem><para> -Unbound data constructors used in expressions behave exactly as above. -However, unbound data constructors used in <emphasis>patterns</emphasis> cannot -be deferred, and instead bring compilation to a halt. (In implementation terms, they -are reported by the renamer rather than the type checker.) -</para></listitem> - -</itemizedlist> -</para> - -</sect1> -<!-- ==================== Partial Type Signatures ================= --> - -<sect1 id="partial-type-signatures"> -<title>Partial Type Signatures</title> - -<para> -A partial type signature is a type signature containing special placeholders -written with a leading underscore (e.g., "<literal>_</literal>", -"<literal>_foo</literal>", "<literal>_bar</literal>") called -<emphasis>wildcards</emphasis>. Partial type signatures are to type signatures -what <xref linkend="typed-holes"/> are to expressions. During compilation these -wildcards or holes will generate an error message that describes which type -was inferred at the hole's location, and information about the origin of any -free type variables. GHC reports such error messages by default.</para> - -<para> -Unlike <xref linkend="typed-holes"/>, which make the program incomplete and -will generate errors when they are evaluated, this needn't be the case for -holes in type signatures. The type checker is capable (in most cases) of -type-checking a binding with or without a type signature. A partial type -signature bridges the gap between the two extremes, the programmer can choose -which parts of a type to annotate and which to leave over to the type-checker -to infer. -</para> - -<para> -By default, the type-checker will report an error message for each hole in a -partial type signature, informing the programmer of the inferred type. When -the <option>-XPartialTypeSignatures</option> flag is enabled, the type-checker -will accept the inferred type for each hole, generating warnings instead of -errors. Additionally, these warnings can be silenced with the -<option>-fno-warn-partial-type-signatures</option> flag. -</para> - -<sect2 id="pts-syntax"> -<title>Syntax</title> - -<para> -A (partial) type signature has the following form: <literal>forall a b .. . -(C1, C2, ..) => tau</literal>. It consists of three parts: -</para> - -<itemizedlist> - <listitem>The type variables: <literal>a b ..</literal></listitem> - <listitem>The constraints: <literal>(C1, C2, ..)</literal></listitem> - <listitem>The (mono)type: <literal>tau</literal></listitem> -</itemizedlist> - -<para> -We distinguish three kinds of wildcards. -</para> - -<sect3 id="type-wildcards"> -<title>Type Wildcards</title> -<para> -Wildcards occurring within the monotype (tau) part of the type signature are -<emphasis>type wildcards</emphasis> ("type" is often omitted as this is the -default kind of wildcard). Type wildcards can be instantiated to any monotype -like <literal>Bool</literal> or <literal>Maybe [Bool]</literal>, including -functions and higher-kinded types like <literal>(Int -> Bool)</literal> or -<literal>Maybe</literal>. -</para> -<programlisting> -not' :: Bool -> _ -not' x = not x --- Inferred: Bool -> Bool - -maybools :: _ -maybools = Just [True] --- Inferred: Maybe [Bool] - -just1 :: _ Int -just1 = Just 1 --- Inferred: Maybe Int - -filterInt :: _ -> _ -> [Int] -filterInt = filter -- has type forall a. (a -> Bool) -> [a] -> [a] --- Inferred: (Int -> Bool) -> [Int] -> [Int] -</programlisting> - -<para> -For instance, the first wildcard in the type signature <literal>not'</literal> -would produce the following error message: -</para> -<programlisting> -Test.hs:4:17: - Found hole ‘_’ with type: Bool - To use the inferred type, enable PartialTypeSignatures - In the type signature for ‘not'’: Bool -> _ -</programlisting> - -<para> -When a wildcard is not instantiated to a monotype, it will be generalised -over, i.e. replaced by a fresh type variable (of which the name will often -start with <literal>w_</literal>), e.g. -</para> -<programlisting> -foo :: _ -> _ -foo x = x --- Inferred: forall w_. w_ -> w_ - -filter' :: _ -filter' = filter -- has type forall a. (a -> Bool) -> [a] -> [a] --- Inferred: (a -> Bool) -> [a] -> [a] -</programlisting> -</sect3> - -<sect3 id="named-wildcards"> -<title>Named Wildcards</title> -<para> -Type wildcards can also be named by giving the underscore an identifier as -suffix, i.e. <literal>_a</literal>. These are called <emphasis>named -wildcards</emphasis>. All occurrences of the same named wildcard within one -type signature will unify to the same type. For example: -</para> -<programlisting> -f :: _x -> _x -f ('c', y) = ('d', error "Urk") --- Inferred: forall t. (Char, t) -> (Char, t) -</programlisting> - -<para> -The named wildcard forces the argument and result types to be the same. -Lacking a signature, GHC would have inferred <literal>forall a b. (Char, a) -> -(Char, b)</literal>. A named wildcard can be mentioned in constraints, -provided it also occurs in the monotype part of the type signature to make -sure that it unifies with something: -</para> - -<programlisting> -somethingShowable :: Show _x => _x -> _ -somethingShowable x = show x --- Inferred type: Show w_x => w_x -> String - -somethingShowable' :: Show _x => _x -> _ -somethingShowable' x = show (not x) --- Inferred type: Bool -> String -</programlisting> - -<para> -Besides an extra-constraints wildcard (see <xref -linkend="extra-constraints-wildcard"/>), only named wildcards can occur in the -constraints, e.g. the <literal>_x</literal> in <literal>Show _x</literal>. -</para> - -<para> -Named wildcards <emphasis>should not be confused with type -variables</emphasis>. Even though syntactically similar, named wildcards can -unify with monotypes as well as be generalised over (and behave as type -variables).</para> - -<para> -In the first example above, <literal>_x</literal> is generalised over (and is -effectively replaced by a fresh type variable <literal>w_x</literal>). In the -second example, <literal>_x</literal> is unified with the -<literal>Bool</literal> type, and as <literal>Bool</literal> implements the -<literal>Show</literal> type class, the constraint <literal>Show -Bool</literal> can be simplified away. -</para> - -<para> -By default, GHC (as the Haskell 2010 standard prescribes) parses identifiers -starting with an underscore in a type as type variables. To treat them as -named wildcards, the <option>-XNamedWildCards</option> flag should be enabled. -The example below demonstrated the effect. -</para> - -<programlisting> -foo :: _a -> _a -foo _ = False -</programlisting> - -<para> -Compiling this program without enabling <option>-XNamedWildCards</option> -produces the following error message complaining about the type variable -<literal>_a</literal> no matching the actual type <literal>Bool</literal>. -</para> - -<programlisting> -Test.hs:5:9: - Couldn't match expected type ‘_a’ with actual type ‘Bool’ - ‘_a’ is a rigid type variable bound by - the type signature for foo :: _a -> _a at Test.hs:4:8 - Relevant bindings include foo :: _a -> _a (bound at Test.hs:4:1) - In the expression: False - In an equation for ‘foo’: foo _ = False -</programlisting> - -<para> -Compiling this program with <option>-XNamedWildCards</option> enabled produces -the following error message reporting the inferred type of the named wildcard -<literal>_a</literal>. -</para> - -<programlisting> -Test.hs:4:8: Warning: - Found hole ‘_a’ with type: Bool - In the type signature for ‘foo’: _a -> _a -</programlisting> -</sect3> - -<sect3 id="extra-constraints-wildcard"> -<title>Extra-Constraints Wildcard</title> - -<para> -The third kind of wildcard is the <emphasis>extra-constraints -wildcard</emphasis>. The presence of an extra-constraints wildcard indicates -that an arbitrary number of extra constraints may be inferred during type -checking and will be added to the type signature. In the example below, the -extra-constraints wildcard is used to infer three extra constraints. -</para> - -<programlisting> -arbitCs :: _ => a -> String -arbitCs x = show (succ x) ++ show (x == x) --- Inferred: --- forall a. (Enum a, Eq a, Show a) => a -> String --- Error: -Test.hs:5:12: - Found hole ‘_’ with inferred constraints: (Enum a, Eq a, Show a) - To use the inferred type, enable PartialTypeSignatures - In the type signature for ‘arbitCs’: _ => a -> String -</programlisting> - -<para> -An extra-constraints wildcard shouldn't prevent the programmer from already -listing the constraints he knows or wants to annotate, e.g. -</para> - -<programlisting> --- Also a correct partial type signature: -arbitCs' :: (Enum a, _) => a -> String -arbitCs' x = arbitCs x --- Inferred: --- forall a. (Enum a, Show a, Eq a) => a -> String --- Error: -Test.hs:9:22: - Found hole ‘_’ with inferred constraints: (Eq a, Show a) - To use the inferred type, enable PartialTypeSignatures - In the type signature for ‘arbitCs'’: (Enum a, _) => a -> String -</programlisting> - -<para> -An extra-constraints wildcard can also lead to zero extra constraints to be -inferred, e.g. -</para> - -<programlisting> -noCs :: _ => String -noCs = "noCs" --- Inferred: String --- Error: -Test.hs:13:9: - Found hole ‘_’ with inferred constraints: () - To use the inferred type, enable PartialTypeSignatures - In the type signature for ‘noCs’: _ => String -</programlisting> - -<para> -As a single extra-constraints wildcard is enough to infer any number of -constraints, only one is allowed in a type signature and it should come last -in the list of constraints. -</para> - -<para> -Extra-constraints wildcards cannot be named. -</para> - -</sect3> -</sect2> - -<sect2 id="pts-where"> -<title>Where can they occur?</title> - -<para> -Partial type signatures are allowed for bindings, pattern and expression signatures. -In all other contexts, e.g. type class or type family declarations, they are disallowed. -In the following example a wildcard is used in each of the three possible contexts. -Extra-constraints wildcards are not supported in pattern or expression signatures. -</para> -<programlisting> -{-# LANGUAGE ScopedTypeVariables #-} -foo :: _ -foo (x :: _) = (x :: _) --- Inferred: forall w_. w_ -> w_ -</programlisting> - -<para> - Anonymous wildcards <emphasis>can</emphasis> occur in type or data instance - declarations. However, these declarations are not partial type signatures - and different rules apply. See <xref linkend="data-instance-declarations"/> - for more details. -</para> - -<para> -Partial type signatures can also be used in <xref linkend="template-haskell"/> splices. -</para> - -<itemizedlist> - <listitem>Declaration splices: partial type signature are fully supported. -<programlisting> -{-# LANGUAGE TemplateHaskell, NamedWildCards #-} -$( [d| foo :: _ => _a -> _a -> _ - foo x y = x == y|] ) -</programlisting> - </listitem> - <listitem>Expression splices: anonymous and named wildcards can be used in expression signatures. - Extra-constraints wildcards are not supported, just like in regular expression signatures. -<programlisting> -{-# LANGUAGE TemplateHaskell, NamedWildCards #-} -$( [e| foo = (Just True :: _m _) |] ) -</programlisting> - </listitem> - <listitem>Typed expression splices: the same wildcards as in (untyped) expression splices are supported. - </listitem> - <listitem>Pattern splices: Template Haskell doesn't support type signatures in pattern splices. - Consequently, partial type signatures are not supported either. - </listitem> - <listitem>Type splices: only anonymous wildcards are supported in type splices. - Named and extra-constraints wildcards are not. -<programlisting> -{-# LANGUAGE TemplateHaskell #-} -foo :: $( [t| _ |] ) -> a -foo x = x -</programlisting> - </listitem> -</itemizedlist> - - -</sect2> -</sect1> -<!-- ==================== Deferring type errors ================= --> - -<sect1 id="defer-type-errors"> -<title>Deferring type errors to runtime</title> - <para> - While developing, sometimes it is desirable to allow compilation to succeed - even if there are type errors in the code. Consider the following case: -<programlisting> -module Main where - -a :: Int -a = 'a' - -main = print "b" -</programlisting> - Even though <literal>a</literal> is ill-typed, it is not used in the end, so if - all that we're interested in is <literal>main</literal> it can be useful to be - able to ignore the problems in <literal>a</literal>. - </para> - <para> - For more motivation and details please refer to the <ulink - url="http://ghc.haskell.org/trac/ghc/wiki/DeferErrorsToRuntime">HaskellWiki</ulink> - page or the <ulink - url="http://research.microsoft.com/en-us/um/people/simonpj/papers/ext-f/">original - paper</ulink>. - </para> - -<sect2><title>Enabling deferring of type errors</title> - <para> - The flag <literal>-fdefer-type-errors</literal> controls whether type - errors are deferred to runtime. Type errors will still be emitted as - warnings, but will not prevent compilation. You can use - <literal>-fno-warn-deferred-type-errors</literal> to suppress these warnings. - </para> - <para> - This flag implies the <literal>-fdefer-typed-holes</literal> flag, - which enables this behaviour for <link linkend="typed-holes">typed holes - </link>. Should you so wish, it is possible to enable - <literal>-fdefer-type-errors</literal> without enabling - <literal>-fdefer-typed-holes</literal>, by explicitly specifying - <literal>-fno-defer-typed-holes</literal> on the command-line after the - <literal>-fdefer-type-errors</literal> flag. - </para> - <para> - At runtime, whenever a term containing a type error would need to be - evaluated, the error is converted into a runtime exception of type - <literal>TypeError</literal>. Note that type errors are deferred as much - as possible during runtime, but invalid coercions are never performed, - even when they would ultimately result in a value of the correct type. - For example, given the following code: -<programlisting> -x :: Int -x = 0 - -y :: Char -y = x - -z :: Int -z = y -</programlisting> - evaluating <literal>z</literal> will result in a runtime <literal>TypeError</literal>. - </para> -</sect2> -<sect2><title>Deferred type errors in GHCi</title> - <para> - The flag <literal>-fdefer-type-errors</literal> works in GHCi as well, with - one exception: for "naked" expressions typed at the prompt, type - errors don't get delayed, so for example: -<programlisting> -Prelude> fst (True, 1 == 'a') - -<interactive>:2:12: - No instance for (Num Char) arising from the literal `1' - Possible fix: add an instance declaration for (Num Char) - In the first argument of `(==)', namely `1' - In the expression: 1 == 'a' - In the first argument of `fst', namely `(True, 1 == 'a')' -</programlisting> -Otherwise, in the common case of a simple type error such as -typing <literal>reverse True</literal> at the prompt, you would get a warning and then -an immediately-following type error when the expression is evaluated. - </para> - <para> - This exception doesn't apply to statements, as the following example demonstrates: -<programlisting> -Prelude> let x = (True, 1 == 'a') - -<interactive>:3:16: Warning: - No instance for (Num Char) arising from the literal `1' - Possible fix: add an instance declaration for (Num Char) - In the first argument of `(==)', namely `1' - In the expression: 1 == 'a' - In the expression: (True, 1 == 'a') -Prelude> fst x -True -</programlisting> - </para> -</sect2> -</sect1> - -<!-- ====================== TEMPLATE HASKELL ======================= --> - -<sect1 id="template-haskell"> -<title>Template Haskell</title> - -<para>Template Haskell allows you to do compile-time meta-programming in -Haskell. -The background to -the main technical innovations is discussed in "<ulink -url="http://research.microsoft.com/~simonpj/papers/meta-haskell/"> -Template Meta-programming for Haskell</ulink>" (Proc Haskell Workshop 2002). -</para> -<para> -There is a Wiki page about -Template Haskell at <ulink url="http://www.haskell.org/haskellwiki/Template_Haskell"> -http://www.haskell.org/haskellwiki/Template_Haskell</ulink>, and that is the best place to look for -further details. -You may also -consult the <ulink -url="http://www.haskell.org/ghc/docs/latest/html/libraries/index.html">online -Haskell library reference material</ulink> -(look for module <literal>Language.Haskell.TH</literal>). -Many changes to the original design are described in - <ulink url="http://research.microsoft.com/~simonpj/papers/meta-haskell/notes2.ps"> -Notes on Template Haskell version 2</ulink>. -Not all of these changes are in GHC, however. -</para> - -<para> The first example from that paper is set out below (<xref linkend="th-example"/>) -as a worked example to help get you started. -</para> - -<para> -The documentation here describes the realisation of Template Haskell in GHC. It is not detailed enough to -understand Template Haskell; see the <ulink url="http://haskell.org/haskellwiki/Template_Haskell"> -Wiki page</ulink>. -</para> - - <sect2 id="th-syntax"> - <title>Syntax</title> - - <para> Template Haskell has the following new syntactic - constructions. You need to use the flag - <option>-XTemplateHaskell</option> - <indexterm><primary><option>-XTemplateHaskell</option></primary> - </indexterm>to switch these syntactic extensions on.</para> - - <itemizedlist> - <listitem><para> - A splice is written <literal>$x</literal>, where <literal>x</literal> is an - identifier, or <literal>$(...)</literal>, where the "..." is an arbitrary expression. - There must be no space between the "$" and the identifier or parenthesis. This use - of "$" overrides its meaning as an infix operator, just as "M.x" overrides the meaning - of "." as an infix operator. If you want the infix operator, put spaces around it. - </para> - <para> A splice can occur in place of - <itemizedlist> - <listitem><para> an expression; the spliced expression must - have type <literal>Q Exp</literal></para></listitem> - <listitem><para> a pattern; the spliced pattern must - have type <literal>Q Pat</literal></para></listitem> - <listitem><para> a type; the spliced expression must - have type <literal>Q Type</literal></para></listitem> - <listitem><para> a list of declarations at top level; the spliced expression - must have type <literal>Q [Dec]</literal></para></listitem> - </itemizedlist> - Inside a splice you can only call functions defined in imported modules, - not functions defined elsewhere in the same module. Note that - declaration splices are not allowed anywhere except at top level - (outside any other declarations).</para></listitem> - - <listitem><para> - A expression quotation is written in Oxford brackets, thus: - <itemizedlist> - <listitem><para> <literal>[| ... |]</literal>, or <literal>[e| ... |]</literal>, - where the "..." is an expression; - the quotation has type <literal>Q Exp</literal>.</para></listitem> - <listitem><para> <literal>[d| ... |]</literal>, where the "..." is a list of top-level declarations; - the quotation has type <literal>Q [Dec]</literal>.</para></listitem> - <listitem><para> <literal>[t| ... |]</literal>, where the "..." is a type; - the quotation has type <literal>Q Type</literal>.</para></listitem> - <listitem><para> <literal>[p| ... |]</literal>, where the "..." is a pattern; - the quotation has type <literal>Q Pat</literal>.</para></listitem> - </itemizedlist> - See <xref linkend="pts-where"/> for using partial type signatures in quotations.</para></listitem> - - <listitem> - <para> - A <emphasis>typed</emphasis> expression splice is written - <literal>$$x</literal>, where <literal>x</literal> is an - identifier, or <literal>$$(...)</literal>, where the "..." is - an arbitrary expression. - </para> - <para> - A typed expression splice can occur in place of an - expression; the spliced expression must have type <literal>Q - (TExp a)</literal> - </para> - </listitem> - - <listitem> - <para> - A <emphasis>typed</emphasis> expression quotation is written - as <literal>[|| ... ||]</literal>, or <literal>[e|| - ... ||]</literal>, where the "..." is an expression; if the - "..." expression has type <literal>a</literal>, then the - quotation has type <literal>Q (TExp a)</literal>. - </para> - - <para> - Values of type <literal>TExp a</literal> may be converted to - values of type <literal>Exp</literal> using the function - <literal>unType :: TExp a -> Exp</literal>. - </para> - </listitem> - - <listitem><para> - A quasi-quotation can appear in a pattern, type, expression, or - declaration context and is also written in Oxford brackets: - <itemizedlist> - <listitem><para> <literal>[<replaceable>varid</replaceable>| ... |]</literal>, - where the "..." is an arbitrary string; a full description of the - quasi-quotation facility is given in <xref linkend="th-quasiquotation"/>.</para></listitem> - </itemizedlist></para></listitem> - - <listitem><para> - A name can be quoted with either one or two prefix single quotes: - <itemizedlist> - <listitem><para> <literal>'f</literal> has type <literal>Name</literal>, and names the function <literal>f</literal>. - Similarly <literal>'C</literal> has type <literal>Name</literal> and names the data constructor <literal>C</literal>. - In general <literal>'</literal><replaceable>thing</replaceable> - interprets <replaceable>thing</replaceable> in an expression context.</para> - <para>A name whose second character is a single - quote (sadly) cannot be quoted in this way, - because it will be parsed instead as a quoted - character. For example, if the function is called - <literal>f'7</literal> (which is a legal Haskell - identifier), an attempt to quote it as - <literal>'f'7</literal> would be parsed as the - character literal <literal>'f'</literal> followed - by the numeric literal <literal>7</literal>. There - is no current escape mechanism in this (unusual) - situation. - </para></listitem> - <listitem><para> <literal>''T</literal> has type <literal>Name</literal>, and names the type constructor <literal>T</literal>. - That is, <literal>''</literal><replaceable>thing</replaceable> interprets <replaceable>thing</replaceable> in a type context. - </para></listitem> - </itemizedlist> - These <literal>Names</literal> can be used to construct Template Haskell expressions, patterns, declarations etc. They - may also be given as an argument to the <literal>reify</literal> function. - </para> - </listitem> - - <listitem> - <para> - It is possible for a splice to expand to an expression that contain - names which are not in scope at the site of the splice. As an - example, consider the following code: - -<programlisting> -module Bar where - -import Language.Haskell.TH - -add1 :: Int -> Q Exp -add1 x = [| x + 1 |] -</programlisting> - - Now consider a splice using <literal>add1</literal> in a separate - module: - -<programlisting> -module Foo where - -import Bar - -two :: Int -two = $(add1 1) -</programlisting> - - Template Haskell cannot know what the argument to - <literal>add1</literal> will be at the function's definition site, so - a lifting mechanism is used to promote <literal>x</literal> into a - value of type <literal>Q Exp</literal>. This functionality is exposed - to the user as the <literal>Lift</literal> typeclass in the - <literal>Language.Haskell.TH.Syntax</literal> module. If a type has a - <literal>Lift</literal> instance, then any of its values can be - lifted to a Template Haskell expression: - -<programlisting> -class Lift t where - lift :: t -> Q Exp -</programlisting> - - In general, if GHC sees an expression within Oxford brackets (e.g., - <literal>[| foo bar |]</literal>, then GHC looks up each name within - the brackets. If a name is global (e.g., suppose - <literal>foo</literal> comes from an import or a top-level - declaration), then the fully qualified name is used directly in the - quotation. If the name is local (e.g., suppose <literal>bar</literal> - is bound locally in the function definition - <literal>mkFoo bar = [| foo bar |]</literal>), then GHC uses - <literal>lift</literal> on it (so GHC pretends - <literal>[| foo bar |]</literal> actually contains - <literal>[| foo $(lift bar) |]</literal>). Local names, which are not - in scope at splice locations, are actually evaluated when the - quotation is processed. - - The <literal>template-haskell</literal> library provides - <literal>Lift</literal> instances for many common data types. - Furthermore, it is possible to derive <literal>Lift</literal> - instances automatically by using the <option>-XDeriveLift</option> - language extension. See <xref linkend="deriving-lift" /> for more - information. - </para> - </listitem> - - <listitem><para> You may omit the <literal>$(...)</literal> in a top-level declaration splice. - Simply writing an expression (rather than a declaration) implies a splice. For example, you can write -<programlisting> -module Foo where -import Bar - -f x = x - -$(deriveStuff 'f) -- Uses the $(...) notation - -g y = y+1 - -deriveStuff 'g -- Omits the $(...) - -h z = z-1 -</programlisting> - This abbreviation makes top-level declaration slices quieter and less intimidating. - </para></listitem> - - <listitem> - <para> - Outermost pattern splices may bind variables. By "outermost" here, we refer to - a pattern splice that occurs outside of any quotation brackets. For example, - -<programlisting> -mkPat :: Bool -> Q Pat -mkPat True = [p| (x, y) |] -mkPat False = [p| (y, x) |] - --- in another module: -foo :: (Char, String) -> String -foo $(mkPat True) = x : y - -bar :: (String, Char) -> String -bar $(mkPat False) = x : y -</programlisting> - </para> - </listitem> - - - <listitem> - <para> - Nested pattern splices do <emphasis>not</emphasis> bind variables. - By "nested" here, we refer to a pattern splice occurring within a - quotation bracket. Continuing the example from the last bullet: - -<programlisting> -baz :: Bool -> Q Exp -baz b = [| quux $(mkPat b) = x + y |] -</programlisting> - - would fail with <literal>x</literal> and <literal>y</literal> - being out of scope. - </para> - - <para> - The difference in treatment of outermost and nested pattern splices is - because outermost splices are run at compile time. GHC can then use - the result of running the splice when analysing the expressions within - the pattern's scope. Nested splices, on the other hand, are <emphasis>not</emphasis> - run at compile time; they are run when the bracket is spliced in, sometime later. - Since nested pattern splices may refer to local variables, there is no way for GHC - to know, at splice compile time, what variables are bound, so it binds none. - </para> - </listitem> - - <listitem> - <para> - A pattern quasiquoter <emphasis>may</emphasis> - generate binders that scope over the right-hand side of a - definition because these binders are in scope lexically. For - example, given a quasiquoter <literal>haskell</literal> that - parses Haskell, in the following code, the <literal>y</literal> - in the right-hand side of <literal>f</literal> refers to the - <literal>y</literal> bound by the <literal>haskell</literal> - pattern quasiquoter, <emphasis>not</emphasis> the top-level - <literal>y = 7</literal>. -<programlisting> -y :: Int -y = 7 - -f :: Int -> Int -> Int -f n = \ [haskell|y|] -> y+n -</programlisting> - </para> - </listitem> - <listitem> - <para> - Top-level declaration splices break up a source file into - <emphasis>declaration groups</emphasis>. A - <emphasis>declaration group</emphasis> is the group of - declarations created by a top-level declaration splice, plus - those following it, down to but not including the next - top-level declaration splice. The first declaration group in a - module includes all top-level definitions down to but not - including the first top-level declaration splice. - </para> - - <para> - Each declaration group is mutually recursive only within - the group. Declaration groups can refer to definitions within - previous groups, but not later ones. - </para> - - <para> - Accordingly, the type environment seen by - <literal>reify</literal> includes all the top-level - declarations up to the end of the immediately preceding - declaration group, but no more. - </para> - - <para> - Unlike normal declaration splices, declaration quasiquoters - do not cause a break. These quasiquoters are expanded before - the rest of the declaration group is processed, and the - declarations they generate are merged into the surrounding - declaration group. Consequently, the type environment seen - by <literal>reify</literal> from a declaration quasiquoter - will not include anything from the quasiquoter's declaration - group. - </para> - - <para> - Concretely, consider the following code -<programlisting> -module M where - import ... - f x = x - $(th1 4) - h y = k y y $(blah1) - [qq|blah|] - k x y = x + y - $(th2 10) - w z = $(blah2) -</programlisting> - - In this example - <orderedlist> - <listitem> - <para> - The body of <literal>h</literal> would be unable to refer - to the function <literal>w</literal>. - </para> - - <para> - A <literal>reify</literal> inside the splice <literal>$(th1 - ..)</literal> would see the definition of - <literal>f</literal>. - </para> - </listitem> - <listitem> - <para> - A <literal>reify</literal> inside the splice - <literal>$(blah1)</literal> would see the definition of - <literal>f</literal>, but would not see the definition of - <literal>h</literal>. - </para> - </listitem> - <listitem> - <para> - A <literal>reify</literal> inside the splice - <literal>$(th2..)</literal> would see the definition of - <literal>f</literal>, all the bindings created by - <literal>$(th1..)</literal>, and the definition of - <literal>h</literal>. - </para> - </listitem> - <listitem> - <para> - A <literal>reify</literal> inside the splice - <literal>$(blah2)</literal> would see the same definitions - as the splice <literal>$(th2...)</literal>. - </para> - </listitem> - <listitem> - <para> - The body of <literal>h</literal> <emphasis>is</emphasis> - able to refer to the function <literal>k</literal> - appearing on the other side of the declaration - quasiquoter, as quasiquoters never cause a declaration - group to be broken up. - </para> - <para> - A <literal>reify</literal> inside the - <literal>qq</literal> quasiquoter would be able to see - the definition of <literal>f</literal> from the - preceding declaration group, but not the definitions of - <literal>h</literal> or <literal>k</literal>, or any - definitions from subsequent declaration groups. - </para> - </listitem> - </orderedlist> - </para> - </listitem> - <listitem> - <para> - Expression quotations accept most Haskell language constructs. - However, there are some GHC-specific extensions which expression - quotations currently do not support, including - <itemizedlist> - <listitem> - <para> - Recursive <literal>do</literal>-statements (see - <ulink url="https://ghc.haskell.org/trac/ghc/ticket/1262"> - Trac #1262</ulink>) - </para> - </listitem> - <listitem> - <para> - Pattern synonyms (see - <ulink url="https://ghc.haskell.org/trac/ghc/ticket/8761"> - Trac #8761</ulink>) - </para> - </listitem> - <listitem> - <para> - Typed holes (see - <ulink url="https://ghc.haskell.org/trac/ghc/ticket/10267"> - Trac #10267</ulink>) - </para> - </listitem> - </itemizedlist> - </para> - </listitem> - - </itemizedlist> -(Compared to the original paper, there are many differences of detail. -The syntax for a declaration splice uses "<literal>$</literal>" not "<literal>splice</literal>". -The type of the enclosed expression must be <literal>Q [Dec]</literal>, not <literal>[Q Dec]</literal>. -Typed expression splices and quotations are supported.) - -</sect2> - -<sect2> <title> Using Template Haskell </title> -<para> -<itemizedlist> - <listitem><para> - The data types and monadic constructor functions for Template Haskell are in the library - <literal>Language.Haskell.THSyntax</literal>. - </para></listitem> - - <listitem><para> - You can only run a function at compile time if it is imported from another module. That is, - you can't define a function in a module, and call it from within a splice in the same module. - (It would make sense to do so, but it's hard to implement.) - </para></listitem> - - <listitem><para> - You can only run a function at compile time if it is imported - from another module <emphasis>that is not part of a mutually-recursive group of modules - that includes the module currently being compiled</emphasis>. Furthermore, all of the modules of - the mutually-recursive group must be reachable by non-SOURCE imports from the module where the - splice is to be run.</para> - <para> - For example, when compiling module A, - you can only run Template Haskell functions imported from B if B does not import A (directly or indirectly). - The reason should be clear: to run B we must compile and run A, but we are currently type-checking A. - </para></listitem> - - <listitem><para> - If you are building GHC from source, you need at least a stage-2 bootstrap compiler to - run Template Haskell splices and quasi-quotes. A stage-1 compiler will only accept regular quotes of Haskell. Reason: TH splices and quasi-quotes - compile and run a program, and then looks at the result. So it's important that - the program it compiles produces results whose representations are identical to - those of the compiler itself. - </para></listitem> -</itemizedlist> -</para> -<para> Template Haskell works in any mode (<literal>--make</literal>, <literal>--interactive</literal>, - or file-at-a-time). There used to be a restriction to the former two, but that restriction - has been lifted. -</para> -</sect2> - -<sect2 id="th-view-gen-code"> <title> Viewing Template Haskell generated code </title> - <para> - The flag <literal>-ddump-splices</literal> shows the expansion of all top-level declaration splices, both typed and untyped, as they happen. - As with all dump flags, the default is for this output to be sent to stdout. - For a non-trivial program, you may be interested in combining this with the <literal>-ddump-to-file flag</literal> (see <xref linkend="dumping-output"/>. - For each file using Template Haskell, this will show the output in a <literal>.dump-splices</literal> file. - </para> - - <para> - The flag <literal>-dth-dec-file</literal> shows the expansions of all top-level TH declaration splices, both typed and untyped, in the file <literal>M.th.hs</literal> where M is the name of the module being compiled. - Note that other types of splices (expressions, types, and patterns) are not shown. - Application developers can check this into their repository so that they can grep for identifiers that were defined in Template Haskell. - This is similar to using <option>-ddump-to-file</option> with <option>-ddump-splices</option> but it always generates a file instead of being coupled to <option>-ddump-to-file</option>. The format is also different: it does not show code from the original file, instead it only shows generated code and has a comment for the splice location of the original file. - </para> - - <para> - Below is a sample output of <literal>-ddump-splices</literal> - </para> - -<programlisting> -TH_pragma.hs:(6,4)-(8,26): Splicing declarations - [d| foo :: Int -> Int - foo x = x + 1 |] -======> - foo :: Int -> Int - foo x = (x + 1) -</programlisting> - - <para> - Below is the output of the same sample using <literal>-dth-dec-file</literal> - </para> - -<programlisting> --- TH_pragma.hs:(6,4)-(8,26): Splicing declarations -foo :: Int -> Int -foo x = (x + 1) -</programlisting> -</sect2> - -<sect2 id="th-example"> <title> A Template Haskell Worked Example </title> -<para>To help you get over the confidence barrier, try out this skeletal worked example. - First cut and paste the two modules below into "Main.hs" and "Printf.hs":</para> - -<programlisting> - -{- Main.hs -} -module Main where - --- Import our template "pr" -import Printf ( pr ) - --- The splice operator $ takes the Haskell source code --- generated at compile time by "pr" and splices it into --- the argument of "putStrLn". -main = putStrLn ( $(pr "Hello") ) - - -{- Printf.hs -} -module Printf where - --- Skeletal printf from the paper. --- It needs to be in a separate module to the one where --- you intend to use it. - --- Import some Template Haskell syntax -import Language.Haskell.TH - --- Describe a format string -data Format = D | S | L String - --- Parse a format string. This is left largely to you --- as we are here interested in building our first ever --- Template Haskell program and not in building printf. -parse :: String -> [Format] -parse s = [ L s ] - --- Generate Haskell source code from a parsed representation --- of the format string. This code will be spliced into --- the module which calls "pr", at compile time. -gen :: [Format] -> Q Exp -gen [D] = [| \n -> show n |] -gen [S] = [| \s -> s |] -gen [L s] = stringE s - --- Here we generate the Haskell code for the splice --- from an input format string. -pr :: String -> Q Exp -pr s = gen (parse s) -</programlisting> - -<para>Now run the compiler (here we are a Cygwin prompt on Windows): -</para> -<programlisting> -$ ghc --make -XTemplateHaskell main.hs -o main.exe -</programlisting> - -<para>Run "main.exe" and here is your output:</para> - -<programlisting> -$ ./main -Hello -</programlisting> - -</sect2> - -<sect2> -<title>Using Template Haskell with Profiling</title> -<indexterm><primary>profiling</primary><secondary>with Template Haskell</secondary></indexterm> - -<para>Template Haskell relies on GHC's built-in bytecode compiler and -interpreter to run the splice expressions. The bytecode interpreter -runs the compiled expression on top of the same runtime on which GHC -itself is running; this means that the compiled code referred to by -the interpreted expression must be compatible with this runtime, and -in particular this means that object code that is compiled for -profiling <emphasis>cannot</emphasis> be loaded and used by a splice -expression, because profiled object code is only compatible with the -profiling version of the runtime.</para> - -<para>This causes difficulties if you have a multi-module program -containing Template Haskell code and you need to compile it for -profiling, because GHC cannot load the profiled object code and use it -when executing the splices. Fortunately GHC provides a workaround. -The basic idea is to compile the program twice:</para> - -<orderedlist> -<listitem> - <para>Compile the program or library first the normal way, without - <option>-prof</option><indexterm><primary><option>-prof</option></primary></indexterm>.</para> -</listitem> -<listitem> - <para>Then compile it again with <option>-prof</option>, and - additionally use <option>-osuf - p_o</option><indexterm><primary><option>-osuf</option></primary></indexterm> - to name the object files differently (you can choose any suffix - that isn't the normal object suffix here). GHC will automatically - load the object files built in the first step when executing splice - expressions. If you omit the <option>-osuf</option> flag when - building with <option>-prof</option> and Template Haskell is used, - GHC will emit an error message. </para> -</listitem> -</orderedlist> -</sect2> - -<sect2 id="th-quasiquotation"> <title> Template Haskell Quasi-quotation </title> -<para>Quasi-quotation allows patterns and expressions to be written using -programmer-defined concrete syntax; the motivation behind the extension and -several examples are documented in -"<ulink url="http://www.cs.tufts.edu/comp/150FP/archive/geoff-mainland/quasiquoting.pdf">Why It's -Nice to be Quoted: Quasiquoting for Haskell</ulink>" (Proc Haskell Workshop -2007). The example below shows how to write a quasiquoter for a simple -expression language.</para> -<para> -Here are the salient features -<itemizedlist> -<listitem><para> -A quasi-quote has the form -<literal>[<replaceable>quoter</replaceable>| <replaceable>string</replaceable> |]</literal>. -<itemizedlist> -<listitem><para> -The <replaceable>quoter</replaceable> must be the name of an imported quoter, -either qualified or unqualified; it cannot be an arbitrary expression. -</para></listitem> -<listitem><para> -The <replaceable>quoter</replaceable> cannot be "<literal>e</literal>", -"<literal>t</literal>", "<literal>d</literal>", or "<literal>p</literal>", since -those overlap with Template Haskell quotations. -</para></listitem> -<listitem><para> -There must be no spaces in the token -<literal>[<replaceable>quoter</replaceable>|</literal>. -</para></listitem> -<listitem><para> -The quoted <replaceable>string</replaceable> -can be arbitrary, and may contain newlines. -</para></listitem> -<listitem><para> -The quoted <replaceable>string</replaceable> -finishes at the first occurrence of the two-character sequence <literal>"|]"</literal>. -Absolutely no escaping is performed. If you want to embed that character -sequence in the string, you must invent your own escape convention (such -as, say, using the string <literal>"|~]"</literal> instead), and make your -quoter function interpret <literal>"|~]"</literal> as <literal>"|]"</literal>. -One way to implement this is to compose your quoter with a pre-processing pass to -perform your escape conversion. See the -<ulink url="http://ghc.haskell.org/trac/ghc/ticket/5348"> -discussion in Trac</ulink> for details. -</para></listitem> -</itemizedlist> -</para></listitem> - -<listitem><para> -A quasiquote may appear in place of -<itemizedlist> -<listitem><para>An expression</para></listitem> -<listitem><para>A pattern</para></listitem> -<listitem><para>A type</para></listitem> -<listitem><para>A top-level declaration</para></listitem> -</itemizedlist> -(Only the first two are described in the paper.) -</para></listitem> - -<listitem><para> -A quoter is a value of type <literal>Language.Haskell.TH.Quote.QuasiQuoter</literal>, -which is defined thus: -<programlisting> -data QuasiQuoter = QuasiQuoter { quoteExp :: String -> Q Exp, - quotePat :: String -> Q Pat, - quoteType :: String -> Q Type, - quoteDec :: String -> Q [Dec] } -</programlisting> -That is, a quoter is a tuple of four parsers, one for each of the contexts -in which a quasi-quote can occur. -</para></listitem> -<listitem><para> -A quasi-quote is expanded by applying the appropriate parser to the string -enclosed by the Oxford brackets. The context of the quasi-quote (expression, pattern, -type, declaration) determines which of the parsers is called. -</para></listitem> -<listitem><para> -Unlike normal declaration splices of the form <literal>$(...)</literal>, -declaration quasi-quotes do not cause a declaration group break. See -<xref linkend="th-syntax"/> for more information. -</para></listitem> -</itemizedlist> -</para> -<para> -The example below shows quasi-quotation in action. The quoter <literal>expr</literal> -is bound to a value of type <literal>QuasiQuoter</literal> defined in module <literal>Expr</literal>. -The example makes use of an antiquoted -variable <literal>n</literal>, indicated by the syntax <literal>'int:n</literal> -(this syntax for anti-quotation was defined by the parser's -author, <emphasis>not</emphasis> by GHC). This binds <literal>n</literal> to the -integer value argument of the constructor <literal>IntExpr</literal> when -pattern matching. Please see the referenced paper for further details regarding -anti-quotation as well as the description of a technique that uses SYB to -leverage a single parser of type <literal>String -> a</literal> to generate both -an expression parser that returns a value of type <literal>Q Exp</literal> and a -pattern parser that returns a value of type <literal>Q Pat</literal>. -</para> - -<para> -Quasiquoters must obey the same stage restrictions as Template Haskell, e.g., in -the example, <literal>expr</literal> cannot be defined -in <literal>Main.hs</literal> where it is used, but must be imported. -</para> - -<programlisting> -{- ------------- file Main.hs --------------- -} -module Main where - -import Expr - -main :: IO () -main = do { print $ eval [expr|1 + 2|] - ; case IntExpr 1 of - { [expr|'int:n|] -> print n - ; _ -> return () - } - } - - -{- ------------- file Expr.hs --------------- -} -module Expr where - -import qualified Language.Haskell.TH as TH -import Language.Haskell.TH.Quote - -data Expr = IntExpr Integer - | AntiIntExpr String - | BinopExpr BinOp Expr Expr - | AntiExpr String - deriving(Show, Typeable, Data) - -data BinOp = AddOp - | SubOp - | MulOp - | DivOp - deriving(Show, Typeable, Data) - -eval :: Expr -> Integer -eval (IntExpr n) = n -eval (BinopExpr op x y) = (opToFun op) (eval x) (eval y) - where - opToFun AddOp = (+) - opToFun SubOp = (-) - opToFun MulOp = (*) - opToFun DivOp = div - -expr = QuasiQuoter { quoteExp = parseExprExp, quotePat = parseExprPat } - --- Parse an Expr, returning its representation as --- either a Q Exp or a Q Pat. See the referenced paper --- for how to use SYB to do this by writing a single --- parser of type String -> Expr instead of two --- separate parsers. - -parseExprExp :: String -> Q Exp -parseExprExp ... - -parseExprPat :: String -> Q Pat -parseExprPat ... -</programlisting> - -<para>Now run the compiler: -<programlisting> -$ ghc --make -XQuasiQuotes Main.hs -o main -</programlisting> -</para> - -<para>Run "main" and here is your output: -<programlisting> -$ ./main -3 -1 -</programlisting> -</para> -</sect2> - -</sect1> - -<!-- ===================== Arrow notation =================== --> - -<sect1 id="arrow-notation"> -<title>Arrow notation -</title> - -<para>Arrows are a generalisation of monads introduced by John Hughes. -For more details, see -<itemizedlist> - -<listitem> -<para> -“Generalising Monads to Arrows”, -John Hughes, in <citetitle>Science of Computer Programming</citetitle> 37, -pp67–111, May 2000. -The paper that introduced arrows: a friendly introduction, motivated with -programming examples. -</para> -</listitem> - -<listitem> -<para> -“<ulink url="http://www.soi.city.ac.uk/~ross/papers/notation.html">A New Notation for Arrows</ulink>”, -Ross Paterson, in <citetitle>ICFP</citetitle>, Sep 2001. -Introduced the notation described here. -</para> -</listitem> - -<listitem> -<para> -“<ulink url="http://www.soi.city.ac.uk/~ross/papers/fop.html">Arrows and Computation</ulink>”, -Ross Paterson, in <citetitle>The Fun of Programming</citetitle>, -Palgrave, 2003. -</para> -</listitem> - -<listitem> -<para> -“<ulink url="http://www.cse.chalmers.se/~rjmh/afp-arrows.pdf">Programming with Arrows</ulink>”, -John Hughes, in <citetitle>5th International Summer School on -Advanced Functional Programming</citetitle>, -<citetitle>Lecture Notes in Computer Science</citetitle> vol. 3622, -Springer, 2004. -This paper includes another introduction to the notation, -with practical examples. -</para> -</listitem> - -<listitem> -<para> -“<ulink url="http://www.haskell.org/ghc/docs/papers/arrow-rules.pdf">Type and Translation Rules for Arrow Notation in GHC</ulink>”, -Ross Paterson and Simon Peyton Jones, September 16, 2004. -A terse enumeration of the formal rules used -(extracted from comments in the source code). -</para> -</listitem> - -<listitem> -<para> -The arrows web page at -<ulink url="http://www.haskell.org/arrows/"><literal>http://www.haskell.org/arrows/</literal></ulink>. -</para> -</listitem> - -</itemizedlist> -With the <option>-XArrows</option> flag, GHC supports the arrow -notation described in the second of these papers, -translating it using combinators from the -<ulink url="&libraryBaseLocation;/Control-Arrow.html"><literal>Control.Arrow</literal></ulink> -module. -What follows is a brief introduction to the notation; -it won't make much sense unless you've read Hughes's paper. -</para> - -<para>The extension adds a new kind of expression for defining arrows: -<screen> -<replaceable>exp</replaceable><superscript>10</superscript> ::= ... - | proc <replaceable>apat</replaceable> -> <replaceable>cmd</replaceable> -</screen> -where <literal>proc</literal> is a new keyword. -The variables of the pattern are bound in the body of the -<literal>proc</literal>-expression, -which is a new sort of thing called a <firstterm>command</firstterm>. -The syntax of commands is as follows: -<screen> -<replaceable>cmd</replaceable> ::= <replaceable>exp</replaceable><superscript>10</superscript> -< <replaceable>exp</replaceable> - | <replaceable>exp</replaceable><superscript>10</superscript> -<< <replaceable>exp</replaceable> - | <replaceable>cmd</replaceable><superscript>0</superscript> -</screen> -with <replaceable>cmd</replaceable><superscript>0</superscript> up to -<replaceable>cmd</replaceable><superscript>9</superscript> defined using -infix operators as for expressions, and -<screen> -<replaceable>cmd</replaceable><superscript>10</superscript> ::= \ <replaceable>apat</replaceable> ... <replaceable>apat</replaceable> -> <replaceable>cmd</replaceable> - | let <replaceable>decls</replaceable> in <replaceable>cmd</replaceable> - | if <replaceable>exp</replaceable> then <replaceable>cmd</replaceable> else <replaceable>cmd</replaceable> - | case <replaceable>exp</replaceable> of { <replaceable>calts</replaceable> } - | do { <replaceable>cstmt</replaceable> ; ... <replaceable>cstmt</replaceable> ; <replaceable>cmd</replaceable> } - | <replaceable>fcmd</replaceable> - -<replaceable>fcmd</replaceable> ::= <replaceable>fcmd</replaceable> <replaceable>aexp</replaceable> - | ( <replaceable>cmd</replaceable> ) - | (| <replaceable>aexp</replaceable> <replaceable>cmd</replaceable> ... <replaceable>cmd</replaceable> |) - -<replaceable>cstmt</replaceable> ::= let <replaceable>decls</replaceable> - | <replaceable>pat</replaceable> <- <replaceable>cmd</replaceable> - | rec { <replaceable>cstmt</replaceable> ; ... <replaceable>cstmt</replaceable> [;] } - | <replaceable>cmd</replaceable> -</screen> -where <replaceable>calts</replaceable> are like <replaceable>alts</replaceable> -except that the bodies are commands instead of expressions. -</para> - -<para> -Commands produce values, but (like monadic computations) -may yield more than one value, -or none, and may do other things as well. -For the most part, familiarity with monadic notation is a good guide to -using commands. -However the values of expressions, even monadic ones, -are determined by the values of the variables they contain; -this is not necessarily the case for commands. -</para> - -<para> -A simple example of the new notation is the expression -<screen> -proc x -> f -< x+1 -</screen> -We call this a <firstterm>procedure</firstterm> or -<firstterm>arrow abstraction</firstterm>. -As with a lambda expression, the variable <literal>x</literal> -is a new variable bound within the <literal>proc</literal>-expression. -It refers to the input to the arrow. -In the above example, <literal>-<</literal> is not an identifier but an -new reserved symbol used for building commands from an expression of arrow -type and an expression to be fed as input to that arrow. -(The weird look will make more sense later.) -It may be read as analogue of application for arrows. -The above example is equivalent to the Haskell expression -<screen> -arr (\ x -> x+1) >>> f -</screen> -That would make no sense if the expression to the left of -<literal>-<</literal> involves the bound variable <literal>x</literal>. -More generally, the expression to the left of <literal>-<</literal> -may not involve any <firstterm>local variable</firstterm>, -i.e. a variable bound in the current arrow abstraction. -For such a situation there is a variant <literal>-<<</literal>, as in -<screen> -proc x -> f x -<< x+1 -</screen> -which is equivalent to -<screen> -arr (\ x -> (f x, x+1)) >>> app -</screen> -so in this case the arrow must belong to the <literal>ArrowApply</literal> -class. -Such an arrow is equivalent to a monad, so if you're using this form -you may find a monadic formulation more convenient. -</para> - -<sect2> -<title>do-notation for commands</title> - -<para> -Another form of command is a form of <literal>do</literal>-notation. -For example, you can write -<screen> -proc x -> do - y <- f -< x+1 - g -< 2*y - let z = x+y - t <- h -< x*z - returnA -< t+z -</screen> -You can read this much like ordinary <literal>do</literal>-notation, -but with commands in place of monadic expressions. -The first line sends the value of <literal>x+1</literal> as an input to -the arrow <literal>f</literal>, and matches its output against -<literal>y</literal>. -In the next line, the output is discarded. -The arrow <function>returnA</function> is defined in the -<ulink url="&libraryBaseLocation;/Control-Arrow.html"><literal>Control.Arrow</literal></ulink> -module as <literal>arr id</literal>. -The above example is treated as an abbreviation for -<screen> -arr (\ x -> (x, x)) >>> - first (arr (\ x -> x+1) >>> f) >>> - arr (\ (y, x) -> (y, (x, y))) >>> - first (arr (\ y -> 2*y) >>> g) >>> - arr snd >>> - arr (\ (x, y) -> let z = x+y in ((x, z), z)) >>> - first (arr (\ (x, z) -> x*z) >>> h) >>> - arr (\ (t, z) -> t+z) >>> - returnA -</screen> -Note that variables not used later in the composition are projected out. -After simplification using rewrite rules (see <xref linkend="rewrite-rules"/>) -defined in the -<ulink url="&libraryBaseLocation;/Control-Arrow.html"><literal>Control.Arrow</literal></ulink> -module, this reduces to -<screen> -arr (\ x -> (x+1, x)) >>> - first f >>> - arr (\ (y, x) -> (2*y, (x, y))) >>> - first g >>> - arr (\ (_, (x, y)) -> let z = x+y in (x*z, z)) >>> - first h >>> - arr (\ (t, z) -> t+z) -</screen> -which is what you might have written by hand. -With arrow notation, GHC keeps track of all those tuples of variables for you. -</para> - -<para> -Note that although the above translation suggests that -<literal>let</literal>-bound variables like <literal>z</literal> must be -monomorphic, the actual translation produces Core, -so polymorphic variables are allowed. -</para> - -<para> -It's also possible to have mutually recursive bindings, -using the new <literal>rec</literal> keyword, as in the following example: -<programlisting> -counter :: ArrowCircuit a => a Bool Int -counter = proc reset -> do - rec output <- returnA -< if reset then 0 else next - next <- delay 0 -< output+1 - returnA -< output -</programlisting> -The translation of such forms uses the <function>loop</function> combinator, -so the arrow concerned must belong to the <literal>ArrowLoop</literal> class. -</para> - -</sect2> - -<sect2> -<title>Conditional commands</title> - -<para> -In the previous example, we used a conditional expression to construct the -input for an arrow. -Sometimes we want to conditionally execute different commands, as in -<screen> -proc (x,y) -> - if f x y - then g -< x+1 - else h -< y+2 -</screen> -which is translated to -<screen> -arr (\ (x,y) -> if f x y then Left x else Right y) >>> - (arr (\x -> x+1) >>> g) ||| (arr (\y -> y+2) >>> h) -</screen> -Since the translation uses <function>|||</function>, -the arrow concerned must belong to the <literal>ArrowChoice</literal> class. -</para> - -<para> -There are also <literal>case</literal> commands, like -<screen> -case input of - [] -> f -< () - [x] -> g -< x+1 - x1:x2:xs -> do - y <- h -< (x1, x2) - ys <- k -< xs - returnA -< y:ys -</screen> -The syntax is the same as for <literal>case</literal> expressions, -except that the bodies of the alternatives are commands rather than expressions. -The translation is similar to that of <literal>if</literal> commands. -</para> - -</sect2> - -<sect2> -<title>Defining your own control structures</title> - -<para> -As we're seen, arrow notation provides constructs, -modelled on those for expressions, -for sequencing, value recursion and conditionals. -But suitable combinators, -which you can define in ordinary Haskell, -may also be used to build new commands out of existing ones. -The basic idea is that a command defines an arrow from environments to values. -These environments assign values to the free local variables of the command. -Thus combinators that produce arrows from arrows -may also be used to build commands from commands. -For example, the <literal>ArrowPlus</literal> class includes a combinator -<programlisting> -ArrowPlus a => (<+>) :: a b c -> a b c -> a b c -</programlisting> -so we can use it to build commands: -<programlisting> -expr' = proc x -> do - returnA -< x - <+> do - symbol Plus -< () - y <- term -< () - expr' -< x + y - <+> do - symbol Minus -< () - y <- term -< () - expr' -< x - y -</programlisting> -(The <literal>do</literal> on the first line is needed to prevent the first -<literal><+> ...</literal> from being interpreted as part of the -expression on the previous line.) -This is equivalent to -<programlisting> -expr' = (proc x -> returnA -< x) - <+> (proc x -> do - symbol Plus -< () - y <- term -< () - expr' -< x + y) - <+> (proc x -> do - symbol Minus -< () - y <- term -< () - expr' -< x - y) -</programlisting> -We are actually using <literal><+></literal> here with the more specific type -<programlisting> -ArrowPlus a => (<+>) :: a (e,()) c -> a (e,()) c -> a (e,()) c -</programlisting> -It is essential that this operator be polymorphic in <literal>e</literal> -(representing the environment input to the command -and thence to its subcommands) -and satisfy the corresponding naturality property -<screen> -arr (first k) >>> (f <+> g) = (arr (first k) >>> f) <+> (arr (first k) >>> g) -</screen> -at least for strict <literal>k</literal>. -(This should be automatic if you're not using <function>seq</function>.) -This ensures that environments seen by the subcommands are environments -of the whole command, -and also allows the translation to safely trim these environments. -(The second component of the input pairs can contain unnamed input values, -as described in the next section.) -The operator must also not use any variable defined within the current -arrow abstraction. -</para> - -<para> -We could define our own operator -<programlisting> -untilA :: ArrowChoice a => a (e,s) () -> a (e,s) Bool -> a (e,s) () -untilA body cond = proc x -> - b <- cond -< x - if b then returnA -< () - else do - body -< x - untilA body cond -< x -</programlisting> -and use it in the same way. -Of course this infix syntax only makes sense for binary operators; -there is also a more general syntax involving special brackets: -<screen> -proc x -> do - y <- f -< x+1 - (|untilA (increment -< x+y) (within 0.5 -< x)|) -</screen> -</para> - -</sect2> - -<sect2> -<title>Primitive constructs</title> - -<para> -Some operators will need to pass additional inputs to their subcommands. -For example, in an arrow type supporting exceptions, -the operator that attaches an exception handler will wish to pass the -exception that occurred to the handler. -Such an operator might have a type -<screen> -handleA :: ... => a (e,s) c -> a (e,(Ex,s)) c -> a (e,s) c -</screen> -where <literal>Ex</literal> is the type of exceptions handled. -You could then use this with arrow notation by writing a command -<screen> -body `handleA` \ ex -> handler -</screen> -so that if an exception is raised in the command <literal>body</literal>, -the variable <literal>ex</literal> is bound to the value of the exception -and the command <literal>handler</literal>, -which typically refers to <literal>ex</literal>, is entered. -Though the syntax here looks like a functional lambda, -we are talking about commands, and something different is going on. -The input to the arrow represented by a command consists of values for -the free local variables in the command, plus a stack of anonymous values. -In all the prior examples, we made no assumptions about this stack. -In the second argument to <function>handleA</function>, -the value of the exception has been added to the stack input to the handler. -The command form of lambda merely gives this value a name. -</para> - -<para> -More concretely, -the input to a command consists of a pair of an environment and a stack. -Each value on the stack is paired with the remainder of the stack, -with an empty stack being <literal>()</literal>. -So operators like <function>handleA</function> that pass -extra inputs to their subcommands can be designed for use with the notation -by placing the values on the stack paired with the environment in this way. -More precisely, the type of each argument of the operator (and its result) -should have the form -<screen> -a (e, (t1, ... (tn, ())...)) t -</screen> -where <replaceable>e</replaceable> is a polymorphic variable -(representing the environment) -and <replaceable>ti</replaceable> are the types of the values on the stack, -with <replaceable>t1</replaceable> being the <quote>top</quote>. -The polymorphic variable <replaceable>e</replaceable> must not occur in -<replaceable>a</replaceable>, <replaceable>ti</replaceable> or -<replaceable>t</replaceable>. -However the arrows involved need not be the same. -Here are some more examples of suitable operators: -<screen> -bracketA :: ... => a (e,s) b -> a (e,(b,s)) c -> a (e,(c,s)) d -> a (e,s) d -runReader :: ... => a (e,s) c -> a' (e,(State,s)) c -runState :: ... => a (e,s) c -> a' (e,(State,s)) (c,State) -</screen> -We can supply the extra input required by commands built with the last two -by applying them to ordinary expressions, as in -<screen> -proc x -> do - s <- ... - (|runReader (do { ... })|) s -</screen> -which adds <literal>s</literal> to the stack of inputs to the command -built using <function>runReader</function>. -</para> - -<para> -The command versions of lambda abstraction and application are analogous to -the expression versions. -In particular, the beta and eta rules describe equivalences of commands. -These three features (operators, lambda abstraction and application) -are the core of the notation; everything else can be built using them, -though the results would be somewhat clumsy. -For example, we could simulate <literal>do</literal>-notation by defining -<programlisting> -bind :: Arrow a => a (e,s) b -> a (e,(b,s)) c -> a (e,s) c -u `bind` f = returnA &&& u >>> f - -bind_ :: Arrow a => a (e,s) b -> a (e,s) c -> a (e,s) c -u `bind_` f = u `bind` (arr fst >>> f) -</programlisting> -We could simulate <literal>if</literal> by defining -<programlisting> -cond :: ArrowChoice a => a (e,s) b -> a (e,s) b -> a (e,(Bool,s)) b -cond f g = arr (\ (e,(b,s)) -> if b then Left (e,s) else Right (e,s)) >>> f ||| g -</programlisting> -</para> - -</sect2> - -<sect2> -<title>Differences with the paper</title> - -<itemizedlist> - -<listitem> -<para>Instead of a single form of arrow application (arrow tail) with two -translations, the implementation provides two forms -<quote><literal>-<</literal></quote> (first-order) -and <quote><literal>-<<</literal></quote> (higher-order). -</para> -</listitem> - -<listitem> -<para>User-defined operators are flagged with banana brackets instead of -a new <literal>form</literal> keyword. -</para> -</listitem> - -<listitem> -<para>In the paper and the previous implementation, -values on the stack were paired to the right of the environment -in a single argument, -but now the environment and stack are separate arguments. -</para> -</listitem> - -</itemizedlist> - -</sect2> - -<sect2> -<title>Portability</title> - -<para> -Although only GHC implements arrow notation directly, -there is also a preprocessor -(available from the -<ulink url="http://www.haskell.org/arrows/">arrows web page</ulink>) -that translates arrow notation into Haskell 98 -for use with other Haskell systems. -You would still want to check arrow programs with GHC; -tracing type errors in the preprocessor output is not easy. -Modules intended for both GHC and the preprocessor must observe some -additional restrictions: -<itemizedlist> - -<listitem> -<para> -The module must import -<ulink url="&libraryBaseLocation;/Control-Arrow.html"><literal>Control.Arrow</literal></ulink>. -</para> -</listitem> - -<listitem> -<para> -The preprocessor cannot cope with other Haskell extensions. -These would have to go in separate modules. -</para> -</listitem> - -<listitem> -<para> -Because the preprocessor targets Haskell (rather than Core), -<literal>let</literal>-bound variables are monomorphic. -</para> -</listitem> - -</itemizedlist> -</para> - -</sect2> - -</sect1> - -<!-- ==================== BANG PATTERNS ================= --> - -<sect1 id="bang-patterns"> -<title>Bang patterns -<indexterm><primary>Bang patterns</primary></indexterm> -</title> -<para>GHC supports an extension of pattern matching called <emphasis>bang -patterns</emphasis>, written <literal>!<replaceable>pat</replaceable></literal>. -Bang patterns are under consideration for Haskell Prime. -The <ulink -url="http://ghc.haskell.org/trac/haskell-prime/wiki/BangPatterns">Haskell -prime feature description</ulink> contains more discussion and examples -than the material below. -</para> -<para> -The key change is the addition of a new rule to the -<ulink url="http://haskell.org/onlinereport/exps.html#sect3.17.2">semantics of pattern matching in the Haskell 98 report</ulink>. -Add new bullet 10, saying: Matching the pattern <literal>!</literal><replaceable>pat</replaceable> -against a value <replaceable>v</replaceable> behaves as follows: -<itemizedlist> -<listitem><para>if <replaceable>v</replaceable> is bottom, the match diverges</para></listitem> -<listitem><para>otherwise, <replaceable>pat</replaceable> is matched against <replaceable>v</replaceable> </para></listitem> -</itemizedlist> -</para> -<para> -Bang patterns are enabled by the flag <option>-XBangPatterns</option>. -</para> - -<sect2 id="bang-patterns-informal"> -<title>Informal description of bang patterns -</title> -<para> -The main idea is to add a single new production to the syntax of patterns: -<programlisting> - pat ::= !pat -</programlisting> -Matching an expression <literal>e</literal> against a pattern <literal>!p</literal> is done by first -evaluating <literal>e</literal> (to WHNF) and then matching the result against <literal>p</literal>. -Example: -<programlisting> -f1 !x = True -</programlisting> -This definition makes <literal>f1</literal> is strict in <literal>x</literal>, -whereas without the bang it would be lazy. -Bang patterns can be nested of course: -<programlisting> -f2 (!x, y) = [x,y] -</programlisting> -Here, <literal>f2</literal> is strict in <literal>x</literal> but not in -<literal>y</literal>. -A bang only really has an effect if it precedes a variable or wild-card pattern: -<programlisting> -f3 !(x,y) = [x,y] -f4 (x,y) = [x,y] -</programlisting> -Here, <literal>f3</literal> and <literal>f4</literal> are identical; -putting a bang before a pattern that -forces evaluation anyway does nothing. -</para> -<para> -There is one (apparent) exception to this general rule that a bang only -makes a difference when it precedes a variable or wild-card: a bang at the -top level of a <literal>let</literal> or <literal>where</literal> -binding makes the binding strict, regardless of the pattern. -(We say "apparent" exception because the Right Way to think of it is that the bang -at the top of a binding is not part of the <emphasis>pattern</emphasis>; rather it -is part of the syntax of the <emphasis>binding</emphasis>, -creating a "bang-pattern binding".) -For example: -<programlisting> -let ![x,y] = e in b -</programlisting> -is a bang-pattern binding. Operationally, it behaves just like a case expression: -<programlisting> -case e of [x,y] -> b -</programlisting> -Like a case expression, a bang-pattern binding must be non-recursive, and -is monomorphic. - -However, <emphasis>nested</emphasis> bangs in a pattern binding behave uniformly with all other forms of -pattern matching. For example -<programlisting> -let (!x,[y]) = e in b -</programlisting> -is equivalent to this: -<programlisting> -let { t = case e of (x,[y]) -> x `seq` (x,y) - x = fst t - y = snd t } -in b -</programlisting> -The binding is lazy, but when either <literal>x</literal> or <literal>y</literal> is -evaluated by <literal>b</literal> the entire pattern is matched, including forcing the -evaluation of <literal>x</literal>. -</para> -<para> -Bang patterns work in <literal>case</literal> expressions too, of course: -<programlisting> -g5 x = let y = f x in body -g6 x = case f x of { y -> body } -g7 x = case f x of { !y -> body } -</programlisting> -The functions <literal>g5</literal> and <literal>g6</literal> mean exactly the same thing. -But <literal>g7</literal> evaluates <literal>(f x)</literal>, binds <literal>y</literal> to the -result, and then evaluates <literal>body</literal>. -</para> -</sect2> - - -<sect2 id="bang-patterns-sem"> -<title>Syntax and semantics -</title> -<para> - -We add a single new production to the syntax of patterns: -<programlisting> - pat ::= !pat -</programlisting> -There is one problem with syntactic ambiguity. Consider: -<programlisting> -f !x = 3 -</programlisting> -Is this a definition of the infix function "<literal>(!)</literal>", -or of the "<literal>f</literal>" with a bang pattern? GHC resolves this -ambiguity in favour of the latter. If you want to define -<literal>(!)</literal> with bang-patterns enabled, you have to do so using -prefix notation: -<programlisting> -(!) f x = 3 -</programlisting> -The semantics of Haskell pattern matching is described in <ulink -url="http://www.haskell.org/onlinereport/exps.html#sect3.17.2"> -Section 3.17.2</ulink> of the Haskell Report. To this description add -one extra item 10, saying: -<itemizedlist><listitem><para>Matching -the pattern <literal>!pat</literal> against a value <literal>v</literal> behaves as follows: -<itemizedlist><listitem><para>if <literal>v</literal> is bottom, the match diverges</para></listitem> - <listitem><para>otherwise, <literal>pat</literal> is matched against - <literal>v</literal></para></listitem> -</itemizedlist> -</para></listitem></itemizedlist> -Similarly, in Figure 4 of <ulink url="http://www.haskell.org/onlinereport/exps.html#sect3.17.3"> -Section 3.17.3</ulink>, add a new case (t): -<programlisting> -case v of { !pat -> e; _ -> e' } - = v `seq` case v of { pat -> e; _ -> e' } -</programlisting> -</para><para> -That leaves let expressions, whose translation is given in -<ulink url="http://www.haskell.org/onlinereport/exps.html#sect3.12">Section -3.12</ulink> -of the Haskell Report. -In the translation box, first apply -the following transformation: for each pattern <literal>pi</literal> that is of -form <literal>!qi = ei</literal>, transform it to <literal>(xi,!qi) = ((),ei)</literal>, and replace <literal>e0</literal> -by <literal>(xi `seq` e0)</literal>. Then, when none of the left-hand-side patterns -have a bang at the top, apply the rules in the existing box. -</para> -<para>The effect of the let rule is to force complete matching of the pattern -<literal>qi</literal> before evaluation of the body is begun. The bang is -retained in the translated form in case <literal>qi</literal> is a variable, -thus: -<programlisting> - let !y = f x in b -</programlisting> - -</para> -<para> -The let-binding can be recursive. However, it is much more common for -the let-binding to be non-recursive, in which case the following law holds: -<literal>(let !p = rhs in body)</literal> - is equivalent to -<literal>(case rhs of !p -> body)</literal> -</para> -<para> -A pattern with a bang at the outermost level is not allowed at the top level of -a module. -</para> -</sect2> -</sect1> - -<!-- ==================== ASSERTIONS ================= --> - -<sect1 id="assertions"> -<title>Assertions -<indexterm><primary>Assertions</primary></indexterm> -</title> - -<para> -If you want to make use of assertions in your standard Haskell code, you -could define a function like the following: -</para> - -<para> - -<programlisting> -assert :: Bool -> a -> a -assert False x = error "assertion failed!" -assert _ x = x -</programlisting> - -</para> - -<para> -which works, but gives you back a less than useful error message -- -an assertion failed, but which and where? -</para> - -<para> -One way out is to define an extended <function>assert</function> function which also -takes a descriptive string to include in the error message and -perhaps combine this with the use of a pre-processor which inserts -the source location where <function>assert</function> was used. -</para> - -<para> -Ghc offers a helping hand here, doing all of this for you. For every -use of <function>assert</function> in the user's source: -</para> - -<para> - -<programlisting> -kelvinToC :: Double -> Double -kelvinToC k = assert (k >= 0.0) (k+273.15) -</programlisting> - -</para> - -<para> -Ghc will rewrite this to also include the source location where the -assertion was made, -</para> - -<para> - -<programlisting> -assert pred val ==> assertError "Main.hs|15" pred val -</programlisting> - -</para> - -<para> -The rewrite is only performed by the compiler when it spots -applications of <function>Control.Exception.assert</function>, so you -can still define and use your own versions of -<function>assert</function>, should you so wish. If not, import -<literal>Control.Exception</literal> to make use -<function>assert</function> in your code. -</para> - -<para> -GHC ignores assertions when optimisation is turned on with the - <option>-O</option><indexterm><primary><option>-O</option></primary></indexterm> flag. That is, expressions of the form -<literal>assert pred e</literal> will be rewritten to -<literal>e</literal>. You can also disable assertions using the - <option>-fignore-asserts</option> - option<indexterm><primary><option>-fignore-asserts</option></primary> - </indexterm>. The option <option>-fno-ignore-asserts</option> allows -enabling assertions even when optimisation is turned on. -</para> - -<para> -Assertion failures can be caught, see the documentation for the -<literal>Control.Exception</literal> library for the details. -</para> - -</sect1> - -<!-- =============================== STATIC POINTERS =========================== --> - -<sect1 id="static-pointers"> -<title>Static pointers -<indexterm><primary>Static pointers</primary></indexterm> -</title> - -<para> -The language extension <literal>-XStaticPointers</literal> adds a new -syntactic form <literal>static <replaceable>e</replaceable></literal>, -which stands for a reference to the closed expression -<replaceable>e</replaceable>. This reference is stable and portable, -in the sense that it remains valid across different processes on -possibly different machines. Thus, a process can create a reference -and send it to another process that can resolve it to -<replaceable>e</replaceable>. -</para> -<para> -With this extension turned on, <literal>static</literal> is no longer -a valid identifier. -</para> -<para> -Static pointers were first proposed in the paper <ulink -url="http://research.microsoft.com/en-us/um/people/simonpj/papers/parallel/remote.pdf"> -Towards Haskell in the cloud</ulink>, Jeff Epstein, Andrew P. Black and Simon -Peyton-Jones, Proceedings of the 4th ACM Symposium on Haskell, pp. -118-129, ACM, 2011. -</para> - -<sect2 id="using-static-pointers"> -<title>Using static pointers</title> - -<para> -Each reference is given a key which can be used to locate it at runtime with -<ulink url="&libraryBaseLocation;/GHC.StaticPtr.html#v%3AunsafeLookupStaticPtr"><literal>unsafeLookupStaticPtr</literal></ulink> -which uses a global and immutable table called the Static Pointer Table. -The compiler includes entries in this table for all static forms found in -the linked modules. The value can be obtained from the reference via -<ulink url="&libraryBaseLocation;/GHC.StaticPtr.html#v%3AdeRefStaticPtr"><literal>deRefStaticPtr</literal></ulink> -</para> - -<para> -The body <literal>e</literal> of a <literal>static -e</literal> expression must be a closed expression. That is, there can -be no free variables occurring in <literal>e</literal>, i.e. lambda- -or let-bound variables bound locally in the context of the expression. -</para> - -<para> -All of the following are permissible: -<programlisting> -inc :: Int -> Int -inc x = x + 1 - -ref1 = static 1 -ref2 = static inc -ref3 = static (inc 1) -ref4 = static ((\x -> x + 1) (1 :: Int)) -ref5 y = static (let x = 1 in x) -</programlisting> -While the following definitions are rejected: -<programlisting> -ref6 = let x = 1 in static x -ref7 y = static (let x = 1 in y) -</programlisting> -</para> -</sect2> - -<sect2 id="typechecking-static-pointers"> -<title>Static semantics of static pointers</title> - -<para> - -Informally, if we have a closed expression -<programlisting> -e :: forall a_1 ... a_n . t -</programlisting> -the static form is of type -<programlisting> -static e :: (Typeable a_1, ... , Typeable a_n) => StaticPtr t -</programlisting> -Furthermore, type <literal>t</literal> is constrained to have a -<literal>Typeable</literal> instance. - -The following are therefore illegal: -<programlisting> -static show -- No Typeable instance for (Show a => a -> String) -static Control.Monad.ST.runST -- No Typeable instance for ((forall s. ST s a) -> a) -</programlisting> - -That being said, with the appropriate use of wrapper datatypes, the -above limitations induce no loss of generality: -<programlisting> -{-# LANGUAGE ConstraintKinds #-} -{-# LANGUAGE DeriveDataTypeable #-} -{-# LANGUAGE ExistentialQuantification #-} -{-# LANGUAGE Rank2Types #-} -{-# LANGUAGE StandaloneDeriving #-} -{-# LANGUAGE StaticPointers #-} - -import Control.Monad.ST -import Data.Typeable -import GHC.StaticPtr - -data Dict c = c => Dict - deriving Typeable - -g1 :: Typeable a => StaticPtr (Dict (Show a) -> a -> String) -g1 = static (\Dict -> show) - -data Rank2Wrapper f = R2W (forall s. f s) - deriving Typeable -newtype Flip f a s = Flip { unFlip :: f s a } - deriving Typeable - -g2 :: Typeable a => StaticPtr (Rank2Wrapper (Flip ST a) -> a) -g2 = static (\(R2W f) -> runST (unFlip f)) -</programlisting> -</para> -</sect2> - -</sect1> - - -<!-- =============================== PRAGMAS =========================== --> - - <sect1 id="pragmas"> - <title>Pragmas</title> - - <indexterm><primary>pragma</primary></indexterm> - - <para>GHC supports several pragmas, or instructions to the - compiler placed in the source code. Pragmas don't normally affect - the meaning of the program, but they might affect the efficiency - of the generated code.</para> - - <para>Pragmas all take the form - -<literal>{-# <replaceable>word</replaceable> ... #-}</literal> - - where <replaceable>word</replaceable> indicates the type of - pragma, and is followed optionally by information specific to that - type of pragma. Case is ignored in - <replaceable>word</replaceable>. The various values for - <replaceable>word</replaceable> that GHC understands are described - in the following sections; any pragma encountered with an - unrecognised <replaceable>word</replaceable> is - ignored. The layout rule applies in pragmas, so the closing <literal>#-}</literal> - should start in a column to the right of the opening <literal>{-#</literal>. </para> - - <para>Certain pragmas are <emphasis>file-header pragmas</emphasis>: - <itemizedlist> - <listitem><para> - A file-header - pragma must precede the <literal>module</literal> keyword in the file. - </para></listitem> - <listitem><para> - There can be as many file-header pragmas as you please, and they can be - preceded or followed by comments. - </para></listitem> - <listitem><para> - File-header pragmas are read once only, before - pre-processing the file (e.g. with cpp). - </para></listitem> - <listitem><para> - The file-header pragmas are: <literal>{-# LANGUAGE #-}</literal>, - <literal>{-# OPTIONS_GHC #-}</literal>, and - <literal>{-# INCLUDE #-}</literal>. - </para></listitem> - </itemizedlist> - </para> - - <sect2 id="language-pragma"> - <title>LANGUAGE pragma</title> - - <indexterm><primary>LANGUAGE</primary><secondary>pragma</secondary></indexterm> - <indexterm><primary>pragma</primary><secondary>LANGUAGE</secondary></indexterm> - - <para>The <literal>LANGUAGE</literal> pragma allows language extensions to be enabled - in a portable way. - It is the intention that all Haskell compilers support the - <literal>LANGUAGE</literal> pragma with the same syntax, although not - all extensions are supported by all compilers, of - course. The <literal>LANGUAGE</literal> pragma should be used instead - of <literal>OPTIONS_GHC</literal>, if possible.</para> - - <para>For example, to enable the FFI and preprocessing with CPP:</para> - -<programlisting>{-# LANGUAGE ForeignFunctionInterface, CPP #-}</programlisting> - - <para><literal>LANGUAGE</literal> is a file-header pragma (see <xref linkend="pragmas"/>).</para> - - <para>Every language extension can also be turned into a command-line flag - by prefixing it with "<literal>-X</literal>"; for example <option>-XForeignFunctionInterface</option>. - (Similarly, all "<literal>-X</literal>" flags can be written as <literal>LANGUAGE</literal> pragmas.) - </para> - - <para>A list of all supported language extensions can be obtained by invoking - <literal>ghc --supported-extensions</literal> (see <xref linkend="modes"/>).</para> - - <para>Any extension from the <literal>Extension</literal> type defined in - <ulink - url="&libraryCabalLocation;/Language-Haskell-Extension.html"><literal>Language.Haskell.Extension</literal></ulink> - may be used. GHC will report an error if any of the requested extensions are not supported.</para> - </sect2> - - - <sect2 id="options-pragma"> - <title>OPTIONS_GHC pragma</title> - <indexterm><primary>OPTIONS_GHC</primary> - </indexterm> - <indexterm><primary>pragma</primary><secondary>OPTIONS_GHC</secondary> - </indexterm> - - <para>The <literal>OPTIONS_GHC</literal> pragma is used to specify - additional options that are given to the compiler when compiling - this source file. See <xref linkend="source-file-options"/> for - details.</para> - - <para>Previous versions of GHC accepted <literal>OPTIONS</literal> rather - than <literal>OPTIONS_GHC</literal>, but that is now deprecated.</para> - </sect2> - - <para><literal>OPTIONS_GHC</literal> is a file-header pragma (see <xref linkend="pragmas"/>).</para> - - <sect2 id="include-pragma"> - <title>INCLUDE pragma</title> - - <para>The <literal>INCLUDE</literal> used to be necessary for - specifying header files to be included when using the FFI and - compiling via C. It is no longer required for GHC, but is - accepted (and ignored) for compatibility with other - compilers.</para> - </sect2> - - <sect2 id="warning-deprecated-pragma"> - <title>WARNING and DEPRECATED pragmas</title> - <indexterm><primary>WARNING</primary></indexterm> - <indexterm><primary>DEPRECATED</primary></indexterm> - - <para>The WARNING pragma allows you to attach an arbitrary warning - to a particular function, class, or type. - A DEPRECATED pragma lets you specify that - a particular function, class, or type is deprecated. - There are two ways of using these pragmas. - - <itemizedlist> - <listitem> - <para>You can work on an entire module thus:</para> -<programlisting> - module Wibble {-# DEPRECATED "Use Wobble instead" #-} where - ... -</programlisting> - <para>Or:</para> -<programlisting> - module Wibble {-# WARNING "This is an unstable interface." #-} where - ... -</programlisting> - <para>When you compile any module that import - <literal>Wibble</literal>, GHC will print the specified - message.</para> - </listitem> - - <listitem> - <para>You can attach a warning to a function, class, type, or data constructor, with the - following top-level declarations:</para> -<programlisting> - {-# DEPRECATED f, C, T "Don't use these" #-} - {-# WARNING unsafePerformIO "This is unsafe; I hope you know what you're doing" #-} -</programlisting> - <para>When you compile any module that imports and uses any - of the specified entities, GHC will print the specified - message.</para> - <para> You can only attach to entities declared at top level in the module - being compiled, and you can only use unqualified names in the list of - entities. A capitalised name, such as <literal>T</literal> - refers to <emphasis>either</emphasis> the type constructor <literal>T</literal> - <emphasis>or</emphasis> the data constructor <literal>T</literal>, or both if - both are in scope. If both are in scope, there is currently no way to - specify one without the other (c.f. fixities - <xref linkend="infix-tycons"/>).</para> - </listitem> - </itemizedlist> - Warnings and deprecations are not reported for - (a) uses within the defining module, - (b) defining a method in a class instance, and - (c) uses in an export list. - The latter reduces spurious complaints within a library - in which one module gathers together and re-exports - the exports of several others. - </para> - <para>You can suppress the warnings with the flag - <option>-fno-warn-warnings-deprecations</option>.</para> - </sect2> - - <sect2 id="minimal-pragma"> - <title>MINIMAL pragma</title> - <indexterm><primary>MINIMAL</primary></indexterm> - <para>The MINIMAL pragma is used to specify the minimal complete definition of a class. I.e. specify which methods must be implemented by all instances. If an instance does not satisfy the minimal complete definition, then a warning is generated. - This can be useful when a class has methods with circular defaults. For example - </para> -<programlisting> -class Eq a where - (==) :: a -> a -> Bool - (/=) :: a -> a -> Bool - x == y = not (x /= y) - x /= y = not (x == y) - {-# MINIMAL (==) | (/=) #-} -</programlisting> - <para>Without the MINIMAL pragma no warning would be generated for an instance that implements neither method. - </para> - <para>The syntax for minimal complete definition is:</para> -<screen> -mindef ::= name - | '(' mindef ')' - | mindef '|' mindef - | mindef ',' mindef -</screen> - <para>A vertical bar denotes disjunction, i.e. one of the two sides is required. - A comma denotes conjunction, i.e. both sides are required. - Conjunction binds stronger than disjunction.</para> - <para> - If no MINIMAL pragma is given in the class declaration, it is just as if - a pragma <literal>{-# MINIMAL op1, op2, ..., opn #-}</literal> was given, where - the <literal>opi</literal> are the methods - (a) that lack a default method in the class declaration, and - (b) whose name that does not start with an underscore - (c.f. <option>-fwarn-missing-methods</option>, <xref linkend="options-sanity"/>). - </para> - <para>This warning can be turned off with the flag <option>-fno-warn-missing-methods</option>.</para> - </sect2> - - <sect2 id="inline-noinline-pragma"> - <title>INLINE and NOINLINE pragmas</title> - - <para>These pragmas control the inlining of function - definitions.</para> - - <sect3 id="inline-pragma"> - <title>INLINE pragma</title> - <indexterm><primary>INLINE</primary></indexterm> - - <para> - GHC (with <option>-O</option>, as always) tries to inline - (or “unfold”) functions/values that are - “small enough,” thus avoiding the call overhead - and possibly exposing other more-wonderful optimisations. - GHC has a set of heuristics, tuned over a long period of - time using many benchmarks, that decide when it is - beneficial to inline a function at its call site. The - heuristics are designed to inline functions when it appears - to be beneficial to do so, but without incurring excessive - code bloat. If a function looks too big, it won't be - inlined, and functions larger than a certain size will not - even have their definition exported in the interface file. - Some of the thresholds that govern these heuristic decisions - can be changed using flags, see <xref linkend="options-f" - />. - </para> - - <para> - Normally GHC will do a reasonable job of deciding by itself - when it is a good idea to inline a function. However, - sometimes you might want to override the default behaviour. - For example, if you have a key function that is important to - inline because it leads to further optimisations, but GHC - judges it to be too big to inline. - </para> - - <para>The sledgehammer you can bring to bear is the - <literal>INLINE</literal><indexterm><primary>INLINE - pragma</primary></indexterm> pragma, used thusly:</para> - -<programlisting> -key_function :: Int -> String -> (Bool, Double) -{-# INLINE key_function #-} -</programlisting> - - <para>The major effect of an <literal>INLINE</literal> pragma - is to declare a function's “cost” to be very low. - The normal unfolding machinery will then be very keen to - inline it. However, an <literal>INLINE</literal> pragma for a - function "<literal>f</literal>" has a number of other effects: -<itemizedlist> -<listitem><para> -While GHC is keen to inline the function, it does not do so -blindly. For example, if you write -<programlisting> -map key_function xs -</programlisting> -there really isn't any point in inlining <literal>key_function</literal> to get -<programlisting> -map (\x -> <replaceable>body</replaceable>) xs -</programlisting> -In general, GHC only inlines the function if there is some reason (no matter -how slight) to suppose that it is useful to do so. -</para></listitem> - -<listitem><para> -Moreover, GHC will only inline the function if it is <emphasis>fully applied</emphasis>, -where "fully applied" -means applied to as many arguments as appear (syntactically) -on the LHS of the function -definition. For example: -<programlisting> -comp1 :: (b -> c) -> (a -> b) -> a -> c -{-# INLINE comp1 #-} -comp1 f g = \x -> f (g x) - -comp2 :: (b -> c) -> (a -> b) -> a -> c -{-# INLINE comp2 #-} -comp2 f g x = f (g x) -</programlisting> -The two functions <literal>comp1</literal> and <literal>comp2</literal> have the -same semantics, but <literal>comp1</literal> will be inlined when applied -to <emphasis>two</emphasis> arguments, while <literal>comp2</literal> requires -<emphasis>three</emphasis>. This might make a big difference if you say -<programlisting> -map (not `comp1` not) xs -</programlisting> -which will optimise better than the corresponding use of `comp2`. -</para></listitem> - -<listitem><para> -It is useful for GHC to optimise the definition of an -INLINE function <literal>f</literal> just like any other non-INLINE function, -in case the non-inlined version of <literal>f</literal> is -ultimately called. But we don't want to inline -the <emphasis>optimised</emphasis> version -of <literal>f</literal>; -a major reason for INLINE pragmas is to expose functions -in <literal>f</literal>'s RHS that have -rewrite rules, and it's no good if those functions have been optimised -away. -</para> -<para> -So <emphasis>GHC guarantees to inline precisely the code that you wrote</emphasis>, no more -and no less. It does this by capturing a copy of the definition of the function to use -for inlining (we call this the "inline-RHS"), which it leaves untouched, -while optimising the ordinarily RHS as usual. For externally-visible functions -the inline-RHS (not the optimised RHS) is recorded in the interface file. -</para></listitem> -<listitem><para> -An INLINE function is not worker/wrappered by strictness analysis. -It's going to be inlined wholesale instead. -</para></listitem> -</itemizedlist> -</para> -<para>GHC ensures that inlining cannot go on forever: every mutually-recursive -group is cut by one or more <emphasis>loop breakers</emphasis> that is never inlined -(see <ulink url="http://research.microsoft.com/%7Esimonpj/Papers/inlining/index.htm"> -Secrets of the GHC inliner, JFP 12(4) July 2002</ulink>). -GHC tries not to select a function with an INLINE pragma as a loop breaker, but -when there is no choice even an INLINE function can be selected, in which case -the INLINE pragma is ignored. -For example, for a self-recursive function, the loop breaker can only be the function -itself, so an INLINE pragma is always ignored.</para> - - <para>Syntactically, an <literal>INLINE</literal> pragma for a - function can be put anywhere its type signature could be - put.</para> - - <para><literal>INLINE</literal> pragmas are a particularly - good idea for the - <literal>then</literal>/<literal>return</literal> (or - <literal>bind</literal>/<literal>unit</literal>) functions in - a monad. For example, in GHC's own - <literal>UniqueSupply</literal> monad code, we have:</para> - -<programlisting> -{-# INLINE thenUs #-} -{-# INLINE returnUs #-} -</programlisting> - - <para>See also the <literal>NOINLINE</literal> (<xref linkend="noinline-pragma"/>) - and <literal>INLINABLE</literal> (<xref linkend="inlinable-pragma"/>) - pragmas.</para> - - </sect3> - - <sect3 id="inlinable-pragma"> - <title>INLINABLE pragma</title> - -<para>An <literal>{-# INLINABLE f #-}</literal> pragma on a -function <literal>f</literal> has the following behaviour: -<itemizedlist> -<listitem><para> -While <literal>INLINE</literal> says "please inline me", the <literal>INLINABLE</literal> -says "feel free to inline me; use your -discretion". In other words the choice is left to GHC, which uses the same -rules as for pragma-free functions. Unlike <literal>INLINE</literal>, that decision is made at -the <emphasis>call site</emphasis>, and -will therefore be affected by the inlining threshold, optimisation level etc. -</para></listitem> -<listitem><para> -Like <literal>INLINE</literal>, the <literal>INLINABLE</literal> pragma retains a -copy of the original RHS for -inlining purposes, and persists it in the interface file, regardless of -the size of the RHS. -</para></listitem> - -<listitem><para> -One way to use <literal>INLINABLE</literal> is in conjunction with -the special function <literal>inline</literal> (<xref linkend="special-ids"/>). -The call <literal>inline f</literal> tries very hard to inline <literal>f</literal>. -To make sure that <literal>f</literal> can be inlined, -it is a good idea to mark the definition -of <literal>f</literal> as <literal>INLINABLE</literal>, -so that GHC guarantees to expose an unfolding regardless of how big it is. -Moreover, by annotating <literal>f</literal> as <literal>INLINABLE</literal>, -you ensure that <literal>f</literal>'s original RHS is inlined, rather than -whatever random optimised version of <literal>f</literal> GHC's optimiser -has produced. -</para></listitem> - -<listitem><para> -The <literal>INLINABLE</literal> pragma also works with <literal>SPECIALISE</literal>: -if you mark function <literal>f</literal> as <literal>INLINABLE</literal>, then -you can subsequently <literal>SPECIALISE</literal> in another module -(see <xref linkend="specialize-pragma"/>).</para></listitem> - -<listitem><para> -Unlike <literal>INLINE</literal>, it is OK to use -an <literal>INLINABLE</literal> pragma on a recursive function. -The principal reason do to so to allow later use of <literal>SPECIALISE</literal> -</para></listitem> -</itemizedlist> -</para> - - </sect3> - - <sect3 id="noinline-pragma"> - <title>NOINLINE pragma</title> - - <indexterm><primary>NOINLINE</primary></indexterm> - <indexterm><primary>NOTINLINE</primary></indexterm> - - <para>The <literal>NOINLINE</literal> pragma does exactly what - you'd expect: it stops the named function from being inlined - by the compiler. You shouldn't ever need to do this, unless - you're very cautious about code size.</para> - - <para><literal>NOTINLINE</literal> is a synonym for - <literal>NOINLINE</literal> (<literal>NOINLINE</literal> is - specified by Haskell 98 as the standard way to disable - inlining, so it should be used if you want your code to be - portable).</para> - </sect3> - - <sect3 id="conlike-pragma"> - <title>CONLIKE modifier</title> - <indexterm><primary>CONLIKE</primary></indexterm> - <para>An INLINE or NOINLINE pragma may have a CONLIKE modifier, - which affects matching in RULEs (only). See <xref linkend="conlike"/>. - </para> - </sect3> - - <sect3 id="phase-control"> - <title>Phase control</title> - - <para> Sometimes you want to control exactly when in GHC's - pipeline the INLINE pragma is switched on. Inlining happens - only during runs of the <emphasis>simplifier</emphasis>. Each - run of the simplifier has a different <emphasis>phase - number</emphasis>; the phase number decreases towards zero. - If you use <option>-dverbose-core2core</option> you'll see the - sequence of phase numbers for successive runs of the - simplifier. In an INLINE pragma you can optionally specify a - phase number, thus: - <itemizedlist> - <listitem> - <para>"<literal>INLINE[k] f</literal>" means: do not inline - <literal>f</literal> - until phase <literal>k</literal>, but from phase - <literal>k</literal> onwards be very keen to inline it. - </para></listitem> - <listitem> - <para>"<literal>INLINE[~k] f</literal>" means: be very keen to inline - <literal>f</literal> - until phase <literal>k</literal>, but from phase - <literal>k</literal> onwards do not inline it. - </para></listitem> - <listitem> - <para>"<literal>NOINLINE[k] f</literal>" means: do not inline - <literal>f</literal> - until phase <literal>k</literal>, but from phase - <literal>k</literal> onwards be willing to inline it (as if - there was no pragma). - </para></listitem> - <listitem> - <para>"<literal>NOINLINE[~k] f</literal>" means: be willing to inline - <literal>f</literal> - until phase <literal>k</literal>, but from phase - <literal>k</literal> onwards do not inline it. - </para></listitem> - </itemizedlist> -The same information is summarised here: -<programlisting> - -- Before phase 2 Phase 2 and later - {-# INLINE [2] f #-} -- No Yes - {-# INLINE [~2] f #-} -- Yes No - {-# NOINLINE [2] f #-} -- No Maybe - {-# NOINLINE [~2] f #-} -- Maybe No - - {-# INLINE f #-} -- Yes Yes - {-# NOINLINE f #-} -- No No -</programlisting> -By "Maybe" we mean that the usual heuristic inlining rules apply (if the -function body is small, or it is applied to interesting-looking arguments etc). -Another way to understand the semantics is this: -<itemizedlist> -<listitem><para>For both INLINE and NOINLINE, the phase number says -when inlining is allowed at all.</para></listitem> -<listitem><para>The INLINE pragma has the additional effect of making the -function body look small, so that when inlining is allowed it is very likely to -happen. -</para></listitem> -</itemizedlist> -</para> -<para>The same phase-numbering control is available for RULES - (<xref linkend="rewrite-rules"/>).</para> - </sect3> - </sect2> - - - <sect2 id="line-pragma"> - <title>LINE pragma</title> - - <indexterm><primary>LINE</primary><secondary>pragma</secondary></indexterm> - <indexterm><primary>pragma</primary><secondary>LINE</secondary></indexterm> - <para>This pragma is similar to C's <literal>#line</literal> - pragma, and is mainly for use in automatically generated Haskell - code. It lets you specify the line number and filename of the - original code; for example</para> - -<programlisting>{-# LINE 42 "Foo.vhs" #-}</programlisting> - - <para>if you'd generated the current file from something called - <filename>Foo.vhs</filename> and this line corresponds to line - 42 in the original. GHC will adjust its error messages to refer - to the line/file named in the <literal>LINE</literal> - pragma.</para> - - <para><literal>LINE</literal> pragmas generated from Template Haskell set - the file and line position for the duration of the splice and are limited - to the splice. Note that because Template Haskell splices abstract syntax, - the file positions are not automatically advanced.</para> - </sect2> - - <sect2 id="rules"> - <title>RULES pragma</title> - - <para>The RULES pragma lets you specify rewrite rules. It is - described in <xref linkend="rewrite-rules"/>.</para> - </sect2> - - <sect2 id="specialize-pragma"> - <title>SPECIALIZE pragma</title> - - <indexterm><primary>SPECIALIZE pragma</primary></indexterm> - <indexterm><primary>pragma, SPECIALIZE</primary></indexterm> - <indexterm><primary>overloading, death to</primary></indexterm> - - <para>(UK spelling also accepted.) For key overloaded - functions, you can create extra versions (NB: more code space) - specialised to particular types. Thus, if you have an - overloaded function:</para> - -<programlisting> - hammeredLookup :: Ord key => [(key, value)] -> key -> value -</programlisting> - - <para>If it is heavily used on lists with - <literal>Widget</literal> keys, you could specialise it as - follows:</para> - -<programlisting> - {-# SPECIALIZE hammeredLookup :: [(Widget, value)] -> Widget -> value #-} -</programlisting> - -<itemizedlist> -<listitem> - <para>A <literal>SPECIALIZE</literal> pragma for a function can - be put anywhere its type signature could be put. Moreover, you - can also <literal>SPECIALIZE</literal> an <emphasis>imported</emphasis> - function provided it was given an <literal>INLINABLE</literal> pragma at - its definition site (<xref linkend="inlinable-pragma"/>).</para> -</listitem> - -<listitem> - <para>A <literal>SPECIALIZE</literal> has the effect of generating - (a) a specialised version of the function and (b) a rewrite rule - (see <xref linkend="rewrite-rules"/>) that rewrites a call to - the un-specialised function into a call to the specialised one. - Moreover, given a <literal>SPECIALIZE</literal> pragma for a - function <literal>f</literal>, GHC will automatically create - specialisations for any type-class-overloaded functions called - by <literal>f</literal>, if they are in the same module as - the <literal>SPECIALIZE</literal> pragma, or if they are - <literal>INLINABLE</literal>; and so on, transitively.</para> -</listitem> - -<listitem> - <para>You can add phase control (<xref linkend="phase-control"/>) - to the RULE generated by a <literal>SPECIALIZE</literal> pragma, - just as you can if you write a RULE directly. For example: -<programlisting> - {-# SPECIALIZE [0] hammeredLookup :: [(Widget, value)] -> Widget -> value #-} -</programlisting> - generates a specialisation rule that only fires in Phase 0 (the final phase). - If you do not specify any phase control in the <literal>SPECIALIZE</literal> pragma, - the phase control is inherited from the inline pragma (if any) of the function. - For example: -<programlisting> - foo :: Num a => a -> a - foo = ...blah... - {-# NOINLINE [0] foo #-} - {-# SPECIALIZE foo :: Int -> Int #-} -</programlisting> - The <literal>NOINLINE</literal> pragma tells GHC not to inline <literal>foo</literal> - until Phase 0; and this property is inherited by the specialisation RULE, which will - therefore only fire in Phase 0.</para> - <para>The main reason for using phase control on specialisations is so that you can - write optimisation RULES that fire early in the compilation pipeline, and only - <emphasis>then</emphasis> specialise the calls to the function. If specialisation is - done too early, the optimisation rules might fail to fire. - </para> -</listitem> - -<listitem> - <para>The type in a SPECIALIZE pragma can be any type that is less - polymorphic than the type of the original function. In concrete terms, - if the original function is <literal>f</literal> then the pragma -<programlisting> - {-# SPECIALIZE f :: <type> #-} -</programlisting> - is valid if and only if the definition -<programlisting> - f_spec :: <type> - f_spec = f -</programlisting> - is valid. Here are some examples (where we only give the type signature - for the original function, not its code): -<programlisting> - f :: Eq a => a -> b -> b - {-# SPECIALISE f :: Int -> b -> b #-} - - g :: (Eq a, Ix b) => a -> b -> b - {-# SPECIALISE g :: (Eq a) => a -> Int -> Int #-} - - h :: Eq a => a -> a -> a - {-# SPECIALISE h :: (Eq a) => [a] -> [a] -> [a] #-} -</programlisting> -The last of these examples will generate a -RULE with a somewhat-complex left-hand side (try it yourself), so it might not fire very -well. If you use this kind of specialisation, let us know how well it works. -</para> -</listitem> -</itemizedlist> - - <sect3 id="specialize-inline"> - <title>SPECIALIZE INLINE</title> - -<para>A <literal>SPECIALIZE</literal> pragma can optionally be followed with a -<literal>INLINE</literal> or <literal>NOINLINE</literal> pragma, optionally -followed by a phase, as described in <xref linkend="inline-noinline-pragma"/>. -The <literal>INLINE</literal> pragma affects the specialised version of the -function (only), and applies even if the function is recursive. The motivating -example is this: -<programlisting> --- A GADT for arrays with type-indexed representation -data Arr e where - ArrInt :: !Int -> ByteArray# -> Arr Int - ArrPair :: !Int -> Arr e1 -> Arr e2 -> Arr (e1, e2) - -(!:) :: Arr e -> Int -> e -{-# SPECIALISE INLINE (!:) :: Arr Int -> Int -> Int #-} -{-# SPECIALISE INLINE (!:) :: Arr (a, b) -> Int -> (a, b) #-} -(ArrInt _ ba) !: (I# i) = I# (indexIntArray# ba i) -(ArrPair _ a1 a2) !: i = (a1 !: i, a2 !: i) -</programlisting> -Here, <literal>(!:)</literal> is a recursive function that indexes arrays -of type <literal>Arr e</literal>. Consider a call to <literal>(!:)</literal> -at type <literal>(Int,Int)</literal>. The second specialisation will fire, and -the specialised function will be inlined. It has two calls to -<literal>(!:)</literal>, -both at type <literal>Int</literal>. Both these calls fire the first -specialisation, whose body is also inlined. The result is a type-based -unrolling of the indexing function.</para> -<para>You can add explicit phase control (<xref linkend="phase-control"/>) -to <literal>SPECIALISE INLINE</literal> pragma, -just like on an <literal>INLINE</literal> pragma; if you do so, the same phase -is used for the rewrite rule and the INLINE control of the specialised function.</para> - -<para>Warning: you can make GHC diverge by using <literal>SPECIALISE INLINE</literal> -on an ordinarily-recursive function.</para> -</sect3> - -<sect3><title>SPECIALIZE for imported functions</title> - -<para> -Generally, you can only give a <literal>SPECIALIZE</literal> pragma -for a function defined in the same module. -However if a function <literal>f</literal> is given an <literal>INLINABLE</literal> -pragma at its definition site, then it can subsequently be specialised by -importing modules (see <xref linkend="inlinable-pragma"/>). -For example -<programlisting> -module Map( lookup, blah blah ) where - lookup :: Ord key => [(key,a)] -> key -> Maybe a - lookup = ... - {-# INLINABLE lookup #-} - -module Client where - import Map( lookup ) - - data T = T1 | T2 deriving( Eq, Ord ) - {-# SPECIALISE lookup :: [(T,a)] -> T -> Maybe a -</programlisting> -Here, <literal>lookup</literal> is declared <literal>INLINABLE</literal>, but -it cannot be specialised for type <literal>T</literal> at its definition site, -because that type does not exist yet. Instead a client module can define <literal>T</literal> -and then specialise <literal>lookup</literal> at that type. -</para> -<para> -Moreover, every module that imports <literal>Client</literal> (or imports a module -that imports <literal>Client</literal>, transitively) will "see", and make use of, -the specialised version of <literal>lookup</literal>. You don't need to put -a <literal>SPECIALIZE</literal> pragma in every module. -</para> -<para> -Moreover you often don't even need the <literal>SPECIALIZE</literal> pragma in the -first place. When compiling a module M, -GHC's optimiser (with -O) automatically considers each top-level -overloaded function declared in M, and specialises it -for the different types at which it is called in M. The optimiser -<emphasis>also</emphasis> considers each <emphasis>imported</emphasis> -<literal>INLINABLE</literal> overloaded function, and specialises it -for the different types at which it is called in M. -So in our example, it would be enough for <literal>lookup</literal> to -be called at type <literal>T</literal>: -<programlisting> -module Client where - import Map( lookup ) - - data T = T1 | T2 deriving( Eq, Ord ) - - findT1 :: [(T,a)] -> Maybe a - findT1 m = lookup m T1 -- A call of lookup at type T -</programlisting> -However, sometimes there are no such calls, in which case the -pragma can be useful. -</para> -</sect3> - -<sect3><title>Obsolete SPECIALIZE syntax</title> - - <para>Note: In earlier versions of GHC, it was possible to provide your own - specialised function for a given type: - -<programlisting> -{-# SPECIALIZE hammeredLookup :: [(Int, value)] -> Int -> value = intLookup #-} -</programlisting> - - This feature has been removed, as it is now subsumed by the - <literal>RULES</literal> pragma (see <xref linkend="rule-spec"/>).</para> -</sect3> - - </sect2> - -<sect2 id="specialize-instance-pragma"> -<title>SPECIALIZE instance pragma -</title> - -<para> -<indexterm><primary>SPECIALIZE pragma</primary></indexterm> -<indexterm><primary>overloading, death to</primary></indexterm> -Same idea, except for instance declarations. For example: - -<programlisting> -instance (Eq a) => Eq (Foo a) where { - {-# SPECIALIZE instance Eq (Foo [(Int, Bar)]) #-} - ... usual stuff ... - } -</programlisting> -The pragma must occur inside the <literal>where</literal> part -of the instance declaration. -</para> - -</sect2> - - <sect2 id="unpack-pragma"> - <title>UNPACK pragma</title> - - <indexterm><primary>UNPACK</primary></indexterm> - - <para>The <literal>UNPACK</literal> indicates to the compiler - that it should unpack the contents of a constructor field into - the constructor itself, removing a level of indirection. For - example:</para> - -<programlisting> -data T = T {-# UNPACK #-} !Float - {-# UNPACK #-} !Float -</programlisting> - - <para>will create a constructor <literal>T</literal> containing - two unboxed floats. This may not always be an optimisation: if - the <function>T</function> constructor is scrutinised and the - floats passed to a non-strict function for example, they will - have to be reboxed (this is done automatically by the - compiler).</para> - - <para>Unpacking constructor fields should only be used in - conjunction with <option>-O</option><footnote>in fact, UNPACK - has no effect without <option>-O</option>, for technical - reasons - (see <ulink url="http://ghc.haskell.org/trac/ghc/ticket/5252">tick - 5252</ulink>)</footnote>, in order to expose - unfoldings to the compiler so the reboxing can be removed as - often as possible. For example:</para> - -<programlisting> -f :: T -> Float -f (T f1 f2) = f1 + f2 -</programlisting> - - <para>The compiler will avoid reboxing <function>f1</function> - and <function>f2</function> by inlining <function>+</function> - on floats, but only when <option>-O</option> is on.</para> - - <para>Any single-constructor data is eligible for unpacking; for - example</para> - -<programlisting> -data T = T {-# UNPACK #-} !(Int,Int) -</programlisting> - - <para>will store the two <literal>Int</literal>s directly in the - <function>T</function> constructor, by flattening the pair. - Multi-level unpacking is also supported: - -<programlisting> -data T = T {-# UNPACK #-} !S -data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int -</programlisting> - - will store two unboxed <literal>Int#</literal>s - directly in the <function>T</function> constructor. The - unpacker can see through newtypes, too.</para> - - <para>See also the <option>-funbox-strict-fields</option> flag, - which essentially has the effect of adding - <literal>{-# UNPACK #-}</literal> to every strict - constructor field.</para> - </sect2> - - <sect2 id="nounpack-pragma"> - <title>NOUNPACK pragma</title> - - <indexterm><primary>NOUNPACK</primary></indexterm> - - <para>The <literal>NOUNPACK</literal> pragma indicates to the compiler - that it should not unpack the contents of a constructor field. - Example: - </para> -<programlisting> -data T = T {-# NOUNPACK #-} !(Int,Int) -</programlisting> - <para> - Even with the flags - <option>-funbox-strict-fields</option> and <option>-O</option>, - the field of the constructor <function>T</function> is not - unpacked. - </para> - </sect2> - - <sect2 id="source-pragma"> - <title>SOURCE pragma</title> - - <indexterm><primary>SOURCE</primary></indexterm> - <para>The <literal>{-# SOURCE #-}</literal> pragma is used only in <literal>import</literal> declarations, - to break a module loop. It is described in detail in <xref linkend="mutual-recursion"/>. - </para> -</sect2> - -<sect2 id="overlap-pragma"> -<title>OVERLAPPING, OVERLAPPABLE, OVERLAPS, and INCOHERENT pragmas</title> -<para> -The pragmas - <literal>OVERLAPPING</literal>, - <literal>OVERLAPPABLE</literal>, - <literal>OVERLAPS</literal>, - <literal>INCOHERENT</literal> are used to specify the overlap -behavior for individual instances, as described in Section -<xref linkend="instance-overlap"/>. The pragmas are written immediately -after the <literal>instance</literal> keyword, like this: -</para> -<programlisting> -instance {-# OVERLAPPING #-} C t where ... -</programlisting> -</sect2> - -</sect1> - -<!-- ======================= REWRITE RULES ======================== --> - -<sect1 id="rewrite-rules"> -<title>Rewrite rules - -<indexterm><primary>RULES pragma</primary></indexterm> -<indexterm><primary>pragma, RULES</primary></indexterm> -<indexterm><primary>rewrite rules</primary></indexterm></title> - -<para> -The programmer can specify rewrite rules as part of the source program -(in a pragma). -Here is an example: - -<programlisting> - {-# RULES - "map/map" forall f g xs. map f (map g xs) = map (f.g) xs - #-} -</programlisting> -</para> -<para> -Use the debug flag <option>-ddump-simpl-stats</option> to see what rules fired. -If you need more information, then <option>-ddump-rule-firings</option> shows you -each individual rule firing and <option>-ddump-rule-rewrites</option> also shows what the code looks like before and after the rewrite. -</para> - -<sect2> -<title>Syntax</title> - -<para> -From a syntactic point of view: - -<itemizedlist> - -<listitem> -<para> - There may be zero or more rules in a <literal>RULES</literal> pragma, separated by semicolons (which - may be generated by the layout rule). -</para> -</listitem> - -<listitem> -<para> -The layout rule applies in a pragma. -Currently no new indentation level -is set, so if you put several rules in single RULES pragma and wish to use layout to separate them, -you must lay out the starting in the same column as the enclosing definitions. -<programlisting> - {-# RULES - "map/map" forall f g xs. map f (map g xs) = map (f.g) xs - "map/append" forall f xs ys. map f (xs ++ ys) = map f xs ++ map f ys - #-} -</programlisting> -Furthermore, the closing <literal>#-}</literal> -should start in a column to the right of the opening <literal>{-#</literal>. -</para> -</listitem> - -<listitem> -<para> - Each rule has a name, enclosed in double quotes. The name itself has -no significance at all. It is only used when reporting how many times the rule fired. -</para> -</listitem> - -<listitem> -<para> -A rule may optionally have a phase-control number (see <xref linkend="phase-control"/>), -immediately after the name of the rule. Thus: -<programlisting> - {-# RULES - "map/map" [2] forall f g xs. map f (map g xs) = map (f.g) xs - #-} -</programlisting> -The "[2]" means that the rule is active in Phase 2 and subsequent phases. The inverse -notation "[~2]" is also accepted, meaning that the rule is active up to, but not including, -Phase 2. -</para> -<para> -Rules support the special phase-control notation "[~]", which means the rule is never active. -This feature supports plugins (see <xref linkend="compiler-plugins"/>), by making it possible -to define a RULE that is never run by GHC, but is nevertheless parsed, typechecked etc, so that -it is available to the plugin. -</para> -</listitem> - - - -<listitem> -<para> - Each variable mentioned in a rule must either be in scope (e.g. <function>map</function>), -or bound by the <literal>forall</literal> (e.g. <function>f</function>, <function>g</function>, <function>xs</function>). The variables bound by -the <literal>forall</literal> are called the <emphasis>pattern</emphasis> variables. They are separated -by spaces, just like in a type <literal>forall</literal>. -</para> -</listitem> -<listitem> - -<para> - A pattern variable may optionally have a type signature. -If the type of the pattern variable is polymorphic, it <emphasis>must</emphasis> have a type signature. -For example, here is the <literal>foldr/build</literal> rule: - -<programlisting> -"fold/build" forall k z (g::forall b. (a->b->b) -> b -> b) . - foldr k z (build g) = g k z -</programlisting> - -Since <function>g</function> has a polymorphic type, it must have a type signature. - -</para> -</listitem> -<listitem> - -<para> -The left hand side of a rule must consist of a top-level variable applied -to arbitrary expressions. For example, this is <emphasis>not</emphasis> OK: - -<programlisting> -"wrong1" forall e1 e2. case True of { True -> e1; False -> e2 } = e1 -"wrong2" forall f. f True = True -</programlisting> - -In <literal>"wrong1"</literal>, the LHS is not an application; in <literal>"wrong2"</literal>, the LHS has a pattern variable -in the head. -</para> -</listitem> -<listitem> - -<para> - A rule does not need to be in the same module as (any of) the -variables it mentions, though of course they need to be in scope. -</para> -</listitem> -<listitem> - -<para> - All rules are implicitly exported from the module, and are therefore -in force in any module that imports the module that defined the rule, directly -or indirectly. (That is, if A imports B, which imports C, then C's rules are -in force when compiling A.) The situation is very similar to that for instance -declarations. -</para> -</listitem> - -<listitem> - -<para> -Inside a RULE "<literal>forall</literal>" is treated as a keyword, regardless of -any other flag settings. Furthermore, inside a RULE, the language extension -<option>-XScopedTypeVariables</option> is automatically enabled; see -<xref linkend="scoped-type-variables"/>. -</para> -</listitem> -<listitem> - -<para> -Like other pragmas, RULE pragmas are always checked for scope errors, and -are typechecked. Typechecking means that the LHS and RHS of a rule are typechecked, -and must have the same type. However, rules are only <emphasis>enabled</emphasis> -if the <option>-fenable-rewrite-rules</option> flag is -on (see <xref linkend="rule-semantics"/>). -</para> -</listitem> -</itemizedlist> - -</para> - -</sect2> - -<sect2 id="rule-semantics"> -<title>Semantics</title> - -<para> -From a semantic point of view: - -<itemizedlist> -<listitem> -<para> -Rules are enabled (that is, used during optimisation) -by the <option>-fenable-rewrite-rules</option> flag. -This flag is implied by <option>-O</option>, and may be switched -off (as usual) by <option>-fno-enable-rewrite-rules</option>. -(NB: enabling <option>-fenable-rewrite-rules</option> without <option>-O</option> -may not do what you expect, though, because without <option>-O</option> GHC -ignores all optimisation information in interface files; -see <option>-fignore-interface-pragmas</option>, <xref linkend="options-f"/>.) -Note that <option>-fenable-rewrite-rules</option> is an <emphasis>optimisation</emphasis> flag, and -has no effect on parsing or typechecking. -</para> -</listitem> - -<listitem> -<para> - Rules are regarded as left-to-right rewrite rules. -When GHC finds an expression that is a substitution instance of the LHS -of a rule, it replaces the expression by the (appropriately-substituted) RHS. -By "a substitution instance" we mean that the LHS can be made equal to the -expression by substituting for the pattern variables. - -</para> -</listitem> -<listitem> - -<para> - GHC makes absolutely no attempt to verify that the LHS and RHS -of a rule have the same meaning. That is undecidable in general, and -infeasible in most interesting cases. The responsibility is entirely the programmer's! - -</para> -</listitem> -<listitem> - -<para> - GHC makes no attempt to make sure that the rules are confluent or -terminating. For example: - -<programlisting> - "loop" forall x y. f x y = f y x -</programlisting> - -This rule will cause the compiler to go into an infinite loop. - -</para> -</listitem> -<listitem> - -<para> - If more than one rule matches a call, GHC will choose one arbitrarily to apply. - -</para> -</listitem> -<listitem> -<para> - GHC currently uses a very simple, syntactic, matching algorithm -for matching a rule LHS with an expression. It seeks a substitution -which makes the LHS and expression syntactically equal modulo alpha -conversion. The pattern (rule), but not the expression, is eta-expanded if -necessary. (Eta-expanding the expression can lead to laziness bugs.) -But not beta conversion (that's called higher-order matching). -</para> - -<para> -Matching is carried out on GHC's intermediate language, which includes -type abstractions and applications. So a rule only matches if the -types match too. See <xref linkend="rule-spec"/> below. -</para> -</listitem> -<listitem> - -<para> - GHC keeps trying to apply the rules as it optimises the program. -For example, consider: - -<programlisting> - let s = map f - t = map g - in - s (t xs) -</programlisting> - -The expression <literal>s (t xs)</literal> does not match the rule <literal>"map/map"</literal>, but GHC -will substitute for <varname>s</varname> and <varname>t</varname>, giving an expression which does match. -If <varname>s</varname> or <varname>t</varname> was (a) used more than once, and (b) large or a redex, then it would -not be substituted, and the rule would not fire. - -</para> -</listitem> -</itemizedlist> - -</para> - -</sect2> - -<sect2 id="rules-inline"> -<title>How rules interact with INLINE/NOINLINE pragmas</title> - -<para> -Ordinary inlining happens at the same time as rule rewriting, which may lead to unexpected -results. Consider this (artificial) example -<programlisting> -f x = x -g y = f y -h z = g True - -{-# RULES "f" f True = False #-} -</programlisting> -Since <literal>f</literal>'s right-hand side is small, it is inlined into <literal>g</literal>, -to give -<programlisting> -g y = y -</programlisting> -Now <literal>g</literal> is inlined into <literal>h</literal>, but <literal>f</literal>'s RULE has -no chance to fire. -If instead GHC had first inlined <literal>g</literal> into <literal>h</literal> then there -would have been a better chance that <literal>f</literal>'s RULE might fire. -</para> -<para> -The way to get predictable behaviour is to use a NOINLINE -pragma, or an INLINE[<replaceable>phase</replaceable>] pragma, on <literal>f</literal>, to ensure -that it is not inlined until its RULEs have had a chance to fire. -The warning flag <option>-fwarn-inline-rule-shadowing</option> (see <xref linkend="options-sanity"/>) -warns about this situation. -</para> -</sect2> - -<sect2 id="conlike"> -<title>How rules interact with CONLIKE pragmas</title> - -<para> -GHC is very cautious about duplicating work. For example, consider -<programlisting> -f k z xs = let xs = build g - in ...(foldr k z xs)...sum xs... -{-# RULES "foldr/build" forall k z g. foldr k z (build g) = g k z #-} -</programlisting> -Since <literal>xs</literal> is used twice, GHC does not fire the foldr/build rule. Rightly -so, because it might take a lot of work to compute <literal>xs</literal>, which would be -duplicated if the rule fired. -</para> -<para> -Sometimes, however, this approach is over-cautious, and we <emphasis>do</emphasis> want the -rule to fire, even though doing so would duplicate redex. There is no way that GHC can work out -when this is a good idea, so we provide the CONLIKE pragma to declare it, thus: -<programlisting> -{-# INLINE CONLIKE [1] f #-} -f x = <replaceable>blah</replaceable> -</programlisting> -CONLIKE is a modifier to an INLINE or NOINLINE pragma. It specifies that an application -of f to one argument (in general, the number of arguments to the left of the '=' sign) -should be considered cheap enough to duplicate, if such a duplication would make rule -fire. (The name "CONLIKE" is short for "constructor-like", because constructors certainly -have such a property.) -The CONLIKE pragma is a modifier to INLINE/NOINLINE because it really only makes sense to match -<literal>f</literal> on the LHS of a rule if you are sure that <literal>f</literal> is -not going to be inlined before the rule has a chance to fire. -</para> -</sect2> - -<sect2 id="rules-class-methods"> -<title>How rules interact with class methods</title> - -<para> -Giving a RULE for a class method is a bad idea: -<programlisting> -class C a where - op :: a -> a -> a - -instance C Bool where - op x y = ...rhs for op at Bool... - -{-# RULES "f" op True y = False #-} -</programlisting> -In this -example, <literal>op</literal> is not an ordinary top-level function; -it is a class method. GHC rapidly rewrites any occurrences of -<literal>op</literal>-used-at-type-Bool -to a specialised function, say <literal>opBool</literal>, where -<programlisting> -opBool :: Bool -> Bool -> Bool -opBool x y = ..rhs for op at Bool... -</programlisting> -So the RULE never has a chance to fire, for just the same reasons as in <xref linkend="rules-inline"/>. -</para> -<para> -The solution is to define the instance-specific function yourself, with a pragma to prevent -it being inlined too early, and give a RULE for it: -<programlisting> -instance C Bool where - op x y = opBool - -opBool :: Bool -> Bool -> Bool -{-# NOINLINE [1] opBool #-} -opBool x y = ..rhs for op at Bool... - -{-# RULES "f" opBool True y = False #-} -</programlisting> -If you want a RULE that truly applies to the overloaded class method, the only way to -do it is like this: -<programlisting> -class C a where - op_c :: a -> a -> a - -op :: C a => a -> a -> a -{-# NOINLINE [1] op #-} -op = op_c - -{-# RULES "reassociate" op (op x y) z = op x (op y z) #-} -</programlisting> -Now the inlining of <literal>op</literal> is delayed until the rule has a chance to fire. -The down-side is that instance declarations must define <literal>op_c</literal>, but -all other uses should go via <literal>op</literal>. -</para> -</sect2> -<sect2> -<title>List fusion</title> - -<para> -The RULES mechanism is used to implement fusion (deforestation) of common list functions. -If a "good consumer" consumes an intermediate list constructed by a "good producer", the -intermediate list should be eliminated entirely. -</para> - -<para> -The following are good producers: - -<itemizedlist> -<listitem> - -<para> - List comprehensions -</para> -</listitem> -<listitem> - -<para> - Enumerations of <literal>Int</literal>, <literal>Integer</literal> and <literal>Char</literal> (e.g. <literal>['a'..'z']</literal>). -</para> -</listitem> -<listitem> - -<para> - Explicit lists (e.g. <literal>[True, False]</literal>) -</para> -</listitem> -<listitem> - -<para> - The cons constructor (e.g <literal>3:4:[]</literal>) -</para> -</listitem> -<listitem> - -<para> - <function>++</function> -</para> -</listitem> - -<listitem> -<para> - <function>map</function> -</para> -</listitem> - -<listitem> -<para> -<function>take</function>, <function>filter</function> -</para> -</listitem> -<listitem> - -<para> - <function>iterate</function>, <function>repeat</function> -</para> -</listitem> -<listitem> - -<para> - <function>zip</function>, <function>zipWith</function> -</para> -</listitem> - -</itemizedlist> - -</para> - -<para> -The following are good consumers: - -<itemizedlist> -<listitem> - -<para> - List comprehensions -</para> -</listitem> -<listitem> - -<para> - <function>array</function> (on its second argument) -</para> -</listitem> -<listitem> - -<para> - <function>++</function> (on its first argument) -</para> -</listitem> - -<listitem> -<para> - <function>foldr</function> -</para> -</listitem> - -<listitem> -<para> - <function>map</function> -</para> -</listitem> -<listitem> - -<para> -<function>take</function>, <function>filter</function> -</para> -</listitem> -<listitem> - -<para> - <function>concat</function> -</para> -</listitem> -<listitem> - -<para> - <function>unzip</function>, <function>unzip2</function>, <function>unzip3</function>, <function>unzip4</function> -</para> -</listitem> -<listitem> - -<para> - <function>zip</function>, <function>zipWith</function> (but on one argument only; if both are good producers, <function>zip</function> -will fuse with one but not the other) -</para> -</listitem> -<listitem> - -<para> - <function>partition</function> -</para> -</listitem> -<listitem> - -<para> - <function>head</function> -</para> -</listitem> -<listitem> - -<para> - <function>and</function>, <function>or</function>, <function>any</function>, <function>all</function> -</para> -</listitem> -<listitem> - -<para> - <function>sequence_</function> -</para> -</listitem> -<listitem> - -<para> - <function>msum</function> -</para> -</listitem> - -</itemizedlist> - -</para> - - <para> -So, for example, the following should generate no intermediate lists: - -<programlisting> -array (1,10) [(i,i*i) | i <- map (+ 1) [0..9]] -</programlisting> - -</para> - -<para> -This list could readily be extended; if there are Prelude functions that you use -a lot which are not included, please tell us. -</para> - -<para> -If you want to write your own good consumers or producers, look at the -Prelude definitions of the above functions to see how to do so. -</para> - -</sect2> - -<sect2 id="rule-spec"> -<title>Specialisation -</title> - -<para> -Rewrite rules can be used to get the same effect as a feature -present in earlier versions of GHC. -For example, suppose that: - -<programlisting> -genericLookup :: Ord a => Table a b -> a -> b -intLookup :: Table Int b -> Int -> b -</programlisting> - -where <function>intLookup</function> is an implementation of -<function>genericLookup</function> that works very fast for -keys of type <literal>Int</literal>. You might wish -to tell GHC to use <function>intLookup</function> instead of -<function>genericLookup</function> whenever the latter was called with -type <literal>Table Int b -> Int -> b</literal>. -It used to be possible to write - -<programlisting> -{-# SPECIALIZE genericLookup :: Table Int b -> Int -> b = intLookup #-} -</programlisting> - -This feature is no longer in GHC, but rewrite rules let you do the same thing: - -<programlisting> -{-# RULES "genericLookup/Int" genericLookup = intLookup #-} -</programlisting> - -This slightly odd-looking rule instructs GHC to replace -<function>genericLookup</function> by <function>intLookup</function> -<emphasis>whenever the types match</emphasis>. -What is more, this rule does not need to be in the same -file as <function>genericLookup</function>, unlike the -<literal>SPECIALIZE</literal> pragmas which currently do (so that they -have an original definition available to specialise). -</para> - -<para>It is <emphasis>Your Responsibility</emphasis> to make sure that -<function>intLookup</function> really behaves as a specialised version -of <function>genericLookup</function>!!!</para> - -<para>An example in which using <literal>RULES</literal> for -specialisation will Win Big: - -<programlisting> -toDouble :: Real a => a -> Double -toDouble = fromRational . toRational - -{-# RULES "toDouble/Int" toDouble = i2d #-} -i2d (I# i) = D# (int2Double# i) -- uses Glasgow prim-op directly -</programlisting> - -The <function>i2d</function> function is virtually one machine -instruction; the default conversion—via an intermediate -<literal>Rational</literal>—is obscenely expensive by -comparison. -</para> - -</sect2> - -<sect2 id="controlling-rules"> -<title>Controlling what's going on in rewrite rules</title> - -<para> - -<itemizedlist> -<listitem> - -<para> -Use <option>-ddump-rules</option> to see the rules that are defined -<emphasis>in this module</emphasis>. -This includes rules generated by the specialisation pass, but excludes -rules imported from other modules. -</para> -</listitem> - -<listitem> -<para> - Use <option>-ddump-simpl-stats</option> to see what rules are being fired. -If you add <option>-dppr-debug</option> you get a more detailed listing. -</para> -</listitem> - -<listitem> -<para> - Use <option>-ddump-rule-firings</option> or <option>-ddump-rule-rewrites</option> -to see in great detail what rules are being fired. -If you add <option>-dppr-debug</option> you get a still more detailed listing. -</para> -</listitem> - -<listitem> -<para> - The definition of (say) <function>build</function> in <filename>GHC/Base.lhs</filename> looks like this: - -<programlisting> - build :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a] - {-# INLINE build #-} - build g = g (:) [] -</programlisting> - -Notice the <literal>INLINE</literal>! That prevents <literal>(:)</literal> from being inlined when compiling -<literal>PrelBase</literal>, so that an importing module will “see” the <literal>(:)</literal>, and can -match it on the LHS of a rule. <literal>INLINE</literal> prevents any inlining happening -in the RHS of the <literal>INLINE</literal> thing. I regret the delicacy of this. - -</para> -</listitem> -<listitem> - -<para> - In <filename>libraries/base/GHC/Base.lhs</filename> look at the rules for <function>map</function> to -see how to write rules that will do fusion and yet give an efficient -program even if fusion doesn't happen. More rules in <filename>GHC/List.lhs</filename>. -</para> -</listitem> - -</itemizedlist> - -</para> - -</sect2> - -</sect1> - -<sect1 id="special-ids"> -<title>Special built-in functions</title> -<para>GHC has a few built-in functions with special behaviour. -In particular: -<itemizedlist> -<listitem><para> -<ulink url="&libraryBaseLocation;/GHC-Exts.html#v%3Ainline"><literal>inline</literal></ulink> -allows control over inlining on a per-call-site basis. -</para></listitem> -<listitem><para> -<ulink url="&libraryBaseLocation;/GHC-Exts.html#v%3Alazy"><literal>lazy</literal></ulink> -restrains the strictness analyser. -</para></listitem> -<listitem><para> -<ulink url="&libraryBaseLocation;/GHC-Exts.html#v%3AoneShot"><literal>oneShot</literal></ulink> -gives a hint to the compiler about how often a function is being called. -</para></listitem> -</itemizedlist> -</para> -</sect1> - - -<sect1 id="generic-classes"> -<title>Generic classes</title> - -<para> -GHC used to have an implementation of generic classes as defined in the paper -"Derivable type classes", Ralf Hinze and Simon Peyton Jones, Haskell Workshop, -Montreal Sept 2000, pp94-105. These have been removed and replaced by the more -general <link linkend="generic-programming">support for generic programming</link>. -</para> - -</sect1> - - -<sect1 id="generic-programming"> -<title>Generic programming</title> - -<para> -Using a combination of <option>-XDeriveGeneric</option> -(<xref linkend="deriving-typeable"/>), -<option>-XDefaultSignatures</option> (<xref linkend="class-default-signatures"/>), -and <option>-XDeriveAnyClass</option> (<xref linkend="derive-any-class"/>), -you can easily do datatype-generic -programming using the <literal>GHC.Generics</literal> framework. This section -gives a very brief overview of how to do it. -</para> - -<para> -Generic programming support in GHC allows defining classes with methods that -do not need a user specification when instantiating: the method body is -automatically derived by GHC. This is similar to what happens for standard -classes such as <literal>Read</literal> and <literal>Show</literal>, for -instance, but now for user-defined classes. -</para> - -<sect2> -<title>Deriving representations</title> - -<para> -The first thing we need is generic representations. The -<literal>GHC.Generics</literal> module defines a couple of primitive types -that are used to represent Haskell datatypes: - -<programlisting> --- | Unit: used for constructors without arguments -data U1 p = U1 - --- | Constants, additional parameters and recursion of kind * -newtype K1 i c p = K1 { unK1 :: c } - --- | Meta-information (constructor names, etc.) -newtype M1 i c f p = M1 { unM1 :: f p } - --- | Sums: encode choice between constructors -infixr 5 :+: -data (:+:) f g p = L1 (f p) | R1 (g p) - --- | Products: encode multiple arguments to constructors -infixr 6 :*: -data (:*:) f g p = f p :*: g p -</programlisting> -</para> - -<para> -The <literal>Generic</literal> and <literal>Generic1</literal> classes mediate -between user-defined datatypes and their internal representation as a -sum-of-products: - -<programlisting> -class Generic a where - -- Encode the representation of a user datatype - type Rep a :: * -> * - -- Convert from the datatype to its representation - from :: a -> (Rep a) x - -- Convert from the representation to the datatype - to :: (Rep a) x -> a - -class Generic1 f where - type Rep1 f :: * -> * - - from1 :: f a -> Rep1 f a - to1 :: Rep1 f a -> f a -</programlisting> - -<literal>Generic1</literal> is used for functions that can only be defined over -type containers, such as <literal>map</literal>. -Instances of these classes can be derived by GHC with the -<option>-XDeriveGeneric</option> (<xref linkend="deriving-typeable"/>), and are -necessary to be able to define generic instances automatically. -</para> - -<para> -For example, a user-defined datatype of trees <literal>data UserTree a = Node a -(UserTree a) (UserTree a) | Leaf</literal> gets the following representation: - -<programlisting> -instance Generic (UserTree a) where - -- Representation type - type Rep (UserTree a) = - M1 D D1UserTree ( - M1 C C1_0UserTree ( - M1 S NoSelector (K1 R a) - :*: M1 S NoSelector (K1 R (UserTree a)) - :*: M1 S NoSelector (K1 R (UserTree a))) - :+: M1 C C1_1UserTree U1) - - -- Conversion functions - from (Node x l r) = M1 (L1 (M1 (M1 (K1 x) :*: M1 (K1 l) :*: M1 (K1 r)))) - from Leaf = M1 (R1 (M1 U1)) - to (M1 (L1 (M1 (M1 (K1 x) :*: M1 (K1 l) :*: M1 (K1 r))))) = Node x l r - to (M1 (R1 (M1 U1))) = Leaf - --- Meta-information -data D1UserTree -data C1_0UserTree -data C1_1UserTree - -instance Datatype D1UserTree where - datatypeName _ = "UserTree" - moduleName _ = "Main" - packageName _ = "main" - -instance Constructor C1_0UserTree where - conName _ = "Node" - -instance Constructor C1_1UserTree where - conName _ = "Leaf" -</programlisting> - -This representation is generated automatically if a -<literal>deriving Generic</literal> clause is attached to the datatype. -<link linkend="stand-alone-deriving">Standalone deriving</link> can also be -used. -</para> - -</sect2> - -<sect2> -<title>Writing generic functions</title> - -<para> -A generic function is defined by creating a class and giving instances for -each of the representation types of <literal>GHC.Generics</literal>. As an -example we show generic serialization: -<programlisting> -data Bin = O | I - -class GSerialize f where - gput :: f a -> [Bin] - -instance GSerialize U1 where - gput U1 = [] - -instance (GSerialize a, GSerialize b) => GSerialize (a :*: b) where - gput (x :*: y) = gput x ++ gput y - -instance (GSerialize a, GSerialize b) => GSerialize (a :+: b) where - gput (L1 x) = O : gput x - gput (R1 x) = I : gput x - -instance (GSerialize a) => GSerialize (M1 i c a) where - gput (M1 x) = gput x - -instance (Serialize a) => GSerialize (K1 i a) where - gput (K1 x) = put x -</programlisting> - -Typically this class will not be exported, as it only makes sense to have -instances for the representation types. -</para> -</sect2> - -<sect2> -<title>Generic defaults</title> - -<para> -The only thing left to do now is to define a "front-end" class, which is -exposed to the user: -<programlisting> -class Serialize a where - put :: a -> [Bin] - - default put :: (Generic a, GSerialize (Rep a)) => a -> [Bit] - put = gput . from -</programlisting> -Here we use a <link linkend="class-default-signatures">default signature</link> -to specify that the user does not have to provide an implementation for -<literal>put</literal>, as long as there is a <literal>Generic</literal> -instance for the type to instantiate. For the <literal>UserTree</literal> type, -for instance, the user can just write: - -<programlisting> -instance (Serialize a) => Serialize (UserTree a) -</programlisting> - -The default method for <literal>put</literal> is then used, corresponding to the -generic implementation of serialization. - -If you are using <option>-XDeriveAnyClass</option>, the same instance is -generated by simply attaching a <literal>deriving Serialize</literal> clause -to the <literal>UserTree</literal> datatype declaration. - -For more examples of generic functions please refer to the -<ulink url="http://hackage.haskell.org/package/generic-deriving">generic-deriving</ulink> -package on Hackage. -</para> -</sect2> - -<sect2> -<title>More information</title> - -<para> -For more details please refer to the -<ulink url="http://www.haskell.org/haskellwiki/GHC.Generics">HaskellWiki -page</ulink> or the original paper: -</para> - -<itemizedlist> -<listitem> -<para> -Jose Pedro Magalhaes, Atze Dijkstra, Johan Jeuring, and Andres Loeh. -<ulink url="http://dreixel.net/research/pdf/gdmh.pdf"> - A generic deriving mechanism for Haskell</ulink>. -<citetitle>Proceedings of the third ACM Haskell symposium on Haskell</citetitle> -(Haskell'2010), pp. 37-48, ACM, 2010. -</para> -</listitem> -</itemizedlist> - -</sect2> - -</sect1> - -<sect1 id="roles"> -<title>Roles -<indexterm><primary>roles</primary></indexterm> -</title> - -<para> -Using <option>-XGeneralizedNewtypeDeriving</option> (<xref -linkend="generalized-newtype-deriving" />), a programmer can take existing -instances of classes and "lift" these into instances of that class for a -newtype. However, this is not always safe. For example, consider the following: -</para> - -<programlisting> - newtype Age = MkAge { unAge :: Int } - - type family Inspect x - type instance Inspect Age = Int - type instance Inspect Int = Bool - - class BadIdea a where - bad :: a -> Inspect a - - instance BadIdea Int where - bad = (> 0) - - deriving instance BadIdea Age -- not allowed! -</programlisting> - -<para> -If the derived instance were allowed, what would the type of its method -<literal>bad</literal> be? It would seem to be <literal>Age -> Inspect -Age</literal>, which is equivalent to <literal>Age -> Int</literal>, according -to the type family <literal>Inspect</literal>. Yet, if we simply adapt the -implementation from the instance for <literal>Int</literal>, the implementation -for <literal>bad</literal> produces a <literal>Bool</literal>, and we have trouble. -</para> - -<para> -The way to identify such situations is to have <emphasis>roles</emphasis> assigned -to type variables of datatypes, classes, and type synonyms.</para> - -<para> -Roles as implemented in GHC are a from a simplified version of the work -described in <ulink -url="http://www.seas.upenn.edu/~sweirich/papers/popl163af-weirich.pdf">Generative -type abstraction and type-level computation</ulink>, published at POPL 2011.</para> - -<sect2 id="nominal-representational-and-phantom"> -<title>Nominal, Representational, and Phantom</title> - -<para>The goal of the roles system is to track when two types have the same -underlying representation. In the example above, <literal>Age</literal> and -<literal>Int</literal> have the same representation. But, the corresponding -instances of <literal>BadIdea</literal> would <emphasis>not</emphasis> have -the same representation, because the types of the implementations of -<literal>bad</literal> would be different.</para> - -<para>Suppose we have two uses of a type constructor, each applied to the same -parameters except for one difference. (For example, <literal>T Age Bool -c</literal> and <literal>T Int Bool c</literal> for some type -<literal>T</literal>.) The role of a type parameter says what we need to -know about the two differing type arguments in order to know that the two -outer types have the same representation (in the example, what must be true -about <literal>Age</literal> and <literal>Int</literal> in order to show that -<literal>T Age Bool c</literal> has the same representation as <literal> -T Int Bool c</literal>).</para> - -<para>GHC supports three different roles for type parameters: nominal, -representational, and phantom. If a type parameter has a nominal role, then -the two types that differ must not actually differ at all: they must be -identical (after type family reduction). If a type parameter has a -representational role, then the two types must have the same representation. -(If <literal>T</literal>'s first parameter's role is representational, then -<literal>T Age Bool c</literal> and <literal>T Int Bool c</literal> would have -the same representation, because <literal>Age</literal> and -<literal>Int</literal> have the same representation.) If a type parameter has -a phantom role, then we need no further information.</para> - -<para>Here are some examples:</para> - -<programlisting> - data Simple a = MkSimple a -- a has role representational - - type family F - type instance F Int = Bool - type instance F Age = Char - - data Complex a = MkComplex (F a) -- a has role nominal - - data Phant a = MkPhant Bool -- a has role phantom -</programlisting> - -<para>The type <literal>Simple</literal> has its parameter at role -representational, which is generally the most common case. <literal>Simple -Age</literal> would have the same representation as <literal>Simple -Int</literal>. The type <literal>Complex</literal>, on the other hand, has its -parameter at role nominal, because <literal>Simple Age</literal> and -<literal>Simple Int</literal> are <emphasis>not</emphasis> the same. Lastly, -<literal>Phant Age</literal> and <literal>Phant Bool</literal> have the same -representation, even though <literal>Age</literal> and <literal>Bool</literal> -are unrelated.</para> - -</sect2> - -<sect2 id="role-inference"> -<title>Role inference</title> - -<para> -What role should a given type parameter should have? GHC performs role -inference to determine the correct role for every parameter. It starts with a -few base facts: <literal>(->)</literal> has two representational parameters; -<literal>(~)</literal> has two nominal parameters; all type families' -parameters are nominal; and all GADT-like parameters are nominal. Then, these -facts are propagated to all places where these types are used. The default -role for datatypes and synonyms is phantom; the default role for classes is -nominal. Thus, for datatypes and synonyms, any parameters unused in the -right-hand side (or used only in other types in phantom positions) will be -phantom. Whenever a parameter is used in a representational position (that is, -used as a type argument to a constructor whose corresponding variable is at -role representational), we raise its role from phantom to representational. -Similarly, when a parameter is used in a nominal position, its role is -upgraded to nominal. We never downgrade a role from nominal to phantom or -representational, or from representational to phantom. In this way, we infer -the most-general role for each parameter. -</para> - -<para> -Classes have their roles default to nominal to promote coherence of class -instances. If a <literal>C Int</literal> were stored in a datatype, it would -be quite bad if that were somehow changed into a <literal>C Age</literal> -somewhere, especially if another <literal>C Age</literal> had been declared! -</para> - -<para>There is one particularly tricky case that should be explained:</para> - -<programlisting> - data Tricky a b = MkTricky (a b) -</programlisting> - -<para>What should <literal>Tricky</literal>'s roles be? At first blush, it -would seem that both <literal>a</literal> and <literal>b</literal> should be -at role representational, since both are used in the right-hand side and -neither is involved in a type family. However, this would be wrong, as the -following example shows:</para> - -<programlisting> - data Nom a = MkNom (F a) -- type family F from example above -</programlisting> - -<para>Is <literal>Tricky Nom Age</literal> representationally equal to -<literal>Tricky Nom Int</literal>? No! The former stores a -<literal>Char</literal> and the latter stores a <literal>Bool</literal>. The -solution to this is to require all parameters to type variables to have role -nominal. Thus, GHC would infer role representational for <literal>a</literal> -but role nominal for <literal>b</literal>.</para> - -</sect2> - -<sect2 id="role-annotations"> -<title>Role annotations -<indexterm><primary>-XRoleAnnotations</primary></indexterm> -</title> - -<para> -Sometimes the programmer wants to constrain the inference process. For -example, the base library contains the following definition: -</para> - -<programlisting> - data Ptr a = Ptr Addr# -</programlisting> - -<para> -The idea is that <literal>a</literal> should really be a representational -parameter, but role inference assigns it to phantom. This makes some level of -sense: a pointer to an <literal>Int</literal> really is representationally the -same as a pointer to a <literal>Bool</literal>. But, that's not at all how we -want to use <literal>Ptr</literal>s! So, we want to be able to say</para> - -<programlisting> - type role Ptr representational - data Ptr a = Ptr Addr# -</programlisting> - -<para> -The <literal>type role</literal> (enabled with -<option>-XRoleAnnotations</option>) declaration forces the parameter -<literal>a</literal> to be at role representational, not role phantom. GHC -then checks the user-supplied roles to make sure they don't break any -promises. It would be bad, for example, if the user could make -<literal>BadIdea</literal>'s role be representational. -</para> - -<para>As another example, we can consider a type <literal>Set a</literal> that -represents a set of data, ordered according to <literal>a</literal>'s -<literal>Ord</literal> instance. While it would generally be type-safe to -consider <literal>a</literal> to be at role representational, it is possible -that a <literal>newtype</literal> and its base type have -<emphasis>different</emphasis> orderings encoded in their respective -<literal>Ord</literal> instances. This would lead to misbehavior at runtime. -So, the author of the <literal>Set</literal> datatype would like its parameter -to be at role nominal. This would be done with a declaration</para> - -<programlisting> - type role Set nominal -</programlisting> - -<para>Role annotations can also be used should a programmer wish to write -a class with a representational (or phantom) role. However, as a class -with non-nominal roles can quickly lead to class instance incoherence, -it is necessary to also specify <option>-XIncoherentInstances</option> -to allow non-nominal roles for classes.</para> - -<para>The other place where role annotations may be necessary are in -<literal>hs-boot</literal> files (<xref linkend="mutual-recursion"/>), where -the right-hand sides of definitions can be omitted. As usual, the -types/classes declared in an <literal>hs-boot</literal> file must match up -with the definitions in the <literal>hs</literal> file, including down to the -roles. The default role for datatypes -is representational in <literal>hs-boot</literal> files, -corresponding to the common use case.</para> - -<para> -Role annotations are allowed on data, newtype, and class declarations. A role -annotation declaration starts with <literal>type role</literal> and is -followed by one role listing for each parameter of the type. (This parameter -count includes parameters implicitly specified by a kind signature in a -GADT-style data or newtype declaration.) Each role listing is a role -(<literal>nominal</literal>, <literal>representational</literal>, or -<literal>phantom</literal>) or a <literal>_</literal>. Using a -<literal>_</literal> says that GHC should infer that role. The role annotation -may go anywhere in the same module as the datatype or class definition -(much like a value-level type signature). -Here are some examples:</para> - -<programlisting> - type role T1 _ phantom - data T1 a b = MkT1 a -- b is not used; annotation is fine but unnecessary - - type role T2 _ phantom - data T2 a b = MkT2 b -- ERROR: b is used and cannot be phantom - - type role T3 _ nominal - data T3 a b = MkT3 a -- OK: nominal is higher than necessary, but safe - - type role T4 nominal - data T4 a = MkT4 (a Int) -- OK, but nominal is higher than necessary - - type role C representational _ -- OK, with -XIncoherentInstances - class C a b where ... -- OK, b will get a nominal role - - type role X nominal - type X a = ... -- ERROR: role annotations not allowed for type synonyms -</programlisting> - -</sect2> - -</sect1> - -<sect1 id="strict-haskell"> - <title>Strict Haskell</title> - <indexterm><primary>strict haskell</primary></indexterm> - - <para>High-performance Haskell code (e.g. numeric code) can - sometimes be littered with bang patterns, making it harder to - read. The reason is that lazy evaluation isn't the right default in - this particular code but the programmer has no way to say that - except by repeatedly adding bang patterns. Below - <option>-XStrictData</option> is detailed that allows the programmer - to switch the default behavior on a per-module basis.</para> - - <sect2 id="strict-data"> - <title>Strict-by-default data types</title> - - <para>Informally the <literal>StrictData</literal> language - extension switches data type declarations to be strict by default - allowing fields to be lazy by adding a <literal>~</literal> in - front of the field.</para> - - <para>When the user writes</para> - - <programlisting> - data T = C a - data T' = C' ~a - </programlisting> - - <para>we interpret it as if she had written</para> - - <programlisting> - data T = C !a - data T' = C' a - </programlisting> - - <para>The extension only affects definitions in this module.</para> - </sect2> - -</sect1> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> diff --git a/docs/users_guide/gone_wrong.rst b/docs/users_guide/gone_wrong.rst new file mode 100644 index 0000000000..5737c2d989 --- /dev/null +++ b/docs/users_guide/gone_wrong.rst @@ -0,0 +1,138 @@ +.. _wrong: + +What to do when something goes wrong +==================================== + +.. index:: + single: problems + +If you still have a problem after consulting this section, then you may +have found a *bug*—please report it! See :ref:`bug-reporting` for +details on how to report a bug and a list of things we'd like to know +about your bug. If in doubt, send a report — we love mail from irate users +:-! + +(:ref:`vs-Haskell-defn`, which describes Glasgow Haskell's shortcomings +vs. the Haskell language definition, may also be of interest.) + +.. _wrong-compiler: + +When the compiler “does the wrong thing” +---------------------------------------- + +.. index:: + single: compiler problems + single: problems with the compiler + +"Help! The compiler crashed (or panic'd)!" + These events are *always* bugs in the GHC system—please report them. + +"This is a terrible error message." + If you think that GHC could have produced a better error message, + please report it as a bug. + +"What about this warning from the C compiler?" + For example: ``…warning: \`Foo' declared \`static' but never + defined.`` Unsightly, but shouldn't be a problem. + +Sensitivity to ``.hi`` interface files + GHC is very sensitive about interface files. For example, if it + picks up a non-standard ``Prelude.hi`` file, pretty terrible things + will happen. If you turn on + ``-XNoImplicitPrelude``-XNoImplicitPrelude option, the compiler will + almost surely die, unless you know what you are doing. + + Furthermore, as sketched below, you may have big problems running + programs compiled using unstable interfaces. + +"I think GHC is producing incorrect code" + Unlikely :-) A useful be-more-paranoid option to give to GHC is + ``-dcore-lint``-dcore-lint option; this causes a “lint” pass to + check for errors (notably type errors) after each Core-to-Core + transformation pass. We run with ``-dcore-lint`` on all the time; it + costs about 5% in compile time. + +Why did I get a link error? + If the linker complains about not finding ``_<something>_fast``, + then something is inconsistent: you probably didn't compile modules + in the proper dependency order. + +"Is this line number right?" + On this score, GHC usually does pretty well, especially if you + "allow" it to be off by one or two. In the case of an instance or + class declaration, the line number may only point you to the + declaration, not to a specific method. + + Please report line-number errors that you find particularly + unhelpful. + +.. _wrong-compile: + +When your program “does the wrong thing” +---------------------------------------- + +.. index:: + single: problems running your program + +(For advice about overly slow or memory-hungry Haskell programs, please +see :ref:`sooner-faster-quicker`). + +"Help! My program crashed!" + (e.g., a "segmentation fault" or "core dumped") segmentation fault + + If your program has no foreign calls in it, and no calls to + known-unsafe functions (such as ``unsafePerformIO``) then a crash is + always a BUG in the GHC system, except in one case: If your program + is made of several modules, each module must have been compiled + after any modules on which it depends (unless you use ``.hi-boot`` + files, in which case these *must* be correct with respect to the + module source). + + For example, if an interface is lying about the type of an imported + value then GHC may well generate duff code for the importing module. + *This applies to pragmas inside interfaces too!* If the pragma is + lying (e.g., about the “arity” of a value), then duff code may + result. Furthermore, arities may change even if types do not. + + In short, if you compile a module and its interface changes, then + all the modules that import that interface *must* be re-compiled. + + A useful option to alert you when interfaces change is + ``-ddump-hi-diffs`` option. It will run ``diff`` on + the changed interface file, before and after, when applicable. + + .. index:: + single: -ddump-hi-diffs + + If you are using ``make``, GHC can automatically generate the + dependencies required in order to make sure that every module *is* + up-to-date with respect to its imported interfaces. Please see + :ref:`makefile-dependencies`. + + If you are down to your last-compile-before-a-bug-report, we would + recommend that you add a ``-dcore-lint`` option (for extra checking) + to your compilation options. + + So, before you report a bug because of a core dump, you should + probably: + + :: + + % rm *.o # scrub your object files + % make my_prog # re-make your program; use -ddump-hi-diffs to highlight changes; + # as mentioned above, use -dcore-lint to be more paranoid + % ./my_prog ... # retry... + + Of course, if you have foreign calls in your program then all bets + are off, because you can trash the heap, the stack, or whatever. + +"My program entered an 'absent' argument." + This is definitely caused by a bug in GHC. Please report it (see + :ref:`bug-reporting`). + +"What's with this arithmetic (or floating-point) exception?" + ``Int``, ``Float``, and ``Double`` arithmetic is *unchecked*. + Overflows, underflows and loss of precision are either silent or + reported as an exception by the operating system (depending on the + platform). Divide-by-zero *may* cause an untrapped exception (please + report it if it does). diff --git a/docs/users_guide/gone_wrong.xml b/docs/users_guide/gone_wrong.xml deleted file mode 100644 index 7ffca8bea8..0000000000 --- a/docs/users_guide/gone_wrong.xml +++ /dev/null @@ -1,213 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<chapter id="wrong"> - <title>What to do when something goes wrong</title> - - <indexterm><primary>problems</primary></indexterm> - - <para>If you still have a problem after consulting this section, - then you may have found a <emphasis>bug</emphasis>—please - report it! See <xref linkend="bug-reporting"/> for details on how to - report a bug and a list of things we'd like to know about your bug. - If in doubt, send a report—we love mail from irate users - :-!</para> - - <para>(<xref linkend="vs-Haskell-defn"/>, which describes Glasgow - Haskell's shortcomings vs. the Haskell language definition, may - also be of interest.)</para> - - <sect1 id="wrong-compiler"> - <title>When the compiler “does the wrong thing”</title> - - <indexterm><primary>compiler problems</primary></indexterm> - <indexterm><primary>problems with the compiler</primary></indexterm> - - <variablelist> - <varlistentry> - <term>“Help! The compiler crashed (or `panic'd)!”</term> - <listitem> - <para>These events are <emphasis>always</emphasis> bugs in - the GHC system—please report them.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>“This is a terrible error message.”</term> - <listitem> - <para>If you think that GHC could have produced a better - error message, please report it as a bug.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>“What about this warning from the C - compiler?”</term> - <listitem> - <para>For example: “…warning: `Foo' declared - `static' but never defined.” Unsightly, but shouldn't - be a problem.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Sensitivity to <filename>.hi</filename> interface files:</term> - <listitem> - <para>GHC is very sensitive about interface files. For - example, if it picks up a non-standard - <filename>Prelude.hi</filename> file, pretty terrible things - will happen. If you turn on - <option>-XNoImplicitPrelude</option><indexterm><primary>-XNoImplicitPrelude - option</primary></indexterm>, the compiler will almost - surely die, unless you know what you are doing.</para> - - <para>Furthermore, as sketched below, you may have big - problems running programs compiled using unstable - interfaces.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>“I think GHC is producing incorrect code”:</term> - <listitem> - <para>Unlikely :-) A useful be-more-paranoid option to give - to GHC is - <option>-dcore-lint</option><indexterm><primary>-dcore-lint - option</primary></indexterm>; this causes a - “lint” pass to check for errors (notably type - errors) after each Core-to-Core transformation pass. We run - with <option>-dcore-lint</option> on all the time; it costs - about 5% in compile time.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>“Why did I get a link error?”</term> - <listitem> - <para>If the linker complains about not finding - <literal>_<something>_fast</literal>, - then something is inconsistent: you probably didn't compile - modules in the proper dependency order.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>“Is this line number right?”</term> - <listitem> - <para>On this score, GHC usually does pretty well, - especially if you “allow” it to be off by one or - two. In the case of an instance or class declaration, the - line number may only point you to the declaration, not to a - specific method.</para> - - <para>Please report line-number errors that you find - particularly unhelpful.</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1 id="wrong-compile"> - <title>When your program “does the wrong thing”</title> - - <indexterm><primary>problems running your program</primary></indexterm> - - <para>(For advice about overly slow or memory-hungry Haskell - programs, please see <xref - linkend="sooner-faster-quicker"/>).</para> - - <variablelist> - - <varlistentry> - <term>“Help! My program crashed!”</term> - <listitem> - <para>(e.g., a `segmentation fault' or `core dumped') - <indexterm><primary>segmentation - fault</primary></indexterm></para> - - <para>If your program has no foreign calls in it, and no - calls to known-unsafe functions (such as - <literal>unsafePerformIO</literal>) then a crash is always a - BUG in the GHC system, except in one case: If your program - is made of several modules, each module must have been - compiled after any modules on which it depends (unless you - use <filename>.hi-boot</filename> files, in which case these - <emphasis>must</emphasis> be correct with respect to the - module source).</para> - - <para>For example, if an interface is lying about the type - of an imported value then GHC may well generate duff code - for the importing module. <emphasis>This applies to pragmas - inside interfaces too!</emphasis> If the pragma is lying - (e.g., about the “arity” of a value), then duff - code may result. Furthermore, arities may change even if - types do not.</para> - - <para>In short, if you compile a module and its interface - changes, then all the modules that import that interface - <emphasis>must</emphasis> be re-compiled.</para> - - <para>A useful option to alert you when interfaces change is - <option>-ddump-hi-diffs</option><indexterm><primary>-ddump-hi-diffs - option</primary></indexterm>. It will run - <command>diff</command> on the changed interface file, - before and after, when applicable.</para> - - <para>If you are using <command>make</command>, GHC can - automatically generate the dependencies required in order to - make sure that every module <emphasis>is</emphasis> - up-to-date with respect to its imported interfaces. Please - see <xref linkend="makefile-dependencies"/>.</para> - - <para>If you are down to your - last-compile-before-a-bug-report, we would recommend that - you add a <option>-dcore-lint</option> option (for extra - checking) to your compilation options.</para> - - <para>So, before you report a bug because of a core dump, - you should probably:</para> - -<screen> -% rm *.o # scrub your object files -% make my_prog # re-make your program; use -ddump-hi-diffs to highlight changes; - # as mentioned above, use -dcore-lint to be more paranoid -% ./my_prog ... # retry... -</screen> - - <para>Of course, if you have foreign calls in your program - then all bets are off, because you can trash the heap, the - stack, or whatever.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>“My program entered an `absent' argument.”</term> - <listitem> - <para>This is definitely caused by a bug in GHC. Please - report it (see <xref linkend="bug-reporting"/>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>“What's with this `arithmetic (or `floating') - exception' ”?</term> - <listitem> - <para><literal>Int</literal>, <literal>Float</literal>, and - <literal>Double</literal> arithmetic is - <emphasis>unchecked</emphasis>. Overflows, underflows and - loss of precision are either silent or reported as an - exception by the operating system (depending on the - platform). Divide-by-zero <emphasis>may</emphasis> cause an - untrapped exception (please report it if it does).</para> - </listitem> - </varlistentry> - - </variablelist> - </sect1> - -</chapter> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> diff --git a/docs/users_guide/images/logo.pdf b/docs/users_guide/images/logo.pdf Binary files differnew file mode 100644 index 0000000000..e20d1da4b2 --- /dev/null +++ b/docs/users_guide/images/logo.pdf diff --git a/docs/users_guide/images/prof_scc.pdf b/docs/users_guide/images/prof_scc.pdf Binary files differnew file mode 100644 index 0000000000..1476d9e340 --- /dev/null +++ b/docs/users_guide/images/prof_scc.pdf diff --git a/docs/users_guide/images/prof_scc.svg b/docs/users_guide/images/prof_scc.svg new file mode 100644 index 0000000000..4fde2a7934 --- /dev/null +++ b/docs/users_guide/images/prof_scc.svg @@ -0,0 +1,800 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + id="svg2" + version="1.1" + inkscape:version="0.91 r13725" + xml:space="preserve" + width="810.625" + height="540.625" + viewBox="0 0 810.625 540.625" + sodipodi:docname="prof_scc.svg"><metadata + id="metadata8"><rdf:RDF><cc:Work + rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /><dc:title></dc:title></cc:Work></rdf:RDF></metadata><defs + id="defs6" /><sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="1916" + inkscape:window-height="1051" + id="namedview4" + showgrid="false" + fit-margin-top="0" + fit-margin-left="0" + fit-margin-right="0" + fit-margin-bottom="0" + inkscape:zoom="0.63462185" + inkscape:cx="208.09177" + inkscape:cy="177.95892" + inkscape:window-x="0" + inkscape:window-y="25" + inkscape:window-maximized="0" + inkscape:current-layer="g10" /><g + id="g10" + inkscape:groupmode="layer" + inkscape:label="ink_ext_XXXXXX" + transform="matrix(0,-1.25,-1.25,0,945.3125,630.3125)"><g + id="g12" + transform="scale(0.1,0.1)"><path + d="m 720,1080 4320,0 0,6480 -4320,0 0,-6480 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path14" + inkscape:connector-curvature="0" /><path + d="m 4790,1130 200,0 0,6380 -200,0 0,-6380 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path16" + inkscape:connector-curvature="0" /><g + id="g18" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,485,745)" + style="font-variant:normal;font-weight:normal;font-size:12px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text20"><tspan + x="0 9.9960003 16.667999 19.332001 26.004 29.34 36.012001 42.683998 49.355999 52.692001 59.700001 68.363998 75.695999 83.699997 87.036003 91.031998 97.704002 248.3004 254.9724 258.30841 264.98041 271.6524 278.3244 281.6604 288.3324 294.3324 297.6684 304.34039 310.34039 313.67639 319.67639 323.01239 329.01239 335.68439 341.68439 348.35641 355.02841 361.70041 513.27478 520.60681 524.60278 527.26678 530.60278 539.93878 545.93878 549.27478 555.94678 562.61877 565.95477 572.62677 579.29883 582.63483 589.30682 595.97882 599.31482 605.98682 612.65881 619.33081" + y="0" + sodipodi:role="line" + id="tspan22">Main 100 +RTS -hc9,661 bytes x secondsFri Oct 2 15:01 2015</tspan></text> +</g><path + d="m 920,7110 0,-4092.29" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path24" + inkscape:connector-curvature="0" /><g + id="g26" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,77,339.011)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text28"><tspan + x="0 5 10.56 15.56 21.120001 26.68 32.240002" + y="0" + sodipodi:role="line" + id="tspan30">seconds</tspan></text> +</g><path + d="m 920,7110 -40,0" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path32" + inkscape:connector-curvature="0" /><g + id="g34" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,77,717.95)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text36"><tspan + x="0 5.5599999 8.3400002" + y="0" + sodipodi:role="line" + id="tspan38">0.0</tspan></text> +</g><path + d="m 920,6489.96 -40,0" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path40" + inkscape:connector-curvature="0" /><g + id="g42" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,77,655.945)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text44"><tspan + x="0 5.5599999 8.3400002" + y="0" + sodipodi:role="line" + id="tspan46">0.1</tspan></text> +</g><path + d="m 920,5869.91 -40,0" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path48" + inkscape:connector-curvature="0" /><g + id="g50" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,77,593.941)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text52"><tspan + x="0 5.5599999 8.3400002" + y="0" + sodipodi:role="line" + id="tspan54">0.1</tspan></text> +</g><path + d="m 920,5249.87 -40,0" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path56" + inkscape:connector-curvature="0" /><g + id="g58" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,77,531.937)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text60"><tspan + x="0 5.5599999 8.3400002" + y="0" + sodipodi:role="line" + id="tspan62">0.2</tspan></text> +</g><path + d="m 920,4629.83 -40,0" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path64" + inkscape:connector-curvature="0" /><g + id="g66" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,77,469.932)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text68"><tspan + x="0 5.5599999 8.3400002" + y="0" + sodipodi:role="line" + id="tspan70">0.2</tspan></text> +</g><path + d="m 920,4009.79 -40,0" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path72" + inkscape:connector-curvature="0" /><g + id="g74" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,77,407.928)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text76"><tspan + x="0 5.5599999 8.3400002" + y="0" + sodipodi:role="line" + id="tspan78">0.2</tspan></text> +</g><path + d="m 920,7110 3820,0" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path80" + inkscape:connector-curvature="0" /><g + id="g82" + transform="scale(10,10)"><text + transform="matrix(1,0,0,-1,450.101,716)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text84"><tspan + x="0 5.5599999 10.56 13.34 18.9" + y="0" + sodipodi:role="line" + id="tspan86">bytes</tspan></text> +</g><path + d="m 920,7110 0,40" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path88" + inkscape:connector-curvature="0" /><g + id="g90" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,92,726.56)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text92"><tspan + x="0 5.5599999" + y="0" + sodipodi:role="line" + id="tspan94">0k</tspan></text> +</g><path + d="m 1427.76,7110 0,40" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path96" + inkscape:connector-curvature="0" /><g + id="g98" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,142.776,726.56)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text100"><tspan + x="0 5.5599999" + y="0" + sodipodi:role="line" + id="tspan102">5k</tspan></text> +</g><path + d="m 1935.52,7110 0,40" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path104" + inkscape:connector-curvature="0" /><g + id="g106" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,193.552,732.12)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text108"><tspan + x="0 5.5599999 11.12" + y="0" + sodipodi:role="line" + id="tspan110">10k</tspan></text> +</g><path + d="m 2443.29,7110 0,40" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path112" + inkscape:connector-curvature="0" /><g + id="g114" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,244.329,732.12)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text116"><tspan + x="0 5.5599999 11.12" + y="0" + sodipodi:role="line" + id="tspan118">15k</tspan></text> +</g><path + d="m 2951.05,7110 0,40" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path120" + inkscape:connector-curvature="0" /><g + id="g122" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,295.105,732.12)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text124"><tspan + x="0 5.5599999 11.12" + y="0" + sodipodi:role="line" + id="tspan126">20k</tspan></text> +</g><path + d="m 3458.81,7110 0,40" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path128" + inkscape:connector-curvature="0" /><g + id="g130" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,345.881,732.12)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text132"><tspan + x="0 5.5599999 11.12" + y="0" + sodipodi:role="line" + id="tspan134">25k</tspan></text> +</g><path + d="m 3966.57,7110 0,40" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path136" + inkscape:connector-curvature="0" /><g + id="g138" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,396.657,732.12)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text140"><tspan + x="0 5.5599999 11.12" + y="0" + sodipodi:role="line" + id="tspan142">30k</tspan></text> +</g><path + d="m 1031.91,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path144" + inkscape:connector-curvature="0" /><path + d="m 1031.91,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path146" + inkscape:connector-curvature="0" /><g + id="g148" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,105.191,277.772)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text150"><tspan + x="0 7.7800002 13.89 21.110001 27.780001" + y="0" + sodipodi:role="line" + id="tspan152">OTHER</tspan></text> +</g><path + d="m 1213.81,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:#333333;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path154" + inkscape:connector-curvature="0" /><path + d="m 1213.81,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path156" + inkscape:connector-curvature="0" /><g + id="g158" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,123.381,277.772)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text160"><tspan + x="0 3.3299999 8.8900003 14.45 20.01 23.34 26.120001 29.450001 35.009998 40.009998 45.57 51.130001 53.349998 58.349998 63.91 66.129997 68.910004 72.239998 77.800003 82.800003 85.580002 88.360001 91.139999 94.470001 100.03 105.03 107.81 110.59 113.37" + y="0" + sodipodi:role="line" + id="tspan162">(112)tracepixel/ray.f/ray/...</tspan></text> +</g><path + d="m 1395.71,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:#999999;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path164" + inkscape:connector-curvature="0" /><path + d="m 1395.71,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path166" + inkscape:connector-curvature="0" /><g + id="g168" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,141.571,277.772)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text170"><tspan + x="0 3.3299999 8.8900003 14.45 20.01 23.34 28.34 33.900002 39.459999 45.02 48.349998 53.91 56.130001 61.689999 64.470001 70.029999 73.360001 78.360001 83.919998 88.919998 91.699997 94.480003 97.260002 100.59 106.15 111.15 116.71 119.49 122.27" + y="0" + sodipodi:role="line" + id="tspan172">(122)sphereintersect/trace...</tspan></text> +</g><path + d="m 1577.62,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:#4d4d4d;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path174" + inkscape:connector-curvature="0" /><path + d="m 1577.62,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path176" + inkscape:connector-curvature="0" /><g + id="g178" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,159.762,277.772)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text180"><tspan + x="0 3.3299999 8.8900003 14.45 20.01 23.34 26.67 32.23 37.790001 40.57 46.130001 48.349998 53.91 59.470001 62.25 67.809998 73.370003 75.589996 78.370003 81.150002 84.480003 90.040001 95.599998 98.379997 103.94 106.16 111.16 113.94 116.72" + y="0" + sodipodi:role="line" + id="tspan182">(183)rbg.eight_bit/rbg/pix...</tspan></text> +</g><path + d="m 1759.52,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:#e6e6e6;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path184" + inkscape:connector-curvature="0" /><path + d="m 1759.52,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path186" + inkscape:connector-curvature="0" /><g + id="g188" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,177.952,277.772)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text190"><tspan + x="0 3.3299999 8.8900003 14.45 20.01 23.34 28.9 31.120001 36.119999 41.68 43.900002 48.900002 51.68 57.240002 62.799999 71.129997 73.910004 77.239998 82.800003 88.360001 91.139999 99.470001 105.03 107.25 112.81 115.59 118.37 121.15 123.93" + y="0" + sodipodi:role="line" + id="tspan192">(108)pixels/ppm/run/main.\...</tspan></text> +</g><path + d="m 1941.43,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:#666666;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path194" + inkscape:connector-curvature="0" /><path + d="m 1941.43,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path196" + inkscape:connector-curvature="0" /><g + id="g198" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,196.143,277.772)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text200"><tspan + x="0 3.3299999 8.8900003 14.45 20.01 23.34 28.34 33.900002 38.900002 44.459999 50.02 55.580002 58.360001 63.360001 68.919998 73.919998 78.919998 84.480003 92.809998 95.589996 100.59 106.15 111.71 117.27 122.83 125.61 131.17 133.95 136.73" + y="0" + sodipodi:role="line" + id="tspan202">(221)vecadd/vecsum/shade.d...</tspan></text> +</g><path + d="m 2123.33,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path204" + inkscape:connector-curvature="0" /><path + d="m 2123.33,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path206" + inkscape:connector-curvature="0" /><g + id="g208" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,214.333,277.772)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text210"><tspan + x="0 3.3299999 8.8900003 14.45 20.01 23.34 28.34 33.900002 38.900002 43.900002 48.900002 54.459999 56.68 62.240002 65.019997 70.019997 75.580002 83.910004 89.470001 95.029999 98.360001 103.92 112.25 117.25 120.03 125.03 130.03 132.81 135.59" + y="0" + sodipodi:role="line" + id="tspan212">(147)vecscale/camparams.sc...</tspan></text> +</g><path + d="m 2305.24,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:#b2b2b2;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path214" + inkscape:connector-curvature="0" /><path + d="m 2305.24,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path216" + inkscape:connector-curvature="0" /><g + id="g218" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,232.524,277.772)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text220"><tspan + x="0 3.3299999 8.8900003 14.45 20.01 23.34 28.34 33.900002 38.900002 43.900002 48.900002 54.459999 56.68 62.240002 65.019997 70.019997 75.580002 83.910004 89.470001 95.029999 98.360001 103.92 112.25 117.25 120.03 125.03 130.03 132.81 135.59" + y="0" + sodipodi:role="line" + id="tspan222">(157)vecscale/camparams.sc...</tspan></text> +</g><path + d="m 2487.14,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:#808080;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path224" + inkscape:connector-curvature="0" /><path + d="m 2487.14,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path226" + inkscape:connector-curvature="0" /><g + id="g228" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,250.714,277.772)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text230"><tspan + x="0 3.3299999 8.8900003 14.45 20.01 23.34 28.34 33.900002 38.900002 43.900002 49.459999 55.02 57.799999 62.799999 68.360001 76.690002 82.25 87.809998 91.139999 96.699997 105.03 110.03 112.81 115.59 117.81 121.14 126.14 128.92 131.7" + y="0" + sodipodi:role="line" + id="tspan232">(140)vecsub/camparams.firs...</tspan></text> +</g><path + d="m 2669.05,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:#cccccc;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path234" + inkscape:connector-curvature="0" /><path + d="m 2669.05,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path236" + inkscape:connector-curvature="0" /><g + id="g238" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,268.905,277.772)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text240"><tspan + x="0 3.3299999 8.8900003 14.45 20.01 23.34 26.67 32.23 37.790001 40.57 46.130001 48.349998 53.349998 58.91 61.130001 66.129997 68.910004 74.470001 80.029999 88.360001 91.139999 94.470001 100.03 105.59 108.37 116.7 122.26 125.04 127.82" + y="0" + sodipodi:role="line" + id="tspan242">(110)rbg/pixels/ppm/run/ma...</tspan></text> +</g><path + d="m 2850.95,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path244" + inkscape:connector-curvature="0" /><path + d="m 2850.95,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path246" + inkscape:connector-curvature="0" /><g + id="g248" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,287.095,277.772)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text250"><tspan + x="0 3.3299999 8.8900003 14.45 17.780001 25.559999 32.779999 40 42.779999 45.560001 53.34 56.119999 62.790001 68.349998 73.349998 78.910004 84.470001 86.690002 92.25 97.809998 100.59 103.37 108.37 113.93 119.49 124.49 127.27 134.49001 141.16" + y="0" + sodipodi:role="line" + id="tspan252">(80)GHC.IO.Encoding.Iconv.CAF</tspan></text> +</g><path + d="m 3032.86,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:#333333;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path254" + inkscape:connector-curvature="0" /><path + d="m 3032.86,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path256" + inkscape:connector-curvature="0" /><g + id="g258" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,305.286,277.772)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text260"><tspan + x="0 3.3299999 8.8900003 14.45 20.01 23.34 28.34 33.900002 38.900002 43.900002 49.459999 57.790001 60.57 68.900002 74.459999 76.68 82.239998 85.019997 92.239998 98.910004" + y="0" + sodipodi:role="line" + id="tspan262">(217)vecsum/Main.CAF</tspan></text> +</g><path + d="m 3214.76,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:#999999;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path264" + inkscape:connector-curvature="0" /><path + d="m 3214.76,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path266" + inkscape:connector-curvature="0" /><g + id="g268" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,323.476,277.772)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text270"><tspan + x="0 3.3299999 8.8900003 14.45 20.01 23.34 26.120001 31.68 36.68 39.459999 44.459999 50.02 55.580002 61.139999 64.470001 70.029999 75.029999 77.809998 86.139999 91.699997 93.919998 99.480003 102.26 109.48 116.15" + y="0" + sodipodi:role="line" + id="tspan272">(119)testspheres/Main.CAF</tspan></text> +</g><path + d="m 3396.67,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:#4d4d4d;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path274" + inkscape:connector-curvature="0" /><path + d="m 3396.67,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path276" + inkscape:connector-curvature="0" /><g + id="g278" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,341.667,277.772)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text280"><tspan + x="0 3.3299999 8.8900003 14.45 20.01 23.34 28.34 33.900002 39.459999 45.02 50.580002 53.360001 56.139999 59.470001 65.029999 70.029999 75.589996 81.150002 83.370003 88.370003 93.93 96.150002 98.93 102.26 107.82 112.82 115.6 118.38 121.16" + y="0" + sodipodi:role="line" + id="tspan282">(185)shade/tracepixel/ray....</tspan></text> +</g><path + d="m 3578.57,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:#e6e6e6;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path284" + inkscape:connector-curvature="0" /><path + d="m 3578.57,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path286" + inkscape:connector-curvature="0" /><g + id="g288" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,359.857,277.772)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text290"><tspan + x="0 3.3299999 8.8900003 14.45 20.01 23.34 26.67 32.23 37.23 40.009998 43.34 48.900002 54.459999 57.240002 65.57 71.129997 73.349998 78.910004 81.690002 84.470001 87.25 95.580002 101.14 103.36 108.92 111.7 120.03 122.81 125.59" + y="0" + sodipodi:role="line" + id="tspan292">(109)ray/run/main.\/main/M...</tspan></text> +</g><path + d="m 3760.48,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:#666666;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path294" + inkscape:connector-curvature="0" /><path + d="m 3760.48,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path296" + inkscape:connector-curvature="0" /><g + id="g298" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,378.048,277.772)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text300"><tspan + x="0 3.3299999 8.8900003 14.45 20.01 23.34 31.67 37.23 39.450001 45.009998 47.790001 55.009998 61.68" + y="0" + sodipodi:role="line" + id="tspan302">(103)Main.CAF</tspan></text> +</g><path + d="m 3942.38,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path304" + inkscape:connector-curvature="0" /><path + d="m 3942.38,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path306" + inkscape:connector-curvature="0" /><g + id="g308" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,396.238,277.772)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text310"><tspan + x="0 3.3299999 8.8900003 14.45 17.780001 25.559999 32.779999 40 42.779999 50 55.560001 61.119999 66.120003 68.900002 75.57 77.790001 83.349998 88.910004 94.470001 96.690002 99.470001 106.69 113.36" + y="0" + sodipodi:role="line" + id="tspan312">(84)GHC.Conc.Signal.CAF</tspan></text> +</g><path + d="m 4124.29,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:#b2b2b2;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path314" + inkscape:connector-curvature="0" /><path + d="m 4124.29,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path316" + inkscape:connector-curvature="0" /><g + id="g318" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,414.429,277.772)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text320"><tspan + x="0 3.3299999 8.8900003 14.45 17.780001 25.559999 32.779999 40 42.779999 45.560001 53.34 56.119999 63.34 68.900002 74.459999 80.019997 82.239998 87.800003 90.580002 96.690002 103.91 106.69 113.91 120.58" + y="0" + sodipodi:role="line" + id="tspan322">(77)GHC.IO.Handle.FD.CAF</tspan></text> +</g><path + d="m 4306.19,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:#808080;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path324" + inkscape:connector-curvature="0" /><path + d="m 4306.19,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path326" + inkscape:connector-curvature="0" /><g + id="g328" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,432.619,277.772)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text330"><tspan + x="0 3.3299999 8.8900003 14.45 17.780001 25.559999 32.779999 40 42.779999 45.560001 53.34 56.119999 62.790001 68.349998 73.349998 78.910004 84.470001 86.690002 92.25 97.809998 100.59 107.81 114.48" + y="0" + sodipodi:role="line" + id="tspan332">(92)GHC.IO.Encoding.CAF</tspan></text> +</g><path + d="m 4488.09,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:#cccccc;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path334" + inkscape:connector-curvature="0" /><path + d="m 4488.09,2827.72 140,0 0,140 -140,0 0,-140 z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path336" + inkscape:connector-curvature="0" /><g + id="g338" + transform="scale(10,10)"><text + transform="matrix(0,-1,-1,0,450.809,277.772)" + style="font-variant:normal;font-weight:normal;font-size:10px;font-family:Helvetica;-inkscape-font-specification:Helvetica;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="text340"><tspan + x="0 3.3299999 8.8900003 14.45 17.780001 24.450001 27.23 34.450001 41.669998 48.34" + y="0" + sodipodi:role="line" + id="tspan342">(54)PINNED</tspan></text> +</g><path + d="m 920,7110 0,-4092.28 17.063,620.04 51.992,1240.08 L 924.063,5993.92 920,7110" + style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path344" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,-4092.28 17.063,620.04 51.992,1240.08 L 924.063,5993.92 920,7110 Z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path346" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 4.063,-1116.08 L 989.055,4877.84 937.063,3637.76 920,3017.72 l 0,0 30.871,620.04 38.184,1240.08 L 924.063,5993.92 920,7110" + style="fill:#333333;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path348" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 4.063,-1116.08 L 989.055,4877.84 937.063,3637.76 920,3017.72 l 0,0 30.871,620.04 38.184,1240.08 L 924.063,5993.92 920,7110 Z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path350" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 4.063,-1116.08 L 989.055,4877.84 950.871,3637.76 920,3017.72 l 0,0 45.496,620.04 23.559,1240.08 L 924.063,5993.92 920,7110" + style="fill:#999999;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path352" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 4.063,-1116.08 L 989.055,4877.84 950.871,3637.76 920,3017.72 l 0,0 45.496,620.04 23.559,1240.08 L 924.063,5993.92 920,7110 Z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path354" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 4.063,-1116.08 L 989.055,4877.84 965.496,3637.76 920,3017.72 l 0,0 45.496,620.04 L 1005.3,4877.84 925.688,5993.92 920,7110" + style="fill:#4d4d4d;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path356" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 4.063,-1116.08 L 989.055,4877.84 965.496,3637.76 920,3017.72 l 0,0 45.496,620.04 L 1005.3,4877.84 925.688,5993.92 920,7110 Z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path358" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 5.688,-1116.08 L 1005.3,4877.84 965.496,3637.76 920,3017.72 l 0,0 60.117,620.04 27.623,1240.08 L 928.125,5993.92 920,7110" + style="fill:#e6e6e6;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path360" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 5.688,-1116.08 L 1005.3,4877.84 965.496,3637.76 920,3017.72 l 0,0 60.117,620.04 27.623,1240.08 L 928.125,5993.92 920,7110 Z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path362" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 8.125,-1116.08 L 1007.74,4877.84 980.117,3637.76 920,3017.72 l 0,0 60.117,620.04 47.123,1240.08 L 928.125,5993.92 920,7110" + style="fill:#666666;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path364" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 8.125,-1116.08 L 1007.74,4877.84 980.117,3637.76 920,3017.72 l 0,0 60.117,620.04 47.123,1240.08 L 928.125,5993.92 920,7110 Z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path366" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 8.125,-1116.08 L 1027.24,4877.84 980.117,3637.76 920,3017.72 l 0,0 68.242,620.04 47.118,1240.08 L 936.25,5993.92 920,7110" + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path368" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 8.125,-1116.08 L 1027.24,4877.84 980.117,3637.76 920,3017.72 l 0,0 68.242,620.04 47.118,1240.08 L 936.25,5993.92 920,7110 Z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path370" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 16.25,-1116.08 99.11,-1116.08 L 988.242,3637.76 920,3017.72 l 0,0 76.367,620.04 47.123,1240.08 L 944.371,5993.92 920,7110" + style="fill:#b2b2b2;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path372" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 16.25,-1116.08 99.11,-1116.08 L 988.242,3637.76 920,3017.72 l 0,0 76.367,620.04 47.123,1240.08 L 944.371,5993.92 920,7110 Z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path374" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 L 944.371,5993.92 1043.49,4877.84 996.367,3637.76 920,3017.72 l 0,0 84.49,620.04 47.12,1240.08 L 952.496,5993.92 920,7110" + style="fill:#808080;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path376" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 L 944.371,5993.92 1043.49,4877.84 996.367,3637.76 920,3017.72 l 0,0 84.49,620.04 47.12,1240.08 L 952.496,5993.92 920,7110 Z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path378" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 32.496,-1116.08 99.114,-1116.08 -47.12,-1240.08 -84.49,-620.04 0,0 84.49,620.04 67.43,1240.08 L 964.684,5993.92 920,7110" + style="fill:#cccccc;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path380" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 32.496,-1116.08 99.114,-1116.08 -47.12,-1240.08 -84.49,-620.04 0,0 84.49,620.04 67.43,1240.08 L 964.684,5993.92 920,7110 Z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path382" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 44.684,-1116.08 107.236,-1116.08 -67.43,-1240.08 -84.49,-620.04 0,0 96.68,620.04 67.43,1240.08 L 976.871,5993.92 920,7110" + style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path384" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 44.684,-1116.08 107.236,-1116.08 -67.43,-1240.08 -84.49,-620.04 0,0 96.68,620.04 67.43,1240.08 L 976.871,5993.92 920,7110 Z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path386" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 56.871,-1116.08 107.239,-1116.08 -67.43,-1240.08 -96.68,-620.04 0,0 108.86,620.04 67.44,1240.08 L 989.055,5993.92 920,7110" + style="fill:#333333;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path388" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 56.871,-1116.08 107.239,-1116.08 -67.43,-1240.08 -96.68,-620.04 0,0 108.86,620.04 67.44,1240.08 L 989.055,5993.92 920,7110 Z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path390" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 L 989.055,5993.92 1096.3,4877.84 1028.86,3637.76 920,3017.72 l 0,0 121.86,620.04 67.43,1240.08 L 1002.05,5993.92 920,7110" + style="fill:#999999;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path392" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 L 989.055,5993.92 1096.3,4877.84 1028.86,3637.76 920,3017.72 l 0,0 121.86,620.04 67.43,1240.08 L 1002.05,5993.92 920,7110 Z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path394" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 82.05,-1116.08 107.24,-1116.08 -67.43,-1240.08 -121.86,-620.04 0,0 162.48,620.04 30.06,1240.08 L 1002.05,5993.92 920,7110" + style="fill:#4d4d4d;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path396" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 82.05,-1116.08 107.24,-1116.08 -67.43,-1240.08 -121.86,-620.04 0,0 162.48,620.04 30.06,1240.08 L 1002.05,5993.92 920,7110 Z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path398" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 82.05,-1116.08 110.49,-1116.08 -30.06,-1240.08 -162.48,-620.04 0,0 191.73,620.04 28.43,1240.08 L 1029.68,5993.92 920,7110" + style="fill:#e6e6e6;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path400" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 82.05,-1116.08 110.49,-1116.08 -30.06,-1240.08 -162.48,-620.04 0,0 191.73,620.04 28.43,1240.08 L 1029.68,5993.92 920,7110 Z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path402" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 109.68,-1116.08 110.48,-1116.08 -28.43,-1240.08 -191.73,-620.04 0,0 223.41,620.04 28.44,1240.08 L 1061.36,5993.92 920,7110" + style="fill:#666666;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path404" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 109.68,-1116.08 110.48,-1116.08 -28.43,-1240.08 -191.73,-620.04 0,0 223.41,620.04 28.44,1240.08 L 1061.36,5993.92 920,7110 Z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path406" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 141.36,-1116.08 110.49,-1116.08 -28.44,-1240.08 -223.41,-620.04 0,0 288.41,620.04 28.43,1240.08 L 1126.36,5993.92 920,7110" + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path408" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 141.36,-1116.08 110.49,-1116.08 -28.44,-1240.08 -223.41,-620.04 0,0 288.41,620.04 28.43,1240.08 L 1126.36,5993.92 920,7110 Z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path410" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 206.36,-1116.08 110.48,-1116.08 -28.43,-1240.08 -288.41,-620.04 0,0 357.46,620.04 28.44,1240.08 L 1195.41,5993.92 920,7110" + style="fill:#b2b2b2;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path412" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 206.36,-1116.08 110.48,-1116.08 -28.43,-1240.08 -288.41,-620.04 0,0 357.46,620.04 28.44,1240.08 L 1195.41,5993.92 920,7110 Z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path414" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 L 1195.41,5993.92 1305.9,4877.84 1277.46,3637.76 920,3017.72 l 0,0 468.77,620.04 28.43,1240.08 L 1306.71,5993.92 920,7110" + style="fill:#808080;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path416" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 L 1195.41,5993.92 1305.9,4877.84 1277.46,3637.76 920,3017.72 l 0,0 468.77,620.04 28.43,1240.08 L 1306.71,5993.92 920,7110 Z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path418" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 L 1306.71,5993.92 1417.2,4877.84 1388.77,3637.76 920,3017.72 l 0,0 3791.57,620.04 L 4740,4877.84 4629.51,5993.92 920,7110" + style="fill:#cccccc;fill-opacity:1;fill-rule:nonzero;stroke:none" + id="path420" + inkscape:connector-curvature="0" /><path + d="m 920,7110 0,0 L 1306.71,5993.92 1417.2,4877.84 1388.77,3637.76 920,3017.72 l 0,0 3791.57,620.04 L 4740,4877.84 4629.51,5993.92 920,7110 Z" + style="fill:none;stroke:#000000;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" + id="path422" + inkscape:connector-curvature="0" /></g></g></svg>
\ No newline at end of file diff --git a/docs/users_guide/index.rst b/docs/users_guide/index.rst new file mode 100644 index 0000000000..1b618d4179 --- /dev/null +++ b/docs/users_guide/index.rst @@ -0,0 +1,36 @@ +.. GHC Users Guide documentation master file, created by + + +Welcome to the GHC Users Guide +============================== + +Contents: + +.. toctree:: + :maxdepth: 2 + :numbered: + + license + intro + 7.12.1-notes + ghci + runghc + usage + profiling + sooner + lang + ffi-chap + extending_ghc + gone_wrong + utils + win32-dlls + bugs + editing-guide + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` + diff --git a/docs/users_guide/intro.rst b/docs/users_guide/intro.rst new file mode 100644 index 0000000000..281c04a211 --- /dev/null +++ b/docs/users_guide/intro.rst @@ -0,0 +1,177 @@ +.. _introduction-GHC: + +Introduction to GHC +=================== + +This is a guide to using the Glasgow Haskell Compiler (GHC): an +interactive and batch compilation system for the +`Haskell 2010 <http://www.haskell.org/>`__ language. + +GHC has two main components: an interactive Haskell interpreter (also +known as GHCi), described in :ref:`ghci`, and a batch compiler, +described throughout :ref:`using-ghc`. In fact, GHC consists of a single +program which is just run with different options to provide either the +interactive or the batch system. + +The batch compiler can be used alongside GHCi: compiled modules can be +loaded into an interactive session and used in the same way as +interpreted code, and in fact when using GHCi most of the library code +will be pre-compiled. This means you get the best of both worlds: fast +pre-compiled library code, and fast compile turnaround for the parts of +your program being actively developed. + +GHC supports numerous language extensions, including concurrency, a +foreign function interface, exceptions, type system extensions such as +multi-parameter type classes, local universal and existential +quantification, functional dependencies, scoped type variables and +explicit unboxed types. These are all described in +:ref:`ghc-language-features`. + +GHC has a comprehensive optimiser, so when you want to Really Go For It +(and you've got time to spare) GHC can produce pretty fast code. +Alternatively, the default option is to compile as fast as possible +while not making too much effort to optimise the generated code +(although GHC probably isn't what you'd describe as a fast compiler :-). + +GHC's profiling system supports "cost centre stacks": a way of seeing +the profile of a Haskell program in a call-graph like structure. See +:ref:`profiling` for more details. + +GHC comes with a number of libraries. These are described in separate +documentation. + +.. _getting: + +Obtaining GHC +------------- + +Go to the `GHC home page <http://www.haskell.org/ghc/>`__ and follow the +"download" link to download GHC for your platform. + +Alternatively, if you want to build GHC yourself, head on over to the +:ghc-wiki:`GHC Building Guide <Building>` to find out how to get the sources, +and build it on your system. Note that GHC itself is written in Haskell, so you +will still need to install GHC in order to build it. + +.. _mailing-lists-GHC: + +Meta-information: Web sites, mailing lists, etc. +------------------------------------------------ + +.. index:: + single: mailing lists, Glasgow Haskell + single: Glasgow Haskell mailing lists + +On the World-Wide Web, there are several URLs of likely interest: + +- `GHC home page <http://www.haskell.org/ghc/>`__ + +- `GHC Developers Home <http://ghc.haskell.org/trac/ghc/>`__ (developer + documentation, wiki, and bug tracker) + +We run the following mailing lists about GHC. We encourage you to join, +as you feel is appropriate. + +``glasgow-haskell-users`` + This list is for GHC users to chat among themselves. If you have a + specific question about GHC, please check the + `FAQ <http://www.haskell.org/haskellwiki/GHC/FAQ>`__ first. + + Subscribers can post to the list by sending their message to + glasgow-haskell-users@haskell.org. Further information can be found + on the + `Mailman page <http://www.haskell.org/mailman/listinfo/glasgow-haskell-users>`__. + +``ghc-devs`` + The GHC developers hang out here. If you are working with the GHC API + or have a question about GHC's implementation, feel free to chime in. + + Subscribers can post to the list by sending their message to + ghc-devs@haskell.org. Further information can be found on the + `Mailman page <http://www.haskell.org/mailman/listinfo/ghc-devs>`__. + +There are several other Haskell and GHC-related mailing lists served by +``www.haskell.org``. Go to http://www.haskell.org/mailman/listinfo/ +for the full list. + +.. _bug-reporting: + +Reporting bugs in GHC +--------------------- + +.. index:: + single: bugs; reporting + single: reporting bugs + +Glasgow Haskell is a changing system so there are sure to be bugs in it. +If you find one, please see :ghc-wiki:`this wiki page <ReportABug>` for +information on how to report it. + +.. _version-numbering: + +GHC version numbering policy +---------------------------- + +.. index:: + single: version, of ghc + +As of GHC version 6.8, we have adopted the following policy for +numbering GHC versions: + + Stable branches are numbered ``x.y``, where ⟨y⟩ is *even*. Releases + on the stable branch ``x.y`` are numbered ``x.y.z``, where ⟨z⟩ (>= + 1) is the patchlevel number. Patchlevels are bug-fix releases only, + and never change the programmer interface to any system-supplied + code. However, if you install a new patchlevel over an old one you + will need to recompile any code that was compiled against the old + libraries. + + The value of ``__GLASGOW_HASKELL__`` (see :ref:`c-pre-processor`) + for a major release ``x.y.z`` is the integer ⟨xyy⟩ (if ⟨y⟩ is a + single digit, then a leading zero is added, so for example in + version 6.8.2 of GHC we would have ``__GLASGOW_HASKELL__==608``). + + .. index:: + single: __GLASGOW_HASKELL__ + + We may make snapshot releases of the current stable branch + `available for + download <http://www.haskell.org/ghc/dist/stable/dist/>`__, and the + latest sources are available from + :ghc-wiki:`the git repositories <Repositories>`. + + Stable snapshot releases are named ``x.y.z.YYYYMMDD``. where + ``YYYYMMDD`` is the date of the sources from which the snapshot was + built, and ``x.y.z+1`` is the next release to be made on that + branch. For example, ``6.8.1.20040225`` would be a snapshot of the + ``6.8`` branch during the development of ``6.8.2``. + + The value of ``__GLASGOW_HASKELL__`` for a snapshot release is the + integer ⟨xyy⟩. You should never write any conditional code which + tests for this value, however: since interfaces change on a + day-to-day basis, and we don't have finer granularity in the values + of ``__GLASGOW_HASKELL__``, you should only conditionally compile + using predicates which test whether ``__GLASGOW_HASKELL__`` is equal + to, later than, or earlier than a given major release. + + We may make snapshot releases of the HEAD `available for + download <http://www.haskell.org/ghc/dist/current/dist/>`__, and the + latest sources are available from + :ghc-wiki:`the git repositories <Repositories>`. + + Unstable snapshot releases are named ``x.y.YYYYMMDD``. where + ``YYYYMMDD`` is the date of the sources from which the snapshot was + built. For example, ``6.7.20040225`` would be a snapshot of the HEAD + before the creation of the ``6.8`` branch. + + The value of ``__GLASGOW_HASKELL__`` for a snapshot release is the + integer ⟨xyy⟩. You should never write any conditional code which + tests for this value, however: since interfaces change on a + day-to-day basis, and we don't have finer granularity in the values + of ``__GLASGOW_HASKELL__``, you should only conditionally compile + using predicates which test whether ``__GLASGOW_HASKELL__`` is equal + to, later than, or earlier than a given major release. + +The version number of your copy of GHC can be found by invoking ``ghc`` +with the ``--version`` flag (see :ref:`options-help`). + diff --git a/docs/users_guide/intro.xml b/docs/users_guide/intro.xml deleted file mode 100644 index 85c91ba0f4..0000000000 --- a/docs/users_guide/intro.xml +++ /dev/null @@ -1,319 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<chapter id="introduction-GHC"> - <title>Introduction to GHC</title> - - <para>This is a guide to using the Glasgow Haskell Compiler (GHC): - an interactive and batch compilation system for the <ulink - url="http://www.haskell.org/">Haskell 98</ulink> - language.</para> - - <para>GHC has two main components: an interactive Haskell - interpreter (also known as GHCi), described in <xref - linkend="ghci"/>, and a batch compiler, described throughout <xref - linkend="using-ghc"/>. In fact, GHC consists of a single program - which is just run with different options to provide either the - interactive or the batch system.</para> - - <para>The batch compiler can be used alongside GHCi: compiled - modules can be loaded into an interactive session and used in the - same way as interpreted code, and in fact when using GHCi most of - the library code will be pre-compiled. This means you get the best - of both worlds: fast pre-compiled library code, and fast compile - turnaround for the parts of your program being actively - developed.</para> - - <para>GHC supports numerous language extensions, including - concurrency, a foreign function interface, exceptions, type system - extensions such as multi-parameter type classes, local universal and - existential quantification, functional dependencies, scoped type - variables and explicit unboxed types. These are all described in - <xref linkend="ghc-language-features"/>.</para> - - <para>GHC has a comprehensive optimiser, so when you want to Really - Go For It (and you've got time to spare) GHC can produce pretty fast - code. Alternatively, the default option is to compile as fast as - possible while not making too much effort to optimise the generated - code (although GHC probably isn't what you'd describe as a fast - compiler :-).</para> - - <para>GHC's profiling system supports “cost centre - stacks”: a way of seeing the profile of a Haskell program in a - call-graph like structure. See <xref linkend="profiling"/> for more - details.</para> - - <para>GHC comes with a number of libraries. These are - described in separate documentation.</para> - - <sect1 id="getting"> - <title>Obtaining GHC</title> - - <para>Go to the <ulink url="http://www.haskell.org/ghc/">GHC home - page</ulink> and follow the "download" link to download GHC - for your platform.</para> - - <para>Alternatively, if you want to build GHC yourself, head on - over to the - <ulink url="http://ghc.haskell.org/trac/ghc/wiki/Building">GHC - Building Guide</ulink> to find out how to get the sources, and - build it on your system. Note that GHC itself is written in - Haskell, so you will still need to install GHC in order to - build it.</para> - </sect1> - - <sect1 id="mailing-lists-GHC"> - <title>Meta-information: Web sites, mailing lists, etc.</title> - - <indexterm><primary>mailing lists, Glasgow Haskell</primary></indexterm> - <indexterm><primary>Glasgow Haskell mailing lists</primary></indexterm> - - <para>On the World-Wide Web, there are several URLs of likely - interest:</para> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.haskell.org/ghc/">GHC home - page</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://ghc.haskell.org/trac/ghc/">GHC - Developers Home</ulink> (developer documentation, wiki, and - bug tracker)</para> - </listitem> - </itemizedlist> - - <para>We run the following mailing lists about GHC. - We encourage you to join, as you feel is appropriate.</para> - - <variablelist> - <varlistentry> - <term>glasgow-haskell-users:</term> - <listitem> - <para>This list is for GHC users to chat among themselves. - If you have a specific question about GHC, please check the - <ulink - url="http://www.haskell.org/haskellwiki/GHC/FAQ">FAQ</ulink> - first.</para> - - <variablelist> - <varlistentry> - <term>list email address:</term> - <listitem> - <para><email>glasgow-haskell-users@haskell.org</email></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>subscribe at:</term> - <listitem> - <para><ulink - url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-users"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-users</literal></ulink>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>admin email address:</term> - <listitem> - <para><email>glasgow-haskell-users-admin@haskell.org</email></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>list archives:</term> - <listitem> - <para><ulink - url="http://www.haskell.org/pipermail/glasgow-haskell-users/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-users/</literal></ulink></para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term>ghc-devs:</term> - <listitem> - <para>The hardcore GHC developers hang out here.</para> - - <variablelist> - <varlistentry> - <term>list email address:</term> - <listitem> - <para><email>ghc-devs@haskell.org</email></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>subscribe at:</term> - <listitem> - <para><ulink - url="http://www.haskell.org/mailman/listinfo/ghc-devs"><literal>http://www.haskell.org/mailman/listinfo/ghc-devs</literal></ulink>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>admin email address:</term> - <listitem> - <para><email>ghc-devs-admin@haskell.org</email></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>list archives:</term> - <listitem> - <para><ulink - url="http://www.haskell.org/pipermail/ghc-devs/"><literal>http://www.haskell.org/pipermail/ghc-devs/</literal></ulink></para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - </variablelist> - - <para>There are several other Haskell and GHC-related mailing - lists served by <literal>www.haskell.org</literal>. Go to <ulink - url="http://www.haskell.org/mailman/listinfo/"><literal>http://www.haskell.org/mailman/listinfo/</literal></ulink> - for the full list.</para> - - <para>Some Haskell-related discussion also takes place in the - Usenet newsgroup <literal>comp.lang.functional</literal>.</para> - - </sect1> - - <sect1 id="bug-reporting"> - <title>Reporting bugs in GHC</title> - <indexterm><primary>bugs</primary><secondary>reporting</secondary> - </indexterm> - <indexterm><primary>reporting bugs</primary> - </indexterm> - - <para> - Glasgow Haskell is a changing system so there are sure to be - bugs in it. If you find one, please see - <ulink url="http://ghc.haskell.org/trac/ghc/wiki/ReportABug">this wiki page</ulink> - for information on how to report it. - </para> - - </sect1> - - <sect1 id="version-numbering"> - <title>GHC version numbering policy</title> - <indexterm><primary>version, of ghc</primary></indexterm> - - <para>As of GHC version 6.8, we have adopted the following policy - for numbering GHC versions:</para> - - <variablelist> - <varlistentry> - <term>Stable Releases</term> - <listitem> - <para>Stable branches are numbered <literal><replaceable>x</replaceable>.<replaceable>y</replaceable></literal>, where - <replaceable>y</replaceable> is <emphasis>even</emphasis>. - Releases on the stable branch <literal><replaceable>x</replaceable>.<replaceable>y</replaceable></literal> are numbered <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>, where - <replaceable>z</replaceable> (>= 1) is the patchlevel number. - Patchlevels are bug-fix releases only, and never - change the programmer interface to any system-supplied code. - However, if you install a new patchlevel over an old one you - will need to recompile any code that was compiled against the - old libraries.</para> - - <para>The value of <literal>__GLASGOW_HASKELL__</literal> - (see <xref linkend="c-pre-processor"/>) for a major release - <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal> - is the integer <replaceable>xyy</replaceable> (if - <replaceable>y</replaceable> is a single digit, then a leading zero - is added, so for example in version 6.8.2 of GHC we would have - <literal>__GLASGOW_HASKELL__==608</literal>).</para> - <indexterm> - <primary><literal>__GLASGOW_HASKELL__</literal></primary> - </indexterm> - </listitem> - </varlistentry> - - <varlistentry> - <term>Stable snapshots</term> - <listitem> - <para> - We may make snapshot releases of the current stable branch <ulink - url="http://www.haskell.org/ghc/dist/stable/dist/">available for - download</ulink>, and the latest sources are available from <ulink - url="http://ghc.haskell.org/trac/ghc/wiki/Repositories">the git - repositories</ulink>. - </para> - - <para>Stable snapshot releases are named - <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>.<replaceable>YYYYMMDD</replaceable></literal>. - where <literal><replaceable>YYYYMMDD</replaceable></literal> is the date of the sources - from which the snapshot was built, and <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z+1</replaceable></literal> is the next release to be made on that branch. - For example, <literal>6.8.1.20040225</literal> would be a - snapshot of the <literal>6.8</literal> branch during the development - of <literal>6.8.2</literal>.</para> - - <para>The value of <literal>__GLASGOW_HASKELL__</literal> - for a snapshot release is the integer - <replaceable>xyy</replaceable>. You should never write any - conditional code which tests for this value, however: since - interfaces change on a day-to-day basis, and we don't have - finer granularity in the values of - <literal>__GLASGOW_HASKELL__</literal>, you should only - conditionally compile using predicates which test whether - <literal>__GLASGOW_HASKELL__</literal> is equal to, later - than, or earlier than a given major release.</para> - <indexterm> - <primary><literal>__GLASGOW_HASKELL__</literal></primary> - </indexterm> - </listitem> - </varlistentry> - - <varlistentry> - <term>Unstable snapshots</term> - <listitem> - <para> - We may make snapshot releases of the HEAD <ulink - url="http://www.haskell.org/ghc/dist/current/dist/">available for - download</ulink>, and the latest sources are available from <ulink - url="http://ghc.haskell.org/trac/ghc/wiki/Repositories">the git - repositories</ulink>. - </para> - - <para>Unstable snapshot releases are named - <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>YYYYMMDD</replaceable></literal>. - where <literal><replaceable>YYYYMMDD</replaceable></literal> is the date of the sources - from which the snapshot was built. - For example, <literal>6.7.20040225</literal> would be a - snapshot of the HEAD before the creation of the - <literal>6.8</literal> branch.</para> - - <para>The value of <literal>__GLASGOW_HASKELL__</literal> - for a snapshot release is the integer - <replaceable>xyy</replaceable>. You should never write any - conditional code which tests for this value, however: since - interfaces change on a day-to-day basis, and we don't have - finer granularity in the values of - <literal>__GLASGOW_HASKELL__</literal>, you should only - conditionally compile using predicates which test whether - <literal>__GLASGOW_HASKELL__</literal> is equal to, later - than, or earlier than a given major release.</para> - <indexterm> - <primary><literal>__GLASGOW_HASKELL__</literal></primary> - </indexterm> - </listitem> - </varlistentry> - </variablelist> - - <para>The version number of your copy of GHC can be found by - invoking <literal>ghc</literal> with the - <literal>--version</literal> flag (see <xref - linkend="options-help"/>).</para> - </sect1> - - -&relnotes1; - -</chapter> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> diff --git a/docs/users_guide/lang.rst b/docs/users_guide/lang.rst new file mode 100644 index 0000000000..47864a6c91 --- /dev/null +++ b/docs/users_guide/lang.rst @@ -0,0 +1,10 @@ +.. _ghc-language-features: + +GHC Language Features +===================== + +.. toctree:: + glasgow_exts + parallel + safe_haskell + diff --git a/docs/users_guide/lang.xml b/docs/users_guide/lang.xml deleted file mode 100644 index 7e94ba4b68..0000000000 --- a/docs/users_guide/lang.xml +++ /dev/null @@ -1,16 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<chapter id="ghc-language-features"> -<title>GHC Language Features</title> - -&glasgowexts; -∥ -&safehaskell; - -</chapter> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> diff --git a/docs/users_guide/license.rst b/docs/users_guide/license.rst new file mode 100644 index 0000000000..c325af3dd0 --- /dev/null +++ b/docs/users_guide/license.rst @@ -0,0 +1,35 @@ +.. _License: + +The Glasgow Haskell Compiler License +==================================== + +Copyright 2002 - 2007, The University Court of the University of +Glasgow. All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +- Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +- Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +- Neither name of the University nor the names of its contributors may + be used to endorse or promote products derived from this software + without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE UNIVERSITY COURT OF THE UNIVERSITY OF +GLASGOW AND THE CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED +WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN +NO EVENT SHALL THE UNIVERSITY COURT OF THE UNIVERSITY OF GLASGOW OR THE +CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, +EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, +PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR +PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/docs/users_guide/license.xml b/docs/users_guide/license.xml deleted file mode 100644 index 19f928ddce..0000000000 --- a/docs/users_guide/license.xml +++ /dev/null @@ -1,65 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<preface id="License"> -<title>The Glasgow Haskell Compiler License</title> - -<para> -Copyright 2002 - 2007, The University Court of the University of Glasgow. -All rights reserved. -</para> - -<para> -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: -</para> - -<para> -<itemizedlist> - -<listitem> -<para> -Redistributions of source code must retain the above copyright notice, -this list of conditions and the following disclaimer. -</para> -</listitem> - -<listitem> -<para> -Redistributions in binary form must reproduce the above copyright notice, -this list of conditions and the following disclaimer in the documentation -and/or other materials provided with the distribution. -</para> -</listitem> - -<listitem> -<para> -Neither name of the University nor the names of its contributors may be -used to endorse or promote products derived from this software without -specific prior written permission. -</para> -</listitem> - -</itemizedlist> -</para> - -<para> -THIS SOFTWARE IS PROVIDED BY THE UNIVERSITY COURT OF THE UNIVERSITY OF -GLASGOW AND THE CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, -INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND -FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE -UNIVERSITY COURT OF THE UNIVERSITY OF GLASGOW OR THE CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH -DAMAGE. -</para> - -</preface> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "preface") *** - ;;; End: *** - --> diff --git a/docs/users_guide/packages.rst b/docs/users_guide/packages.rst new file mode 100644 index 0000000000..a58f10ed87 --- /dev/null +++ b/docs/users_guide/packages.rst @@ -0,0 +1,1359 @@ +.. _packages: + +Packages +======== + +.. index:: + single: packages + +A package is a library of Haskell modules known to the compiler. GHC +comes with several packages: see the accompanying `library +documentation <../libraries/index.html>`__. More packages to install can +be obtained from +`HackageDB <http://hackage.haskell.org/packages/hackage.html>`__. + +Using a package couldn't be simpler: if you're using ``--make`` or GHCi, +then most of the installed packages will be automatically available to +your program without any further options. The exceptions to this rule +are covered below in :ref:`using-packages`. + +Building your own packages is also quite straightforward: we provide the +`Cabal <http://www.haskell.org/cabal/>`__ infrastructure which automates +the process of configuring, building, installing and distributing a +package. All you need to do is write a simple configuration file, put a +few files in the right places, and you have a package. See the `Cabal +documentation <http://www.haskell.org/cabal/users-guide/>`__ for +details, and also the Cabal libraries +(:cabal-ref:`Distribution.Simple <Distribution-Simple.html>`, +for example). + +.. _using-packages: + +Using Packages +-------------- + +.. index:: + single: packages; using + +GHC only knows about packages that are *installed*. To see which +packages are installed, use the ``ghc-pkg list`` command: + +:: + + $ ghc-pkg list + /usr/lib/ghc-6.12.1/package.conf.d: + Cabal-1.7.4 + array-0.2.0.1 + base-3.0.3.0 + base-4.2.0.0 + bin-package-db-0.0.0.0 + binary-0.5.0.1 + bytestring-0.9.1.4 + containers-0.2.0.1 + directory-1.0.0.2 + (dph-base-0.4.0) + (dph-par-0.4.0) + (dph-prim-interface-0.4.0) + (dph-prim-par-0.4.0) + (dph-prim-seq-0.4.0) + (dph-seq-0.4.0) + extensible-exceptions-0.1.1.0 + ffi-1.0 + filepath-1.1.0.1 + (ghc-6.12.1) + ghc-prim-0.1.0.0 + haskeline-0.6.2 + haskell98-1.0.1.0 + hpc-0.5.0.2 + integer-gmp-0.1.0.0 + mtl-1.1.0.2 + old-locale-1.0.0.1 + old-time-1.0.0.1 + pretty-1.0.1.0 + process-1.0.1.1 + random-1.0.0.1 + rts-1.0 + syb-0.1.0.0 + template-haskell-2.4.0.0 + terminfo-0.3.1 + time-1.1.4 + unix-2.3.1.0 + utf8-string-0.3.4 + +An installed package is either *exposed* or *hidden* by default. +Packages hidden by default are listed in parentheses (e.g. +``(lang-1.0)``), or possibly in blue if your terminal supports colour, +in the output of ``ghc-pkg list``. Command-line flags, described below, +allow you to expose a hidden package or hide an exposed one. Only +modules from exposed packages may be imported by your Haskell code; if +you try to import a module from a hidden package, GHC will emit an error +message. If there are a multiple exposed versions of a package, GHC will +prefer the latest one. Additionally, some packages may be broken: that +is, they are missing from the package database, or one of their +dependencies are broken; in this case; these packages are excluded from +the default set of packages. + +.. note:: + If you're using Cabal, then the exposed or hidden status of a + package is irrelevant: the available packages are instead determined by + the dependencies listed in your ``.cabal`` specification. The + exposed/hidden status of packages is only relevant when using ``ghc`` or + ``ghci`` directly. + +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 +:ref:`safe-haskell`) with the ``-fpackage-trust`` flag enabled. + +To see which modules are provided by a package use the ``ghc-pkg`` +command (see :ref:`package-management`): + +:: + + $ ghc-pkg field network exposed-modules + exposed-modules: Network.BSD, + Network.CGI, + Network.Socket, + Network.URI, + Network + +The GHC command line options that control packages are: + +``-package ⟨pkg⟩`` + .. index:: + single: -package + + This option causes the installed package ⟨pkg⟩ to be exposed. The + package ⟨pkg⟩ can be specified in full with its version number (e.g. + ``network-1.0``) or the version number can be omitted if there is + only one version of the package installed. If there are multiple + versions of ⟨pkg⟩ installed and ``-hide-all-packages`` was not + specified, then all other versions will become hidden. ``-package`` + supports thinning and renaming described in + :ref:`package-thinning-and-renaming`. + + The ``-package ⟨pkg⟩`` option also causes package ⟨pkg⟩ to be linked into + the resulting executable or shared object. Whether a packages' + library is linked statically or dynamically is controlled by the + flag pair ``-static``/``-dynamic``. + + In ``--make`` mode and ``--interactive`` mode (see :ref:`modes`), + the compiler normally determines which packages are required by the + current Haskell modules, and links only those. In batch mode + however, the dependency information isn't available, and explicit + ``-package`` options must be given when linking. The one other time + you might need to use ``-package`` to force linking a package is + when the package does not contain any Haskell modules (it might + contain a C library only, for example). In that case, GHC will never + discover a dependency on it, so it has to be mentioned explicitly. + + For example, to link a program consisting of objects ``Foo.o`` and + ``Main.o``, where we made use of the ``network`` package, we need to + give GHC the ``-package`` flag thus: + + :: + + $ ghc -o myprog Foo.o Main.o -package network + + The same flag is necessary even if we compiled the modules from + source, because GHC still reckons it's in batch mode: + + :: + + $ ghc -o myprog Foo.hs Main.hs -package network + +``-package-id ⟨pkg-id⟩`` + .. index:: + single: -package-id + + Exposes a package like ``-package``, but the package is named by its + installed package ID rather than by name. This is a more robust way + to name packages, and can be used to select packages that would + otherwise be shadowed. Cabal passes ``-package-id`` flags to GHC. + ``-package-id`` supports thinning and renaming described in + :ref:`package-thinning-and-renaming`. + +``-hide-all-packages`` + .. index:: + single: -hide-package + + Ignore the exposed flag on installed packages, and hide them all by + default. If you use this flag, then any packages you require + (including ``base``) need to be explicitly exposed using + ``-package`` options. + + This is a good way to insulate your program from differences in the + globally exposed packages, and being explicit about package + dependencies is a Good Thing. Cabal always passes the + ``-hide-all-packages`` flag to GHC, for exactly this reason. + +``-hide-package ⟨pkg⟩`` + .. index:: + single: -hide-package + + This option does the opposite of ``-package``: it causes the + specified package to be hidden, which means that none of its modules + will be available for import by Haskell ``import`` directives. + + Note that the package might still end up being linked into the final + program, if it is a dependency (direct or indirect) of another + exposed package. + +``-ignore-package ⟨pkg⟩`` + .. index:: + single: -ignore-package + + Causes the compiler to behave as if package ⟨pkg⟩, and any packages + that depend on ⟨pkg⟩, are not installed at all. + + Saying ``-ignore-package ⟨pkg⟩`` is the same as giving ``-hide-package`` + flags for ⟨pkg⟩ and all the packages that depend on ⟨pkg⟩. Sometimes + we don't know ahead of time which packages will be installed that + depend on ⟨pkg⟩, which is when the ``-ignore-package`` flag can be + useful. + +``-no-auto-link-packages`` + .. index:: + single: -no-auto-link-packages + + By default, GHC will automatically link in the ``base`` and ``rts`` + packages. This flag disables that behaviour. + +``-this-package-key ⟨pkg-key⟩`` + .. index:: + single: -this-package-key + + Tells GHC the the module being compiled forms part of package key + ⟨pkg-key⟩; internally, these keys are used to determine type equality + and linker symbols. + +``-library-name ⟨hash⟩`` + .. index:: + single: -library-name + + Tells GHC that the source of a Backpack file and its textual + dependencies is uniquely identified by ⟨hash⟩. Library names are + determined by Cabal; a usual recipe for a library name is that it is + the hash source package identifier of a package, as well as the + version hashes of all its textual dependencies. GHC will then use + this library name to generate more package keys. + +``-trust ⟨pkg⟩`` + .. index:: + single: -trust + + This option causes the install package ⟨pkg⟩ to be both exposed and + trusted by GHC. This command functions in the in a very similar way + to the ``-package`` command but in addition sets the selected + packaged to be trusted by GHC, regardless of the contents of the + package database. (see :ref:`safe-haskell`). + +``-distrust ⟨pkg⟩`` + .. index:: + single: -distrust + + This option causes the install package ⟨pkg⟩ to be both exposed and + distrusted by GHC. This command functions in the in a very similar + way to the ``-package`` command but in addition sets the selected + packaged to be distrusted by GHC, regardless of the contents of the + package database. (see :ref:`safe-haskell`). + +``-distrust-all`` + .. index:: + single: -distrust-all + + 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 ``base``) need to be explicitly + trusted using ``-trust`` options. This option does not change the + exposed/hidden status of a package, so it isn't equivalent to + applying ``-distrust`` to all packages on the system. (see + :ref:`safe-haskell`). + +.. _package-main: + +The ``main`` package +-------------------- + +Every complete Haskell program must define ``main`` in module ``Main`` +in package ``main``. Omitting the ``-this-package-key`` flag compiles +code for package ``main``. Failure to do so leads to a somewhat obscure +link-time error of the form: + +:: + + /usr/bin/ld: Undefined symbols: + _ZCMain_main_closure + +.. _package-overlaps: + +Consequences of packages for the Haskell language +------------------------------------------------- + +It is possible that by using packages you might end up with a program +that contains two modules with the same name: perhaps you used a package +``P`` that has a *hidden* module ``M``, and there is also a module ``M`` in your +program. Or perhaps the dependencies of packages that you used contain +some overlapping modules. Perhaps the program even contains multiple +versions of a certain package, due to dependencies from other packages. + +None of these scenarios gives rise to an error on its own [1]_, but they +may have some interesting consequences. For instance, if you have a type +``M.T`` from version 1 of package ``P``, then this is *not* the same as +the type ``M.T`` from version 2 of package ``P``, and GHC will report an +error if you try to use one where the other is expected. + +Formally speaking, in Haskell 98, an entity (function, type or class) in +a program is uniquely identified by the pair of the module name in which +it is defined and its name. In GHC, an entity is uniquely defined by a +triple: package, module, and name. + +.. _package-thinning-and-renaming: + +Thinning and renaming modules +----------------------------- + +When incorporating packages from multiple sources, you may end up in a +situation where multiple packages publish modules with the same name. +Previously, the only way to distinguish between these modules was to use +:ref:`package-qualified-imports`. However, since GHC 7.10, the +``-package`` flags (and their variants) have been extended to allow a +user to explicitly control what modules a package brings into scope, by +analogy to the import lists that users can attach to module imports. + +The basic syntax is that instead of specifying a package name P to the +package flag ``-package``, instead we specify both a package name and a +parenthesized, comma-separated list of module names to import. For +example, ``-package "base (Data.List, Data.Bool)"`` makes only +``Data.List`` and ``Data.Bool`` visible from package ``base``. We also +support renaming of modules, in case you need to refer to both modules +simultaneously; this is supporting by writing +``OldModName as NewModName``, e.g. +``-package "base (Data.Bool as Bool)``. You can also write +``-package "base with (Data.Bool as Bool)`` to include all of the +original bindings (e.g. the renaming is strictly additive). It's +important to specify quotes so that your shell passes the package name +and thinning/renaming list as a single argument to GHC. + +Package imports with thinning/renaming do not hide other versions of the +package: e.g. if containers-0.9 is already exposed, +``-package "containers-0.8 (Data.List as ListV8)"`` will only add an +additional binding to the environment. Similarly, +``-package "base (Data.Bool as Bool)" -package "base (Data.List as List)"`` +is equivalent to +``-package "base (Data.Bool as Bool, Data.List as List)"``. Literal +names must refer to modules defined by the original package, so for +example ``-package "base (Data.Bool as Bool, Bool as Baz)"`` is invalid +unless there was a ``Bool`` module defined in the original package. +Hiding a package also clears all of its renamings. + +You can use renaming to provide an alternate prelude, e.g. +``-hide-all-packages -package "basic-prelude (BasicPrelude as Prelude)"``, +in lieu of the :ref:`rebindable-syntax` extension. + +.. _package-databases: + +Package Databases +----------------- + +A package database is where the details about installed packages are +stored. It is a directory, usually called ``package.conf.d``, that +contains a file for each package, together with a binary cache of the +package data in the file ``package.cache``. Normally you won't need to +look at or modify the contents of a package database directly; all +management of package databases can be done through the ``ghc-pkg`` tool +(see :ref:`package-management`). + +GHC knows about two package databases in particular: + +- The global package database, which comes with your GHC installation, + e.g. ``/usr/lib/ghc-6.12.1/package.conf.d``. + +- A package database private to each user. On Unix systems this will be + ``$HOME/.ghc/arch-os-version/package.conf.d``, and on Windows it will + be something like + ``C:\Documents And Settings\user\ghc\package.conf.d``. The + ``ghc-pkg`` tool knows where this file should be located, and will + create it if it doesn't exist (see :ref:`package-management`). + +When GHC starts up, it reads the contents of these two package +databases, and builds up a list of the packages it knows about. You can +see GHC's package table by running GHC with the ``-v`` flag. + +Package databases may overlap, and they are arranged in a stack +structure. Packages closer to the top of the stack will override +(*shadow*) those below them. By default, the stack contains just the +global and the user's package databases, in that order. + +You can control GHC's package database stack using the following +options: + +``-package-db ⟨file⟩`` + .. index:: + single: -package-db + + Add the package database ⟨file⟩ on top of the current stack. + Packages in additional databases read this way will override those + in the initial stack and those in previously specified databases. + +``-no-global-package-db`` + .. index:: + single: -no-global-package-db + + Remove the global package database from the package database stack. + +``-no-user-package-db`` + .. index:: + single: -no-user-package-db + + Prevent loading of the user's local package database in the initial + stack. + +``-clear-package-db`` + .. index:: + single: -clear-package-db + + Reset the current package database stack. This option removes every + previously specified package database (including those read from the + ``GHC_PACKAGE_PATH`` environment variable) from the package database + stack. + +``-global-package-db`` + .. index:: + single: -global-package-db + + Add the global package database on top of the current stack. This + option can be used after ``-no-global-package-db`` to specify the + position in the stack where the global package database should be + loaded. + +``-user-package-db`` + .. index:: + single: -user-package-db + + Add the user's package database on top of the current stack. This + option can be used after ``-no-user-package-db`` to specify the + position in the stack where the user's package database should be + loaded. + +.. _ghc-package-path: + +The ``GHC_PACKAGE_PATH`` environment variable +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: Environment variable; ``GHC_PACKAGE_PATH`` + single: GHC_PACKAGE_PATH + +The ``GHC_PACKAGE_PATH`` environment variable may be set to a +``:``\-separated (``;``\-separated on Windows) list of files containing +package databases. This list of package databases is used by GHC and +ghc-pkg, with earlier databases in the list overriding later ones. This +order was chosen to match the behaviour of the ``PATH`` environment +variable; think of it as a list of package databases that are searched +left-to-right for packages. + +If ``GHC_PACKAGE_PATH`` ends in a separator, then the default package +database stack (i.e. the user and global package databases, in that +order) is appended. For example, to augment the usual set of packages +with a database of your own, you could say (on Unix): + +:: + + $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf: + +(use ``;`` instead of ``:`` on Windows). + +To check whether your ``GHC_PACKAGE_PATH`` setting is doing the right +thing, ``ghc-pkg list`` will list all the databases in use, in the +reverse order they are searched. + +.. _package-ids: + +Installed package IDs, dependencies, and broken packages +-------------------------------------------------------- + +Each installed package has a unique identifier (the "installed package +ID"), which distinguishes it from all other installed packages on the +system. To see the installed package IDs associated with each installed +package, use ``ghc-pkg list -v``: + +:: + + $ ghc-pkg list -v + using cache: /usr/lib/ghc-6.12.1/package.conf.d/package.cache + /usr/lib/ghc-6.12.1/package.conf.d + Cabal-1.7.4 (Cabal-1.7.4-48f5247e06853af93593883240e11238) + array-0.2.0.1 (array-0.2.0.1-9cbf76a576b6ee9c1f880cf171a0928d) + base-3.0.3.0 (base-3.0.3.0-6cbb157b9ae852096266e113b8fac4a2) + base-4.2.0.0 (base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c) + ... + +The string in parentheses after the package name is the installed +package ID: it normally begins with the package name and version, and +ends in a hash string derived from the compiled package. Dependencies +between packages are expressed in terms of installed package IDs, rather +than just packages and versions. For example, take a look at the +dependencies of the ``haskell98`` package: + +:: + + $ ghc-pkg field haskell98 depends + depends: array-0.2.0.1-9cbf76a576b6ee9c1f880cf171a0928d + base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c + directory-1.0.0.2-f51711bc872c35ce4a453aa19c799008 + old-locale-1.0.0.1-d17c9777c8ee53a0d459734e27f2b8e9 + old-time-1.0.0.1-1c0d8ea38056e5087ef1e75cb0d139d1 + process-1.0.1.1-d8fc6d3baf44678a29b9d59ca0ad5780 + random-1.0.0.1-423d08c90f004795fd10e60384ce6561 + +The purpose of the installed package ID is to detect problems caused by +re-installing a package without also recompiling the packages that +depend on it. Recompiling dependencies is necessary, because the newly +compiled package may have a different ABI (Application Binary Interface) +than the previous version, even if both packages were built from the +same source code using the same compiler. With installed package IDs, a +recompiled package will have a different installed package ID from the +previous version, so packages that depended on the previous version are +now orphaned - one of their dependencies is not satisfied. Packages that +are broken in this way are shown in the ``ghc-pkg list`` output either +in red (if possible) or otherwise surrounded by braces. In the following +example, we have recompiled and reinstalled the ``filepath`` package, +and this has caused various dependencies including ``Cabal`` to break: + +:: + + $ ghc-pkg list + WARNING: there are broken packages. Run 'ghc-pkg check' for more details. + /usr/lib/ghc-6.12.1/package.conf.d: + {Cabal-1.7.4} + array-0.2.0.1 + base-3.0.3.0 + ... etc ... + +Additionally, ``ghc-pkg list`` reminds you that there are broken +packages and suggests ``ghc-pkg check``, which displays more information +about the nature of the failure: + +:: + + $ ghc-pkg check + There are problems in package ghc-6.12.1: + dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist + There are problems in package haskeline-0.6.2: + dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist + There are problems in package Cabal-1.7.4: + dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist + There are problems in package process-1.0.1.1: + dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist + There are problems in package directory-1.0.0.2: + dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist + + The following packages are broken, either because they have a problem + listed above, or because they depend on a broken package. + ghc-6.12.1 + haskeline-0.6.2 + Cabal-1.7.4 + process-1.0.1.1 + directory-1.0.0.2 + bin-package-db-0.0.0.0 + hpc-0.5.0.2 + haskell98-1.0.1.0 + +To fix the problem, you need to recompile the broken packages against +the new dependencies. The easiest way to do this is to use +``cabal-install``, or download the packages from +`HackageDB <http://hackage.haskell.org/packages/hackage.html>`__ and +build and install them as normal. + +Be careful not to recompile any packages that GHC itself depends on, as +this may render the ``ghc`` package itself broken, and ``ghc`` cannot be +simply recompiled. The only way to recover from this would be to +re-install GHC. + +.. _package-management: + +Package management (the ``ghc-pkg`` command) +-------------------------------------------- + +.. index:: + single: packages; management + +The ``ghc-pkg`` tool is for querying and modifying package databases. To +see what package databases are in use, use ``ghc-pkg list``. The stack +of databases that ``ghc-pkg`` knows about can be modified using the +``GHC_PACKAGE_PATH`` environment variable (see :ref:`ghc-package-path`, +and using ``--package-db`` options on the ``ghc-pkg`` command line. + +When asked to modify a database, ``ghc-pkg`` modifies the global +database by default. Specifying ``--user`` causes it to act on the user +database, or ``--package-db`` can be used to act on another database +entirely. When multiple of these options are given, the rightmost one is +used as the database to act upon. + +Commands that query the package database (list, latest, describe, field, +dot) operate on the list of databases specified by the flags ``--user``, +``--global``, and ``--package-db``. If none of these flags are given, +the default is ``--global --user``. + +If the environment variable ``GHC_PACKAGE_PATH`` is set, and its value +does not end in a separator (``:`` on Unix, ``;`` on Windows), then the +last database is considered to be the global database, and will be +modified by default by ``ghc-pkg``. The intention here is that +``GHC_PACKAGE_PATH`` can be used to create a virtual package environment +into which Cabal packages can be installed without setting anything +other than ``GHC_PACKAGE_PATH``. + +The ``ghc-pkg`` program may be run in the ways listed below. Where a +package name is required, the package can be named in full including the +version number (e.g. ``network-1.0``), or without the version number. +Naming a package without the version number matches all versions of the +package; the specified action will be applied to all the matching +packages. A package specifier that matches all version of the package +can also be written ``⟨pkg⟩ -*``, to make it clearer that multiple +packages are being matched. To match against the installed package ID +instead of just package name and version, pass the ``--ipid`` flag. + +``ghc-pkg init path`` + Creates a new, empty, package database at ⟨path⟩, which must not + already exist. + +``ghc-pkg register ⟨file⟩`` + Reads a package specification from ⟨file⟩ (which may be "``-``" + to indicate standard input), and adds it to the database of + installed packages. The syntax of ⟨file⟩ is given in + :ref:`installed-pkg-info`. + + The package specification must be a package that isn't already + installed. + +``ghc-pkg update ⟨file⟩`` + The same as ``register``, except that if a package of the same name + is already installed, it is replaced by the new one. + +``ghc-pkg unregister ⟨P⟩`` + Remove the specified package from the database. + +``ghc-pkg check`` + Check consistency of dependencies in the package database, and + report packages that have missing dependencies. + +``ghc-pkg expose ⟨P⟩`` + Sets the ``exposed`` flag for package ⟨P⟩ to ``True``. + +``ghc-pkg hide ⟨P⟩`` + Sets the ``exposed`` flag for package ⟨P⟩ to ``False``. + +``ghc-pkg trust ⟨P⟩`` + Sets the ``trusted`` flag for package ⟨P⟩ to ``True``. + +``ghc-pkg distrust ⟨P⟩`` + Sets the ``trusted`` flag for package ⟨P⟩ to ``False``. + +``ghc-pkg list [⟨P⟩] [--simple-output]`` + This option displays the currently installed packages, for each of + the databases known to ``ghc-pkg``. That includes the global + database, the user's local database, and any further files specified + using the ``-f`` option on the command line. + + Hidden packages (those for which the ``exposed`` flag is ``False``) + are shown in parentheses in the list of packages. + + If an optional package identifier ⟨P⟩ is given, then only packages + matching that identifier are shown. + + If the option ``--simple-output`` is given, then the packages are + listed on a single line separated by spaces, and the database names + are not included. This is intended to make it easier to parse the + output of ``ghc-pkg list`` using a script. + +``ghc-pkg find-module ⟨M⟩ [--simple-output]`` + This option lists registered packages exposing module ⟨M⟩. Examples: + + :: + + $ ghc-pkg find-module Var + c:/fptools/validate/ghc/driver/package.conf.inplace: + (ghc-6.9.20080428) + + $ ghc-pkg find-module Data.Sequence + c:/fptools/validate/ghc/driver/package.conf.inplace: + containers-0.1 + + Otherwise, it behaves like ``ghc-pkg list``, including options. + +``ghc-pkg latest ⟨P⟩`` + Prints the latest available version of package ⟨P⟩. + +``ghc-pkg describe ⟨P⟩`` + Emit the full description of the specified package. The description + is in the form of an ``InstalledPackageInfo``, the same as the input + file format for ``ghc-pkg register``. See :ref:`installed-pkg-info` + for details. + + If the pattern matches multiple packages, the description for each + package is emitted, separated by the string ``---`` on a line by + itself. + +``ghc-pkg field ⟨P⟩ ⟨field⟩[,⟨field⟩]*`` + Show just a single field of the installed package description for + ``P``. Multiple fields can be selected by separating them with + commas + +``ghc-pkg dot`` + Generate a graph of the package dependencies in a form suitable for + input for the `graphviz <http://www.graphviz.org/>`__ tools. For + example, to generate a PDF of the dependency graph: + + :: + + ghc-pkg dot | tred | dot -Tpdf >pkgs.pdf + +``ghc-pkg dump`` + Emit the full description of every package, in the form of an + ``InstalledPackageInfo``. Multiple package descriptions are + separated by the string ``---`` on a line by itself. + + This is almost the same as ``ghc-pkg describe '*'``, except that + ``ghc-pkg dump`` is intended for use by tools that parse the + results, so for example where ``ghc-pkg describe '*'`` will emit an + error if it can't find any packages that match the pattern, + ``ghc-pkg dump`` will simply emit nothing. + +``ghc-pkg recache`` + Re-creates the binary cache file ``package.cache`` for the selected + database. This may be necessary if the cache has somehow become + out-of-sync with the contents of the database (``ghc-pkg`` will warn + you if this might be the case). + + The other time when ``ghc-pkg recache`` is useful is for registering + packages manually: it is possible to register a package by simply + putting the appropriate file in the package database directory and + invoking ``ghc-pkg recache`` to update the cache. This method of + registering packages may be more convenient for automated packaging + systems. + +Substring matching is supported for ⟨M⟩ in ``find-module`` and for ⟨P⟩ +in ``list``, ``describe``, and ``field``, where a ``'*'`` indicates open +substring ends (``prefix*``, ``*suffix``, ``*infix*``). Examples (output +omitted): + +:: + + -- list all regex-related packages + ghc-pkg list '*regex*' --ignore-case + -- list all string-related packages + ghc-pkg list '*string*' --ignore-case + -- list OpenGL-related packages + ghc-pkg list '*gl*' --ignore-case + -- list packages exporting modules in the Data hierarchy + ghc-pkg find-module 'Data.*' + -- list packages exporting Monad modules + ghc-pkg find-module '*Monad*' + -- list names and maintainers for all packages + ghc-pkg field '*' name,maintainer + -- list location of haddock htmls for all packages + ghc-pkg field '*' haddock-html + -- dump the whole database + ghc-pkg describe '*' + +Additionally, the following flags are accepted by ``ghc-pkg``: + +``-f ⟨file⟩``, ``-package-db ⟨file⟩`` + .. index:: + single: -f; ghc-pkg option + single: -package-db; ghc-pkg option + + Adds ⟨file⟩ to the stack of package databases. Additionally, ⟨file⟩ + will also be the database modified by a ``register``, + ``unregister``, ``expose`` or ``hide`` command, unless it is + overridden by a later ``--package-db``, ``--user`` or ``--global`` + option. + +``--force`` + .. index:: + single: --force; ghc-pkg option + + Causes ``ghc-pkg`` to ignore missing dependencies, directories and + libraries when registering a package, and just go ahead and add it + anyway. This might be useful if your package installation system + needs to add the package to GHC before building and installing the + files. + +``--global`` + .. index:: + single: --global; ghc-pkg option + + Operate on the global package database (this is the default). This + flag affects the ``register``, ``update``, ``unregister``, + ``expose``, and ``hide`` commands. + +``--help``, ``-?`` + .. index:: + single: --help; ghc-pkg option + single: -?; ghc-pkg option + + Outputs the command-line syntax. + +``--user`` + .. index:: + single: --user; ghc-pkg option + + Operate on the current user's local package database. This flag + affects the ``register``, ``update``, ``unregister``, ``expose``, + and ``hide`` commands. + +``-v [⟨n⟩]``, ``--verbose [=⟨n⟩]`` + .. index:: + single: -v; ghc-pkg option + single: --verbose; ghc-pkg option + + Control verbosity. Verbosity levels range from 0-2, where the + default is 1, and ``-v`` alone selects level 2. + +``-V``; \ ``--version`` + .. index:: + single: -V; ghc-pkg option + single: --version; ghc-pkg option + + Output the ``ghc-pkg`` version number. + +``--ipid`` + .. index:: + single: --ipid; ghc-pkg option + + Causes ``ghc-pkg`` to interpret arguments as installed package IDs + (e.g., an identifier like + ``unix-2.3.1.0-de7803f1a8cd88d2161b29b083c94240``). This is useful + if providing just the package name and version are ambiguous (in old + versions of GHC, this was guaranteed to be unique, but this + invariant no longer necessarily holds). + +``--package-key`` + .. index:: + single: --package-key; ghc-pkg option + + Causes ``ghc-pkg`` to interpret arguments as package keys (e.g., an + identifier like ``I5BErHzyOm07EBNpKBEeUv``). Package keys are used + to prefix symbol names GHC produces (e.g., + ``6VWy06pWzzJq9evDvK2d4w6_DataziByteStringziInternal_unsafePackLenChars_info``), + so if you need to figure out what package a symbol belongs to, use + ``ghc-pkg`` with this flag. + +.. _building-packages: + +Building a package from Haskell source +-------------------------------------- + +.. index:: + single: packages; building + +We don't recommend building packages the hard way. Instead, use the +`Cabal <http://www.haskell.org/cabal/users-guide/>`__ infrastructure if +possible. If your package is particularly complicated or requires a lot +of configuration, then you might have to fall back to the low-level +mechanisms, so a few hints for those brave souls follow. + +You need to build an "installed package info" file for passing to +``ghc-pkg`` when installing your package. The contents of this file are +described in :ref:`installed-pkg-info`. + +The Haskell code in a package may be built into one or more archive +libraries (e.g. ``libHSfoo.a``), or a single shared object (e.g. +``libHSfoo.dll/.so/.dylib``). The restriction to a single shared object +is because the package system is used to tell the compiler when it +should make an inter-shared-object call rather than an +intra-shared-object-call call (inter-shared-object calls require an +extra indirection). + +- Building a static library is done by using the ``ar`` tool, like so: + + :: + + ar cqs libHSfoo-1.0.a A.o B.o C.o ... + + where ``A.o``, ``B.o`` and so on are the compiled Haskell modules, + and ``libHSfoo.a`` is the library you wish to create. The syntax may + differ slightly on your system, so check the documentation if you run + into difficulties. + +- To load a package ``foo``, GHCi can load its ``libHSfoo.a`` library + directly, but it can also load a package in the form of a single + ``HSfoo.o`` file that has been pre-linked. Loading the ``.o`` file is + slightly quicker, but at the expense of having another copy of the + compiled package. The rule of thumb is that if the modules of the + package were compiled with ``-split-objs`` then building the + ``HSfoo.o`` is worthwhile because it saves time when loading the + package into GHCi. Without ``-split-objs``, there is not much + difference in load time between the ``.o`` and ``.a`` libraries, so + it is better to save the disk space and only keep the ``.a`` around. + In a GHC distribution we provide ``.o`` files for most packages + except the GHC package itself. + + The ``HSfoo.o`` file is built by Cabal automatically; use + ``--disable-library-for-ghci`` to disable it. To build one manually, + the following GNU ``ld`` command can be used: + + :: + + ld -r --whole-archive -o HSfoo.o libHSfoo.a + + (replace ``--whole-archive`` with ``-all_load`` on MacOS X) + +- When building the package as shared library, GHC can be used to + perform the link step. This hides some of the details out the + underlying linker and provides a common interface to all shared + object variants that are supported by GHC (DLLs, ELF DSOs, and Mac OS + dylibs). The shared object must be named in specific way for two + reasons: (1) the name must contain the GHC compiler version, so that + two library variants don't collide that are compiled by different + versions of GHC and that therefore are most likely incompatible with + respect to calling conventions, (2) it must be different from the + static name otherwise we would not be able to control the linker as + precisely as necessary to make the ``-static``/``-dynamic`` flags + work, see :ref:`options-linker`. + + :: + + ghc -shared libHSfoo-1.0-ghcGHCVersion.so A.o B.o C.o + + Using GHC's version number in the shared object name allows different + library versions compiled by different GHC versions to be installed + in standard system locations, e.g. under \*nix ``/usr/lib``. To obtain + the version number of GHC invoke ``ghc --numeric-version`` and use + its output in place of ⟨GHCVersion⟩. See also :ref:`options-codegen` + on how object files must be prepared for shared object linking. + +To compile a module which is to be part of a new package, use the +``-package-name`` (to identify the name of the package) and +``-library-name`` (to identify the version and the version hashes of its +identities.) options (:ref:`using-packages`). Failure to use these +options when compiling a package will probably result in disaster, but +you will only discover later when you attempt to import modules from the +package. At this point GHC will complain that the package name it was +expecting the module to come from is not the same as the package name +stored in the ``.hi`` file. + +It is worth noting with shared objects, when each package is built as a +single shared object file, since a reference to a shared object costs an +extra indirection, intra-package references are cheaper than +inter-package references. Of course, this applies to the ``main`` +package as well. + +.. _installed-pkg-info: + +``InstalledPackageInfo``: a package specification +------------------------------------------------- + +A package specification is a Haskell record; in particular, it is the +record +:cabal-ref:`InstalledPackageInfo <Distribution-InstalledPackageInfo.html#%tInstalledPackageInfo>` +in the module Distribution.InstalledPackageInfo, which is part of the +Cabal package distributed with GHC. + +An ``InstalledPackageInfo`` has a human readable/writable syntax. The +functions ``parseInstalledPackageInfo`` and ``showInstalledPackageInfo`` +read and write this syntax respectively. Here's an example of the +``InstalledPackageInfo`` for the ``unix`` package: + +:: + + $ ghc-pkg describe unix + name: unix + version: 2.3.1.0 + id: unix-2.3.1.0-de7803f1a8cd88d2161b29b083c94240 + license: BSD3 + copyright: + maintainer: libraries@haskell.org + stability: + homepage: + package-url: + description: This package gives you access to the set of operating system + services standardised by POSIX 1003.1b (or the IEEE Portable + Operating System Interface for Computing Environments - + IEEE Std. 1003.1). + . + The package is not supported under Windows (except under Cygwin). + category: System + author: + exposed: True + exposed-modules: System.Posix System.Posix.DynamicLinker.Module + System.Posix.DynamicLinker.Prim System.Posix.Directory + System.Posix.DynamicLinker System.Posix.Env System.Posix.Error + System.Posix.Files System.Posix.IO System.Posix.Process + System.Posix.Process.Internals System.Posix.Resource + System.Posix.Temp System.Posix.Terminal System.Posix.Time + System.Posix.Unistd System.Posix.User System.Posix.Signals + 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 + extra-libraries: rt util dl + extra-ghci-libraries: + include-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0/include + includes: HsUnix.h execvpe.h + depends: base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c + hugs-options: + cc-options: + ld-options: + framework-dirs: + frameworks: + haddock-interfaces: /usr/share/doc/ghc/html/libraries/unix/unix.haddock + haddock-html: /usr/share/doc/ghc/html/libraries/unix + +Here is a brief description of the syntax of this file: + +A package description consists of a number of field/value pairs. A field +starts with the field name in the left-hand column followed by a +"``:``", and the value continues until the next line that begins in +the left-hand column, or the end of file. + +The syntax of the value depends on the field. The various field types +are: + +freeform + Any arbitrary string, no interpretation or parsing is done. + +string + A sequence of non-space characters, or a sequence of arbitrary + characters surrounded by quotes ``"...."``. + +string list + A sequence of strings, separated by commas. The sequence may be + empty. + +In addition, there are some fields with special syntax (e.g. package +names, version, dependencies). + +The allowed fields, with their types, are: + +``name`` + .. index:: + single: name; package specification + + (string) The package's name (without the version). + +``id`` + .. index:: + single: id; package specification + + (string) The installed package ID. It is up to you to choose a suitable one. + +``version`` + .. index:: + single: version; package specification + + (string) The package's version, usually in the form ``A.B`` (any number of + components are allowed). + +``license`` + .. index:: + single: auto; package specification + + (string) The type of license under which this package is + distributed. This field is a value of the + :cabal-ref:`License <Distribution-License.html#t:License>` type. + +``license-file`` + .. index:: + single: license-file; package specification + + (optional string) The name of a file giving detailed license + information for this package. + +``copyright`` + .. index:: + single: copyright; package specification + + (optional freeform) The copyright string. + +``maintainer`` + .. index:: + single: maintainer; package specification + + (optional freeform) The email address of the package's maintainer. + +``stability`` + .. index:: + single: stability; package specification + + (optional freeform) A string describing the stability of the package + (e.g. stable, provisional or experimental). + +``homepage`` + .. index:: + single: homepage; package specification + + (optional freeform) URL of the package's home page. + +``package-url`` + .. index:: + single: package-url; package specification + + (optional freeform) URL of a downloadable distribution for this + package. The distribution should be a Cabal package. + +``description`` + .. index:: + single: description; package specification + + (optional freeform) Description of the package. + +``category`` + .. index:: + single: category; package specification + + (optional freeform) Which category the package belongs to. This + field is for use in conjunction with a future centralised package + distribution framework, tentatively titled Hackage. + +``author`` + .. index:: + single: author; package specification + + (optional freeform) Author of the package. + +``exposed`` + .. index:: + single: exposed; package specification + + (bool) Whether the package is exposed or not. + +``exposed-modules`` + .. index:: + single: exposed-modules; package specification + + (string list) modules exposed by this package. + +``hidden-modules`` + .. index:: + single: hidden-modules; package specification + + (string list) modules provided by this package, but not exposed to + the programmer. These modules cannot be imported, but they are still + subject to the overlapping constraint: no other package in the same + program may provide a module of the same name. + +``reexported-modules`` + .. index:: + single: reexported-modules; reexport specification + + Modules reexported by this package. This list takes the form of + ``pkg:OldName as NewName (A@orig-pkg-0.1-HASH)``: the first portion + of the string is the user-written reexport specification (possibly + omitting the package qualifier and the renaming), while the + parenthetical is the original package which exposed the module under + are particular name. Reexported modules have a relaxed overlap + constraint: it's permissible for two packages to reexport the same + module as the same name if the reexported moduleis identical. + +``trusted`` + .. index:: + single: trusted; package specification + + (bool) Whether the package is trusted or not. + +``import-dirs`` + .. index:: + single: import-dirs; package specification + + (string list) A list of directories containing interface files + (``.hi`` files) for this package. + + If the package contains profiling libraries, then the interface + files for those library modules should have the suffix ``.p_hi``. So + the package can contain both normal and profiling versions of the + same library without conflict (see also ``library_dirs`` below). + +``library-dirs`` + .. index:: + single: library-dirs; package specification + + (string list) A list of directories containing libraries for this + package. + +``hs-libraries`` + .. index:: + single: hs-libraries; package specification + + (string list) A list of libraries containing Haskell code for this + package, with the ``.a`` or ``.dll`` suffix omitted. When packages + are built as libraries, the ``lib`` prefix is also omitted. + + For use with GHCi, each library should have an object file too. The + name of the object file does *not* have a ``lib`` prefix, and has + the normal object suffix for your platform. + + For example, if we specify a Haskell library as ``HSfoo`` in the + package spec, then the various flavours of library that GHC actually + uses will be called: + + ``libHSfoo.a`` + The name of the library on Unix and Windows (mingw) systems. + Note that we don't support building dynamic libraries of Haskell + code on Unix systems. + + ``HSfoo.dll`` + The name of the dynamic library on Windows systems (optional). + + ``HSfoo.o``; \ ``HSfoo.obj`` + The object version of the library used by GHCi. + +``extra-libraries`` + .. index:: + single: extra-libraries; package specification + + (string list) A list of extra libraries for this package. The + difference between ``hs-libraries`` and ``extra-libraries`` is that + ``hs-libraries`` normally have several versions, to support + profiling, parallel and other build options. The various versions + are given different suffixes to distinguish them, for example the + profiling version of the standard prelude library is named + ``libHSbase_p.a``, with the ``_p`` indicating that this is a + profiling version. The suffix is added automatically by GHC for + ``hs-libraries`` only, no suffix is added for libraries in + ``extra-libraries``. + + The libraries listed in ``extra-libraries`` may be any libraries + supported by your system's linker, including dynamic libraries + (``.so`` on Unix, ``.DLL`` on Windows). + + Also, ``extra-libraries`` are placed on the linker command line + after the ``hs-libraries`` for the same package. If your package has + dependencies in the other direction (i.e. ``extra-libraries`` + depends on ``hs-libraries``), and the libraries are static, you + might need to make two separate packages. + +``include-dirs`` + .. index:: + single: include-dirs; package specification + + (string list) A list of directories containing C includes for this + package. + +``includes`` + .. index:: + single: includes; package specification + + (string list) A list of files to include for via-C compilations + using this package. Typically the include file(s) will contain + function prototypes for any C functions used in the package, in case + they end up being called as a result of Haskell functions from the + package being inlined. + +``depends`` + .. index:: + single: depends; package specification + + (package id list) Packages on which this package depends. + +``hugs-options`` + .. index:: + single: hugs-options; package specification + + (string list) Options to pass to Hugs for this package. + +``cc-options`` + .. index:: + single: cc-options; package specification + + (string list) Extra arguments to be added to the gcc command line + when this package is being used (only for via-C compilations). + +``ld-options`` + .. index:: + single: ld-options; package specification + + (string list) Extra arguments to be added to the ``gcc`` command + line (for linking) when this package is being used. + +``framework-dirs`` + .. index:: + single: framework-dirs; package specification + + (string list) On Darwin/MacOS X, a list of directories containing + frameworks for this package. This corresponds to the + ``-framework-path`` option. It is ignored on all other platforms. + +``frameworks`` + .. index:: + single: frameworks; package specification + + (string list) On Darwin/MacOS X, a list of frameworks to link to. + This corresponds to the ``-framework`` option. Take a look at + Apple's developer documentation to find out what frameworks actually + are. This entry is ignored on all other platforms. + +``haddock-interfaces`` + .. index:: + single: haddock-interfaces; package specification + + (string list) A list of filenames containing + `Haddock <http://www.haskell.org/haddock/>`__ interface files + (``.haddock`` files) for this package. + +``haddock-html`` + .. index:: + single: haddock-html; package specification + + (optional string) The directory containing the Haddock-generated + HTML for this package. + +.. _package-environments: + +Package environments +-------------------- + +.. index:: + single: package environments + +A *package environment* is a file that tells ``ghc`` precisely which +packages should be visible. It contains package IDs, one per line: + +:: + + package_id_1 + package_id_2 + ... + package_id_n + +If a package environment is found, it is equivalent to passing these +command line arguments to ``ghc``: + +:: + + -hide-all-packages + -package-id package_id_1 + -package-id package_id_2 + ... + -package-id package_id_n + +In order, ``ghc`` will look for the package environment in the following +locations: + +- File ⟨file⟩ if you pass the option ``-package-env file``. + +- File ``$HOME/.ghc/arch-os-version/environments/name`` if you pass the + option ``-package-env name``. + +- File ⟨file⟩ if the environment variable ``GHC_ENVIRONMENT`` is set to + ⟨file⟩. + +- File ``$HOME/.ghc/arch-os-version/environments/name`` if the + environment variable ``GHC_ENVIRONMENT`` is set to ⟨name⟩. + +- File ``./.ghc.environment`` if it exists. + +- File ``$HOME/.ghc/arch-os-version/environments/default`` if it + exists. + +Package environments can be modified by further command line arguments; +for example, if you specify ``-package foo`` on the command line, then +package ⟨foo⟩ will be visible even if it's not listed in the currently +active package environment. + +.. [1] it used to in GHC 6.4, but not since 6.6 diff --git a/docs/users_guide/packages.xml b/docs/users_guide/packages.xml deleted file mode 100644 index 1d3b4b4d7c..0000000000 --- a/docs/users_guide/packages.xml +++ /dev/null @@ -1,1939 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> - <sect1 id="packages"> - <title> -Packages - </title> - <indexterm><primary>packages</primary></indexterm> - - <para>A package is a library of Haskell modules known to the - compiler. GHC comes with several packages: see the accompanying - <ulink url="../libraries/index.html">library - documentation</ulink>. More packages to install can be obtained - from <ulink - url="http://hackage.haskell.org/packages/hackage.html">HackageDB</ulink>.</para> - - <para>Using a package couldn't be simpler: if you're using - <option>--make</option> or GHCi, then most of the installed packages will be - automatically available to your program without any further options. The - exceptions to this rule are covered below in <xref - linkend="using-packages" />.</para> - - <para>Building your own packages is also quite straightforward: we provide - the <ulink url="http://www.haskell.org/cabal/">Cabal</ulink> infrastructure which - automates the process of configuring, building, installing and distributing - a package. All you need to do is write a simple configuration file, put a - few files in the right places, and you have a package. See the - <ulink url="http://www.haskell.org/cabal/users-guide/">Cabal documentation</ulink> - for details, and also the Cabal libraries (<ulink url="&libraryCabalLocation;/Distribution-Simple.html">Distribution.Simple</ulink>, - for example).</para> - - <sect2 id="using-packages"> - <title>Using Packages - </title> - <indexterm><primary>packages</primary> - <secondary>using</secondary></indexterm> - - <para>GHC only knows about packages that are - <emphasis>installed</emphasis>. To see which packages are installed, use - the <literal>ghc-pkg list</literal> command:</para> - -<screen> -$ ghc-pkg list -/usr/lib/ghc-6.12.1/package.conf.d: - Cabal-1.7.4 - array-0.2.0.1 - base-3.0.3.0 - base-4.2.0.0 - bin-package-db-0.0.0.0 - binary-0.5.0.1 - bytestring-0.9.1.4 - containers-0.2.0.1 - directory-1.0.0.2 - (dph-base-0.4.0) - (dph-par-0.4.0) - (dph-prim-interface-0.4.0) - (dph-prim-par-0.4.0) - (dph-prim-seq-0.4.0) - (dph-seq-0.4.0) - extensible-exceptions-0.1.1.0 - ffi-1.0 - filepath-1.1.0.1 - (ghc-6.12.1) - ghc-prim-0.1.0.0 - haskeline-0.6.2 - haskell98-1.0.1.0 - hpc-0.5.0.2 - integer-gmp-0.1.0.0 - mtl-1.1.0.2 - old-locale-1.0.0.1 - old-time-1.0.0.1 - pretty-1.0.1.0 - process-1.0.1.1 - random-1.0.0.1 - rts-1.0 - syb-0.1.0.0 - template-haskell-2.4.0.0 - terminfo-0.3.1 - time-1.1.4 - unix-2.3.1.0 - utf8-string-0.3.4 -</screen> - - <para>An installed package is either <emphasis>exposed</emphasis> - or <emphasis>hidden</emphasis> by default. Packages hidden by - default are listed in parentheses - (e.g. <literal>(lang-1.0)</literal>), or possibly in blue if your - terminal supports colour, in the output of <literal>ghc-pkg - list</literal>. Command-line flags, described below, allow you - to expose a hidden package or hide an exposed one. Only modules - from exposed packages may be imported by your Haskell code; if - you try to import a module from a hidden package, GHC will emit - an error message. If there are a multiple exposed versions of a package, - GHC will prefer the latest one. Additionally, some packages may be - broken: that is, they are missing from the package database, or one of - their dependencies are broken; in this case; these packages are excluded - from the default set of packages. - </para> - - <para> - Note: if you're using Cabal, then the exposed or hidden status - of a package is irrelevant: the available packages are instead - determined by the dependencies listed in - your <literal>.cabal</literal> specification. The - exposed/hidden status of packages is only relevant when - using <literal>ghc</literal> or <literal>ghci</literal> - 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"/>) with the - <option>-fpackage-trust</option> flag enabled. - </para> - - <para>To see which modules are provided by a package use the - <literal>ghc-pkg</literal> command (see <xref linkend="package-management"/>):</para> - -<screen> -$ ghc-pkg field network exposed-modules -exposed-modules: Network.BSD, - Network.CGI, - Network.Socket, - Network.URI, - Network -</screen> - - <para>The GHC command line options that control packages are:</para> - - <variablelist> - <varlistentry> - <term> - <option>-package <replaceable>P</replaceable></option> - <indexterm><primary><option>-package</option></primary></indexterm> - </term> - <listitem> - <para>This option causes the installed - package <replaceable>P</replaceable> to be exposed. The - package <replaceable>P</replaceable> can be specified in - full with its version number - (e.g. <literal>network-1.0</literal>) or the version - number can be omitted if there is only one version of the - package installed. If there are multiple versions - of <replaceable>P</replaceable> installed and - <option>-hide-all-packages</option> was not specified, then all - other versions will become hidden. <option>-package</option> - supports thinning and renaming described in <xref - linkend="package-thinning-and-renaming" />.</para> - - <para>The <option>-package <replaceable>P</replaceable></option> - option also causes package <replaceable>P</replaceable> to - be linked into the resulting executable or shared - object. Whether a packages' library is linked statically - or dynamically is controlled by the flag - pair <option>-static</option>/<option>-dynamic</option>.</para> - - <para>In <option>--make</option> mode - and <option>--interactive</option> mode (see - <xref linkend="modes" />), the compiler normally - determines which packages are required by the current - Haskell modules, and links only those. In batch mode - however, the dependency information isn't available, and - explicit - <option>-package</option> options must be given when linking. The one other time you might need to use - <option>-package</option> to force linking a package is - when the package does not contain any Haskell modules (it - might contain a C library only, for example). In that - case, GHC will never discover a dependency on it, so it - has to be mentioned explicitly.</para> - - <para>For example, to link a program consisting of objects - <filename>Foo.o</filename> and <filename>Main.o</filename>, where - we made use of the <literal>network</literal> package, we need to - give GHC the <literal>-package</literal> flag thus: - -<screen>$ ghc -o myprog Foo.o Main.o -package network</screen> - - The same flag is necessary even if we compiled the modules from - source, because GHC still reckons it's in batch mode: - -<screen>$ ghc -o myprog Foo.hs Main.hs -package network</screen></para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-package-id <replaceable>P</replaceable></option> - <indexterm><primary><option>-package-id</option></primary></indexterm> - </term> - <listitem> - <para> - Exposes a package like <option>-package</option>, but the - package is named by its installed package ID rather than by name. This is a - more robust way to name packages, and can be used to - select packages that would otherwise be shadowed. Cabal - passes <option>-package-id</option> flags to GHC. - <option>-package-id</option> supports thinning and renaming - described in <xref linkend="package-thinning-and-renaming" />. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-hide-all-packages</option> - <indexterm><primary><option>-hide-package</option></primary> - </indexterm></term> - <listitem> - <para>Ignore the exposed flag on installed packages, and hide them - all by default. If you use - this flag, then any packages you require (including - <literal>base</literal>) need to be explicitly exposed using - <option>-package</option> options.</para> - - <para>This is a good way to insulate your program from - differences in the globally exposed packages, and being - explicit about package dependencies is a Good Thing. - Cabal always passes the - <option>-hide-all-packages</option> flag to GHC, for - exactly this reason.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-hide-package</option> <replaceable>P</replaceable> - <indexterm><primary><option>-hide-package</option></primary> - </indexterm></term> - <listitem> - <para>This option does the opposite of <option>-package</option>: it - causes the specified package to be <firstterm>hidden</firstterm>, - which means that none of its modules will be available for import - by Haskell <literal>import</literal> directives.</para> - - <para>Note that the package might still end up being linked into the - final program, if it is a dependency (direct or indirect) of - another exposed package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-ignore-package</option> <replaceable>P</replaceable> - <indexterm><primary><option>-ignore-package</option></primary> - </indexterm></term> - <listitem> - <para>Causes the compiler to behave as if package - <replaceable>P</replaceable>, and any packages that depend on - <literal>P</literal>, are not installed at all.</para> - - <para>Saying <literal>-ignore-package P</literal> is the same as - giving <literal>-hide-package</literal> flags for - <literal>P</literal> and all the packages that depend on - <literal>P</literal>. Sometimes we don't know ahead of time which - packages will be installed that depend on <literal>P</literal>, - which is when the <literal>-ignore-package</literal> flag can be - useful.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-no-auto-link-packages</option> - <indexterm><primary><option>-no-auto-link-packages</option></primary> - </indexterm></term> - <listitem> - <para>By default, GHC will automatically link in the - <literal>base</literal> and <literal>rts</literal> packages. - This flag disables that behaviour.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-this-package-key</option> <replaceable>foo</replaceable> - <indexterm><primary><option>-this-package-key</option></primary> - </indexterm></term> - <listitem> - <para>Tells GHC the the module being compiled forms part of - package key <replaceable>foo</replaceable>; internally, these - keys are used to determine type equality and linker symbols. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-library-name</option> <replaceable>hash</replaceable> - <indexterm><primary><option>-library-name</option></primary> - </indexterm></term> - <listitem> - <para>Tells GHC that the source of a Backpack file and - its textual dependencies is uniquely identified by - <replaceable>hash</replaceable>. Library names are determined - by Cabal; a usual recipe for a library name is that it is - the hash source package identifier of a package, as well as the - version hashes of all its textual dependencies. GHC will - then use this library name to generate more package keys.</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> - - <sect2 id="package-main"> - <title>The main package</title> - - <para>Every complete Haskell program must define <literal>main</literal> in - module <literal>Main</literal> - in package <literal>main</literal>. (Omitting the <option>-this-package-key</option> flag compiles - code for package <literal>main</literal>.) Failure to do so leads to a somewhat obscure - link-time error of the form: -<programlisting> -/usr/bin/ld: Undefined symbols: -_ZCMain_main_closure -</programlisting> -</para> - - </sect2> - - <sect2 id="package-overlaps"> - <title>Consequences of packages for the Haskell language</title> - - <para>It is possible that by using packages you might end up with - a program that contains two modules with the same name: perhaps - you used a package P that has a <emphasis>hidden</emphasis> module - M, and there is also a module M in your program. Or perhaps the - dependencies of packages that you used contain some overlapping - modules. Perhaps the program even contains multiple versions of a - certain package, due to dependencies from other packages.</para> - - <para>None of these scenarios gives rise to an error on its - own<footnote><para>it used to in GHC 6.4, but not since - 6.6</para></footnote>, but they may have some interesting - consequences. For instance, if you have a type - <literal>M.T</literal> from version 1 of package - <literal>P</literal>, then this is <emphasis>not</emphasis> the - same as the type <literal>M.T</literal> from version 2 of package - <literal>P</literal>, and GHC will report an error if you try to - use one where the other is expected.</para> - - <para>Formally speaking, in Haskell 98, an entity (function, type - or class) in a program is uniquely identified by the pair of the - module name in which it is defined and its name. In GHC, an - entity is uniquely defined by a triple: package, module, and - name.</para> - </sect2> - - <sect2 id="package-thinning-and-renaming"> - <title>Thinning and renaming modules</title> - - <para>When incorporating packages from multiple sources, you may end up - in a situation where multiple packages publish modules with the same name. - Previously, the only way to distinguish between these modules was to - use <xref linkend="package-qualified-imports" />. However, since GHC 7.10, - the <option>-package</option> flags (and their variants) have been extended - to allow a user to explicitly control what modules a package brings into - scope, by analogy to the import lists that users can attach to module imports. - </para> - - <para> - The basic syntax is that instead of specifying a package name P to the package - flag <literal>-package</literal>, instead we specify both a package name and a - parenthesized, comma-separated list of module names to import. For example, - <literal>-package "base (Data.List, Data.Bool)"</literal> makes only - <literal>Data.List</literal> and <literal>Data.Bool</literal> visible from - package <literal>base</literal>. We also support renaming of modules, in case - you need to refer to both modules simultaneously; this is supporting by - writing <literal>OldModName as NewModName</literal>, e.g. <literal>-package - "base (Data.Bool as Bool)</literal>. You can also write <literal>-package - "base with (Data.Bool as Bool)</literal> to include all of the original - bindings (e.g. the renaming is strictly additive). It's important to specify - quotes so that your shell passes the package name and thinning/renaming list - as a single argument to GHC.</para> - - <para>Package imports with thinning/renaming do not hide other versions of the - package: e.g. if containers-0.9 is already exposed, <literal>-package - "containers-0.8 (Data.List as ListV8)"</literal> will only add an additional - binding to the environment. Similarly, <literal>-package "base (Data.Bool as - Bool)" -package "base (Data.List as List)"</literal> is equivalent to - <literal>-package "base (Data.Bool as Bool, Data.List as List)"</literal>. - Literal names must refer to modules defined by the original package, so for - example <literal>-package "base (Data.Bool as Bool, Bool as Baz)"</literal> is - invalid unless there was a <literal>Bool</literal> module defined in the - original package. Hiding a package also clears all of its renamings. </para> - - <para> - You can use renaming to provide an alternate prelude, e.g. - <literal>-hide-all-packages -package "basic-prelude (BasicPrelude as - Prelude)"</literal>, in lieu of the <xref - linkend="rebindable-syntax">NoImplicitPrelude</xref> extension. - </para> - - </sect2> - - <sect2 id="package-databases"> - <title>Package Databases</title> - - <para> - A package database is where the details about installed packages - are stored. It is a directory, usually - called <literal>package.conf.d</literal>, that contains a file - for each package, together with a binary cache of the package - data in the file <literal>package.cache</literal>. Normally - you won't need to look at or modify the contents of a package - database directly; all management of package databases can be - done through the <literal>ghc-pkg</literal> tool (see - <xref linkend="package-management" />). - </para> - - <para> - GHC knows about two package databases in particular: - </para> - - <itemizedlist> - <listitem> - <para>The global package database, which comes with your GHC - installation, - e.g. <filename>/usr/lib/ghc-6.12.1/package.conf.d</filename>.</para> - </listitem> - <listitem> - <para>A package database private to each user. On Unix - systems this will be - <filename>$HOME/.ghc/<replaceable>arch</replaceable>-<replaceable>os</replaceable>-<replaceable>version</replaceable>/package.conf.d</filename>, and on - Windows it will be something like - <filename>C:\Documents And Settings\<replaceable>user</replaceable>\ghc\package.conf.d</filename>. - The <literal>ghc-pkg</literal> tool knows where this file should be - located, and will create it if it doesn't exist (see <xref linkend="package-management" />).</para> - </listitem> - </itemizedlist> - - <para>When GHC starts up, it reads the contents of these two package - databases, and builds up a list of the packages it knows about. You can - see GHC's package table by running GHC with the <option>-v</option> - flag.</para> - - <para>Package databases may overlap, and they are arranged in a stack - structure. Packages closer to the top of the stack will override - (<emphasis>shadow</emphasis>) those below them. By default, the stack - contains just the global and the user's package databases, in that - order.</para> - - <para>You can control GHC's package database stack using the following - options:</para> - - <variablelist> - <varlistentry> - <term> - <option>-package-db <replaceable>file</replaceable></option> - <indexterm><primary><option>-package-db</option></primary></indexterm> - </term> - <listitem> - <para>Add the package database <replaceable>file</replaceable> on top - of the current stack. Packages in additional databases read this - way will override those in the initial stack and those in - previously specified databases.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-no-global-package-db</option> - <indexterm><primary><option>-no-global-package-db</option></primary> - </indexterm> - </term> - <listitem> - <para>Remove the global package database from the package database - stack.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-no-user-package-db</option> - <indexterm><primary><option>-no-user-package-db</option></primary> - </indexterm> - </term> - <listitem> - <para>Prevent loading of the user's local package database in the - initial stack.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-clear-package-db</option> - <indexterm><primary><option>-clear-package-db</option></primary> - </indexterm> - </term> - <listitem> - <para>Reset the current package database stack. This option removes - every previously specified package database (including those - read from the <literal>GHC_PACKAGE_PATH</literal> environment - variable) from the package database stack.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-global-package-db</option> - <indexterm><primary><option>-global-package-db</option></primary> - </indexterm> - </term> - <listitem> - <para>Add the global package database on top of the current stack. - This option can be used after - <literal>-no-global-package-db</literal> to specify the position in - the stack where the global package database should be - loaded.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-user-package-db</option> - <indexterm><primary><option>-user-package-db</option></primary> - </indexterm> - </term> - <listitem> - <para>Add the user's package database on top of the current stack. - This option can be used after - <literal>-no-user-package-db</literal> to specify the position in - the stack where the user's package database should be - loaded.</para> - </listitem> - </varlistentry> - </variablelist> - - <sect3 id="ghc-package-path"> - <title>The <literal>GHC_PACKAGE_PATH</literal> environment variable</title> - <indexterm><primary>Environment variable</primary><secondary><literal>GHC_PACKAGE_PATH</literal></secondary> - </indexterm> - <indexterm><primary><literal>GHC_PACKAGE_PATH</literal></primary></indexterm> - <para>The <literal>GHC_PACKAGE_PATH</literal> environment variable may be - set to a <literal>:</literal>-separated (<literal>;</literal>-separated - on Windows) list of files containing package databases. This list of - package databases is used by GHC and ghc-pkg, with earlier databases in - the list overriding later ones. This order was chosen to match the - behaviour of the <literal>PATH</literal> environment variable; think of - it as a list of package databases that are searched left-to-right for - packages.</para> - - <para>If <literal>GHC_PACKAGE_PATH</literal> ends in a separator, then - the default package database stack (i.e. the user and global - package databases, in that order) is appended. For example, to augment - the usual set of packages with a database of your own, you could say - (on Unix): - - <screen> $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen> - - (use <literal>;</literal> instead of <literal>:</literal> on - Windows).</para> - - <para>To check whether your <literal>GHC_PACKAGE_PATH</literal> setting - is doing the right thing, <literal>ghc-pkg list</literal> will list all - the databases in use, in the reverse order they are searched.</para> - - </sect3> - </sect2> - - <sect2 id="package-ids"> - <title>Installed package IDs, dependencies, and broken packages</title> - - <para>Each installed package has a unique identifier (the - “installed package ID”), which distinguishes it from all other - installed packages on the system. To see the installed package IDs - associated with each installed package, use <literal>ghc-pkg - list -v</literal>:</para> - - <screen> -$ ghc-pkg list -v -using cache: /usr/lib/ghc-6.12.1/package.conf.d/package.cache -/usr/lib/ghc-6.12.1/package.conf.d - Cabal-1.7.4 (Cabal-1.7.4-48f5247e06853af93593883240e11238) - array-0.2.0.1 (array-0.2.0.1-9cbf76a576b6ee9c1f880cf171a0928d) - base-3.0.3.0 (base-3.0.3.0-6cbb157b9ae852096266e113b8fac4a2) - base-4.2.0.0 (base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c) - ... -</screen> - - <para> - The string in parentheses after the package name is the installed package - ID: it normally begins with the package name and version, and - ends in a hash string derived from the compiled package. - Dependencies between packages are expressed in terms of installed package - IDs, rather than just packages and versions. For example, take - a look at the dependencies of the <literal>haskell98</literal> - package: - </para> - - <screen> -$ ghc-pkg field haskell98 depends -depends: array-0.2.0.1-9cbf76a576b6ee9c1f880cf171a0928d - base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c - directory-1.0.0.2-f51711bc872c35ce4a453aa19c799008 - old-locale-1.0.0.1-d17c9777c8ee53a0d459734e27f2b8e9 - old-time-1.0.0.1-1c0d8ea38056e5087ef1e75cb0d139d1 - process-1.0.1.1-d8fc6d3baf44678a29b9d59ca0ad5780 - random-1.0.0.1-423d08c90f004795fd10e60384ce6561 -</screen> - - <para> - The purpose of the installed package ID is to detect problems caused by - re-installing a package without also recompiling the packages - that depend on it. Recompiling dependencies is necessary, - because the newly compiled package may have a different ABI - (Application Binary Interface) than the previous version, even - if both packages were built from the same source code using the - same compiler. With installed package IDs, a recompiled - package will have a different installed package ID from the previous - version, so packages that depended on the previous version are - now orphaned - one of their dependencies is not satisfied. - Packages that are broken in this way are shown in - the <literal>ghc-pkg list</literal> output either in red (if - possible) or otherwise surrounded by braces. In the following - example, we have recompiled and reinstalled - the <literal>filepath</literal> package, and this has caused - various dependencies including <literal>Cabal</literal> to - break:</para> - - <screen> -$ ghc-pkg list -WARNING: there are broken packages. Run 'ghc-pkg check' for more details. -/usr/lib/ghc-6.12.1/package.conf.d: - {Cabal-1.7.4} - array-0.2.0.1 - base-3.0.3.0 - ... etc ... -</screen> - - <para> - Additionally, <literal>ghc-pkg list</literal> reminds you that - there are broken packages and suggests <literal>ghc-pkg - check</literal>, which displays more information about the - nature of the failure: - </para> - - <screen> -$ ghc-pkg check -There are problems in package ghc-6.12.1: - dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist -There are problems in package haskeline-0.6.2: - dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist -There are problems in package Cabal-1.7.4: - dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist -There are problems in package process-1.0.1.1: - dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist -There are problems in package directory-1.0.0.2: - dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist - -The following packages are broken, either because they have a problem -listed above, or because they depend on a broken package. -ghc-6.12.1 -haskeline-0.6.2 -Cabal-1.7.4 -process-1.0.1.1 -directory-1.0.0.2 -bin-package-db-0.0.0.0 -hpc-0.5.0.2 -haskell98-1.0.1.0 -</screen> - - <para> - To fix the problem, you need to recompile the broken packages - against the new dependencies. The easiest way to do this is to - use <literal>cabal-install</literal>, or download the packages - from <ulink - url="http://hackage.haskell.org/packages/hackage.html">HackageDB</ulink> - and build and install them as normal.</para> - - <para>Be careful not to recompile any packages that GHC itself - depends on, as this may render the <literal>ghc</literal> - package itself broken, and <literal>ghc</literal> cannot be - simply recompiled. The only way to recover from this would be - to re-install GHC.</para> - </sect2> - - <sect2 id="package-management"> - <title>Package management (the <literal>ghc-pkg</literal> command)</title> - <indexterm><primary>packages</primary> - <secondary>management</secondary></indexterm> - - <para>The <literal>ghc-pkg</literal> tool is for querying and - modifying package databases. To see what package databases are - in use, use - <literal>ghc-pkg list</literal>. The stack of databases that - <literal>ghc-pkg</literal> knows about can be modified using the - <literal>GHC_PACKAGE_PATH</literal> environment variable (see <xref - linkend="ghc-package-path" />, and using - <literal>--package-db</literal> options on the - <literal>ghc-pkg</literal> command line.</para> - - <para>When asked to modify a database, <literal>ghc-pkg</literal> modifies - the global database by default. Specifying <option>--user</option> - causes it to act on the user database, or <option>--package-db</option> - can be used to act on another database entirely. When multiple of these - options are given, the rightmost one is used as the database to act - upon.</para> - - <para>Commands that query the package database (list, latest, - describe, field, dot) operate on the list of databases specified by - the flags <option>--user</option>, <option>--global</option>, and - <option>--package-db</option>. If none of these flags are - given, the default is <option>--global</option> - <option>--user</option>.</para> - - <para>If the environment variable <literal>GHC_PACKAGE_PATH</literal> is - set, and its value does not end in a separator (<literal>:</literal> on - Unix, <literal>;</literal> on Windows), then the last database is - considered to be the global database, and will be modified by default by - <literal>ghc-pkg</literal>. The intention here is that - <literal>GHC_PACKAGE_PATH</literal> can be used to create a virtual - package environment into which Cabal packages can be installed without - setting anything other than <literal>GHC_PACKAGE_PATH</literal>.</para> - - <para>The <literal>ghc-pkg</literal> program may be run in the ways listed - below. Where a package name is required, the package can be named in - full including the version number - (e.g. <literal>network-1.0</literal>), or without the version number. - Naming a package without the version number matches all versions of the - package; the specified action will be applied to all the matching - packages. A package specifier that matches all version of the package - can also be written <replaceable>pkg</replaceable><literal>-*</literal>, - to make it clearer that multiple packages are being matched. To match - against the installed package ID instead of just package name and version, - pass the <option>--ipid</option> flag.</para> - - <variablelist> - <varlistentry> - <term><literal>ghc-pkg init <replaceable>path</replaceable></literal></term> - <listitem> - <para>Creates a new, empty, package database - at <replaceable>path</replaceable>, which must not already - exist.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ghc-pkg register <replaceable>file</replaceable></literal></term> - <listitem> - <para>Reads a package specification from - <replaceable>file</replaceable> (which may be “<literal>-</literal>” - to indicate standard input), - and adds it to the database of installed packages. The syntax of - <replaceable>file</replaceable> is given in <xref - linkend="installed-pkg-info" />.</para> - - <para>The package specification must be a package that isn't already - installed.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ghc-pkg update <replaceable>file</replaceable></literal></term> - <listitem> - <para>The same as <literal>register</literal>, except that if a - package of the same name is already installed, it is - replaced by the new one.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ghc-pkg unregister <replaceable>P</replaceable></literal></term> - <listitem> - <para>Remove the specified package from the database.</para> - </listitem> - </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 - <replaceable>P</replaceable> to <literal>True</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ghc-pkg hide <replaceable>P</replaceable></literal></term> - <listitem> - <para>Sets the <literal>exposed</literal> flag for package - <replaceable>P</replaceable> to <literal>False</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ghc-pkg trust <replaceable>P</replaceable></literal></term> - <listitem> - <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> - - <varlistentry> - <term><literal>ghc-pkg list [<replaceable>P</replaceable>] [<option>--simple-output</option>]</literal></term> - <listitem> - <para>This option displays the currently installed - packages, for each of the databases known to - <literal>ghc-pkg</literal>. That includes the global database, the - user's local database, and any further files specified using the - <option>-f</option> option on the command line.</para> - - <para>Hidden packages (those for which the <literal>exposed</literal> - flag is <literal>False</literal>) are shown in parentheses in the - list of packages.</para> - - <para>If an optional package identifier <replaceable>P</replaceable> - is given, then only packages matching that identifier are - shown.</para> - - <para>If the option <option>--simple-output</option> is given, then - the packages are listed on a single line separated by spaces, and - the database names are not included. This is intended to make it - easier to parse the output of <literal>ghc-pkg list</literal> using - a script.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ghc-pkg find-module <replaceable>M</replaceable> [<option>--simple-output</option>]</literal></term> - <listitem> - <para>This option lists registered packages exposing module - <replaceable>M</replaceable>. Examples:</para> -<screen> -$ ghc-pkg find-module Var -c:/fptools/validate/ghc/driver/package.conf.inplace: - (ghc-6.9.20080428) - -$ ghc-pkg find-module Data.Sequence -c:/fptools/validate/ghc/driver/package.conf.inplace: - containers-0.1 -</screen> - <para>Otherwise, it behaves like <literal>ghc-pkg list</literal>, - including options.</para> - </listitem> - </varlistentry> - - - <varlistentry> - <term><literal>ghc-pkg latest <replaceable>P</replaceable></literal></term> - <listitem> - <para>Prints the latest available version of package - <replaceable>P</replaceable>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ghc-pkg describe <replaceable>P</replaceable></literal></term> - <listitem> - <para>Emit the full description of the specified package. The - description is in the form of an - <literal>InstalledPackageInfo</literal>, the same as the input file - format for <literal>ghc-pkg register</literal>. See <xref - linkend="installed-pkg-info" /> for details.</para> - - <para>If the pattern matches multiple packages, the - description for each package is emitted, separated by the - string <literal>---</literal> on a line by itself.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ghc-pkg field <replaceable>P</replaceable> <replaceable>field</replaceable>[,<replaceable>field</replaceable>]*</literal></term> - <listitem> - <para>Show just a single field of the installed package description - for <literal>P</literal>. Multiple fields can be selected by separating - them with commas</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ghc-pkg dot</literal></term> - <listitem> - <para> - Generate a graph of the package dependencies in a form - suitable for input for the <ulink url="http://www.graphviz.org/">graphviz</ulink> tools. For example, - to generate a PDF of the dependency graph:</para> -<screen> -ghc-pkg dot | tred | dot -Tpdf >pkgs.pdf -</screen> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ghc-pkg dump</literal></term> - <listitem> - <para>Emit the full description of every package, in the - form of an <literal>InstalledPackageInfo</literal>. - Multiple package descriptions are separated by the - string <literal>---</literal> on a line by itself.</para> - - <para>This is almost the same as <literal>ghc-pkg describe '*'</literal>, except that <literal>ghc-pkg dump</literal> - is intended for use by tools that parse the results, so - for example where <literal>ghc-pkg describe '*'</literal> - will emit an error if it can't find any packages that - match the pattern, <literal>ghc-pkg dump</literal> will - simply emit nothing.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ghc-pkg recache</literal></term> - <listitem> - <para> - Re-creates the binary cache - file <filename>package.cache</filename> for the selected - database. This may be necessary if the cache has somehow - become out-of-sync with the contents of the database - (<literal>ghc-pkg</literal> will warn you if this might be - the case).</para> - - <para> - The other time when <literal>ghc-pkg recache</literal> is - useful is for registering packages manually: it is - possible to register a package by simply putting the - appropriate file in the package database directory and - invoking <literal>ghc-pkg recache</literal> to update the - cache. This method of registering packages may be more - convenient for automated packaging systems. - </para> - </listitem> - </varlistentry> - </variablelist> - - <para> - Substring matching is supported for <replaceable>M</replaceable> in - <literal>find-module</literal> and for <replaceable>P</replaceable> in - <literal>list</literal>, <literal>describe</literal>, and - <literal>field</literal>, where a <literal>'*'</literal> indicates open - substring ends (<literal>prefix*</literal>, <literal>*suffix</literal>, - <literal>*infix*</literal>). Examples (output omitted): - </para> - <screen> - -- list all regex-related packages - ghc-pkg list '*regex*' --ignore-case - -- list all string-related packages - ghc-pkg list '*string*' --ignore-case - -- list OpenGL-related packages - ghc-pkg list '*gl*' --ignore-case - -- list packages exporting modules in the Data hierarchy - ghc-pkg find-module 'Data.*' - -- list packages exporting Monad modules - ghc-pkg find-module '*Monad*' - -- list names and maintainers for all packages - ghc-pkg field '*' name,maintainer - -- list location of haddock htmls for all packages - ghc-pkg field '*' haddock-html - -- dump the whole database - ghc-pkg describe '*' -</screen> - - <para>Additionally, the following flags are accepted by - <literal>ghc-pkg</literal>:</para> - - <variablelist> - <varlistentry> - <term> - <option>-f</option> <replaceable>file</replaceable> - <indexterm><primary><option>-f</option></primary> - </indexterm> - </term> - <term> - <option>-package-db</option> <replaceable>file</replaceable> - <indexterm><primary><option>-package-db</option></primary> - </indexterm> - </term> - <listitem> - <para>Adds <replaceable>file</replaceable> to the stack of package - databases. Additionally, <replaceable>file</replaceable> will - also be the database modified by a <literal>register</literal>, - <literal>unregister</literal>, <literal>expose</literal> or - <literal>hide</literal> command, unless it is overridden by a later - <option>--package-db</option>, <option>--user</option> or - <option>--global</option> option.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--force</option> - <indexterm><primary> - <option>--force</option> - </primary></indexterm> - </term> - <listitem> - <para>Causes <literal>ghc-pkg</literal> to ignore missing - dependencies, directories and libraries when registering a package, - and just go ahead and add it anyway. This might be useful if your - package installation system needs to add the package to - GHC before building and installing the files.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--global</option><indexterm><primary><option>--global</option></primary> - </indexterm> - </term> - <listitem> - <para>Operate on the global package database (this is the default). - This flag affects the <literal>register</literal>, - <literal>update</literal>, <literal>unregister</literal>, - <literal>expose</literal>, and <literal>hide</literal> - commands.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--help</option><indexterm><primary><option>--help</option></primary> - </indexterm> - </term> - <term> - <option>-?</option><indexterm><primary><option>-?</option></primary> - </indexterm> - </term> - <listitem> - <para>Outputs the command-line syntax.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--user</option><indexterm><primary><option>--user</option></primary> - </indexterm> - </term> - <listitem> - <para>Operate on the current user's local package database. - This flag affects the <literal>register</literal>, - <literal>update</literal>, <literal>unregister</literal>, - <literal>expose</literal>, and <literal>hide</literal> - commands.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-v</option><optional><replaceable>n</replaceable></optional><indexterm><primary><option>-v</option></primary><secondary>ghc-pkg - option</secondary></indexterm> - </term> - <term> - <option>--verbose</option><optional>=<replaceable>n</replaceable></optional><indexterm><primary><option>--verbose</option></primary><secondary>ghc-pkg option</secondary></indexterm> - </term> - <listitem> - <para> - Control verbosity. Verbosity levels range from 0-2, where - the default is 1, and <option>-v</option> alone selects - level 2. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-V</option><indexterm><primary><option>-V</option></primary> - </indexterm> - </term> - <term> - <option>--version</option><indexterm><primary><option>--version</option></primary> - </indexterm> - </term> - <listitem> - <para>Output the <literal>ghc-pkg</literal> version number.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--ipid</option> - <indexterm><primary> - <option>--ipid</option> - </primary></indexterm> - </term> - <listitem> - <para>Causes <literal>ghc-pkg</literal> to interpret arguments - as installed package IDs (e.g., an identifier like - <literal>unix-2.3.1.0-de7803f1a8cd88d2161b29b083c94240 - </literal>). This is useful if providing just the package - name and version are ambiguous (in old versions of GHC, this - was guaranteed to be unique, but this invariant no longer - necessarily holds).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--package-key</option> - <indexterm><primary> - <option>--package-key</option> - </primary></indexterm> - </term> - <listitem> - <para>Causes <literal>ghc-pkg</literal> to interpret arguments - as package keys (e.g., an identifier like - <literal>I5BErHzyOm07EBNpKBEeUv</literal>). Package keys are - used to prefix symbol names GHC produces (e.g., <literal>6VWy06pWzzJq9evDvK2d4w6_DataziByteStringziInternal_unsafePackLenChars_info</literal>), so if you need to figure out what package a symbol belongs to, use <literal>ghc-pkg</literal> with this flag.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="building-packages"> - <title>Building a package from Haskell source</title> - <indexterm><primary>packages</primary> - <secondary>building</secondary></indexterm> - - <para>We don't recommend building packages the hard way. Instead, use the - <ulink url="http://www.haskell.org/cabal/users-guide/">Cabal</ulink> infrastructure - if possible. If your package is particularly complicated or requires a - lot of configuration, then you might have to fall back to the low-level - mechanisms, so a few hints for those brave souls follow.</para> - - <para>You need to build an "installed package info" file for - passing to <literal>ghc-pkg</literal> when installing your - package. The contents of this file are described in - <xref linkend="installed-pkg-info" />.</para> - - <para>The Haskell code in a package may be built into one or more - archive libraries (e.g. <filename>libHSfoo.a</filename>), or a - single shared object - (e.g. <filename>libHSfoo.dll/.so/.dylib</filename>). The - restriction to a single shared object is because the package - system is used to tell the compiler when it should make an - inter-shared-object call rather than an intra-shared-object-call - call (inter-shared-object calls require an extra - indirection).</para> - <itemizedlist> - <listitem><para>Building a static library is done by using the - <literal>ar</literal> tool, like so:</para> - -<screen>ar cqs libHSfoo-1.0.a A.o B.o C.o ...</screen> - - <para>where <filename>A.o</filename>, - <filename>B.o</filename> and so on are the compiled Haskell - modules, and <filename>libHSfoo.a</filename> is the library you - wish to create. The syntax may differ slightly on your system, - so check the documentation if you run into difficulties.</para> - </listitem> - <listitem> - <para>To load a package <literal>foo</literal>, GHCi can load - its <literal>libHSfoo.a</literal> library directly, but it - can also load a package in the form of a - single <literal>HSfoo.o</literal> file that has been - pre-linked. Loading the <literal>.o</literal> file is - slightly quicker, but at the expense of having another copy - of the compiled package. The rule of thumb is that if the - modules of the package were compiled - with <option>-split-objs</option> then building - the <literal>HSfoo.o</literal> is worthwhile because it - saves time when loading the package into GHCi. - Without <option>-split-objs</option>, there is not much - difference in load time between the <literal>.o</literal> - and <literal>.a</literal> libraries, so it is better to save - the disk space and only keep the <literal>.a</literal> - around. In a GHC distribution we - provide <literal>.o</literal> files for most packages except - the GHC package itself. - </para> - - <para>The <literal>HSfoo.o</literal> file is built by Cabal - automatically; - use <option>--disable-library-for-ghci</option> to disable - it. To build one manually, the following - GNU <command>ld</command> command can be used:</para> - -<screen>ld -r --whole-archive -o HSfoo.o libHSfoo.a</screen> - - <para>(replace - <literal>--whole-archive</literal> with - <literal>-all_load</literal> on MacOS X)</para> - </listitem> - <listitem> - <para>When building the package as shared library, GHC can be used to - perform the link step. This hides some of the details - out the underlying linker and provides a common - interface to all shared object variants that are supported - by GHC (DLLs, ELF DSOs, and Mac OS dylibs). The shared - object must be named in specific way for two reasons: (1) - the name must contain the GHC compiler version, so that two - library variants don't collide that are compiled by - different versions of GHC and that therefore are most likely - incompatible with respect to calling conventions, (2) it - must be different from the static name otherwise we would - not be able to control the linker as precisely as necessary - to make - the <option>-static</option>/<option>-dynamic</option> flags - work, see <xref linkend="options-linker" />.</para> - -<screen>ghc -shared libHSfoo-1.0-ghc<replaceable>GHCVersion</replaceable>.so A.o B.o C.o</screen> - <para>Using GHC's version number in the shared object name - allows different library versions compiled by different GHC - versions to be installed in standard system locations, - e.g. under *nix /usr/lib. To obtain the version number of - GHC invoke <literal>ghc --numeric-version</literal> and use - its output in place - of <replaceable>GHCVersion</replaceable>. See also - <xref linkend="options-codegen" /> on how object files must - be prepared for shared object linking.</para> - </listitem> - </itemizedlist> - - <para>To compile a module which is to be part of a new package, - use the <literal>-package-name</literal> (to identify the name of the package) and - <literal>-library-name</literal> (to identify the version and the version - hashes of its identities.) options (<xref linkend="using-packages"/>). - Failure to use these options - when compiling a package will probably result in disaster, but - you will only discover later when you attempt to import modules - from the package. At this point GHC will complain that the - package name it was expecting the module to come from is not the - same as the package name stored in the <literal>.hi</literal> - file.</para> - - <para>It is worth noting with shared objects, when each package - is built as a single shared object file, since a reference to a shared object costs an extra - indirection, intra-package references are cheaper than - inter-package references. Of course, this applies to the - <filename>main</filename> package as well.</para> - </sect2> - - <sect2 id="installed-pkg-info"> - <title> - <literal>InstalledPackageInfo</literal>: a package specification - </title> - - <para>A package specification is a Haskell record; in particular, it is the - record <ulink - url="&libraryCabalLocation;/Distribution-InstalledPackageInfo.html#%tInstalledPackageInfo">InstalledPackageInfo</ulink> in the module Distribution.InstalledPackageInfo, which is part of the Cabal package distributed with GHC.</para> - - <para>An <literal>InstalledPackageInfo</literal> has a human - readable/writable syntax. The functions - <literal>parseInstalledPackageInfo</literal> and - <literal>showInstalledPackageInfo</literal> read and write this syntax - respectively. Here's an example of the - <literal>InstalledPackageInfo</literal> for the <literal>unix</literal> package:</para> - -<screen> -$ ghc-pkg describe unix -name: unix -version: 2.3.1.0 -id: unix-2.3.1.0-de7803f1a8cd88d2161b29b083c94240 -license: BSD3 -copyright: -maintainer: libraries@haskell.org -stability: -homepage: -package-url: -description: This package gives you access to the set of operating system - services standardised by POSIX 1003.1b (or the IEEE Portable - Operating System Interface for Computing Environments - - IEEE Std. 1003.1). - . - The package is not supported under Windows (except under Cygwin). -category: System -author: -exposed: True -exposed-modules: System.Posix System.Posix.DynamicLinker.Module - System.Posix.DynamicLinker.Prim System.Posix.Directory - System.Posix.DynamicLinker System.Posix.Env System.Posix.Error - System.Posix.Files System.Posix.IO System.Posix.Process - System.Posix.Process.Internals System.Posix.Resource - System.Posix.Temp System.Posix.Terminal System.Posix.Time - System.Posix.Unistd System.Posix.User System.Posix.Signals - 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 -extra-libraries: rt util dl -extra-ghci-libraries: -include-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0/include -includes: HsUnix.h execvpe.h -depends: base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c -hugs-options: -cc-options: -ld-options: -framework-dirs: -frameworks: -haddock-interfaces: /usr/share/doc/ghc/html/libraries/unix/unix.haddock -haddock-html: /usr/share/doc/ghc/html/libraries/unix -</screen> - - <para>Here is a brief description of the syntax of this file:</para> - - <para>A package description consists of a number of field/value pairs. A - field starts with the field name in the left-hand column followed by a - “<literal>:</literal>”, and the value continues until the next line that begins in the - left-hand column, or the end of file.</para> - - <para>The syntax of the value depends on the field. The various field - types are:</para> - - <variablelist> - <varlistentry> - <term>freeform</term> - <listitem> - <para>Any arbitrary string, no interpretation or parsing is - done.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>string</term> - <listitem> - <para>A sequence of non-space characters, or a sequence of arbitrary - characters surrounded by quotes <literal>"...."</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>string list</term> - <listitem> - <para>A sequence of strings, separated by commas. The sequence may - be empty.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>In addition, there are some fields with special syntax (e.g. package - names, version, dependencies).</para> - - <para>The allowed fields, with their types, are:</para> - - <variablelist> - <varlistentry> - <term> - <literal>name</literal> - <indexterm><primary><literal>name</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>The package's name (without the version).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>id</literal> - <indexterm><primary><literal>id</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>The installed package ID. It is up to you to choose a suitable - one.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>version</literal> - <indexterm><primary><literal>version</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>The package's version, usually in the form - <literal>A.B</literal> (any number of components are allowed).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>license</literal> - <indexterm><primary><literal>auto</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(string) The type of license under which this package is distributed. - This field is a value of the <ulink - url="&libraryCabalLocation;/Distribution-License.html#t:License"><literal>License</literal></ulink> type.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>license-file</literal> - <indexterm><primary><literal>license-file</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(optional string) The name of a file giving detailed license - information for this package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>copyright</literal> - <indexterm><primary><literal>copyright</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(optional freeform) The copyright string.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>maintainer</literal> - <indexterm><primary><literal>maintainer</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(optional freeform) The email address of the package's maintainer.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>stability</literal> - <indexterm><primary><literal>stability</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(optional freeform) A string describing the stability of the package - (e.g. stable, provisional or experimental).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>homepage</literal> - <indexterm><primary><literal>homepage</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(optional freeform) URL of the package's home page.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>package-url</literal> - <indexterm><primary><literal>package-url</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(optional freeform) URL of a downloadable distribution for this - package. The distribution should be a Cabal package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>description</literal> - <indexterm><primary><literal>description</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(optional freeform) Description of the package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>category</literal> - <indexterm><primary><literal>category</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(optional freeform) Which category the package belongs to. This field - is for use in conjunction with a future centralised package - distribution framework, tentatively titled Hackage.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>author</literal> - <indexterm><primary><literal>author</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(optional freeform) Author of the package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>exposed</literal> - <indexterm><primary><literal>exposed</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(bool) Whether the package is exposed or not.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>exposed-modules</literal> - <indexterm><primary><literal>exposed-modules</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(string list) modules exposed by this package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>hidden-modules</literal> - <indexterm><primary><literal>hidden-modules</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(string list) modules provided by this package, - but not exposed to the programmer. These modules cannot be - imported, but they are still subject to the overlapping constraint: - no other package in the same program may provide a module of the - same name.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>reexported-modules</literal> - <indexterm><primary><literal>reexported-modules</literal></primary><secondary>reexport specification</secondary></indexterm> - </term> - <listitem> - <para>Modules reexported by this package. This list takes - the form of <literal>pkg:OldName as NewName - (A@orig-pkg-0.1-HASH)</literal>: the first portion of the - string is the user-written reexport specification (possibly - omitting the package qualifier and the renaming), while the - parenthetical is the original package which exposed the - module under are particular name. Reexported modules have - a relaxed overlap constraint: it's permissible for two - packages to reexport the same module as the same name if the - reexported moduleis identical.</para> - </listitem> - </varlistentry> - - <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> - <listitem> - <para>(string list) A list of directories containing interface files - (<literal>.hi</literal> files) for this package.</para> - - <para>If the package contains profiling libraries, then - the interface files for those library modules should have - the suffix <literal>.p_hi</literal>. So the package can - contain both normal and profiling versions of the same - library without conflict (see also - <literal>library_dirs</literal> below).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>library-dirs</literal> - <indexterm><primary><literal>library-dirs</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(string list) A list of directories containing libraries for this - package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>hs-libraries</literal> - <indexterm><primary><literal>hs-libraries</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(string list) A list of libraries containing Haskell code for this - package, with the <literal>.a</literal> or - <literal>.dll</literal> suffix omitted. When packages are - built as libraries, the - <literal>lib</literal> prefix is also omitted.</para> - - <para>For use with GHCi, each library should have an - object file too. The name of the object file does - <emphasis>not</emphasis> have a <literal>lib</literal> - prefix, and has the normal object suffix for your - platform.</para> - - <para>For example, if we specify a Haskell library as - <filename>HSfoo</filename> in the package spec, then the - various flavours of library that GHC actually uses will be - called:</para> - <variablelist> - <varlistentry> - <term><filename>libHSfoo.a</filename></term> - <listitem> - <para>The name of the library on Unix and Windows - (mingw) systems. Note that we don't support - building dynamic libraries of Haskell code on Unix - systems.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>HSfoo.dll</filename></term> - <listitem> - <para>The name of the dynamic library on Windows - systems (optional).</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>HSfoo.o</filename></term> - <term><filename>HSfoo.obj</filename></term> - <listitem> - <para>The object version of the library used by - GHCi.</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>extra-libraries</literal> - <indexterm><primary><literal>extra-libraries</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(string list) A list of extra libraries for this package. The - difference between <literal>hs-libraries</literal> and - <literal>extra-libraries</literal> is that - <literal>hs-libraries</literal> normally have several - versions, to support profiling, parallel and other build - options. The various versions are given different - suffixes to distinguish them, for example the profiling - version of the standard prelude library is named - <filename>libHSbase_p.a</filename>, with the - <literal>_p</literal> indicating that this is a profiling - version. The suffix is added automatically by GHC for - <literal>hs-libraries</literal> only, no suffix is added - for libraries in - <literal>extra-libraries</literal>.</para> - - <para>The libraries listed in - <literal>extra-libraries</literal> may be any libraries - supported by your system's linker, including dynamic - libraries (<literal>.so</literal> on Unix, - <literal>.DLL</literal> on Windows).</para> - - <para>Also, <literal>extra-libraries</literal> are placed - on the linker command line after the - <literal>hs-libraries</literal> for the same package. If - your package has dependencies in the other direction (i.e. - <literal>extra-libraries</literal> depends on - <literal>hs-libraries</literal>), and the libraries are - static, you might need to make two separate - packages.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>include-dirs</literal> - <indexterm><primary><literal>include-dirs</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(string list) A list of directories containing C includes for this - package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>includes</literal> - <indexterm><primary><literal>includes</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(string list) A list of files to include for via-C compilations - using this package. Typically the include file(s) will - contain function prototypes for any C functions used in - the package, in case they end up being called as a result - of Haskell functions from the package being - inlined.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>depends</literal> - <indexterm><primary><literal>depends</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(package id list) Packages on which this package - depends.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>hugs-options</literal> - <indexterm><primary><literal>hugs-options</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(string list) Options to pass to Hugs for this package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>cc-options</literal> - <indexterm><primary><literal>cc-options</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(string list) Extra arguments to be added to the gcc command line - when this package is being used (only for via-C - compilations).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>ld-options</literal> - <indexterm><primary><literal>ld-options</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(string list) Extra arguments to be added to the - <command>gcc</command> command line (for linking) when - this package is being used.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>framework-dirs</literal> - <indexterm><primary><literal>framework-dirs</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(string list) On Darwin/MacOS X, a list of directories containing - frameworks for this package. This corresponds to the - <option>-framework-path</option> option. It is ignored on all other - platforms.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>frameworks</literal> - <indexterm><primary><literal>frameworks</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(string list) On Darwin/MacOS X, a list of frameworks to link to. This - corresponds to the <option>-framework</option> option. Take a look - at Apple's developer documentation to find out what frameworks - actually are. This entry is ignored on all other platforms.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>haddock-interfaces</literal> - <indexterm><primary><literal>haddock-interfaces</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(string list) A list of filenames containing <ulink - url="http://www.haskell.org/haddock/">Haddock</ulink> interface - files (<literal>.haddock</literal> files) for this package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>haddock-html</literal> - <indexterm><primary><literal>haddock-html</literal></primary><secondary>package specification</secondary></indexterm> - </term> - <listitem> - <para>(optional string) The directory containing the Haddock-generated HTML - for this package.</para> - </listitem> - </varlistentry> - </variablelist> - -<!-- This isn't true any more. I'm not sure if we still need it -SDM - <para> - The <literal>ghc-pkg</literal> tool performs expansion of - environment variables occurring in input package specifications. - So, if the <literal>mypkg</literal> was added to the package - database as follows: - </para> -<screen> - $ installdir=/usr/local/lib ghc-pkg -a < mypkg.pkg -</screen> - - <para> - The occurrence of <literal>${installdir}</literal> is replaced - with <literal>/usr/local/lib</literal> in the package data that - is added for <literal>mypkg</literal>. - </para> - - <para> - This feature enables the distribution of package specification - files that can be easily configured when installing. - </para> - - <para>For examples of more package specifications, take a look - at the <literal>package.conf</literal> in your GHC - installation.</para> - ---> - - </sect2> - <sect2 id="package-environments"> - <indexterm><primary>package environments</primary></indexterm> - <title> - Package environments - </title> - <para> - A <emphasis>package environment</emphasis> is a file that tells - <literal>ghc</literal> precisely which packages should be visible. It - contains package IDs, one per line: - </para> -<screen> -package_id_1 -package_id_2 -... -package_id_n -</screen> - <para> - If a package environment is found, it is equivalent to passing these - command line arguments to <literal>ghc</literal>: - </para> -<screen> --hide-all-packages --package-id package_id_1 --package-id package_id_2 -... --package-id package_id_n -</screen> - <para> - In order, <literal>ghc</literal> will look for the package environment - in the following locations: - </para> - <itemizedlist> - <listitem> - <para> - File - <replaceable>file</replaceable> - if you pass the option - <option>-package-env <replaceable>file</replaceable></option>. - </para> - </listitem> - <listitem> - <para> - File - <filename>$HOME/.ghc/<replaceable>arch</replaceable>-<replaceable>os</replaceable>-<replaceable>version</replaceable>/environments/<replaceable>name</replaceable></filename> - if you pass the option - <option>-package-env <replaceable>name</replaceable></option>. - </para> - </listitem> - <listitem> - <para> - File - <replaceable>file</replaceable> - if the environment variable <literal>GHC_ENVIRONMENT</literal> - is set to <replaceable>file</replaceable>. - </para> - </listitem> - <listitem> - <para> - File - <filename>$HOME/.ghc/<replaceable>arch</replaceable>-<replaceable>os</replaceable>-<replaceable>version</replaceable>/environments/<replaceable>name</replaceable></filename> - if the environment variable <literal>GHC_ENVIRONMENT</literal> - is set to <replaceable>name</replaceable>. - </para> - </listitem> - <listitem> - <para> - File <filename>./.ghc.environment</filename> if it exists. - </para> - </listitem> - <listitem> - <para> - File - <filename>$HOME/.ghc/<replaceable>arch</replaceable>-<replaceable>os</replaceable>-<replaceable>version</replaceable>/environments/default</filename> - if it exists. - </para> - </listitem> - </itemizedlist> - <para> - Package environments can be modified by further command line arguments; - for example, if you specify - <option>-package <replaceable>foo</replaceable></option> - on the command line, then package <replaceable>foo</replaceable> will be - visible even if it's not listed in the currently active package - environment. - </para> - </sect2> - </sect1> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> diff --git a/docs/users_guide/parallel.rst b/docs/users_guide/parallel.rst new file mode 100644 index 0000000000..07dc60fc47 --- /dev/null +++ b/docs/users_guide/parallel.rst @@ -0,0 +1,169 @@ +.. _lang-parallel: + +Concurrent and Parallel Haskell +=============================== + +.. index:: + single: parallelism + single: concurrency + +GHC implements some major extensions to Haskell to support concurrent +and parallel programming. Let us first establish terminology: + +- *Parallelism* means running a Haskell program on multiple processors, + with the goal of improving performance. Ideally, this should be done + invisibly, and with no semantic changes. + +- *Concurrency* means implementing a program by using multiple + I/O-performing threads. While a concurrent Haskell program *can* run + on a parallel machine, the primary goal of using concurrency is not + to gain performance, but rather because that is the simplest and most + direct way to write the program. Since the threads perform I/O, the + semantics of the program is necessarily non-deterministic. + +GHC supports both concurrency and parallelism. + +.. _concurrent-haskell: + +Concurrent Haskell +------------------ + +Concurrent Haskell is the name given to GHC's concurrency extension. It +is enabled by default, so no special flags are required. The `Concurrent +Haskell +paper <https://www.haskell.org/ghc/docs/papers/concurrent-haskell.ps.gz>`__ +is still an excellent resource, as is `Tackling the awkward +squad <http://research.microsoft.com/%7Esimonpj/papers/marktoberdorf/>`__. + +To the programmer, Concurrent Haskell introduces no new language +constructs; rather, it appears simply as a library, +:base-ref:`Control.Concurrent <Control-Concurrent.html>`. +The functions exported by this library include: + +- Forking and killing threads. + +- Sleeping. + +- Synchronised mutable variables, called ``MVars`` + +- Support for bound threads; see the paper `Extending the FFI with + concurrency <http://research.microsoft.com/%7Esimonpj/Papers/conc-ffi/index.htm>`__. + +Software Transactional Memory +----------------------------- + +GHC now supports a new way to coordinate the activities of Concurrent +Haskell threads, called Software Transactional Memory (STM). The `STM +papers <http://research.microsoft.com/%7Esimonpj/papers/stm/index.htm>`__ +are an excellent introduction to what STM is, and how to use it. + +The main library you need to use is the `stm +library <http://hackage.haskell.org/package/stm>`__. The main features +supported are these: + +- Atomic blocks. + +- Transactional variables. + +- Operations for composing transactions: ``retry``, and ``orElse``. + +- Data invariants. + +All these features are described in the papers mentioned earlier. + +Parallel Haskell +---------------- + +.. index:: + single: SMP + +GHC includes support for running Haskell programs in parallel on +symmetric, shared-memory multi-processor (SMP). By default GHC runs +your program on one processor; if you want it to run in parallel you +must link your program with the ``-threaded``, and run it with the RTS +``-N`` option; see :ref:`using-smp`). The runtime will schedule the +running Haskell threads among the available OS threads, running as many +in parallel as you specified with the ``-N`` RTS option. + +Annotating pure code for parallelism +------------------------------------ + +Ordinary single-threaded Haskell programs will not benefit from enabling +SMP parallelism alone: you must expose parallelism to the compiler. One +way to do so is forking threads using Concurrent Haskell +(:ref:`concurrent-haskell`), but the simplest mechanism for extracting +parallelism from pure code is to use the ``par`` combinator, which is +closely related to (and often used with) ``seq``. Both of these are +available from the +`parallel library <http://hackage.haskell.org/package/parallel>`__: + +:: + + infixr 0 `par` + infixr 1 `pseq` + + par :: a -> b -> b + pseq :: a -> b -> b + +The expression ``(x `par` y)`` *sparks* the evaluation of ``x`` (to weak +head normal form) and returns ``y``. Sparks are queued for execution in +FIFO order, but are not executed immediately. If the runtime detects +that there is an idle CPU, then it may convert a spark into a real +thread, and run the new thread on the idle CPU. In this way the +available parallelism is spread amongst the real CPUs. + +For example, consider the following parallel version of our old nemesis, +``nfib``: + +:: + + import Control.Parallel + + nfib :: Int -> Int + nfib n | n <= 1 = 1 + | otherwise = par n1 (pseq n2 (n1 + n2 + 1)) + where n1 = nfib (n-1) + n2 = nfib (n-2) + +For values of ``n`` greater than 1, we use ``par`` to spark a thread to +evaluate ``nfib (n-1)``, and then we use ``pseq`` to force the parent +thread to evaluate ``nfib (n-2)`` before going on to add together these +two subexpressions. In this divide-and-conquer approach, we only spark a +new thread for one branch of the computation (leaving the parent to +evaluate the other branch). Also, we must use ``pseq`` to ensure that +the parent will evaluate ``n2`` *before* ``n1`` in the expression +``(n1 + n2 + 1)``. It is not sufficient to reorder the expression as +``(n2 + n1 + 1)``, because the compiler may not generate code to +evaluate the addends from left to right. + +Note that we use ``pseq`` rather than ``seq``. The two are almost +equivalent, but differ in their runtime behaviour in a subtle way: +``seq`` can evaluate its arguments in either order, but ``pseq`` is +required to evaluate its first argument before its second, which makes +it more suitable for controlling the evaluation order in conjunction +with ``par``. + +When using ``par``, the general rule of thumb is that the sparked +computation should be required at a later time, but not too soon. Also, +the sparked computation should not be too small, otherwise the cost of +forking it in parallel will be too large relative to the amount of +parallelism gained. Getting these factors right is tricky in practice. + +It is possible to glean a little information about how well ``par`` is +working from the runtime statistics; see :ref:`rts-options-gc`. + +More sophisticated combinators for expressing parallelism are available +from the ``Control.Parallel.Strategies`` module in the `parallel +package <http://hackage.haskell.org/package/parallel>`__. This module +builds functionality around ``par``, expressing more elaborate patterns +of parallel computation, such as parallel ``map``. + +.. _dph: + +Data Parallel Haskell +--------------------- + +GHC includes experimental support for Data Parallel Haskell (DPH). This +code is highly unstable and is only provided as a technology preview. +More information can be found on the corresponding +`DPH wiki page <http://www.haskell.org/haskellwiki/GHC/Data_Parallel_Haskell>`__. diff --git a/docs/users_guide/parallel.xml b/docs/users_guide/parallel.xml deleted file mode 100644 index b216592c5e..0000000000 --- a/docs/users_guide/parallel.xml +++ /dev/null @@ -1,203 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<sect1 id="lang-parallel"> - <title>Concurrent and Parallel Haskell</title> - <indexterm><primary>parallelism</primary> - </indexterm> - - <para>GHC implements some major extensions to Haskell to support - concurrent and parallel programming. Let us first establish terminology: - <itemizedlist> - <listitem><para><emphasis>Parallelism</emphasis> means running - a Haskell program on multiple processors, with the goal of improving - performance. Ideally, this should be done invisibly, and with no - semantic changes. - </para></listitem> - <listitem><para><emphasis>Concurrency</emphasis> means implementing - a program by using multiple I/O-performing threads. While a - concurrent Haskell program <emphasis>can</emphasis> run on a - parallel machine, the primary goal of using concurrency is not to gain - performance, but rather because that is the simplest and most - direct way to write the program. Since the threads perform I/O, - the semantics of the program is necessarily non-deterministic. - </para></listitem> - </itemizedlist> - GHC supports both concurrency and parallelism. - </para> - - <sect2 id="concurrent-haskell"> - <title>Concurrent Haskell</title> - - <para>Concurrent Haskell is the name given to GHC's concurrency extension. - It is enabled by default, so no special flags are required. - The <ulink - url="https://www.haskell.org/ghc/docs/papers/concurrent-haskell.ps.gz"> - Concurrent Haskell paper</ulink> is still an excellent - resource, as is <ulink - url="http://research.microsoft.com/%7Esimonpj/papers/marktoberdorf/">Tackling - the awkward squad</ulink>. - </para><para> - To the programmer, Concurrent Haskell introduces no new language constructs; - rather, it appears simply as a library, <ulink - url="&libraryBaseLocation;/Control-Concurrent.html"> - Control.Concurrent</ulink>. The functions exported by this - library include: - <itemizedlist> -<listitem><para>Forking and killing threads.</para></listitem> -<listitem><para>Sleeping.</para></listitem> -<listitem><para>Synchronised mutable variables, called <literal>MVars</literal></para></listitem> -<listitem><para>Support for bound threads; see the paper <ulink -url="http://research.microsoft.com/%7Esimonpj/Papers/conc-ffi/index.htm">Extending -the FFI with concurrency</ulink>.</para></listitem> -</itemizedlist> -</para> -</sect2> - - <sect2><title>Software Transactional Memory</title> - - <para>GHC now supports a new way to coordinate the activities of Concurrent - Haskell threads, called Software Transactional Memory (STM). The - <ulink - url="http://research.microsoft.com/%7Esimonpj/papers/stm/index.htm">STM - papers</ulink> are an excellent introduction to what STM is, and how to use - it.</para> - - <para>The main library you need to use is the <ulink - url="http://hackage.haskell.org/package/stm"> - stm library</ulink>. The main features supported are these: -<itemizedlist> -<listitem><para>Atomic blocks.</para></listitem> -<listitem><para>Transactional variables.</para></listitem> -<listitem><para>Operations for composing transactions: -<literal>retry</literal>, and <literal>orElse</literal>.</para></listitem> -<listitem><para>Data invariants.</para></listitem> -</itemizedlist> -All these features are described in the papers mentioned earlier. -</para> -</sect2> - -<sect2><title>Parallel Haskell</title> - - <para>GHC includes support for running Haskell programs in parallel - on symmetric, shared-memory multi-processor - (SMP)<indexterm><primary>SMP</primary></indexterm>. - By default GHC runs your program on one processor; if you - want it to run in parallel you must link your program - with the <option>-threaded</option>, and run it with the RTS - <option>-N</option> option; see <xref linkend="using-smp" />). - The runtime will - schedule the running Haskell threads among the available OS - threads, running as many in parallel as you specified with the - <option>-N</option> RTS option.</para> - - <para>GHC only supports parallelism on a shared-memory multiprocessor. - Glasgow Parallel Haskell<indexterm><primary>Glasgow Parallel Haskell</primary></indexterm> - (GPH) supports running Parallel Haskell - programs on both clusters of machines, and single multiprocessors. GPH is - developed and distributed - separately from GHC (see <ulink url="http://www.macs.hw.ac.uk/~dsg/gph/">The - GPH Page</ulink>). However, the current version of GPH is based on a much older - version of GHC (4.06).</para> - - </sect2> - <sect2> - <title>Annotating pure code for parallelism</title> - - <para>Ordinary single-threaded Haskell programs will not benefit from - enabling SMP parallelism alone: you must expose parallelism to the - compiler. - - One way to do so is forking threads using Concurrent Haskell (<xref - linkend="concurrent-haskell"/>), but the simplest mechanism for extracting parallelism from pure code is - to use the <literal>par</literal> combinator, which is closely related to (and often used - with) <literal>seq</literal>. Both of these are available from the <ulink - url="http://hackage.haskell.org/package/parallel">parallel library</ulink>:</para> - -<programlisting> -infixr 0 `par` -infixr 1 `pseq` - -par :: a -> b -> b -pseq :: a -> b -> b</programlisting> - - <para>The expression <literal>(x `par` y)</literal> - <emphasis>sparks</emphasis> the evaluation of <literal>x</literal> - (to weak head normal form) and returns <literal>y</literal>. Sparks are - queued for execution in FIFO order, but are not executed immediately. If - the runtime detects that there is an idle CPU, then it may convert a - spark into a real thread, and run the new thread on the idle CPU. In - this way the available parallelism is spread amongst the real - CPUs.</para> - - <para>For example, consider the following parallel version of our old - nemesis, <function>nfib</function>:</para> - -<programlisting> -import Control.Parallel - -nfib :: Int -> Int -nfib n | n <= 1 = 1 - | otherwise = par n1 (pseq n2 (n1 + n2 + 1)) - where n1 = nfib (n-1) - n2 = nfib (n-2)</programlisting> - - <para>For values of <varname>n</varname> greater than 1, we use - <function>par</function> to spark a thread to evaluate <literal>nfib (n-1)</literal>, - and then we use <function>pseq</function> to force the - parent thread to evaluate <literal>nfib (n-2)</literal> before going on - to add together these two subexpressions. In this divide-and-conquer - approach, we only spark a new thread for one branch of the computation - (leaving the parent to evaluate the other branch). Also, we must use - <function>pseq</function> to ensure that the parent will evaluate - <varname>n2</varname> <emphasis>before</emphasis> <varname>n1</varname> - in the expression <literal>(n1 + n2 + 1)</literal>. It is not sufficient - to reorder the expression as <literal>(n2 + n1 + 1)</literal>, because - the compiler may not generate code to evaluate the addends from left to - right.</para> - - <para> - Note that we use <literal>pseq</literal> rather - than <literal>seq</literal>. The two are almost equivalent, but - differ in their runtime behaviour in a subtle - way: <literal>seq</literal> can evaluate its arguments in either - order, but <literal>pseq</literal> is required to evaluate its - first argument before its second, which makes it more suitable - for controlling the evaluation order in conjunction - with <literal>par</literal>. - </para> - - <para>When using <literal>par</literal>, the general rule of thumb is that - the sparked computation should be required at a later time, but not too - soon. Also, the sparked computation should not be too small, otherwise - the cost of forking it in parallel will be too large relative to the - amount of parallelism gained. Getting these factors right is tricky in - practice.</para> - - <para>It is possible to glean a little information about how - well <literal>par</literal> is working from the runtime - statistics; see <xref linkend="rts-options-gc" />.</para> - - <para>More sophisticated combinators for expressing parallelism are - available from the <literal>Control.Parallel.Strategies</literal> - module in the <ulink - url="http://hackage.haskell.org/package/parallel">parallel package</ulink>. - This module builds functionality around <literal>par</literal>, - expressing more elaborate patterns of parallel computation, such as - parallel <literal>map</literal>.</para> - </sect2> - -<sect2 id="dph"><title>Data Parallel Haskell</title> - <para>GHC includes experimental support for Data Parallel Haskell (DPH). This code - is highly unstable and is only provided as a technology preview. More - information can be found on the corresponding <ulink - url="http://www.haskell.org/haskellwiki/GHC/Data_Parallel_Haskell">DPH - wiki page</ulink>.</para> -</sect2> - -</sect1> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> diff --git a/docs/users_guide/phases.rst b/docs/users_guide/phases.rst new file mode 100644 index 0000000000..e7a46950b5 --- /dev/null +++ b/docs/users_guide/phases.rst @@ -0,0 +1,903 @@ +.. _options-phases: + +Options related to a particular phase +===================================== + +.. _replacing-phases: + +Replacing the program for one or more phases +-------------------------------------------- + +.. index:: + single: compilation phases, changing + +You may specify that a different program be used for one of the phases +of the compilation system, in place of whatever the ``ghc`` has wired +into it. For example, you might want to try a different assembler. The +following options allow you to change the external program used for a +given compilation phase: + +``-pgmL ⟨cmd⟩`` + .. index:: + single: -pgmL + + Use ⟨cmd⟩ as the literate pre-processor. + +``-pgmP ⟨cmd⟩`` + .. index:: + single: -pgmP + + Use ⟨cmd⟩ as the C pre-processor (with ``-cpp`` only). + +``-pgmc ⟨cmd⟩`` + .. index:: + single: -pgmc + + Use ⟨cmd⟩ as the C compiler. + +``-pgmlo ⟨cmd⟩`` + .. index:: + single: -pgmlo + + Use ⟨cmd⟩ as the LLVM optimiser. + +``-pgmlc ⟨cmd⟩`` + .. index:: + single: -pgmlc + + Use ⟨cmd⟩ as the LLVM compiler. + +``-pgms ⟨cmd⟩`` + .. index:: + single: -pgms + + Use ⟨cmd⟩ as the splitter. + +``-pgma ⟨cmd⟩`` + .. index:: + single: -pgma + + Use ⟨cmd⟩ as the assembler. + +``-pgml ⟨cmd⟩`` + .. index:: + single: -pgml + + Use ⟨cmd⟩ as the linker. + +``-pgmdll ⟨cmd⟩`` + .. index:: + single: -pgmdll + + Use ⟨cmd⟩ as the DLL generator. + +``-pgmF ⟨cmd⟩`` + .. index:: + single: -pgmF + + Use ⟨cmd⟩ as the pre-processor (with ``-F`` only). + +``-pgmwindres ⟨cmd⟩`` + .. index:: + single: -pgmwindres + + Use ⟨cmd⟩ as the program to use for embedding manifests on Windows. + Normally this is the program ``windres``, which is supplied with a + GHC installation. See ``-fno-embed-manifest`` in + :ref:`options-linker`. + +``-pgmlibtool ⟨cmd⟩`` + .. index:: + single: -pgmlibtool + + Use ⟨cmd⟩ as the libtool command (when using ``-staticlib`` only). + +.. _forcing-options-through: + +Forcing options to a particular phase +------------------------------------- + +.. index:: + single: forcing GHC-phase options + +Options can be forced through to a particular compilation phase, using +the following flags: + +``-optL ⟨option⟩`` + .. index:: + single: -optL + + Pass ⟨option⟩ to the literate pre-processor + +``-optP ⟨option⟩`` + .. index:: + single: -optP + + Pass ⟨option⟩ to CPP (makes sense only if ``-cpp`` is also on). + +``-optF ⟨option⟩`` + .. index:: + single: -optF + + Pass ⟨option⟩ to the custom pre-processor (see + :ref:`pre-processor`). + +``-optc ⟨option⟩`` + .. index:: + single: -optc + + Pass ⟨option⟩ to the C compiler. + +``-optlo ⟨option⟩`` + .. index:: + single: -optlo + + Pass ⟨option⟩ to the LLVM optimiser. + +``-optlc ⟨option⟩`` + .. index:: + single: -optlc + + Pass ⟨option⟩ to the LLVM compiler. + +``-opta ⟨option⟩`` + .. index:: + single: -opta + + Pass ⟨option⟩ to the assembler. + +``-optl ⟨option⟩`` + .. index:: + single: -optl + + Pass ⟨option⟩ to the linker. + +``-optdll ⟨option⟩`` + .. index:: + single: -optdll + + Pass ⟨option⟩ to the DLL generator. + +``-optwindres ⟨option⟩`` + .. index:: + single: -optwindres + + Pass ⟨option⟩ to ``windres`` when embedding manifests on Windows. + See ``-fno-embed-manifest`` in :ref:`options-linker`. + +So, for example, to force an ``-Ewurble`` option to the assembler, you +would tell the driver ``-opta-Ewurble`` (the dash before the E is +required). + +GHC is itself a Haskell program, so if you need to pass options directly +to GHC's runtime system you can enclose them in ``+RTS ... -RTS`` (see +:ref:`runtime-control`). + +.. _c-pre-processor: + +Options affecting the C pre-processor +------------------------------------- + +.. index:: + single: pre-processing: cpp + single: C pre-processor options + single: cpp, pre-processing with + +``-cpp`` + .. index:: + single: -cpp + + The C pre-processor ``cpp`` is run over your Haskell code only if + the ``-cpp`` option -cpp option is given. Unless you are building a + large system with significant doses of conditional compilation, you + really shouldn't need it. + +``-D ⟨symbol⟩[=⟨value⟩]`` + .. index:: + single: -D + + Define macro ⟨symbol⟩ in the usual way. NB: does *not* affect ``-D`` + macros passed to the C compiler when compiling via C! For those, use + the ``-optc-Dfoo`` hack… (see :ref:`forcing-options-through`). + +``-U ⟨symbol⟩`` + .. index:: + single: -U + + Undefine macro ⟨symbol⟩ in the usual way. + +``-I ⟨dir⟩`` + .. index:: + single: -I + + Specify a directory in which to look for ``#include`` files, in the + usual C way. + +The GHC driver pre-defines several macros when processing Haskell source +code (``.hs`` or ``.lhs`` files). + +The symbols defined by GHC are listed below. To check which symbols are +defined by your local GHC installation, the following trick is useful: + +:: + + $ ghc -E -optP-dM -cpp foo.hs + $ cat foo.hspp + +(you need a file ``foo.hs``, but it isn't actually used). + +``__GLASGOW_HASKELL__`` + .. index:: + single: __GLASGOW_HASKELL__ + + For version ``x.y.z`` of GHC, the value of ``__GLASGOW_HASKELL__`` + is the integer ⟨xyy⟩ (if ⟨y⟩ is a single digit, then a leading zero + is added, so for example in version 6.2 of GHC, + ``__GLASGOW_HASKELL__==602``). More information in + :ref:`version-numbering`. + + With any luck, ``__GLASGOW_HASKELL__`` will be undefined in all + other implementations that support C-style pre-processing. + + .. note:: + The comparable symbols for other systems are: + ``__HUGS__`` for Hugs, ``__NHC__`` for nhc98, and ``__HBC__`` for + hbc). + + NB. This macro is set when pre-processing both Haskell source and C + source, including the C source generated from a Haskell module (i.e. + ``.hs``, ``.lhs``, ``.c`` and ``.hc`` files). + +``__GLASGOW_HASKELL_PATCHLEVEL1__``; \ ``__GLASGOW_HASKELL_PATCHLEVEL2__`` + .. index:: + single: __GLASGOW_HASKELL_PATCHLEVEL2__ + + .. index:: + single: __GLASGOW_HASKELL_PATCHLEVEL1__ + + These macros are available starting with GHC 7.10.1. + + For three-part GHC version numbers ``x.y.z``, the value of + ``__GLASGOW_HASKELL_PATCHLEVEL1__`` is the integer ⟨z⟩. + + For four-part GHC version numbers ``x.y.z.z'``, the value of + ``__GLASGOW_HASKELL_PATCHLEVEL1__`` is the integer ⟨z⟩ while the + value of ``__GLASGOW_HASKELL_PATCHLEVEL2__`` is set to the integer + ⟨z'⟩. + + These macros are provided for allowing finer granularity than is + provided by ``__GLASGOW_HASKELL__``. Usually, this should not be + necessary as it's expected for most APIs to remain stable between + patchlevel releases, but occasionally internal API changes are + necessary to fix bugs. Also conditional compilation on the + patchlevel can be useful for working around bugs in older releases. + + .. tip:: + These macros are set when pre-processing both Haskell source and + C source, including the C source generated from a Haskell module + (i.e. ``.hs``, ``.lhs``, ``.c`` and ``.hc`` files). + +``MIN_VERSION_GLASGOW_HASKELL(x,y,z,z')`` + .. index:: + single: MIN_VERSION_GLASGOW_HASKELL + + This macro is available starting with GHC 7.10.1. + + This macro is provided for convenience to write CPP conditionals + testing whether the GHC version used is version ``x.y.z.z'`` or + later. + + If compatibility with Haskell compilers (including GHC prior to + version 7.10.1) which do not define ``MIN_VERSION_GLASGOW_HASKELL`` + is required, the presence of the ``MIN_VERSION_GLASGOW_HASKELL`` + macro needs to be ensured before it is called, e.g.: + + :: + + #ifdef MIN_VERSION_GLASGOW_HASKELL + #if MIN_VERSION_GLASGOW_HASKELL(7,10,2,0) + /* code that applies only to GHC 7.10.2 or later */ + #endif + #endif + + .. tip:: + This macro is set when pre-processing both Haskell source and C + source, including the C source generated from a Haskell module (i.e. + ``.hs``, ``.lhs``, ``.c`` and ``.hc`` files). + +``__GLASGOW_HASKELL_TH__`` + .. index:: + single: __GLASGOW_HASKELL_TH__ + + This is set to ``YES`` when the compiler supports Template Haskell, + and to ``NO`` when not. The latter is the case for a stage-1 + compiler during bootstrapping, or on architectures where the + interpreter is not available. + +``__GLASGOW_HASKELL_LLVM__`` + .. index:: + single: __GLASGOW_HASKELL_LLVM__ + + Only defined when ``-fllvm`` is specified. When GHC is using version + ``x.y.z`` of LLVM, the value of ``__GLASGOW_HASKELL_LLVM__`` is the + integer ⟨xy⟩. + +``__PARALLEL_HASKELL__`` + .. index:: + single: __PARALLEL_HASKELL__ + + Only defined when ``-parallel`` is in use! This symbol is defined + when pre-processing Haskell (input) and pre-processing C (GHC + output). + +``os_HOST_OS=1`` + This define allows conditional compilation based on the Operating + System, where⟨os⟩ is the name of the current Operating System (eg. + ``linux``, ``mingw32`` for Windows, ``solaris``, etc.). + +``arch_HOST_ARCH=1`` + This define allows conditional compilation based on the host + architecture, where⟨arch⟩ is the name of the current architecture + (eg. ``i386``, ``x86_64``, ``powerpc``, ``sparc``, etc.). + +.. _cpp-string-gaps: + +CPP and string gaps +~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: -cpp vs string gaps + single: string gaps vs -cpp. + +A small word of warning: ``-cpp`` is not friendly to "string gaps". +In other words, strings such as the following: + +:: + + strmod = "\ + \ p \ + \ " + +don't work with ``-cpp``; ``/usr/bin/cpp`` elides the backslash-newline +pairs. + +However, it appears that if you add a space at the end of the line, then +``cpp`` (at least GNU ``cpp`` and possibly other ``cpp``\ s) leaves the +backslash-space pairs alone and the string gap works as expected. + +.. _pre-processor: + +Options affecting a Haskell pre-processor +----------------------------------------- + +.. index:: + single: pre-processing: custom + single: pre-processor options + +``-F`` + .. index:: + single: -F + + A custom pre-processor is run over your Haskell source file only if + the ``-F`` option is given. + + Running a custom pre-processor at compile-time is in some settings + appropriate and useful. The ``-F`` option lets you run a + pre-processor as part of the overall GHC compilation pipeline, which + has the advantage over running a Haskell pre-processor separately in + that it works in interpreted mode and you can continue to take reap + the benefits of GHC's recompilation checker. + + The pre-processor is run just before the Haskell compiler proper + processes the Haskell input, but after the literate markup has been + stripped away and (possibly) the C pre-processor has washed the + Haskell input. + + Use ``-pgmF ⟨cmd⟩`` to select the program to use as the preprocessor. + When invoked, the ⟨cmd⟩ pre-processor is given at least three + arguments on its command-line: the first argument is the name of the + original source file, the second is the name of the file holding the + input, and the third is the name of the file where ⟨cmd⟩ should + write its output to. + + Additional arguments to the pre-processor can be passed in using the + ``-optF`` option. These are fed to ⟨cmd⟩ on the command line after + the three standard input and output arguments. + + An example of a pre-processor is to convert your source files to the + input encoding that GHC expects, i.e. create a script ``convert.sh`` + containing the lines: + + :: + + #!/bin/sh + ( echo "{-# LINE 1 \"$2\" #-}" ; iconv -f l1 -t utf-8 $2 ) > $3 + + and pass ``-F -pgmF convert.sh`` to GHC. The ``-f l1`` option tells + iconv to convert your Latin-1 file, supplied in argument ``$2``, + while the "-t utf-8" options tell iconv to return a UTF-8 encoded + file. The result is redirected into argument ``$3``. The + ``echo "{-# LINE 1 \"$2\" #-}"`` just makes sure that your error + positions are reported as in the original source file. + +.. _options-codegen: + +Options affecting code generation +--------------------------------- + +``-fasm`` + .. index:: + single: -fasm + + Use GHC's :ref:`native code generator <native-code-gen>` rather than + compiling via LLVM. ``-fasm`` is the default. + +``-fllvm`` + .. index:: + single: -fllvm + + Compile via :ref:`LLVM <llvm-code-gen>` instead of using the native + code generator. This will generally take slightly longer than the + native code generator to compile. Produced code is generally the + same speed or faster than the other two code generators. Compiling + via LLVM requires LLVM's ``opt`` and ``llc`` executables to be in ``PATH``. + +``-fno-code`` + .. index:: + single: -fno-code + + Omit code generation (and all later phases) altogether. This is + useful if you're only interested in type checking code. + +``-fwrite-interface`` + .. index:: + single: -fwrite-interface + + Always write interface files. GHC will normally write interface + files automatically, but this flag is useful with ``-fno-code``, + which normally suppresses generation of interface files. This is + useful if you want to type check over multiple runs of GHC without + compiling dependencies. + +``-fobject-code`` + .. index:: + single: -fobject-code + + Generate object code. This is the default outside of GHCi, and can + be used with GHCi to cause object code to be generated in preference + to bytecode. + +``-fbyte-code`` + .. index:: + single: -fbyte-code + + Generate byte-code instead of object-code. This is the default in + GHCi. Byte-code can currently only be used in the interactive + interpreter, not saved to disk. This option is only useful for + reversing the effect of ``-fobject-code``. + +``-fPIC`` + .. index:: + single: -fPIC + + Generate position-independent code (code that can be put into shared + libraries). This currently works on Linux x86 and x86-64. On + Windows, position-independent code is never used so the flag is a + no-op on that platform. + +``-dynamic`` + When generating code, assume that entities imported from a different + package will reside in a different shared library or binary. + + Note that using this option when linking causes GHC to link against + shared libraries. + +.. _options-linker: + +Options affecting linking +------------------------- + +.. index:: + single: linker options + single: ld options + +GHC has to link your code with various libraries, possibly including: +user-supplied, GHC-supplied, and system-supplied (``-lm`` math library, +for example). + +``-l ⟨lib⟩`` + .. index:: + single: -l + + Link in the ⟨lib⟩ library. On Unix systems, this will be in a file + called ``liblib.a`` or ``liblib.so`` which resides somewhere on the + library directories path. + + Because of the sad state of most UNIX linkers, the order of such + options does matter. If library ⟨foo⟩ requires library ⟨bar⟩, then + in general ``-l ⟨foo⟩`` should come *before* ``-l ⟨bar⟩`` on the + command line. + + There's one other gotcha to bear in mind when using external + libraries: if the library contains a ``main()`` function, then this + will be linked in preference to GHC's own ``main()`` function (eg. + ``libf2c`` and ``libl`` have their own ``main()``\ s). This is + because GHC's ``main()`` comes from the ``HSrts`` library, which is + normally included *after* all the other libraries on the linker's + command line. To force GHC's ``main()`` to be used in preference to + any other ``main()``\ s from external libraries, just add the option + ``-lHSrts`` before any other libraries on the command line. + +``-c`` + .. index:: + single: -c + + Omits the link step. This option can be used with ``--make`` to + avoid the automatic linking that takes place if the program contains + a ``Main`` module. + +``-package ⟨name⟩`` + .. index:: + single: -package + + If you are using a Haskell “package” (see :ref:`packages`), don't + forget to add the relevant ``-package`` option when linking the + program too: it will cause the appropriate libraries to be linked in + with the program. Forgetting the ``-package`` option will likely + result in several pages of link errors. + +``-framework ⟨name⟩`` + .. index:: + single: -framework + + On Darwin/OS X/iOS only, link in the framework ⟨name⟩. This option + corresponds to the ``-framework`` option for Apple's Linker. Please + note that frameworks and packages are two different things - + frameworks don't contain any Haskell code. Rather, they are Apple's + way of packaging shared libraries. To link to Apple's “Carbon” API, + for example, you'd use ``-framework Carbon``. + +``-staticlib`` + .. index:: + single: -staticlib + + On Darwin/OS X/iOS only, link all passed files into a static library + suitable for linking into an iOS (when using a cross-compiler) or + Mac Xcode project. To control the name, use the ``-o`` ⟨name⟩ option + as usual. The default name is ``liba.a``. This should nearly always + be passed when compiling for iOS with a cross-compiler. + +``-L ⟨dir⟩`` + .. index:: + single: -L + + Where to find user-supplied libraries… Prepend the directory ⟨dir⟩ + to the library directories path. + +``-framework-path ⟨dir⟩`` + .. index:: + single: -framework-path + + On Darwin/OS X/iOS only, prepend the directory ⟨dir⟩ to the + framework directories path. This option corresponds to the ``-F`` + option for Apple's Linker (``-F`` already means something else for + GHC). + +``-split-objs`` + .. index:: + single: -split-objs + + Tell the linker to split the single object file that would normally + be generated into multiple object files, one per top-level Haskell + function or type in the module. This only makes sense for libraries, + where it means that executables linked against the library are + smaller as they only link against the object files that they need. + However, assembling all the sections separately is expensive, so + this is slower than compiling normally. Additionally, the size of + the library itself (the ``.a`` file) can be a factor of 2 to 2.5 + larger. We use this feature for building GHC's libraries. + +``-static`` + .. index:: + single: -static + + Tell the linker to avoid shared Haskell libraries, if possible. This + is the default. + +``-dynamic`` + .. index:: + single: -dynamic + + This flag tells GHC to link against shared Haskell libraries. This + flag only affects the selection of dependent libraries, not the form + of the current target (see -shared). See :ref:`using-shared-libs` on + how to create them. + + Note that this option also has an effect on code generation (see + above). + +``-shared`` + .. index:: + single: -shared + + Instead of creating an executable, GHC produces a shared object with + this linker flag. Depending on the operating system target, this + might be an ELF DSO, a Windows DLL, or a Mac OS dylib. GHC hides the + operating system details beneath this uniform flag. + + The flags ``-dynamic``/``-static`` control whether the resulting + shared object links statically or dynamically to Haskell package + libraries given as ``-package`` option. Non-Haskell libraries are + linked as gcc would regularly link it on your system, e.g. on most + ELF system the linker uses the dynamic libraries when found. + + Object files linked into shared objects must be compiled with + ``-fPIC``, see :ref:`options-codegen` + + When creating shared objects for Haskell packages, the shared object + must be named properly, so that GHC recognizes the shared object + when linked against this package. See shared object name mangling. + +``-dynload`` + .. index:: + single: -dynload + + This flag selects one of a number of modes for finding shared + libraries at runtime. See :ref:`finding-shared-libs` for a + description of each mode. + +``-main-is ⟨thing⟩`` + .. index:: + single: -main-is + single: specifying your own main function + + The normal rule in Haskell is that your program must supply a + ``main`` function in module ``Main``. When testing, it is often + convenient to change which function is the "main" one, and the + ``-main-is`` flag allows you to do so. The ⟨thing⟩ can be one of: + + - A lower-case identifier ``foo``. GHC assumes that the main + function is ``Main.foo``. + + - A module name ``A``. GHC assumes that the main function is + ``A.main``. + + - A qualified name ``A.foo``. GHC assumes that the main function is + ``A.foo``. + + Strictly speaking, ``-main-is`` is not a link-phase flag at all; it + has no effect on the link step. The flag must be specified when + compiling the module containing the specified main function (e.g. + module ``A`` in the latter two items above). It has no effect for + other modules, and hence can safely be given to ``ghc --make``. + However, if all the modules are otherwise up to date, you may need + to force recompilation both of the module where the new "main" is, + and of the module where the "main" function used to be; ``ghc`` is + not clever enough to figure out that they both need recompiling. You + can force recompilation by removing the object file, or by using the + ``-fforce-recomp`` flag. + +``-no-hs-main`` + .. index:: + single: -no-hs-main + single: linking Haskell libraries with foreign code + + In the event you want to include ghc-compiled code as part of + another (non-Haskell) program, the RTS will not be supplying its + definition of ``main()`` at link-time, you will have to. To signal + that to the compiler when linking, use ``-no-hs-main``. See also + :ref:`using-own-main`. + + Notice that since the command-line passed to the linker is rather + involved, you probably want to use ``ghc`` to do the final link of + your \`mixed-language' application. This is not a requirement + though, just try linking once with ``-v`` on to see what options the + driver passes through to the linker. + + The ``-no-hs-main`` flag can also be used to persuade the compiler + to do the link step in ``--make`` mode when there is no Haskell + ``Main`` module present (normally the compiler will not attempt + linking when there is no ``Main``). + + The flags ``-rtsopts`` and ``-with-rtsopts`` have no effect when + used with ``-no-hs-main``, because they are implemented by changing + the definition of ``main`` that GHC generates. See + :ref:`using-own-main` for how to get the effect of ``-rtsopts`` and + ``-with-rtsopts`` when using your own ``main``. + +``-debug`` + .. index:: + single: -debug + + Link the program with a debugging version of the runtime system. The + debugging runtime turns on numerous assertions and sanity checks, + and provides extra options for producing debugging output at runtime + (run the program with ``+RTS -?`` to see a list). + +``-threaded`` + .. index:: + single: -threaded + + Link the program with the "threaded" version of the runtime system. + The threaded runtime system is so-called because it manages multiple + OS threads, as opposed to the default runtime system which is purely + single-threaded. + + Note that you do *not* need ``-threaded`` in order to use + concurrency; the single-threaded runtime supports concurrency + between Haskell threads just fine. + + The threaded runtime system provides the following benefits: + + - It enables the ``-N``\ ``-Nx``\ RTS option RTS option to be used, + which allows threads to run in parallelparallelism on a + multiprocessormultiprocessorSMP or multicoremulticore machine. + See :ref:`using-smp`. + + - If a thread makes a foreign call (and the call is not marked + ``unsafe``), then other Haskell threads in the program will + continue to run while the foreign call is in progress. + Additionally, ``foreign export``\ ed Haskell functions may be + called from multiple OS threads simultaneously. See + :ref:`ffi-threads`. + +``-eventlog`` + .. index:: + single: -eventlog + + Link the program with the "eventlog" version of the runtime system. + A program linked in this way can generate a runtime trace of events + (such as thread start/stop) to a binary file ``program.eventlog``, + which can then be interpreted later by various tools. See + :ref:`rts-eventlog` for more information. + + ``-eventlog`` can be used with ``-threaded``. It is implied by + ``-debug``. + +``-rtsopts`` + .. index:: + single: -rtsopts + + This option affects the processing of RTS control options given + either on the command line or via the ``GHCRTS`` environment + variable. There are three possibilities: + + ``-rtsopts=none`` + Disable all processing of RTS options. If ``+RTS`` appears + anywhere on the command line, then the program will abort with + an error message. If the ``GHCRTS`` environment variable is set, + then the program will emit a warning message, ``GHCRTS`` will be + ignored, and the program will run as normal. + + ``-rtsopts=some`` + [this is the default setting] Enable only the "safe" RTS + options: (Currently only ``-?`` and ``--info``.) Any other RTS + options on the command line or in the ``GHCRTS`` environment + variable causes the program with to abort with an error message. + + ``-rtsopts=all`` or just ``-rtsopts`` + Enable *all* RTS option processing, both on the command line and + through the ``GHCRTS`` environment variable. + + In GHC 6.12.3 and earlier, the default was to process all RTS + options. However, since RTS options can be used to write logging + data to arbitrary files under the security context of the running + program, there is a potential security problem. For this reason, GHC + 7.0.1 and later default to ``-rtsops=some``. + + Note that ``-rtsopts`` has no effect when used with ``-no-hs-main``; + see :ref:`using-own-main` for details. + +``-with-rtsopts`` + .. index:: + single: -with-rtsopts + + This option allows you to set the default RTS options at link-time. + For example, ``-with-rtsopts="-H128m"`` sets the default heap size + to 128MB. This will always be the default heap size for this + program, unless the user overrides it. (Depending on the setting of + the ``-rtsopts`` option, the user might not have the ability to + change RTS options at run-time, in which case ``-with-rtsopts`` + would be the *only* way to set them.) + + Note that ``-with-rtsopts`` has no effect when used with + ``-no-hs-main``; see :ref:`using-own-main` for details. + +``-no-rtsopts-suggestions`` + .. index:: + single: -no-rtsopts-suggestions + + This option disables RTS suggestions about linking with ``-rtsopts`` + when they are not available. These suggestions would be unhelpful if + the users have installed Haskell programs through their package + managers. With this option enabled, these suggestions will not + appear. It is recommended for people distributing binaries to build + with either ``-rtsopts`` or ``-no-rtsopts-suggestions``. + +``-fno-gen-manifest`` + .. index:: + single: -fno-gen-manifest + + On Windows, GHC normally generates a manifestmanifest file when + linking a binary. The manifest is placed in the file + ``prog.exe.manifest`` where ⟨prog.exe⟩ is the name of the + executable. The manifest file currently serves just one purpose: it + disables the "installer detection"installer detectionin Windows + Vista that attempts to elevate privileges for executables with + certain names (e.g. names containing "install", "setup" or "patch"). + Without the manifest file to turn off installer detection, + attempting to run an executable that Windows deems to be an + installer will return a permission error code to the invoker. + Depending on the invoker, the result might be a dialog box asking + the user for elevated permissions, or it might simply be a + permission denied error. + + Installer detection can be also turned off globally for the system + using the security control panel, but GHC by default generates + binaries that don't depend on the user having disabled installer + detection. + + The ``-fno-gen-manifest`` disables generation of the manifest file. + One reason to do this would be if you had a manifest file of your + own, for example. + + In the future, GHC might use the manifest file for more things, such + as supplying the location of dependent DLLs. + + ``-fno-gen-manifest`` also implies ``-fno-embed-manifest``, see + below. + +``-fno-embed-manifest`` + .. index:: + single: -fno-embed-manifest + single: windres + + The manifest file that GHC generates when linking a binary on + Windows is also embedded in the executable itself, by default. This + means that the binary can be distributed without having to supply + the manifest file too. The embedding is done by running + ``windres``; to see exactly what GHC does to embed the + manifest, use the ``-v`` flag. A GHC installation comes with its own + copy of ``windres`` for this reason. + + See also ``-pgmwindres`` (:ref:`replacing-phases`) and + ``-optwindres`` (:ref:`forcing-options-through`). + +``-fno-shared-implib`` + .. index:: + single: -fno-shared-implib + + DLLs on Windows are typically linked to by linking to a + corresponding ``.lib`` or ``.dll.a`` — the so-called import library. + GHC will typically generate such a file for every DLL you create by + compiling in ``-shared`` mode. However, sometimes you don't want to + pay the disk-space cost of creating this import library, which can + be substantial — it might require as much space as the code itself, + as Haskell DLLs tend to export lots of symbols. + + As long as you are happy to only be able to link to the DLL using + ``GetProcAddress`` and friends, you can supply the + ``-fno-shared-implib`` flag to disable the creation of the import + library entirely. + +``-dylib-install-name path`` + .. index:: + single: -dylib-install-name + + On Darwin/OS X, dynamic libraries are stamped at build time with an + "install name", which is the ultimate install path of the library + file. Any libraries or executables that subsequently link against it + will pick up that path as their runtime search location for it. By + default, ghc sets the install name to the location where the library + is built. This option allows you to override it with the specified + file path. (It passes ``-install_name`` to Apple's linker.) Ignored + on other platforms. + +``-rdynamic`` + .. index:: + single: -rdynamic + + This instructs the linker to add all symbols, not only used ones, to + the dynamic symbol table. Currently Linux and Windows/MinGW32 only. + This is equivalent to using ``-optl -rdynamic`` on Linux, and + ``-optl -export-all-symbols`` on Windows. diff --git a/docs/users_guide/phases.xml b/docs/users_guide/phases.xml deleted file mode 100644 index eefef55d79..0000000000 --- a/docs/users_guide/phases.xml +++ /dev/null @@ -1,1373 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<sect1 id="options-phases"> - <title>Options related to a particular phase</title> - - <sect2 id="replacing-phases"> - <title>Replacing the program for one or more phases</title> - <indexterm><primary>phases, changing</primary></indexterm> - - <para>You may specify that a different program be used for one - of the phases of the compilation system, in place of whatever - the <command>ghc</command> has wired into it. For example, you - might want to try a different assembler. The following options - allow you to change the external program used for a given - compilation phase:</para> - - <variablelist> - <varlistentry> - <term> - <option>-pgmL</option> <replaceable>cmd</replaceable> - <indexterm><primary><option>-pgmL</option></primary></indexterm> - </term> - <listitem> - <para>Use <replaceable>cmd</replaceable> as the literate - pre-processor.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-pgmP</option> <replaceable>cmd</replaceable> - <indexterm><primary><option>-pgmP</option></primary></indexterm> - </term> - <listitem> - <para>Use <replaceable>cmd</replaceable> as the C - pre-processor (with <option>-cpp</option> only).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-pgmc</option> <replaceable>cmd</replaceable> - <indexterm><primary><option>-pgmc</option></primary></indexterm> - </term> - <listitem> - <para>Use <replaceable>cmd</replaceable> as the C - compiler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-pgmlo</option> <replaceable>cmd</replaceable> - <indexterm><primary><option>-pgmlo</option></primary></indexterm> - </term> - <listitem> - <para>Use <replaceable>cmd</replaceable> as the LLVM - optimiser.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-pgmlc</option> <replaceable>cmd</replaceable> - <indexterm><primary><option>-pgmlc</option></primary></indexterm> - </term> - <listitem> - <para>Use <replaceable>cmd</replaceable> as the LLVM - compiler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-pgms</option> <replaceable>cmd</replaceable> - <indexterm><primary><option>-pgms</option></primary></indexterm> - </term> - <listitem> - <para>Use <replaceable>cmd</replaceable> as the - splitter.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-pgma</option> <replaceable>cmd</replaceable> - <indexterm><primary><option>-pgma</option></primary></indexterm> - </term> - <listitem> - <para>Use <replaceable>cmd</replaceable> as the - assembler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-pgml</option> <replaceable>cmd</replaceable> - <indexterm><primary><option>-pgml</option></primary></indexterm> - </term> - <listitem> - <para>Use <replaceable>cmd</replaceable> as the - linker.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-pgmdll</option> <replaceable>cmd</replaceable> - <indexterm><primary><option>-pgmdll</option></primary></indexterm> - </term> - <listitem> - <para>Use <replaceable>cmd</replaceable> as the DLL - generator.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-pgmF</option> <replaceable>cmd</replaceable> - <indexterm><primary><option>-pgmF</option></primary></indexterm> - </term> - <listitem> - <para>Use <replaceable>cmd</replaceable> as the - pre-processor (with <option>-F</option> only).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-pgmwindres</option> <replaceable>cmd</replaceable> - <indexterm><primary><option>-pgmwindres</option></primary></indexterm> - </term> - <listitem> - <para>Use <replaceable>cmd</replaceable> as the - program to use for embedding manifests on Windows. Normally this - is the program <literal>windres</literal>, which is supplied with a - GHC installation. See <option>-fno-embed-manifest</option> in <xref - linkend="options-linker" />.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-pgmlibtool</option> <replaceable>cmd</replaceable> - <indexterm><primary><option>-pgmlibtool</option></primary></indexterm> - </term> - <listitem> - <para>Use <replaceable>cmd</replaceable> as the libtool command - (when using <option>-staticlib</option> only).</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="forcing-options-through"> - <title>Forcing options to a particular phase</title> - <indexterm><primary>forcing GHC-phase options</primary></indexterm> - - <para>Options can be forced through to a particular compilation - phase, using the following flags:</para> - - <variablelist> - <varlistentry> - <term> - <option>-optL</option> <replaceable>option</replaceable> - <indexterm><primary><option>-optL</option></primary></indexterm> - </term> - <listitem> - <para>Pass <replaceable>option</replaceable> to the - literate pre-processor</para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>-optP</option> <replaceable>option</replaceable> - <indexterm><primary><option>-optP</option></primary></indexterm> - </term> - <listitem> - <para>Pass <replaceable>option</replaceable> to CPP (makes - sense only if <option>-cpp</option> is also on).</para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>-optF</option> <replaceable>option</replaceable> - <indexterm><primary><option>-optF</option></primary></indexterm> - </term> - <listitem> - <para>Pass <replaceable>option</replaceable> to the - custom pre-processor (see <xref linkend="pre-processor"/>).</para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>-optc</option> <replaceable>option</replaceable> - <indexterm><primary><option>-optc</option></primary></indexterm> - </term> - <listitem> - <para>Pass <replaceable>option</replaceable> to the C compiler.</para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>-optlo</option> <replaceable>option</replaceable> - <indexterm><primary><option>-optlo</option></primary></indexterm> - </term> - <listitem> - <para>Pass <replaceable>option</replaceable> to the LLVM optimiser.</para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>-optlc</option> <replaceable>option</replaceable> - <indexterm><primary><option>-optlc</option></primary></indexterm> - </term> - <listitem> - <para>Pass <replaceable>option</replaceable> to the LLVM compiler.</para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>-opta</option> <replaceable>option</replaceable> - <indexterm><primary><option>-opta</option></primary></indexterm> - </term> - <listitem> - <para>Pass <replaceable>option</replaceable> to the assembler.</para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>-optl</option> <replaceable>option</replaceable> - <indexterm><primary><option>-optl</option></primary></indexterm> - </term> - <listitem> - <para>Pass <replaceable>option</replaceable> to the linker.</para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>-optdll</option> <replaceable>option</replaceable> - <indexterm><primary><option>-optdll</option></primary></indexterm> - </term> - <listitem> - <para>Pass <replaceable>option</replaceable> to the DLL generator.</para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>-optwindres</option> <replaceable>option</replaceable> - <indexterm><primary><option>-optwindres</option></primary></indexterm> - </term> - <listitem> - <para>Pass <replaceable>option</replaceable> to - <literal>windres</literal> when embedding manifests on Windows. - See <option>-fno-embed-manifest</option> in <xref - linkend="options-linker" />.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>So, for example, to force an <option>-Ewurble</option> - option to the assembler, you would tell the driver - <option>-opta-Ewurble</option> (the dash before the E is - required).</para> - - <para>GHC is itself a Haskell program, so if you need to pass - options directly to GHC's runtime system you can enclose them in - <literal>+RTS ... -RTS</literal> (see <xref - linkend="runtime-control"/>).</para> - - </sect2> - - <sect2 id="c-pre-processor"> - <title>Options affecting the C pre-processor</title> - - <indexterm><primary>pre-processing: cpp</primary></indexterm> - <indexterm><primary>C pre-processor options</primary></indexterm> - <indexterm><primary>cpp, pre-processing with</primary></indexterm> - - <variablelist> - - <varlistentry> - <term> - <option>-cpp</option> - <indexterm><primary><option>-cpp</option></primary></indexterm> - </term> - <listitem> - <para>The C pre-processor <command>cpp</command> is run - over your Haskell code only if the <option>-cpp</option> - option <indexterm><primary>-cpp - option</primary></indexterm> is given. Unless you are - building a large system with significant doses of - conditional compilation, you really shouldn't need - it.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional> - <indexterm><primary><option>-D</option></primary></indexterm> - </term> - <listitem> - <para>Define macro <replaceable>symbol</replaceable> in the - usual way. NB: does <emphasis>not</emphasis> affect - <option>-D</option> macros passed to the C compiler - when compiling via C! For those, use the - <option>-optc-Dfoo</option> hack… (see <xref - linkend="forcing-options-through"/>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-U</option><replaceable>symbol</replaceable> - <indexterm><primary><option>-U</option></primary></indexterm> - </term> - <listitem> - <para> Undefine macro <replaceable>symbol</replaceable> in the - usual way.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-I</option><replaceable>dir</replaceable> - <indexterm><primary><option>-I</option></primary></indexterm> - </term> - <listitem> - <para> Specify a directory in which to look for - <literal>#include</literal> files, in the usual C - way.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The GHC driver pre-defines several macros when processing - Haskell source code (<filename>.hs</filename> or - <filename>.lhs</filename> files).</para> - - <para>The symbols defined by GHC are listed below. To check which - symbols are defined by your local GHC installation, the following - trick is useful:</para> - -<screen>$ ghc -E -optP-dM -cpp foo.hs -$ cat foo.hspp</screen> - - <para>(you need a file <filename>foo.hs</filename>, but it isn't - actually used).</para> - - <variablelist> - <varlistentry> - <term> - <constant>__GLASGOW_HASKELL__</constant> - <indexterm><primary><constant>__GLASGOW_HASKELL__</constant></primary></indexterm> - </term> - <listitem> - <para>For version - <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal> - of GHC, the value of - <constant>__GLASGOW_HASKELL__</constant> - is the integer <replaceable>xyy</replaceable> (if - <replaceable>y</replaceable> is a single digit, then a leading zero - is added, so for example in version 6.2 of GHC, - <literal>__GLASGOW_HASKELL__==602</literal>). More - information in <xref linkend="version-numbering"/>.</para> - - <para>With any luck, - <constant>__GLASGOW_HASKELL__</constant> - will be undefined in all other implementations that - support C-style pre-processing.</para> - - <para>(For reference: the comparable symbols for other - systems are: - <constant>__HUGS__</constant> - for Hugs, - <constant>__NHC__</constant> - for nhc98, and - <constant>__HBC__</constant> - for hbc.)</para> - - <para>NB. This macro is set when pre-processing both - Haskell source and C source, including the C source - generated from a Haskell module - (i.e. <filename>.hs</filename>, <filename>.lhs</filename>, - <filename>.c</filename> and <filename>.hc</filename> - files).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <constant>__GLASGOW_HASKELL_PATCHLEVEL1__</constant> - <indexterm><primary><constant>__GLASGOW_HASKELL_PATCHLEVEL1__</constant></primary></indexterm> - </term> - <term> - <constant>__GLASGOW_HASKELL_PATCHLEVEL2__</constant> - <indexterm><primary><constant>__GLASGOW_HASKELL_PATCHLEVEL2__</constant></primary></indexterm> - </term> - <listitem> - <para>These macros are available starting with GHC 7.10.1.</para> - - <para>For three-part GHC version numbers - <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>, - the value of - <constant>__GLASGOW_HASKELL_PATCHLEVEL1__</constant> - is the integer <replaceable>z</replaceable>.</para> - - <para>For four-part GHC version numbers - <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>.<replaceable>z'</replaceable></literal>, - the value of - <constant>__GLASGOW_HASKELL_PATCHLEVEL1__</constant> - is the integer <replaceable>z</replaceable> while the value of - <constant>__GLASGOW_HASKELL_PATCHLEVEL2__</constant> - is set to the integer <replaceable>z'</replaceable>.</para> - - <para>These macros are provided for allowing finer - granularity than is provided by - <literal>__GLASGOW_HASKELL__</literal>. Usually, this should - not be necessary as it's expected for most APIs to remain - stable between patchlevel releases, but occasionally - internal API changes are necessary to fix bugs. Also - conditional compilation on the patchlevel can be useful for - working around bugs in older releases.</para> - - <para>NB. These macros are set when pre-processing both - Haskell source and C source, including the C source - generated from a Haskell module - (i.e. <filename>.hs</filename>, <filename>.lhs</filename>, - <filename>.c</filename> and <filename>.hc</filename> - files).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <constant>MIN_VERSION_GLASGOW_HASKELL(<replaceable>x</replaceable>,<replaceable>y</replaceable>,<replaceable>z</replaceable>,<replaceable>z'</replaceable>)</constant> - <indexterm><primary><constant>MIN_VERSION_GLASGOW_HASKELL</constant></primary></indexterm> - </term> - <listitem> - <para>This macro is available starting with GHC 7.10.1.</para> - - <para>This macro is provided for convenience to write CPP - conditionals testing whether the GHC version used is version - <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>.<replaceable>z'</replaceable></literal> - or later.</para> - - <para>If compatibility with Haskell compilers (including GHC - prior to version 7.10.1) which do not define - <literal>MIN_VERSION_GLASGOW_HASKELL</literal> is required, - the presence of the - <literal>MIN_VERSION_GLASGOW_HASKELL</literal> macro needs - to be ensured before it is called, e.g.:</para> - -<programlisting>#ifdef MIN_VERSION_GLASGOW_HASKELL -#if MIN_VERSION_GLASGOW_HASKELL(7,10,2,0) -/* code that applies only to GHC 7.10.2 or later */ -#endif -#endif</programlisting> - - <para>NB. This macro is set when pre-processing both - Haskell source and C source, including the C source - generated from a Haskell module - (i.e. <filename>.hs</filename>, <filename>.lhs</filename>, - <filename>.c</filename> and <filename>.hc</filename> - files).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <constant>__GLASGOW_HASKELL_TH__</constant> - <indexterm><primary><constant>__GLASGOW_HASKELL_TH__</constant></primary></indexterm> - </term> - <listitem> - <para> - This is set to <literal>YES</literal> when the compiler supports Template Haskell, and to - <literal>NO</literal> when not. The latter is the case for a stage-1 compiler during bootstrapping, or - on architectures where the interpreter is not available. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term> - <constant>__GLASGOW_HASKELL_LLVM__</constant> - <indexterm><primary><constant>__GLASGOW_HASKELL_LLVM__</constant></primary></indexterm> - </term> - <listitem> - <para>Only defined when <option>-fllvm</option> is specified. When GHC - is using version - <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal> - of LLVM, the value of - <constant>__GLASGOW_HASKELL_LLVM__</constant> - is the integer <replaceable>xy</replaceable>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <constant>__PARALLEL_HASKELL__</constant> - <indexterm><primary><constant>__PARALLEL_HASKELL__</constant></primary></indexterm> - </term> - <listitem> - <para>Only defined when <option>-parallel</option> is in - use! This symbol is defined when pre-processing Haskell - (input) and pre-processing C (GHC output).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <constant><replaceable>os</replaceable>_HOST_OS=1</constant> - </term> - <listitem> - <para>This define allows conditional compilation based on - the Operating System, where<replaceable>os</replaceable> is - the name of the current Operating System - (eg. <literal>linux</literal>, <literal>mingw32</literal> - for Windows, <literal>solaris</literal>, etc.).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <constant><replaceable>arch</replaceable>_HOST_ARCH=1</constant> - </term> - <listitem> - <para>This define allows conditional compilation based on - the host architecture, where<replaceable>arch</replaceable> - is the name of the current architecture - (eg. <literal>i386</literal>, <literal>x86_64</literal>, - <literal>powerpc</literal>, <literal>sparc</literal>, - etc.).</para> - </listitem> - </varlistentry> - </variablelist> - - <sect3 id="cpp-string-gaps"> - <title>CPP and string gaps</title> - - <para>A small word of warning: <option>-cpp</option> is not - friendly to “string gaps”.<indexterm><primary>-cpp - vs string gaps</primary></indexterm><indexterm><primary>string - gaps vs -cpp</primary></indexterm>. In other words, strings - such as the following:</para> - -<programlisting>strmod = "\ -\ p \ -\ "</programlisting> - - <para>don't work with <option>-cpp</option>; - <filename>/usr/bin/cpp</filename> elides the backslash-newline - pairs.</para> - - <para>However, it appears that if you add a space at the end - of the line, then <command>cpp</command> (at least GNU - <command>cpp</command> and possibly other - <command>cpp</command>s) leaves the backslash-space pairs - alone and the string gap works as expected.</para> - </sect3> - </sect2> - - <sect2 id="pre-processor"> - <title>Options affecting a Haskell pre-processor</title> - - <indexterm><primary>pre-processing: custom</primary></indexterm> - <indexterm><primary>Pre-processor options</primary></indexterm> - - <variablelist> - <varlistentry> - <term> - <option>-F</option> - <indexterm><primary><option>-F</option></primary></indexterm> - </term> - <listitem> - <para>A custom pre-processor is run over your Haskell - source file only if the <option>-F</option> option - <indexterm><primary>-F</primary></indexterm> is - given.</para> - - <para>Running a custom pre-processor at compile-time is in - some settings appropriate and useful. The - <option>-F</option> option lets you run a pre-processor as - part of the overall GHC compilation pipeline, which has - the advantage over running a Haskell pre-processor - separately in that it works in interpreted mode and you - can continue to take reap the benefits of GHC's - recompilation checker.</para> - - <para>The pre-processor is run just before the Haskell - compiler proper processes the Haskell input, but after the - literate markup has been stripped away and (possibly) the - C pre-processor has washed the Haskell input.</para> - - <para>Use - <option>-pgmF <replaceable>cmd</replaceable></option> - to select the program to use as the preprocessor. When - invoked, the <replaceable>cmd</replaceable> pre-processor - is given at least three arguments on its command-line: the - first argument is the name of the original source file, - the second is the name of the file holding the input, and - the third is the name of the file where - <replaceable>cmd</replaceable> should write its output - to.</para> - - <para>Additional arguments to the pre-processor can be - passed in using the <option>-optF</option> option. These - are fed to <replaceable>cmd</replaceable> on the command - line after the three standard input and output - arguments.</para> - - <para> - An example of a pre-processor is to convert your source files to the - input encoding that GHC expects, i.e. create a script - <literal>convert.sh</literal> containing the lines: - </para> - -<screen>#!/bin/sh -( echo "{-# LINE 1 \"$2\" #-}" ; iconv -f l1 -t utf-8 $2 ) > $3</screen> - - <para>and pass <literal>-F -pgmF convert.sh</literal> to GHC. - The <literal>-f l1</literal> option tells iconv to convert your - Latin-1 file, supplied in argument <literal>$2</literal>, while - the "-t utf-8" options tell iconv to return a UTF-8 encoded file. - The result is redirected into argument <literal>$3</literal>. - The <literal>echo "{-# LINE 1 \"$2\" #-}"</literal> - just makes sure that your error positions are reported as - in the original source file.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="options-codegen"> - <title>Options affecting code generation</title> - - <variablelist> - <varlistentry> - <term> - <option>-fasm</option> - <indexterm><primary><option>-fasm</option></primary></indexterm> - </term> - <listitem> - <para>Use GHC's <link linkend="native-code-gen">native code generator - </link>rather than compiling via LLVM. - <option>-fasm</option> is the default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fllvm</option> - <indexterm><primary><option>-fllvm</option></primary></indexterm> - </term> - <listitem> - <para>Compile via <link linkend="llvm-code-gen">LLVM</link>instead - of using the native code generator. This will generally take slightly - longer than the native code generator to compile. Produced code is - generally the same speed or faster than the other two code - generators. Compiling via LLVM requires LLVM to be on the - path.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fno-code</option> - <indexterm><primary><option>-fno-code</option></primary></indexterm> - </term> - <listitem> - <para>Omit code generation (and all later phases) - altogether. This is useful if you're only interested in - type checking code.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fwrite-interface</option> - <indexterm><primary><option>-fwrite-interface</option></primary></indexterm> - </term> - <listitem> - <para>Always write interface files. GHC will normally write - interface files automatically, but this flag is useful with - <option>-fno-code</option>, which normally suppresses generation - of interface files. This is useful if you want to type check - over multiple runs of GHC without compiling dependencies.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fobject-code</option> - <indexterm><primary><option>-fobject-code</option></primary></indexterm> - </term> - <listitem> - <para>Generate object code. This is the default outside of - GHCi, and can be used with GHCi to cause object code to be - generated in preference to bytecode.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fbyte-code</option> - <indexterm><primary><option>-fbyte-code</option></primary></indexterm> - </term> - <listitem> - <para>Generate byte-code instead of object-code. This is - the default in GHCi. Byte-code can currently only be used - in the interactive interpreter, not saved to disk. This - option is only useful for reversing the effect of - <option>-fobject-code</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fPIC</option> - <indexterm><primary><option>-fPIC</option></primary></indexterm> - </term> - <listitem> - <para>Generate position-independent code (code that can be put into - shared libraries). This currently works on Linux x86 and x86-64. On - Windows, position-independent code is never used so the flag is a - no-op on that platform.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dynamic</option> - </term> - <listitem> - <para>When generating code, assume that entities imported from a - different package will reside in a different shared library or - binary.</para> - <para>Note that using this option when linking causes GHC to link - against shared libraries.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="options-linker"> - <title>Options affecting linking</title> - - <indexterm><primary>linker options</primary></indexterm> - <indexterm><primary>ld options</primary></indexterm> - - - <para>GHC has to link your code with various libraries, possibly - including: user-supplied, GHC-supplied, and system-supplied - (<option>-lm</option> math library, for example).</para> - - <variablelist> - - <varlistentry> - <term> - <option>-l</option><replaceable>lib</replaceable> - <indexterm><primary><option>-l</option></primary></indexterm> - </term> - <listitem> - <para>Link in the <replaceable>lib</replaceable> library. - On Unix systems, this will be in a file called - <filename>lib<replaceable>lib</replaceable>.a</filename> - or - <filename>lib<replaceable>lib</replaceable>.so</filename> - which resides somewhere on the library directories path.</para> - - <para>Because of the sad state of most UNIX linkers, the - order of such options does matter. If library - <replaceable>foo</replaceable> requires library - <replaceable>bar</replaceable>, then in general - <option>-l</option><replaceable>foo</replaceable> should - come <emphasis>before</emphasis> - <option>-l</option><replaceable>bar</replaceable> on the - command line.</para> - - <para>There's one other gotcha to bear in mind when using - external libraries: if the library contains a - <literal>main()</literal> function, then this will be - linked in preference to GHC's own - <literal>main()</literal> function - (eg. <literal>libf2c</literal> and <literal>libl</literal> - have their own <literal>main()</literal>s). This is - because GHC's <literal>main()</literal> comes from the - <literal>HSrts</literal> library, which is normally - included <emphasis>after</emphasis> all the other - libraries on the linker's command line. To force GHC's - <literal>main()</literal> to be used in preference to any - other <literal>main()</literal>s from external libraries, - just add the option <option>-lHSrts</option> before any - other libraries on the command line.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-c</option> - <indexterm><primary><option>-c</option></primary></indexterm> - </term> - <listitem> - <para>Omits the link step. This option can be used with - <option>--make</option> to avoid the automatic linking - that takes place if the program contains a <literal>Main</literal> - module.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-package</option> <replaceable>name</replaceable> - <indexterm><primary><option>-package</option></primary></indexterm> - </term> - <listitem> - <para>If you are using a Haskell “package” - (see <xref linkend="packages"/>), don't forget to add the - relevant <option>-package</option> option when linking the - program too: it will cause the appropriate libraries to be - linked in with the program. Forgetting the - <option>-package</option> option will likely result in - several pages of link errors.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-framework</option> <replaceable>name</replaceable> - <indexterm><primary><option>-framework</option></primary></indexterm> - </term> - <listitem> - <para>On Darwin/OS X/iOS only, link in the framework <replaceable>name</replaceable>. - This option corresponds to the <option>-framework</option> option for Apple's Linker. - Please note that frameworks and packages are two different things - frameworks don't - contain any Haskell code. Rather, they are Apple's way of packaging shared libraries. - To link to Apple's “Carbon” API, for example, you'd use - <option>-framework Carbon</option>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-staticlib</option> - <indexterm><primary><option>-staticlib</option></primary></indexterm> - </term> - <listitem> - <para>On Darwin/OS X/iOS only, link all passed files into a static library suitable - for linking into an iOS (when using a cross-compiler) or Mac Xcode project. To control - the name, use the <option>-o</option> <replaceable>name</replaceable> option as usual. - The default name is <literal>liba.a</literal>. - This should nearly always be passed when compiling for iOS with a cross-compiler. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-L</option><replaceable>dir</replaceable> - <indexterm><primary><option>-L</option></primary></indexterm> - </term> - <listitem> - <para>Where to find user-supplied libraries… - Prepend the directory <replaceable>dir</replaceable> to - the library directories path.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-framework-path</option><replaceable>dir</replaceable> - <indexterm><primary><option>-framework-path</option></primary></indexterm> - </term> - <listitem> - <para>On Darwin/OS X/iOS only, prepend the directory <replaceable>dir</replaceable> to - the framework directories path. This option corresponds to the <option>-F</option> - option for Apple's Linker (<option>-F</option> already means something else for GHC).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-split-objs</option> - <indexterm><primary><option>-split-objs</option></primary></indexterm> - </term> - <listitem> - <para>Tell the linker to split the single object file that - would normally be generated into multiple object files, - one per top-level Haskell function or type in the module. - This only makes sense for libraries, where it means that - executables linked against the library are smaller as they only - link against the object files that they need. However, assembling - all the sections separately is expensive, so this is slower than - compiling normally. Additionally, the size of the library itself - (the <literal>.a</literal> file) can be a factor of 2 to 2.5 - larger. - We use this feature for building GHC's libraries.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-static</option> - <indexterm><primary><option>-static</option></primary></indexterm> - </term> - <listitem> - <para>Tell the linker to avoid shared Haskell libraries, - if possible. This is the default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dynamic</option> - <indexterm><primary><option>-dynamic</option></primary></indexterm> - </term> - <listitem> - <para>This flag tells GHC to link against shared Haskell libraries. - This flag only affects the selection of dependent libraries, not - the form of the current target (see -shared). - See <xref linkend="using-shared-libs" /> on how to - create them.</para> - - <para>Note that this option also has an effect on - code generation (see above).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-shared</option> - <indexterm><primary><option>-shared</option></primary></indexterm> - </term> - <listitem> - <para>Instead of creating an executable, GHC produces a - shared object with this linker flag. Depending on the - operating system target, this might be an ELF DSO, a Windows - DLL, or a Mac OS dylib. GHC hides the operating system - details beneath this uniform flag.</para> - - <para>The flags <option>-dynamic</option>/<option>-static</option> control whether the - resulting shared object links statically or dynamically to - Haskell package libraries given as <option>-package</option> option. Non-Haskell - libraries are linked as gcc would regularly link it on your - system, e.g. on most ELF system the linker uses the dynamic - libraries when found.</para> - - <para>Object files linked into shared objects must be - compiled with <option>-fPIC</option>, see <xref linkend="options-codegen" /></para> - - <para>When creating shared objects for Haskell packages, the - shared object must be named properly, so that GHC recognizes - the shared object when linked against this package. See - shared object name mangling.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dynload</option> - <indexterm><primary><option>-dynload</option></primary></indexterm> - </term> - <listitem> - <para> - This flag selects one of a number of modes for finding shared - libraries at runtime. See <xref linkend="finding-shared-libs"/> for - a description of each mode. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-main-is <replaceable>thing</replaceable></option> - <indexterm><primary><option>-main-is</option></primary></indexterm> - <indexterm><primary>specifying your own main function</primary></indexterm> - </term> - <listitem> - <para> The normal rule in Haskell is that your program must supply a <literal>main</literal> - function in module <literal>Main</literal>. When testing, it is often convenient - to change which function is the "main" one, and the <option>-main-is</option> flag - allows you to do so. The <replaceable>thing</replaceable> can be one of: - <itemizedlist> - <listitem><para>A lower-case identifier <literal>foo</literal>. GHC assumes that the main function is <literal>Main.foo</literal>.</para></listitem> - <listitem><para>A module name <literal>A</literal>. GHC assumes that the main function is <literal>A.main</literal>.</para></listitem> - <listitem><para>A qualified name <literal>A.foo</literal>. GHC assumes that the main function is <literal>A.foo</literal>.</para></listitem> - </itemizedlist> - Strictly speaking, <option>-main-is</option> is not a link-phase flag at all; it has no effect on the link step. - The flag must be specified when compiling the module containing the specified main function (e.g. module <literal>A</literal> - in the latter two items above). It has no effect for other modules, - and hence can safely be given to <literal>ghc --make</literal>. - However, if all the modules are otherwise up to date, you may need to force - recompilation both of the module where the new "main" is, and of the - module where the "main" function used to be; - <literal>ghc</literal> is not clever - enough to figure out that they both need recompiling. You can - force recompilation by removing the object file, or by using the - <option>-fforce-recomp</option> flag. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-no-hs-main</option> - <indexterm><primary><option>-no-hs-main</option></primary></indexterm> - <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm> - </term> - <listitem> - <para>In the event you want to include ghc-compiled code - as part of another (non-Haskell) program, the RTS will not - be supplying its definition of <function>main()</function> - at link-time, you will have to. To signal that to the - compiler when linking, use - <option>-no-hs-main</option>. See also <xref linkend="using-own-main"/>.</para> - - <para>Notice that since the command-line passed to the - linker is rather involved, you probably want to use - <command>ghc</command> to do the final link of your - `mixed-language' application. This is not a requirement - though, just try linking once with <option>-v</option> on - to see what options the driver passes through to the - linker.</para> - - <para>The <option>-no-hs-main</option> flag can also be - used to persuade the compiler to do the link step in - <option>--make</option> mode when there is no Haskell - <literal>Main</literal> module present (normally the - compiler will not attempt linking when there is no - <literal>Main</literal>).</para> - - <para>The flags <option>-rtsopts</option> - and <option>-with-rtsopts</option> have no effect when - used with <option>-no-hs-main</option>, because they are - implemented by changing the definition - of <literal>main</literal> that GHC generates. See - <xref linkend="using-own-main" /> for how to get the - effect of <option>-rtsopts</option> - and <option>-with-rtsopts</option> when using your - own <literal>main</literal>. - </para> - - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-debug</option> - <indexterm><primary><option>-debug</option></primary></indexterm> - </term> - <listitem> - <para>Link the program with a debugging version of the - runtime system. The debugging runtime turns on numerous - assertions and sanity checks, and provides extra options - for producing debugging output at runtime (run the program - with <literal>+RTS -?</literal> to see a list).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-threaded</option> - <indexterm><primary><option>-threaded</option></primary></indexterm> - </term> - <listitem> - <para>Link the program with the "threaded" version of the - runtime system. The threaded runtime system is so-called - because it manages multiple OS threads, as opposed to the - default runtime system which is purely - single-threaded.</para> - - <para>Note that you do <emphasis>not</emphasis> need - <option>-threaded</option> in order to use concurrency; the - single-threaded runtime supports concurrency between Haskell - threads just fine.</para> - - <para>The threaded runtime system provides the following - benefits:</para> - - <itemizedlist> - <listitem> - <para>It enables the <option>-N</option><indexterm><primary><option>-N<replaceable>x</replaceable></option></primary><secondary>RTS option</secondary></indexterm> RTS option to be - used, which allows threads to run in - parallel<indexterm><primary>parallelism</primary></indexterm> - on a - multiprocessor<indexterm><primary>multiprocessor</primary></indexterm><indexterm><primary>SMP</primary></indexterm> - or - multicore<indexterm><primary>multicore</primary></indexterm> - machine. See <xref linkend="using-smp" />.</para> - </listitem> - <listitem> - <para>If a thread makes a foreign call (and the call is - not marked <literal>unsafe</literal>), then other - Haskell threads in the program will continue to run - while the foreign call is in progress. - Additionally, <literal>foreign export</literal>ed - Haskell functions may be called from multiple OS - threads simultaneously. See - <xref linkend="ffi-threads" />.</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-eventlog</option> - <indexterm><primary><option>-eventlog</option></primary></indexterm> - </term> - <listitem> - <para> - Link the program with the "eventlog" version of the - runtime system. A program linked in this way can generate - a runtime trace of events (such as thread start/stop) to a - binary file - <literal><replaceable>program</replaceable>.eventlog</literal>, - which can then be interpreted later by various tools. See - <xref linkend="rts-eventlog" /> for more information. - </para> - <para> - <option>-eventlog</option> can be used - with <option>-threaded</option>. It is implied - by <option>-debug</option>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-rtsopts</option> - <indexterm><primary><option>-rtsopts</option></primary></indexterm> - </term> - <listitem> - <para> - This option affects the processing of RTS control options given either - on the command line or via the <envar>GHCRTS</envar> environment variable. - There are three possibilities: - </para> - <variablelist> - <varlistentry> - <term><option>-rtsopts=none</option></term> - <listitem> - <para> - Disable all processing of RTS options. - If <option>+RTS</option> appears anywhere on the command - line, then the program will abort with an error message. - If the <envar>GHCRTS</envar> environment variable is - set, then the program will emit a warning message, - <envar>GHCRTS</envar> will be ignored, and the program - will run as normal. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-rtsopts=some</option></term> - <listitem> - <para>[this is the default setting] Enable - only the "safe" RTS options: (Currently - only <option>-?</option> - and <option>--info</option>.) Any other RTS options - on the command line or in the <envar>GHCRTS</envar> - environment variable causes the program with to abort - with an error message. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-rtsopts=all</option>, or - just <option>-rtsopts</option></term> - <listitem> - <para> - Enable <emphasis>all</emphasis> RTS option - processing, both on the command line and through - the <envar>GHCRTS</envar> environment variable. - </para> - </listitem> - </varlistentry> - </variablelist> - <para> - In GHC 6.12.3 and earlier, the default was to process all - RTS options. However, since RTS options can be used to - write logging data to arbitrary files under the security - context of the running program, there is a potential - security problem. For this reason, GHC 7.0.1 and later - default to <option>-rtsops=some</option>. - </para> - - <para> - Note that <option>-rtsopts</option> has no effect when - used with <option>-no-hs-main</option>; see - <xref linkend="using-own-main" /> for details. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-with-rtsopts</option> - <indexterm><primary><option>-with-rtsopts</option></primary></indexterm> - </term> - <listitem> - <para> - This option allows you to set the default RTS options at link-time. For example, - <option>-with-rtsopts="-H128m"</option> sets the default heap size to 128MB. - This will always be the default heap size for this program, unless the user overrides it. - (Depending on the setting of the <option>-rtsopts</option> option, the user might - not have the ability to change RTS options at run-time, in which case - <option>-with-rtsopts</option> would be the <emphasis>only</emphasis> way to set - them.) - </para> - - <para> - Note that <option>-with-rtsopts</option> has no effect when - used with <option>-no-hs-main</option>; see - <xref linkend="using-own-main" /> for details. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-no-rtsopts-suggestions</option> - <indexterm><primary><option>-no-rtsopts-suggestions</option></primary></indexterm> - </term> - <listitem> - <para> - This option disables RTS suggestions about linking with <option>-rtsopts</option> - when they are not available. - - These suggestions would be unhelpful if the users have installed Haskell programs - through their package managers. - With this option enabled, these suggestions will not appear. - - It is recommended for people distributing binaries - to build with either <option>-rtsopts</option> or - <option>-no-rtsopts-suggestions</option>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fno-gen-manifest</option> - <indexterm><primary><option>-fno-gen-manifest</option></primary> - </indexterm> - </term> - <listitem> - <para>On Windows, GHC normally generates a - <firstterm>manifest</firstterm><indexterm><primary>manifest</primary> - </indexterm> file when linking a binary. The - manifest is placed in the file - <literal><replaceable>prog</replaceable>.exe.manifest</literal> - where <replaceable>prog.exe</replaceable> is the name of the - executable. The manifest file currently serves just one purpose: - it disables the "installer detection"<indexterm><primary>installer detection</primary> - </indexterm>in Windows Vista that - attempts to elevate privileges for executables with certain names - (e.g. names containing "install", "setup" or "patch"). Without the - manifest file to turn off installer detection, attempting to run an - executable that Windows deems to be an installer will return a - permission error code to the invoker. Depending on the invoker, - the result might be a dialog box asking the user for elevated - permissions, or it might simply be a permission denied - error.</para> - - <para>Installer detection can be also turned off globally for the - system using the security control panel, but GHC by default - generates binaries that don't depend on the user having disabled - installer detection.</para> - - <para>The <option>-fno-gen-manifest</option> disables generation of - the manifest file. One reason to do this would be if you had - a manifest file of your own, for example.</para> - - <para>In the future, GHC might use the manifest file for more things, - such as supplying the location of dependent DLLs.</para> - - <para><option>-fno-gen-manifest</option> also implies - <option>-fno-embed-manifest</option>, see below.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fno-embed-manifest</option> - <indexterm><primary><option>-fno-embed-manifest</option></primary> - </indexterm> - </term> - <listitem> - <para>The manifest file that GHC generates when linking a binary on - Windows is also embedded in the executable itself, by default. - This means that the binary can be distributed without having to - supply the manifest file too. The embedding is done by running - <literal>windres</literal><indexterm><primary><literal>windres</literal></primary> - </indexterm>; to see exactly what GHC does to embed the manifest, - use the <option>-v</option> flag. A GHC installation comes with - its own copy of <literal>windres</literal> for this reason.</para> - - <para>See also <option>-pgmwindres</option> (<xref - linkend="replacing-phases" />) and - <option>-optwindres</option> (<xref - linkend="forcing-options-through" - />).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fno-shared-implib</option> - <indexterm><primary><option>-fno-shared-implib</option></primary> - </indexterm> - </term> - <listitem> - <para>DLLs on Windows are typically linked to by linking to a corresponding - <literal>.lib</literal> or <literal>.dll.a</literal> - the so-called import library. - GHC will typically generate such a file for every DLL you create by compiling in - <literal>-shared</literal> mode. However, sometimes you don't want to pay the - disk-space cost of creating this import library, which can be substantial - it - might require as much space as the code itself, as Haskell DLLs tend to export - lots of symbols.</para> - - <para>As long as you are happy to only be able to link to the DLL using - <literal>GetProcAddress</literal> and friends, you can supply the - <option>-fno-shared-implib</option> flag to disable the creation of the import - library entirely.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dylib-install-name <replaceable>path</replaceable></option> - <indexterm><primary><option>-dylib-install-name</option></primary> - </indexterm> - </term> - <listitem> - <para>On Darwin/OS X, dynamic libraries are stamped at build time with an - "install name", which is the ultimate install path of the library file. - Any libraries or executables that subsequently link against it will pick - up that path as their runtime search location for it. By default, ghc sets - the install name to the location where the library is built. This option - allows you to override it with the specified file path. (It passes - <literal>-install_name</literal> to Apple's linker.) Ignored on other - platforms.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-rdynamic</option> - <indexterm><primary><option>-rdynamic</option></primary> - </indexterm> - </term> - <listitem> - <para> - This instructs the linker to add all symbols, not only used ones, to the - dynamic symbol table. Currently Linux and Windows/MinGW32 only. - This is equivalent to using <literal>-optl -rdynamic</literal> on Linux, - and <literal>-optl -export-all-symbols</literal> on Windows.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - -</sect1> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> diff --git a/docs/users_guide/prof_scc.eps b/docs/users_guide/prof_scc.eps Binary files differdeleted file mode 100644 index beac36f498..0000000000 --- a/docs/users_guide/prof_scc.eps +++ /dev/null diff --git a/docs/users_guide/profiling.rst b/docs/users_guide/profiling.rst new file mode 100644 index 0000000000..34525d12b8 --- /dev/null +++ b/docs/users_guide/profiling.rst @@ -0,0 +1,1390 @@ +.. _profiling: + +Profiling +========= + +.. index:: + single: profiling + single: cost-centre profiling + single: -p; RTS option + +GHC comes with a time and space profiling system, so that you can answer +questions like "why is my program so slow?", or "why is my program using +so much memory?". + +Profiling a program is a three-step process: + +1. Re-compile your program for profiling with the ``-prof`` option, and + probably one of the options for adding automatic annotations: + ``-fprof-auto`` is the most common [1]_. ``-fprof-auto`` + + If you are using external packages with ``cabal``, you may need to + reinstall these packages with profiling support; typically this is + done with ``cabal install -p package --reinstall``. + +2. Having compiled the program for profiling, you now need to run it to + generate the profile. For example, a simple time profile can be + generated by running the program with ``+RTS -p``, which generates a file + named ``⟨prog⟩.prof`` where ⟨prog⟩ is the name of your program (without the + ``.exe`` extension, if you are on Windows). + + There are many different kinds of profile that can be generated, + selected by different RTS options. We will be describing the various + kinds of profile throughout the rest of this chapter. Some profiles + require further processing using additional tools after running the + program. + +3. Examine the generated profiling information, use the information to + optimise your program, and repeat as necessary. + +.. _cost-centres: + +Cost centres and cost-centre stacks +----------------------------------- + +GHC's profiling system assigns costs to cost centres. A cost is simply +the time or space (memory) required to evaluate an expression. Cost +centres are program annotations around expressions; all costs incurred +by the annotated expression are assigned to the enclosing cost centre. +Furthermore, GHC will remember the stack of enclosing cost centres for +any given expression at run-time and generate a call-tree of cost +attributions. + +Let's take a look at an example: + +:: + + main = print (fib 30) + fib n = if n < 2 then 1 else fib (n-1) + fib (n-2) + +Compile and run this program as follows: + +:: + + $ ghc -prof -fprof-auto -rtsopts Main.hs + $ ./Main +RTS -p + 121393 + $ + +When a GHC-compiled program is run with the ``-p`` RTS option, it +generates a file called ``prog.prof``. In this case, the file will +contain something like this: + +:: + + Wed Oct 12 16:14 2011 Time and Allocation Profiling Report (Final) + + Main +RTS -p -RTS + + total time = 0.68 secs (34 ticks @ 20 ms) + total alloc = 204,677,844 bytes (excludes profiling overheads) + + COST CENTRE MODULE %time %alloc + + fib Main 100.0 100.0 + + + individual inherited + COST CENTRE MODULE no. entries %time %alloc %time %alloc + + MAIN MAIN 102 0 0.0 0.0 100.0 100.0 + CAF GHC.IO.Handle.FD 128 0 0.0 0.0 0.0 0.0 + CAF GHC.IO.Encoding.Iconv 120 0 0.0 0.0 0.0 0.0 + CAF GHC.Conc.Signal 110 0 0.0 0.0 0.0 0.0 + CAF Main 108 0 0.0 0.0 100.0 100.0 + main Main 204 1 0.0 0.0 100.0 100.0 + fib Main 205 2692537 100.0 100.0 100.0 100.0 + +The first part of the file gives the program name and options, and the +total time and total memory allocation measured during the run of the +program (note that the total memory allocation figure isn't the same as +the amount of *live* memory needed by the program at any one time; the +latter can be determined using heap profiling, which we will describe +later in :ref:`prof-heap`). + +The second part of the file is a break-down by cost centre of the most +costly functions in the program. In this case, there was only one +significant function in the program, namely ``fib``, and it was +responsible for 100% of both the time and allocation costs of the +program. + +The third and final section of the file gives a profile break-down by +cost-centre stack. This is roughly a call-tree profile of the program. +In the example above, it is clear that the costly call to ``fib`` came +from ``main``. + +The time and allocation incurred by a given part of the program is +displayed in two ways: “individual”, which are the costs incurred by the +code covered by this cost centre stack alone, and “inherited”, which +includes the costs incurred by all the children of this node. + +The usefulness of cost-centre stacks is better demonstrated by modifying +the example slightly: + +:: + + main = print (f 30 + g 30) + where + f n = fib n + g n = fib (n `div` 2) + + fib n = if n < 2 then 1 else fib (n-1) + fib (n-2) + +Compile and run this program as before, and take a look at the new +profiling results: + +:: + + COST CENTRE MODULE no. entries %time %alloc %time %alloc + + MAIN MAIN 102 0 0.0 0.0 100.0 100.0 + CAF GHC.IO.Handle.FD 128 0 0.0 0.0 0.0 0.0 + CAF GHC.IO.Encoding.Iconv 120 0 0.0 0.0 0.0 0.0 + CAF GHC.Conc.Signal 110 0 0.0 0.0 0.0 0.0 + CAF Main 108 0 0.0 0.0 100.0 100.0 + main Main 204 1 0.0 0.0 100.0 100.0 + main.g Main 207 1 0.0 0.0 0.0 0.1 + fib Main 208 1973 0.0 0.1 0.0 0.1 + main.f Main 205 1 0.0 0.0 100.0 99.9 + fib Main 206 2692537 100.0 99.9 100.0 99.9 + +Now although we had two calls to ``fib`` in the program, it is +immediately clear that it was the call from ``f`` which took all the +time. The functions ``f`` and ``g`` which are defined in the ``where`` +clause in ``main`` are given their own cost centres, ``main.f`` and +``main.g`` respectively. + +The actual meaning of the various columns in the output is: + + The number of times this particular point in the call tree was + entered. + + The percentage of the total run time of the program spent at this + point in the call tree. + + The percentage of the total memory allocations (excluding profiling + overheads) of the program made by this call. + + The percentage of the total run time of the program spent below this + point in the call tree. + + The percentage of the total memory allocations (excluding profiling + overheads) of the program made by this call and all of its + sub-calls. + +In addition you can use the ``-P`` RTS option ``-P`` to get the +following additional information: + +``ticks`` + The raw number of time “ticks” which were attributed to this + cost-centre; from this, we get the ``%time`` figure mentioned above. + +``bytes`` + Number of bytes allocated in the heap while in this cost-centre; + again, this is the raw number from which we get the ``%alloc`` + figure mentioned above. + +What about recursive functions, and mutually recursive groups of +functions? Where are the costs attributed? Well, although GHC does keep +information about which groups of functions called each other +recursively, this information isn't displayed in the basic time and +allocation profile, instead the call-graph is flattened into a tree as +follows: a call to a function that occurs elsewhere on the current stack +does not push another entry on the stack, instead the costs for this +call are aggregated into the caller [2]_. + +.. _scc-pragma: + +Inserting cost centres by hand +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Cost centres are just program annotations. When you say ``-fprof-auto`` +to the compiler, it automatically inserts a cost centre annotation +around every binding not marked INLINE in your program, but you are +entirely free to add cost centre annotations yourself. + +The syntax of a cost centre annotation is + +:: + + {-# SCC "name" #-} <expression> + +where ``"name"`` is an arbitrary string, that will become the name of +your cost centre as it appears in the profiling output, and +``<expression>`` is any Haskell expression. An ``SCC`` annotation +extends as far to the right as possible when parsing. (SCC stands for +"Set Cost Centre"). The double quotes can be omitted if ``name`` is a +Haskell identifier, for example: + +:: + + {-# SCC my_function #-} <expression> + +Here is an example of a program with a couple of SCCs: + +:: + + main :: IO () + main = do let xs = [1..1000000] + let ys = [1..2000000] + print $ {-# SCC last_xs #-} last xs + print $ {-# SCC last_init_xs #-} last $ init xs + print $ {-# SCC last_ys #-} last ys + print $ {-# SCC last_init_ys #-} last $ init ys + +which gives this profile when run: + +:: + + COST CENTRE MODULE no. entries %time %alloc %time %alloc + + MAIN MAIN 102 0 0.0 0.0 100.0 100.0 + CAF GHC.IO.Handle.FD 130 0 0.0 0.0 0.0 0.0 + CAF GHC.IO.Encoding.Iconv 122 0 0.0 0.0 0.0 0.0 + CAF GHC.Conc.Signal 111 0 0.0 0.0 0.0 0.0 + CAF Main 108 0 0.0 0.0 100.0 100.0 + main Main 204 1 0.0 0.0 100.0 100.0 + last_init_ys Main 210 1 25.0 27.4 25.0 27.4 + main.ys Main 209 1 25.0 39.2 25.0 39.2 + last_ys Main 208 1 12.5 0.0 12.5 0.0 + last_init_xs Main 207 1 12.5 13.7 12.5 13.7 + main.xs Main 206 1 18.8 19.6 18.8 19.6 + last_xs Main 205 1 6.2 0.0 6.2 0.0 + +.. _prof-rules: + +Rules for attributing costs +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +While running a program with profiling turned on, GHC maintains a +cost-centre stack behind the scenes, and attributes any costs (memory +allocation and time) to whatever the current cost-centre stack is at the +time the cost is incurred. + +The mechanism is simple: whenever the program evaluates an expression +with an SCC annotation, ``{-# SCC c -#} E``, the cost centre ``c`` is +pushed on the current stack, and the entry count for this stack is +incremented by one. The stack also sometimes has to be saved and +restored; in particular when the program creates a thunk (a lazy +suspension), the current cost-centre stack is stored in the thunk, and +restored when the thunk is evaluated. In this way, the cost-centre stack +is independent of the actual evaluation order used by GHC at runtime. + +At a function call, GHC takes the stack stored in the function being +called (which for a top-level function will be empty), and *appends* it +to the current stack, ignoring any prefix that is identical to a prefix +of the current stack. + +We mentioned earlier that lazy computations, i.e. thunks, capture the +current stack when they are created, and restore this stack when they +are evaluated. What about top-level thunks? They are "created" when the +program is compiled, so what stack should we give them? The technical +name for a top-level thunk is a CAF ("Constant Applicative Form"). GHC +assigns every CAF in a module a stack consisting of the single cost +centre ``M.CAF``, where ``M`` is the name of the module. It is also +possible to give each CAF a different stack, using the option +``-fprof-cafs``. This is especially useful when +compiling with ``-ffull-laziness`` (as is default with ``-O`` and +higher), as constants in function bodies will be lifted to the top-level +and become CAFs. You will probably need to consult the Core +(``-ddump-simpl``) in order to determine what these CAFs correspond to. + +.. index:: + single: -fprof-cafs + +.. _prof-compiler-options: + +Compiler options for profiling +------------------------------ + +.. index:: + single: profiling; options + single: options; for profiling + +``-prof`` + .. index:: + single: -prof + + To make use of the profiling system *all* modules must be compiled + and linked with the ``-prof`` option. Any ``SCC`` annotations you've + put in your source will spring to life. + + Without a ``-prof`` option, your ``SCC``\ s are ignored; so you can + compile ``SCC``-laden code without changing it. + +There are a few other profiling-related compilation options. Use them +*in addition to* ``-prof``. These do not have to be used consistently +for all modules in a program. + +``-fprof-auto`` + .. index:: + single: -fprof-auto + + *All* bindings not marked INLINE, whether exported or not, top level + or nested, will be given automatic ``SCC`` annotations. Functions + marked INLINE must be given a cost centre manually. + +``-fprof-auto-top`` + .. index:: + single: -fprof-auto-top + single: cost centres; automatically inserting + + GHC will automatically add ``SCC`` annotations for all top-level + bindings not marked INLINE. If you want a cost centre on an INLINE + function, you have to add it manually. + +``-fprof-auto-exported`` + .. index:: + single: -fprof-auto-top + + .. index:: + single: cost centres; automatically inserting + + GHC will automatically add ``SCC`` annotations for all exported + functions not marked INLINE. If you want a cost centre on an INLINE + function, you have to add it manually. + +``-fprof-auto-calls`` + .. index:: + single: -fprof-auto-calls + + Adds an automatic ``SCC`` annotation to all *call sites*. This is + particularly useful when using profiling for the purposes of + generating stack traces; see the function ``traceStack`` in the + module ``Debug.Trace``, or the ``-xc`` RTS flag + (:ref:`rts-options-debugging`) for more details. + +``-fprof-cafs`` + .. index:: + single: -fprof-cafs + + The costs of all CAFs in a module are usually attributed to one + “big” CAF cost-centre. With this option, all CAFs get their own + cost-centre. An “if all else fails” option… + +``-fno-prof-auto`` + .. index:: + single: -no-fprof-auto + + Disables any previous ``-fprof-auto``, ``-fprof-auto-top``, or + ``-fprof-auto-exported`` options. + +``-fno-prof-cafs`` + .. index:: + single: -fno-prof-cafs + + Disables any previous ``-fprof-cafs`` option. + +``-fno-prof-count-entries`` + .. index:: + single: -fno-prof-count-entries + + Tells GHC not to collect information about how often functions are + entered at runtime (the "entries" column of the time profile), for + this module. This tends to make the profiled code run faster, and + hence closer to the speed of the unprofiled code, because GHC is + able to optimise more aggressively if it doesn't have to maintain + correct entry counts. This option can be useful if you aren't + interested in the entry counts (for example, if you only intend to + do heap profiling). + +.. _prof-time-options: + +Time and allocation profiling +----------------------------- + +To generate a time and allocation profile, give one of the following RTS +options to the compiled program when you run it (RTS options should be +enclosed between ``+RTS ... -RTS`` as usual): + +``-p``, ``-P``, ``-pa`` + .. index:: + single: -p; RTS option + single: -P; RTS option + single: -pa; RTS option + single: time profile + + The ``-p`` option produces a standard *time profile* report. It is + written into the file ``program.prof``. + + The ``-P`` option produces a more detailed report containing the + actual time and allocation data as well. (Not used much.) + + The ``-pa`` option produces the most detailed report containing all + cost centres in addition to the actual time and allocation data. + +``-Vsecs`` + .. index:: + single: -V; RTS option + + Sets the interval that the RTS clock ticks at, which is also the + sampling interval of the time and allocation profile. The default is + 0.02 seconds. + +``-xc`` + .. index:: + single: -xc; RTS option + + This option causes the runtime to print out the current cost-centre + stack whenever an exception is raised. This can be particularly + useful for debugging the location of exceptions, such as the + notorious ``Prelude.head: empty list`` error. See + :ref:`rts-options-debugging`. + +.. _prof-heap: + +Profiling memory usage +---------------------- + +In addition to profiling the time and allocation behaviour of your +program, you can also generate a graph of its memory usage over time. +This is useful for detecting the causes of space leaks, when your +program holds on to more memory at run-time that it needs to. Space +leaks lead to slower execution due to heavy garbage collector activity, +and may even cause the program to run out of memory altogether. + +To generate a heap profile from your program: + +1. Compile the program for profiling (:ref:`prof-compiler-options`). + +2. Run it with one of the heap profiling options described below (eg. + ``-h`` for a basic producer profile). This generates the file + ``prog.hp``. + +3. Run ``hp2ps`` to produce a Postscript file, ``prog.ps``. The + ``hp2ps`` utility is described in detail in :ref:`hp2ps`. + +4. Display the heap profile using a postscript viewer such as Ghostview, + or print it out on a Postscript-capable printer. + +For example, here is a heap profile produced for the ``sphere`` program +from GHC's ``nofib`` benchmark suite, + +.. image:: images/prof_scc.* + +You might also want to take a look at +`hp2any <http://www.haskell.org/haskellwiki/Hp2any>`__, a more advanced +suite of tools (not distributed with GHC) for displaying heap profiles. + +.. _rts-options-heap-prof: + +RTS options for heap profiling +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are several different kinds of heap profile that can be generated. +All the different profile types yield a graph of live heap against time, +but they differ in how the live heap is broken down into bands. The +following RTS options select which break-down to use: + +``-hc`` + .. index:: + single: -hc; RTS option + + (can be shortened to ``-h``). Breaks down the graph by the + cost-centre stack which produced the data. + +``-hm`` + .. index:: + single: -hm; RTS option + + Break down the live heap by the module containing the code which + produced the data. + +``-hd`` + .. index:: + single: -hd; RTS option + + Breaks down the graph by closure description. For actual data, the + description is just the constructor name, for other closures it is a + compiler-generated string identifying the closure. + +``-hy`` + .. index:: + single: -hy; RTS option + + Breaks down the graph by type. For closures which have function type + or unknown/polymorphic type, the string will represent an + approximation to the actual type. + +``-hr`` + .. index:: + single: -hr; RTS option + + Break down the graph by retainer set. Retainer profiling is + described in more detail below (:ref:`retainer-prof`). + +``-hb`` + .. index:: + single: -hb; RTS option + + Break down the graph by biography. Biographical profiling is + described in more detail below (:ref:`biography-prof`). + +In addition, the profile can be restricted to heap data which satisfies +certain criteria - for example, you might want to display a profile by +type but only for data produced by a certain module, or a profile by +retainer for a certain type of data. Restrictions are specified as +follows: + +``-hc ⟨name⟩`` + .. index:: + single: -hc; RTS option + + Restrict the profile to closures produced by cost-centre stacks with + one of the specified cost centres at the top. + +``-hC ⟨name⟩`` + .. index:: + single: -hC; RTS option + + Restrict the profile to closures produced by cost-centre stacks with + one of the specified cost centres anywhere in the stack. + +``-hm ⟨module⟩`` + .. index:: + single: -hm; RTS option + + Restrict the profile to closures produced by the specified modules. + +``-hd ⟨desc⟩`` + .. index:: + single: -hd; RTS option + + Restrict the profile to closures with the specified description + strings. + +``-hy ⟨type⟩`` + .. index:: + single: -hy; RTS option + + Restrict the profile to closures with the specified types. + +``-hr ⟨cc⟩`` + .. index:: + single: -hr; RTS option + + Restrict the profile to closures with retainer sets containing + cost-centre stacks with one of the specified cost centres at the + top. + +``-hb ⟨bio⟩`` + .. index:: + single: -hb; RTS option + + Restrict the profile to closures with one of the specified + biographies, where ⟨bio⟩ is one of ``lag``, ``drag``, ``void``, or + ``use``. + +For example, the following options will generate a retainer profile +restricted to ``Branch`` and ``Leaf`` constructors: + +:: + + prog +RTS -hr -hdBranch,Leaf + +There can only be one "break-down" option (eg. ``-hr`` in the example +above), but there is no limit on the number of further restrictions that +may be applied. All the options may be combined, with one exception: GHC +doesn't currently support mixing the ``-hr`` and ``-hb`` options. + +There are three more options which relate to heap profiling: + +``-isecs`` + .. index:: + single: -i + + Set the profiling (sampling) interval to ⟨secs⟩ seconds (the default + is 0.1 second). Fractions are allowed: for example ``-i0.2`` will + get 5 samples per second. This only affects heap profiling; time + profiles are always sampled with the frequency of the RTS clock. See + :ref:`prof-time-options` for changing that. + +``-xt`` + .. index:: + single: -xt; RTS option + + Include the memory occupied by threads in a heap profile. Each + thread takes up a small area for its thread state in addition to the + space allocated for its stack (stacks normally start small and then + grow as necessary). + + This includes the main thread, so using ``-xt`` is a good way to see + how much stack space the program is using. + + Memory occupied by threads and their stacks is labelled as “TSO” and + “STACK” respectively when displaying the profile by closure + description or type description. + +``-Lnum`` + .. index:: + single: -L; RTS option + + Sets the maximum length of a cost-centre stack name in a heap + profile. Defaults to 25. + +.. _retainer-prof: + +Retainer Profiling +~~~~~~~~~~~~~~~~~~ + +Retainer profiling is designed to help answer questions like “why is +this data being retained?”. We start by defining what we mean by a +retainer: + + A retainer is either the system stack, an unevaluated closure + (thunk), or an explicitly mutable object. + +In particular, constructors are *not* retainers. + +An object B retains object A if (i) B is a retainer object and (ii) +object A can be reached by recursively following pointers starting from +object B, but not meeting any other retainer objects on the way. Each +live object is retained by one or more retainer objects, collectively +called its retainer set, or its retainer set, or its retainers. + +When retainer profiling is requested by giving the program the ``-hr`` +option, a graph is generated which is broken down by retainer set. A +retainer set is displayed as a set of cost-centre stacks; because this +is usually too large to fit on the profile graph, each retainer set is +numbered and shown abbreviated on the graph along with its number, and +the full list of retainer sets is dumped into the file ``prog.prof``. + +Retainer profiling requires multiple passes over the live heap in order +to discover the full retainer set for each object, which can be quite +slow. So we set a limit on the maximum size of a retainer set, where all +retainer sets larger than the maximum retainer set size are replaced by +the special set ``MANY``. The maximum set size defaults to 8 and can be +altered with the ``-R`` RTS option: + +``-R ⟨size⟩`` + Restrict the number of elements in a retainer set to ⟨size⟩ (default + 8). + +Hints for using retainer profiling +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The definition of retainers is designed to reflect a common cause of +space leaks: a large structure is retained by an unevaluated +computation, and will be released once the computation is forced. A good +example is looking up a value in a finite map, where unless the lookup +is forced in a timely manner the unevaluated lookup will cause the whole +mapping to be retained. These kind of space leaks can often be +eliminated by forcing the relevant computations to be performed eagerly, +using ``seq`` or strictness annotations on data constructor fields. + +Often a particular data structure is being retained by a chain of +unevaluated closures, only the nearest of which will be reported by +retainer profiling - for example A retains B, B retains C, and C retains +a large structure. There might be a large number of Bs but only a single +A, so A is really the one we're interested in eliminating. However, +retainer profiling will in this case report B as the retainer of the +large structure. To move further up the chain of retainers, we can ask +for another retainer profile but this time restrict the profile to B +objects, so we get a profile of the retainers of B: + +:: + + prog +RTS -hr -hcB + +This trick isn't foolproof, because there might be other B closures in +the heap which aren't the retainers we are interested in, but we've +found this to be a useful technique in most cases. + +.. _biography-prof: + +Biographical Profiling +~~~~~~~~~~~~~~~~~~~~~~ + +A typical heap object may be in one of the following four states at each +point in its lifetime: + +- The lag stage, which is the time between creation and the first use + of the object, + +- the use stage, which lasts from the first use until the last use of + the object, and + +- The drag stage, which lasts from the final use until the last + reference to the object is dropped. + +- An object which is never used is said to be in the void state for its + whole lifetime. + +A biographical heap profile displays the portion of the live heap in +each of the four states listed above. Usually the most interesting +states are the void and drag states: live heap in these states is more +likely to be wasted space than heap in the lag or use states. + +It is also possible to break down the heap in one or more of these +states by a different criteria, by restricting a profile by biography. +For example, to show the portion of the heap in the drag or void state +by producer: + +:: + + prog +RTS -hc -hbdrag,void + +Once you know the producer or the type of the heap in the drag or void +states, the next step is usually to find the retainer(s): + +:: + + prog +RTS -hr -hccc... + +.. note:: + This two stage process is required because GHC cannot currently + profile using both biographical and retainer information simultaneously. + +.. _mem-residency: + +Actual memory residency +~~~~~~~~~~~~~~~~~~~~~~~ + +How does the heap residency reported by the heap profiler relate to the +actual memory residency of your program when you run it? You might see a +large discrepancy between the residency reported by the heap profiler, +and the residency reported by tools on your system (eg. ``ps`` or +``top`` on Unix, or the Task Manager on Windows). There are several +reasons for this: + +- There is an overhead of profiling itself, which is subtracted from + the residency figures by the profiler. This overhead goes away when + compiling without profiling support, of course. The space overhead is + currently 2 extra words per heap object, which probably results in + about a 30% overhead. + +- Garbage collection requires more memory than the actual residency. + The factor depends on the kind of garbage collection algorithm in + use: a major GC in the standard generation copying collector will + usually require 3L bytes of memory, where L is the amount of live + data. This is because by default (see the ``+RTS -F`` option) we + allow the old generation to grow to twice its size (2L) before + collecting it, and we require additionally L bytes to copy the live + data into. When using compacting collection (see the ``+RTS -c`` + option), this is reduced to 2L, and can further be reduced by + tweaking the ``-F`` option. Also add the size of the allocation area + (currently a fixed 512Kb). + +- The stack isn't counted in the heap profile by default. See the + ``+RTS -xt`` option. + +- The program text itself, the C stack, any non-heap data (e.g. data + allocated by foreign libraries, and data allocated by the RTS), and + ``mmap()``\'d memory are not counted in the heap profile. + +.. _hp2ps: + +``hp2ps`` -- Rendering heap profiles to PostScript +-------------------------------------------------- + +.. index:: + single: hp2ps + single: heap profiles + single: postscript, from heap profiles + single: -h⟨break-down⟩ + +Usage: + +:: + + hp2ps [flags] [<file>[.hp]] + +The program ``hp2ps`` program converts a heap profile as produced +by the ``-h<break-down>`` runtime option into a PostScript graph of the +heap profile. By convention, the file to be processed by ``hp2ps`` has a +``.hp`` extension. The PostScript output is written to ``<file>@.ps``. +If ``<file>`` is omitted entirely, then the program behaves as a filter. + +``hp2ps`` is distributed in ``ghc/utils/hp2ps`` in a GHC source +distribution. It was originally developed by Dave Wakeling as part of +the HBC/LML heap profiler. + +The flags are: + +``-d`` + In order to make graphs more readable, ``hp2ps`` sorts the shaded + bands for each identifier. The default sort ordering is for the + bands with the largest area to be stacked on top of the smaller + ones. The ``-d`` option causes rougher bands (those representing + series of values with the largest standard deviations) to be stacked + on top of smoother ones. + +``-b`` + Normally, ``hp2ps`` puts the title of the graph in a small box at + the top of the page. However, if the JOB string is too long to fit + in a small box (more than 35 characters), then ``hp2ps`` will choose + to use a big box instead. The ``-b`` option forces ``hp2ps`` to use + a big box. + +``-e<float>[in|mm|pt]`` + Generate encapsulated PostScript suitable for inclusion in LaTeX + documents. Usually, the PostScript graph is drawn in landscape mode + in an area 9 inches wide by 6 inches high, and ``hp2ps`` arranges + for this area to be approximately centred on a sheet of a4 paper. + This format is convenient of studying the graph in detail, but it is + unsuitable for inclusion in LaTeX documents. The ``-e`` option + causes the graph to be drawn in portrait mode, with float specifying + the width in inches, millimetres or points (the default). The + resulting PostScript file conforms to the Encapsulated PostScript + (EPS) convention, and it can be included in a LaTeX document using + Rokicki's dvi-to-PostScript converter ``dvips``. + +``-g`` + Create output suitable for the ``gs`` PostScript previewer (or + similar). In this case the graph is printed in portrait mode without + scaling. The output is unsuitable for a laser printer. + +``-l`` + Normally a profile is limited to 20 bands with additional + identifiers being grouped into an ``OTHER`` band. The ``-l`` flag + removes this 20 band and limit, producing as many bands as + necessary. No key is produced as it won't fit!. It is useful for + creation time profiles with many bands. + +``-m<int>`` + Normally a profile is limited to 20 bands with additional + identifiers being grouped into an ``OTHER`` band. The ``-m`` flag + specifies an alternative band limit (the maximum is 20). + + ``-m0`` requests the band limit to be removed. As many bands as + necessary are produced. However no key is produced as it won't fit! + It is useful for displaying creation time profiles with many bands. + +``-p`` + Use previous parameters. By default, the PostScript graph is + automatically scaled both horizontally and vertically so that it + fills the page. However, when preparing a series of graphs for use + in a presentation, it is often useful to draw a new graph using the + same scale, shading and ordering as a previous one. The ``-p`` flag + causes the graph to be drawn using the parameters determined by a + previous run of ``hp2ps`` on ``file``. These are extracted from + ``file@.aux``. + +``-s`` + Use a small box for the title. + +``-t<float>`` + Normally trace elements which sum to a total of less than 1% of the + profile are removed from the profile. The ``-t`` option allows this + percentage to be modified (maximum 5%). + + ``-t0`` requests no trace elements to be removed from the profile, + ensuring that all the data will be displayed. + +``-c`` + Generate colour output. + +``-y`` + Ignore marks. + +``-?`` + Print out usage information. + +.. _manipulating-hp: + +Manipulating the hp file +~~~~~~~~~~~~~~~~~~~~~~~~ + +(Notes kindly offered by Jan-Willem Maessen.) + +The ``FOO.hp`` file produced when you ask for the heap profile of a +program ``FOO`` is a text file with a particularly simple structure. +Here's a representative example, with much of the actual data omitted: + +:: + + JOB "FOO -hC" + DATE "Thu Dec 26 18:17 2002" + SAMPLE_UNIT "seconds" + VALUE_UNIT "bytes" + BEGIN_SAMPLE 0.00 + END_SAMPLE 0.00 + BEGIN_SAMPLE 15.07 + ... sample data ... + END_SAMPLE 15.07 + BEGIN_SAMPLE 30.23 + ... sample data ... + END_SAMPLE 30.23 + ... etc. + BEGIN_SAMPLE 11695.47 + END_SAMPLE 11695.47 + +The first four lines (``JOB``, ``DATE``, ``SAMPLE_UNIT``, +``VALUE_UNIT``) form a header. Each block of lines starting with +``BEGIN_SAMPLE`` and ending with ``END_SAMPLE`` forms a single sample +(you can think of this as a vertical slice of your heap profile). The +hp2ps utility should accept any input with a properly-formatted header +followed by a series of *complete* samples. + +Zooming in on regions of your profile +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can look at particular regions of your profile simply by loading a +copy of the ``.hp`` file into a text editor and deleting the unwanted +samples. The resulting ``.hp`` file can be run through ``hp2ps`` and +viewed or printed. + +Viewing the heap profile of a running program +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``.hp`` file is generated incrementally as your program runs. In +principle, running ``hp2ps`` on the incomplete file should produce a +snapshot of your program's heap usage. However, the last sample in the +file may be incomplete, causing ``hp2ps`` to fail. If you are using a +machine with UNIX utilities installed, it's not too hard to work around +this problem (though the resulting command line looks rather Byzantine): + +:: + + head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \ + | hp2ps > FOO.ps + +The command ``fgrep -n END_SAMPLE FOO.hp`` finds the end of every +complete sample in ``FOO.hp``, and labels each sample with its ending +line number. We then select the line number of the last complete sample +using ``tail`` and ``cut``. This is used as a parameter to ``head``; the +result is as if we deleted the final incomplete sample from ``FOO.hp``. +This results in a properly-formatted .hp file which we feed directly to +``hp2ps``. + +Viewing a heap profile in real time +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``gv`` and ``ghostview`` programs have a "watch file" option can be +used to view an up-to-date heap profile of your program as it runs. +Simply generate an incremental heap profile as described in the previous +section. Run ``gv`` on your profile: + +:: + + gv -watch -orientation=seascape FOO.ps + +If you forget the ``-watch`` flag you can still select "Watch file" from +the "State" menu. Now each time you generate a new profile ``FOO.ps`` +the view will update automatically. + +This can all be encapsulated in a little script: + +:: + + #!/bin/sh + head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \ + | hp2ps > FOO.ps + gv -watch -orientation=seascape FOO.ps & + while [ 1 ] ; do + sleep 10 # We generate a new profile every 10 seconds. + head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \ + | hp2ps > FOO.ps + done + +Occasionally ``gv`` will choke as it tries to read an incomplete copy of +``FOO.ps`` (because ``hp2ps`` is still running as an update occurs). A +slightly more complicated script works around this problem, by using the +fact that sending a SIGHUP to gv will cause it to re-read its input +file: + +:: + + #!/bin/sh + head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \ + | hp2ps > FOO.ps + gv FOO.ps & + gvpsnum=$! + while [ 1 ] ; do + sleep 10 + head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \ + | hp2ps > FOO.ps + kill -HUP $gvpsnum + done + +.. _prof-threaded: + +Profiling Parallel and Concurrent Programs +------------------------------------------ + +Combining ``-threaded`` and ``-prof`` is perfectly fine, and indeed it +is possible to profile a program running on multiple processors with the +``+RTS -N`` option. [3]_ + +Some caveats apply, however. In the current implementation, a profiled +program is likely to scale much less well than the unprofiled program, +because the profiling implementation uses some shared data structures +which require locking in the runtime system. Furthermore, the memory +allocation statistics collected by the profiled program are stored in +shared memory but *not* locked (for speed), which means that these +figures might be inaccurate for parallel programs. + +We strongly recommend that you use ``-fno-prof-count-entries`` when +compiling a program to be profiled on multiple cores, because the entry +counts are also stored in shared memory, and continuously updating them +on multiple cores is extremely slow. + +We also recommend using +`ThreadScope <http://www.haskell.org/haskellwiki/ThreadScope>`__ for +profiling parallel programs; it offers a GUI for visualising parallel +execution, and is complementary to the time and space profiling features +provided with GHC. + +.. _hpc: + +Observing Code Coverage +----------------------- + +.. index:: + single: code coverage + single: Haskell Program Coverage + single: hpc + +Code coverage tools allow a programmer to determine what parts of their +code have been actually executed, and which parts have never actually +been invoked. GHC has an option for generating instrumented code that +records code coverage as part of the Haskell Program Coverage (HPC) +toolkit, which is included with GHC. HPC tools can be used to render the +generated code coverage information into human understandable format. + +Correctly instrumented code provides coverage information of two kinds: +source coverage and boolean-control coverage. Source coverage is the +extent to which every part of the program was used, measured at three +different levels: declarations (both top-level and local), alternatives +(among several equations or case branches) and expressions (at every +level). Boolean coverage is the extent to which each of the values True +and False is obtained in every syntactic boolean context (ie. guard, +condition, qualifier). + +HPC displays both kinds of information in two primary ways: textual +reports with summary statistics (``hpc report``) and sources with color +mark-up (``hpc markup``). For boolean coverage, there are four possible +outcomes for each guard, condition or qualifier: both True and False +values occur; only True; only False; never evaluated. In hpc-markup +output, highlighting with a yellow background indicates a part of the +program that was never evaluated; a green background indicates an +always-True expression and a red background indicates an always-False +one. + +A small example: Reciprocation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For an example we have a program, called ``Recip.hs``, which computes +exact decimal representations of reciprocals, with recurring parts +indicated in brackets. + +:: + + reciprocal :: Int -> (String, Int) + reciprocal n | n > 1 = ('0' : '.' : digits, recur) + | otherwise = error + "attempting to compute reciprocal of number <= 1" + where + (digits, recur) = divide n 1 [] + divide :: Int -> Int -> [Int] -> (String, Int) + divide n c cs | c `elem` cs = ([], position c cs) + | r == 0 = (show q, 0) + | r /= 0 = (show q ++ digits, recur) + where + (q, r) = (c*10) `quotRem` n + (digits, recur) = divide n r (c:cs) + + position :: Int -> [Int] -> Int + position n (x:xs) | n==x = 1 + | otherwise = 1 + position n xs + + showRecip :: Int -> String + showRecip n = + "1/" ++ show n ++ " = " ++ + if r==0 then d else take p d ++ "(" ++ drop p d ++ ")" + where + p = length d - r + (d, r) = reciprocal n + + main = do + number <- readLn + putStrLn (showRecip number) + main + +HPC instrumentation is enabled with the -fhpc flag: + +:: + + $ ghc -fhpc Recip.hs + +GHC creates a subdirectory ``.hpc`` in the current directory, and puts +HPC index (``.mix``) files in there, one for each module compiled. You +don't need to worry about these files: they contain information needed +by the ``hpc`` tool to generate the coverage data for compiled modules +after the program is run. + +:: + + $ ./Recip + 1/3 + = 0.(3) + +Running the program generates a file with the ``.tix`` suffix, in this +case ``Recip.tix``, which contains the coverage data for this run of the +program. The program may be run multiple times (e.g. with different test +data), and the coverage data from the separate runs is accumulated in +the ``.tix`` file. To reset the coverage data and start again, just +remove the ``.tix`` file. + +Having run the program, we can generate a textual summary of coverage: + +:: + + $ hpc report Recip + 80% expressions used (81/101) + 12% boolean coverage (1/8) + 14% guards (1/7), 3 always True, + 1 always False, + 2 unevaluated + 0% 'if' conditions (0/1), 1 always False + 100% qualifiers (0/0) + 55% alternatives used (5/9) + 100% local declarations used (9/9) + 100% top-level declarations used (5/5) + +We can also generate a marked-up version of the source. + +:: + + $ hpc markup Recip + writing Recip.hs.html + +This generates one file per Haskell module, and 4 index files, +``hpc_index.html``, ``hpc_index_alt.html``, ``hpc_index_exp.html``, +``hpc_index_fun.html``. + +Options for instrumenting code for coverage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``-fhpc`` + Enable code coverage for the current module or modules being + compiled. + + Modules compiled with this option can be freely mixed with modules + compiled without it; indeed, most libraries will typically be + compiled without ``-fhpc``. When the program is run, coverage data + will only be generated for those modules that were compiled with + ``-fhpc``, and the ``hpc`` tool will only show information about + those modules. + +The hpc toolkit +~~~~~~~~~~~~~~~ + +The hpc command has several sub-commands: + +:: + + $ hpc + Usage: hpc COMMAND ... + + Commands: + help Display help for hpc or a single command + Reporting Coverage: + report Output textual report about program coverage + markup Markup Haskell source with program coverage + Processing Coverage files: + sum Sum multiple .tix files in a single .tix file + combine Combine two .tix files in a single .tix file + map Map a function over a single .tix file + Coverage Overlays: + overlay Generate a .tix file from an overlay file + draft Generate draft overlay that provides 100% coverage + Others: + show Show .tix file in readable, verbose format + version Display version for hpc + +In general, these options act on a ``.tix`` file after an instrumented +binary has generated it. + +The hpc tool assumes you are in the top-level directory of the location +where you built your application, and the ``.tix`` file is in the same +top-level directory. You can use the flag ``--srcdir`` to use ``hpc`` +for any other directory, and use ``--srcdir`` multiple times to analyse +programs compiled from difference locations, as is typical for packages. + +We now explain in more details the major modes of hpc. + +hpc report +^^^^^^^^^^ + +``hpc report`` gives a textual report of coverage. By default, all +modules and packages are considered in generating report, unless include +or exclude are used. The report is a summary unless the ``--per-module`` +flag is used. The ``--xml-output`` option allows for tools to use hpc to +glean coverage. + +:: + + $ hpc help report + Usage: hpc report [OPTION] .. <TIX_FILE> [<MODULE> [<MODULE> ..]] + + Options: + + --per-module show module level detail + --decl-list show unused decls + --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE + --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE + --srcdir=DIR path to source directory of .hs files + multi-use of srcdir possible + --hpcdir=DIR append sub-directory that contains .mix files + default .hpc [rarely used] + --reset-hpcdirs empty the list of hpcdir's + [rarely used] + --xml-output show output in XML + +hpc markup +^^^^^^^^^^ + +``hpc markup`` marks up source files into colored html. + +:: + + $ hpc help markup + Usage: hpc markup [OPTION] .. <TIX_FILE> [<MODULE> [<MODULE> ..]] + + Options: + + --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE + --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE + --srcdir=DIR path to source directory of .hs files + multi-use of srcdir possible + --hpcdir=DIR append sub-directory that contains .mix files + default .hpc [rarely used] + --reset-hpcdirs empty the list of hpcdir's + [rarely used] + --fun-entry-count show top-level function entry counts + --highlight-covered highlight covered code, rather that code gaps + --destdir=DIR path to write output to + +hpc sum +^^^^^^^ + +``hpc sum`` adds together any number of ``.tix`` files into a single +``.tix`` file. ``hpc sum`` does not change the original ``.tix`` file; +it generates a new ``.tix`` file. + +:: + + $ hpc help sum + Usage: hpc sum [OPTION] .. <TIX_FILE> [<TIX_FILE> [<TIX_FILE> ..]] + Sum multiple .tix files in a single .tix file + + Options: + + --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE + --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE + --output=FILE output FILE + --union use the union of the module namespace (default is intersection) + +hpc combine +^^^^^^^^^^^ + +``hpc combine`` is the swiss army knife of ``hpc``. It can be used to +take the difference between ``.tix`` files, to subtract one ``.tix`` +file from another, or to add two ``.tix`` files. hpc combine does not +change the original ``.tix`` file; it generates a new ``.tix`` file. + +:: + + $ hpc help combine + Usage: hpc combine [OPTION] .. <TIX_FILE> <TIX_FILE> + Combine two .tix files in a single .tix file + + Options: + + --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE + --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE + --output=FILE output FILE + --function=FUNCTION combine .tix files with join function, default = ADD + FUNCTION = ADD | DIFF | SUB + --union use the union of the module namespace (default is intersection) + +hpc map +^^^^^^^ + +hpc map inverts or zeros a ``.tix`` file. hpc map does not change the +original ``.tix`` file; it generates a new ``.tix`` file. + +:: + + $ hpc help map + Usage: hpc map [OPTION] .. <TIX_FILE> + Map a function over a single .tix file + + Options: + + --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE + --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE + --output=FILE output FILE + --function=FUNCTION apply function to .tix files, default = ID + FUNCTION = ID | INV | ZERO + --union use the union of the module namespace (default is intersection) + +hpc overlay and hpc draft +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Overlays are an experimental feature of HPC, a textual description of +coverage. hpc draft is used to generate a draft overlay from a .tix +file, and hpc overlay generates a .tix files from an overlay. + +:: + + % hpc help overlay + Usage: hpc overlay [OPTION] .. <OVERLAY_FILE> [<OVERLAY_FILE> [...]] + + Options: + + --srcdir=DIR path to source directory of .hs files + multi-use of srcdir possible + --hpcdir=DIR append sub-directory that contains .mix files + default .hpc [rarely used] + --reset-hpcdirs empty the list of hpcdir's + [rarely used] + --output=FILE output FILE + % hpc help draft + Usage: hpc draft [OPTION] .. <TIX_FILE> + + Options: + + --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE + --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE + --srcdir=DIR path to source directory of .hs files + multi-use of srcdir possible + --hpcdir=DIR append sub-directory that contains .mix files + default .hpc [rarely used] + --reset-hpcdirs empty the list of hpcdir's + [rarely used] + --output=FILE output FILE + +Caveats and Shortcomings of Haskell Program Coverage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +HPC does not attempt to lock the ``.tix`` file, so multiple concurrently +running binaries in the same directory will exhibit a race condition. +There is no way to change the name of the ``.tix`` file generated, apart +from renaming the binary. HPC does not work with GHCi. + +.. _ticky-ticky: + +Using “ticky-ticky” profiling (for implementors) +------------------------------------------------ + +.. index:: + single: ticky-ticky profiling + +Because ticky-ticky profiling requires a certain familiarity with GHC +internals, we have moved the documentation to the GHC developers wiki. +Take a look at its +:ghc-wiki:`overview of the profiling options <Commentary/Profiling>`, +which includeds a link to the ticky-ticky profiling page. + +.. [1] + ``-fprof-auto`` was known as ``-auto-all``\ ``-auto-all`` prior to + GHC 7.4.1. + +.. [2] + Note that this policy has changed slightly in GHC 7.4.1 relative to + earlier versions, and may yet change further, feedback is welcome. + +.. [3] + This feature was added in GHC 7.4.1. diff --git a/docs/users_guide/profiling.xml b/docs/users_guide/profiling.xml deleted file mode 100644 index 8ecda28634..0000000000 --- a/docs/users_guide/profiling.xml +++ /dev/null @@ -1,1787 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<chapter id="profiling"> - <title>Profiling</title> - <indexterm><primary>profiling</primary> - </indexterm> - <indexterm><primary>cost-centre profiling</primary></indexterm> - - <para>GHC comes with a time and space profiling system, so that you - can answer questions like "why is my program so slow?", or "why is - my program using so much memory?".</para> - - <para>Profiling a program is a three-step process:</para> - - <orderedlist> - <listitem> - <para>Re-compile your program for profiling with the - <literal>-prof</literal> option, and probably one of the options - for adding automatic annotations: - <literal>-fprof-auto</literal> is the most common<footnote><para><option>-fprof-auto</option> was known as <option>-auto-all</option><indexterm><primary><literal>-auto-all</literal></primary> - </indexterm> prior to GHC 7.4.1.</para></footnote>. - <indexterm><primary><literal>-fprof-auto</literal></primary> - </indexterm></para> - - <para>If you are using external packages with - <literal>cabal</literal>, you may need to reinstall these - packages with profiling support; typically this is done with - <literal>cabal install -p <replaceable>package</replaceable> - --reinstall</literal>.</para> - </listitem> - - <listitem> - <para>Having compiled the program for profiling, you now need to - run it to generate the profile. For example, a simple time - profile can be generated by running the program with - <option>+RTS - -p</option><indexterm><primary><option>-p</option></primary><secondary>RTS - option</secondary></indexterm>, which generates a file named - <literal><replaceable>prog</replaceable>.prof</literal> where - <replaceable>prog</replaceable> is the name of your program - (without the <literal>.exe</literal> extension, if you are on - Windows).</para> - - <para>There are many different kinds of profile that can be - generated, selected by different RTS options. We will be - describing the various kinds of profile throughout the rest of - this chapter. Some profiles require further processing using - additional tools after running the program.</para> - </listitem> - - <listitem> - <para>Examine the generated profiling information, use the - information to optimise your program, and repeat as - necessary.</para> - </listitem> - - </orderedlist> - - <sect1 id="cost-centres"> - <title>Cost centres and cost-centre stacks</title> - - <para>GHC's profiling system assigns <firstterm>costs</firstterm> - to <firstterm>cost centres</firstterm>. A cost is simply the time - or space (memory) required to evaluate an expression. Cost centres are - program annotations around expressions; all costs incurred by the - annotated expression are assigned to the enclosing cost centre. - Furthermore, GHC will remember the stack of enclosing cost centres - for any given expression at run-time and generate a call-tree of - cost attributions.</para> - - <para>Let's take a look at an example:</para> - - <programlisting> -main = print (fib 30) -fib n = if n < 2 then 1 else fib (n-1) + fib (n-2) -</programlisting> - - <para>Compile and run this program as follows:</para> - - <screen> -$ ghc -prof -fprof-auto -rtsopts Main.hs -$ ./Main +RTS -p -121393 -$ -</screen> - - <para>When a GHC-compiled program is run with the - <option>-p</option> RTS option, it generates a file called - <filename><replaceable>prog</replaceable>.prof</filename>. In this case, the file - will contain something like this:</para> - -<screen> - Wed Oct 12 16:14 2011 Time and Allocation Profiling Report (Final) - - Main +RTS -p -RTS - - total time = 0.68 secs (34 ticks @ 20 ms) - total alloc = 204,677,844 bytes (excludes profiling overheads) - -COST CENTRE MODULE %time %alloc - -fib Main 100.0 100.0 - - - individual inherited -COST CENTRE MODULE no. entries %time %alloc %time %alloc - -MAIN MAIN 102 0 0.0 0.0 100.0 100.0 - CAF GHC.IO.Handle.FD 128 0 0.0 0.0 0.0 0.0 - CAF GHC.IO.Encoding.Iconv 120 0 0.0 0.0 0.0 0.0 - CAF GHC.Conc.Signal 110 0 0.0 0.0 0.0 0.0 - CAF Main 108 0 0.0 0.0 100.0 100.0 - main Main 204 1 0.0 0.0 100.0 100.0 - fib Main 205 2692537 100.0 100.0 100.0 100.0 -</screen> - - <para>The first part of the file gives the program name and - options, and the total time and total memory allocation measured - during the run of the program (note that the total memory - allocation figure isn't the same as the amount of - <emphasis>live</emphasis> memory needed by the program at any one - time; the latter can be determined using heap profiling, which we - will describe later in <xref linkend="prof-heap" />).</para> - - <para>The second part of the file is a break-down by cost centre - of the most costly functions in the program. In this case, there - was only one significant function in the program, namely - <function>fib</function>, and it was responsible for 100% - of both the time and allocation costs of the program.</para> - - <para>The third and final section of the file gives a profile - break-down by cost-centre stack. This is roughly a call-tree - profile of the program. In the example above, it is clear that - the costly call to <function>fib</function> came from - <function>main</function>.</para> - - <para>The time and allocation incurred by a given part of the - program is displayed in two ways: “individual”, which - are the costs incurred by the code covered by this cost centre - stack alone, and “inherited”, which includes the costs - incurred by all the children of this node.</para> - - <para>The usefulness of cost-centre stacks is better demonstrated - by modifying the example slightly:</para> - - <programlisting> -main = print (f 30 + g 30) - where - f n = fib n - g n = fib (n `div` 2) - -fib n = if n < 2 then 1 else fib (n-1) + fib (n-2) -</programlisting> - - <para>Compile and run this program as before, and take a look at - the new profiling results:</para> - -<screen> -COST CENTRE MODULE no. entries %time %alloc %time %alloc - -MAIN MAIN 102 0 0.0 0.0 100.0 100.0 - CAF GHC.IO.Handle.FD 128 0 0.0 0.0 0.0 0.0 - CAF GHC.IO.Encoding.Iconv 120 0 0.0 0.0 0.0 0.0 - CAF GHC.Conc.Signal 110 0 0.0 0.0 0.0 0.0 - CAF Main 108 0 0.0 0.0 100.0 100.0 - main Main 204 1 0.0 0.0 100.0 100.0 - main.g Main 207 1 0.0 0.0 0.0 0.1 - fib Main 208 1973 0.0 0.1 0.0 0.1 - main.f Main 205 1 0.0 0.0 100.0 99.9 - fib Main 206 2692537 100.0 99.9 100.0 99.9 -</screen> - - <para>Now although we had two calls to <function>fib</function> in - the program, it is immediately clear that it was the call from - <function>f</function> which took all the time. The functions - <literal>f</literal> and <literal>g</literal> which are defined in - the <literal>where</literal> clause in <literal>main</literal> are - given their own cost centres, <literal>main.f</literal> and - <literal>main.g</literal> respectively.</para> - - <para>The actual meaning of the various columns in the output is:</para> - - <variablelist> - <varlistentry> - <term>entries</term> - <listitem> - <para>The number of times this particular point in the call - tree was entered.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>individual %time</term> - <listitem> - <para>The percentage of the total run time of the program - spent at this point in the call tree.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>individual %alloc</term> - <listitem> - <para>The percentage of the total memory allocations - (excluding profiling overheads) of the program made by this - call.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>inherited %time</term> - <listitem> - <para>The percentage of the total run time of the program - spent below this point in the call tree.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>inherited %alloc</term> - <listitem> - <para>The percentage of the total memory allocations - (excluding profiling overheads) of the program made by this - call and all of its sub-calls.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>In addition you can use the <option>-P</option> RTS option - <indexterm><primary><option>-P</option></primary></indexterm> to - get the following additional information:</para> - - <variablelist> - <varlistentry> - <term><literal>ticks</literal></term> - <listitem> - <para>The raw number of time “ticks” which were - attributed to this cost-centre; from this, we get the - <literal>%time</literal> figure mentioned - above.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>bytes</literal></term> - <listitem> - <para>Number of bytes allocated in the heap while in this - cost-centre; again, this is the raw number from which we get - the <literal>%alloc</literal> figure mentioned - above.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>What about recursive functions, and mutually recursive - groups of functions? Where are the costs attributed? Well, - although GHC does keep information about which groups of functions - called each other recursively, this information isn't displayed in - the basic time and allocation profile, instead the call-graph is - flattened into a tree as follows: a call to a function that occurs - elsewhere on the current stack does not push another entry on the - stack, instead the costs for this call are aggregated into the - caller<footnote><para>Note that this policy has changed slightly - in GHC 7.4.1 relative to earlier versions, and may yet change - further, feedback is welcome.</para></footnote>.</para> - - <sect2 id="scc-pragma"><title>Inserting cost centres by hand</title> - - <para>Cost centres are just program annotations. When you say - <option>-fprof-auto</option> to the compiler, it automatically - inserts a cost centre annotation around every binding not marked - INLINE in your program, but you are entirely free to add cost - centre annotations yourself.</para> - - <para>The syntax of a cost centre annotation is</para> - -<programlisting> - {-# SCC "name" #-} <expression> -</programlisting> - - <para>where <literal>"name"</literal> is an arbitrary string, - that will become the name of your cost centre as it appears - in the profiling output, and - <literal><expression></literal> is any Haskell - expression. An <literal>SCC</literal> annotation extends as - far to the right as possible when parsing. (SCC stands for "Set - Cost Centre"). The double quotes can be omitted - if <literal>name</literal> is a Haskell identifier, for example:</para> - -<programlisting> - {-# SCC my_function #-} <expression> -</programlisting> - - <para>Here is an example of a program with a couple of SCCs:</para> - -<programlisting> -main :: IO () -main = do let xs = [1..1000000] - let ys = [1..2000000] - print $ {-# SCC last_xs #-} last xs - print $ {-# SCC last_init_xs #-} last $ init xs - print $ {-# SCC last_ys #-} last ys - print $ {-# SCC last_init_ys #-}last $ init ys -</programlisting> - - <para>which gives this profile when run:</para> - -<screen> -COST CENTRE MODULE no. entries %time %alloc %time %alloc - -MAIN MAIN 102 0 0.0 0.0 100.0 100.0 - CAF GHC.IO.Handle.FD 130 0 0.0 0.0 0.0 0.0 - CAF GHC.IO.Encoding.Iconv 122 0 0.0 0.0 0.0 0.0 - CAF GHC.Conc.Signal 111 0 0.0 0.0 0.0 0.0 - CAF Main 108 0 0.0 0.0 100.0 100.0 - main Main 204 1 0.0 0.0 100.0 100.0 - last_init_ys Main 210 1 25.0 27.4 25.0 27.4 - main.ys Main 209 1 25.0 39.2 25.0 39.2 - last_ys Main 208 1 12.5 0.0 12.5 0.0 - last_init_xs Main 207 1 12.5 13.7 12.5 13.7 - main.xs Main 206 1 18.8 19.6 18.8 19.6 - last_xs Main 205 1 6.2 0.0 6.2 0.0 -</screen> - - </sect2> - - <sect2 id="prof-rules"> - <title>Rules for attributing costs</title> - - <para>While running a program with profiling turned on, GHC - maintains a cost-centre stack behind the scenes, and attributes - any costs (memory allocation and time) to whatever the current - cost-centre stack is at the time the cost is incurred.</para> - - <para>The mechanism is simple: whenever the program evaluates an - expression with an SCC annotation, <literal>{-# SCC c -#} - E</literal>, the cost centre <literal>c</literal> is pushed on - the current stack, and the entry count for this stack is - incremented by one. The stack also sometimes has to be saved - and restored; in particular when the program creates a - <firstterm>thunk</firstterm> (a lazy suspension), the current - cost-centre stack is stored in the thunk, and restored when the - thunk is evaluated. In this way, the cost-centre stack is - independent of the actual evaluation order used by GHC at - runtime.</para> - - <para>At a function call, GHC takes the stack stored in the - function being called (which for a top-level function will be - empty), and <emphasis>appends</emphasis> it to the current - stack, ignoring any prefix that is identical to a prefix of the - current stack.</para> - - <para>We mentioned earlier that lazy computations, i.e. thunks, - capture the current stack when they are created, and restore - this stack when they are evaluated. What about top-level - thunks? They are "created" when the program is compiled, so - what stack should we give them? The technical name for a - top-level thunk is a CAF ("Constant Applicative Form"). GHC - assigns every CAF in a module a stack consisting of the single - cost centre <literal>M.CAF</literal>, where <literal>M</literal> - is the name of the module. It is also possible to give each CAF - a different stack, using the option - <option>-fprof-cafs</option><indexterm><primary><option>-fprof-cafs</option></primary></indexterm>. - This is especially useful when compiling with - <option>-ffull-laziness</option> (as is default with - <option>-O</option> and higher), as constants in function bodies - will be lifted to the top-level and become CAFs. You will probably - need to consult the Core (<option>-ddump-simpl</option>) in order - to determine what these CAFs correspond to.</para> - </sect2> - </sect1> - - <sect1 id="prof-compiler-options"> - <title>Compiler options for profiling</title> - - <indexterm><primary>profiling</primary><secondary>options</secondary></indexterm> - <indexterm><primary>options</primary><secondary>for profiling</secondary></indexterm> - - <variablelist> - <varlistentry> - <term> - <option>-prof</option>: - <indexterm><primary><option>-prof</option></primary></indexterm> - </term> - <listitem> - <para>To make use of the profiling system - <emphasis>all</emphasis> modules must be compiled and linked - with the <option>-prof</option> option. Any - <literal>SCC</literal> annotations you've put in your source - will spring to life.</para> - - <para>Without a <option>-prof</option> option, your - <literal>SCC</literal>s are ignored; so you can compile - <literal>SCC</literal>-laden code without changing - it.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>There are a few other profiling-related compilation options. - Use them <emphasis>in addition to</emphasis> - <option>-prof</option>. These do not have to be used consistently - for all modules in a program.</para> - - <variablelist> - <varlistentry> - <term> - <option>-fprof-auto</option>: - <indexterm><primary><option>-fprof-auto</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>All</emphasis> bindings not marked INLINE, - whether exported or not, top level or nested, will be given - automatic <literal>SCC</literal> annotations. Functions - marked INLINE must be given a cost centre manually.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fprof-auto-top</option>: - <indexterm><primary><option>-fprof-auto-top</option></primary></indexterm> - <indexterm><primary>cost centres</primary><secondary>automatically inserting</secondary></indexterm> - </term> - <listitem> - <para>GHC will automatically add <literal>SCC</literal> - annotations for all top-level bindings not marked INLINE. If - you want a cost centre on an INLINE function, you have to - add it manually.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fprof-auto-exported</option>: - <indexterm><primary><option>-fprof-auto-top</option></primary></indexterm> - <indexterm><primary>cost centres</primary><secondary>automatically inserting</secondary></indexterm> - </term> - <listitem> - <para>GHC will automatically add <literal>SCC</literal> - annotations for all exported functions not marked - INLINE. If you want a cost centre on an INLINE function, you - have to add it manually.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fprof-auto-calls</option>: - <indexterm><primary><option>-fprof-auto-calls</option></primary></indexterm> - </term> - <listitem> - <para>Adds an automatic <literal>SCC</literal> annotation to - all <emphasis>call sites</emphasis>. This is particularly - useful when using profiling for the purposes of generating - stack traces; see the - function <literal>traceStack</literal> in the - module <literal>Debug.Trace</literal>, or - the <literal>-xc</literal> RTS flag - (<xref linkend="rts-options-debugging" />) for more - details.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fprof-cafs</option>: - <indexterm><primary><option>-fprof-cafs</option></primary></indexterm> - </term> - <listitem> - <para>The costs of all CAFs in a module are usually - attributed to one “big” CAF cost-centre. With - this option, all CAFs get their own cost-centre. An - “if all else fails” option…</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fno-prof-auto</option>: - <indexterm><primary><option>-no-fprof-auto</option></primary></indexterm> - </term> - <listitem> - <para>Disables any previous <option>-fprof-auto</option>, - <option>-fprof-auto-top</option>, or - <option>-fprof-auto-exported</option> options. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fno-prof-cafs</option>: - <indexterm><primary><option>-fno-prof-cafs</option></primary></indexterm> - </term> - <listitem> - <para>Disables any previous <option>-fprof-cafs</option> option. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fno-prof-count-entries</option>: - <indexterm><primary><option>-fno-prof-count-entries</option></primary></indexterm> - </term> - <listitem> - <para>Tells GHC not to collect information about how often - functions are entered at runtime (the "entries" column of - the time profile), for this module. This tends to make the - profiled code run faster, and hence closer to the speed of - the unprofiled code, because GHC is able to optimise more - aggressively if it doesn't have to maintain correct entry - counts. This option can be useful if you aren't interested - in the entry counts (for example, if you only intend to do - heap profiling). - </para> - </listitem> - </varlistentry> - </variablelist> - - </sect1> - - <sect1 id="prof-time-options"> - <title>Time and allocation profiling</title> - - <para>To generate a time and allocation profile, give one of the - following RTS options to the compiled program when you run it (RTS - options should be enclosed between <literal>+RTS...-RTS</literal> - as usual):</para> - - <variablelist> - <varlistentry> - <term> - <option>-p</option> or <option>-P</option> or <option>-pa</option>: - <indexterm><primary><option>-p</option></primary></indexterm> - <indexterm><primary><option>-P</option></primary></indexterm> - <indexterm><primary><option>-pa</option></primary></indexterm> - <indexterm><primary>time profile</primary></indexterm> - </term> - <listitem> - <para>The <option>-p</option> option produces a standard - <emphasis>time profile</emphasis> report. It is written - into the file - <filename><replaceable>program</replaceable>.prof</filename>.</para> - - <para>The <option>-P</option> option produces a more - detailed report containing the actual time and allocation - data as well. (Not used much.)</para> - - <para>The <option>-pa</option> option produces the most detailed - report containing all cost centres in addition to the actual time - and allocation data.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-V<replaceable>secs</replaceable></option> - <indexterm><primary><option>-V</option></primary><secondary>RTS - option</secondary></indexterm></term> - <listitem> - <para>Sets the interval that the RTS clock ticks at, which is - also the sampling interval of the time and allocation profile. - The default is 0.02 seconds.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-xc</option> - <indexterm><primary><option>-xc</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>This option causes the runtime to print out the - current cost-centre stack whenever an exception is raised. - This can be particularly useful for debugging the location - of exceptions, such as the notorious <literal>Prelude.head: - empty list</literal> error. See <xref - linkend="rts-options-debugging"/>.</para> - </listitem> - </varlistentry> - </variablelist> - - </sect1> - - <sect1 id="prof-heap"> - <title>Profiling memory usage</title> - - <para>In addition to profiling the time and allocation behaviour - of your program, you can also generate a graph of its memory usage - over time. This is useful for detecting the causes of - <firstterm>space leaks</firstterm>, when your program holds on to - more memory at run-time that it needs to. Space leaks lead to - slower execution due to heavy garbage collector activity, and may - even cause the program to run out of memory altogether.</para> - - <para>To generate a heap profile from your program:</para> - - <orderedlist> - <listitem> - <para>Compile the program for profiling (<xref - linkend="prof-compiler-options"/>).</para> - </listitem> - <listitem> - <para>Run it with one of the heap profiling options described - below (eg. <option>-h</option> for a basic producer profile). - This generates the file - <filename><replaceable>prog</replaceable>.hp</filename>.</para> - </listitem> - <listitem> - <para>Run <command>hp2ps</command> to produce a Postscript - file, - <filename><replaceable>prog</replaceable>.ps</filename>. The - <command>hp2ps</command> utility is described in detail in - <xref linkend="hp2ps"/>.</para> - </listitem> - <listitem> - <para>Display the heap profile using a postscript viewer such - as <application>Ghostview</application>, or print it out on a - Postscript-capable printer.</para> - </listitem> - </orderedlist> - - <para>For example, here is a heap profile produced for the program given above in <xref linkend="scc-pragma" />:</para> - - <!-- - contentwidth/contentheight don't appear to have any effect - other than making the PS file generation work, rather than - falling over. The result seems to be broken PS on the page - with the image. --> - <imagedata fileref="prof_scc.eps" contentwidth="645px" - contentdepth="428px"/> - - <para>You might also want to take a look - at <ulink url="http://www.haskell.org/haskellwiki/Hp2any">hp2any</ulink>, - a more advanced suite of tools (not distributed with GHC) for - displaying heap profiles.</para> - - <sect2 id="rts-options-heap-prof"> - <title>RTS options for heap profiling</title> - - <para>There are several different kinds of heap profile that can - be generated. All the different profile types yield a graph of - live heap against time, but they differ in how the live heap is - broken down into bands. The following RTS options select which - break-down to use:</para> - - <variablelist> - <varlistentry> - <term> - <option>-hc</option> - <indexterm><primary><option>-hc</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>(can be shortened to <option>-h</option>). Breaks down the graph by the cost-centre stack which - produced the data.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-hm</option> - <indexterm><primary><option>-hm</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>Break down the live heap by the module containing - the code which produced the data.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-hd</option> - <indexterm><primary><option>-hd</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>Breaks down the graph by <firstterm>closure - description</firstterm>. For actual data, the description - is just the constructor name, for other closures it is a - compiler-generated string identifying the closure.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-hy</option> - <indexterm><primary><option>-hy</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>Breaks down the graph by - <firstterm>type</firstterm>. For closures which have - function type or unknown/polymorphic type, the string will - represent an approximation to the actual type.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-hr</option> - <indexterm><primary><option>-hr</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>Break down the graph by <firstterm>retainer - set</firstterm>. Retainer profiling is described in more - detail below (<xref linkend="retainer-prof"/>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-hb</option> - <indexterm><primary><option>-hb</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>Break down the graph by - <firstterm>biography</firstterm>. Biographical profiling - is described in more detail below (<xref - linkend="biography-prof"/>).</para> - </listitem> - </varlistentry> - </variablelist> - - <para>In addition, the profile can be restricted to heap data - which satisfies certain criteria - for example, you might want - to display a profile by type but only for data produced by a - certain module, or a profile by retainer for a certain type of - data. Restrictions are specified as follows:</para> - - <variablelist> - <varlistentry> - <term> - <option>-hc</option><replaceable>name</replaceable>,... - <indexterm><primary><option>-hc</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>Restrict the profile to closures produced by - cost-centre stacks with one of the specified cost centres - at the top.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-hC</option><replaceable>name</replaceable>,... - <indexterm><primary><option>-hC</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>Restrict the profile to closures produced by - cost-centre stacks with one of the specified cost centres - anywhere in the stack.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-hm</option><replaceable>module</replaceable>,... - <indexterm><primary><option>-hm</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>Restrict the profile to closures produced by the - specified modules.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-hd</option><replaceable>desc</replaceable>,... - <indexterm><primary><option>-hd</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>Restrict the profile to closures with the specified - description strings.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-hy</option><replaceable>type</replaceable>,... - <indexterm><primary><option>-hy</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>Restrict the profile to closures with the specified - types.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-hr</option><replaceable>cc</replaceable>,... - <indexterm><primary><option>-hr</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>Restrict the profile to closures with retainer sets - containing cost-centre stacks with one of the specified - cost centres at the top.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-hb</option><replaceable>bio</replaceable>,... - <indexterm><primary><option>-hb</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>Restrict the profile to closures with one of the - specified biographies, where - <replaceable>bio</replaceable> is one of - <literal>lag</literal>, <literal>drag</literal>, - <literal>void</literal>, or <literal>use</literal>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>For example, the following options will generate a - retainer profile restricted to <literal>Branch</literal> and - <literal>Leaf</literal> constructors:</para> - -<screen> -<replaceable>prog</replaceable> +RTS -hr -hdBranch,Leaf -</screen> - - <para>There can only be one "break-down" option - (eg. <option>-hr</option> in the example above), but there is no - limit on the number of further restrictions that may be applied. - All the options may be combined, with one exception: GHC doesn't - currently support mixing the <option>-hr</option> and - <option>-hb</option> options.</para> - - <para>There are three more options which relate to heap - profiling:</para> - - <variablelist> - <varlistentry> - <term> - <option>-i<replaceable>secs</replaceable></option>: - <indexterm><primary><option>-i</option></primary></indexterm> - </term> - <listitem> - <para>Set the profiling (sampling) interval to - <replaceable>secs</replaceable> seconds (the default is - 0.1 second). Fractions are allowed: for example - <option>-i0.2</option> will get 5 samples per second. - This only affects heap profiling; time profiles are always - sampled with the frequency of the RTS clock. See - <xref linkend="prof-time-options"/> for changing that.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-xt</option> - <indexterm><primary><option>-xt</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>Include the memory occupied by threads in a heap - profile. Each thread takes up a small area for its thread - state in addition to the space allocated for its stack - (stacks normally start small and then grow as - necessary).</para> - - <para>This includes the main thread, so using - <option>-xt</option> is a good way to see how much stack - space the program is using.</para> - - <para>Memory occupied by threads and their stacks is - labelled as “TSO” and “STACK” - respectively when displaying the profile by closure - description or type description.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-L<replaceable>num</replaceable></option> - <indexterm><primary><option>-L</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para> - Sets the maximum length of a cost-centre stack name in a - heap profile. Defaults to 25. - </para> - </listitem> - </varlistentry> - </variablelist> - - </sect2> - - <sect2 id="retainer-prof"> - <title>Retainer Profiling</title> - - <para>Retainer profiling is designed to help answer questions - like <quote>why is this data being retained?</quote>. We start - by defining what we mean by a retainer:</para> - - <blockquote> - <para>A retainer is either the system stack, an unevaluated - closure (thunk), or an explicitly mutable object.</para> - </blockquote> - - <para>In particular, constructors are <emphasis>not</emphasis> - retainers.</para> - - <para>An object B retains object A if (i) B is a retainer object and - (ii) object A can be reached by recursively following pointers - starting from object B, but not meeting any other retainer - objects on the way. Each live object is retained by one or more - retainer objects, collectively called its retainer set, or its - <firstterm>retainer set</firstterm>, or its - <firstterm>retainers</firstterm>.</para> - - <para>When retainer profiling is requested by giving the program - the <option>-hr</option> option, a graph is generated which is - broken down by retainer set. A retainer set is displayed as a - set of cost-centre stacks; because this is usually too large to - fit on the profile graph, each retainer set is numbered and - shown abbreviated on the graph along with its number, and the - full list of retainer sets is dumped into the file - <filename><replaceable>prog</replaceable>.prof</filename>.</para> - - <para>Retainer profiling requires multiple passes over the live - heap in order to discover the full retainer set for each - object, which can be quite slow. So we set a limit on the - maximum size of a retainer set, where all retainer sets larger - than the maximum retainer set size are replaced by the special - set <literal>MANY</literal>. The maximum set size defaults to 8 - and can be altered with the <option>-R</option> RTS - option:</para> - - <variablelist> - <varlistentry> - <term><option>-R</option><replaceable>size</replaceable></term> - <listitem> - <para>Restrict the number of elements in a retainer set to - <replaceable>size</replaceable> (default 8).</para> - </listitem> - </varlistentry> - </variablelist> - - <sect3> - <title>Hints for using retainer profiling</title> - - <para>The definition of retainers is designed to reflect a - common cause of space leaks: a large structure is retained by - an unevaluated computation, and will be released once the - computation is forced. A good example is looking up a value in - a finite map, where unless the lookup is forced in a timely - manner the unevaluated lookup will cause the whole mapping to - be retained. These kind of space leaks can often be - eliminated by forcing the relevant computations to be - performed eagerly, using <literal>seq</literal> or strictness - annotations on data constructor fields.</para> - - <para>Often a particular data structure is being retained by a - chain of unevaluated closures, only the nearest of which will - be reported by retainer profiling - for example A retains B, B - retains C, and C retains a large structure. There might be a - large number of Bs but only a single A, so A is really the one - we're interested in eliminating. However, retainer profiling - will in this case report B as the retainer of the large - structure. To move further up the chain of retainers, we can - ask for another retainer profile but this time restrict the - profile to B objects, so we get a profile of the retainers of - B:</para> - -<screen> -<replaceable>prog</replaceable> +RTS -hr -hcB -</screen> - - <para>This trick isn't foolproof, because there might be other - B closures in the heap which aren't the retainers we are - interested in, but we've found this to be a useful technique - in most cases.</para> - </sect3> - </sect2> - - <sect2 id="biography-prof"> - <title>Biographical Profiling</title> - - <para>A typical heap object may be in one of the following four - states at each point in its lifetime:</para> - - <itemizedlist> - <listitem> - <para>The <firstterm>lag</firstterm> stage, which is the - time between creation and the first use of the - object,</para> - </listitem> - <listitem> - <para>the <firstterm>use</firstterm> stage, which lasts from - the first use until the last use of the object, and</para> - </listitem> - <listitem> - <para>The <firstterm>drag</firstterm> stage, which lasts - from the final use until the last reference to the object - is dropped.</para> - </listitem> - <listitem> - <para>An object which is never used is said to be in the - <firstterm>void</firstterm> state for its whole - lifetime.</para> - </listitem> - </itemizedlist> - - <para>A biographical heap profile displays the portion of the - live heap in each of the four states listed above. Usually the - most interesting states are the void and drag states: live heap - in these states is more likely to be wasted space than heap in - the lag or use states.</para> - - <para>It is also possible to break down the heap in one or more - of these states by a different criteria, by restricting a - profile by biography. For example, to show the portion of the - heap in the drag or void state by producer: </para> - -<screen> -<replaceable>prog</replaceable> +RTS -hc -hbdrag,void -</screen> - - <para>Once you know the producer or the type of the heap in the - drag or void states, the next step is usually to find the - retainer(s):</para> - -<screen> -<replaceable>prog</replaceable> +RTS -hr -hc<replaceable>cc</replaceable>... -</screen> - - <para>NOTE: this two stage process is required because GHC - cannot currently profile using both biographical and retainer - information simultaneously.</para> - </sect2> - - <sect2 id="mem-residency"> - <title>Actual memory residency</title> - - <para>How does the heap residency reported by the heap profiler relate to - the actual memory residency of your program when you run it? You might - see a large discrepancy between the residency reported by the heap - profiler, and the residency reported by tools on your system - (eg. <literal>ps</literal> or <literal>top</literal> on Unix, or the - Task Manager on Windows). There are several reasons for this:</para> - - <itemizedlist> - <listitem> - <para>There is an overhead of profiling itself, which is subtracted - from the residency figures by the profiler. This overhead goes - away when compiling without profiling support, of course. The - space overhead is currently 2 extra - words per heap object, which probably results in - about a 30% overhead.</para> - </listitem> - - <listitem> - <para>Garbage collection requires more memory than the actual - residency. The factor depends on the kind of garbage collection - algorithm in use: a major GC in the standard - generation copying collector will usually require 3L bytes of - memory, where L is the amount of live data. This is because by - default (see the <option>+RTS -F</option> option) we allow the old - generation to grow to twice its size (2L) before collecting it, and - we require additionally L bytes to copy the live data into. When - using compacting collection (see the <option>+RTS -c</option> - option), this is reduced to 2L, and can further be reduced by - tweaking the <option>-F</option> option. Also add the size of the - allocation area (currently a fixed 512Kb).</para> - </listitem> - - <listitem> - <para>The stack isn't counted in the heap profile by default. See the - <option>+RTS -xt</option> option.</para> - </listitem> - - <listitem> - <para>The program text itself, the C stack, any non-heap data (eg. data - allocated by foreign libraries, and data allocated by the RTS), and - <literal>mmap()</literal>'d memory are not counted in the heap profile.</para> - </listitem> - </itemizedlist> - </sect2> - - </sect1> - - <sect1 id="hp2ps"> - <title><command>hp2ps</command>--heap profile to PostScript</title> - - <indexterm><primary><command>hp2ps</command></primary></indexterm> - <indexterm><primary>heap profiles</primary></indexterm> - <indexterm><primary>postscript, from heap profiles</primary></indexterm> - <indexterm><primary><option>-h<break-down></option></primary></indexterm> - - <para>Usage:</para> - -<screen> -hp2ps [flags] [<file>[.hp]] -</screen> - - <para>The program - <command>hp2ps</command><indexterm><primary>hp2ps - program</primary></indexterm> converts a heap profile as produced - by the <option>-h<break-down></option> runtime option into a - PostScript graph of the heap profile. By convention, the file to - be processed by <command>hp2ps</command> has a - <filename>.hp</filename> extension. The PostScript output is - written to <filename><file>@.ps</filename>. If - <filename><file></filename> is omitted entirely, then the - program behaves as a filter.</para> - - <para><command>hp2ps</command> is distributed in - <filename>ghc/utils/hp2ps</filename> in a GHC source - distribution. It was originally developed by Dave Wakeling as part - of the HBC/LML heap profiler.</para> - - <para>The flags are:</para> - - <variablelist> - - <varlistentry> - <term><option>-d</option></term> - <listitem> - <para>In order to make graphs more readable, - <command>hp2ps</command> sorts the shaded bands for each - identifier. The default sort ordering is for the bands with - the largest area to be stacked on top of the smaller ones. - The <option>-d</option> option causes rougher bands (those - representing series of values with the largest standard - deviations) to be stacked on top of smoother ones.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-b</option></term> - <listitem> - <para>Normally, <command>hp2ps</command> puts the title of - the graph in a small box at the top of the page. However, if - the JOB string is too long to fit in a small box (more than - 35 characters), then <command>hp2ps</command> will choose to - use a big box instead. The <option>-b</option> option - forces <command>hp2ps</command> to use a big box.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-e<float>[in|mm|pt]</option></term> - <listitem> - <para>Generate encapsulated PostScript suitable for - inclusion in LaTeX documents. Usually, the PostScript graph - is drawn in landscape mode in an area 9 inches wide by 6 - inches high, and <command>hp2ps</command> arranges for this - area to be approximately centred on a sheet of a4 paper. - This format is convenient of studying the graph in detail, - but it is unsuitable for inclusion in LaTeX documents. The - <option>-e</option> option causes the graph to be drawn in - portrait mode, with float specifying the width in inches, - millimetres or points (the default). The resulting - PostScript file conforms to the Encapsulated PostScript - (EPS) convention, and it can be included in a LaTeX document - using Rokicki's dvi-to-PostScript converter - <command>dvips</command>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-g</option></term> - <listitem> - <para>Create output suitable for the <command>gs</command> - PostScript previewer (or similar). In this case the graph is - printed in portrait mode without scaling. The output is - unsuitable for a laser printer.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-l</option></term> - <listitem> - <para>Normally a profile is limited to 20 bands with - additional identifiers being grouped into an - <literal>OTHER</literal> band. The <option>-l</option> flag - removes this 20 band and limit, producing as many bands as - necessary. No key is produced as it won't fit!. It is useful - for creation time profiles with many bands.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-m<int></option></term> - <listitem> - <para>Normally a profile is limited to 20 bands with - additional identifiers being grouped into an - <literal>OTHER</literal> band. The <option>-m</option> flag - specifies an alternative band limit (the maximum is - 20).</para> - - <para><option>-m0</option> requests the band limit to be - removed. As many bands as necessary are produced. However no - key is produced as it won't fit! It is useful for displaying - creation time profiles with many bands.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-p</option></term> - <listitem> - <para>Use previous parameters. By default, the PostScript - graph is automatically scaled both horizontally and - vertically so that it fills the page. However, when - preparing a series of graphs for use in a presentation, it - is often useful to draw a new graph using the same scale, - shading and ordering as a previous one. The - <option>-p</option> flag causes the graph to be drawn using - the parameters determined by a previous run of - <command>hp2ps</command> on <filename>file</filename>. These - are extracted from <filename>file@.aux</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-s</option></term> - <listitem> - <para>Use a small box for the title.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-t<float></option></term> - <listitem> - <para>Normally trace elements which sum to a total of less - than 1% of the profile are removed from the - profile. The <option>-t</option> option allows this - percentage to be modified (maximum 5%).</para> - - <para><option>-t0</option> requests no trace elements to be - removed from the profile, ensuring that all the data will be - displayed.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-c</option></term> - <listitem> - <para>Generate colour output.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-y</option></term> - <listitem> - <para>Ignore marks.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-?</option></term> - <listitem> - <para>Print out usage information.</para> - </listitem> - </varlistentry> - </variablelist> - - - <sect2 id="manipulating-hp"> - <title>Manipulating the hp file</title> - -<para>(Notes kindly offered by Jan-Willem Maessen.)</para> - -<para> -The <filename>FOO.hp</filename> file produced when you ask for the -heap profile of a program <filename>FOO</filename> is a text file with a particularly -simple structure. Here's a representative example, with much of the -actual data omitted: -<screen> -JOB "FOO -hC" -DATE "Thu Dec 26 18:17 2002" -SAMPLE_UNIT "seconds" -VALUE_UNIT "bytes" -BEGIN_SAMPLE 0.00 -END_SAMPLE 0.00 -BEGIN_SAMPLE 15.07 - ... sample data ... -END_SAMPLE 15.07 -BEGIN_SAMPLE 30.23 - ... sample data ... -END_SAMPLE 30.23 -... etc. -BEGIN_SAMPLE 11695.47 -END_SAMPLE 11695.47 -</screen> -The first four lines (<literal>JOB</literal>, <literal>DATE</literal>, <literal>SAMPLE_UNIT</literal>, <literal>VALUE_UNIT</literal>) form a -header. Each block of lines starting with <literal>BEGIN_SAMPLE</literal> and ending -with <literal>END_SAMPLE</literal> forms a single sample (you can think of this as a -vertical slice of your heap profile). The hp2ps utility should accept -any input with a properly-formatted header followed by a series of -*complete* samples. -</para> -</sect2> - - <sect2> - <title>Zooming in on regions of your profile</title> - -<para> -You can look at particular regions of your profile simply by loading a -copy of the <filename>.hp</filename> file into a text editor and deleting the unwanted -samples. The resulting <filename>.hp</filename> file can be run through <command>hp2ps</command> and viewed -or printed. -</para> -</sect2> - - <sect2> - <title>Viewing the heap profile of a running program</title> - -<para> -The <filename>.hp</filename> file is generated incrementally as your -program runs. In principle, running <command>hp2ps</command> on the incomplete file -should produce a snapshot of your program's heap usage. However, the -last sample in the file may be incomplete, causing <command>hp2ps</command> to fail. If -you are using a machine with UNIX utilities installed, it's not too -hard to work around this problem (though the resulting command line -looks rather Byzantine): -<screen> - head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \ - | hp2ps > FOO.ps -</screen> - -The command <command>fgrep -n END_SAMPLE FOO.hp</command> finds the -end of every complete sample in <filename>FOO.hp</filename>, and labels each sample with -its ending line number. We then select the line number of the last -complete sample using <command>tail</command> and <command>cut</command>. This is used as a -parameter to <command>head</command>; the result is as if we deleted the final -incomplete sample from <filename>FOO.hp</filename>. This results in a properly-formatted -.hp file which we feed directly to <command>hp2ps</command>. -</para> -</sect2> - <sect2> - <title>Viewing a heap profile in real time</title> - -<para> -The <command>gv</command> and <command>ghostview</command> programs -have a "watch file" option can be used to view an up-to-date heap -profile of your program as it runs. Simply generate an incremental -heap profile as described in the previous section. Run <command>gv</command> on your -profile: -<screen> - gv -watch -orientation=seascape FOO.ps -</screen> -If you forget the <literal>-watch</literal> flag you can still select -"Watch file" from the "State" menu. Now each time you generate a new -profile <filename>FOO.ps</filename> the view will update automatically. -</para> - -<para> -This can all be encapsulated in a little script: -<screen> - #!/bin/sh - head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \ - | hp2ps > FOO.ps - gv -watch -orientation=seascape FOO.ps & - while [ 1 ] ; do - sleep 10 # We generate a new profile every 10 seconds. - head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \ - | hp2ps > FOO.ps - done -</screen> -Occasionally <command>gv</command> will choke as it tries to read an incomplete copy of -<filename>FOO.ps</filename> (because <command>hp2ps</command> is still running as an update -occurs). A slightly more complicated script works around this -problem, by using the fact that sending a SIGHUP to gv will cause it -to re-read its input file: -<screen> - #!/bin/sh - head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \ - | hp2ps > FOO.ps - gv FOO.ps & - gvpsnum=$! - while [ 1 ] ; do - sleep 10 - head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \ - | hp2ps > FOO.ps - kill -HUP $gvpsnum - done -</screen> -</para> -</sect2> - </sect1> - - <sect1 id="prof-threaded"> - <title>Profiling Parallel and Concurrent Programs</title> - - <para>Combining <option>-threaded</option> - and <option>-prof</option> is perfectly fine, and indeed it is - possible to profile a program running on multiple processors - with the <option>+RTS -N</option> option.<footnote>This feature - was added in GHC 7.4.1.</footnote> - </para> - - <para> - Some caveats apply, however. In the current implementation, a - profiled program is likely to scale much less well than the - unprofiled program, because the profiling implementation uses - some shared data structures which require locking in the runtime - system. Furthermore, the memory allocation statistics collected - by the profiled program are stored in shared memory - but <emphasis>not</emphasis> locked (for speed), which means - that these figures might be inaccurate for parallel programs. - </para> - - <para> - We strongly recommend that you - use <option>-fno-prof-count-entries</option> when compiling a - program to be profiled on multiple cores, because the entry - counts are also stored in shared memory, and continuously - updating them on multiple cores is extremely slow. - </para> - - <para> - We also recommend - using <ulink url="http://www.haskell.org/haskellwiki/ThreadScope">ThreadScope</ulink> - for profiling parallel programs; it offers a GUI for visualising - parallel execution, and is complementary to the time and space - profiling features provided with GHC. - </para> - </sect1> - - <sect1 id="hpc"> - <title>Observing Code Coverage</title> - <indexterm><primary>code coverage</primary></indexterm> - <indexterm><primary>Haskell Program Coverage</primary></indexterm> - <indexterm><primary>hpc</primary></indexterm> - - <para> - Code coverage tools allow a programmer to determine what parts - of their code have been actually executed, and which parts have - never actually been invoked. GHC has an option for generating - instrumented code that records code coverage as part of the - Haskell Program Coverage (HPC) toolkit, which is included with - GHC. HPC tools can be used to render the generated code coverage - information into human understandable format. </para> - - <para> - Correctly instrumented code provides coverage information of two - kinds: source coverage and boolean-control coverage. Source - coverage is the extent to which every part of the program was - used, measured at three different levels: declarations (both - top-level and local), alternatives (among several equations or - case branches) and expressions (at every level). Boolean - coverage is the extent to which each of the values True and - False is obtained in every syntactic boolean context (ie. guard, - condition, qualifier). </para> - - <para> - HPC displays both kinds of information in two primary ways: - textual reports with summary statistics (<literal>hpc report</literal>) and sources - with color mark-up (<literal>hpc markup</literal>). For boolean coverage, there - are four possible outcomes for each guard, condition or - qualifier: both True and False values occur; only True; only - False; never evaluated. In hpc-markup output, highlighting with - a yellow background indicates a part of the program that was - never evaluated; a green background indicates an always-True - expression and a red background indicates an always-False one. - </para> - - <sect2><title>A small example: Reciprocation</title> - - <para> - For an example we have a program, called <filename>Recip.hs</filename>, which computes exact decimal - representations of reciprocals, with recurring parts indicated in - brackets. - </para> -<programlisting> -reciprocal :: Int -> (String, Int) -reciprocal n | n > 1 = ('0' : '.' : digits, recur) - | otherwise = error - "attempting to compute reciprocal of number <= 1" - where - (digits, recur) = divide n 1 [] -divide :: Int -> Int -> [Int] -> (String, Int) -divide n c cs | c `elem` cs = ([], position c cs) - | r == 0 = (show q, 0) - | r /= 0 = (show q ++ digits, recur) - where - (q, r) = (c*10) `quotRem` n - (digits, recur) = divide n r (c:cs) - -position :: Int -> [Int] -> Int -position n (x:xs) | n==x = 1 - | otherwise = 1 + position n xs - -showRecip :: Int -> String -showRecip n = - "1/" ++ show n ++ " = " ++ - if r==0 then d else take p d ++ "(" ++ drop p d ++ ")" - where - p = length d - r - (d, r) = reciprocal n - -main = do - number <- readLn - putStrLn (showRecip number) - main -</programlisting> - - <para>HPC instrumentation is enabled with the -fhpc flag: - </para> - -<screen> -$ ghc -fhpc Recip.hs -</screen> - <para>GHC creates a subdirectory <filename>.hpc</filename> in the - current directory, and puts HPC index (<filename>.mix</filename>) - files in there, one for each module compiled. You don't need to - worry about these files: they contain information needed by the - <literal>hpc</literal> tool to generate the coverage data for - compiled modules after the program is run.</para> -<screen> -$ ./Recip -1/3 -= 0.(3) -</screen> - <para>Running the program generates a file with the - <literal>.tix</literal> suffix, in this case - <filename>Recip.tix</filename>, which contains the coverage data - for this run of the program. The program may be run multiple - times (e.g. with different test data), and the coverage data from - the separate runs is accumulated in the <filename>.tix</filename> - file. To reset the coverage data and start again, just remove the - <filename>.tix</filename> file. - </para> - - <para>Having run the program, we can generate a textual summary of - coverage:</para> -<screen> -$ hpc report Recip - 80% expressions used (81/101) - 12% boolean coverage (1/8) - 14% guards (1/7), 3 always True, - 1 always False, - 2 unevaluated - 0% 'if' conditions (0/1), 1 always False - 100% qualifiers (0/0) - 55% alternatives used (5/9) -100% local declarations used (9/9) -100% top-level declarations used (5/5) -</screen> - <para>We can also generate a marked-up version of the source.</para> -<screen> -$ hpc markup Recip -writing Recip.hs.html -</screen> - <para> - This generates one file per Haskell module, and 4 index files, - hpc_index.html, hpc_index_alt.html, hpc_index_exp.html, - hpc_index_fun.html. - </para> - </sect2> - - <sect2><title>Options for instrumenting code for coverage</title> - - <variablelist> - <varlistentry> - <term><option>-fhpc</option></term> - <indexterm><primary><option>-fhpc</option></primary></indexterm> - <listitem> - <para>Enable code coverage for the current module or modules - being compiled.</para> - - <para>Modules compiled with this option can be freely mixed - with modules compiled without it; indeed, most libraries - will typically be compiled without <option>-fhpc</option>. - When the program is run, coverage data will only be - generated for those modules that were compiled with - <option>-fhpc</option>, and the <literal>hpc</literal> tool - will only show information about those modules. - </para> - </listitem> - </varlistentry> - </variablelist> - - </sect2> - - <sect2><title>The hpc toolkit</title> - - <para>The hpc command has several sub-commands:</para> -<screen> -$ hpc -Usage: hpc COMMAND ... - -Commands: - help Display help for hpc or a single command -Reporting Coverage: - report Output textual report about program coverage - markup Markup Haskell source with program coverage -Processing Coverage files: - sum Sum multiple .tix files in a single .tix file - combine Combine two .tix files in a single .tix file - map Map a function over a single .tix file -Coverage Overlays: - overlay Generate a .tix file from an overlay file - draft Generate draft overlay that provides 100% coverage -Others: - show Show .tix file in readable, verbose format - version Display version for hpc -</screen> - - <para>In general, these options act on a - <filename>.tix</filename> file after an instrumented binary has - generated it. - </para> - - <para> - The hpc tool assumes you are in the top-level directory of - the location where you built your application, and the <filename>.tix</filename> - file is in the same top-level directory. You can use the - flag <option>--srcdir</option> to use <literal>hpc</literal> for any other directory, and use - <option>--srcdir</option> multiple times to analyse programs compiled from - difference locations, as is typical for packages. - </para> - - <para> - We now explain in more details the major modes of hpc. - </para> - - <sect3><title>hpc report</title> - <para><literal>hpc report</literal> gives a textual report of coverage. By default, - all modules and packages are considered in generating report, - unless include or exclude are used. The report is a summary - unless the <option>--per-module</option> flag is used. The <option>--xml-output</option> option - allows for tools to use hpc to glean coverage. - </para> -<screen> -$ hpc help report -Usage: hpc report [OPTION] .. <TIX_FILE> [<MODULE> [<MODULE> ..]] - -Options: - - --per-module show module level detail - --decl-list show unused decls - --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE - --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE - --srcdir=DIR path to source directory of .hs files - multi-use of srcdir possible - --hpcdir=DIR append sub-directory that contains .mix files - default .hpc [rarely used] - --reset-hpcdirs empty the list of hpcdir's - [rarely used] - --xml-output show output in XML -</screen> - </sect3> - <sect3><title>hpc markup</title> - <para><literal>hpc markup</literal> marks up source files into colored html. - </para> -<screen> -$ hpc help markup -Usage: hpc markup [OPTION] .. <TIX_FILE> [<MODULE> [<MODULE> ..]] - -Options: - - --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE - --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE - --srcdir=DIR path to source directory of .hs files - multi-use of srcdir possible - --hpcdir=DIR append sub-directory that contains .mix files - default .hpc [rarely used] - --reset-hpcdirs empty the list of hpcdir's - [rarely used] - --fun-entry-count show top-level function entry counts - --highlight-covered highlight covered code, rather that code gaps - --destdir=DIR path to write output to -</screen> - - </sect3> - <sect3><title>hpc sum</title> - <para><literal>hpc sum</literal> adds together any number of <filename>.tix</filename> files into a single - <filename>.tix</filename> file. <literal>hpc sum</literal> does not change the original <filename>.tix</filename> file; it generates a new <filename>.tix</filename> file. - </para> -<screen> -$ hpc help sum -Usage: hpc sum [OPTION] .. <TIX_FILE> [<TIX_FILE> [<TIX_FILE> ..]] -Sum multiple .tix files in a single .tix file - -Options: - - --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE - --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE - --output=FILE output FILE - --union use the union of the module namespace (default is intersection) -</screen> - </sect3> - <sect3><title>hpc combine</title> - <para><literal>hpc combine</literal> is the swiss army knife of <literal>hpc</literal>. It can be - used to take the difference between <filename>.tix</filename> files, to subtract one - <filename>.tix</filename> file from another, or to add two <filename>.tix</filename> files. hpc combine does not - change the original <filename>.tix</filename> file; it generates a new <filename>.tix</filename> file. - </para> -<screen> -$ hpc help combine -Usage: hpc combine [OPTION] .. <TIX_FILE> <TIX_FILE> -Combine two .tix files in a single .tix file - -Options: - - --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE - --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE - --output=FILE output FILE - --function=FUNCTION combine .tix files with join function, default = ADD - FUNCTION = ADD | DIFF | SUB - --union use the union of the module namespace (default is intersection) -</screen> - </sect3> - <sect3><title>hpc map</title> - <para>hpc map inverts or zeros a <filename>.tix</filename> file. hpc map does not - change the original <filename>.tix</filename> file; it generates a new <filename>.tix</filename> file. - </para> -<screen> -$ hpc help map -Usage: hpc map [OPTION] .. <TIX_FILE> -Map a function over a single .tix file - -Options: - - --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE - --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE - --output=FILE output FILE - --function=FUNCTION apply function to .tix files, default = ID - FUNCTION = ID | INV | ZERO - --union use the union of the module namespace (default is intersection) -</screen> - </sect3> - <sect3><title>hpc overlay and hpc draft</title> - <para> - Overlays are an experimental feature of HPC, a textual description - of coverage. hpc draft is used to generate a draft overlay from a .tix file, - and hpc overlay generates a .tix files from an overlay. - </para> -<screen> -% hpc help overlay -Usage: hpc overlay [OPTION] .. <OVERLAY_FILE> [<OVERLAY_FILE> [...]] - -Options: - - --srcdir=DIR path to source directory of .hs files - multi-use of srcdir possible - --hpcdir=DIR append sub-directory that contains .mix files - default .hpc [rarely used] - --reset-hpcdirs empty the list of hpcdir's - [rarely used] - --output=FILE output FILE -% hpc help draft -Usage: hpc draft [OPTION] .. <TIX_FILE> - -Options: - - --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE - --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE - --srcdir=DIR path to source directory of .hs files - multi-use of srcdir possible - --hpcdir=DIR append sub-directory that contains .mix files - default .hpc [rarely used] - --reset-hpcdirs empty the list of hpcdir's - [rarely used] - --output=FILE output FILE -</screen> - </sect3> - </sect2> - <sect2><title>Caveats and Shortcomings of Haskell Program Coverage</title> - <para> - HPC does not attempt to lock the <filename>.tix</filename> file, so multiple concurrently running - binaries in the same directory will exhibit a race condition. There is no way - to change the name of the <filename>.tix</filename> file generated, apart from renaming the binary. - HPC does not work with GHCi. - </para> - </sect2> - </sect1> - - <sect1 id="ticky-ticky"> - <title>Using “ticky-ticky” profiling (for implementors)</title> - <indexterm><primary>ticky-ticky profiling</primary></indexterm> - - <para>Because ticky-ticky profiling requires a certain familiarity - with GHC internals, we have moved the documentation to the - GHC developers wiki. Take a look at its <ulink - url="http://ghc.haskell.org/trac/ghc/wiki/Commentary/Profiling">overview - of the profiling options</ulink>, which includeds a link to the - ticky-ticky profiling page.</para> - </sect1> - -</chapter> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> diff --git a/docs/users_guide/runghc.rst b/docs/users_guide/runghc.rst new file mode 100644 index 0000000000..0bf9690f62 --- /dev/null +++ b/docs/users_guide/runghc.rst @@ -0,0 +1,36 @@ +.. _runghc: + +Using runghc +============ + +.. index:: + single: runghc + +``runghc`` allows you to run Haskell programs without first having to +compile them. + +.. _runghc-introduction: + +Flags +----- + +The ``runghc`` command-line looks like: + +:: + + runghc [runghc flags] [GHC flags] module [program args] + +The runghc flags are ``-f /path/to/ghc``, which tells runghc which GHC +to use to run the program, and ``--help``, which prints usage +information. If it is not given then runghc will search for GHC in the +directories in the system search path. + +runghc will try to work out where the boundaries between +``[runghc flags]`` and ``[GHC flags]``, and ``[program args]`` and +``module`` are, but you can use a ``--`` flag if it doesn't get it +right. For example, ``runghc -- -fwarn-unused-bindings Foo`` means +runghc won't try to use ``warn-unused-bindings`` as the path to GHC, but +instead will pass the flag to GHC. If a GHC flag doesn't start with a +dash then you need to prefix it with ``--ghc-arg=`` or runghc will think +that it is the program to run, e.g. +``runghc -package-db --ghc-arg=foo.conf Main.hs``. diff --git a/docs/users_guide/runghc.xml b/docs/users_guide/runghc.xml deleted file mode 100644 index 0fc147f687..0000000000 --- a/docs/users_guide/runghc.xml +++ /dev/null @@ -1,47 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<chapter id="runghc"> - <title>Using runghc</title> - <indexterm><primary>runghc</primary></indexterm> - - <para>runghc allows you to run Haskell programs without first having - to compile them.</para> - - <sect1 id="runghc-introduction"> - <title>Flags</title> - - <para>The runghc command-line looks like:</para> -<screen> -runghc [runghc flags] [GHC flags] module [program args] -</screen> - <para>The runghc flags are - <literal>-f /path/to/ghc</literal>, - which tells runghc which GHC to use to run the program, - and <literal>--help</literal>, which prints usage information. If it is - not given then runghc will search for GHC in the directories in the - system search path.</para> - - <para>runghc will try to work out where the boundaries between - <literal>[runghc flags]</literal> and - <literal>[GHC flags]</literal>, and - <literal>[program args]</literal> and - <literal>module</literal> are, but you can use a - <literal>--</literal> flag if it doesn't get it right. For example, - <literal>runghc -- -fwarn-unused-bindings Foo</literal> means runghc - won't try to use <literal>warn-unused-bindings</literal> as the path to GHC, - but instead will pass the flag to GHC. If a GHC flag doesn't start - with a dash then you need to prefix it with - <literal>--ghc-arg=</literal> or runghc will think that it is the - program to run, e.g. - <literal>runghc -package-db --ghc-arg=foo.conf Main.hs</literal>. - </para> - - </sect1> - -</chapter> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> diff --git a/docs/users_guide/runtime_control.rst b/docs/users_guide/runtime_control.rst new file mode 100644 index 0000000000..4a05291612 --- /dev/null +++ b/docs/users_guide/runtime_control.rst @@ -0,0 +1,1070 @@ +.. _runtime-control: + +Running a compiled program +========================== + +.. index:: + single: runtime control of Haskell programs + single: running, compiled program + single: RTS options + +To make an executable program, the GHC system compiles your code and +then links it with a non-trivial runtime system (RTS), which handles +storage management, thread scheduling, profiling, and so on. + +The RTS has a lot of options to control its behaviour. For example, you +can change the context-switch interval, the default size of the heap, +and enable heap profiling. These options can be passed to the runtime +system in a variety of different ways; the next section +(:ref:`setting-rts-options`) describes the various methods, and the +following sections describe the RTS options themselves. + +.. _setting-rts-options: + +Setting RTS options +------------------- + +.. index:: + single: RTS options, setting + +There are four ways to set RTS options: + +- on the command line between ``+RTS ... -RTS``, when running the + program (:ref:`rts-opts-cmdline`) + +- at compile-time, using ``--with-rtsopts`` + (:ref:`rts-opts-compile-time`) + +- with the environment variable ``GHCRTS`` + (:ref:`rts-options-environment`) + +- by overriding "hooks" in the runtime system (:ref:`rts-hooks`) + +.. _rts-opts-cmdline: + +Setting RTS options on the command line +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: +RTS + single: -RTS + single: --RTS + +If you set the ``-rtsopts`` flag appropriately when linking (see +:ref:`options-linker`), you can give RTS options on the command line +when running your program. + +When your Haskell program starts up, the RTS extracts command-line +arguments bracketed between ``+RTS`` and ``-RTS`` as its own. For example: + +:: + + $ ghc prog.hs -rtsopts + [1 of 1] Compiling Main ( prog.hs, prog.o ) + Linking prog ... + $ ./prog -f +RTS -H32m -S -RTS -h foo bar + +The RTS will snaffle ``-H32m -S`` for itself, and the remaining +arguments ``-f -h foo bar`` will be available to your program if/when it +calls ``System.Environment.getArgs``. + +No ``-RTS`` option is required if the runtime-system options extend to +the end of the command line, as in this example: + +:: + + % hls -ltr /usr/etc +RTS -A5m + +If you absolutely positively want all the rest of the options in a +command line to go to the program (and not the RTS), use a +``--RTS``. + +As always, for RTS options that take ⟨size⟩s: If the last character of +⟨size⟩ is a K or k, multiply by 1000; if an M or m, by 1,000,000; if a G +or G, by 1,000,000,000. (And any wraparound in the counters is *your* +fault!) + +Giving a ``+RTS -?`` ``-?``\ RTS option option will print out the RTS +options actually available in your program (which vary, depending on how +you compiled). + +.. note:: + Since GHC is itself compiled by GHC, you can change RTS options in + the compiler using the normal ``+RTS ... -RTS`` combination. For instance, to set + the maximum heap size for a compilation to 128M, you would add + ``+RTS -M128m -RTS`` to the command line. + +.. _rts-opts-compile-time: + +Setting RTS options at compile time +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +GHC lets you change the default RTS options for a program at compile +time, using the ``-with-rtsopts`` flag (:ref:`options-linker`). A common +use for this is to give your program a default heap and/or stack size +that is greater than the default. For example, to set ``-H128m -K64m``, +link with ``-with-rtsopts="-H128m -K64m"``. + +.. _rts-options-environment: + +Setting RTS options with the ``GHCRTS`` environment variable +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: RTS options; from the environment + single: environment variable; for setting RTS options + single: GHCRTS environment variable + +If the ``-rtsopts`` flag is set to something other than ``none`` when +linking, RTS options are also taken from the environment variable +``GHCRTS``. For example, to set the maximum heap size to 2G +for all GHC-compiled programs (using an ``sh``\-like shell): + +:: + + GHCRTS='-M2G' + export GHCRTS + +RTS options taken from the ``GHCRTS`` environment variable can be +overridden by options given on the command line. + +.. tip:: + Setting something like ``GHCRTS=-M2G`` in your environment is a + handy way to avoid Haskell programs growing beyond the real memory in + your machine, which is easy to do by accident and can cause the machine + to slow to a crawl until the OS decides to kill the process (and you + hope it kills the right one). + +.. _rts-hooks: + +"Hooks" to change RTS behaviour +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: hooks; RTS + single: RTS hooks + single: RTS behaviour, changing + +GHC lets you exercise rudimentary control over certain RTS settings for +any given program, by compiling in a "hook" that is called by the +run-time system. The RTS contains stub definitions for these hooks, but +by writing your own version and linking it on the GHC command line, you +can override the defaults. + +Owing to the vagaries of DLL linking, these hooks don't work under +Windows when the program is built dynamically. + +You can change the messages printed when the runtime system "blows up," +e.g., on stack overflow. The hooks for these are as follows: + +``void OutOfHeapHook (unsigned long, unsigned long)`` + .. index:: + single: OutOfHeapHook + + The heap-overflow message. + +``void StackOverflowHook (long int)`` + .. index:: + single: StackOverflowHook + + The stack-overflow message. + +``void MallocFailHook (long int)`` + .. index:: + single: MallocFailHook + + The message printed if ``malloc`` fails. + +.. _rts-options-misc: + +Miscellaneous RTS options +------------------------- + +``-Vsecs`` + .. index:: + single: -V; RTS option + + Sets the interval that the RTS clock ticks at. The runtime uses a + single timer signal to count ticks; this timer signal is used to + control the context switch timer (:ref:`using-concurrent`) and the + heap profiling timer :ref:`rts-options-heap-prof`. Also, the time + profiler uses the RTS timer signal directly to record time profiling + samples. + + Normally, setting the ``-V`` option directly is not necessary: the + resolution of the RTS timer is adjusted automatically if a short + interval is requested with the ``-C`` or ``-i`` options. However, + setting ``-V`` is required in order to increase the resolution of + the time profiler. + + Using a value of zero disables the RTS clock completely, and has the + effect of disabling timers that depend on it: the context switch + timer and the heap profiling timer. Context switches will still + happen, but deterministically and at a rate much faster than normal. + Disabling the interval timer is useful for debugging, because it + eliminates a source of non-determinism at runtime. + +``--install-signal-handlers=yes|no`` + .. index:: + single: --install-signal-handlers; RTS option + + If yes (the default), the RTS installs signal handlers to catch + things like ctrl-C. This option is primarily useful for when you are + using the Haskell code as a DLL, and want to set your own signal + handlers. + + Note that even with ``--install-signal-handlers=no``, the RTS + interval timer signal is still enabled. The timer signal is either + SIGVTALRM or SIGALRM, depending on the RTS configuration and OS + capabilities. To disable the timer signal, use the ``-V0`` RTS + option (see above). + +``-xmaddress`` + .. index:: + single: -xm; RTS option + + WARNING: this option is for working around memory allocation + problems only. Do not use unless GHCi fails with a message like + “\ ``failed to mmap() memory below 2Gb``\ ”. If you need to use this + option to get GHCi working on your machine, please file a bug. + + On 64-bit machines, the RTS needs to allocate memory in the low 2Gb + of the address space. Support for this across different operating + systems is patchy, and sometimes fails. This option is there to give + the RTS a hint about where it should be able to allocate memory in + the low 2Gb of the address space. For example, + ``+RTS -xm20000000 -RTS`` would hint that the RTS should allocate + starting at the 0.5Gb mark. The default is to use the OS's built-in + support for allocating memory in the low 2Gb if available (e.g. + ``mmap`` with ``MAP_32BIT`` on Linux), or otherwise ``-xm40000000``. + +``-xqsize`` + .. index:: + single: -xq; RTS option + + [Default: 100k] This option relates to allocation limits; for more + about this see + :base-ref:`enableAllocationLimit <GHC-Conc.html#v%3AenableAllocationLimit>`. + When a thread hits its allocation limit, the RTS throws an exception + to the thread, and the thread gets an additional quota of allocation + before the exception is raised again, the idea being so that the + thread can execute its exception handlers. The ``-xq`` controls the + size of this additional quota. + +.. _rts-options-gc: + +RTS options to control the garbage collector +-------------------------------------------- + +.. index:: + single: garbage collector; options + single: RTS options; garbage collection + +There are several options to give you precise control over garbage +collection. Hopefully, you won't need any of these in normal operation, +but there are several things that can be tweaked for maximum +performance. + +``-A ⟨size⟩`` + .. index:: + single: -A; RTS option + single: allocation area, size + + [Default: 512k] Set the allocation area size used by the garbage + collector. The allocation area (actually generation 0 step 0) is + fixed and is never resized (unless you use ``-H``, below). + + Increasing the allocation area size may or may not give better + performance (a bigger allocation area means worse cache behaviour + but fewer garbage collections and less promotion). + + With only 1 generation (``-G1``) the ``-A`` option specifies the + minimum allocation area, since the actual size of the allocation + area will be resized according to the amount of data in the heap + (see ``-F``, below). + +``-O ⟨size⟩`` + .. index:: + single: -O; RTS option + single: old generation, size + + [Default: 1m] Set the minimum size of the old generation. The old + generation is collected whenever it grows to this size or the value + of the ``-F`` option multiplied by the size of the live data at the + previous major collection, whichever is larger. + +``-n ⟨size⟩`` + .. index:: + single: -n; RTS option + + .. index:: + single: allocation area, chunk size + + [Default: 0, Example: ``-n4m``\ ] When set to a non-zero value, this + option divides the allocation area (``-A`` value) into chunks of the + specified size. During execution, when a processor exhausts its + current chunk, it is given another chunk from the pool until the + pool is exhausted, at which point a collection is triggered. + + This option is only useful when running in parallel (``-N2`` or + greater). It allows the processor cores to make better use of the + available allocation area, even when cores are allocating at + different rates. Without ``-n``, each core gets a fixed-size + allocation area specified by the ``-A``, and the first core to + exhaust its allocation area triggers a GC across all the cores. This + can result in a collection happening when the allocation areas of + some cores are only partially full, so the purpose of the ``-n`` is + to allow cores that are allocating faster to get more of the + allocation area. This means less frequent GC, leading a lower GC + overhead for the same heap size. + + This is particularly useful in conjunction with larger ``-A`` + values, for example ``-A64m -n4m`` is a useful combination on larger core + counts (8+). + +``-c`` + .. index:: + single: -c; RTS option + + .. index:: + single: garbage collection; compacting + + .. index:: + single: compacting garbage collection + + Use a compacting algorithm for collecting the oldest generation. By + default, the oldest generation is collected using a copying + algorithm; this option causes it to be compacted in-place instead. + The compaction algorithm is slower than the copying algorithm, but + the savings in memory use can be considerable. + + For a given heap size (using the ``-H`` option), compaction can in + fact reduce the GC cost by allowing fewer GCs to be performed. This + is more likely when the ratio of live data to heap size is high, say + greater than 30%. + + .. note:: + Compaction doesn't currently work when a single generation is + requested using the ``-G1`` option. + +``-c ⟨n⟩`` + [Default: 30] Automatically enable compacting collection when the + live data exceeds ⟨n⟩% of the maximum heap size (see the ``-M`` + option). Note that the maximum heap size is unlimited by default, so + this option has no effect unless the maximum heap size is set with + ``-M ⟨size⟩.`` + +``-F ⟨factor⟩`` + .. index:: + single: -F; RTS option + single: heap size, factor + + [Default: 2] This option controls the amount of memory reserved for + the older generations (and in the case of a two space collector the + size of the allocation area) as a factor of the amount of live data. + For example, if there was 2M of live data in the oldest generation + when we last collected it, then by default we'll wait until it grows + to 4M before collecting it again. + + The default seems to work well here. If you have plenty of memory, + it is usually better to use ``-H ⟨size⟩`` than to increase + ``-F ⟨factor⟩.`` + + The ``-F`` setting will be automatically reduced by the garbage + collector when the maximum heap size (the ``-M ⟨size⟩`` setting) is + approaching. + +``-G ⟨generations⟩`` + .. index:: + single: -G; RTS option + single: generations, number of + + [Default: 2] Set the number of generations used by the garbage + collector. The default of 2 seems to be good, but the garbage + collector can support any number of generations. Anything larger + than about 4 is probably not a good idea unless your program runs + for a *long* time, because the oldest generation will hardly ever + get collected. + + Specifying 1 generation with ``+RTS -G1`` gives you a simple 2-space + collector, as you would expect. In a 2-space collector, the ``-A`` + option (see above) specifies the *minimum* allocation area size, + since the allocation area will grow with the amount of live data in + the heap. In a multi-generational collector the allocation area is a + fixed size (unless you use the ``-H`` option, see below). + +``-qggen`` + .. index:: + single: -qg; RTS option + + [New in GHC 6.12.1] [Default: 0] Use parallel GC in generation ⟨gen⟩ + and higher. Omitting ⟨gen⟩ turns off the parallel GC completely, + reverting to sequential GC. + + The default parallel GC settings are usually suitable for parallel + programs (i.e. those using ``par``, Strategies, or with multiple + threads). However, it is sometimes beneficial to enable the parallel + GC for a single-threaded sequential program too, especially if the + program has a large amount of heap data and GC is a significant + fraction of runtime. To use the parallel GC in a sequential program, + enable the parallel runtime with a suitable ``-N`` option, and + additionally it might be beneficial to restrict parallel GC to the + old generation with ``-qg1``. + +``-qbgen`` + .. index:: + single: -qb; RTS option + + [New in GHC 6.12.1] [Default: 1] Use load-balancing in the parallel + GC in generation ⟨gen⟩ and higher. Omitting ⟨gen⟩ disables + load-balancing entirely. + + Load-balancing shares out the work of GC between the available + cores. This is a good idea when the heap is large and we need to + parallelise the GC work, however it is also pessimal for the short + young-generation collections in a parallel program, because it can + harm locality by moving data from the cache of the CPU where is it + being used to the cache of another CPU. Hence the default is to do + load-balancing only in the old-generation. In fact, for a parallel + program it is sometimes beneficial to disable load-balancing + entirely with ``-qb``. + +``-H [⟨size⟩]`` + .. index:: + single: -H; RTS option + single: heap size, suggested + + [Default: 0] This option provides a “suggested heap size” for the + garbage collector. Think of ``-Hsize`` as a variable ``-A`` option. + It says: I want to use at least ⟨size⟩ bytes, so use whatever is + left over to increase the ``-A`` value. + + This option does not put a *limit* on the heap size: the heap may + grow beyond the given size as usual. + + If ⟨size⟩ is omitted, then the garbage collector will take the size + of the heap at the previous GC as the ⟨size⟩. This has the effect of + allowing for a larger ``-A`` value but without increasing the + overall memory requirements of the program. It can be useful when + the default small ``-A`` value is suboptimal, as it can be in + programs that create large amounts of long-lived data. + +``-I ⟨seconds⟩`` + .. index:: + single: -I; RTS option + single: idle GC + + (default: 0.3) In the threaded and SMP versions of the RTS (see + ``-threaded``, :ref:`options-linker`), a major GC is automatically + performed if the runtime has been idle (no Haskell computation has + been running) for a period of time. The amount of idle time which + must pass before a GC is performed is set by the ``-I ⟨seconds⟩`` + option. Specifying ``-I0`` disables the idle GC. + + For an interactive application, it is probably a good idea to use + the idle GC, because this will allow finalizers to run and + deadlocked threads to be detected in the idle time when no Haskell + computation is happening. Also, it will mean that a GC is less + likely to happen when the application is busy, and so responsiveness + may be improved. However, if the amount of live data in the heap is + particularly large, then the idle GC can cause a significant delay, + and too small an interval could adversely affect interactive + responsiveness. + + This is an experimental feature, please let us know if it causes + problems and/or could benefit from further tuning. + +``-ki ⟨size⟩`` + .. index:: + single: -k; RTS option + single: stack, initial size + + [Default: 1k] Set the initial stack size for new threads. + + Thread stacks (including the main thread's stack) live on the heap. + As the stack grows, new stack chunks are added as required; if the + stack shrinks again, these extra stack chunks are reclaimed by the + garbage collector. The default initial stack size is deliberately + small, in order to keep the time and space overhead for thread + creation to a minimum, and to make it practical to spawn threads for + even tiny pieces of work. + + .. note:: + This flag used to be simply ``-k``, but was renamed to ``-ki`` in + GHC 7.2.1. The old name is still accepted for backwards + compatibility, but that may be removed in a future version. + +``-kc ⟨size⟩`` + .. index:: + single: -kc; RTS option + single: stack; chunk size + + [Default: 32k] Set the size of “stack chunks”. When a thread's + current stack overflows, a new stack chunk is created and added to + the thread's stack, until the limit set by ``-K`` is reached. + + The advantage of smaller stack chunks is that the garbage collector + can avoid traversing stack chunks if they are known to be unmodified + since the last collection, so reducing the chunk size means that the + garbage collector can identify more stack as unmodified, and the GC + overhead might be reduced. On the other hand, making stack chunks + too small adds some overhead as there will be more + overflow/underflow between chunks. The default setting of 32k + appears to be a reasonable compromise in most cases. + +``-kb ⟨size⟩`` + .. index:: + single: -kc; RTS option + single: stack; chunk buffer size + + [Default: 1k] Sets the stack chunk buffer size. When a stack chunk + overflows and a new stack chunk is created, some of the data from + the previous stack chunk is moved into the new chunk, to avoid an + immediate underflow and repeated overflow/underflow at the boundary. + The amount of stack moved is set by the ``-kb`` option. + + Note that to avoid wasting space, this value should typically be + less than 10% of the size of a stack chunk (``-kc``), because in a + chain of stack chunks, each chunk will have a gap of unused space of + this size. + +``-K ⟨size⟩`` + .. index:: + single: -K; RTS option + single: stack, maximum size + + [Default: 80% physical memory size] Set the maximum stack size for + an individual thread to ⟨size⟩ bytes. If the thread attempts to + exceed this limit, it will be sent the ``StackOverflow`` exception. + The limit can be disabled entirely by specifying a size of zero. + + This option is there mainly to stop the program eating up all the + available memory in the machine if it gets into an infinite loop. + +``-m ⟨n⟩`` + .. index:: + single: -m; RTS option + single: heap, minimum free + + Minimum % ⟨n⟩ of heap which must be available for allocation. The + default is 3%. + +``-M ⟨size⟩`` + .. index:: + single: -M; RTS option + single: heap size, maximum + + [Default: unlimited] Set the maximum heap size to ⟨size⟩ bytes. The + heap normally grows and shrinks according to the memory requirements + of the program. The only reason for having this option is to stop + the heap growing without bound and filling up all the available swap + space, which at the least will result in the program being summarily + killed by the operating system. + + The maximum heap size also affects other garbage collection + parameters: when the amount of live data in the heap exceeds a + certain fraction of the maximum heap size, compacting collection + will be automatically enabled for the oldest generation, and the + ``-F`` parameter will be reduced in order to avoid exceeding the + maximum heap size. + +.. _rts-options-statistics: + +RTS options to produce runtime statistics +----------------------------------------- + +``-T``, ``-t [⟨file⟩]``, ``-s [⟨file⟩]``, ``-S [⟨file⟩]``, ``--machine-readable`` + .. index:: + single: -T; RTS option + single: -t; RTS option + single: -s; RTS option + single: -S; RTS option + single: --machine-readable; RTS option + + These options produce runtime-system statistics, such as the amount + of time spent executing the program and in the garbage collector, + the amount of memory allocated, the maximum size of the heap, and so + on. The three variants give different levels of detail: ``-T`` + collects the data but produces no output ``-t`` produces a single + line of output in the same format as GHC's ``-Rghc-timing`` option, + ``-s`` produces a more detailed summary at the end of the program, + and ``-S`` additionally produces information about each and every + garbage collection. + + The output is placed in ⟨file⟩. If ⟨file⟩ is omitted, then the + output is sent to ``stderr``. + + If you use the ``-T`` flag then, you should access the statistics + using :base-ref:`GHC.Stats <GHC-Stats.html>`. + + If you use the ``-t`` flag then, when your program finishes, you + will see something like this: + + :: + + <<ghc: 36169392 bytes, 69 GCs, 603392/1065272 avg/max bytes residency (2 samples), 3M in use, 0.00 INIT (0.00 elapsed), 0.02 MUT (0.02 elapsed), 0.07 GC (0.07 elapsed) :ghc>> + + This tells you: + + - The total number of bytes allocated by the program over the whole + run. + + - The total number of garbage collections performed. + + - The average and maximum "residency", which is the amount of live + data in bytes. The runtime can only determine the amount of live + data during a major GC, which is why the number of samples + corresponds to the number of major GCs (and is usually relatively + small). To get a better picture of the heap profile of your + program, use the ``-hT`` RTS option (:ref:`rts-profiling`). + + - The peak memory the RTS has allocated from the OS. + + - The amount of CPU time and elapsed wall clock time while + initialising the runtime system (INIT), running the program + itself (MUT, the mutator), and garbage collecting (GC). + + You can also get this in a more future-proof, machine readable + format, with ``-t --machine-readable``: + + :: + + [("bytes allocated", "36169392") + ,("num_GCs", "69") + ,("average_bytes_used", "603392") + ,("max_bytes_used", "1065272") + ,("num_byte_usage_samples", "2") + ,("peak_megabytes_allocated", "3") + ,("init_cpu_seconds", "0.00") + ,("init_wall_seconds", "0.00") + ,("mutator_cpu_seconds", "0.02") + ,("mutator_wall_seconds", "0.02") + ,("GC_cpu_seconds", "0.07") + ,("GC_wall_seconds", "0.07") + ] + + If you use the ``-s`` flag then, when your program finishes, you + will see something like this (the exact details will vary depending + on what sort of RTS you have, e.g. you will only see profiling data + if your RTS is compiled for profiling): + + :: + + 36,169,392 bytes allocated in the heap + 4,057,632 bytes copied during GC + 1,065,272 bytes maximum residency (2 sample(s)) + 54,312 bytes maximum slop + 3 MB total memory in use (0 MB lost due to fragmentation) + + Generation 0: 67 collections, 0 parallel, 0.04s, 0.03s elapsed + Generation 1: 2 collections, 0 parallel, 0.03s, 0.04s elapsed + + SPARKS: 359207 (557 converted, 149591 pruned) + + INIT time 0.00s ( 0.00s elapsed) + MUT time 0.01s ( 0.02s elapsed) + GC time 0.07s ( 0.07s elapsed) + EXIT time 0.00s ( 0.00s elapsed) + Total time 0.08s ( 0.09s elapsed) + + %GC time 89.5% (75.3% elapsed) + + Alloc rate 4,520,608,923 bytes per MUT second + + Productivity 10.5% of total user, 9.1% of total elapsed + + - The "bytes allocated in the heap" is the total bytes allocated by + the program over the whole run. + + - GHC uses a copying garbage collector by default. "bytes copied + during GC" tells you how many bytes it had to copy during garbage + collection. + + - The maximum space actually used by your program is the "bytes + maximum residency" figure. This is only checked during major + garbage collections, so it is only an approximation; the number + of samples tells you how many times it is checked. + + - The "bytes maximum slop" tells you the most space that is ever + wasted due to the way GHC allocates memory in blocks. Slop is + memory at the end of a block that was wasted. There's no way to + control this; we just like to see how much memory is being lost + this way. + + - The "total memory in use" tells you the peak memory the RTS has + allocated from the OS. + + - Next there is information about the garbage collections done. For + each generation it says how many garbage collections were done, + how many of those collections were done in parallel, the total + CPU time used for garbage collecting that generation, and the + total wall clock time elapsed while garbage collecting that + generation. + + - The ``SPARKS`` statistic refers to the use of + ``Control.Parallel.par`` and related functionality in the + program. Each spark represents a call to ``par``; a spark is + "converted" when it is executed in parallel; and a spark is + "pruned" when it is found to be already evaluated and is + discarded from the pool by the garbage collector. Any remaining + sparks are discarded at the end of execution, so "converted" plus + "pruned" does not necessarily add up to the total. + + - Next there is the CPU time and wall clock time elapsed broken + down by what the runtime system was doing at the time. INIT is + the runtime system initialisation. MUT is the mutator time, i.e. + the time spent actually running your code. GC is the time spent + doing garbage collection. RP is the time spent doing retainer + profiling. PROF is the time spent doing other profiling. EXIT is + the runtime system shutdown time. And finally, Total is, of + course, the total. + + %GC time tells you what percentage GC is of Total. "Alloc rate" + tells you the "bytes allocated in the heap" divided by the MUT + CPU time. "Productivity" tells you what percentage of the Total + CPU and wall clock elapsed times are spent in the mutator (MUT). + + The ``-S`` flag, as well as giving the same output as the ``-s`` + flag, prints information about each GC as it happens: + + :: + + Alloc Copied Live GC GC TOT TOT Page Flts + bytes bytes bytes user elap user elap + 528496 47728 141512 0.01 0.02 0.02 0.02 0 0 (Gen: 1) + [...] + 524944 175944 1726384 0.00 0.00 0.08 0.11 0 0 (Gen: 0) + + For each garbage collection, we print: + + - How many bytes we allocated this garbage collection. + + - How many bytes we copied this garbage collection. + + - How many bytes are currently live. + + - How long this garbage collection took (CPU time and elapsed wall + clock time). + + - How long the program has been running (CPU time and elapsed wall + clock time). + + - How many page faults occurred this garbage collection. + + - How many page faults occurred since the end of the last garbage + collection. + + - Which generation is being garbage collected. + +RTS options for concurrency and parallelism +------------------------------------------- + +The RTS options related to concurrency are described in +:ref:`using-concurrent`, and those for parallelism in +:ref:`parallel-options`. + +.. _rts-profiling: + +RTS options for profiling +------------------------- + +Most profiling runtime options are only available when you compile your +program for profiling (see :ref:`prof-compiler-options`, and +:ref:`rts-options-heap-prof` for the runtime options). However, there is +one profiling option that is available for ordinary non-profiled +executables: + +``-hT`` + .. index:: + single: -hT; RTS option + + (can be shortened to ``-h``.) Generates a basic heap profile, in the + file ``prog.hp``. To produce the heap profile graph, use ``hp2ps`` + (see :ref:`hp2ps`). The basic heap profile is broken down by data + constructor, with other types of closures (functions, thunks, etc.) + grouped into broad categories (e.g. ``FUN``, ``THUNK``). To get a + more detailed profile, use the full profiling support + (:ref:`profiling`). + +.. _rts-eventlog: + +Tracing +------- + +.. index:: + single: tracing + single: events + single: eventlog files + +When the program is linked with the ``-eventlog`` option +(:ref:`options-linker`), runtime events can be logged in two ways: + +- In binary format to a file for later analysis by a variety of tools. + One such tool is + `ThreadScope <http://www.haskell.org/haskellwiki/ThreadScope>`__\ ThreadScope, + which interprets the event log to produce a visual parallel execution + profile of the program. + +- As text to standard output, for debugging purposes. + +``-lflags`` + .. index:: + single: -l; RTS option + + Log events in binary format to the file ``program.eventlog``. + Without any ⟨flags⟩ specified, this logs a default set of events, + suitable for use with tools like ThreadScope. + + For some special use cases you may want more control over which + events are included. The ⟨flags⟩ is a sequence of zero or more + characters indicating which classes of events to log. Currently + these the classes of events that can be enabled/disabled: + + - ``s`` — scheduler events, including Haskell thread creation and start/stop + events. Enabled by default. + + - ``g`` — GC events, including GC start/stop. Enabled by default. + + - ``p`` — parallel sparks (sampled). Enabled by default. + + - ``f`` — parallel sparks (fully accurate). Disabled by default. + + - ``u`` — user events. These are events emitted from Haskell code using + functions such as ``Debug.Trace.traceEvent``. Enabled by default. + + You can disable specific classes, or enable/disable all classes at + once: + + - ``a`` — enable all event classes listed above + - ``-⟨x⟩`` — disable the given class of events, for any event class listed above + - ``-a`` — disable all classes + + For example, ``-l-ag`` would disable all event classes (``-a``) except for + GC events (``g``). + + For spark events there are two modes: sampled and fully accurate. + There are various events in the life cycle of each spark, usually + just creating and running, but there are some more exceptional + possibilities. In the sampled mode the number of occurrences of each + kind of spark event is sampled at frequent intervals. In the fully + accurate mode every spark event is logged individually. The latter + has a higher runtime overhead and is not enabled by default. + + The format of the log file is described by the header + ``EventLogFormat.h`` that comes with GHC, and it can be parsed in + Haskell using the + `ghc-events <http://hackage.haskell.org/package/ghc-events>`__ + library. To dump the contents of a ``.eventlog`` file as text, use + the tool ``ghc-events show`` that comes with the + `ghc-events <http://hackage.haskell.org/package/ghc-events>`__ + package. + +``-v [⟨flags⟩]`` + .. index:: + single: -v; RTS option + + Log events as text to standard output, instead of to the + ``.eventlog`` file. The ⟨flags⟩ are the same as for ``-l``, with the + additional option ``t`` which indicates that the each event printed + should be preceded by a timestamp value (in the binary ``.eventlog`` + file, all events are automatically associated with a timestamp). + +The debugging options ``-Dx`` also generate events which are logged +using the tracing framework. By default those events are dumped as text +to stdout (``-Dx`` implies ``-v``), but they may instead be stored in +the binary eventlog file by using the ``-l`` option. + +.. _rts-options-debugging: + +RTS options for hackers, debuggers, and over-interested souls +------------------------------------------------------------- + +.. index:: + single: RTS options, hacking/debugging + +These RTS options might be used (a) to avoid a GHC bug, (b) to see +"what's really happening", or (c) because you feel like it. Not +recommended for everyday use! + +``-B`` + .. index:: + single: -B; RTS option + + Sound the bell at the start of each (major) garbage collection. + + Oddly enough, people really do use this option! Our pal in Durham + (England), Paul Callaghan, writes: “Some people here use it for a + variety of purposes—honestly!—e.g., confirmation that the + code/machine is doing something, infinite loop detection, gauging + cost of recently added code. Certain people can even tell what stage + [the program] is in by the beep pattern. But the major use is for + annoying others in the same office…” + +``-D ⟨x⟩`` + .. index:: + single: -D; RTS option + + An RTS debugging flag; only available if the program was linked with + the ``-debug`` option. Various values of ⟨x⟩ are provided to enable + debug messages and additional runtime sanity checks in different + subsystems in the RTS, for example ``+RTS -Ds -RTS`` enables debug + messages from the scheduler. Use ``+RTS -?`` to find out which debug + flags are supported. + + Debug messages will be sent to the binary event log file instead of + stdout if the ``-l`` option is added. This might be useful for + reducing the overhead of debug tracing. + +``-r ⟨file⟩`` + .. index:: + single: -r; RTS option + single: ticky ticky profiling + single: profiling; ticky ticky + + Produce "ticky-ticky" statistics at the end of the program run (only + available if the program was linked with ``-debug``). The ⟨file⟩ + business works just like on the ``-S`` RTS option, above. + + For more information on ticky-ticky profiling, see + :ref:`ticky-ticky`. + +``-xc`` + .. index:: + single: -xc; RTS option + + (Only available when the program is compiled for profiling.) When an + exception is raised in the program, this option causes a stack trace + to be dumped to ``stderr``. + + This can be particularly useful for debugging: if your program is + complaining about a ``head []`` error and you haven't got a clue + which bit of code is causing it, compiling with + ``-prof -fprof-auto`` and running with ``+RTS -xc -RTS`` will tell + you exactly the call stack at the point the error was raised. + + The output contains one report for each exception raised in the + program (the program might raise and catch several exceptions during + its execution), where each report looks something like this: + + :: + + *** Exception raised (reporting due to +RTS -xc), stack trace: + GHC.List.CAF + --> evaluated by: Main.polynomial.table_search, + called from Main.polynomial.theta_index, + called from Main.polynomial, + called from Main.zonal_pressure, + called from Main.make_pressure.p, + called from Main.make_pressure, + called from Main.compute_initial_state.p, + called from Main.compute_initial_state, + called from Main.CAF + ... + + The stack trace may often begin with something uninformative like + ``GHC.List.CAF``; this is an artifact of GHC's optimiser, which + lifts out exceptions to the top-level where the profiling system + assigns them to the cost centre "CAF". However, ``+RTS -xc`` doesn't + just print the current stack, it looks deeper and reports the stack + at the time the CAF was evaluated, and it may report further stacks + until a non-CAF stack is found. In the example above, the next stack + (after ``--> evaluated by``) contains plenty of information about + what the program was doing when it evaluated ``head []``. + + Implementation details aside, the function names in the stack should + hopefully give you enough clues to track down the bug. + + See also the function ``traceStack`` in the module ``Debug.Trace`` + for another way to view call stacks. + +``-Z`` + .. index:: + single: -Z; RTS option + + Turn *off* "update-frame squeezing" at garbage-collection time. + (There's no particularly good reason to turn it off, except to + ensure the accuracy of certain data collected regarding thunk entry + counts.) + +.. _ghc-info: + +Getting information about the RTS +--------------------------------- + +.. index:: + single: RTS + +It is possible to ask the RTS to give some information about itself. To +do this, use the ``--info`` flag, e.g. + +:: + + $ ./a.out +RTS --info + [("GHC RTS", "YES") + ,("GHC version", "6.7") + ,("RTS way", "rts_p") + ,("Host platform", "x86_64-unknown-linux") + ,("Host architecture", "x86_64") + ,("Host OS", "linux") + ,("Host vendor", "unknown") + ,("Build platform", "x86_64-unknown-linux") + ,("Build architecture", "x86_64") + ,("Build OS", "linux") + ,("Build vendor", "unknown") + ,("Target platform", "x86_64-unknown-linux") + ,("Target architecture", "x86_64") + ,("Target OS", "linux") + ,("Target vendor", "unknown") + ,("Word size", "64") + ,("Compiler unregisterised", "NO") + ,("Tables next to code", "YES") + ] + +The information is formatted such that it can be read as a of type +``[(String, String)]``. Currently the following fields are present: + +``GHC RTS`` + Is this program linked against the GHC RTS? (always "YES"). + +``GHC version`` + The version of GHC used to compile this program. + +``RTS way`` + The variant (“way”) of the runtime. The most common values are + ``rts_v`` (vanilla), ``rts_thr`` (threaded runtime, i.e. linked + using the ``-threaded`` option) and ``rts_p`` (profiling runtime, + i.e. linked using the ``-prof`` option). Other variants include + ``debug`` (linked using ``-debug``), and ``dyn`` (the RTS is linked + in dynamically, i.e. a shared library, rather than statically linked + into the executable itself). These can be combined, e.g. you might + have ``rts_thr_debug_p``. + +``Target platform``\ ``Target architecture``\ ``Target OS``\ ``Target vendor`` + These are the platform the program is compiled to run on. + +``Build platform``\ ``Build architecture``\ ``Build OS``\ ``Build vendor`` + These are the platform where the program was built on. (That is, the + target platform of GHC itself.) Ordinarily this is identical to the + target platform. (It could potentially be different if + cross-compiling.) + +``Host platform``\ ``Host architecture``\ ``Host OS``\ ``Host vendor`` + These are the platform where GHC itself was compiled. Again, this + would normally be identical to the build and target platforms. + +``Word size`` + Either ``"32"`` or ``"64"``, reflecting the word size of the target + platform. + +``Compiler unregistered`` + Was this program compiled with an :ref:`"unregistered" <unreg>` + version of GHC? (I.e., a version of GHC that has no + platform-specific optimisations compiled in, usually because this is + a currently unsupported platform.) This value will usually be no, + unless you're using an experimental build of GHC. + +``Tables next to code`` + Putting info tables directly next to entry code is a useful + performance optimisation that is not available on all platforms. + This field tells you whether the program has been compiled with this + optimisation. (Usually yes, except on unusual platforms.) diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml deleted file mode 100644 index b23f79fabf..0000000000 --- a/docs/users_guide/runtime_control.xml +++ /dev/null @@ -1,1605 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<sect1 id="runtime-control"> - <title>Running a compiled program</title> - - <indexterm><primary>runtime control of Haskell programs</primary></indexterm> - <indexterm><primary>running, compiled program</primary></indexterm> - <indexterm><primary>RTS options</primary></indexterm> - - <para>To make an executable program, the GHC system compiles your - code and then links it with a non-trivial runtime system (RTS), - which handles storage management, thread scheduling, profiling, and - so on.</para> - - <para> - The RTS has a lot of options to control its behaviour. For - example, you can change the context-switch interval, the default - size of the heap, and enable heap profiling. These options can be - passed to the runtime system in a variety of different ways; the - next section (<xref linkend="setting-rts-options" />) describes - the various methods, and the following sections describe the RTS - options themselves. - </para> - - <sect2 id="setting-rts-options"> - <title>Setting RTS options</title> - <indexterm><primary>RTS options, setting</primary></indexterm> - - <para> - There are four ways to set RTS options: - - <itemizedlist> - <listitem> - <para> - on the command line between <literal>+RTS ... -RTS</literal>, when running the program - (<xref linkend="rts-opts-cmdline" />) - </para> - </listitem> - <listitem> - <para>at compile-time, using <option>--with-rtsopts</option> - (<xref linkend="rts-opts-compile-time" />) - </para> - </listitem> - <listitem> - <para>with the environment variable <envar>GHCRTS</envar> - (<xref linkend="rts-options-environment" />) - </para> - </listitem> - <listitem> - <para>by overriding “hooks” in the runtime system - (<xref linkend="rts-hooks" />) - </para> - </listitem> - </itemizedlist> - </para> - - <sect3 id="rts-opts-cmdline"> - <title>Setting RTS options on the command line</title> - - <para> - If you set the <literal>-rtsopts</literal> flag appropriately - when linking (see <xref linkend="options-linker" />), you can - give RTS options on the command line when running your - program. - </para> - - <para> - When your Haskell program starts up, the RTS extracts - command-line arguments bracketed between - <option>+RTS</option><indexterm><primary><option>+RTS</option></primary></indexterm> - and - <option>-RTS</option><indexterm><primary><option>-RTS</option></primary></indexterm> - as its own. For example: - </para> - -<screen> -$ ghc prog.hs -rtsopts -[1 of 1] Compiling Main ( prog.hs, prog.o ) -Linking prog ... -$ ./prog -f +RTS -H32m -S -RTS -h foo bar -</screen> - - <para> - The RTS will - snaffle <option>-H32m</option> <option>-S</option> for itself, - and the remaining arguments <literal>-f -h foo bar</literal> - will be available to your program if/when it calls - <function>System.Environment.getArgs</function>. - </para> - - <para> - No <option>-RTS</option> option is required if the - runtime-system options extend to the end of the command line, as in - this example: - </para> - -<screen> -% hls -ltr /usr/etc +RTS -A5m -</screen> - - <para> - If you absolutely positively want all the rest of the options - in a command line to go to the program (and not the RTS), use a - <option>--RTS</option><indexterm><primary><option>--RTS</option></primary></indexterm>. - </para> - - <para> - As always, for RTS options that take - <replaceable>size</replaceable>s: If the last character of - <replaceable>size</replaceable> is a K or k, multiply by 1000; if an - M or m, by 1,000,000; if a G or G, by 1,000,000,000. (And any - wraparound in the counters is <emphasis>your</emphasis> - fault!) - </para> - - <para> - Giving a <literal>+RTS -?</literal> - <indexterm><primary><option>-?</option></primary><secondary>RTS option</secondary></indexterm> option - will print out the RTS options actually available in your program - (which vary, depending on how you compiled).</para> - - <para> - NOTE: since GHC is itself compiled by GHC, you can change RTS - options in the compiler using the normal - <literal>+RTS ... -RTS</literal> - combination. eg. to set the maximum heap - size for a compilation to 128M, you would add - <literal>+RTS -M128m -RTS</literal> - to the command line. - </para> - </sect3> - - <sect3 id="rts-opts-compile-time"> - <title>Setting RTS options at compile time</title> - - <para> - GHC lets you change the default RTS options for a program at - compile time, using the <literal>-with-rtsopts</literal> - flag (<xref linkend="options-linker" />). A common use for this is - to give your program a default heap and/or stack size that is - greater than the default. For example, to set <literal>-H128m - -K64m</literal>, link - with <literal>-with-rtsopts="-H128m -K64m"</literal>. - </para> - </sect3> - - <sect3 id="rts-options-environment"> - <title>Setting RTS options with the <envar>GHCRTS</envar> - environment variable</title> - - <indexterm><primary>RTS options</primary><secondary>from the environment</secondary></indexterm> - <indexterm><primary>environment variable</primary><secondary>for - setting RTS options</secondary></indexterm> - - <para> - If the <literal>-rtsopts</literal> flag is set to - something other than <literal>none</literal> when linking, - RTS options are also taken from the environment variable - <envar>GHCRTS</envar><indexterm><primary><envar>GHCRTS</envar></primary> - </indexterm>. For example, to set the maximum heap size - to 2G for all GHC-compiled programs (using an - <literal>sh</literal>-like shell): - </para> - -<screen> - GHCRTS='-M2G' - export GHCRTS -</screen> - - <para> - RTS options taken from the <envar>GHCRTS</envar> environment - variable can be overridden by options given on the command - line. - </para> - - <para> - Tip: setting something like <literal>GHCRTS=-M2G</literal> - in your environment is a handy way to avoid Haskell programs - growing beyond the real memory in your machine, which is - easy to do by accident and can cause the machine to slow to - a crawl until the OS decides to kill the process (and you - hope it kills the right one). - </para> - </sect3> - - <sect3 id="rts-hooks"> - <title>“Hooks” to change RTS behaviour</title> - - <indexterm><primary>hooks</primary><secondary>RTS</secondary></indexterm> - <indexterm><primary>RTS hooks</primary></indexterm> - <indexterm><primary>RTS behaviour, changing</primary></indexterm> - - <para>GHC lets you exercise rudimentary control over certain RTS - settings for any given program, by compiling in a - “hook” that is called by the run-time system. The RTS - contains stub definitions for these hooks, but by writing your - own version and linking it on the GHC command line, you can - override the defaults.</para> - - <para>Owing to the vagaries of DLL linking, these hooks don't work - under Windows when the program is built dynamically.</para> - - <para>You can change the messages printed when the runtime - system “blows up,” e.g., on stack overflow. The hooks - for these are as follows:</para> - - <variablelist> - - <varlistentry> - <term> - <function>void OutOfHeapHook (unsigned long, unsigned long)</function> - <indexterm><primary><function>OutOfHeapHook</function></primary></indexterm> - </term> - <listitem> - <para>The heap-overflow message.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <function>void StackOverflowHook (long int)</function> - <indexterm><primary><function>StackOverflowHook</function></primary></indexterm> - </term> - <listitem> - <para>The stack-overflow message.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <function>void MallocFailHook (long int)</function> - <indexterm><primary><function>MallocFailHook</function></primary></indexterm> - </term> - <listitem> - <para>The message printed if <function>malloc</function> - fails.</para> - </listitem> - </varlistentry> - </variablelist> - </sect3> - - </sect2> - - <sect2 id="rts-options-misc"> - <title>Miscellaneous RTS options</title> - - <variablelist> - <varlistentry> - <term><option>-V<replaceable>secs</replaceable></option> - <indexterm><primary><option>-V</option></primary><secondary>RTS - option</secondary></indexterm></term> - <listitem> - <para>Sets the interval that the RTS clock ticks at. The - runtime uses a single timer signal to count ticks; this timer - signal is used to control the context switch timer (<xref - linkend="using-concurrent" />) and the heap profiling - timer <xref linkend="rts-options-heap-prof" />. Also, the - time profiler uses the RTS timer signal directly to record - time profiling samples.</para> - - <para>Normally, setting the <option>-V</option> option - directly is not necessary: the resolution of the RTS timer is - adjusted automatically if a short interval is requested with - the <option>-C</option> or <option>-i</option> options. - However, setting <option>-V</option> is required in order to - increase the resolution of the time profiler.</para> - - <para>Using a value of zero disables the RTS clock - completely, and has the effect of disabling timers that - depend on it: the context switch timer and the heap profiling - timer. Context switches will still happen, but - deterministically and at a rate much faster than normal. - Disabling the interval timer is useful for debugging, because - it eliminates a source of non-determinism at runtime.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--install-signal-handlers=<replaceable>yes|no</replaceable></option> - <indexterm><primary><option>--install-signal-handlers</option></primary><secondary>RTS - option</secondary></indexterm></term> - <listitem> - <para>If yes (the default), the RTS installs signal handlers to catch - things like ctrl-C. This option is primarily useful for when - you are using the Haskell code as a DLL, and want to set your - own signal handlers.</para> - - <para>Note that even - with <option>--install-signal-handlers=no</option>, the RTS - interval timer signal is still enabled. The timer signal - is either SIGVTALRM or SIGALRM, depending on the RTS - configuration and OS capabilities. To disable the timer - signal, use the <literal>-V0</literal> RTS option (see - above). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-xm<replaceable>address</replaceable></option> - <indexterm><primary><option>-xm</option></primary><secondary>RTS - option</secondary></indexterm></term> - <listitem> - <para> - WARNING: this option is for working around memory - allocation problems only. Do not use unless GHCi fails - with a message like “<literal>failed to mmap() memory below 2Gb</literal>”. If you need to use this option to get GHCi working - on your machine, please file a bug. - </para> - - <para> - On 64-bit machines, the RTS needs to allocate memory in the - low 2Gb of the address space. Support for this across - different operating systems is patchy, and sometimes fails. - This option is there to give the RTS a hint about where it - should be able to allocate memory in the low 2Gb of the - address space. For example, <literal>+RTS -xm20000000 - -RTS</literal> would hint that the RTS should allocate - starting at the 0.5Gb mark. The default is to use the OS's - built-in support for allocating memory in the low 2Gb if - available (e.g. <literal>mmap</literal> - with <literal>MAP_32BIT</literal> on Linux), or - otherwise <literal>-xm40000000</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-xq<replaceable>size</replaceable></option> - <indexterm><primary><option>-xq</option></primary><secondary>RTS - option</secondary></indexterm></term> - <listitem> - <para> - [Default: 100k] This option relates to allocation - limits; for more about this see <ulink - url="&libraryBaseLocation;/GHC-Conc.html#v%3AenableAllocationLimit"><literal>enableAllocationLimit</literal></ulink>. - When a thread hits its allocation limit, the RTS throws an - exception to the thread, and the thread gets an additional - quota of allocation before the exception is raised again, - the idea being so that the thread can execute its exception - handlers. The <option>-xq</option> controls the size of - this additional quota. - </para> - </listitem> - </varlistentry> - - </variablelist> - </sect2> - - <sect2 id="rts-options-gc"> - <title>RTS options to control the garbage collector</title> - - <indexterm><primary>garbage collector</primary><secondary>options</secondary></indexterm> - <indexterm><primary>RTS options</primary><secondary>garbage collection</secondary></indexterm> - - <para>There are several options to give you precise control over - garbage collection. Hopefully, you won't need any of these in - normal operation, but there are several things that can be tweaked - for maximum performance.</para> - - <variablelist> - - <varlistentry> - <term> - <option>-A</option><replaceable>size</replaceable> - <indexterm><primary><option>-A</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>allocation area, size</primary></indexterm> - </term> - <listitem> - <para>[Default: 512k] Set the allocation area size - used by the garbage collector. The allocation area - (actually generation 0 step 0) is fixed and is never resized - (unless you use <option>-H</option>, below).</para> - - <para>Increasing the allocation area size may or may not - give better performance (a bigger allocation area means - worse cache behaviour but fewer garbage collections and less - promotion).</para> - - <para>With only 1 generation (<option>-G1</option>) the - <option>-A</option> option specifies the minimum allocation - area, since the actual size of the allocation area will be - resized according to the amount of data in the heap (see - <option>-F</option>, below).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-O</option><replaceable>size</replaceable> - <indexterm><primary><option>-O</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>old generation, size</primary></indexterm> - </term> - <listitem> - <para>[Default: 1m] Set the minimum size of the - old generation. The old generation is collected whenever it - grows to this size or the value of the <option>-F</option> option - multiplied by the size of the live data at the previous major - collection, whichever is larger.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-n</option><replaceable>size</replaceable> - <indexterm><primary><option>-n</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>allocation area, chunk size</primary></indexterm> - </term> - <listitem> - <para>[Default: 0, Example: - <literal>-n4m</literal>] When set to a non-zero value, - this option divides the allocation area (<option>-A</option> - value) into chunks of the specified size. During execution, - when a processor exhausts its current chunk, it is given - another chunk from the pool until the pool is exhausted, at - which point a collection is triggered.</para> - - <para>This option is only useful when running in parallel - (<option>-N2</option> or greater). It allows the processor - cores to make better use of the available allocation area, - even when cores are allocating at different rates. Without - <option>-n</option>, each core gets a fixed-size allocation - area specified by the <option>-A</option>, and the first - core to exhaust its allocation area triggers a GC across all - the cores. This can result in a collection happening when - the allocation areas of some cores are only partially full, - so the purpose of the <option>-n</option> is to allow cores - that are allocating faster to get more of the allocation - area. This means less frequent GC, leading a lower GC - overhead for the same heap size.</para> - - <para>This is particularly useful in conjunction with larger - <option>-A</option> values, for example <option>-A64m - -n4m</option> is a useful combination on larger core counts - (8+).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-c</option> - <indexterm><primary><option>-c</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>garbage collection</primary><secondary>compacting</secondary></indexterm> - <indexterm><primary>compacting garbage collection</primary></indexterm> - </term> - <listitem> - <para>Use a compacting algorithm for collecting the oldest - generation. By default, the oldest generation is collected - using a copying algorithm; this option causes it to be - compacted in-place instead. The compaction algorithm is - slower than the copying algorithm, but the savings in memory - use can be considerable.</para> - - <para>For a given heap size (using the <option>-H</option> - option), compaction can in fact reduce the GC cost by - allowing fewer GCs to be performed. This is more likely - when the ratio of live data to heap size is high, say - >30%.</para> - - <para>NOTE: compaction doesn't currently work when a single - generation is requested using the <option>-G1</option> - option.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-c</option><replaceable>n</replaceable></term> - - <listitem> - <para>[Default: 30] Automatically enable - compacting collection when the live data exceeds - <replaceable>n</replaceable>% of the maximum heap size - (see the <option>-M</option> option). Note that the maximum - heap size is unlimited by default, so this option has no - effect unless the maximum heap size is set with - <option>-M</option><replaceable>size</replaceable>. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-F</option><replaceable>factor</replaceable> - <indexterm><primary><option>-F</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>heap size, factor</primary></indexterm> - </term> - <listitem> - - <para>[Default: 2] This option controls the amount - of memory reserved for the older generations (and in the - case of a two space collector the size of the allocation - area) as a factor of the amount of live data. For example, - if there was 2M of live data in the oldest generation when - we last collected it, then by default we'll wait until it - grows to 4M before collecting it again.</para> - - <para>The default seems to work well here. If you have - plenty of memory, it is usually better to use - <option>-H</option><replaceable>size</replaceable> than to - increase - <option>-F</option><replaceable>factor</replaceable>.</para> - - <para>The <option>-F</option> setting will be automatically - reduced by the garbage collector when the maximum heap size - (the <option>-M</option><replaceable>size</replaceable> - setting) is approaching.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-G</option><replaceable>generations</replaceable> - <indexterm><primary><option>-G</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>generations, number of</primary></indexterm> - </term> - <listitem> - <para>[Default: 2] Set the number of generations - used by the garbage collector. The default of 2 seems to be - good, but the garbage collector can support any number of - generations. Anything larger than about 4 is probably not a - good idea unless your program runs for a - <emphasis>long</emphasis> time, because the oldest - generation will hardly ever get collected.</para> - - <para>Specifying 1 generation with <option>+RTS -G1</option> - gives you a simple 2-space collector, as you would expect. - In a 2-space collector, the <option>-A</option> option (see - above) specifies the <emphasis>minimum</emphasis> allocation - area size, since the allocation area will grow with the - amount of live data in the heap. In a multi-generational - collector the allocation area is a fixed size (unless you - use the <option>-H</option> option, see below).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-qg<optional><replaceable>gen</replaceable></optional></option> - <indexterm><primary><option>-qg</option><secondary>RTS - option</secondary></primary></indexterm> - </term> - <listitem> - <para>[New in GHC 6.12.1] [Default: 0] - Use parallel GC in - generation <replaceable>gen</replaceable> and higher. - Omitting <replaceable>gen</replaceable> turns off the - parallel GC completely, reverting to sequential GC.</para> - - <para>The default parallel GC settings are usually suitable - for parallel programs (i.e. those - using <literal>par</literal>, Strategies, or with multiple - threads). However, it is sometimes beneficial to enable - the parallel GC for a single-threaded sequential program - too, especially if the program has a large amount of heap - data and GC is a significant fraction of runtime. To use - the parallel GC in a sequential program, enable the - parallel runtime with a suitable <literal>-N</literal> - option, and additionally it might be beneficial to - restrict parallel GC to the old generation - with <literal>-qg1</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-qb<optional><replaceable>gen</replaceable></optional></option> - <indexterm><primary><option>-qb</option><secondary>RTS - option</secondary></primary></indexterm> - </term> - <listitem> - <para> - [New in GHC 6.12.1] [Default: 1] Use - load-balancing in the parallel GC in - generation <replaceable>gen</replaceable> and higher. - Omitting <replaceable>gen</replaceable> disables - load-balancing entirely.</para> - - <para> - Load-balancing shares out the work of GC between the - available cores. This is a good idea when the heap is - large and we need to parallelise the GC work, however it - is also pessimal for the short young-generation - collections in a parallel program, because it can harm - locality by moving data from the cache of the CPU where is - it being used to the cache of another CPU. Hence the - default is to do load-balancing only in the - old-generation. In fact, for a parallel program it is - sometimes beneficial to disable load-balancing entirely - with <literal>-qb</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-H</option><optional><replaceable>size</replaceable></optional> - <indexterm><primary><option>-H</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>heap size, suggested</primary></indexterm> - </term> - <listitem> - <para>[Default: 0] This option provides a - “suggested heap size” for the garbage - collector. Think - of <option>-H<replaceable>size</replaceable></option> as a - variable <option>-A</option> option. It says: I want to - use at least <replaceable>size</replaceable> bytes, so use - whatever is left over to increase the <option>-A</option> - value.</para> - - <para>This option does not put - a <emphasis>limit</emphasis> on the heap size: the heap - may grow beyond the given size as usual.</para> - - <para>If <replaceable>size</replaceable> is omitted, then - the garbage collector will take the size of the heap at - the previous GC as the <replaceable>size</replaceable>. - This has the effect of allowing for a - larger <option>-A</option> value but without increasing - the overall memory requirements of the program. It can be - useful when the default small <option>-A</option> value is - suboptimal, as it can be in programs that create large - amounts of long-lived data.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-I</option><replaceable>seconds</replaceable> - <indexterm><primary><option>-I</option></primary> - <secondary>RTS option</secondary> - </indexterm> - <indexterm><primary>idle GC</primary> - </indexterm> - </term> - <listitem> - <para>(default: 0.3) In the threaded and SMP versions of the RTS (see - <option>-threaded</option>, <xref linkend="options-linker" />), a - major GC is automatically performed if the runtime has been idle - (no Haskell computation has been running) for a period of time. - The amount of idle time which must pass before a GC is performed is - set by the <option>-I</option><replaceable>seconds</replaceable> - option. Specifying <option>-I0</option> disables the idle GC.</para> - - <para>For an interactive application, it is probably a good idea to - use the idle GC, because this will allow finalizers to run and - deadlocked threads to be detected in the idle time when no Haskell - computation is happening. Also, it will mean that a GC is less - likely to happen when the application is busy, and so - responsiveness may be improved. However, if the amount of live data in - the heap is particularly large, then the idle GC can cause a - significant delay, and too small an interval could adversely affect - interactive responsiveness.</para> - - <para>This is an experimental feature, please let us know if it - causes problems and/or could benefit from further tuning.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ki</option><replaceable>size</replaceable> - <indexterm><primary><option>-k</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>stack, initial size</primary></indexterm> - </term> - <listitem> - <para> - [Default: 1k] Set the initial stack size for new - threads. (Note: this flag used to be - simply <option>-k</option>, but was renamed - to <option>-ki</option> in GHC 7.2.1. The old name is - still accepted for backwards compatibility, but that may - be removed in a future version). - </para> - - <para> - Thread stacks (including the main thread's stack) live on - the heap. As the stack grows, new stack chunks are added - as required; if the stack shrinks again, these extra stack - chunks are reclaimed by the garbage collector. The - default initial stack size is deliberately small, in order - to keep the time and space overhead for thread creation to - a minimum, and to make it practical to spawn threads for - even tiny pieces of work. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-kc</option><replaceable>size</replaceable> - <indexterm><primary><option>-kc</option></primary><secondary>RTS - option</secondary></indexterm> - <indexterm><primary>stack</primary><secondary>chunk size</secondary></indexterm> - </term> - <listitem> - <para> - [Default: 32k] Set the size of “stack - chunks”. When a thread's current stack overflows, a - new stack chunk is created and added to the thread's - stack, until the limit set by <option>-K</option> is - reached. - </para> - - <para> - The advantage of smaller stack chunks is that the garbage - collector can avoid traversing stack chunks if they are - known to be unmodified since the last collection, so - reducing the chunk size means that the garbage collector - can identify more stack as unmodified, and the GC overhead - might be reduced. On the other hand, making stack chunks - too small adds some overhead as there will be more - overflow/underflow between chunks. The default setting of - 32k appears to be a reasonable compromise in most cases. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-kb</option><replaceable>size</replaceable> - <indexterm><primary><option>-kc</option></primary><secondary>RTS - option</secondary></indexterm> - <indexterm><primary>stack</primary><secondary>chunk buffer size</secondary></indexterm> - </term> - <listitem> - <para> - [Default: 1k] Sets the stack chunk buffer size. - When a stack chunk overflows and a new stack chunk is - created, some of the data from the previous stack chunk is - moved into the new chunk, to avoid an immediate underflow - and repeated overflow/underflow at the boundary. The - amount of stack moved is set by the <option>-kb</option> - option. - </para> - <para> - Note that to avoid wasting space, this value should - typically be less than 10% of the size of a stack - chunk (<option>-kc</option>), because in a chain of stack - chunks, each chunk will have a gap of unused space of this - size. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-K</option><replaceable>size</replaceable> - <indexterm><primary><option>-K</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>stack, maximum size</primary></indexterm> - </term> - <listitem> - <para>[Default: 80% physical memory size] Set the - maximum stack size for an individual thread to - <replaceable>size</replaceable> bytes. If the thread - attempts to exceed this limit, it will be sent the - <literal>StackOverflow</literal> exception. The - limit can be disabled entirely by specifying a size of zero. - </para> - <para> - This option is there mainly to stop the program eating up - all the available memory in the machine if it gets into an - infinite loop. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-m</option><replaceable>n</replaceable> - <indexterm><primary><option>-m</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>heap, minimum free</primary></indexterm> - </term> - <listitem> - <para>Minimum % <replaceable>n</replaceable> of heap - which must be available for allocation. The default is - 3%.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-M</option><replaceable>size</replaceable> - <indexterm><primary><option>-M</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>heap size, maximum</primary></indexterm> - </term> - <listitem> - <para>[Default: unlimited] Set the maximum heap size to - <replaceable>size</replaceable> bytes. The heap normally - grows and shrinks according to the memory requirements of - the program. The only reason for having this option is to - stop the heap growing without bound and filling up all the - available swap space, which at the least will result in the - program being summarily killed by the operating - system.</para> - - <para>The maximum heap size also affects other garbage - collection parameters: when the amount of live data in the - heap exceeds a certain fraction of the maximum heap size, - compacting collection will be automatically enabled for the - oldest generation, and the <option>-F</option> parameter - will be reduced in order to avoid exceeding the maximum heap - size.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-T</option> - <indexterm><primary><option>-T</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <term> - <option>-t</option><optional><replaceable>file</replaceable></optional> - <indexterm><primary><option>-t</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <term> - <option>-s</option><optional><replaceable>file</replaceable></optional> - <indexterm><primary><option>-s</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <term> - <option>-S</option><optional><replaceable>file</replaceable></optional> - <indexterm><primary><option>-S</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <term> - <option>--machine-readable</option> - <indexterm><primary><option>--machine-readable</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>These options produce runtime-system statistics, such - as the amount of time spent executing the program and in the - garbage collector, the amount of memory allocated, the - maximum size of the heap, and so on. The three - variants give different levels of detail: - <option>-T</option> collects the data but produces no output - <option>-t</option> produces a single line of output in the - same format as GHC's <option>-Rghc-timing</option> option, - <option>-s</option> produces a more detailed summary at the - end of the program, and <option>-S</option> additionally - produces information about each and every garbage - collection.</para> - - <para>The output is placed in - <replaceable>file</replaceable>. If - <replaceable>file</replaceable> is omitted, then the output - is sent to <constant>stderr</constant>.</para> - - <para> - If you use the <literal>-T</literal> flag then, you should - access the statistics using - <ulink url="&libraryBaseLocation;/GHC-Stats.html">GHC.Stats</ulink>. - </para> - - <para> - If you use the <literal>-t</literal> flag then, when your - program finishes, you will see something like this: - </para> - -<programlisting> -<<ghc: 36169392 bytes, 69 GCs, 603392/1065272 avg/max bytes residency (2 samples), 3M in use, 0.00 INIT (0.00 elapsed), 0.02 MUT (0.02 elapsed), 0.07 GC (0.07 elapsed) :ghc>> -</programlisting> - - <para> - This tells you: - </para> - - <itemizedlist> - <listitem> - <para> - The total number of bytes allocated by the program over the - whole run. - </para> - </listitem> - <listitem> - <para> - The total number of garbage collections performed. - </para> - </listitem> - <listitem> - <para> - The average and maximum "residency", which is the amount of - live data in bytes. The runtime can only determine the - amount of live data during a major GC, which is why the - number of samples corresponds to the number of major GCs - (and is usually relatively small). To get a better picture - of the heap profile of your program, use - the <option>-hT</option> RTS option - (<xref linkend="rts-profiling" />). - </para> - </listitem> - <listitem> - <para> - The peak memory the RTS has allocated from the OS. - </para> - </listitem> - <listitem> - <para> - The amount of CPU time and elapsed wall clock time while - initialising the runtime system (INIT), running the program - itself (MUT, the mutator), and garbage collecting (GC). - </para> - </listitem> - </itemizedlist> - - <para> - You can also get this in a more future-proof, machine readable - format, with <literal>-t --machine-readable</literal>: - </para> - -<programlisting> - [("bytes allocated", "36169392") - ,("num_GCs", "69") - ,("average_bytes_used", "603392") - ,("max_bytes_used", "1065272") - ,("num_byte_usage_samples", "2") - ,("peak_megabytes_allocated", "3") - ,("init_cpu_seconds", "0.00") - ,("init_wall_seconds", "0.00") - ,("mutator_cpu_seconds", "0.02") - ,("mutator_wall_seconds", "0.02") - ,("GC_cpu_seconds", "0.07") - ,("GC_wall_seconds", "0.07") - ] -</programlisting> - - <para> - If you use the <literal>-s</literal> flag then, when your - program finishes, you will see something like this (the exact - details will vary depending on what sort of RTS you have, e.g. - you will only see profiling data if your RTS is compiled for - profiling): - </para> - -<programlisting> - 36,169,392 bytes allocated in the heap - 4,057,632 bytes copied during GC - 1,065,272 bytes maximum residency (2 sample(s)) - 54,312 bytes maximum slop - 3 MB total memory in use (0 MB lost due to fragmentation) - - Generation 0: 67 collections, 0 parallel, 0.04s, 0.03s elapsed - Generation 1: 2 collections, 0 parallel, 0.03s, 0.04s elapsed - - SPARKS: 359207 (557 converted, 149591 pruned) - - INIT time 0.00s ( 0.00s elapsed) - MUT time 0.01s ( 0.02s elapsed) - GC time 0.07s ( 0.07s elapsed) - EXIT time 0.00s ( 0.00s elapsed) - Total time 0.08s ( 0.09s elapsed) - - %GC time 89.5% (75.3% elapsed) - - Alloc rate 4,520,608,923 bytes per MUT second - - Productivity 10.5% of total user, 9.1% of total elapsed -</programlisting> - - <itemizedlist> - <listitem> - <para> - The "bytes allocated in the heap" is the total bytes allocated - by the program over the whole run. - </para> - </listitem> - <listitem> - <para> - GHC uses a copying garbage collector by default. "bytes copied - during GC" tells you how many bytes it had to copy during - garbage collection. - </para> - </listitem> - <listitem> - <para> - The maximum space actually used by your program is the - "bytes maximum residency" figure. This is only checked during - major garbage collections, so it is only an approximation; - the number of samples tells you how many times it is checked. - </para> - </listitem> - <listitem> - <para> - The "bytes maximum slop" tells you the most space that is ever - wasted due to the way GHC allocates memory in blocks. Slop is - memory at the end of a block that was wasted. There's no way - to control this; we just like to see how much memory is being - lost this way. - </para> - </listitem> - <listitem> - <para> - The "total memory in use" tells you the peak memory the RTS has - allocated from the OS. - </para> - </listitem> - <listitem> - <para> - Next there is information about the garbage collections done. - For each generation it says how many garbage collections were - done, how many of those collections were done in parallel, - the total CPU time used for garbage collecting that generation, - and the total wall clock time elapsed while garbage collecting - that generation. - </para> - </listitem> - <listitem> - <para>The <literal>SPARKS</literal> statistic refers to the - use of <literal>Control.Parallel.par</literal> and related - functionality in the program. Each spark represents a call - to <literal>par</literal>; a spark is "converted" when it is - executed in parallel; and a spark is "pruned" when it is - found to be already evaluated and is discarded from the pool - by the garbage collector. Any remaining sparks are - discarded at the end of execution, so "converted" plus - "pruned" does not necessarily add up to the total.</para> - </listitem> - <listitem> - <para> - Next there is the CPU time and wall clock time elapsed broken - down by what the runtime system was doing at the time. - INIT is the runtime system initialisation. - MUT is the mutator time, i.e. the time spent actually running - your code. - GC is the time spent doing garbage collection. - RP is the time spent doing retainer profiling. - PROF is the time spent doing other profiling. - EXIT is the runtime system shutdown time. - And finally, Total is, of course, the total. - </para> - <para> - %GC time tells you what percentage GC is of Total. - "Alloc rate" tells you the "bytes allocated in the heap" divided - by the MUT CPU time. - "Productivity" tells you what percentage of the Total CPU and wall - clock elapsed times are spent in the mutator (MUT). - </para> - </listitem> - </itemizedlist> - - <para> - The <literal>-S</literal> flag, as well as giving the same - output as the <literal>-s</literal> flag, prints information - about each GC as it happens: - </para> - -<programlisting> - Alloc Copied Live GC GC TOT TOT Page Flts - bytes bytes bytes user elap user elap - 528496 47728 141512 0.01 0.02 0.02 0.02 0 0 (Gen: 1) -[...] - 524944 175944 1726384 0.00 0.00 0.08 0.11 0 0 (Gen: 0) -</programlisting> - - <para> - For each garbage collection, we print: - </para> - - <itemizedlist> - <listitem> - <para> - How many bytes we allocated this garbage collection. - </para> - </listitem> - <listitem> - <para> - How many bytes we copied this garbage collection. - </para> - </listitem> - <listitem> - <para> - How many bytes are currently live. - </para> - </listitem> - <listitem> - <para> - How long this garbage collection took (CPU time and elapsed - wall clock time). - </para> - </listitem> - <listitem> - <para> - How long the program has been running (CPU time and elapsed - wall clock time). - </para> - </listitem> - <listitem> - <para> - How many page faults occurred this garbage collection. - </para> - </listitem> - <listitem> - <para> - How many page faults occurred since the end of the last garbage - collection. - </para> - </listitem> - <listitem> - <para> - Which generation is being garbage collected. - </para> - </listitem> - </itemizedlist> - - </listitem> - </varlistentry> - </variablelist> - - </sect2> - - <sect2> - <title>RTS options for concurrency and parallelism</title> - - <para>The RTS options related to concurrency are described in - <xref linkend="using-concurrent" />, and those for parallelism in - <xref linkend="parallel-options"/>.</para> - </sect2> - - <sect2 id="rts-profiling"> - <title>RTS options for profiling</title> - - <para>Most profiling runtime options are only available when you - compile your program for profiling (see - <xref linkend="prof-compiler-options" />, and - <xref linkend="rts-options-heap-prof" /> for the runtime options). - However, there is one profiling option that is available - for ordinary non-profiled executables:</para> - - <variablelist> - <varlistentry> - <term> - <option>-hT</option> - <indexterm><primary><option>-hT</option></primary><secondary>RTS - option</secondary></indexterm> - </term> - <listitem> - <para>(can be shortened to <option>-h</option>.) Generates a basic heap profile, in the - file <literal><replaceable>prog</replaceable>.hp</literal>. - To produce the heap profile graph, - use <command>hp2ps</command> (see <xref linkend="hp2ps" - />). The basic heap profile is broken down by data - constructor, with other types of closures (functions, thunks, - etc.) grouped into broad categories - (e.g. <literal>FUN</literal>, <literal>THUNK</literal>). To - get a more detailed profile, use the full profiling - support (<xref linkend="profiling" />).</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="rts-eventlog"> - <title>Tracing</title> - - <indexterm><primary>tracing</primary></indexterm> - <indexterm><primary>events</primary></indexterm> - <indexterm><primary>eventlog files</primary></indexterm> - - <para> - When the program is linked with the <option>-eventlog</option> - option (<xref linkend="options-linker" />), runtime events can - be logged in two ways: - </para> - - <itemizedlist> - <listitem> - <para> - In binary format to a file for later analysis by a - variety of tools. One such tool - is <ulink url="http://www.haskell.org/haskellwiki/ThreadScope">ThreadScope</ulink><indexterm><primary>ThreadScope</primary></indexterm>, - which interprets the event log to produce a visual parallel - execution profile of the program. - </para> - </listitem> - <listitem> - <para> - As text to standard output, for debugging purposes. - </para> - </listitem> - </itemizedlist> - - <variablelist> - <varlistentry> - <term> - <option>-l<optional><replaceable>flags</replaceable></optional></option> - <indexterm><primary><option>-l</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para> - Log events in binary format to the - file <filename><replaceable>program</replaceable>.eventlog</filename>. - Without any <replaceable>flags</replaceable> specified, this logs a - default set of events, suitable for use with tools like ThreadScope. - </para> - - <para> - For some special use cases you may want more control over which - events are included. The <replaceable>flags</replaceable> is a - sequence of zero or more characters indicating which classes of - events to log. Currently these the classes of events that can - be enabled/disabled: - <simplelist> - <member> - <option>s</option> — scheduler events, including Haskell - thread creation and start/stop events. Enabled by default. - </member> - <member> - <option>g</option> — GC events, including GC start/stop. - Enabled by default. - </member> - <member> - <option>p</option> — parallel sparks (sampled). - Enabled by default. - </member> - <member> - <option>f</option> — parallel sparks (fully accurate). - Disabled by default. - </member> - <member> - <option>u</option> — user events. These are events emitted - from Haskell code using functions such as - <literal>Debug.Trace.traceEvent</literal>. Enabled by default. - </member> - </simplelist> - </para> - - <para> - You can disable specific classes, or enable/disable all classes at - once: - <simplelist> - <member> - <option>a</option> — enable all event classes listed above - </member> - <member> - <option>-<replaceable>x</replaceable></option> — disable the - given class of events, for any event class listed above or - <option>-a</option> for all classes - </member> - </simplelist> - For example, <option>-l-ag</option> would disable all event classes - (<option>-a</option>) except for GC events (<option>g</option>). - </para> - - <para> - For spark events there are two modes: sampled and fully accurate. - There are various events in the life cycle of each spark, usually - just creating and running, but there are some more exceptional - possibilities. In the sampled mode the number of occurrences of each - kind of spark event is sampled at frequent intervals. In the fully - accurate mode every spark event is logged individually. The latter - has a higher runtime overhead and is not enabled by default. - </para> - - <para> - The format of the log file is described by the header - <filename>EventLogFormat.h</filename> that comes with - GHC, and it can be parsed in Haskell using - the <ulink url="http://hackage.haskell.org/package/ghc-events">ghc-events</ulink> - library. To dump the contents of - a <literal>.eventlog</literal> file as text, use the - tool <literal>ghc-events show</literal> that comes with - the <ulink url="http://hackage.haskell.org/package/ghc-events">ghc-events</ulink> - package. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-v</option><optional><replaceable>flags</replaceable></optional> - <indexterm><primary><option>-v</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para> - Log events as text to standard output, instead of to - the <literal>.eventlog</literal> file. - The <replaceable>flags</replaceable> are the same as - for <option>-l</option>, with the additional - option <literal>t</literal> which indicates that the - each event printed should be preceded by a timestamp value - (in the binary <literal>.eventlog</literal> file, all - events are automatically associated with a timestamp). - </para> - </listitem> - </varlistentry> - - </variablelist> - - <para> - The debugging - options <option>-D<replaceable>x</replaceable></option> also - generate events which are logged using the tracing framework. - By default those events are dumped as text to stdout - (<option>-D<replaceable>x</replaceable></option> - implies <option>-v</option>), but they may instead be stored in - the binary eventlog file by using the <option>-l</option> - option. - </para> - </sect2> - - <sect2 id="rts-options-debugging"> - <title>RTS options for hackers, debuggers, and over-interested - souls</title> - - <indexterm><primary>RTS options, hacking/debugging</primary></indexterm> - - <para>These RTS options might be used (a) to avoid a GHC bug, - (b) to see “what's really happening”, or - (c) because you feel like it. Not recommended for everyday - use!</para> - - <variablelist> - - <varlistentry> - <term> - <option>-B</option> - <indexterm><primary><option>-B</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>Sound the bell at the start of each (major) garbage - collection.</para> - - <para>Oddly enough, people really do use this option! Our - pal in Durham (England), Paul Callaghan, writes: “Some - people here use it for a variety of - purposes—honestly!—e.g., confirmation that the - code/machine is doing something, infinite loop detection, - gauging cost of recently added code. Certain people can even - tell what stage [the program] is in by the beep - pattern. But the major use is for annoying others in the - same office…”</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-D</option><replaceable>x</replaceable> - <indexterm><primary>-D</primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para> - An RTS debugging flag; only available if the program was - linked with the <option>-debug</option> option. Various - values of <replaceable>x</replaceable> are provided to - enable debug messages and additional runtime sanity checks - in different subsystems in the RTS, for - example <literal>+RTS -Ds -RTS</literal> enables debug - messages from the scheduler. - Use <literal>+RTS -?</literal> to find out which - debug flags are supported. - </para> - - <para> - Debug messages will be sent to the binary event log file - instead of stdout if the <option>-l</option> option is - added. This might be useful for reducing the overhead of - debug tracing. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-r</option><replaceable>file</replaceable> - <indexterm><primary><option>-r</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>ticky ticky profiling</primary></indexterm> - <indexterm><primary>profiling</primary><secondary>ticky ticky</secondary></indexterm> - </term> - <listitem> - <para>Produce “ticky-ticky” statistics at the - end of the program run (only available if the program was - linked with <option>-debug</option>). - The <replaceable>file</replaceable> business works just like - on the <option>-S</option> RTS option, above.</para> - - <para>For more information on ticky-ticky profiling, see - <xref linkend="ticky-ticky"/>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-xc</option> - <indexterm><primary><option>-xc</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>(Only available when the program is compiled for - profiling.) When an exception is raised in the program, - this option causes a stack trace to be - dumped to <literal>stderr</literal>.</para> - - <para>This can be particularly useful for debugging: if your - program is complaining about a <literal>head []</literal> - error and you haven't got a clue which bit of code is - causing it, compiling with <literal>-prof - -fprof-auto</literal> and running with <literal>+RTS -xc - -RTS</literal> will tell you exactly the call stack at the - point the error was raised.</para> - - <para>The output contains one report for each exception - raised in the program (the program might raise and catch - several exceptions during its execution), where each report - looks something like this: - </para> - -<screen> -*** Exception raised (reporting due to +RTS -xc), stack trace: - GHC.List.CAF - --> evaluated by: Main.polynomial.table_search, - called from Main.polynomial.theta_index, - called from Main.polynomial, - called from Main.zonal_pressure, - called from Main.make_pressure.p, - called from Main.make_pressure, - called from Main.compute_initial_state.p, - called from Main.compute_initial_state, - called from Main.CAF - ... -</screen> - <para>The stack trace may often begin with something - uninformative like <literal>GHC.List.CAF</literal>; this is - an artifact of GHC's optimiser, which lifts out exceptions - to the top-level where the profiling system assigns them to - the cost centre "CAF". However, <literal>+RTS -xc</literal> - doesn't just print the current stack, it looks deeper and - reports the stack at the time the CAF was evaluated, and it - may report further stacks until a non-CAF stack is found. In - the example above, the next stack (after <literal>--> - evaluated by</literal>) contains plenty of information about - what the program was doing when it evaluated <literal>head - []</literal>.</para> - - <para>Implementation details aside, the function names in - the stack should hopefully give you enough clues to track - down the bug.</para> - - <para> - See also the function <literal>traceStack</literal> in the - module <literal>Debug.Trace</literal> for another way to - view call stacks. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-Z</option> - <indexterm><primary><option>-Z</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>Turn <emphasis>off</emphasis> “update-frame - squeezing” at garbage-collection time. (There's no - particularly good reason to turn it off, except to ensure - the accuracy of certain data collected regarding thunk entry - counts.)</para> - </listitem> - </varlistentry> - </variablelist> - - </sect2> - - <sect2 id="ghc-info"> - <title>Getting information about the RTS</title> - - <indexterm><primary>RTS</primary></indexterm> - - <para>It is possible to ask the RTS to give some information about - itself. To do this, use the <option>--info</option> flag, e.g.</para> -<screen> -$ ./a.out +RTS --info - [("GHC RTS", "YES") - ,("GHC version", "6.7") - ,("RTS way", "rts_p") - ,("Host platform", "x86_64-unknown-linux") - ,("Host architecture", "x86_64") - ,("Host OS", "linux") - ,("Host vendor", "unknown") - ,("Build platform", "x86_64-unknown-linux") - ,("Build architecture", "x86_64") - ,("Build OS", "linux") - ,("Build vendor", "unknown") - ,("Target platform", "x86_64-unknown-linux") - ,("Target architecture", "x86_64") - ,("Target OS", "linux") - ,("Target vendor", "unknown") - ,("Word size", "64") - ,("Compiler unregisterised", "NO") - ,("Tables next to code", "YES") - ] -</screen> - <para>The information is formatted such that it can be read as a - of type <literal>[(String, String)]</literal>. Currently the following - fields are present:</para> - - <variablelist> - - <varlistentry> - <term><literal>GHC RTS</literal></term> - <listitem> - <para>Is this program linked against the GHC RTS? (always - "YES").</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>GHC version</literal></term> - <listitem> - <para>The version of GHC used to compile this program.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>RTS way</literal></term> - <listitem> - <para>The variant (“way”) of the runtime. The - most common values are <literal>rts_v</literal> (vanilla), - <literal>rts_thr</literal> (threaded runtime, i.e. linked using the - <literal>-threaded</literal> option) and <literal>rts_p</literal> - (profiling runtime, i.e. linked using the <literal>-prof</literal> - option). Other variants include <literal>debug</literal> - (linked using <literal>-debug</literal>), and - <literal>dyn</literal> (the RTS is - linked in dynamically, i.e. a shared library, rather than statically - linked into the executable itself). These can be combined, - e.g. you might have <literal>rts_thr_debug_p</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>Target platform</literal>, - <literal>Target architecture</literal>, - <literal>Target OS</literal>, - <literal>Target vendor</literal> - </term> - <listitem> - <para>These are the platform the program is compiled to run on.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>Build platform</literal>, - <literal>Build architecture</literal>, - <literal>Build OS</literal>, - <literal>Build vendor</literal> - </term> - <listitem> - <para>These are the platform where the program was built - on. (That is, the target platform of GHC itself.) Ordinarily - this is identical to the target platform. (It could potentially - be different if cross-compiling.)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>Host platform</literal>, - <literal>Host architecture</literal> - <literal>Host OS</literal> - <literal>Host vendor</literal> - </term> - <listitem> - <para>These are the platform where GHC itself was compiled. - Again, this would normally be identical to the build and - target platforms.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>Word size</literal></term> - <listitem> - <para>Either <literal>"32"</literal> or <literal>"64"</literal>, - reflecting the word size of the target platform.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>Compiler unregistered</literal></term> - <listitem> - <para>Was this program compiled with an - <link linkend="unreg">“unregistered”</link> - version of GHC? (I.e., a version of GHC that has no platform-specific - optimisations compiled in, usually because this is a currently - unsupported platform.) This value will usually be no, unless you're - using an experimental build of GHC.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>Tables next to code</literal></term> - <listitem> - <para>Putting info tables directly next to entry code is a useful - performance optimisation that is not available on all platforms. - This field tells you whether the program has been compiled with - this optimisation. (Usually yes, except on unusual platforms.)</para> - </listitem> - </varlistentry> - - </variablelist> - - </sect2> -</sect1> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> diff --git a/docs/users_guide/safe_haskell.rst b/docs/users_guide/safe_haskell.rst new file mode 100644 index 0000000000..7d1b844202 --- /dev/null +++ b/docs/users_guide/safe_haskell.rst @@ -0,0 +1,748 @@ +.. _safe-haskell: + +Safe Haskell +============ + +.. index:: + single: safe haskell + +Safe Haskell is an extension to the Haskell language that is implemented +in GHC as of version 7.2. It allows for unsafe code to be securely +included in a trusted code base by restricting the features of GHC +Haskell the code is allowed to use. Put simply, it makes the types of +programs trustable. + +While a primary use case of Safe Haskell is running untrusted code, Safe +Haskell doesn't provide this directly. Instead, Safe Haskell provides +strict type safety. Without Safe Haskell, GHC allows many exceptions to +the type system which can subvert any abstractions. By providing strict +type safety, Safe Haskell enables developers to build their own library +level sandbox mechanisms to run untrusted code. + +While Safe Haskell is an extension, it actually runs in the background +for every compilation with GHC. It does this to track the type +violations of modules to infer their safety, even when they aren't +explicitly using Safe Haskell. Please refer to section +:ref:`safe-inference` for more details of this. + +The design of Safe Haskell covers the following aspects: + +- A :ref:`safe language <safe-language>` dialect of Haskell that provides + stricter guarantees about the code. It allows types and module boundaries to + be trusted. + +- A *safe import* extension that specifies that the module being imported must + be trusted. + +- A definition of *trust* (or safety) and how it operates, along with ways of + defining and changing the trust of modules and packages. + +Safe Haskell, however, *does not offer* compilation safety. During +compilation time it is possible for arbitrary processes to be launched, +using for example the :ref:`custom pre-processor <pre-processor>` flag. +This can be manipulated to either compromise a users system at +compilation time, or to modify the source code just before compilation +to try to alter Safe Haskell flags. This is discussed further in section +:ref:`safe-compilation`. + +.. _safe-use-cases: + +Uses of Safe Haskell +-------------------- + +.. index:: + single: safe haskell uses + +Safe Haskell has been designed with two use cases in mind: + +- Enforcing strict type safety at compile time +- Compiling and executing untrusted code + +Strict type-safety (good style) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Haskell offers a powerful type system and separation of pure and effectual +functions through the ``IO`` monad. However, there are several loop holes in the +type system, the most obvious being the ``unsafePerformIO :: IO a -> a`` +function. The safe language dialect of Safe Haskell disallows the use of such +functions. This can be useful restriction as it makes Haskell code easier to +analyse and reason about. It also codifies the existing culture in the Haskell +community of trying to avoid unsafe functions unless absolutely necessary. As +such, using the safe language (through the ``-XSafe`` flag) can be thought of as +a way of enforcing good style, similar to the function of ``-Wall``. + +Building secure systems (restricted IO Monads) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: secure haskell + +Systems such as information flow control security, capability based +security systems and DSLs for working with encrypted data.. etc can be +built in the Haskell language as a library. However they require +guarantees about the properties of Haskell that aren't true in general +due to the presence of functions like ``unsafePerformIO``. Safe Haskell +gives users enough guarantees about the type system to allow them to +build such secure systems. + +As an example, lets define an interface for a plugin system where the +plugin authors are untrusted, possibly malicious third-parties. We do +this by restricting the plugin interface to pure functions or to a +restricted ``IO`` monad that we have defined. The restricted ``IO`` +monad will only allow a safe subset of ``IO`` actions to be executed. We +define the plugin interface so that it requires the plugin module, +``Danger``, to export a single computation, ``Danger.runMe``, of type +``RIO ()``, where ``RIO`` is a monad defined as follows: + +:: + + -- While we use `Safe', the `Trustworthy' pragma would also be + -- fine. We simply want to ensure that: + -- 1) The module exports an interface that untrusted code can't + -- abuse. + -- 2) Untrusted code can import this module. + -- + {-# LANGUAGE Safe #-} + + module RIO (RIO(), runRIO, rioReadFile, rioWriteFile) where + + -- Notice that symbol UnsafeRIO is not exported from this module! + newtype RIO a = UnsafeRIO { runRIO :: IO a } + + instance Monad RIO where + return = UnsafeRIO . return + (UnsafeRIO m) >>= k = UnsafeRIO $ m >>= runRIO . k + + -- Returns True iff access is allowed to file name + pathOK :: FilePath -> IO Bool + pathOK file = {- Implement some policy based on file name -} + + rioReadFile :: FilePath -> RIO String + rioReadFile file = UnsafeRIO $ do + ok <- pathOK file + if ok then readFile file else return "" + + rioWriteFile :: FilePath -> String -> RIO () + rioWriteFile file contents = UnsafeRIO $ do + ok <- pathOK file + if ok then writeFile file contents else return () + +We then compile the ``Danger`` plugin using the new Safe Haskell +``-XSafe`` flag: +:: + + {-# LANGUAGE Safe #-} + module Danger ( runMe ) where + + runMe :: RIO () + runMe = ... + +Before going into the Safe Haskell details, lets point out some of the +reasons this security mechanism would fail without Safe Haskell: + +- The design attempts to restrict the operations that ``Danger`` can perform by + using types, specifically the ``RIO`` type wrapper around ``IO`` . The author + of ``Danger`` can subvert this though by simply writing arbitrary ``IO`` + actions and using ``unsafePerformIO :: IO a -> a`` to execute them as pure + functions. + +- The design also relies on ``Danger`` not being able to access the + ``UnsafeRIO`` constructor. Unfortunately Template Haskell can be used to + subvert module boundaries and so could be used to gain access to this + constructor. + +- There is no way to place restrictions on the modules that ``Danger`` can + import. This gives the author of ``Danger`` a very large attack surface, + essentially any package currently installed on the system. Should any of + these packages have a vulnerability, then the ``Danger`` module can exploit + it. + +Safe Haskell prevents all these attacks. This is done by compiling the +RIO module with the ``-XSafe`` or ``-XTrustworthy`` flag and compiling +``Danger`` with the ``-XSafe`` flag. We explain each below. + +The use of ``-XSafe`` to compile ``Danger`` restricts the features of +Haskell that can be used to a `safe subset <#safe-language>`__. This +includes disallowing ``unsafePerformIO``, Template Haskell, pure FFI +functions, RULES and restricting the operation of Overlapping Instances. +The ``-XSafe`` flag also restricts the modules can be imported by +``Danger`` to only those that are considered trusted. Trusted modules +are those compiled with ``-XSafe``, where GHC provides a mechanical +guarantee that the code is safe. Or those modules compiled with +``-XTrustworthy``, where the module author claims that the module is +Safe. + +This is why the RIO module is compiled with ``-XSafe`` or +``-XTrustworthy``>, to allow the ``Danger`` module to import it. The +``-XTrustworthy`` flag doesn't place any restrictions on the module like +``-XSafe`` does (expect to restrict overlapping instances to `safe +overlapping instances <#safe-overlapping-instances>`__). Instead the +module author claims that while code may use unsafe features internally, +it only exposes an API that can used in a safe manner. + +However, the unrestricted use of ``-XTrustworthy`` is a problem as an +arbitrary module can use it to mark themselves as trusted, yet +``-XTrustworthy`` doesn't offer any guarantees about the module, unlike +``-XSafe``. To control the use of trustworthy modules it is recommended +to use the ``-fpackage-trust`` flag. This flag adds an extra requirement +to the trust check for trustworthy modules. It requires that for a +trustworthy modules to be considered trusted, and allowed to be used in +``-XSafe`` compiled code, the client C compiling the code must tell GHC +that they trust the package the trustworthy module resides in. This is +essentially a way of for C to say, while this package contains +trustworthy modules that can be used by untrusted modules compiled with +``-XSafe``, I trust the author(s) of this package and trust the modules +only expose a safe API. The trust of a package can be changed at any +time, so if a vulnerability found in a package, C can declare that +package untrusted so that any future compilation against that package +would fail. For a more detailed overview of this mechanism see +:ref:`safe-trust`. + +In the example, ``Danger`` can import module ``RIO`` because ``RIO`` is +compiled with ``-XSafe``. Thus, ``Danger`` can make use of the +``rioReadFile`` and ``rioWriteFile`` functions to access permitted file +names. The main application then imports both ``RIO`` and ``Danger``. To +run the plugin, it calls ``RIO.runRIO Danger.runMe`` within the ``IO`` +monad. The application is safe in the knowledge that the only ``IO`` to +ensue will be to files whose paths were approved by the ``pathOK`` test. + +.. _safe-language: + +Safe Language +------------- + +.. index:: + single: safe language + +The Safe Haskell *safe language* (enabled by ``-XSafe``) guarantees the +following properties: + +- *Referential transparency* — The types can be trusted. Any pure function, is + guaranteed to be pure. Evaluating them is deterministic and won't cause any + side effects. Functions in the ``IO`` monad are still allowed and behave as + usual. So, for example, the ``unsafePerformIO :: IO a -> a`` function is + disallowed in the safe language to enforce this property. + +- *Module boundary control* — Only symbols that are publicly available through + other module export lists can be accessed in the safe language. Values using + data constructors not exported by the defining module, cannot be examined or + created. As such, if a module ``M`` establishes some invariants through + careful use of its export list, then code written in the safe language that + imports ``M`` is guaranteed to respect those invariants. + +- *Semantic consistency* — For any module that imports a module written in the + safe language, expressions that compile both with and without the safe import + have the same meaning in both cases. That is, importing a module written in + the safe language cannot change the meaning of existing code that isn't + dependent on that module. So, for example, there are some restrictions placed + on the use of :ref:`OverlappingInstances <instance-overlap>`, as these can + violate this property. + +- *Strict subset* — 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. + +These four properties guarantee that in the safe language you can trust +the types, can trust that module export lists are respected, and can +trust that code that successfully compiles has the same meaning as it +normally would. + +To achieve these properties, in the safe language dialect we disable +completely the following features: + +- ``TemplateHaskell`` — Can be used to gain access to constructors and abstract + data types that weren't exported by a module, subverting module boundaries. + +Furthermore, we restrict the following features: + +- ``ForeignFunctionInterface`` — Foreign import declarations that import a + function with a non-``IO`` type are disallowed. + +- ``RULES`` — Rewrite rules defined in a module M compiled with ``-XSafe`` are + dropped. Rules defined in Trustworthy modules that ``M`` imports are still + valid and will fire as usual. + +- ``OverlappingInstances`` — There is no restriction on the creation of + overlapping instances, but we do restrict their use at a particular call + site. This is a detailed restriction, please refer to :ref:`Safe Overlapping + Instances <safe-overlapping-instances>` for details. + +- ``GeneralisedNewtypeDeriving`` — GND is not allowed in the safe language. This + is due to the ability of it to violate module boundaries when module authors + forget to put nominal role annotations on their types as appropriate. For + this reason, the ``Data.Coerce`` module is also considered unsafe. We are + hoping to find a better solution here in the future. + +- ``Data.Typeable`` — Hand crafted instances of the Typeable type class are not allowed + in Safe Haskell as this can easily be abused to unsafely coerce + between types. Derived instances (through the ``-XDeriveDataTypeable`` + extension) are still allowed. + +.. _safe-overlapping-instances: + +Safe Overlapping Instances +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Due to the semantic consistency guarantee of Safe Haskell, we must +restrict the function of overlapping instances. We don't restrict their +ability to be defined, as this is a global property and not something we +can determine by looking at a single module. Instead, when a module +calls a function belonging to a type-class, we check that the instance +resolution done is considered 'safe'. This check is enforced for modules +compiled with both ``-XSafe`` and ``-XTrustworthy``. + +More specifically, consider the following modules: + +:: + + {-# LANGUAGE Safe #-} + module Class (TC(..)) where + class TC a where { op :: a -> String } + + {-# LANGUAGE Safe #-} + module Dangerous (TC(..)) where + import Class + + instance + {-# OVERLAPS #-} + TC [Int] where { op _ = "[Int]" } + + {-# LANGUAGE Safe #-} + module TCB_Runner where + import Class + import Dangerous + + instance + TC [a] where { op _ = "[a]" } + + f :: String + f = op ([1,2,3,4] :: [Int]) + +Both module ``Class`` and module ``Dangerous`` will compile under ``-XSafe`` +without issue. However, in module ``TCB_Runner``, we must check if the call +to ``op`` in function ``f`` is safe. + +What does it mean to be Safe? That importing a module compiled with +``-XSafe`` shouldn't change the meaning of code that compiles fine +without importing the module. This is the Safe Haskell property known as +*semantic consistency*. + +In our situation, module ``TCB_Runner`` compiles fine without importing +module ``Dangerous``. So when deciding which instance to use for the call to +``op``, if we determine the instance ``TC [Int]`` from module Dangerous +is the most specific, this is unsafe. This prevents code written by +third-parties we don't trust (which is compiled using ``-XSafe`` in Safe +Haskell) from changing the behaviour of our existing code. + +Specifically, we apply the following rule to determine if a type-class +method call is *unsafe* when overlapping instances are involved: + +- Most specific instance, ``Ix``, defined in an ``-XSafe`` compiled module. +- ``Ix`` is an orphan instance or a multi-parameter-type-class. +- At least one overlapped instance, ``Iy``, is both: + + - From a different module than ``Ix`` + - ``Iy`` is not marked ``OVERLAPPABLE`` + +This is a slightly involved heuristic, but captures the situation of an +imported module ``N`` changing the behaviour of existing code. For example, +if the second condition isn't violated, then the module author ``M`` must +depend either on a type-class or type defined in ``N``. + +When an particular type-class method call is considered unsafe due to +overlapping instances, and the module being compiled is using ``-XSafe`` +or ``-XTrustworthy``, then compilation will fail. For ``-XUnsafe``, no +restriction is applied, and for modules using safe inference, they will +be inferred unsafe. + +.. _safe-imports: + +Safe Imports +------------ + +.. index:: + single: safe imports + +Safe Haskell enables a small extension to the usual import syntax of +Haskell, adding a ``safe`` keyword: + +:: + + impdecl -> import [safe] [qualified] modid [as modid] [impspec] + +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 ``-XSafe`` , ``-XTrustworthy`` , or +``-XUnsafe`` flags. When the ``-XSafe`` flag is used, the ``safe`` keyword is +allowed but meaningless, as every import is treated as a safe import. + +.. _safe-trust: + +Trust and Safe Haskell Modes +---------------------------- + +.. index:: + single: safe haskell trust + single: trust + +Safe Haskell introduces the following three language flags: + +- ``-XSafe`` — Enables the safe language dialect, asking GHC to guarantee trust. + The safe language dialect requires that all imports be trusted or a + compilation error will occur. Safe Haskell will also infer this safety type + for modules automatically when possible. Please refer to section + :ref:`safe-inference` for more details of this. + +- ``-XTrustworthy`` — 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. It does however + restrict the resolution of overlapping instances to only allow :ref:`safe + overlapping instances <safe-overlapping-instances>`. The trust guarantee is + provided by the module author, not GHC. An import statement with the ``safe`` + keyword results in a compilation error if the imported module is not trusted. + An import statement without the keyword behaves as usual and can import any + module whether trusted or not. + +- ``-XUnsafe`` — Marks the module being compiled as unsafe so that modules + compiled using ``-XSafe`` can't import it. You may want to explicitly mark a + module unsafe when it exports internal constructors that can be used to + violate invariants. + +While these are flags, they also correspond to Safe Haskell module types +that a module can have. You can think of using these as declaring an +explicit contract (or type) that a module must have. If it is invalid, +then compilation will fail. GHC will also infer the correct type for +Safe Haskell, please refer to section :ref:`safe-inference` for more +details. + +The procedure to check if a module is trusted or not depends on if the +``-fpackage-trust`` flag is present. The check is similar in both cases +with the ``-fpackage-trust`` flag enabling an extra requirement for +trustworthy modules to be regarded as trusted. + +Trust check (``-fpackage-trust`` disabled) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: trust check + +A module ``M`` in a package ``P`` is trusted by a client C if and only if: + +- Both of these hold: + + - The module was compiled with ``-XSafe`` + - All of M's direct imports are trusted by C + +- *or* all of these hold: + + - The module was compiled with ``-XTrustworthy`` + - All of ``M``\'s direct *safe imports* are trusted by C + +The above definition of trust has an issue. Any module can be compiled +with ``-XTrustworthy`` and it will be trusted. To control this, there is +an additional definition of package trust (enabled with the +``-fpackage-trust`` flag). The point of package trust is to require that +the client C explicitly say which packages are allowed to contain +trustworthy modules. Trustworthy packages are only trusted if they +reside in a package trusted by C. + +Trust check (``-fpackage-trust`` enabled) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: trust check + single: -fpackage-trust + +When the ``-fpackage-trust`` flag is enabled, whether or not a module is +trusted depends on if certain packages are trusted. Package trust is +determined by the client C invoking GHC (i.e. you). + +Specifically, a package *P is trusted* when one of these hold: + +- C's package database records that ``P`` is trusted (and no command-line + arguments override this) +- C's command-line flags say to trust ``P`` regardless of what is recorded + in the package database. + +In either case, C is the only authority on package trust. It is up to +the client to decide which `packages they trust <#safe-package-trust>`__. + +When the ``-fpackage-trust`` flag is used a *module M from package P is +trusted by a client C* if and only if: + +- Both of these hold: + + - The module was compiled with ``-XSafe`` + - All of ``M``\'s direct imports are trusted by C + +- *or* all of these hold: + + - The module was compiled with ``-XTrustworthy`` + - All of ``M``\'s direct safe imports are trusted by C + - Package ``P`` is trusted by C + +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 ``-XTrustworthy`` +compiled modules. + +The reason there are two modes of checking trust is that the extra +requirement enabled by ``-fpackage-trust`` causes the design of Safe +Haskell to be invasive. Packages using Safe Haskell when the flag is +enabled may or may not compile depending on the state of trusted +packages on a users machine. This is both fragile, and causes +compilation failures for everyone, even if they aren't trying to use any +of the guarantees provided by Safe Haskell. Disabling +``-fpackage-trust`` by default and turning it into a flag makes Safe +Haskell an opt-in extension rather than an always on feature. + +.. _safe-trust-example: + +Example +~~~~~~~ + +:: + + Package Wuggle: + {-# LANGUAGE Safe #-} + module Buggle where + import Prelude + f x = ...blah... + + Package P: + {-# LANGUAGE Trustworthy #-} + module M where + import System.IO.Unsafe + import safe Buggle + +Suppose a client C decides to trust package ``P`` and package ``base``. Then +does C trust module ``M``? Well ``M`` is marked ``-XTrustworthy``, so we don't +restrict the language. However, we still must check ``M``\'s imports: + +- First, ``M`` imports ``System.IO.Unsafe``. This is an unsafe module, however + ``M`` was compiled with ``-XTrustworthy`` , so ``P``\'s author takes + responsibility for that import. ``C`` trusts ``P``\'s author, so this import + is fine. + +- Second, ``M`` safe imports ``Buggle``. For this import ``P``\'s author takes + no responsibility for the safety, instead asking GHC to check whether + ``Buggle`` is trusted by ``C``. Is it? + +- ``Buggle``, is compiled with ``-XSafe``, so the code is machine-checked to be + OK, but again under the assumption that all of ``Buggle``\'s imports are + trusted by ``C``. We must recursively check all imports! + +- Buggle only imports ``Prelude``, which is compiled with ``-XTrustworthy``. + ``Prelude`` resides in the ``base`` package, which ``C`` trusts, and (we'll + assume) all of ``Prelude``\'s imports are trusted. So ``C`` trusts + ``Prelude``, and so ``C`` also trusts Buggle. (While ``Prelude`` is typically + imported implicitly, it still obeys the same rules outlined here). + +Notice that C didn't need to trust package Wuggle; the machine checking +is enough. C only needs to trust packages that contain ``-XTrustworthy`` +modules. + +.. _trustworthy-guarantees: + +Trustworthy Requirements +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: trustworthy + +Module authors using the ``-XTrustworthy`` language extension for a module ``M`` +should ensure that ``M``\'s public API (the symbols exposed by its export list) +can't be used in an unsafe manner. This mean that symbols exported should +respect type safety and referential transparency. + +.. _safe-package-trust: + +Package Trust +~~~~~~~~~~~~~ + +.. index:: + single: package trust + +Safe Haskell gives packages a new Boolean property, that of trust. +Several new options are available at the GHC command-line to specify the +trust property of packages: + +- ``-trust ⟨pkg⟩`` — Exposes package ⟨pkg⟩ if it was hidden and considers it a + trusted package regardless of the package database. + +- ``-distrust ⟨pkg⟩`` — Exposes package ⟨pkg⟩ if it was hidden and considers it + an untrusted package regardless of the package database. + +- ``-distrust-all-packages`` — Considers all packages distrusted unless they are + explicitly set to be trusted by subsequent command-line options. + +To set a package's trust property in the package database please refer +to :ref:`packages`. + +.. _safe-inference: + +Safe Haskell Inference +---------------------- + +.. index:: + single: safe inference + +In the case where a module is compiled without one of ``-XSafe``, +``-XTrustworthy`` or ``-XUnsafe`` being used, GHC will try to figure out +itself if the module can be considered safe. This safety inference will +never mark a module as trustworthy, only as either unsafe or as safe. +GHC uses a simple method to determine this for a module M: If M would +compile without error under the ``-XSafe`` flag, then M is marked as +safe. Otherwise, it is marked as unsafe. + +When should you use Safe Haskell inference and when should you use an +explicit ``-XSafe`` flag? The later case should be used when you have a +hard requirement that the module be safe. This is most useful for the +:ref:`safe-use-cases` of Safe Haskell: running untrusted code. Safe +inference is meant to be used by ordinary Haskell programmers. Users who +probably don't care about Safe Haskell. + +Haskell library authors have a choice. Most should just use Safe +inference. Assuming you avoid any unsafe features of the language then +your modules will be marked safe. Inferred vs. Explicit has the +following trade-offs: + +- *Inferred* — This works well and adds no dependencies on the Safe Haskell type + of any modules in other packages. It does mean that the Safe Haskell type of + your own modules could change without warning if a dependency changes. One + way to deal with this is through the use of :ref:`Safe Haskell warning flags + <safe-flag-summary>` that will warn if GHC infers a Safe Haskell type + different from expected. + +- *Explicit* — This gives your library a stable Safe Haskell type that others + can depend on. However, it will increase the chance of compilation failure + when your package dependencies change. + +.. _safe-flag-summary: + +Safe Haskell Flag Summary +------------------------- + +.. index:: + single: Safe Haskell flags + +In summary, Safe Haskell consists of the following three language flags: + +``-XSafe`` + .. index:: + single: -XSafe + + Restricts the module to the safe language. All of the module's + direct imports must be trusted, but the module itself need not + reside in a trusted package, because the compiler vouches for its + trustworthiness. The "safe" keyword is allowed but meaningless in + import statements, as regardless, every import is required to be + safe. + + - *Module Trusted* — Yes + - *Haskell Language* — Restricted to Safe Language + - *Imported Modules* — All forced to be safe imports, all must be trusted. + +``-XTrustworthy`` + .. index:: + single: -XTrustworthy + + This establishes that the module is trusted, but the guarantee is + provided by the module's author. A client of this module then + specifies that they trust the module author by specifying they trust + the package containing the module. ``-XTrustworthy`` doesn't restrict the + module to the safe language. It does however restrict the resolution of + overlapping instances to only allow :ref:`safe overlapping instances + <safe-overlapping-instances>`. It also allows the use of the safe import + keyword. + + - *Module Truste* — Yes. + - *Module Truste* (``-fpackage-trust`` enabled) — Yes but only if the package + the module resides in is also trusted. + - *Haskell Languag* — Unrestricted, except only safe overlapping instances + allowed. + - *Imported Modules* — Under control of module author which ones must be + trusted. + +``-XUnsafe`` + .. index:: + single: -XUnsafe + + Mark a module as unsafe so that it can't be imported by code + compiled with ``-XSafe``. Also enable the Safe Import extension so that a + module can require + a dependency to be trusted. + + - *Module Trusted* — No + - *Haskell Language* — Unrestricted + - *Imported Modules* — Under control of module author which ones must be + trusted. + +And one general flag: + +``-fpackage-trust`` + When enabled, turn on an extra check for a trustworthy module ``M``, + requiring the package that ``M`` resides in be considered trusted, for ``M`` + to be considered trusted. + +And three warning flags: + +``-fwarn-unsafe`` + Issue a warning if the module being compiled is regarded to be + unsafe. Should be used to check the safety type of modules when + using safe inference. + +``-fwarn-safe`` + Issue a warning if the module being compiled is regarded to be safe. + Should be used to check the safety type of modules when using safe + inference. + +``-fwarn-trustworthy-safe`` + Issue a warning if the module being compiled is marked as + -XTrustworthy but it could instead be marked as + -XSafe , a more informative bound. Can be used to detect once a Safe Haskell + bound can be improved as dependencies are updated. + +.. _safe-compilation: + +Safe Compilation +---------------- + +.. index:: + single: safe compilation + +GHC includes a variety of flags that allow arbitrary processes to be run +at compilation time. One such example is the +:ref:`custom pre-processor <pre-processor>` flag. Another is the ability of +Template Haskell to execute Haskell code at compilation time, including +IO actions. Safe Haskell *does not address this danger* (although, +Template Haskell is a disallowed feature). + +Due to this, it is suggested that when compiling untrusted source code +that has had no manual inspection done, the following precautions be +taken: + +- Compile in a sandbox, such as a chroot or similar container + technology. Or simply as a user with very reduced system access. + +- Compile untrusted code with the ``-XSafe`` + flag being specified on the command line. This will ensure that + modifications to the source being compiled can't disable the use of + the Safe Language as the command line flag takes precedence over a + source level pragma. + +- Ensure that all untrusted code is imported as a + :ref:`safe import <safe-imports>` + and that the ``-fpackage-trust`` :ref:`flag <safe-package-trust>` is used + with packages from untrusted sources being marked as untrusted. + +There is a more detailed discussion of the issues involved in +compilation safety and some potential solutions on the +:ghc-wiki:`GHC Wiki <SafeHaskell/SafeCompilation>`. + +Additionally, the use of :ref:`annotations <annotation-pragmas>` is forbidden, +as that would allow bypassing Safe Haskell restrictions. See :ghc-ticket:`10826` +for details. diff --git a/docs/users_guide/safe_haskell.xml b/docs/users_guide/safe_haskell.xml deleted file mode 100644 index 02182d3b8e..0000000000 --- a/docs/users_guide/safe_haskell.xml +++ /dev/null @@ -1,964 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<sect1 id="safe-haskell"> - <title>Safe Haskell</title> - <indexterm><primary>safe haskell</primary></indexterm> - - <para> - Safe Haskell is an extension to the Haskell language that is implemented in - GHC as of version 7.2. It allows for unsafe code to be securely included in a - trusted code base by restricting the features of GHC Haskell the code is - allowed to use. Put simply, it makes the types of programs trustable. - </para> - - <para> - While a primary use case of Safe Haskell is running untrusted code, Safe - Haskell doesn't provide this directly. Instead, Safe Haskell provides strict - type safety. Without Safe Haskell, GHC allows many exceptions to the type - system which can subvert any abstractions. By providing strict type safety, - Safe Haskell enables developers to build their own library level sandbox - mechanisms to run untrusted code. - </para> - - <para> - While Safe Haskell is an extension, it actually runs in the background for - every compilation with GHC. It does this to track the type violations of - modules to infer their safety, even when they aren't explicitly using Safe - Haskell. Please refer to section <xref linkend="safe-inference"/> for more - details of this. - </para> - - <para> - The design of Safe Haskell covers the following aspects: - - <itemizedlist> - <listitem>A <link linkend="safe-language">safe language</link> dialect of - Haskell that provides stricter guarantees about the code. It allows types - and module boundaries to be trusted. - </listitem> - <listitem>A <emphasis>safe import</emphasis> extension that specifies that - 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> - </para> - - <para> - Safe Haskell, however, <emphasis>does not offer</emphasis> compilation - safety. During compilation time it is possible for arbitrary processes to be - launched, using for example the <link linkend="pre-processor">custom - pre-processor</link> flag. This can be manipulated to either compromise a - users system at compilation time, or to modify the source code just before - compilation to try to alter Safe Haskell flags. This is discussed further in - section <xref linkend="safe-compilation"/>. - </para> - - <sect2 id="safe-use-cases"> - <title>Uses of Safe Haskell</title> - <indexterm><primary>safe haskell uses</primary></indexterm> - - <para> - Safe Haskell has been designed with two use cases in mind: - - <itemizedlist> - <listitem>Enforcing strict type safety at compile time</listitem> - <listitem>Compiling and executing untrusted code</listitem> - </itemizedlist> - </para> - - <sect3> - <title>Strict type-safety (good style)</title> - - Haskell offers a powerful type system and separation of pure and - effectual functions through the <literal>IO</literal> monad. However, - there are several loop holes in the type system, the most obvious being - the <literal>unsafePerformIO :: IO a -> a</literal> function. The safe - language dialect of Safe Haskell disallows the use of such functions. - This can be useful restriction as it makes Haskell code easier to analyse - and reason about. It also codifies the existing culture in the Haskell - community of trying to avoid unsafe functions unless absolutely - necessary. As such, using the safe language (through the - <option>-XSafe</option> flag) can be thought of as a way of enforcing - good style, similar to the function of <option>-Wall</option>. - </sect3> - - <sect3> - <title>Building secure systems (restricted IO Monads)</title> - <indexterm><primary>secure haskell</primary></indexterm> - - <para> - Systems such as information flow control security, capability based - security systems and DSLs for working with encrypted data.. etc can be - built in the Haskell language as a library. However they require - guarantees about the properties of Haskell that aren't true in general - due to the presence of functions like <literal>unsafePerformIO - </literal>. Safe Haskell gives users enough guarantees about the type - system to allow them to build such secure systems. - </para> - - <para> - As an example, lets define an interface for a plugin system where the - plugin authors are untrusted, possibly malicious third-parties. We do - this by restricting the plugin interface to pure functions or to a - restricted <literal>IO</literal> monad that we have defined. The - restricted <literal>IO</literal> monad will only allow a safe subset of - <literal>IO</literal> actions to be executed. We define the plugin - interface so that it requires the plugin module, - <literal>Danger</literal>, to export a single computation, - <literal>Danger.runMe</literal>, of type <literal>RIO ()</literal>, where - <literal>RIO</literal> is a monad defined as follows: - </para> - - <programlisting> - -- While we use `Safe', the `Trustworthy' pragma would also be - -- fine. We simply want to ensure that: - -- 1) The module exports an interface that untrusted code can't - -- abuse. - -- 2) Untrusted code can import this module. - -- - {-# LANGUAGE Safe #-} - - module RIO (RIO(), runRIO, rioReadFile, rioWriteFile) where - - -- Notice that symbol UnsafeRIO is not exported from this module! - newtype RIO a = UnsafeRIO { runRIO :: IO a } - - instance Monad RIO where - return = UnsafeRIO . return - (UnsafeRIO m) >>= k = UnsafeRIO $ m >>= runRIO . k - - -- Returns True iff access is allowed to file name - pathOK :: FilePath -> IO Bool - pathOK file = {- Implement some policy based on file name -} - - rioReadFile :: FilePath -> RIO String - rioReadFile file = UnsafeRIO $ do - ok <- pathOK file - if ok then readFile file else return "" - - rioWriteFile :: FilePath -> String -> RIO () - rioWriteFile file contents = UnsafeRIO $ do - ok <- pathOK file - if ok then writeFile file contents else return () - </programlisting> - - We then compile the <literal>Danger</literal> plugin using the new Safe - Haskell <option>-XSafe</option> flag: - - <programlisting> - {-# LANGUAGE Safe #-} - module Danger ( runMe ) where - - runMe :: RIO () - runMe = ... - </programlisting> - - <para> - Before going into the Safe Haskell details, lets point out some of the - reasons this security mechanism would fail without Safe Haskell: - </para> - - <itemizedlist> - <listitem>The design attempts to restrict the operations that - <literal>Danger</literal> can perform by using types, specifically - the <literal>RIO</literal> type wrapper around <literal>IO</literal>. - The author of <literal>Danger</literal> can subvert this though by - simply writing arbitrary <literal>IO</literal> actions and using - <literal>unsafePerformIO :: IO a -> a</literal> to execute them as - pure functions. - </listitem> - <listitem>The design also relies on <literal>Danger</literal> not being - able to access the <literal>UnsafeRIO</literal> constructor. - Unfortunately Template Haskell can be used to subvert module - boundaries and so could be used to gain access to this constructor. - </listitem> - <listitem>There is no way to place restrictions on the modules that - <literal>Danger</literal> can import. This gives the author of - <literal>Danger</literal> a very large attack surface, essentially - any package currently installed on the system. Should any of these - packages have a vulnerability, then the <literal>Danger</literal> - module can exploit it. - </listitem> - </itemizedlist> - - <para> - Safe Haskell prevents all these attacks. This is done by compiling the - RIO module with the <option>-XSafe</option> or - <option>-XTrustworthy</option> flag and compiling - <literal>Danger</literal> with the <option>-XSafe</option> flag. We - explain each below. - </para> - - <para> - The use of <option>-XSafe</option> to compile - <literal>Danger</literal> restricts the features of Haskell that can be used - to a <link linkend="safe-language">safe subset</link>. This - includes disallowing <literal>unsafePerformIO</literal>, - Template Haskell, pure FFI functions, RULES and restricting the - operation of Overlapping Instances. The <option>-XSafe</option> - flag also restricts the modules can be imported by - <literal>Danger</literal> to only those that are considered trusted. - Trusted modules are those compiled with <option>-XSafe</option>, where - GHC provides a mechanical guarantee that the code is safe. Or those - modules compiled with <option>-XTrustworthy</option>, where the module - author claims that the module is Safe. - </para> - - <para> - This is why the RIO module is compiled with <option>-XSafe</option> or - <option>-XTrustworthy</option>>, to allow the <literal>Danger</literal> - module to import it. The <option>-XTrustworthy</option> flag doesn't - place any restrictions on the module like <option>-XSafe</option> does - (expect to restrict overlapping instances to - <link linkend="safe-overlapping-instances">safe overlapping - instances</link>). Instead the module author claims that while code - may use unsafe features internally, it only exposes an API that can used - in a safe manner. - </para> - - <para> - However, the unrestricted use of <option>-XTrustworthy</option> is a - problem as an arbitrary module can use it to mark themselves as - trusted, yet <option>-XTrustworthy</option> doesn't offer any - guarantees about the module, unlike <option>-XSafe</option>. - - To control the use of trustworthy modules it is recommended to use the - <option>-fpackage-trust</option> flag. This flag adds an extra - requirement to the trust check for trustworthy modules. - - It requires that for a trustworthy modules to be considered trusted, and - allowed to be used in <option>-XSafe</option> compiled code, the client C - compiling the code must tell GHC that they trust the package the - trustworthy module resides in. - - This is essentially a way of for C to say, while this package contains - trustworthy modules that can be used by untrusted modules compiled with - <option>-XSafe</option>, I trust the author(s) of this package and trust - the modules only expose a safe API. The trust of a package can be - changed at any time, so if a vulnerability found in a package, C can - declare that package untrusted so that any future compilation against - that package would fail. For a more detailed overview of this mechanism - see <xref linkend="safe-trust"/>. - </para> - - <para> - In the example, <literal>Danger</literal> can import module - <literal>RIO</literal> because <literal>RIO</literal> is compiled with - <option>-XSafe</option>. Thus, <literal>Danger</literal> can make use of - the <literal>rioReadFile</literal> and <literal>rioWriteFile</literal> - functions to access permitted file names. The main application then - imports both <literal>RIO</literal> and <literal>Danger</literal>. To run - the plugin, it calls <literal>RIO.runRIO Danger.runMe</literal> within - the <literal>IO</literal> monad. The application is safe in the knowledge - that the only <literal>IO</literal> to ensue will be to files whose paths - were approved by the <literal>pathOK</literal> test. - </para> - </sect3> - </sect2> - - <sect2 id="safe-language"> - <title>Safe Language</title> - <indexterm><primary>safe language</primary></indexterm> - - The Safe Haskell <emphasis>safe language</emphasis> (enabled by - <option>-XSafe</option>) guarantees the following properties: - - <itemizedlist> - <listitem><emphasis>Referential transparency</emphasis> — The types - can be trusted. Any pure function, is guaranteed to be pure. Evaluating - them is deterministic and won't cause any side effects. Functions in - the <literal>IO</literal> monad are still allowed and behave as usual. - So, for example, the <literal>unsafePerformIO :: IO a -> a</literal> - function is disallowed in the safe language to enforce this property. - </listitem> - - <listitem><emphasis>Module boundary control</emphasis> — Only - symbols that are publicly available through other module export lists - can be accessed in the safe language. Values using data constructors - not exported by the defining module, cannot be examined or created. As - such, if a module M establishes some invariants through careful use of - its export list, then code written in the safe language that imports M - is guaranteed to respect those invariants. - </listitem> - - <listitem><emphasis>Semantic consistency</emphasis> — For any - module that imports a module written in the safe language, expressions - that compile both with and without the safe import have the same - meaning in both cases. That is, importing a module written in the safe - language cannot change the meaning of existing code that isn't - dependent on that module. So, for example, there are some restrictions - placed on the use of <emphasis><link linkend="instance-overlap"> - Overlapping Instances</link></emphasis>, as these can violate this - property. - </listitem> - - <listitem><emphasis>Strict subset</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. - </listitem> - </itemizedlist> - - <para> - These four properties guarantee that in the safe language you can trust the - types, can trust that module export lists are respected, and can trust that - code that successfully compiles has the same meaning as it normally would. - </para> - - <para> - To achieve these properties, in the safe language dialect we disable - completely the following features: - <itemizedlist> - <listitem><emphasis>TemplateHaskell</emphasis> — Can be used to - gain access to constructors and abstract data types that weren't - exported by a module, subverting module boundaries. - </listitem> - </itemizedlist> - </para> - - <para> - Furthermore, we restrict the following features: - <itemizedlist> - <listitem><emphasis>ForeignFunctionInterface</emphasis> — Foreign - import declarations that import a function with a non-IO type are - disallowed. - </listitem> - - <listitem><emphasis>RULES</emphasis> — RULES defined in a module M - compiled with <option>-XSafe</option> are dropped. RULES defined in - trustworthy modules that M imports are still valid and will fire as - usual. - </listitem> - - <listitem><emphasis>OverlappingInstances</emphasis> — There is no - restriction on the creation of overlapping instances, but we do - restrict their use at a particular call site. This is a detailed - restriction, please refer to - <link linkend="safe-overlapping-instances">Safe Overlapping Instances - </link> for details. - </listitem> - - <listitem><emphasis>GeneralisedNewtypeDeriving</emphasis> — GND is - not allowed in the safe language. This is due to the ability of it to - violate module boundaries when module authors forget to put nominal - role annotations on their types as appropriate. For this reason, the - <literal>Data.Coerce</literal> module is also considered unsafe. We are - hoping to find a better solution here in the future. - </listitem> - - <listitem><emphasis>Data.Typeable</emphasis> — Hand crafted - instances of the Typeable type class are not allowed in Safe Haskell as - this can easily be abused to unsafely coerce between types. Derived - instances (through the <link linkend="deriving-typeable"><option> - -XDeriveDataTypeable</option></link> extension) are still allowed. - </listitem> - </itemizedlist> - </para> - - <sect3 id="safe-overlapping-instances"> - <title>Safe Overlapping Instances</title> - - <para> - Due to the semantic consistency guarantee of Safe Haskell, we must - restrict the function of overlapping instances. We don't restrict their - ability to be defined, as this is a global property and not something we - can determine by looking at a single module. Instead, when a module calls - a function belonging to a type-class, we check that the instance - resolution done is considered 'safe'. This check is enforced for modules - compiled with both <option>-XSafe</option> and - <option>-XTrustworthy</option>. - </para> - - <para> - More specifically, consider the following modules: - - <programlisting> - {-# LANGUAGE Safe #-} - module Class (TC(..)) where - class TC a where { op :: a -> String } - - {-# LANGUAGE Safe #-} - module Dangerous (TC(..)) where - import Class - - instance - {-# OVERLAPS #-} - TC [Int] where { op _ = "[Int]" } - - {-# LANGUAGE Safe #-} - module TCB_Runner where - import Class - import Dangerous - - instance - TC [a] where { op _ = "[a]" } - - f :: String - f = op ([1,2,3,4] :: [Int]) - </programlisting> - - Both module Class and module Dangerous will compile under - <option>-XSafe</option> without issue. However, in module TCB_Runner, we - must check if the call to <literal>op</literal> in function - <literal>f</literal> is safe. - </para> - - <para> - What does it mean to be Safe? That importing a module compiled with - <option>-XSafe</option> shouldn't change the meaning of code that - compiles fine without importing the module. This is the Safe Haskell - property known as <emphasis>semantic consistency</emphasis>. - </para> - - <para> - In our situation, module TCB_Runner compiles fine without importing - module Dangerous. So when deciding which instance to use for the call to - <literal>op</literal>, if we determine the instance <literal>TC - [Int]</literal> from module Dangerous is the most specific, this is - unsafe. This prevents code written by third-parties we don't trust (which - is compiled using <option>-XSafe</option> in Safe Haskell) from changing - the behaviour of our existing code. - </para> - - <para> - Specifically, we apply the following rule to determine if a type-class - method call is <emphasis>unsafe</emphasis> when overlapping instances are - involved: - - <itemizedlist> - <listitem>Most specific instance, <literal>Ix</literal>, defined in an - `-XSafe` compiled module. - </listitem> - - <listitem><literal>Ix</literal> is an orphan instance or a - multi-parameter-type-class. - </listitem> - - <listitem>At least one overlapped instance, <literal>Iy</literal>, is both: - <itemizedlist> - <listitem>From a different module than <literal>Ix</literal></listitem> - <listitem><literal>Iy</literal> is not marked - <option>OVERLAPPABLE</option></listitem> - </itemizedlist> - </listitem> - </itemizedlist> - - This is a slightly involved heuristic, but captures the situation of an - imported module N changing the behaviour of existing code. For example, if - the second condition isn't violated, then the module author M must depend - either on a type-class or type defined in N. - </para> - - <para> - When an particular type-class method call is considered unsafe due to - overlapping instances, and the module being compiled is using - <option>-XSafe</option> or <option>-XTrustworthy</option>, then - compilation will fail. For <option>-XUnsafe</option>, no restriction is - applied, and for modules using safe inference, they will be inferred - unsafe. - </para> - </sect3> - - </sect2> - - <sect2 id="safe-imports"> - <title>Safe Imports</title> - <indexterm><primary>safe imports</primary></indexterm> - - 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 <option>-XSafe</option>, - <option>-XTrustworthy</option>, or <option>-XUnsafe</option> flags. When - the <option>-XSafe</option> flag is used, the safe keyword is allowed but - meaningless, as every import is treated as a safe import. - </sect2> - - <sect2 id="safe-trust"> - <title>Trust and Safe Haskell Modes</title> - <indexterm><primary>safe haskell trust</primary></indexterm> - <indexterm><primary>trust</primary></indexterm> - - Safe Haskell introduces the following three 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 compilation error will occur. - Safe Haskell will also infer this safety type for modules automatically - when possible. Please refer to section <xref linkend="safe-inference"/> - for more details of this. - </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. It does however restrict the - resolution of overlapping instances to only allow - <link linkend="safe-overlapping-instances">safe overlapping - instances</link>. The trust guarantee is provided by the module - author, not GHC. An import statement with the safe keyword results in a - compilation error if the imported module is not trusted. An import - statement without the keyword behaves as usual and can import any - module whether trusted or not. - </listitem> - - <listitem><emphasis>-XUnsafe</emphasis> — Marks the module being - compiled as unsafe so that modules compiled using - <option>-XSafe</option> can't import it. You may want to explicitly - mark a module unsafe when it exports internal constructors that can be - used to violate invariants. - </listitem> - </itemizedlist> - - <para> - While these are flags, they also correspond to Safe Haskell module types - that a module can have. You can think of using these as declaring an - explicit contract (or type) that a module must have. If it is invalid, then - compilation will fail. GHC will also infer the correct type for Safe - Haskell, please refer to section <xref linkend="safe-inference"/> for more - details. - </para> - - <para> - The procedure to check if a module is trusted or not depends on if the - <option>-fpackage-trust</option> flag is present. The check is similar in - both cases with the <option>-fpackage-trust</option> flag enabling an extra - requirement for trustworthy modules to be regarded as trusted. - </para> - - <sect3> - <title>Trust check (<option>-fpackage-trust</option> disabled)</title> - <indexterm><primary>trust check</primary></indexterm> - - <para> - A <emphasis>module M in a package P is trusted by a client C</emphasis> - if and only if: - - <itemizedlist> - <listitem>Both of these hold: - <itemizedlist> - <listitem>The module was compiled with <option>-XSafe</option> - </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 - <option>-XTrustworthy</option></listitem> - <listitem>All of M's direct <emphasis>safe imports</emphasis>are trusted by - C</listitem> - </itemizedlist> - </listitem> - </itemizedlist> - </para> - - <para> - The above definition of trust has an issue. Any module can be compiled - with <option>-XTrustworthy</option> and it will be trusted. To control - this, there is an additional definition of package trust (enabled with the - <option>-fpackage-trust</option> flag). The point of package trust is to - require that the client C explicitly say which packages are allowed to - contain trustworthy modules. Trustworthy packages are only trusted if - they reside in a package trusted by C. - </para> - </sect3> - - <sect3> - <title>Trust check (<option>-fpackage-trust</option> enabled)</title> - <indexterm><primary>trust check</primary></indexterm> - <indexterm><primary>-fpackage-trust</primary></indexterm> - - <para> - When the <option>-fpackage-trust</option> flag is enabled, whether or not - a module is trusted depends on if certain packages are trusted. Package - trust is determined by the client C invoking GHC (i.e. you). - </para> - - <para> - Specifically, a package <emphasis>P is trusted</emphasis> when one of - these 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 P regardless of what is - recorded in the package database.</listitem> - </itemizedlist> - </para> - - <para> - In either case, C is the only authority on package trust. It is up to the - client to decide which <link linkend="safe-package-trust">packages they - trust</link>. - </para> - - <para> - When the <option>-fpackage-trust</option> flag is used a <emphasis>module M from - package P is trusted by a client C</emphasis> if and only if: - - <itemizedlist> - <listitem>Both of these hold: - <itemizedlist> - <listitem> The module was compiled with <option>-XSafe</option> - </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 - <option>-XTrustworthy</option></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> - </para> - - <para> - 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 - <literal>-XTrustworthy</literal> compiled modules. - </para> - - <para> - The reason there are two modes of checking trust is that the extra - requirement enabled by <option>-fpackage-trust</option> causes the design - of Safe Haskell to be invasive. Packages using Safe Haskell when the flag - is enabled may or may not compile depending on the state of trusted - packages on a users machine. This is both fragile, and causes compilation - failures for everyone, even if they aren't trying to use any of the - guarantees provided by Safe Haskell. Disabling - <option>-fpackage-trust</option> by default and turning it into a flag - makes Safe Haskell an opt-in extension rather than an always on feature. - </para> - </sect3> - - <sect3 id="safe-trust-example"> - <title>Example</title> - - <programlisting> - Package Wuggle: - {-# LANGUAGE Safe #-} - module Buggle where - import Prelude - f x = ...blah... - - Package P: - {-# LANGUAGE Trustworthy #-} - module M where - import System.IO.Unsafe - import safe Buggle - </programlisting> - - <para> - Suppose a client C decides to trust package P and package base. Then does - C trust module M? Well M is marked <option>-XTrustworthy</option>, so we - don't restrict the language. However, we still must check M's imports: - <itemizedlist> - <listitem>First, M imports System.IO.Unsafe. This is an unsafe module, - however M was compiled with <option>-XTrustworthy</option>, so P's - author takes responsibility for that import. C trusts P's author, so - this import is fine. - </listitem> - - <listitem> - Second, M safe imports Buggle. For this import P's author takes no - responsibility for the safety, instead asking GHC to check whether - Buggle is trusted by C. Is it? - </listitem> - - <listitem> - Buggle, is compiled with <option>-XSafe</option>, so the code is - machine-checked to be OK, but again under the assumption that all of - Buggle's imports are trusted by C. We must recursively check all - imports! - </listitem> - - <listitem> - Buggle only imports Prelude, which is compiled with - <option>-XTrustworthy</option>. Prelude resides in the base package, - which C trusts, and (we'll assume) all of Prelude's imports are - trusted. So C trusts Prelude, and so C also trusts Buggle. (While - Prelude is typically imported implicitly, it still obeys the same - rules outlined here). - </listitem> - </itemizedlist> - </para> - - <para> - Notice that C didn't need to trust package Wuggle; the machine checking - is enough. C only needs to trust packages that contain - <option>-XTrustworthy</option> modules. - </para> - </sect3> - - <sect3 id="trustworthy-guarantees"> - <title>Trustworthy Requirements</title> - <indexterm><primary>trustworthy</primary></indexterm> - - Module authors using the <option>-XTrustworthy</option> language - extension for a module M should ensure that M's public API (the symbols - exposed by its export list) can't be used in an unsafe manner. This mean - that symbols exported should respect type safety and referential - transparency. - </sect3> - - <sect3 id="safe-package-trust"> - <title>Package Trust</title> - <indexterm><primary>package trust</primary></indexterm> - - Safe Haskell gives packages a new Boolean property, that of trust. - Several new options are available at the GHC command-line to specify the - trust property of packages: - - <itemizedlist> - <listitem><emphasis>-trust P</emphasis> — Exposes package P if it was - hidden and considers it a trusted package regardless of the package - database.</listitem> - <listitem><emphasis>-distrust P</emphasis> — Exposes package P if it - was hidden and considers it an untrusted package regardless of the - package database.</listitem> - <listitem><emphasis>-distrust-all-packages</emphasis> — Considers all - packages distrusted unless they are explicitly set to be trusted by - subsequent command-line options.</listitem> - </itemizedlist> - - To set a package's trust property in the package database please refer to - <xref linkend="packages"/>. - </sect3> - - </sect2> - - <sect2 id="safe-inference"> - <title>Safe Haskell Inference</title> - <indexterm><primary>safe inference</primary></indexterm> - - <para> - In the case where a module is compiled without one of - <option>-XSafe</option>, <option>-XTrustworthy</option> or - <option>-XUnsafe</option> being used, GHC will try to figure out itself if - the module can be considered safe. This safety inference will never mark a - module as trustworthy, only as either unsafe or as safe. GHC uses a simple - method to determine this for a module M: If M would compile without error - under the <option>-XSafe</option> flag, then M is marked as safe. - Otherwise, it is marked as unsafe. - </para> - - <para> - When should you use Safe Haskell inference and when should you use an - explicit <option>-XSafe</option> flag? The later case should be used when - you have a hard requirement that the module be safe. This is most useful - for the <xref linkend="safe-use-cases">security use case</xref> of Safe - Haskell: running untrusted code. Safe inference is meant to be used by - ordinary Haskell programmers. Users who probably don't care about Safe - Haskell. - </para> - - <para> - Haskell library authors have a choice. Most should just use Safe inference. - Assuming you avoid any unsafe features of the language then your modules - will be marked safe. Inferred vs. Explicit has the following trade-offs: - </para> - - <itemizedlist> - <listitem><emphasis>Inferred</emphasis> — This works well and adds no - dependencies on the Safe Haskell type of any modules in other packages. - It does mean that the Safe Haskell type of your own modules could - change without warning if a dependency changes. One way to deal with - this is through the use of <xref linkend="safe-flag-summary">Safe - Haskell warning flags</xref> that will warn if GHC infers a Safe - Haskell type different from expected.</listitem> - <listitem><emphasis>Explicit</emphasis> — This gives your library a - stable Safe Haskell type that others can depend on. However, it will - increase the chance of compilation failure when your package - dependencies change.</listitem> - </itemizedlist> - </sect2> - - <sect2 id="safe-flag-summary"> - <title>Safe Haskell Flag Summary</title> - <indexterm><primary>safe haskell flags</primary></indexterm> - - In summary, Safe Haskell consists of the following three language flags: - - <variablelist> - <varlistentry> - <term>-XSafe</term> - <indexterm><primary>-XSafe</primary></indexterm> - <listitem>Restricts the module to the safe language. All of the - module's direct imports must be trusted, but the module itself need - not reside in a trusted package, because the compiler vouches for its - trustworthiness. The "safe" keyword is allowed but meaningless in - import statements, as regardless, every import is required to be - safe. - <itemizedlist> - <listitem><emphasis>Module Trusted</emphasis> — Yes</listitem> - <listitem><emphasis>Haskell Language</emphasis> — Restricted to - Safe Language</listitem> - <listitem><emphasis>Imported Modules</emphasis> — All forced to be - safe imports, all must be trusted.</listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>-XTrustworthy</term> - <indexterm><primary>-XTrustworthy</primary></indexterm> - <listitem>This establishes that the module is trusted, but the - guarantee is provided by the module's author. A client of this module - then specifies that they trust the module author by specifying they - trust the package containing the module. - <option>-XTrustworthy</option> doesn't restrict the module to the - safe language. It does however restrict the resolution of overlapping - instances to only allow <link linkend="safe-overlapping-instances"> - safe overlapping instances</link>. It also allows the use of the safe - import keyword. - - <itemizedlist> - <listitem><emphasis>Module Trusted</emphasis> — Yes.</listitem> - <listitem><emphasis>Module Trusted - (<option>-fpackage-trust</option> enabled)</emphasis> — Yes but - only if the package the module resides in is also - trusted.</listitem> - <listitem><emphasis>Haskell Language</emphasis> — Unrestricted, - except only <link linkend="safe-overlapping-instances">safe - overlapping instances</link> allowed. - </listitem> - <listitem><emphasis>Imported Modules</emphasis> — Under control of - module author which ones must be trusted.</listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>-XUnsafe</term> - <indexterm><primary>-XUnsafe</primary></indexterm> - <listitem>Mark a module as unsafe so that it can't be imported by code - compiled with <option>-XSafe</option>. Also enable the Safe Import - extension so that a module can require a dependency to be trusted. - <itemizedlist> - <listitem><emphasis>Module Trusted</emphasis> — No</listitem> - <listitem><emphasis>Haskell Language</emphasis> — - Unrestricted</listitem> - <listitem><emphasis>Imported Modules</emphasis> — Under control of - module author which ones must be trusted.</listitem> - </itemizedlist> - </listitem> - </varlistentry> - - </variablelist> - - And one general flag: - - <variablelist> - <varlistentry> - <term>-fpackage-trust</term> - <indexterm><primary>-fpackage-trust</primary></indexterm> - <listitem>When enabled, turn on an extra check for a trustworthy module - M, requiring the package that M resides in be considered trusted, for - M to be considered trusted. - </listitem> - </varlistentry> - </variablelist> - - And three warning flags: - - <variablelist> - <varlistentry> - <term>-fwarn-unsafe</term> - <indexterm><primary>-fwarn-unsafe</primary></indexterm> - <listitem>Issue a warning if the module being compiled is regarded to - be unsafe. Should be used to check the safety type of modules when - using safe inference. - </listitem> - </varlistentry> - <varlistentry> - <term>-fwarn-safe</term> - <indexterm><primary>-fwarn-safe</primary></indexterm> - <listitem>Issue a warning if the module being compiled is regarded to - be safe. Should be used to check the safety type of modules when - using safe inference. - </listitem> - </varlistentry> - <varlistentry> - <term>-fwarn-trustworthy-safe</term> - <indexterm><primary>-fwarn-trustworthy-safe</primary></indexterm> - <listitem>Issue a warning if the module being compiled is marked as - <option>-XTrustworthy</option> but it could instead be marked as - <option>-XSafe</option>, a more informative bound. Can be used to - detect once a Safe Haskell bound can be improved as dependencies are - updated.</listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="safe-compilation"> - <title>Safe Compilation</title> - <indexterm><primary>safe compilation</primary></indexterm> - - <para> - GHC includes a variety of flags that allow arbitrary processes to be run at - compilation time. One such example is the - <link linkend="pre-processor">custom pre-processor</link> flag. Another is - the ability of Template Haskell to execute Haskell code at compilation - time, including IO actions. Safe Haskell <emphasis>does not address this - danger</emphasis> (although, Template Haskell is a disallowed feature). - </para> - - <para> - Due to this, it is suggested that when compiling untrusted source code that - has had no manual inspection done, the following precautions be taken: - <itemizedlist> - <listitem>Compile in a sandbox, such as a chroot or similar container - technology. Or simply as a user with very reduced system - access.</listitem> - <listitem>Compile untrusted code with the <option>-XSafe</option> flag - being specified on the command line. This will ensure that modifications - to the source being compiled can't disable the use of the Safe Language - as the command line flag takes precedence over a source level - pragma.</listitem> - <listitem>Ensure that all untrusted code is imported as a - <link linkend="safe-imports">safe import</link><emphasis> and</emphasis> - that the <link linkend="safe-package-trust"><option>-fpackage-trust</option></link> - flag is used with packages from untrusted sources being marked as - untrusted.</listitem> - </itemizedlist> - </para> - - <para> - There is a more detailed discussion of the issues involved in compilation - safety and some potential solutions on the <ulink - url="http://ghc.haskell.org/trac/ghc/wiki/SafeHaskell/SafeCompilation">GHC - Wiki</ulink>. - </para> - - <para> - Additionally, the use of <link linkend="annotation-pragmas">annotations</link> - is forbidden, as that would allow bypassing Safe Haskell restrictions. - See <ulink url="https://ghc.haskell.org/trac/ghc/ticket/10826">ticket #10826</ulink>. - </para> - - </sect2> - -</sect1> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> diff --git a/docs/users_guide/separate_compilation.rst b/docs/users_guide/separate_compilation.rst new file mode 100644 index 0000000000..ec5b5d95b3 --- /dev/null +++ b/docs/users_guide/separate_compilation.rst @@ -0,0 +1,1085 @@ +.. _separate-compilation: + +Filenames and separate compilation +================================== + +.. index:: + single: separate compilation + single: recompilation checker + single: make and recompilation + +This section describes what files GHC expects to find, what files it +creates, where these files are stored, and what options affect this +behaviour. + +Note that this section is written with hierarchical modules in mind (see +:ref:`hierarchical-modules`); hierarchical modules are an extension to +Haskell 98 which extends the lexical syntax of module names to include a +dot ``.``. Non-hierarchical modules are thus a special case in which none +of the module names contain dots. + +Pathname conventions vary from system to system. In particular, the +directory separator is "``/``" on Unix systems and "``\``" on +Windows systems. In the sections that follow, we shall consistently use +"``/``" as the directory separator; substitute this for the +appropriate character for your system. + +.. _source-files: + +Haskell source files +-------------------- + +.. index:: + single: file names; of source files + +Each Haskell source module should be placed in a file on its own. + +Usually, the file should be named after the module name, replacing dots +in the module name by directory separators. For example, on a Unix +system, the module ``A.B.C`` should be placed in the file ``A/B/C.hs``, +relative to some base directory. If the module is not going to be +imported by another module (``Main``, for example), then you are free to +use any filename for it. + +.. index:: + single: Unicode + single: UTF-8 + single: ASCII + single: Latin-1 + single: encodings; of source files + +GHC assumes that source files are ASCII or UTF-8 only, other +encoding are not recognised. However, invalid UTF-8 sequences +will be ignored in comments, so it is possible to use other encodings +such as Latin-1, as long as the non-comment source code is ASCII +only. + +.. _output-files: + +Output files +------------ + +.. index:: + single: interface files + single: .hi files + single: object files + single: .o files + +When asked to compile a source file, GHC normally generates two files: +an object file, and an interface file. + +The object file, which normally ends in a ``.o`` suffix, contains the +compiled code for the module. + +The interface file, which normally ends in a ``.hi`` suffix, contains +the information that GHC needs in order to compile further modules that +depend on this module. It contains things like the types of exported +functions, definitions of data types, and so on. It is stored in a +binary format, so don't try to read one; use the ``--show-iface`` option +instead (see :ref:`hi-options`). + +You should think of the object file and the interface file as a pair, +since the interface file is in a sense a compiler-readable description +of the contents of the object file. If the interface file and object +file get out of sync for any reason, then the compiler may end up making +assumptions about the object file that aren't true; trouble will almost +certainly follow. For this reason, we recommend keeping object files and +interface files in the same place (GHC does this by default, but it is +possible to override the defaults as we'll explain shortly). + +Every module has a *module name* defined in its source code +(``module A.B.C where ...``). + +The name of the object file generated by GHC is derived according to the +following rules, where ⟨osuf⟩ is the object-file suffix (this can be +changed with the ``-osuf`` option). + +- If there is no ``-odir`` option (the default), then the object + filename is derived from the source filename (ignoring the module + name) by replacing the suffix with ⟨osuf⟩. + +- If ``-odir ⟨dir⟩`` has been specified, then the object filename is + ⟨dir⟩/⟨mod⟩.⟨osuf⟩, where ⟨mod⟩ is the module name with dots replaced + by slashes. GHC will silently create the necessary directory + structure underneath ⟨dir⟩, if it does not already exist. + +The name of the interface file is derived using the same rules, except +that the suffix is ⟨hisuf⟩ (``.hi`` by default) instead of ⟨osuf⟩, and +the relevant options are ``-hidir`` and ``-hisuf`` instead of ``-odir`` +and ``-osuf`` respectively. + +For example, if GHC compiles the module ``A.B.C`` in the file +``src/A/B/C.hs``, with no ``-odir`` or ``-hidir`` flags, the interface +file will be put in ``src/A/B/C.hi`` and the object file in +``src/A/B/C.o``. + +For any module that is imported, GHC requires that the name of the +module in the import statement exactly matches the name of the module in +the interface file (or source file) found using the strategy specified +in :ref:`search-path`. This means that for most modules, the source file +name should match the module name. + +However, note that it is reasonable to have a module ``Main`` in a file +named ``foo.hs``, but this only works because GHC never needs to search +for the interface for module ``Main`` (because it is never imported). It +is therefore possible to have several ``Main`` modules in separate +source files in the same directory, and GHC will not get confused. + +In batch compilation mode, the name of the object file can also be +overridden using the ``-o`` option, and the name of the interface file +can be specified directly using the ``-ohi`` option. + +.. _search-path: + +The search path +--------------- + +.. index:: + single: search path + single: interface files, finding them + single: finding interface files + +In your program, you import a module ``Foo`` by saying ``import Foo``. +In ``--make`` mode or GHCi, GHC will look for a source file for ``Foo`` +and arrange to compile it first. Without ``--make``, GHC will look for +the interface file for ``Foo``, which should have been created by an +earlier compilation of ``Foo``. GHC uses the same strategy in each of +these cases for finding the appropriate file. + +This strategy is as follows: GHC keeps a list of directories called the +search path. For each of these directories, it tries appending +``⟨basename⟩.⟨extension⟩`` to the directory, and checks whether the +file exists. The value of ⟨basename⟩ is the module name with dots +replaced by the directory separator ("``/``" or "``\\"``, depending on the +system), and ⟨extension⟩ is a source extension (``hs``, ``lhs``) if we +are in ``--make`` mode or GHCi, or ⟨hisuf⟩ otherwise. + +For example, suppose the search path contains directories ``d1``, +``d2``, and ``d3``, and we are in ``--make`` mode looking for the source +file for a module ``A.B.C``. GHC will look in ``d1/A/B/C.hs``, +``d1/A/B/C.lhs``, ``d2/A/B/C.hs``, and so on. + +The search path by default contains a single directory: "``.``" (i.e. the +current directory). The following options can be used to add to or change the +contents of the search path: + +``-i⟨dir⟩[:⟨dir⟩]*`` + .. index:: + single: -idirs; GHC option + + This flag appends a colon-separated list of ``dirs`` to + the search path. + +``-i`` + resets the search path back to nothing. + +This isn't the whole story: GHC also looks for modules in pre-compiled +libraries, known as packages. See the section on packages +(:ref:`packages`) for details. + +.. _options-output: + +Redirecting the compilation output(s) +------------------------------------- + +.. index:: + single: output-directing options + single: redirecting compilation output + +``-o ⟨file⟩`` + .. index:: + single: -o; GHC option + + GHC's compiled output normally goes into a ``.hc``, ``.o``, etc., + file, depending on the last-run compilation phase. The option + ``-o file`` re-directs the output of that last-run phase to ⟨file⟩. + + .. note:: + This “feature” can be counterintuitive: ``ghc -C -o foo.o foo.hs`` + will put the intermediate C code in the file ``foo.o``, name + notwithstanding! + + This option is most often used when creating an executable file, to + set the filename of the executable. For example: + + :: + + ghc -o prog --make Main + + will compile the program starting with module ``Main`` and put the + executable in the file ``prog``. + + Note: on Windows, if the result is an executable file, the extension + "``.exe``" is added if the specified filename does not already have + an extension. Thus + + :: + + ghc -o foo Main.hs + + will compile and link the module ``Main.hs``, and put the resulting + executable in ``foo.exe`` (not ``foo``). + + If you use ``ghc --make`` and you don't use the ``-o``, the name GHC + will choose for the executable will be based on the name of the file + containing the module ``Main``. Note that with GHC the ``Main`` + module doesn't have to be put in file ``Main.hs``. Thus both + + :: + + ghc --make Prog + + and + + :: + + ghc --make Prog.hs + + will produce ``Prog`` (or ``Prog.exe`` if you are on Windows). + +``-odir ⟨dir⟩`` + .. index:: + single: -odir; GHC option + + Redirects object files to directory ⟨dir⟩. For example: + + :: + + $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `uname -m` + + The object files, ``Foo.o``, ``Bar.o``, and ``Bumble.o`` would be + put into a subdirectory named after the architecture of the + executing machine (``x86``, ``mips``, etc). + + Note that the ``-odir`` option does *not* affect where the interface + files are put; use the ``-hidir`` option for that. In the above + example, they would still be put in ``parse/Foo.hi``, + ``parse/Bar.hi``, and ``gurgle/Bumble.hi``. + +``-ohi ⟨file⟩`` + .. index:: + single: -ohi; GHC option + + The interface output may be directed to another file + ``bar2/Wurble.iface`` with the option ``-ohi bar2/Wurble.iface`` + (not recommended). + + .. warning:: + If you redirect the interface file somewhere that GHC can't + find it, then the recompilation checker may get confused (at the + least, you won't get any recompilation avoidance). We recommend + using a combination of ``-hidir`` and ``-hisuf`` options instead, if + possible. + + To avoid generating an interface at all, you could use this option + to redirect the interface into the bit bucket: ``-ohi /dev/null``, + for example. + +``-hidir ⟨dir⟩`` + .. index:: + single: -hidir; GHC option + + Redirects all generated interface files into ⟨dir⟩, instead of the + default. + +``-stubdir ⟨dir⟩`` + .. index:: + single: -stubdir + + Redirects all generated FFI stub files into ⟨dir⟩. Stub files are + generated when the Haskell source contains a ``foreign export`` or + ``foreign import "&wrapper"`` declaration (see + :ref:`foreign-export-ghc`). The ``-stubdir`` option behaves in + exactly the same way as ``-odir`` and ``-hidir`` with respect to + hierarchical modules. + +``-dumpdir ⟨dir⟩`` + .. index:: + single: -dumpdir + + Redirects all dump files into ⟨dir⟩. Dump files are generated when + ``-ddump-to-file`` is used with other ``-ddump-*`` flags. + +``-outputdir ⟨dir⟩`` + .. index:: + single: -outputdir + + The ``-outputdir`` option is shorthand for the combination of + ``-odir``, ``-hidir``, ``-stubdir`` and ``-dumpdir``. + +``-osuf ⟨suffix⟩; \ ``-hisuf``\ ⟨suffix⟩; \ ``-hcsuf``\ ⟨suffix⟩`` + .. index:: + single: -osuf + + .. index:: + single: -hisuf + + .. index:: + single: -hcsuf + + The ``-osuf`` ⟨suffix⟩ will change the ``.o`` file suffix for object + files to whatever you specify. We use this when compiling libraries, + so that objects for the profiling versions of the libraries don't + clobber the normal ones. + + Similarly, the ``-hisuf`` ⟨suffix⟩ will change the ``.hi`` file + suffix for non-system interface files (see :ref:`hi-options`). + + Finally, the option ``-hcsuf`` ⟨suffix⟩ will change the ``.hc`` file + suffix for compiler-generated intermediate C files. + + The ``-hisuf``/``-osuf`` game is particularly useful if you want to + compile a program both with and without profiling, in the same + directory. You can say: + + :: + + ghc ... + + to get the ordinary version, and + + :: + + ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all + + to get the profiled version. + +.. _keeping-intermediates: + +Keeping Intermediate Files +-------------------------- + +.. index:: + single: intermediate files, saving + single: .hc files, saving + single: .ll files, saving + single: .s files, saving + +The following options are useful for keeping certain intermediate files +around, when normally GHC would throw these away after compilation: + +``-keep-hc-file`` + .. index:: + single: -keep-hc-file + single: -keep-hc-files + + Keep intermediate ``.hc`` files when doing ``.hs``-to-``.o`` + compilations via :ref:`C <c-code-gen>` (Note: ``.hc`` files are only + generated by :ref:`unregisterised <unreg>` compilers). + +``-keep-llvm-file`` + .. index:: + single: -keep-llvm-file + single: -keep-llvm-files + + Keep intermediate ``.ll`` files when doing ``.hs``-to-``.o`` + compilations via :ref:`LLVM <llvm-code-gen>` (Note: ``.ll`` files + aren't generated when using the native code generator, you may need + to use ``-fllvm`` to force them to be produced). + +``-keep-s-file`` + .. index:: + single: -keep-s-file + single: -keep-s-files + + Keep intermediate ``.s`` files. + +``-keep-tmp-files`` + .. index:: + single: -keep-tmp-files + single: temporary files; keeping + + Instructs the GHC driver not to delete any of its temporary files, + which it normally keeps in ``/tmp`` (or possibly elsewhere; see + :ref:`temp-files`). Running GHC with ``-v`` will show you what + temporary files were generated along the way. + +.. _temp-files: + +Redirecting temporary files +--------------------------- + +.. index:: + single: temporary files; redirecting + +``-tmpdir`` + .. index:: + single: -tmpdir + + If you have trouble because of running out of space in ``/tmp`` (or + wherever your installation thinks temporary files should go), you + may use the ``-tmpdir <dir>``-tmpdir <dir> option option to specify an + alternate directory. For example, ``-tmpdir .`` says to put temporary files + in the current working directory. + + Alternatively, use your ``TMPDIR`` environment variable.TMPDIR + environment variable Set it to the name of the directory where + temporary files should be put. GCC and other programs will honour + the ``TMPDIR`` variable as well. + + Even better idea: Set the ``DEFAULT_TMPDIR`` make variable when + building GHC, and never worry about ``TMPDIR`` again. (see the build + documentation). + +.. _hi-options: + +Other options related to interface files +---------------------------------------- + +.. index:: + single: interface files, options + +``-ddump-hi`` + .. index:: + single: -ddump-hi + + Dumps the new interface to standard output. + +``-ddump-hi-diffs`` + .. index:: + single: -ddump-hi-diffs + + The compiler does not overwrite an existing ``.hi`` interface file + if the new one is the same as the old one; this is friendly to + ``make``. When an interface does change, it is often enlightening to + be informed. The ``-ddump-hi-diffs`` option will make GHC report the + differences between the old and new ``.hi`` files. + +``-ddump-minimal-imports`` + .. index:: + single: -ddump-minimal-imports + + Dump to the file ``M.imports`` (where ⟨M⟩ is the name of the module + being compiled) a "minimal" set of import declarations. The + directory where the ``.imports`` files are created can be controlled + via the ``-dumpdir`` option. + + You can safely replace all the import declarations in ``M.hs`` with + those found in its respective ``.imports`` file. Why would you want + to do that? Because the "minimal" imports (a) import everything + explicitly, by name, and (b) import nothing that is not required. It + can be quite painful to maintain this property by hand, so this flag + is intended to reduce the labour. + +``--show-iface ⟨file⟩`` + .. index:: + single: --show-iface + + where ⟨file⟩ is the name of an interface file, dumps the contents of + that interface in a human-readable format. See :ref:`modes`. + +.. _recomp: + +The recompilation checker +------------------------- + +.. index:: + single: recompilation checker + +``-fforce-recomp`` + .. index:: + single: -fforce-recomp + single: -fno-force-recomp + + Turn off recompilation checking (which is on by default). + Recompilation checking normally stops compilation early, leaving an + existing ``.o`` file in place, if it can be determined that the + module does not need to be recompiled. + +In the olden days, GHC compared the newly-generated ``.hi`` file with +the previous version; if they were identical, it left the old one alone +and didn't change its modification date. In consequence, importers of a +module with an unchanged output ``.hi`` file were not recompiled. + +This doesn't work any more. Suppose module ``C`` imports module ``B``, +and ``B`` imports module ``A``. So changes to module ``A`` might require +module ``C`` to be recompiled, and hence when ``A.hi`` changes we should +check whether ``C`` should be recompiled. However, the dependencies of +``C`` will only list ``B.hi``, not ``A.hi``, and some changes to ``A`` +(changing the definition of a function that appears in an inlining of a +function exported by ``B``, say) may conceivably not change ``B.hi`` one +jot. So now… + +GHC calculates a fingerprint (in fact an MD5 hash) of each interface +file, and of each declaration within the interface file. It also keeps +in every interface file a list of the fingerprints of everything it used +when it last compiled the file. If the source file's modification date +is earlier than the ``.o`` file's date (i.e. the source hasn't changed +since the file was last compiled), and the recompilation checking is on, +GHC will be clever. It compares the fingerprints on the things it needs +this time with the fingerprints on the things it needed last time +(gleaned from the interface file of the module being compiled); if they +are all the same it stops compiling early in the process saying +“Compilation IS NOT required”. What a beautiful sight! + +You can read about `how all this +works <http://ghc.haskell.org/trac/ghc/wiki/Commentary/Compiler/RecompilationAvoidance>`__ +in the GHC commentary. + +.. _mutual-recursion: + +How to compile mutually recursive modules +----------------------------------------- + +.. index:: + single: module system, recursion + single: recursion, between modules + +GHC supports the compilation of mutually recursive modules. This section +explains how. + +Every cycle in the module import graph must be broken by a ``hs-boot`` +file. Suppose that modules ``A.hs`` and ``B.hs`` are Haskell source +files, thus: + +:: + + module A where + import B( TB(..) ) + + newtype TA = MkTA Int + + f :: TB -> TA + f (MkTB x) = MkTA x + + module B where + import {-# SOURCE #-} A( TA(..) ) + + data TB = MkTB !Int + + g :: TA -> TB + g (MkTA x) = MkTB x + +``hs-boot`` files importing, ``hi-boot`` files Here ``A`` imports ``B``, +but ``B`` imports ``A`` with a ``{-# SOURCE #-}`` pragma, which breaks +the circular dependency. Every loop in the module import graph must be +broken by a ``{-# SOURCE #-}`` import; or, equivalently, the module +import graph must be acyclic if ``{-# SOURCE #-}`` imports are ignored. + +For every module ``A.hs`` that is ``{-# SOURCE #-}``-imported in this +way there must exist a source file ``A.hs-boot``. This file contains an +abbreviated version of ``A.hs``, thus: + +:: + + module A where + newtype TA = MkTA Int + +To compile these three files, issue the following commands: + +:: + + ghc -c A.hs-boot -- Produces A.hi-boot, A.o-boot + ghc -c B.hs -- Consumes A.hi-boot, produces B.hi, B.o + ghc -c A.hs -- Consumes B.hi, produces A.hi, A.o + ghc -o foo A.o B.o -- Linking the program + +There are several points to note here: + +- The file ``A.hs-boot`` is a programmer-written source file. It must + live in the same directory as its parent source file ``A.hs``. + Currently, if you use a literate source file ``A.lhs`` you must also + use a literate boot file, ``A.lhs-boot``; and vice versa. + +- A ``hs-boot`` file is compiled by GHC, just like a ``hs`` file: + + :: + + ghc -c A.hs-boot + + When a hs-boot file ``A.hs-boot`` is compiled, it is checked for + scope and type errors. When its parent module ``A.hs`` is compiled, + the two are compared, and an error is reported if the two are + inconsistent. + +- Just as compiling ``A.hs`` produces an interface file ``A.hi``, and + an object file ``A.o``, so compiling ``A.hs-boot`` produces an + interface file ``A.hi-boot``, and an pseudo-object file ``A.o-boot``: + + - The pseudo-object file ``A.o-boot`` is empty (don't link it!), but + it is very useful when using a Makefile, to record when the + ``A.hi-boot`` was last brought up to date (see :ref:`using-make`). + + - The ``hi-boot`` generated by compiling a ``hs-boot`` file is in + the same machine-generated binary format as any other + GHC-generated interface file (e.g. ``B.hi``). You can display its + contents with ``ghc --show-iface``. If you specify a directory for + interface files, the ``-ohidir`` flag, then that affects ``hi-boot`` files + too. + +- If hs-boot files are considered distinct from their parent source + files, and if a ``{-# SOURCE #-}`` import is considered to refer to + the hs-boot file, then the module import graph must have no cycles. + The command ``ghc -M`` will report an error if a cycle is found. + +- A module ``M`` that is ``{-# SOURCE #-}``\-imported in a program will + usually also be ordinarily imported elsewhere. If not, ``ghc --make`` + automatically adds ``M`` to the set of modules it tries to compile + and link, to ensure that ``M``\'s implementation is included in the + final program. + +A hs-boot file need only contain the bare minimum of information needed +to get the bootstrapping process started. For example, it doesn't need +to contain declarations for *everything* that module ``A`` exports, only +the things required by the module(s) that import ``A`` recursively. + +A hs-boot file is written in a subset of Haskell: + +- The module header (including the export list), and import statements, + are exactly as in Haskell, and so are the scoping rules. Hence, to + mention a non-Prelude type or class, you must import it. + +- There must be no value declarations, but there can be type signatures + for values. For example: + + :: + + double :: Int -> Int + +- Fixity declarations are exactly as in Haskell. + +- Vanilla type synonym declarations are exactly as in Haskell. + +- Open type and data family declarations are exactly as in Haskell. + +- A closed type family may optionally omit its equations, as in the + following example: + + :: + + type family ClosedFam a where .. + + The ``..`` is meant literally -- you should write two dots in your + file. Note that the ``where`` clause is still necessary to + distinguish closed families from open ones. If you give any equations + of a closed family, you must give all of them, in the same order as + they appear in the accompanying Haskell file. + +- A data type declaration can either be given in full, exactly as in + Haskell, or it can be given abstractly, by omitting the '=' sign and + everything that follows. For example: + + :: + + data T a b + + In a *source* program this would declare TA to have no constructors + (a GHC extension: see :ref:`nullary-types`), but in an hi-boot file + it means "I don't know or care what the constructors are". This is + the most common form of data type declaration, because it's easy to + get right. You *can* also write out the constructors but, if you do + so, you must write it out precisely as in its real definition. + + If you do not write out the constructors, you may need to give a kind + annotation (:ref:`kinding`), to tell GHC the kind of the type + variable, if it is not "\*". (In source files, this is worked out + from the way the type variable is used in the constructors.) For + example: + + :: + + data R (x :: * -> *) y + + You cannot use ``deriving`` on a data type declaration; write an + ``instance`` declaration instead. + +- Class declarations is exactly as in Haskell, except that you may not + put default method declarations. You can also omit all the + superclasses and class methods entirely; but you must either omit + them all or put them all in. + +- You can include instance declarations just as in Haskell; but omit + the "where" part. + +- The default role for abstract datatype parameters is now + representational. (An abstract datatype is one with no constructors + listed.) To get another role, use a role annotation. (See + :ref:`roles`.) + +.. _module-signatures: + +Module signatures +----------------- + +GHC supports the specification of module signatures, which both +implementations and users can typecheck against separately. This +functionality should be considered experimental for now; some details, +especially for type classes and type families, may change. This system +was originally described in `Backpack: Retrofitting Haskell with +Interfaces <http://plv.mpi-sws.org/backpack/>`__. Signature files are +somewhat similar to ``hs-boot`` files, but have the ``hsig`` extension +and behave slightly differently. + +Suppose that I have modules ``String.hs`` and ``A.hs``, thus: + +:: + + module Text where + data Text = Text String + + empty :: Text + empty = Text "" + + toString :: Text -> String + toString (Text s) = s + + module A where + import Text + z = toString empty + +Presently, module ``A`` depends explicitly on a concrete implementation +of ``Text``. What if we wanted to a signature ``Text``, so we could vary +the implementation with other possibilities (e.g. packed UTF-8 encoded +bytestrings)? To do this, we can write a signature ``TextSig.hsig``, and +modify ``A`` to include the signature instead: + +:: + + module TextSig where + data Text + empty :: Text + toString :: Text -> String + + module A where + import TextSig + z = toString empty + +To compile these two files, we need to specify what module we would like +to use to implement the signature. This can be done by compiling the +implementation, and then using the ``-sig-of`` flag to specify the +implementation backing a signature: + +:: + + ghc -c Text.hs + ghc -c TextSig.hsig -sig-of "TextSig is main:Text" + ghc -c A.hs + +To specify multiple signatures, use a comma-separated list. The +``-sig-of`` parameter is required to specify the backing implementations +of all home modules, even in one-shot compilation mode. At the moment, +you must specify the full module name (package key, colon, and then +module name), although in the future we may support more user-friendly +syntax. + +To just type-check an interface file, no ``-sig-of`` is necessary; +instead, just pass the options ``-fno-code -fwrite-interface``. ``hsig`` +files will generate normal interface files which other files can also +use to type-check against. However, at the moment, we always assume that +an entity defined in a signature is a unique identifier (even though we +may happen to know it is type equal with another identifier). In the +future, we will support passing shaping information to the compiler in +order to let it know about these type equalities. + +Just like ``hs-boot`` files, when an ``hsig`` file is compiled it is +checked for type consistency against the backing implementation. +Signature files are also written in a subset of Haskell essentially +identical to that of ``hs-boot`` files. + +There is one important gotcha with the current implementation: +currently, instances from backing implementations will "leak" code that +uses signatures, and explicit instance declarations in signatures are +forbidden. This behavior will be subject to change. + +.. _using-make: + +Using ``make`` +-------------- + +.. index:: + single: make; building programs with + +It is reasonably straightforward to set up a ``Makefile`` to use with +GHC, assuming you name your source files the same as your modules. Thus: + +:: + + HC = ghc + HC_OPTS = -cpp $(EXTRA_HC_OPTS) + + SRCS = Main.lhs Foo.lhs Bar.lhs + OBJS = Main.o Foo.o Bar.o + + .SUFFIXES : .o .hs .hi .lhs .hc .s + + cool_pgm : $(OBJS) + rm -f $@ + $(HC) -o $@ $(HC_OPTS) $(OBJS) + + # Standard suffix rules + .o.hi: + @: + + .lhs.o: + $(HC) -c $< $(HC_OPTS) + + .hs.o: + $(HC) -c $< $(HC_OPTS) + + .o-boot.hi-boot: + @: + + .lhs-boot.o-boot: + $(HC) -c $< $(HC_OPTS) + + .hs-boot.o-boot: + $(HC) -c $< $(HC_OPTS) + + # Inter-module dependencies + Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz + Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz + +.. note:: + Sophisticated ``make`` variants may achieve some of the above more + elegantly. Notably, ``gmake``\'s pattern rules let you write the more + comprehensible: + + :: + + %.o : %.lhs + $(HC) -c $< $(HC_OPTS) + + What we've shown should work with any ``make``. + +Note the cheesy ``.o.hi`` rule: It records the dependency of the +interface (``.hi``) file on the source. The rule says a ``.hi`` file can +be made from a ``.o`` file by doing…nothing. Which is true. + +Note that the suffix rules are all repeated twice, once for normal +Haskell source files, and once for ``hs-boot`` files (see +:ref:`mutual-recursion`). + +Note also the inter-module dependencies at the end of the Makefile, +which take the form + +:: + + Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz + +They tell ``make`` that if any of ``Foo.o``, ``Foo.hc`` or ``Foo.s`` +have an earlier modification date than ``Baz.hi``, then the out-of-date +file must be brought up to date. To bring it up to date, ``make`` looks +for a rule to do so; one of the preceding suffix rules does the job +nicely. These dependencies can be generated automatically by ``ghc``; +see :ref:`makefile-dependencies` + +.. _makefile-dependencies: + +Dependency generation +--------------------- + +.. index:: + single: dependencies in Makefiles + single: Makefile dependencies + +Putting inter-dependencies of the form ``Foo.o : Bar.hi`` into your +``Makefile`` by hand is rather error-prone. Don't worry, GHC has support +for automatically generating the required dependencies. Add the +following to your ``Makefile``: + +:: + + depend : + ghc -M $(HC_OPTS) $(SRCS) + +Now, before you start compiling, and any time you change the ``imports`` +in your program, do ``make depend`` before you do ``make cool_pgm``. The command +``ghc -M`` will append the needed dependencies to your ``Makefile``. + +In general, ``ghc -M Foo`` does the following. For each module ``M`` in +the set ``Foo`` plus all its imports (transitively), it adds to the +Makefile: + +- A line recording the dependence of the object file on the source + file. + + :: + + M.o : M.hs + + (or ``M.lhs`` if that is the filename you used). + +- For each import declaration ``import X`` in ``M``, a line recording + the dependence of ``M`` on ``X``: + + :: + + M.o : X.hi + +- For each import declaration ``import {-# SOURCE #-} X`` in ``M``, a + line recording the dependence of ``M`` on ``X``: + + :: + + M.o : X.hi-boot + + (See :ref:`mutual-recursion` for details of ``hi-boot`` style + interface files.) + +If ``M`` imports multiple modules, then there will be multiple lines +with ``M.o`` as the target. + +There is no need to list all of the source files as arguments to the +``ghc -M`` command; ``ghc`` traces the dependencies, just like +``ghc --make`` (a new feature in GHC 6.4). + +Note that ``ghc -M`` needs to find a *source file* for each module in +the dependency graph, so that it can parse the import declarations and +follow dependencies. Any pre-compiled modules without source files must +therefore belong to a package [1]_. + +By default, ``ghc -M`` generates all the dependencies, and then +concatenates them onto the end of ``makefile`` (or ``Makefile`` if +``makefile`` doesn't exist) bracketed by the lines +"``# DO NOT DELETE: Beginning of Haskell dependencies``" and +"``# DO NOT DELETE: End of Haskell dependencies``". If these lines +already exist in the ``makefile``, then the old dependencies are deleted +first. + +Don't forget to use the same ``-package`` options on the ``ghc -M`` +command line as you would when compiling; this enables the dependency +generator to locate any imported modules that come from packages. The +package modules won't be included in the dependencies generated, though +(but see the ``-include-pkg-deps`` option below). + +The dependency generation phase of GHC can take some additional options, +which you may find useful. The options which affect dependency +generation are: + +``-ddump-mod-cycles`` + Display a list of the cycles in the module graph. This is useful + when trying to eliminate such cycles. + +``-v2`` + Print a full list of the module dependencies to stdout. (This is the + standard verbosity flag, so the list will also be displayed with + ``-v3`` and ``-v4``; :ref:`options-help`.) + +``-dep-makefile ⟨file⟩`` + Use ⟨file⟩ as the makefile, rather than ``makefile`` or + ``Makefile``. If ⟨file⟩ doesn't exist, ``mkdependHS`` creates it. We + often use ``-dep-makefile .depend`` to put the dependencies in + ``.depend`` and then ``include`` the file ``.depend`` into + ``Makefile``. + +``-dep-suffix <suf>`` + Make extra dependencies that declare that files with suffix + ``.<suf>_<osuf>`` depend on interface files with suffix + ``.<suf>_hi``, or (for ``{-# SOURCE #-}`` imports) on ``.hi-boot``. + Multiple ``-dep-suffix`` flags are permitted. For example, + ``-dep-suffix a -dep-suffix b`` will make dependencies for ``.hs`` + on ``.hi``, ``.a_hs`` on ``.a_hi``, and ``.b_hs`` on ``.b_hi``. + (Useful in conjunction with NoFib "ways".) + +``--exclude-module=<file>`` + Regard ``<file>`` as "stable"; i.e., exclude it from having + dependencies on it. + +``-include-pkg-deps`` + Regard modules imported from packages as unstable, i.e., generate + dependencies on any imported package modules (including ``Prelude``, + and all other standard Haskell libraries). Dependencies are not + traced recursively into packages; dependencies are only generated + for home-package modules on external-package modules directly + imported by the home package module. This option is normally only + used by the various system libraries. + +.. _orphan-modules: + +Orphan modules and instance declarations +---------------------------------------- + +Haskell specifies that when compiling module ``M``, any instance declaration +in any module "below" ``M`` is visible. (Module ``A`` is "below" ``M`` if ``A`` is +imported directly by ``M``, or if ``A`` is below a module that ``M`` imports +directly.) In principle, GHC must therefore read the interface files of +every module below ``M``, just in case they contain an instance declaration +that matters to ``M``. This would be a disaster in practice, so GHC tries to +be clever. + +In particular, if an instance declaration is in the same module as the +definition of any type or class mentioned in the *head* of the instance +declaration (the part after the "``=>``"; see :ref:`instance-rules`), then GHC +has to visit that interface file anyway. Example: + +:: + + module A where + instance C a => D (T a) where ... + data T a = ... + +The instance declaration is only relevant if the type ``T`` is in use, and +if so, GHC will have visited ``A``\'s interface file to find ``T``\'s definition. + +The only problem comes when a module contains an instance declaration +and GHC has no other reason for visiting the module. Example: + +:: + + module Orphan where + instance C a => D (T a) where ... + class C a where ... + +Here, neither ``D`` nor ``T`` is declared in module ``Orphan``. We call such modules +“orphan modules”. GHC identifies orphan modules, and visits the +interface file of every orphan module below the module being compiled. +This is usually wasted work, but there is no avoiding it. You should +therefore do your best to have as few orphan modules as possible. + +Functional dependencies complicate matters. Suppose we have: + +:: + + module B where + instance E T Int where ... + data T = ... + +Is this an orphan module? Apparently not, because ``T`` is declared in +the same module. But suppose class ``E`` had a functional dependency: + +:: + + module Lib where + class E x y | y -> x where ... + +Then in some importing module ``M``, the constraint ``(E a Int)`` should be +"improved" by setting ``a = T``, *even though there is no explicit +mention* of ``T`` in ``M``. + +These considerations lead to the following definition of an orphan +module: + +- An *orphan module* orphan module contains at least one *orphan + instance* or at least one *orphan rule*. + +- An instance declaration in a module ``M`` is an *orphan instance* if + orphan instance + + - The class of the instance declaration is not declared in ``M``, and + + - *Either* the class has no functional dependencies, and none of the + type constructors in the instance head is declared in ``M``; *or* + there is a functional dependency for which none of the type + constructors mentioned in the *non-determined* part of the + instance head is defined in ``M``. + + Only the instance head counts. In the example above, it is not good + enough for ``C``\'s declaration to be in module ``A``; it must be the + declaration of ``D`` or ``T``. + +- A rewrite rule in a module ``M`` is an *orphan rule* orphan rule if none + of the variables, type constructors, or classes that are free in the + left hand side of the rule are declared in ``M``. + +If you use the flag ``-fwarn-orphans``, GHC will warn you if you are +creating an orphan module. Like any warning, you can switch the warning +off with ``-fno-warn-orphans``, and ``-Werror`` will make the +compilation fail if the warning is issued. + +You can identify an orphan module by looking in its interface file, +``M.hi``, using the ```--show-iface`` :ref:`mode <modes>`. If there is a +``[orphan module]`` on the first line, GHC considers it an orphan +module. + +.. [1] + This is a change in behaviour relative to 6.2 and earlier. diff --git a/docs/users_guide/separate_compilation.xml b/docs/users_guide/separate_compilation.xml deleted file mode 100644 index 121458f4e6..0000000000 --- a/docs/users_guide/separate_compilation.xml +++ /dev/null @@ -1,1351 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> - <sect1 id="separate-compilation"> - <title>Filenames and separate compilation</title> - - <indexterm><primary>separate compilation</primary></indexterm> - <indexterm><primary>recompilation checker</primary></indexterm> - <indexterm><primary>make and recompilation</primary></indexterm> - - <para>This section describes what files GHC expects to find, what - files it creates, where these files are stored, and what options - affect this behaviour.</para> - - <para>Note that this section is written with - <firstterm>hierarchical modules</firstterm> in mind (see <xref - linkend="hierarchical-modules"/>); hierarchical modules are an - extension to Haskell 98 which extends the lexical syntax of - module names to include a dot ‘.’. Non-hierarchical - modules are thus a special case in which none of the module names - contain dots.</para> - - <para>Pathname conventions vary from system to system. In - particular, the directory separator is - ‘<literal>/</literal>’ on Unix systems and - ‘<literal>\</literal>’ on Windows systems. In the - sections that follow, we shall consistently use - ‘<literal>/</literal>’ as the directory separator; - substitute this for the appropriate character for your - system.</para> - - <sect2 id="source-files"> - <title>Haskell source files</title> - - <indexterm><primary>filenames</primary></indexterm> - - <para>Each Haskell source module should be placed in a file on - its own.</para> - - <para>Usually, the file should be named after the module name, - replacing dots in the module name by directory separators. For - example, on a Unix system, the module <literal>A.B.C</literal> - should be placed in the file <literal>A/B/C.hs</literal>, - relative to some base directory. If the module is not going to - be imported by another module (<literal>Main</literal>, for - example), then you are free to use any filename for it.</para> - - <indexterm><primary>unicode</primary></indexterm> - - <para> GHC assumes that source files are - ASCII<indexterm><primary>ASCII</primary></indexterm> or - UTF-8<indexterm><primary>UTF-8</primary></indexterm> only, other - encodings<indexterm><primary>encoding</primary></indexterm> are - not recognised. However, invalid UTF-8 sequences will be - ignored in comments, so it is possible to use other encodings - such as - Latin-1<indexterm><primary>Latin-1</primary></indexterm>, as - long as the non-comment source code is ASCII only.</para> - </sect2> - - <sect2 id="output-files"> - <title>Output files</title> - - <indexterm><primary>interface files</primary></indexterm> - <indexterm><primary><literal>.hi</literal> files</primary></indexterm> - <indexterm><primary>object files</primary></indexterm> - <indexterm><primary><literal>.o</literal> files</primary></indexterm> - - <para>When asked to compile a source file, GHC normally - generates two files: an <firstterm>object file</firstterm>, and - an <firstterm>interface file</firstterm>. </para> - - <para>The object file, which normally ends in a - <literal>.o</literal> suffix, contains the compiled code for the - module.</para> - - <para>The interface file, - which normally ends in a <literal>.hi</literal> suffix, contains - the information that GHC needs in order to compile further - modules that depend on this module. It contains things like the - types of exported functions, definitions of data types, and so - on. It is stored in a binary format, so don't try to read one; - use the <option>--show-iface</option> option instead (see <xref - linkend="hi-options"/>).</para> - - <para>You should think of the object file and the interface file as a - pair, since the interface file is in a sense a compiler-readable - description of the contents of the object file. If the - interface file and object file get out of sync for any reason, - then the compiler may end up making assumptions about the object - file that aren't true; trouble will almost certainly follow. - For this reason, we recommend keeping object files and interface - files in the same place (GHC does this by default, but it is - possible to override the defaults as we'll explain - shortly).</para> - - <para>Every module has a <emphasis>module name</emphasis> - defined in its source code (<literal>module A.B.C where - ...</literal>).</para> - - <para>The name of the object file generated by GHC is derived - according to the following rules, where - <replaceable>osuf</replaceable> is the object-file suffix (this - can be changed with the <option>-osuf</option> option).</para> - - <itemizedlist> - <listitem> - <para>If there is no <option>-odir</option> option (the - default), then the object filename is derived from the - source filename (ignoring the module name) by replacing the - suffix with <replaceable>osuf</replaceable>.</para> - </listitem> - <listitem> - <para>If - <option>-odir</option> <replaceable>dir</replaceable> - has been specified, then the object filename is - <replaceable>dir</replaceable>/<replaceable>mod</replaceable>.<replaceable>osuf</replaceable>, - where <replaceable>mod</replaceable> is the module name with - dots replaced by slashes. GHC will silently create the necessary directory - structure underneath <replaceable>dir</replaceable>, if it does not - already exist.</para> - </listitem> - </itemizedlist> - - <para>The name of the interface file is derived using the same - rules, except that the suffix is - <replaceable>hisuf</replaceable> (<literal>.hi</literal> by - default) instead of <replaceable>osuf</replaceable>, and the - relevant options are <option>-hidir</option> and - <option>-hisuf</option> instead of <option>-odir</option> and - <option>-osuf</option> respectively.</para> - - <para>For example, if GHC compiles the module - <literal>A.B.C</literal> in the file - <filename>src/A/B/C.hs</filename>, with no - <literal>-odir</literal> or <literal>-hidir</literal> flags, the - interface file will be put in <literal>src/A/B/C.hi</literal> - and the object file in <literal>src/A/B/C.o</literal>.</para> - - <para>For any module that is imported, GHC requires that the - name of the module in the import statement exactly matches the - name of the module in the interface file (or source file) found - using the strategy specified in <xref linkend="search-path"/>. - This means that for most modules, the source file name should - match the module name.</para> - - <para>However, note that it is reasonable to have a module - <literal>Main</literal> in a file named - <filename>foo.hs</filename>, but this only works because GHC - never needs to search for the interface for module - <literal>Main</literal> (because it is never imported). It is - therefore possible to have several <literal>Main</literal> - modules in separate source files in the same directory, and GHC - will not get confused.</para> - - <para>In batch compilation mode, the name of the object file can - also be overridden using the <option>-o</option> option, and the - name of the interface file can be specified directly using the - <option>-ohi</option> option.</para> - </sect2> - - <sect2 id="search-path"> - <title>The search path</title> - - <indexterm><primary>search path</primary> - </indexterm> - <indexterm><primary>interface files, finding them</primary></indexterm> - <indexterm><primary>finding interface files</primary></indexterm> - - <para>In your program, you import a module - <literal>Foo</literal> by saying <literal>import Foo</literal>. - In <option>--make</option> mode or GHCi, GHC will look for a - source file for <literal>Foo</literal> and arrange to compile it - first. Without <option>--make</option>, GHC will look for the - interface file for <literal>Foo</literal>, which should have - been created by an earlier compilation of - <literal>Foo</literal>. GHC uses the same strategy in each of - these cases for finding the appropriate file.</para> - - <para>This strategy is as follows: GHC keeps a list of - directories called the <firstterm>search path</firstterm>. For - each of these directories, it tries appending - <replaceable>basename</replaceable><literal>.</literal><replaceable>extension</replaceable> - to the directory, and checks whether the file exists. The value - of <replaceable>basename</replaceable> is the module name with - dots replaced by the directory separator ('/' or '\', depending - on the system), and <replaceable>extension</replaceable> is a - source extension (<literal>hs</literal>, <literal>lhs</literal>) - if we are in <option>--make</option> mode or GHCi, or - <replaceable>hisuf</replaceable> otherwise.</para> - - <para>For example, suppose the search path contains directories - <literal>d1</literal>, <literal>d2</literal>, and - <literal>d3</literal>, and we are in <literal>--make</literal> - mode looking for the source file for a module - <literal>A.B.C</literal>. GHC will look in - <literal>d1/A/B/C.hs</literal>, <literal>d1/A/B/C.lhs</literal>, - <literal>d2/A/B/C.hs</literal>, and so on.</para> - - <para>The search path by default contains a single directory: - <quote>.</quote> (i.e. the current directory). The following - options can be used to add to or change the contents of the - search path:</para> - - <variablelist> - <varlistentry> - <term><option>-i<replaceable>dirs</replaceable></option></term> - <listitem> - <para><indexterm><primary><option>-i<replaceable>dirs</replaceable></option> - </primary></indexterm>This flag appends a colon-separated - list of <filename>dirs</filename> to the search path.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-i</option></term> - <listitem> - <para>resets the search path back to nothing.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>This isn't the whole story: GHC also looks for modules in - pre-compiled libraries, known as packages. See the section on - packages (<xref linkend="packages"/>) for details.</para> - </sect2> - - <sect2 id="options-output"> - <title>Redirecting the compilation output(s)</title> - - <indexterm><primary>output-directing options</primary></indexterm> - <indexterm><primary>redirecting compilation output</primary></indexterm> - - <variablelist> - <varlistentry> - <term> - <option>-o</option> <replaceable>file</replaceable> - <indexterm><primary><option>-o</option></primary></indexterm> - </term> - <listitem> - <para>GHC's compiled output normally goes into a - <filename>.hc</filename>, <filename>.o</filename>, etc., - file, depending on the last-run compilation phase. The - option <option>-o <replaceable>file</replaceable></option> - re-directs the output of that last-run phase to - <replaceable>file</replaceable>.</para> - - <para>Note: this “feature” can be - counterintuitive: <command>ghc -C -o foo.o - foo.hs</command> will put the intermediate C code in the - file <filename>foo.o</filename>, name - notwithstanding!</para> - - <para>This option is most often used when creating an - executable file, to set the filename of the executable. - For example: -<screen> ghc -o prog --make Main</screen> - - will compile the program starting with module - <literal>Main</literal> and put the executable in the - file <literal>prog</literal>.</para> - - <para>Note: on Windows, if the result is an executable - file, the extension "<filename>.exe</filename>" is added - if the specified filename does not already have an - extension. Thus -<programlisting> - ghc -o foo Main.hs -</programlisting> - will compile and link the module - <filename>Main.hs</filename>, and put the resulting - executable in <filename>foo.exe</filename> (not - <filename>foo</filename>).</para> - - <para>If you use <command>ghc --make</command> and you don't - use the <option>-o</option>, the name GHC will choose - for the executable will be based on the name of the file - containing the module <literal>Main</literal>. - Note that with GHC the <literal>Main</literal> module doesn't - have to be put in file <filename>Main.hs</filename>. - Thus both -<programlisting> - ghc --make Prog -</programlisting> - and -<programlisting> - ghc --make Prog.hs -</programlisting> - will produce <filename>Prog</filename> (or - <filename>Prog.exe</filename> if you are on Windows).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-odir</option> <replaceable>dir</replaceable> - <indexterm><primary><option>-odir</option></primary></indexterm> - </term> - <listitem> - <para>Redirects object files to directory - <replaceable>dir</replaceable>. For example:</para> - -<screen> -$ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `uname -m` -</screen> - - <para>The object files, <filename>Foo.o</filename>, - <filename>Bar.o</filename>, and - <filename>Bumble.o</filename> would be put into a - subdirectory named after the architecture of the executing - machine (<filename>x86</filename>, - <filename>mips</filename>, etc).</para> - - <para>Note that the <option>-odir</option> option does - <emphasis>not</emphasis> affect where the interface files - are put; use the <option>-hidir</option> option for that. - In the above example, they would still be put in - <filename>parse/Foo.hi</filename>, - <filename>parse/Bar.hi</filename>, and - <filename>gurgle/Bumble.hi</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ohi</option> <replaceable>file</replaceable> - <indexterm><primary><option>-ohi</option></primary></indexterm> - </term> - <listitem> - <para>The interface output may be directed to another file - <filename>bar2/Wurble.iface</filename> with the option - <option>-ohi bar2/Wurble.iface</option> (not - recommended).</para> - - <para>WARNING: if you redirect the interface file - somewhere that GHC can't find it, then the recompilation - checker may get confused (at the least, you won't get any - recompilation avoidance). We recommend using a - combination of <option>-hidir</option> and - <option>-hisuf</option> options instead, if - possible.</para> - - <para>To avoid generating an interface at all, you could - use this option to redirect the interface into the bit - bucket: <literal>-ohi /dev/null</literal>, for - example.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-hidir</option> <replaceable>dir</replaceable> - <indexterm><primary><option>-hidir</option></primary></indexterm> - </term> - <listitem> - <para>Redirects all generated interface files into - <replaceable>dir</replaceable>, instead of the - default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-stubdir</option> <replaceable>dir</replaceable> - <indexterm><primary><option>-stubdir</option></primary></indexterm> - </term> - <listitem> - <para>Redirects all generated FFI stub files into - <replaceable>dir</replaceable>. Stub files are generated when the - Haskell source contains a <literal>foreign export</literal> or - <literal>foreign import "&wrapper"</literal> declaration (see <xref - linkend="foreign-export-ghc" />). The <option>-stubdir</option> - option behaves in exactly the same way as <option>-odir</option> - and <option>-hidir</option> with respect to hierarchical - modules.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dumpdir</option> <replaceable>dir</replaceable> - <indexterm><primary><option>-dumpdir</option></primary></indexterm> - </term> - <listitem> - <para>Redirects all dump files into - <replaceable>dir</replaceable>. Dump files are generated when - <literal>-ddump-to-file</literal> is used with other - <literal>-ddump-*</literal> flags.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-outputdir</option> <replaceable>dir</replaceable> - <indexterm><primary><option>-outputdir</option></primary></indexterm> - </term> - <listitem> - <para>The <option>-outputdir</option> option is shorthand for - the combination - of <option>-odir</option>, <option>-hidir</option>, - <option>-stubdir</option> and <option>-dumpdir</option>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-osuf</option> <replaceable>suffix</replaceable> - <indexterm><primary><option>-osuf</option></primary></indexterm> - </term> - <term> - <option>-hisuf</option> <replaceable>suffix</replaceable> - <indexterm><primary><option>-hisuf</option></primary></indexterm> - </term> - <term> - <option>-hcsuf</option> <replaceable>suffix</replaceable> - <indexterm><primary><option>-hcsuf</option></primary></indexterm> - </term> - <listitem> - <para>The <option>-osuf</option> - <replaceable>suffix</replaceable> will change the - <literal>.o</literal> file suffix for object files to - whatever you specify. We use this when compiling - libraries, so that objects for the profiling versions of - the libraries don't clobber the normal ones.</para> - - <para>Similarly, the <option>-hisuf</option> - <replaceable>suffix</replaceable> will change the - <literal>.hi</literal> file suffix for non-system - interface files (see <xref linkend="hi-options"/>).</para> - - <para>Finally, the option <option>-hcsuf</option> - <replaceable>suffix</replaceable> will change the - <literal>.hc</literal> file suffix for compiler-generated - intermediate C files.</para> - - <para>The <option>-hisuf</option>/<option>-osuf</option> - game is particularly useful if you want to compile a - program both with and without profiling, in the same - directory. You can say: - <screen> - ghc ...</screen> - to get the ordinary version, and - <screen> - ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all</screen> - to get the profiled version.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="keeping-intermediates"> - <title>Keeping Intermediate Files</title> - <indexterm><primary>intermediate files, saving</primary> - </indexterm> - <indexterm><primary><literal>.hc</literal> files, saving</primary> - </indexterm> - <indexterm><primary><literal>.ll</literal> files, saving</primary> - </indexterm> - <indexterm><primary><literal>.s</literal> files, saving</primary> - </indexterm> - - <para>The following options are useful for keeping certain - intermediate files around, when normally GHC would throw these - away after compilation:</para> - - <variablelist> - <varlistentry> - <term> - <option>-keep-hc-file</option>, - <option>-keep-hc-files</option> - <indexterm><primary><option>-keep-hc-file</option></primary></indexterm> - <indexterm><primary><option>-keep-hc-files</option></primary></indexterm> - </term> - <listitem> - <para>Keep intermediate <literal>.hc</literal> files when - doing <literal>.hs</literal>-to-<literal>.o</literal> - compilations via <link linkend="c-code-gen">C</link> (NOTE: - <literal>.hc</literal> files are only generated by - <link linkend="unreg">unregisterised</link> compilers).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-keep-llvm-file</option>, - <option>-keep-llvm-files</option> - <indexterm><primary><option>-keep-llvm-file</option></primary></indexterm> - <indexterm><primary><option>-keep-llvm-files</option></primary></indexterm> - </term> - <listitem> - <para>Keep intermediate <literal>.ll</literal> files when - doing <literal>.hs</literal>-to-<literal>.o</literal> - compilations via <link linkend="llvm-code-gen">LLVM</link> - (NOTE: <literal>.ll</literal> files aren't generated when using the - native code generator, you may need to use <option>-fllvm</option> to - force them to be produced).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-keep-s-file</option>, - <option>-keep-s-files</option> - <indexterm><primary><option>-keep-s-file</option></primary></indexterm> - <indexterm><primary><option>-keep-s-files</option></primary></indexterm> - </term> - <listitem> - <para>Keep intermediate <literal>.s</literal> files.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-keep-tmp-files</option> - <indexterm><primary><option>-keep-tmp-files</option></primary></indexterm> - <indexterm><primary>temporary files</primary><secondary>keeping</secondary></indexterm> - </term> - <listitem> - <para>Instructs the GHC driver not to delete any of its - temporary files, which it normally keeps in - <literal>/tmp</literal> (or possibly elsewhere; see <xref - linkend="temp-files"/>). Running GHC with - <option>-v</option> will show you what temporary files - were generated along the way.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="temp-files"> - <title>Redirecting temporary files</title> - - <indexterm> - <primary>temporary files</primary> - <secondary>redirecting</secondary> - </indexterm> - - <variablelist> - <varlistentry> - <term> - <option>-tmpdir</option> - <indexterm><primary><option>-tmpdir</option></primary></indexterm> - </term> - <listitem> - <para>If you have trouble because of running out of space - in <filename>/tmp</filename> (or wherever your - installation thinks temporary files should go), you may - use the <option>-tmpdir - <dir></option><indexterm><primary>-tmpdir - <dir> option</primary></indexterm> option to specify - an alternate directory. For example, <option>-tmpdir - .</option> says to put temporary files in the current - working directory.</para> - - <para>Alternatively, use your <constant>TMPDIR</constant> - environment variable.<indexterm><primary>TMPDIR - environment variable</primary></indexterm> Set it to the - name of the directory where temporary files should be put. - GCC and other programs will honour the - <constant>TMPDIR</constant> variable as well.</para> - - <para>Even better idea: Set the - <constant>DEFAULT_TMPDIR</constant> make variable when - building GHC, and never worry about - <constant>TMPDIR</constant> again. (see the build - documentation).</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="hi-options"> - <title>Other options related to interface files</title> - <indexterm><primary>interface files, options</primary></indexterm> - - <variablelist> - <varlistentry> - <term> - <option>-ddump-hi</option> - <indexterm><primary><option>-ddump-hi</option></primary></indexterm> - </term> - <listitem> - <para>Dumps the new interface to standard output.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-hi-diffs</option> - <indexterm><primary><option>-ddump-hi-diffs</option></primary></indexterm> - </term> - <listitem> - <para>The compiler does not overwrite an existing - <filename>.hi</filename> interface file if the new one is - the same as the old one; this is friendly to - <command>make</command>. When an interface does change, - it is often enlightening to be informed. The - <option>-ddump-hi-diffs</option> option will make GHC - report the differences between the old and - new <filename>.hi</filename> files.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-minimal-imports</option> - <indexterm><primary><option>-ddump-minimal-imports</option></primary></indexterm> - </term> - <listitem> - <para>Dump to the file - <filename><replaceable>M</replaceable>.imports</filename> - (where <replaceable>M</replaceable> is the name of the - module being compiled) a "minimal" set of import - declarations. The directory where the - <filename>.imports</filename> files are created can be - controlled via the <option>-dumpdir</option> - option.</para> <para>You can safely replace all the import - declarations in - <filename><replaceable>M</replaceable>.hs</filename> with - those found in its respective <filename>.imports</filename> - file. Why would you want to do that? Because the - "minimal" imports (a) import everything explicitly, by - name, and (b) import nothing that is not required. It can - be quite painful to maintain this property by hand, so - this flag is intended to reduce the labour.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--show-iface</option> <replaceable>file</replaceable> - <indexterm><primary><option>--show-iface</option></primary></indexterm> - </term> - <listitem> - <para>where <replaceable>file</replaceable> is the name of - an interface file, dumps the contents of that interface in - a human-readable (ish) format. See <xref linkend="modes"/>.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="recomp"> - <title>The recompilation checker</title> - - <indexterm><primary>recompilation checker</primary></indexterm> - - <variablelist> - <varlistentry> - <term> - <option>-fforce-recomp</option> - <indexterm><primary><option>-fforce-recomp</option></primary></indexterm> - <indexterm><primary><option>-fno-force-recomp</option></primary></indexterm> - </term> - <listitem> - <para>Turn off recompilation checking (which is on by - default). Recompilation checking normally stops - compilation early, leaving an existing - <filename>.o</filename> file in place, if it can be - determined that the module does not need to be - recompiled.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>In the olden days, GHC compared the newly-generated - <filename>.hi</filename> file with the previous version; if they - were identical, it left the old one alone and didn't change its - modification date. In consequence, importers of a module with - an unchanged output <filename>.hi</filename> file were not - recompiled.</para> - - <para>This doesn't work any more. Suppose module - <literal>C</literal> imports module <literal>B</literal>, and - <literal>B</literal> imports module <literal>A</literal>. So - changes to module <literal>A</literal> might require module - <literal>C</literal> to be recompiled, and hence when - <filename>A.hi</filename> changes we should check whether - <literal>C</literal> should be recompiled. However, the - dependencies of <literal>C</literal> will only list - <literal>B.hi</literal>, not <literal>A.hi</literal>, and some - changes to <literal>A</literal> (changing the definition of a - function that appears in an inlining of a function exported by - <literal>B</literal>, say) may conceivably not change - <filename>B.hi</filename> one jot. So now…</para> - - <para>GHC calculates a fingerprint (in fact an MD5 hash) of each - interface file, and of each declaration within the interface - file. It also keeps in every interface file a list of the - fingerprints of everything it used when it last compiled the - file. If the source file's modification date is earlier than - the <filename>.o</filename> file's date (i.e. the source hasn't - changed since the file was last compiled), and the recompilation - checking is on, GHC will be clever. It compares the fingerprints - on the things it needs this time with the fingerprints - on the things it needed last time (gleaned from the - interface file of the module being compiled); if they are all - the same it stops compiling early in the process saying - “Compilation IS NOT required”. What a beautiful - sight!</para> - - <para>You can read - about <ulink url="http://ghc.haskell.org/trac/ghc/wiki/Commentary/Compiler/RecompilationAvoidance">how - all this works</ulink> in the GHC commentary.</para> - - </sect2> - - <sect2 id="mutual-recursion"> - <title>How to compile mutually recursive modules</title> - - <indexterm><primary>module system, recursion</primary></indexterm> - <indexterm><primary>recursion, between modules</primary></indexterm> - - <para>GHC supports the compilation of mutually recursive modules. - This section explains how.</para> - - <para>Every cycle in the module import graph must be broken by a <filename>hs-boot</filename> file. - Suppose that modules <filename>A.hs</filename> and <filename>B.hs</filename> are Haskell source files, - thus: -<programlisting> -module A where - import B( TB(..) ) - - newtype TA = MkTA Int - - f :: TB -> TA - f (MkTB x) = MkTA x - -module B where - import {-# SOURCE #-} A( TA(..) ) - - data TB = MkTB !Int - - g :: TA -> TB - g (MkTA x) = MkTB x -</programlisting> -<indexterm><primary><literal>hs-boot</literal> - files</primary></indexterm> <indexterm><primary>importing, - <literal>hi-boot</literal> files</primary></indexterm> -Here <filename>A</filename> imports <filename>B</filename>, but <filename>B</filename> imports -<filename>A</filename> with a <literal>{-# SOURCE #-}</literal> pragma, which breaks the -circular dependency. Every loop in the module import graph must be broken by a <literal>{-# SOURCE #-}</literal> import; -or, equivalently, the module import graph must be acyclic if <literal>{-# SOURCE #-}</literal> imports are ignored. -</para> -<para>For every module <filename>A.hs</filename> that is <literal>{-# SOURCE #-}</literal>-imported -in this way there must exist a source file <literal>A.hs-boot</literal>. This file contains an abbreviated -version of <filename>A.hs</filename>, thus: -<programlisting> -module A where - newtype TA = MkTA Int -</programlisting> -</para> -<para>To compile these three files, issue the following commands: -<programlisting> - ghc -c A.hs-boot -- Produces A.hi-boot, A.o-boot - ghc -c B.hs -- Consumes A.hi-boot, produces B.hi, B.o - ghc -c A.hs -- Consumes B.hi, produces A.hi, A.o - ghc -o foo A.o B.o -- Linking the program -</programlisting> -</para> -<para>There are several points to note here: -<itemizedlist> -<listitem> - <para>The file <filename>A.hs-boot</filename> is a programmer-written source file. - It must live in the same directory as its parent source file <filename>A.hs</filename>. - Currently, if you use a literate source file <filename>A.lhs</filename> you must - also use a literate boot file, <filename>A.lhs-boot</filename>; and vice versa. - </para></listitem> - -<listitem><para> - A <filename>hs-boot</filename> file is compiled by GHC, just like a <filename>hs</filename> file: -<programlisting> - ghc -c A.hs-boot -</programlisting> -When a hs-boot file <filename>A.hs-boot</filename> - is compiled, it is checked for scope and type errors. - When its parent module <filename>A.hs</filename> is compiled, the two are compared, and - an error is reported if the two are inconsistent. - </para></listitem> - - <listitem> - <para> Just as compiling <filename>A.hs</filename> produces an - interface file <filename>A.hi</filename>, and an object file - <filename>A.o</filename>, so compiling - <filename>A.hs-boot</filename> produces an interface file - <filename>A.hi-boot</filename>, and an pseudo-object file - <filename>A.o-boot</filename>: </para> - - <itemizedlist> - <listitem> - <para>The pseudo-object file <filename>A.o-boot</filename> is - empty (don't link it!), but it is very useful when using a - Makefile, to record when the <filename>A.hi-boot</filename> was - last brought up to date (see <xref - linkend="using-make"/>).</para> - </listitem> - - <listitem> - <para>The <filename>hi-boot</filename> generated by compiling a - <filename>hs-boot</filename> file is in the same - machine-generated binary format as any other GHC-generated - interface file (e.g. <filename>B.hi</filename>). You can - display its contents with <command>ghc - --show-iface</command>. If you specify a directory for - interface files, the <option>-ohidir</option> flag, then that - affects <filename>hi-boot</filename> files - too.</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem><para> If hs-boot files are considered distinct from their parent source - files, and if a <literal>{-# SOURCE #-}</literal> import is considered to refer to the - hs-boot file, then the module import graph must have no cycles. The command - <command>ghc -M</command> will report an error if a cycle is found. - </para></listitem> - - <listitem><para> A module <literal>M</literal> that is - <literal>{-# SOURCE #-}</literal>-imported in a program will usually also be - ordinarily imported elsewhere. If not, <command>ghc --make</command> - automatically adds <literal>M</literal> to the set of modules it tries to - compile and link, to ensure that <literal>M</literal>'s implementation is included in - the final program. - </para></listitem> -</itemizedlist> -</para> -<para> -A hs-boot file need only contain the bare - minimum of information needed to get the bootstrapping process - started. For example, it doesn't need to contain declarations - for <emphasis>everything</emphasis> that module - <literal>A</literal> exports, only the things required by the - module(s) that import <literal>A</literal> recursively.</para> -<para>A hs-boot file is written in a subset of Haskell: -<itemizedlist> -<listitem><para> The module header (including the export list), and import statements, are exactly as in -Haskell, and so are the scoping rules. - Hence, to mention a non-Prelude type or class, you must import it.</para></listitem> - -<listitem><para> There must be no value declarations, but there can be type signatures for -values. For example: -<programlisting> - double :: Int -> Int -</programlisting> -</para></listitem> -<listitem><para> Fixity declarations are exactly as in Haskell.</para></listitem> -<listitem><para> Vanilla type synonym declarations are exactly as in Haskell.</para></listitem> -<listitem><para> Open type and data family declarations are exactly as in Haskell.</para></listitem> -<listitem><para> A closed type family may optionally omit its equations, as in the following example: -<programlisting> - type family ClosedFam a where .. -</programlisting> -The <literal>..</literal> is meant literally -- you should write two dots in your file. Note that the <literal>where</literal> clause is still necessary to distinguish closed families from open ones. If you give any equations of a closed family, you must give all of them, in the same order as they appear in the accompanying Haskell file.</para></listitem> -<listitem><para> A data type declaration can either be given in full, exactly as in Haskell, or it -can be given abstractly, by omitting the '=' sign and everything that follows. For example: -<programlisting> - data T a b -</programlisting> - In a <emphasis>source</emphasis> program - this would declare TA to have no constructors (a GHC extension: see <xref linkend="nullary-types"/>), - but in an hi-boot file it means "I don't know or care what the constructors are". - This is the most common form of data type declaration, because it's easy to get right. - You <emphasis>can</emphasis> also write out the constructors but, if you do so, you must write - it out precisely as in its real definition.</para> - <para> - If you do not write out the constructors, you may need to give a kind - annotation (<xref linkend="kinding"/>), to tell - GHC the kind of the type variable, if it is not "*". (In source files, this is worked out - from the way the type variable is used in the constructors.) For example: -<programlisting> - data R (x :: * -> *) y -</programlisting> -You cannot use <literal>deriving</literal> on a data type declaration; write an -<literal>instance</literal> declaration instead. -</para></listitem> -<listitem><para> Class declarations is exactly as in Haskell, except that you may not put -default method declarations. You can also omit all the superclasses and class -methods entirely; but you must either omit them all or put them all in. -</para></listitem> -<listitem><para> You can include instance declarations just as in Haskell; but omit the "where" part. - </para></listitem> -<listitem><para>The default role for abstract datatype parameters is now representational. (An abstract datatype is one with no constructors listed.) To get another role, use a role annotation. (See <xref linkend="roles"/>.)</para></listitem> -</itemizedlist> -</para> - </sect2> - - <sect2 id="module-signatures"> - <title>Module signatures</title> - <para>GHC supports the specification of module signatures, which - both implementations and users can typecheck against separately. - This functionality should be considered experimental for now; some - details, especially for type classes and type families, may change. - This system was originally described in <ulink - url="http://plv.mpi-sws.org/backpack/">Backpack: Retrofitting Haskell with - Interfaces</ulink>. Signature files are somewhat similar to - <literal>hs-boot</literal> files, but have the <literal>hsig</literal> - extension and behave slightly differently. - </para> - - <para>Suppose that I have modules <filename>String.hs</filename> and - <filename>A.hs</filename>, thus:</para> - -<programlisting> -module Text where - data Text = Text String - - empty :: Text - empty = Text "" - - toString :: Text -> String - toString (Text s) = s - -module A where - import Text - z = toString empty -</programlisting> - - <para>Presently, module <literal>A</literal> depends explicitly on - a concrete implementation of <literal>Text</literal>. What if we wanted - to a signature <literal>Text</literal>, so we could vary the - implementation with other possibilities (e.g. packed UTF-8 encoded - bytestrings)? To do this, we can write a signature - <filename>TextSig.hsig</filename>, and modify <literal>A</literal> - to include the signature instead: - </para> - -<programlisting> -module TextSig where - data Text - empty :: Text - toString :: Text -> String - -module A where - import TextSig - z = toString empty -</programlisting> - - <para>To compile these two files, we need to specify what module we - would like to use to implement the signature. This can be done by - compiling the implementation, and then using the <literal>-sig-of</literal> - flag to specify the implementation backing a signature:</para> - -<programlisting> -ghc -c Text.hs -ghc -c TextSig.hsig -sig-of "TextSig is main:Text" -ghc -c A.hs -</programlisting> - - <para>To specify multiple signatures, use a comma-separated list. - The <literal>-sig-of</literal> parameter is required to specify - the backing implementations of all home modules, even in one-shot - compilation mode. - At the moment, you must specify the full module name (package key, - colon, and then module name), although in the future we may support - more user-friendly syntax.</para> - - <para>To just type-check an interface file, no <literal>-sig-of</literal> - is necessary; instead, just pass the options - <literal>-fno-code -fwrite-interface</literal>. <literal>hsig</literal> - files will generate normal interface files which other files can - also use to type-check against. However, at the moment, we always - assume that an entity defined in a signature is a unique identifier - (even though we may happen to know it is type equal with another - identifier). In the future, we will support passing shaping information - to the compiler in order to let it know about these type - equalities.</para> - - <para>Just like <literal>hs-boot</literal> files, when an - <literal>hsig</literal> file is compiled it is checked for type - consistency against the backing implementation. Signature files are also - written in a subset of Haskell essentially identical to that of - <literal>hs-boot</literal> files.</para> - - <para>There is one important gotcha with the current implementation: - currently, instances from backing implementations will "leak" code that - uses signatures, and explicit instance declarations in signatures are - forbidden. This behavior will be subject to change.</para> - - </sect2> - - - <sect2 id="using-make"> - <title>Using <command>make</command></title> - - <indexterm><primary><literal>make</literal></primary></indexterm> - - <para>It is reasonably straightforward to set up a - <filename>Makefile</filename> to use with GHC, assuming you name - your source files the same as your modules. Thus:</para> - -<programlisting> -HC = ghc -HC_OPTS = -cpp $(EXTRA_HC_OPTS) - -SRCS = Main.lhs Foo.lhs Bar.lhs -OBJS = Main.o Foo.o Bar.o - -.SUFFIXES : .o .hs .hi .lhs .hc .s - -cool_pgm : $(OBJS) - rm -f $@ - $(HC) -o $@ $(HC_OPTS) $(OBJS) - -# Standard suffix rules -.o.hi: - @: - -.lhs.o: - $(HC) -c $< $(HC_OPTS) - -.hs.o: - $(HC) -c $< $(HC_OPTS) - -.o-boot.hi-boot: - @: - -.lhs-boot.o-boot: - $(HC) -c $< $(HC_OPTS) - -.hs-boot.o-boot: - $(HC) -c $< $(HC_OPTS) - -# Inter-module dependencies -Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz -Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz -</programlisting> - - <para>(Sophisticated <command>make</command> variants may - achieve some of the above more elegantly. Notably, - <command>gmake</command>'s pattern rules let you write the more - comprehensible:</para> - -<programlisting> -%.o : %.lhs - $(HC) -c $< $(HC_OPTS) -</programlisting> - - <para>What we've shown should work with any - <command>make</command>.)</para> - - <para>Note the cheesy <literal>.o.hi</literal> rule: It records - the dependency of the interface (<filename>.hi</filename>) file - on the source. The rule says a <filename>.hi</filename> file - can be made from a <filename>.o</filename> file by - doing…nothing. Which is true.</para> - <para> Note that the suffix rules are all repeated twice, once - for normal Haskell source files, and once for <filename>hs-boot</filename> - files (see <xref linkend="mutual-recursion"/>).</para> - - <para>Note also the inter-module dependencies at the end of the - Makefile, which take the form - -<programlisting> -Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz -</programlisting> - - They tell <command>make</command> that if any of - <literal>Foo.o</literal>, <literal>Foo.hc</literal> or - <literal>Foo.s</literal> have an earlier modification date than - <literal>Baz.hi</literal>, then the out-of-date file must be - brought up to date. To bring it up to date, - <literal>make</literal> looks for a rule to do so; one of the - preceding suffix rules does the job nicely. These dependencies - can be generated automatically by <command>ghc</command>; see - <xref linkend="makefile-dependencies"/></para> - - </sect2> - - <sect2 id="makefile-dependencies"> - <title>Dependency generation</title> - <indexterm><primary>dependencies in Makefiles</primary></indexterm> - <indexterm><primary>Makefile dependencies</primary></indexterm> - - <para>Putting inter-dependencies of the form <literal>Foo.o : - Bar.hi</literal> into your <filename>Makefile</filename> by - hand is rather error-prone. Don't worry, GHC has support for - automatically generating the required dependencies. Add the - following to your <filename>Makefile</filename>:</para> - -<programlisting> -depend : - ghc -M $(HC_OPTS) $(SRCS) -</programlisting> - - <para>Now, before you start compiling, and any time you change - the <literal>imports</literal> in your program, do - <command>make depend</command> before you do <command>make - cool_pgm</command>. The command <command>ghc -M</command> will - append the needed dependencies to your - <filename>Makefile</filename>.</para> - - <para>In general, <command>ghc -M Foo</command> does the following. - For each module <literal>M</literal> in the set - <literal>Foo</literal> plus all its imports (transitively), - it adds to the Makefile: - <itemizedlist> - <listitem><para>A line recording the dependence of the object file on the source file. -<programlisting> -M.o : M.hs -</programlisting> -(or <literal>M.lhs</literal> if that is the filename you used). - </para></listitem> - <listitem><para> For each import declaration <literal>import X</literal> in <literal>M</literal>, - a line recording the dependence of <literal>M</literal> on <literal>X</literal>: -<programlisting> -M.o : X.hi -</programlisting></para></listitem> - <listitem><para> For each import declaration <literal>import {-# SOURCE #-} X</literal> in <literal>M</literal>, - a line recording the dependence of <literal>M</literal> on <literal>X</literal>: -<programlisting> -M.o : X.hi-boot -</programlisting> - (See <xref linkend="mutual-recursion"/> for details of - <literal>hi-boot</literal> style interface files.) - </para></listitem> - </itemizedlist> - If <literal>M</literal> imports multiple modules, then there will - be multiple lines with <filename>M.o</filename> as the - target.</para> - <para>There is no need to list all of the source files as arguments to the <command>ghc -M</command> command; - <command>ghc</command> traces the dependencies, just like <command>ghc --make</command> - (a new feature in GHC 6.4).</para> - - <para>Note that <literal>ghc -M</literal> needs to find a <emphasis>source - file</emphasis> for each module in the dependency graph, so that it can - parse the import declarations and follow dependencies. Any pre-compiled - modules without source files must therefore belong to a - package<footnote><para>This is a change in behaviour relative to 6.2 and - earlier.</para> - </footnote>.</para> - - <para>By default, <command>ghc -M</command> generates all the - dependencies, and then concatenates them onto the end of - <filename>makefile</filename> (or - <filename>Makefile</filename> if <filename>makefile</filename> - doesn't exist) bracketed by the lines "<literal># DO NOT - DELETE: Beginning of Haskell dependencies</literal>" and - "<literal># DO NOT DELETE: End of Haskell - dependencies</literal>". If these lines already exist in the - <filename>makefile</filename>, then the old dependencies are - deleted first.</para> - - <para>Don't forget to use the same <option>-package</option> - options on the <literal>ghc -M</literal> command line as you - would when compiling; this enables the dependency generator to - locate any imported modules that come from packages. The - package modules won't be included in the dependencies - generated, though (but see the - <option>-include-pkg-deps</option> option below).</para> - - <para>The dependency generation phase of GHC can take some - additional options, which you may find useful. - - The options which affect dependency generation are:</para> - - <variablelist> - <varlistentry> - <term><option>-ddump-mod-cycles</option></term> - <listitem> - <para>Display a list of the cycles in the module graph. This is - useful when trying to eliminate such cycles.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-v2</option></term> - <listitem> - <para>Print a full list of the module dependencies to stdout. - (This is the standard verbosity flag, so the list will - also be displayed with <option>-v3</option> and - <option>-v4</option>; - <xref linkend ="options-help"/>.)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-dep-makefile</option> <replaceable>file</replaceable></term> - <listitem> - <para>Use <replaceable>file</replaceable> as the makefile, - rather than <filename>makefile</filename> or - <filename>Makefile</filename>. If - <replaceable>file</replaceable> doesn't exist, - <command>mkdependHS</command> creates it. We often use - <option>-dep-makefile .depend</option> to put the dependencies in - <filename>.depend</filename> and then - <command>include</command> the file - <filename>.depend</filename> into - <filename>Makefile</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-dep-suffix <suf></option></term> - <listitem> - <para>Make extra dependencies that declare that files - with suffix - <filename>.<suf>_<osuf></filename> - depend on interface files with suffix - <filename>.<suf>_hi</filename>, or (for - <literal>{-# SOURCE #-}</literal> - imports) on <filename>.hi-boot</filename>. Multiple - <option>-dep-suffix</option> flags are permitted. For example, - <option>-dep-suffix a -dep-suffix b</option> - will make dependencies - for <filename>.hs</filename> on - <filename>.hi</filename>, - <filename>.a_hs</filename> on - <filename>.a_hi</filename>, and - <filename>.b_hs</filename> on - <filename>.b_hi</filename>. (Useful in - conjunction with NoFib "ways".)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--exclude-module=<file></option></term> - <listitem> - <para>Regard <filename><file></filename> as - "stable"; i.e., exclude it from having dependencies on - it.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-include-pkg-deps</option></term> - <listitem> - <para>Regard modules imported from packages as unstable, - i.e., generate dependencies on any imported package modules - (including <literal>Prelude</literal>, and all other - standard Haskell libraries). Dependencies are not traced - recursively into packages; dependencies are only generated for - home-package modules on external-package modules directly imported - by the home package module. - This option is normally - only used by the various system libraries.</para> - </listitem> - </varlistentry> - </variablelist> - - </sect2> - - <sect2 id="orphan-modules"> - <title>Orphan modules and instance declarations</title> - -<para> Haskell specifies that when compiling module M, any instance -declaration in any module "below" M is visible. (Module A is "below" -M if A is imported directly by M, or if A is below a module that M imports directly.) -In principle, GHC must therefore read the interface files of every module below M, -just in case they contain an instance declaration that matters to M. This would -be a disaster in practice, so GHC tries to be clever. </para> - -<para>In particular, if an instance declaration is in the same module as the definition -of any type or class mentioned in the <emphasis>head</emphasis> of the instance declaration -(the part after the “<literal>=></literal>”; see <xref linkend="instance-rules"/>), then -GHC has to visit that interface file anyway. Example:</para> -<programlisting> - module A where - instance C a => D (T a) where ... - data T a = ... -</programlisting> -<para> The instance declaration is only relevant if the type T is in use, and if -so, GHC will have visited A's interface file to find T's definition. </para> - -<para> The only problem comes when a module contains an instance declaration -and GHC has no other reason for visiting the module. Example: -<programlisting> - module Orphan where - instance C a => D (T a) where ... - class C a where ... -</programlisting> -Here, neither D nor T is declared in module Orphan. -We call such modules “orphan modules”. -GHC identifies orphan modules, and visits the interface file of -every orphan module below the module being compiled. This is usually -wasted work, but there is no avoiding it. You should therefore do -your best to have as few orphan modules as possible. -</para> -<para> -Functional dependencies complicate matters. Suppose we have: -<programlisting> - module B where - instance E T Int where ... - data T = ... -</programlisting> -Is this an orphan module? Apparently not, because <literal>T</literal> -is declared in the same module. But suppose class <literal>E</literal> had a -functional dependency: -<programlisting> - module Lib where - class E x y | y -> x where ... -</programlisting> -Then in some importing module M, the constraint <literal>(E a Int)</literal> should be "improved" by setting -<literal>a = T</literal>, <emphasis>even though there is no explicit mention -of <literal>T</literal> in M</emphasis>.</para> - -These considerations lead to the following definition of an orphan module: -<itemizedlist> - <listitem> <para> An <emphasis>orphan module</emphasis> - <indexterm><primary>orphan module</primary></indexterm> - contains at least one <emphasis>orphan instance</emphasis> or at - least one <emphasis>orphan rule</emphasis>.</para> </listitem> - - <listitem><para> An instance declaration in a module M is an <emphasis>orphan instance</emphasis> if - <indexterm><primary>orphan instance</primary></indexterm> -<itemizedlist> -<listitem><para> - The class of the instance declaration is not declared in M, and -</para></listitem> -<listitem> -<para> <emphasis>Either</emphasis> the class has no functional dependencies, and none of the type constructors - in the instance head is declared in M; <emphasis>or</emphasis> there - is a functional dependency for which none of the type constructors mentioned - in the <emphasis>non-determined</emphasis> part of the instance head is defined in M. - </para></listitem> - </itemizedlist> - </para> - <para> Only the instance head - counts. In the example above, it is not good enough for C's declaration - to be in module A; it must be the declaration of D or T.</para> - </listitem> - - <listitem><para> A rewrite rule in a module M is an <emphasis>orphan rule</emphasis> - <indexterm><primary>orphan rule</primary></indexterm> - if none of the variables, type constructors, - or classes that are free in the left hand side of the rule are declared in M. - </para> </listitem> - </itemizedlist> - - - -<para>If you use the flag <option>-fwarn-orphans</option>, GHC will warn you -if you are creating an orphan module. -Like any warning, you can switch the warning off with <option>-fno-warn-orphans</option>, -and <option>-Werror</option> -will make the compilation fail if the warning is issued. -</para> -<para> -You can identify an orphan module by looking in its interface -file, <filename>M.hi</filename>, using the -<link linkend="modes"><option>--show-iface</option> mode</link>. If there is a <literal>[orphan module]</literal> on the -first line, GHC considers it an orphan module. -</para> -</sect2> - - </sect1> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> diff --git a/docs/users_guide/shared_libs.rst b/docs/users_guide/shared_libs.rst new file mode 100644 index 0000000000..62822382ce --- /dev/null +++ b/docs/users_guide/shared_libs.rst @@ -0,0 +1,226 @@ +.. _using-shared-libs: + +Using shared libraries +====================== + +.. index:: + single: Shared libraries; using + single: Dynamic libraries; using + +On some platforms GHC supports building Haskell code into shared +libraries. Shared libraries are also sometimes known as dynamic +libraries, in particular on Windows they are referred to as dynamic link +libraries (DLLs). + +Shared libraries allow a single instance of some pre-compiled code to be +shared between several programs. In contrast, with static linking the +code is copied into each program. Using shared libraries can thus save +disk space. They also allow a single copy of code to be shared in memory +between several programs that use it. Shared libraries are often used as +a way of structuring large projects, especially where different parts +are written in different programming languages. Shared libraries are +also commonly used as a plugin mechanism by various applications. This +is particularly common on Windows using COM. + +In GHC version 6.12 building shared libraries is supported for Linux (on +x86 and x86-64 architectures). GHC version 7.0 adds support on Windows +(see :ref:`win32-dlls`), FreeBSD and OpenBSD (x86 and x86-64), Solaris +(x86) and Mac OS X (x86 and PowerPC). + +Building and using shared libraries is slightly more complicated than +building and using static libraries. When using Cabal much of the detail +is hidden, just use ``--enable-shared`` when configuring a package to +build it into a shared library, or to link it against other packages +built as shared libraries. The additional complexity when building code +is to distinguish whether the code will be used in a shared library or +will use shared library versions of other packages it depends on. There +is additional complexity when installing and distributing shared +libraries or programs that use shared libraries, to ensure that all +shared libraries that are required at runtime are present in suitable +locations. + +Building programs that use shared libraries +------------------------------------------- + +To build a simple program and have it use shared libraries for the +runtime system and the base libraries use the ``-dynamic`` flag: + +:: + + ghc --make -dynamic Main.hs + +This has two effects. The first is to compile the code in such a way +that it can be linked against shared library versions of Haskell +packages (such as base). The second is when linking, to link against the +shared versions of the packages' libraries rather than the static +versions. Obviously this requires that the packages were built with +shared libraries. On supported platforms GHC comes with shared libraries +for all the core packages, but if you install extra packages (e.g. with +Cabal) then they would also have to be built with shared libraries +(``--enable-shared`` for Cabal). + +Shared libraries for Haskell packages +------------------------------------- + +You can build Haskell code into a shared library and make a package to +be used by other Haskell programs. The easiest way is using Cabal, +simply configure the Cabal package with the ``--enable-shared`` flag. + +If you want to do the steps manually or are writing your own build +system then there are certain conventions that must be followed. +Building a shared library that exports Haskell code, to be used by other +Haskell code is a bit more complicated than it is for one that exports a +C API and will be used by C code. If you get it wrong you will usually +end up with linker errors. + +In particular Haskell shared libraries *must* be made into packages. You +cannot freely assign which modules go in which shared libraries. The +Haskell shared libraries must match the package boundaries. The reason +for this is that GHC handles references to symbols *within* the same +shared library (or main executable binary) differently from references +to symbols *between* different shared libraries. GHC needs to know for +each imported module if that module lives locally in the same shared lib +or in a separate shared lib. The way it does this is by using packages. +When using ``-dynamic``, a module from a separate package is assumed to +come from a separate shared lib, while modules from the same package (or +the default "main" package) are assumed to be within the same shared lib +(or main executable binary). + +Most of the conventions GHC expects when using packages are described in +:ref:`building-packages`. In addition note that GHC expects the ``.hi`` +files to use the extension ``.dyn_hi``. The other requirements are the +same as for C libraries and are described below, in particular the use +of the flags ``-dynamic``, ``-fPIC`` and ``-shared``. + +Shared libraries that export a C API +------------------------------------ + +Building Haskell code into a shared library is a good way to include +Haskell code in a larger mixed-language project. While with static +linking it is recommended to use GHC to perform the final link step, +with shared libraries a Haskell library can be treated just like any +other shared library. The linking can be done using the normal system C +compiler or linker. + +It is possible to load shared libraries generated by GHC in other +programs not written in Haskell, so they are suitable for using as +plugins. Of course to construct a plugin you will have to use the FFI to +export C functions and follow the rules about initialising the RTS. See +:ref:`ffi-library`. In particular you will probably want to export a C +function from your shared library to initialise the plugin before any +Haskell functions are called. + +To build Haskell modules that export a C API into a shared library use +the ``-dynamic``, ``-fPIC`` and ``-shared`` flags: + +:: + + ghc --make -dynamic -shared -fPIC Foo.hs -o libfoo.so + +As before, the ``-dynamic`` flag specifies that this library links +against the shared library versions of the rts and base package. The +``-fPIC`` flag is required for all code that will end up in a shared +library. The ``-shared`` flag specifies to make a shared library rather +than a program. To make this clearer we can break this down into +separate compilation and link steps: + +:: + + ghc -dynamic -fPIC -c Foo.hs + ghc -dynamic -shared Foo.o -o libfoo.so + +In principle you can use ``-shared`` without ``-dynamic`` in the link +step. That means to statically link the rts all the base libraries into +your new shared library. This would make a very big, but standalone +shared library. On most platforms however that would require all the +static libraries to have been built with ``-fPIC`` so that the code is +suitable to include into a shared library and we do not do that at the +moment. + +.. warning:: + If your shared library exports a Haskell API then you cannot + directly link it into another Haskell program and use that Haskell API. + You will get linker errors. You must instead make it into a package as + described in the section above. + +.. _finding-shared-libs: + +Finding shared libraries at runtime +----------------------------------- + +The primary difficulty with managing shared libraries is arranging +things such that programs can find the libraries they need at runtime. +The details of how this works varies between platforms, in particular +the three major systems: Unix ELF platforms, Windows and Mac OS X. + +.. _finding-shared-libs-unix: + +Unix +~~~~ + +On Unix there are two mechanisms. Shared libraries can be installed into +standard locations that the dynamic linker knows about. For example +``/usr/lib`` or ``/usr/local/lib`` on most systems. The other mechanism +is to use a "runtime path" or "rpath" embedded into programs and +libraries themselves. These paths can either be absolute paths or on at +least Linux and Solaris they can be paths relative to the program or +library itself. In principle this makes it possible to construct fully +relocatable sets of programs and libraries. + +GHC has a ``-dynload`` linking flag to select the method that is used to +find shared libraries at runtime. There are currently two modes: + +``sysdep`` + A system-dependent mode. This is also the default mode. On Unix ELF + systems this embeds ``RPATH``/``RUNPATH`` entries into the shared + library or executable. In particular it uses absolute paths to where + the shared libraries for the rts and each package can be found. This + means the program can immediately be run and it will be able to find + the libraries it needs. However it may not be suitable for + deployment if the libraries are installed in a different location on + another machine. + +``deploy`` + This does not embed any runtime paths. It relies on the shared + libraries being available in a standard location or in a directory + given by the ``LD_LIBRARY_PATH`` environment variable. + +To use relative paths for dependent libraries on Linux and Solaris you +can pass a suitable ``-rpath`` flag to the linker: + +:: + + ghc -dynamic Main.hs -o main -lfoo -L. -optl-Wl,-rpath,'$ORIGIN' + +This assumes that the library ``libfoo.so`` is in the current directory +and will be able to be found in the same directory as the executable +``main`` once the program is deployed. Similarly it would be possible to +use a subdirectory relative to the executable e.g. +``-optl-Wl,-rpath,'$ORIGIN/lib'``. + +This relative path technique can be used with either of the two +``-dynload`` modes, though it makes most sense with the ``deploy`` mode. +The difference is that with the ``deploy`` mode, the above example will +end up with an ELF ``RUNPATH`` of just ``$ORIGIN`` while with the +``sysdep`` mode the ``RUNPATH`` will be ``$ORIGIN`` followed by all the +library directories of all the packages that the program depends on +(e.g. ``base`` and ``rts`` packages etc.) which are typically absolute +paths. The unix tool ``readelf --dynamic`` is handy for inspecting the +``RPATH``/``RUNPATH`` entries in ELF shared libraries and executables. + +.. _finding-shared-libs-mac: + +Mac OS X +~~~~~~~~ + +The standard assumption on Darwin/Mac OS X is that dynamic libraries +will be stamped at build time with an "install name", which is the full +ultimate install path of the library file. Any libraries or executables +that subsequently link against it (even if it hasn't been installed yet) +will pick up that path as their runtime search location for it. When +compiling with ghc directly, the install name is set by default to the +location where it is built. You can override this with the +``-dylib-install-name`` option (which passes ``-install_name`` to the +Apple linker). Cabal does this for you. It automatically sets the +install name for dynamic libraries to the absolute path of the ultimate +install location. diff --git a/docs/users_guide/shared_libs.xml b/docs/users_guide/shared_libs.xml deleted file mode 100644 index 7d2b635d7e..0000000000 --- a/docs/users_guide/shared_libs.xml +++ /dev/null @@ -1,269 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<sect1 id="using-shared-libs"> - <title>Using shared libraries</title> - <indexterm><primary>Shared libraries</primary><secondary>using</secondary></indexterm> - <indexterm><primary>Dynamic libraries</primary><secondary>using</secondary></indexterm> - - <para> - On some platforms GHC supports building Haskell code into shared - libraries. Shared libraries are also sometimes known as dynamic - libraries, in particular on Windows they are referred to as dynamic link - libraries (DLLs). - </para> - - <para> - Shared libraries allow a single instance of some pre-compiled code to be - shared between several programs. In contrast, with static linking the - code is copied into each program. Using shared libraries can thus save - disk space. They also allow a single copy of code to be shared in memory - between several programs that use it. Shared libraries are often used as - a way of structuring large projects, especially where different parts are - written in different programming languages. Shared libraries are also - commonly used as a plugin mechanism by various applications. This is - particularly common on Windows using COM. - </para> - - <para> - In GHC version 6.12 building shared libraries is supported for Linux (on - x86 and x86-64 architectures). GHC version 7.0 adds support on Windows - (see <xref linkend="win32-dlls"/>), FreeBSD and OpenBSD (x86 and x86-64), - Solaris (x86) and Mac OS X (x86 and PowerPC). - </para> - - <para> - Building and using shared libraries is slightly more complicated than - building and using static libraries. When using Cabal much of the detail - is hidden, just use <literal>--enable-shared</literal> when configuring a - package to build it into a shared library, or to link it against other - packages built as shared libraries. The additional complexity when - building code is to distinguish whether the code will be used in a shared - library or will use shared library versions of other packages it depends - on. There is additional complexity when installing and distributing - shared libraries or programs that use shared libraries, to ensure that - all shared libraries that are required at runtime are present in suitable - locations. - </para> - - <sect2> - <title>Building programs that use shared libraries</title> - <para> - To build a simple program and have it use shared libraries for the - runtime system and the base libraries use the - <literal>-dynamic</literal> flag: -<programlisting> -ghc --make -dynamic Main.hs -</programlisting> - This has two effects. The first is to compile the code in such a way - that it can be linked against shared library versions of Haskell - packages (such as base). The second is when linking, to link against - the shared versions of the packages' libraries rather than the static - versions. Obviously this requires that the packages were built with - shared libraries. On supported platforms GHC comes with shared - libraries for all the core packages, but if you install extra packages - (e.g. with Cabal) then they would also have to be built with shared - libraries (<literal>--enable-shared</literal> for Cabal). - </para> - </sect2> - - <sect2> - <title>Shared libraries for Haskell packages</title> - <para> - You can build Haskell code into a shared library and make a package to be - used by other Haskell programs. The easiest way is using Cabal, simply - configure the Cabal package with the <literal>--enable-shared</literal> - flag. - </para> - <para> - If you want to do the steps manually or are writing your own build - system then there are certain conventions that must be followed. Building - a shared library that exports Haskell code, to be used by other Haskell - code is a bit more complicated than it is for one that exports a C API - and will be used by C code. If you get it wrong you will usually end up - with linker errors. - </para> - <para> - In particular Haskell shared libraries <emphasis>must</emphasis> be - made into packages. You cannot freely assign which modules go in which - shared libraries. The Haskell shared libraries must match the package - boundaries. The reason for this is that - GHC handles references to symbols <emphasis>within</emphasis> the same - shared library (or main executable binary) differently from references - to symbols <emphasis>between</emphasis> different shared libraries. GHC - needs to know for each imported module if that module lives locally in - the same shared lib or in a separate shared lib. The way it does this - is by using packages. When using <literal>-dynamic</literal>, a module - from a separate package is assumed to come from a separate shared lib, - while modules from the same package (or the default "main" package) are - assumed to be within the same shared lib (or main executable binary). - </para> - <para> - Most of the conventions GHC expects when using packages are described - in <xref linkend="building-packages"/>. In addition note that GHC - expects the <literal>.hi</literal> files to use the extension - <literal>.dyn_hi</literal>. The other requirements are the same as for - C libraries and are described below, in particular the use of the flags - <literal>-dynamic</literal>, <literal>-fPIC</literal> and - <literal>-shared</literal>. - </para> - </sect2> - - <sect2> - <title>Shared libraries that export a C API</title> - <para> - Building Haskell code into a shared library is a good way to include - Haskell code in a larger mixed-language project. While with static - linking it is recommended to use GHC to perform the final link step, - with shared libraries a Haskell library can be treated just like any - other shared library. The linking can be done using the normal system C - compiler or linker. - </para> - <para> - It is possible to load shared libraries generated by GHC in other - programs not written in Haskell, so they are suitable for using as - plugins. Of course to construct a plugin you will have to use the FFI - to export C functions and follow the rules about initialising the RTS. - See <xref linkend="ffi-library"/>. In particular you will probably want - to export a C function from your shared library to initialise the - plugin before any Haskell functions are called. - </para> - <para> - To build Haskell modules that export a C API into a shared library use - the <literal>-dynamic</literal>, <literal>-fPIC</literal> and - <literal>-shared</literal> flags: -<programlisting> -ghc --make -dynamic -shared -fPIC Foo.hs -o libfoo.so -</programlisting> - As before, the <literal>-dynamic</literal> flag specifies that this - library links against the shared library versions of the rts and base - package. The <literal>-fPIC</literal> flag is required for all code - that will end up in a shared library. The <literal>-shared</literal> - flag specifies to make a shared library rather than a program. To make - this clearer we can break this down into separate compilation and link - steps: -<programlisting> -ghc -dynamic -fPIC -c Foo.hs -ghc -dynamic -shared Foo.o -o libfoo.so -</programlisting> - In principle you can use <literal>-shared</literal> without - <literal>-dynamic</literal> in the link step. That means to - statically link the rts all the base libraries into your new shared - library. This would make a very big, but standalone shared library. - On most platforms however that would require all the static libraries - to have been built with <literal>-fPIC</literal> so that the code is - suitable to include into a shared library and we do not do that at the - moment. - </para> - <para> - <emphasis>Warning:</emphasis> if your shared library exports a Haskell - API then you cannot directly link it into another Haskell program and - use that Haskell API. You will get linker errors. You must instead make - it into a package as described in the section above. - </para> - </sect2> - - <sect2 id="finding-shared-libs"> - <title>Finding shared libraries at runtime</title> - <para> - The primary difficulty with managing shared libraries is arranging - things such that programs can find the libraries they need at runtime. - The details of how this works varies between platforms, in particular - the three major systems: Unix ELF platforms, Windows and Mac OS X. - </para> - <sect3 id="finding-shared-libs-unix"> - <title>Unix</title> - <para> - On Unix there are two mechanisms. Shared libraries can be installed - into standard locations that the dynamic linker knows about. For - example <literal>/usr/lib</literal> or - <literal>/usr/local/lib</literal> on most systems. The other mechanism - is to use a "runtime path" or "rpath" embedded into programs and - libraries themselves. These paths can either be absolute paths or on at - least Linux and Solaris they can be paths relative to the program or - library itself. In principle this makes it possible to construct fully - relocatable sets of programs and libraries. - </para> - <para> - GHC has a <literal>-dynload</literal> linking flag to select the method - that is used to find shared libraries at runtime. There are currently - two modes: - <variablelist> - <varlistentry> - <term>sysdep</term> - <listitem> - <para> - A system-dependent mode. This is also the default mode. On Unix - ELF systems this embeds - <literal>RPATH</literal>/<literal>RUNPATH</literal> entries into the - shared library or executable. In particular it uses absolute paths to - where the shared libraries for the rts and each package can be found. - This means the program can immediately be run and it will be able to - find the libraries it needs. However it may not be suitable for - deployment if the libraries are installed in a different location on - another machine. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>deploy</term> - <listitem> - <para> - This does not embed any runtime paths. It relies on the shared - libraries being available in a standard location or in a - directory given by the <literal>LD_LIBRARY_PATH</literal> - environment variable. - </para> - </listitem> - </varlistentry> - </variablelist> - To use relative paths for dependent libraries on Linux and Solaris you - can pass a suitable <literal>-rpath</literal> flag to the linker: -<programlisting> -ghc -dynamic Main.hs -o main -lfoo -L. -optl-Wl,-rpath,'$ORIGIN' -</programlisting> - This assumes that the library <literal>libfoo.so</literal> is in the - current directory and will be able to be found in the same directory as - the executable <literal>main</literal> once the program is deployed. - Similarly it would be possible to use a subdirectory relative to the - executable e.g. <literal>-optl-Wl,-rpath,'$ORIGIN/lib'</literal>. - </para> - <para> - This relative path technique can be used with either of the two - <literal>-dynload</literal> modes, though it makes most sense with the - <literal>deploy</literal> mode. The difference is that with the - <literal>deploy</literal> mode, the above example will end up with an ELF - <literal>RUNPATH</literal> of just <literal>$ORIGIN</literal> while with - the <literal>sysdep</literal> mode the <literal>RUNPATH</literal> will be - <literal>$ORIGIN</literal> followed by all the library directories of all - the packages that the program depends on (e.g. <literal>base</literal> - and <literal>rts</literal> packages etc.) which are typically absolute - paths. The unix tool <literal>readelf --dynamic</literal> is handy for - inspecting the <literal>RPATH</literal>/<literal>RUNPATH</literal> - entries in ELF shared libraries and executables. - </para> - </sect3> - <sect3 id="finding-shared-libs-mac"> - <title>Mac OS X</title> - <para> - The standard assumption on Darwin/Mac OS X is that dynamic libraries will - be stamped at build time with an "install name", which is the full - ultimate install path of the library file. Any libraries or executables - that subsequently link against it (even if it hasn't been installed yet) - will pick up that path as their runtime search location for it. When - compiling with ghc directly, the install name is set by default to the - location where it is built. You can override this with the - <literal>-dylib-install-name</literal> option (which passes - <literal>-install_name</literal> to the Apple linker). Cabal does this - for you. It automatically sets the install name for dynamic libraries to - the absolute path of the ultimate install location. - </para> - </sect3> - </sect2> - -</sect1> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> diff --git a/docs/users_guide/sooner.rst b/docs/users_guide/sooner.rst new file mode 100644 index 0000000000..8019a43425 --- /dev/null +++ b/docs/users_guide/sooner.rst @@ -0,0 +1,361 @@ +.. _sooner-faster-quicker: + +Advice on: sooner, faster, smaller, thriftier +============================================= + +Please advise us of other "helpful hints" that should go here! + +.. _sooner: + +Sooner: producing a program more quickly +---------------------------------------- + +.. index:: + single: compiling faster + single: faster compiling + +Don't use ``-O`` or (especially) ``-O2``: + By using them, you are telling GHC that you are willing to suffer + longer compilation times for better-quality code. + + GHC is surprisingly zippy for normal compilations without ``-O``! + +Use more memory: + Within reason, more memory for heap space means less garbage + collection for GHC, which means less compilation time. If you use + the ``-Rghc-timing`` option, you'll get a garbage-collector report. + (Again, you can use the cheap-and-nasty ``+RTS -S -RTS`` option to + send the GC stats straight to standard error.) + + .. index:: + single: -H; RTS option + + If it says you're using more than 20% of total time in garbage + collecting, then more memory might help: use the ``-H⟨size⟩`` + option. Increasing the default allocation area size used by the + compiler's RTS might also help: use the ``+RTS -A⟨size⟩ -RTS`` + option. + + .. index:: + single: -A⟨size⟩; RTS option + + If GHC persists in being a bad memory citizen, please report it as a + bug. + +Don't use too much memory! + As soon as GHC plus its “fellow citizens” (other processes on your + machine) start using more than the *real memory* on your machine, + and the machine starts “thrashing,” *the party is over*. Compile + times will be worse than terrible! Use something like the csh + builtin ``time`` command to get a report on how many page faults + you're getting. + + If you don't know what virtual memory, thrashing, and page faults + are, or you don't know the memory configuration of your machine, + *don't* try to be clever about memory use: you'll just make your + life a misery (and for other people, too, probably). + +Try to use local disks when linking: + Because Haskell objects and libraries tend to be large, it can take + many real seconds to slurp the bits to/from a remote filesystem. + + It would be quite sensible to *compile* on a fast machine using + remotely-mounted disks; then *link* on a slow machine that had your + disks directly mounted. + +Don't derive/use ``Read`` unnecessarily: + It's ugly and slow. + +GHC compiles some program constructs slowly: + We'd rather you reported such behaviour as a bug, so that we can try + to correct it. + + .. index:: + single: -v; GHC option + + To figure out which part of the compiler is badly behaved, the + ``-v2`` option is your friend. + +.. _faster: + +Faster: producing a program that runs quicker +--------------------------------------------- + +.. index:: + single: faster programs, how to produce + +The key tool to use in making your Haskell program run faster are GHC's +profiling facilities, described separately in :ref:`profiling`. There is +*no substitute* for finding where your program's time/space is *really* +going, as opposed to where you imagine it is going. + +Another point to bear in mind: By far the best way to improve a +program's performance *dramatically* is to use better algorithms. Once +profiling has thrown the spotlight on the guilty time-consumer(s), it +may be better to re-think your program than to try all the tweaks listed +below. + +Another extremely efficient way to make your program snappy is to use +library code that has been Seriously Tuned By Someone Else. You *might* +be able to write a better quicksort than the one in ``Data.List``, but +it will take you much longer than typing ``import Data.List``. + +Please report any overly-slow GHC-compiled programs. Since GHC doesn't +have any credible competition in the performance department these days +it's hard to say what overly-slow means, so just use your judgement! Of +course, if a GHC compiled program runs slower than the same program +compiled with NHC or Hugs, then it's definitely a bug. + +Optimise, using ``-O`` or ``-O2``: + This is the most basic way to make your program go faster. + Compilation time will be slower, especially with ``-O2``. + + At present, ``-O2`` is nearly indistinguishable from ``-O``. + +Compile via LLVM: + The :ref:`LLVM code generator <llvm-code-gen>` can sometimes do a far + better job at producing fast code than the :ref:`native code + generator <native-code-gen>`. This is not universal and depends + on the code. Numeric heavy code seems to show the best improvement + when compiled via LLVM. You can also experiment with passing + specific flags to LLVM with the ``-optlo`` and ``-optlc`` flags. Be + careful though as setting these flags stops GHC from setting its + usual flags for the LLVM optimiser and compiler. + +Overloaded functions are not your friend: + Haskell's overloading (using type classes) is elegant, neat, etc., + etc., but it is death to performance if left to linger in an inner + loop. How can you squash it? + +Give explicit type signatures: + Signatures are the basic trick; putting them on exported, top-level + functions is good software-engineering practice, anyway. (Tip: using + ``-fwarn-missing-signatures``-fwarn-missing-signatures option can + help enforce good signature-practice). + + The automatic specialisation of overloaded functions (with ``-O``) + should take care of overloaded local and/or unexported functions. + +Use ``SPECIALIZE`` pragmas: + .. index:: + single: SPECIALIZE pragma + + .. index:: + single: overloading, death to + + Specialize the overloading on key functions in your program. See + :ref:`specialize-pragma` and :ref:`specialize-instance-pragma`. + +"But how do I know where overloading is creeping in?" + A low-tech way: grep (search) your interface files for overloaded + type signatures. You can view interface files using the + ``--show-iface`` option (see :ref:`hi-options`). + + :: + + % ghc --show-iface Foo.hi | egrep '^[a-z].*::.*=>' + +Strict functions are your dear friends: + And, among other things, lazy pattern-matching is your enemy. + + (If you don't know what a "strict function" is, please consult a + functional-programming textbook. A sentence or two of explanation + here probably would not do much good.) + + Consider these two code fragments: + + :: + + f (Wibble x y) = ... # strict + + f arg = let { (Wibble x y) = arg } in ... # lazy + + The former will result in far better code. + + A less contrived example shows the use of ``cases`` instead of + ``lets`` to get stricter code (a good thing): + + :: + + f (Wibble x y) # beautiful but slow + = let + (a1, b1, c1) = unpackFoo x + (a2, b2, c2) = unpackFoo y + in ... + + f (Wibble x y) # ugly, and proud of it + = case (unpackFoo x) of { (a1, b1, c1) -> + case (unpackFoo y) of { (a2, b2, c2) -> + ... + }} + +GHC loves single-constructor data-types: + It's all the better if a function is strict in a single-constructor + type (a type with only one data-constructor; for example, tuples are + single-constructor types). + +Newtypes are better than datatypes: + If your datatype has a single constructor with a single field, use a + ``newtype`` declaration instead of a ``data`` declaration. The + ``newtype`` will be optimised away in most cases. + +"How do I find out a function's strictness?" + Don't guess—look it up. + + Look for your function in the interface file, then for the third + field in the pragma; it should say ``Strictness: ⟨string⟩``. The + ⟨string⟩ gives the strictness of the function's arguments: see + :ghc-wiki:`the GHC Commentary <Commentary/Compiler/Demand>` + for a description of the strictness notation. + + For an "unpackable" ``U(...)`` argument, the info inside tells the + strictness of its components. So, if the argument is a pair, and it + says ``U(AU(LSS))``, that means “the first component of the pair + isn't used; the second component is itself unpackable, with three + components (lazy in the first, strict in the second \\& third).” + + If the function isn't exported, just compile with the extra flag + ``-ddump-simpl``; next to the signature for any binder, it will + print the self-same pragmatic information as would be put in an + interface file. (Besides, Core syntax is fun to look at!) + +Force key functions to be ``INLINE``\ d (esp. monads): + Placing ``INLINE`` pragmas on certain functions that are used a lot + can have a dramatic effect. See :ref:`inline-pragma`. + +Explicit ``export`` list: + If you do not have an explicit export list in a module, GHC must + assume that everything in that module will be exported. This has + various pessimising effects. For example, if a bit of code is + actually *unused* (perhaps because of unfolding effects), GHC will + not be able to throw it away, because it is exported and some other + module may be relying on its existence. + + GHC can be quite a bit more aggressive with pieces of code if it + knows they are not exported. + +Look at the Core syntax! + (The form in which GHC manipulates your code.) Just run your + compilation with ``-ddump-simpl`` (don't forget the ``-O``). + + If profiling has pointed the finger at particular functions, look at + their Core code. ``lets`` are bad, ``cases`` are good, dictionaries + (``d.⟨Class⟩.⟨Unique⟩``) [or anything overloading-ish] are bad, + nested lambdas are bad, explicit data constructors are good, + primitive operations (e.g., ``eqInt#``) are good, ... + +Use strictness annotations: + Putting a strictness annotation (``!``) on a constructor field helps + in two ways: it adds strictness to the program, which gives the + strictness analyser more to work with, and it might help to reduce + space leaks. + + It can also help in a third way: when used with + ``-funbox-strict-fields`` (see :ref:`options-f`), a strict field can + be unpacked or unboxed in the constructor, and one or more levels of + indirection may be removed. Unpacking only happens for + single-constructor datatypes (``Int`` is a good candidate, for + example). + + Using ``-funbox-strict-fields`` is only really a good idea in + conjunction with ``-O``, because otherwise the extra packing and + unpacking won't be optimised away. In fact, it is possible that + ``-funbox-strict-fields`` may worsen performance even *with* ``-O``, + but this is unlikely (let us know if it happens to you). + +Use unboxed types (a GHC extension): + When you are *really* desperate for speed, and you want to get right + down to the “raw bits.” Please see :ref:`glasgow-unboxed` for some + information about using unboxed types. + + Before resorting to explicit unboxed types, try using strict + constructor fields and ``-funbox-strict-fields`` first (see above). + That way, your code stays portable. + +Use ``foreign import`` (a GHC extension) to plug into fast libraries: + This may take real work, but… There exist piles of massively-tuned + library code, and the best thing is not to compete with it, but link + with it. + + :ref:`ffi` describes the foreign function interface. + +Don't use ``Float``\s: + If you're using ``Complex``, definitely use ``Complex Double`` + rather than ``Complex Float`` (the former is specialised heavily, + but the latter isn't). + + ``Floats`` (probably 32-bits) are almost always a bad idea, anyway, + unless you Really Know What You Are Doing. Use ``Double``\s. + There's rarely a speed disadvantage—modern machines will use the + same floating-point unit for both. With ``Double``\s, you are much + less likely to hang yourself with numerical errors. + + One time when ``Float`` might be a good idea is if you have a *lot* + of them, say a giant array of ``Float``\s. They take up half the + space in the heap compared to ``Doubles``. However, this isn't true + on a 64-bit machine. + +Use unboxed arrays (``UArray``) + GHC supports arrays of unboxed elements, for several basic + arithmetic element types including ``Int`` and ``Char``: see the + ``Data.Array.Unboxed`` library for details. These arrays are likely + to be much faster than using standard Haskell 98 arrays from the + ``Data.Array`` library. + +Use a bigger heap! + If your program's GC stats (``-S`` RTS option) indicate that + it's doing lots of garbage-collection (say, more than 20% of execution + time), more memory might help — with the ``-H⟨size⟩`` or ``-A⟨size⟩`` RTS + options (see :ref:`rts-options-gc`). As a rule of thumb, try setting + ``-H⟨size⟩`` to the amount of memory you're willing to let your process + consume, or perhaps try passing ``-H`` without any argument to let GHC + calculate a value based on the amount of live data. + +.. _smaller: + +Smaller: producing a program that is smaller +-------------------------------------------- + +.. index:: + single: smaller programs, how to produce + single: -funfolding-use-threshold0 option + +Decrease the “go-for-it” threshold for unfolding smallish expressions. +Give a ``-funfolding-use-threshold0`` option for the extreme case. +(“Only unfoldings with zero cost should proceed.”) Warning: except in +certain specialised cases (like Happy parsers) this is likely to +actually *increase* the size of your program, because unfolding +generally enables extra simplifying optimisations to be performed. + +Avoid ``Read``. + +Use ``strip`` on your executables. + +.. _thriftier: + +Thriftier: producing a program that gobbles less heap space +----------------------------------------------------------- + +.. index:: + single: memory, using less heap + single: space-leaks, avoiding + single: heap space, using less + +"I think I have a space leak..." + +Re-run your program with ``+RTS -S``, and remove all doubt! (You'll see the +heap usage get bigger and bigger...) [Hmmm... this might be even easier with +the ``-G1`` RTS option; so... ``./a.out +RTS -S -G1``...] + +.. index:: + single: -G RTS option + single: -S RTS option + +Once again, the profiling facilities (:ref:`profiling`) are the basic +tool for demystifying the space behaviour of your program. + +Strict functions are good for space usage, as they are for time, as +discussed in the previous section. Strict functions get right down to +business, rather than filling up the heap with closures (the system's +notes to itself about how to evaluate something, should it eventually be +required). diff --git a/docs/users_guide/sooner.xml b/docs/users_guide/sooner.xml deleted file mode 100644 index bade7c4bb0..0000000000 --- a/docs/users_guide/sooner.xml +++ /dev/null @@ -1,549 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<chapter id="sooner-faster-quicker"> -<title>Advice on: sooner, faster, smaller, thriftier</title> - -<para>Please advise us of other “helpful hints” that -should go here!</para> - -<sect1 id="sooner"> -<title>Sooner: producing a program more quickly -</title> - -<indexterm><primary>compiling faster</primary></indexterm> -<indexterm><primary>faster compiling</primary></indexterm> - - <variablelist> - <varlistentry> - <term>Don't use <option>-O</option> or (especially) <option>-O2</option>:</term> - <listitem> - <para>By using them, you are telling GHC that you are - willing to suffer longer compilation times for - better-quality code.</para> - - <para>GHC is surprisingly zippy for normal compilations - without <option>-O</option>!</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Use more memory:</term> - <listitem> - <para>Within reason, more memory for heap space means less - garbage collection for GHC, which means less compilation - time. If you use the <option>-Rghc-timing</option> option, - you'll get a garbage-collector report. (Again, you can use - the cheap-and-nasty <option>+RTS -S -RTS</option> - option to send the GC stats straight to standard - error.)</para> - - <para>If it says you're using more than 20% of total - time in garbage collecting, then more memory might - help: use the - <option>-H<size></option><indexterm><primary><option>-H</option></primary></indexterm> - option. Increasing the default allocation area size used by - the compiler's RTS might also help: use the - <option>+RTS -A<size> -RTS</option><indexterm><primary>-A<size> - RTS option</primary></indexterm> option.</para> - - <para>If GHC persists in being a bad memory citizen, please - report it as a bug.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Don't use too much memory!</term> - <listitem> - <para>As soon as GHC plus its “fellow citizens” - (other processes on your machine) start using more than the - <emphasis>real memory</emphasis> on your machine, and the - machine starts “thrashing,” <emphasis>the party - is over</emphasis>. Compile times will be worse than - terrible! Use something like the csh builtin - <command>time</command> command to get a report on how many - page faults you're getting.</para> - - <para>If you don't know what virtual memory, thrashing, and - page faults are, or you don't know the memory configuration - of your machine, <emphasis>don't</emphasis> try to be clever - about memory use: you'll just make your life a misery (and - for other people, too, probably).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Try to use local disks when linking:</term> - <listitem> - <para>Because Haskell objects and libraries tend to be - large, it can take many real seconds to slurp the bits - to/from a remote filesystem.</para> - - <para>It would be quite sensible to - <emphasis>compile</emphasis> on a fast machine using - remotely-mounted disks; then <emphasis>link</emphasis> on a - slow machine that had your disks directly mounted.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Don't derive/use <function>Read</function> unnecessarily:</term> - <listitem> - <para>It's ugly and slow.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>GHC compiles some program constructs slowly:</term> - <listitem> - <para>We'd rather you reported such behaviour as a bug, so - that we can try to correct it.</para> - - <para>To figure out which part of the compiler is badly - behaved, the - <option>-v2</option><indexterm><primary><option>-v</option></primary> - </indexterm> option is your friend.</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1 id="faster"> - <title>Faster: producing a program that runs quicker</title> - - <indexterm><primary>faster programs, how to produce</primary></indexterm> - - <para>The key tool to use in making your Haskell program run - faster are GHC's profiling facilities, described separately in - <xref linkend="profiling"/>. There is <emphasis>no - substitute</emphasis> for finding where your program's time/space - is <emphasis>really</emphasis> going, as opposed to where you - imagine it is going.</para> - - <para>Another point to bear in mind: By far the best way to - improve a program's performance <emphasis>dramatically</emphasis> - is to use better algorithms. Once profiling has thrown the - spotlight on the guilty time-consumer(s), it may be better to - re-think your program than to try all the tweaks listed below.</para> - - <para>Another extremely efficient way to make your program snappy - is to use library code that has been Seriously Tuned By Someone - Else. You <emphasis>might</emphasis> be able to write a better - quicksort than the one in <literal>Data.List</literal>, but it - will take you much longer than typing <literal>import - Data.List</literal>.</para> - - <para>Please report any overly-slow GHC-compiled programs. Since - GHC doesn't have any credible competition in the performance - department these days it's hard to say what overly-slow means, so - just use your judgement! Of course, if a GHC compiled program - runs slower than the same program compiled with NHC or Hugs, then - it's definitely a bug.</para> - - <variablelist> - <varlistentry> - <term>Optimise, using <option>-O</option> or <option>-O2</option>:</term> - <listitem> - <para>This is the most basic way to make your program go - faster. Compilation time will be slower, especially with - <option>-O2</option>.</para> - - <para>At present, <option>-O2</option> is nearly - indistinguishable from <option>-O</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Compile via LLVM:</term> - <listitem> - <para>The <link linkend="llvm-code-gen">LLVM code generator</link> can - sometimes do a far better job at producing fast code than the <link - linkend="native-code-gen">native code generator</link>. This is not - universal and depends on the code. Numeric heavy code seems to show - the best improvement when compiled via LLVM. You can also experiment - with passing specific flags to LLVM with the <option>-optlo</option> - and <option>-optlc</option> flags. Be careful though as setting these - flags stops GHC from setting its usual flags for the LLVM optimiser - and compiler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Overloaded functions are not your friend:</term> - <listitem> - <para>Haskell's overloading (using type classes) is elegant, - neat, etc., etc., but it is death to performance if left to - linger in an inner loop. How can you squash it?</para> - - <variablelist> - <varlistentry> - <term>Give explicit type signatures:</term> - <listitem> - <para>Signatures are the basic trick; putting them on - exported, top-level functions is good - software-engineering practice, anyway. (Tip: using - <option>-fwarn-missing-signatures</option><indexterm><primary>-fwarn-missing-signatures - option</primary></indexterm> can help enforce good - signature-practice).</para> - - <para>The automatic specialisation of overloaded - functions (with <option>-O</option>) should take care - of overloaded local and/or unexported functions.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Use <literal>SPECIALIZE</literal> pragmas:</term> - <listitem> - <indexterm><primary>SPECIALIZE pragma</primary></indexterm> - <indexterm><primary>overloading, death to</primary></indexterm> - - <para>Specialize the overloading on key functions in - your program. See <xref linkend="specialize-pragma"/> - and <xref linkend="specialize-instance-pragma"/>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>“But how do I know where overloading is creeping in?”:</term> - <listitem> - <para>A low-tech way: grep (search) your interface - files for overloaded type signatures. You can view - interface files using the - <option>--show-iface</option> option (see <xref - linkend="hi-options"/>). - -<programlisting> -% ghc --show-iface Foo.hi | egrep '^[a-z].*::.*=>' -</programlisting> -</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Strict functions are your dear friends:</term> - <listitem> - <para>and, among other things, lazy pattern-matching is your - enemy.</para> - - <para>(If you don't know what a “strict - function” is, please consult a functional-programming - textbook. A sentence or two of explanation here probably - would not do much good.)</para> - - <para>Consider these two code fragments: - -<programlisting> -f (Wibble x y) = ... # strict - -f arg = let { (Wibble x y) = arg } in ... # lazy -</programlisting> - - The former will result in far better code.</para> - - <para>A less contrived example shows the use of - <literal>cases</literal> instead of <literal>lets</literal> - to get stricter code (a good thing): - -<programlisting> -f (Wibble x y) # beautiful but slow - = let - (a1, b1, c1) = unpackFoo x - (a2, b2, c2) = unpackFoo y - in ... - -f (Wibble x y) # ugly, and proud of it - = case (unpackFoo x) of { (a1, b1, c1) -> - case (unpackFoo y) of { (a2, b2, c2) -> - ... - }} -</programlisting> - - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>GHC loves single-constructor data-types:</term> - <listitem> - <para>It's all the better if a function is strict in a - single-constructor type (a type with only one - data-constructor; for example, tuples are single-constructor - types).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Newtypes are better than datatypes:</term> - <listitem> - <para>If your datatype has a single constructor with a - single field, use a <literal>newtype</literal> declaration - instead of a <literal>data</literal> declaration. The - <literal>newtype</literal> will be optimised away in most - cases.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>“How do I find out a function's strictness?”</term> - <listitem> - <para>Don't guess—look it up.</para> - - <para>Look for your function in the interface file, then for - the third field in the pragma; it should say - <literal>Strictness: <string></literal>. The - <literal><string></literal> gives the strictness of - the function's arguments: see <ulink url="http://ghc.haskell.org/trac/ghc/wiki/Commentary/Compiler/Demand"> - the GHC Commentary</ulink> for a description of the strictness notation. - </para> - - <para>For an “unpackable” - <function>U(...)</function> argument, the info inside tells - the strictness of its components. So, if the argument is a - pair, and it says <function>U(AU(LSS))</function>, that - means “the first component of the pair isn't used; the - second component is itself unpackable, with three components - (lazy in the first, strict in the second \& - third).”</para> - - <para>If the function isn't exported, just compile with the - extra flag <option>-ddump-simpl</option>; next to the - signature for any binder, it will print the self-same - pragmatic information as would be put in an interface file. - (Besides, Core syntax is fun to look at!)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Force key functions to be <literal>INLINE</literal>d (esp. monads):</term> - <listitem> - <para>Placing <literal>INLINE</literal> pragmas on certain - functions that are used a lot can have a dramatic effect. - See <xref linkend="inline-pragma"/>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Explicit <literal>export</literal> list:</term> - <listitem> - <para>If you do not have an explicit export list in a - module, GHC must assume that everything in that module will - be exported. This has various pessimising effects. For - example, if a bit of code is actually - <emphasis>unused</emphasis> (perhaps because of unfolding - effects), GHC will not be able to throw it away, because it - is exported and some other module may be relying on its - existence.</para> - - <para>GHC can be quite a bit more aggressive with pieces of - code if it knows they are not exported.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Look at the Core syntax!</term> - <listitem> - <para>(The form in which GHC manipulates your code.) Just - run your compilation with <option>-ddump-simpl</option> - (don't forget the <option>-O</option>).</para> - - <para>If profiling has pointed the finger at particular - functions, look at their Core code. <literal>lets</literal> - are bad, <literal>cases</literal> are good, dictionaries - (<literal>d.<Class>.<Unique></literal>) [or - anything overloading-ish] are bad, nested lambdas are - bad, explicit data constructors are good, primitive - operations (e.g., <literal>eqInt#</literal>) are - good,…</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Use strictness annotations:</term> - <listitem> - <para>Putting a strictness annotation ('!') on a constructor - field helps in two ways: it adds strictness to the program, - which gives the strictness analyser more to work with, and - it might help to reduce space leaks.</para> - - <para>It can also help in a third way: when used with - <option>-funbox-strict-fields</option> (see <xref - linkend="options-f"/>), a strict field can be unpacked or - unboxed in the constructor, and one or more levels of - indirection may be removed. Unpacking only happens for - single-constructor datatypes (<literal>Int</literal> is a - good candidate, for example).</para> - - <para>Using <option>-funbox-strict-fields</option> is only - really a good idea in conjunction with <option>-O</option>, - because otherwise the extra packing and unpacking won't be - optimised away. In fact, it is possible that - <option>-funbox-strict-fields</option> may worsen - performance even <emphasis>with</emphasis> - <option>-O</option>, but this is unlikely (let us know if it - happens to you).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Use unboxed types (a GHC extension):</term> - <listitem> - <para>When you are <emphasis>really</emphasis> desperate for - speed, and you want to get right down to the “raw - bits.” Please see <xref linkend="glasgow-unboxed"/> for - some information about using unboxed types.</para> - - <para>Before resorting to explicit unboxed types, try using - strict constructor fields and - <option>-funbox-strict-fields</option> first (see above). - That way, your code stays portable.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Use <literal>foreign import</literal> (a GHC extension) to plug into fast libraries:</term> - <listitem> - <para>This may take real work, but… There exist piles - of massively-tuned library code, and the best thing is not - to compete with it, but link with it.</para> - - <para><xref linkend="ffi"/> describes the foreign function - interface.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Don't use <literal>Float</literal>s:</term> - <listitem> - <para>If you're using <literal>Complex</literal>, definitely - use <literal>Complex Double</literal> rather than - <literal>Complex Float</literal> (the former is specialised - heavily, but the latter isn't).</para> - - <para><literal>Floats</literal> (probably 32-bits) are - almost always a bad idea, anyway, unless you Really Know - What You Are Doing. Use <literal>Double</literal>s. - There's rarely a speed disadvantage—modern machines - will use the same floating-point unit for both. With - <literal>Double</literal>s, you are much less likely to hang - yourself with numerical errors.</para> - - <para>One time when <literal>Float</literal> might be a good - idea is if you have a <emphasis>lot</emphasis> of them, say - a giant array of <literal>Float</literal>s. They take up - half the space in the heap compared to - <literal>Doubles</literal>. However, this isn't true on a - 64-bit machine.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Use unboxed arrays (<literal>UArray</literal>)</term> - <listitem> - <para>GHC supports arrays of unboxed elements, for several - basic arithmetic element types including - <literal>Int</literal> and <literal>Char</literal>: see the - <literal>Data.Array.Unboxed</literal> library for details. - These arrays are likely to be much faster than using - standard Haskell 98 arrays from the - <literal>Data.Array</literal> library.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Use a bigger heap!</term> - <listitem> - <para>If your program's GC stats - (<option>-S</option><indexterm><primary>-S RTS - option</primary></indexterm> RTS option) indicate that it's - doing lots of garbage-collection (say, more than 20% - of execution time), more memory might help—with the - <option>-H<size></option><indexterm><primary>-H<size> - RTS option</primary></indexterm> or - <option>-A<size></option><indexterm><primary>-A<size> - RTS option</primary></indexterm> RTS options (see <xref - linkend="rts-options-gc"/>). As a rule of thumb, try - setting <option>-H<size></option> to the amount of memory - you're willing to let your process consume, or perhaps try passing - <option>-H</option> without any argument to let GHC calculate - a value based on the amount of live data.</para> - </listitem> - </varlistentry> - </variablelist> - -</sect1> - -<sect1 id="smaller"> -<title>Smaller: producing a program that is smaller -</title> - -<para> -<indexterm><primary>smaller programs, how to produce</primary></indexterm> -</para> - -<para> -Decrease the “go-for-it” threshold for unfolding smallish -expressions. Give a -<option>-funfolding-use-threshold0</option><indexterm><primary>-funfolding-use-threshold0 -option</primary></indexterm> option for the extreme case. (“Only unfoldings with -zero cost should proceed.”) Warning: except in certain specialised -cases (like Happy parsers) this is likely to actually -<emphasis>increase</emphasis> the size of your program, because unfolding -generally enables extra simplifying optimisations to be performed. -</para> - -<para> -Avoid <function>Read</function>. -</para> - -<para> -Use <literal>strip</literal> on your executables. -</para> - -</sect1> - -<sect1 id="thriftier"> -<title>Thriftier: producing a program that gobbles less heap space -</title> - -<para> -<indexterm><primary>memory, using less heap</primary></indexterm> -<indexterm><primary>space-leaks, avoiding</primary></indexterm> -<indexterm><primary>heap space, using less</primary></indexterm> -</para> - -<para> -“I think I have a space leak…” Re-run your program -with <option>+RTS -S</option>, and remove all doubt! (You'll -see the heap usage get bigger and bigger…) -[Hmmm…this might be even easier with the -<option>-G1</option> RTS option; so… <command>./a.out +RTS --S -G1</command>...] -<indexterm><primary>-G RTS option</primary></indexterm> -<indexterm><primary>-S RTS option</primary></indexterm> -</para> - -<para> -Once again, the profiling facilities (<xref linkend="profiling"/>) are -the basic tool for demystifying the space behaviour of your program. -</para> - -<para> -Strict functions are good for space usage, as they are for time, as -discussed in the previous section. Strict functions get right down to -business, rather than filling up the heap with closures (the system's -notes to itself about how to evaluate something, should it eventually -be required). -</para> - -</sect1> - -</chapter> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> diff --git a/docs/users_guide/ug-book.xml.in b/docs/users_guide/ug-book.xml.in deleted file mode 100644 index b87563ac3b..0000000000 --- a/docs/users_guide/ug-book.xml.in +++ /dev/null @@ -1,31 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<bookinfo> -<title>@ProjectName@ User's Guide, Version @ProjectVersion@</title> -<author><othername>The GHC Team</othername></author> -<address> -<email>glasgow-haskell-users-request@haskell.org</email> -</address> -</bookinfo> - -&license; -&intro; -&ghci; -&runghc; -&using; -&prof; -&sooner; -&lang-features; -&ffi-chap; -&extending-ghc; -&wrong; -&utils; -&win32-dll; -&bugs; - -<index/> -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; mode: xml *** - ;;; sgml-parent-document: ("users_guide.xml" "book") *** - ;;; End: *** - --> diff --git a/docs/users_guide/ug-ent.xml.in b/docs/users_guide/ug-ent.xml.in deleted file mode 100644 index b357ecf0e9..0000000000 --- a/docs/users_guide/ug-ent.xml.in +++ /dev/null @@ -1,31 +0,0 @@ -<!ENTITY ghci SYSTEM "ghci.xml"> -<!ENTITY runghc SYSTEM "runghc.xml"> -<!ENTITY flags SYSTEM "flags.xml"> -<!ENTITY license SYSTEM "license.xml"> -<!ENTITY intro SYSTEM "intro.xml" > -<!ENTITY relnotes1 SYSTEM "7.12.1-notes.xml" > -<!ENTITY using SYSTEM "using.xml" > -<!ENTITY code-gens SYSTEM "codegens.xml" > -<!ENTITY runtime SYSTEM "runtime_control.xml" > -<!ENTITY prof SYSTEM "profiling.xml" > -<!ENTITY debug SYSTEM "debugging.xml" > -<!ENTITY sooner SYSTEM "sooner.xml" > -<!ENTITY lang-features SYSTEM "lang.xml" > -<!ENTITY glasgowexts SYSTEM "glasgow_exts.xml" > -<!ENTITY packages SYSTEM "packages.xml" > -<!ENTITY parallel SYSTEM "parallel.xml" > -<!ENTITY safehaskell SYSTEM "safe_haskell.xml" > -<!ENTITY extending-ghc SYSTEM "extending_ghc.xml" > -<!ENTITY phases SYSTEM "phases.xml" > -<!ENTITY separate SYSTEM "separate_compilation.xml" > -<!ENTITY bugs SYSTEM "bugs.xml" > -<!ENTITY wrong SYSTEM "gone_wrong.xml" > -<!ENTITY utils SYSTEM "utils.xml" > -<!ENTITY win32-dll SYSTEM "win32-dlls.xml"> -<!ENTITY ffi-chap SYSTEM "ffi-chap.xml"> -<!ENTITY shared_libs SYSTEM "shared_libs.xml"> -<!ENTITY what_glasgow_exts_does SYSTEM "what_glasgow_exts_does.gen.xml"> -<!ENTITY libraryBaseLocation "../libraries/base-@LIBRARY_base_VERSION@"> -<!ENTITY libraryCabalLocation "../libraries/Cabal-@LIBRARY_Cabal_VERSION@"> -<!ENTITY libraryGhcPrimLocation "../libraries/ghc-prim-@LIBRARY_ghc_prim_VERSION@"> -<!ENTITY arw "->"> diff --git a/docs/users_guide/usage.rst b/docs/users_guide/usage.rst new file mode 100644 index 0000000000..be5ff59d97 --- /dev/null +++ b/docs/users_guide/usage.rst @@ -0,0 +1,16 @@ +Using GHC +========= + +.. toctree:: + using + using-warnings + using-optimisation + using-concurrent + flags + runtime_control + separate_compilation + packages + codegens + phases + shared_libs + debugging diff --git a/docs/users_guide/using-concurrent.rst b/docs/users_guide/using-concurrent.rst new file mode 100644 index 0000000000..c00a294132 --- /dev/null +++ b/docs/users_guide/using-concurrent.rst @@ -0,0 +1,196 @@ +.. _using-concurrent: + +Using Concurrent Haskell +------------------------ + +.. index:: + single: Concurrent Haskell; using + +GHC supports Concurrent Haskell by default, without requiring a special +option or libraries compiled in a certain way. To get access to the +support libraries for Concurrent Haskell, just import +:base-ref:`Control.Concurrent <Control-Concurrent.html>`. +More information on Concurrent Haskell is provided in the documentation +for that module. + +Optionally, the program may be linked with the ``-threaded`` option (see +:ref:`options-linker`. This provides two benefits: + +- It enables the ``-N``\ ``-Nx``\ RTS option RTS option to be used, + which allows threads to run in parallelparallelism on a + multiprocessormultiprocessorSMP or multicoremulticore machine. See + :ref:`using-smp`. + +- If a thread makes a foreign call (and the call is not marked + ``unsafe``), then other Haskell threads in the program will continue + to run while the foreign call is in progress. Additionally, + ``foreign export``\ ed Haskell functions may be called from multiple + OS threads simultaneously. See :ref:`ffi-threads`. + +The following RTS option(s) affect the behaviour of Concurrent Haskell +programs: + +.. index:: + single: RTS options; concurrent + +``-Cs`` + .. index:: + single: -Cs; RTS option + + Sets the context switch interval to ⟨s⟩ seconds. + A context switch will occur at the next heap block allocation after + the timer expires (a heap block allocation occurs every 4k of + allocation). With ``-C0`` or ``-C``, context switches will occur as + often as possible (at every heap block allocation). By default, + context switches occur every 20ms. + +.. _using-smp: + +Using SMP parallelism +--------------------- + +.. index:: + single: parallelism + single: SMP + +GHC supports running Haskell programs in parallel on an SMP (symmetric +multiprocessor). + +There's a fine distinction between *concurrency* and *parallelism*: +parallelism is all about making your program run *faster* by making use +of multiple processors simultaneously. Concurrency, on the other hand, +is a means of abstraction: it is a convenient way to structure a program +that must respond to multiple asynchronous events. + +However, the two terms are certainly related. By making use of multiple +CPUs it is possible to run concurrent threads in parallel, and this is +exactly what GHC's SMP parallelism support does. But it is also possible +to obtain performance improvements with parallelism on programs that do +not use concurrency. This section describes how to use GHC to compile +and run parallel programs, in :ref:`lang-parallel` we describe the +language features that affect parallelism. + +.. _parallel-compile-options: + +Compile-time options for SMP parallelism +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In order to make use of multiple CPUs, your program must be linked with +the ``-threaded`` option (see :ref:`options-linker`). Additionally, the +following compiler options affect parallelism: + +``-feager-blackholing`` + Blackholing is the act of marking a thunk (lazy computuation) as + being under evaluation. It is useful for three reasons: firstly it + lets us detect certain kinds of infinite loop (the + ``NonTermination`` exception), secondly it avoids certain kinds of + space leak, and thirdly it avoids repeating a computation in a + parallel program, because we can tell when a computation is already + in progress. + + The option ``-feager-blackholing`` causes each thunk to be + blackholed as soon as evaluation begins. The default is "lazy + blackholing", whereby thunks are only marked as being under + evaluation when a thread is paused for some reason. Lazy blackholing + is typically more efficient (by 1-2% or so), because most thunks + don't need to be blackholed. However, eager blackholing can avoid + more repeated computation in a parallel program, and this often + turns out to be important for parallelism. + + We recommend compiling any code that is intended to be run in + parallel with the ``-feager-blackholing`` flag. + +.. _parallel-options: + +RTS options for SMP parallelism +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two ways to run a program on multiple processors: call +``Control.Concurrent.setNumCapabilities`` from your program, or use the +RTS ``-N`` option. + +``-N⟨x⟩`` + .. index:: + single: -N⟨x⟩; RTS option + + Use ⟨x⟩ simultaneous threads when running the program. + + The runtime manages a set of virtual processors, which we call + *capabilities*, the number of which is determined by the ``-N`` + option. Each capability can run one Haskell thread at a time, so the + number of capabilities is equal to the number of Haskell threads + that can run physically in parallel. A capability is animated by one + or more OS threads; the runtime manages a pool of OS threads for + each capability, so that if a Haskell thread makes a foreign call + (see :ref:`ffi-threads`) another OS thread can take over that + capability. + + Normally ⟨x⟩ should be chosen to match the number of CPU cores on + the machine [1]_. For example, on a dual-core machine we would + probably use ``+RTS -N2 -RTS``. + + Omitting ⟨x⟩, i.e. ``+RTS -N -RTS``, lets the runtime choose the + value of ⟨x⟩ itself based on how many processors are in your + machine. + + Be careful when using all the processors in your machine: if some of + your processors are in use by other programs, this can actually harm + performance rather than improve it. + + Setting ``-N`` also has the effect of enabling the parallel garbage + collector (see :ref:`rts-options-gc`). + + The current value of the ``-N`` option is available to the Haskell + program via ``Control.Concurrent.getNumCapabilities``, and it may be + changed while the program is running by calling + ``Control.Concurrent.setNumCapabilities``. + +The following options affect the way the runtime schedules threads on +CPUs: + +``-qa`` + Use the OS's affinity facilities to try to pin OS threads to CPU + cores. + + When this option is enabled, the OS threads for a capability *i* are + bound to the CPU core *i* using the API provided by the OS for + setting thread affinity. e.g. on Linux GHC uses + ``sched_setaffinity()``. + + Depending on your workload and the other activity on the machine, + this may or may not result in a performance improvement. We + recommend trying it out and measuring the difference. + +``-qm`` + Disable automatic migration for load balancing. Normally the runtime + will automatically try to schedule threads across the available CPUs + to make use of idle CPUs; this option disables that behaviour. Note + that migration only applies to threads; sparks created by ``par`` + are load-balanced separately by work-stealing. + + This option is probably only of use for concurrent programs that + explicitly schedule threads onto CPUs with + ``Control.Concurrent.forkOn``. + +Hints for using SMP parallelism +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Add the ``-s`` RTS option when running the program to see timing stats, +which will help to tell you whether your program got faster by using +more CPUs or not. If the user time is greater than the elapsed time, +then the program used more than one CPU. You should also run the program +without ``-N`` for comparison. + +The output of ``+RTS -s`` tells you how many "sparks" were created and +executed during the run of the program (see :ref:`rts-options-gc`), +which will give you an idea how well your ``par`` annotations are +working. + +GHC's parallelism support has improved in 6.12.1 as a result of much +experimentation and tuning in the runtime system. We'd still be +interested to hear how well it works for you, and we're also interested +in collecting parallel programs to add to our benchmarking suite. + +.. [1] Whether hyperthreading cores should be counted or not is an open + question; please feel free to experiment and let us know what results you + find. diff --git a/docs/users_guide/using-optimisation.rst b/docs/users_guide/using-optimisation.rst new file mode 100644 index 0000000000..84bf27b4d4 --- /dev/null +++ b/docs/users_guide/using-optimisation.rst @@ -0,0 +1,780 @@ +.. _options-optimise: + +Optimisation (code improvement) +------------------------------- + +.. index:: + single: optimisation + single: improvement, code + +The ``-O*`` options specify convenient "packages" of optimisation flags; +the ``-f*`` options described later on specify *individual* +optimisations to be turned on/off; the ``-m*`` options specify +*machine-specific* optimisations to be turned on/off. + +Most of these options are boolean and have options to turn them both "on" and +"off" (beginning with the prefix ``no-``). For instance, while ``-fspecialise`` +enables specialisation, ``-fno-specialise`` disables it. When multiple flags for +the same option appear in the command-line they are evaluated from left to +right. For instance, ``-fno-specialise -fspecialise`` will enable +specialisation. + +It is important to note that the ``-O*`` flags are roughly equivalent to +combinations of ``-f*`` flags. For this reason, the effect of the +``-O*`` and ``-f*`` flags is dependent upon the order in which they +occur on the command line. + +For instance, take the example of ``-fno-specialise -O1``. Despite the +``-fno-specialise`` appearing in the command line, specialisation will +still be enabled. This is the case as ``-O1`` implies ``-fspecialise``, +overriding the previous flag. By contrast, ``-O1 -fno-specialise`` will +compile without specialisation, as one would expect. + +.. _optimise-pkgs: + +``-O*``: convenient “packages” of optimisation flags. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are *many* options that affect the quality of code produced by +GHC. Most people only have a general goal, something like "Compile +quickly" or "Make my program run like greased lightning." The following +"packages" of optimisations (or lack thereof) should suffice. + +Note that higher optimisation levels cause more cross-module +optimisation to be performed, which can have an impact on how much of +your program needs to be recompiled when you change something. This is +one reason to stick to no-optimisation when developing code. + +``-O*`` + .. index:: + single: -O\* not specified + + This is taken to mean: “Please compile quickly; I'm not + over-bothered about compiled-code quality.” So, for example: + ``ghc -c Foo.hs`` + +``-O0`` + .. index:: + single: -O0 + + Means "turn off all optimisation", reverting to the same settings as + if no ``-O`` options had been specified. Saying ``-O0`` can be + useful if eg. ``make`` has inserted a ``-O`` on the command line + already. + +``-O``, ``-O1`` + .. index:: + single: -O option + single: -O1 option + single: optimise; normally + + Means: "Generate good-quality code without taking too long about + it." Thus, for example: ``ghc -c -O Main.lhs`` + +``-O2`` + .. index:: + single: -O2 option + single: optimise; aggressively + + Means: "Apply every non-dangerous optimisation, even if it means + significantly longer compile times." + + The avoided "dangerous" optimisations are those that can make + runtime or space *worse* if you're unlucky. They are normally turned + on or off individually. + + At the moment, ``-O2`` is *unlikely* to produce better code than + ``-O``. + +``-Odph`` + .. index:: + single: -Odph + single: optimise; DPH + + Enables all ``-O2`` optimisation, sets + ``-fmax-simplifier-iterations=20`` and ``-fsimplifier-phases=3``. + Designed for use with :ref:`Data Parallel Haskell (DPH) <dph>`. + +We don't use a ``-O*`` flag for day-to-day work. We use ``-O`` to get +respectable speed; e.g., when we want to measure something. When we want +to go for broke, we tend to use ``-O2`` (and we go for lots of coffee +breaks). + +The easiest way to see what ``-O`` (etc.) “really mean” is to run with +``-v``, then stand back in amazement. + +.. _options-f: + +``-f*``: platform-independent flags +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: -f\* options (GHC) + single: -fno-\* options (GHC) + +These flags turn on and off individual optimisations. Flags marked as +*Enabled by default* are enabled by ``-O``, and as such you shouldn't +need to set any of them explicitly. A flag ``-fwombat`` can be negated +by saying ``-fno-wombat``. See :ref:`options-f-compact` for a compact +list. + +``-fcase-merge`` + .. index:: + single: -fcase-merge + + *On by default.* Merge immediately-nested case expressions that + scrutinse the same variable. For example, + + :: + + case x of + Red -> e1 + _ -> case x of + Blue -> e2 + Green -> e3 + + Is transformed to, + + :: + case x of + Red -> e1 + Blue -> e2 + Green -> e2 + +``-fcall-arity`` + .. index:: + single: -fcall-arity + + *On by default.*. + +``-fcmm-elim-common-blocks`` + .. index:: + single: -felim-common-blocks + + *On by default.*. Enables the common block elimination optimisation + in the code generator. This optimisation attempts to find identical + Cmm blocks and eliminate the duplicates. + +``-fcmm-sink`` + .. index:: + single: -fcmm-sink + + *On by default.*. Enables the sinking pass in the code generator. + This optimisation attempts to find identical Cmm blocks and + eliminate the duplicates attempts to move variable bindings closer + to their usage sites. It also inlines simple expressions like + literals or registers. + +``-fcpr-off`` + .. index:: + single: -fcpr-Off + + Switch off CPR analysis in the demand analyser. + +``-fcse`` + .. index:: + single: -fcse + + *On by default.*. Enables the common-sub-expression elimination + optimisation. Switching this off can be useful if you have some + ``unsafePerformIO`` expressions that you don't want commoned-up. + +``-fdicts-cheap`` + .. index:: + single: -fdicts-cheap + + A very experimental flag that makes dictionary-valued expressions + seem cheap to the optimiser. + +``-fdicts-strict`` + .. index:: + single: -fdicts-strict + + Make dictionaries strict. + +``-fdmd-tx-dict-sel`` + .. index:: + single: -fdmd-tx-dict-sel + + *On by default for ``-O0``, ``-O``, ``-O2``.* + + Use a special demand transformer for dictionary selectors. + +``-fdo-eta-reduction`` + .. index:: + single: -fdo-eta-reduction + + *On by default.* Eta-reduce lambda expressions, if doing so gets rid + of a whole group of lambdas. + +``-fdo-lambda-eta-expansion`` + .. index:: + single: -fdo-lambda-eta-expansion + + *On by default.* Eta-expand let-bindings to increase their arity. + +``-feager-blackholing`` + .. index:: + single: -feager-blackholing + + Usually GHC black-holes a thunk only when it switches threads. This + flag makes it do so as soon as the thunk is entered. See `Haskell on + a shared-memory + multiprocessor <http://research.microsoft.com/en-us/um/people/simonpj/papers/parallel/>`__. + +``-fexcess-precision`` + .. index:: + single: -fexcess-precision + + When this option is given, intermediate floating point values can + have a *greater* precision/range than the final type. Generally this + is a good thing, but some programs may rely on the exact + precision/range of ``Float``/``Double`` values and should not use + this option for their compilation. + + Note that the 32-bit x86 native code generator only supports + excess-precision mode, so neither ``-fexcess-precision`` nor + ``-fno-excess-precision`` has any effect. This is a known bug, see + :ref:`bugs-ghc`. + +``-fexpose-all-unfoldings`` + .. index:: + single: -fexpose-all-unfoldings + + An experimental flag to expose all unfoldings, even for very large + or recursive functions. This allows for all functions to be inlined + while usually GHC would avoid inlining larger functions. + +``-ffloat-in`` + .. index:: + single: -ffloat-in + + *On by default.* Float let-bindings inwards, nearer their binding + site. See `Let-floating: moving bindings to give faster programs + (ICFP'96) <http://research.microsoft.com/en-us/um/people/simonpj/papers/float.ps.gz>`__. + + This optimisation moves let bindings closer to their use site. The + benefit here is that this may avoid unnecessary allocation if the + branch the let is now on is never executed. It also enables other + optimisation passes to work more effectively as they have more + information locally. + + This optimisation isn't always beneficial though (so GHC applies + some heuristics to decide when to apply it). The details get + complicated but a simple example is that it is often beneficial to + move let bindings outwards so that multiple let bindings can be + grouped into a larger single let binding, effectively batching their + allocation and helping the garbage collector and allocator. + +``-ffull-laziness`` + .. index:: + single: -ffull-laziness + + *On by default.* Run the full laziness optimisation (also known as + let-floating), which floats let-bindings outside enclosing lambdas, + in the hope they will be thereby be computed less often. See + `Let-floating: moving bindings to give faster programs + (ICFP'96) <http://research.microsoft.com/en-us/um/people/simonpj/papers/float.ps.gz>`__. + Full laziness increases sharing, which can lead to increased memory + residency. + + .. note:: + GHC doesn't implement complete full-laziness. When + optimisation in on, and ``-fno-full-laziness`` is not given, some + transformations that increase sharing are performed, such as + extracting repeated computations from a loop. These are the same + transformations that a fully lazy implementation would do, the + difference is that GHC doesn't consistently apply full-laziness, so + don't rely on it. + +``-ffun-to-thunk`` + .. index:: + single: -ffun-to-thunk + + Worker-wrapper removes unused arguments, but usually we do not + remove them all, lest it turn a function closure into a thunk, + thereby perhaps creating a space leak and/or disrupting inlining. + This flag allows worker/wrapper to remove *all* value lambdas. Off + by default. + +``-fignore-asserts`` + .. index:: + single: -fignore-asserts + + *On by default.*. Causes GHC to ignore uses of the function + ``Exception.assert`` in source code (in other words, rewriting + ``Exception.assert p e`` to ``e`` (see :ref:`assertions`). + +``-fignore-interface-pragmas`` + .. index:: + single: -fignore-interface-pragmas + + Tells GHC to ignore all inessential information when reading + interface files. That is, even if ``M.hi`` contains unfolding or + strictness information for a function, GHC will ignore that + information. + +``-flate-dmd-anal`` + .. index:: + single: -flate-dmd-anal + + Run demand analysis again, at the end of the simplification + pipeline. We found some opportunities for discovering strictness + that were not visible earlier; and optimisations like + ``-fspec-constr`` can create functions with unused arguments which + are eliminated by late demand analysis. Improvements are modest, but + so is the cost. See notes on the :ghc-wiki:`Trac wiki page <LateDmd>`. + +``-fliberate-case`` + .. index:: + single: -fliberate-case + + *Off by default, but enabled by -O2.* Turn on the liberate-case + transformation. This unrolls recursive function once in its own RHS, + to avoid repeated case analysis of free variables. It's a bit like + the call-pattern specialiser (``-fspec-constr``) but for free + variables rather than arguments. + +``-fliberate-case-threshold=n`` + .. index:: + single: -fliberate-case-threshold + + *default: 2000.* Set the size threshold for the liberate-case + transformation. + +``-floopification`` + .. index:: + single: -floopification + + *On by default.* + + When this optimisation is enabled the code generator will turn all + self-recursive saturated tail calls into local jumps rather than + function calls. + +``-fmax-inline-alloc-size=n`` + .. index:: + single: -fmax-inline-alloc-size + + *default: 128.* Set the maximum size of inline array allocations to n bytes. + GHC will allocate non-pinned arrays of statically known size in the current + nursery block if they're no bigger than n bytes, ignoring GC overheap. This + value should be quite a bit smaller than the block size (typically: 4096). + +``-fmax-inline-memcpy-insn=n`` + .. index:: + single: -fmax-inline-memcpy-insn + + *default: 32.* Inline ``memcpy`` calls if they would generate no more than n pseudo + instructions. + +``-fmax-inline-memset-insns=n`` + .. index:: + single: -fmax-inline-memset-insns + + *default: 32.* Inline ``memset`` calls if they would generate no more than n pseudo + instructions. + +``-fmax-relevant-binds=n`` + .. index:: + single: -fmax-relevant-bindings + + The type checker sometimes displays a fragment of the type + environment in error messages, but only up to some maximum number, + set by this flag. The default is 6. Turning it off with + ``-fno-max-relevant-bindings`` gives an unlimited number. + Syntactically top-level bindings are also usually excluded (since + they may be numerous), but ``-fno-max-relevant-bindings`` includes + them too. + +``-fmax-simplifier-iterations=n`` + .. index:: + single: -fmax-simplifier-iterations + + *default: 4.* Sets the maximal number of iterations for the simplifier. + +``-fmax-worker-args=n`` + .. index:: + single: -fmax-worker-args + + *default: 10.* If a worker has that many arguments, none will be unpacked + anymore. + +``-fno-opt-coercion`` + .. index:: + single: -fno-opt-coercion + + Turn off the coercion optimiser. + +``-fno-pre-inlining`` + .. index:: + single: -fno-pre-inlining + + Turn off pre-inlining. + +``-fno-state-hack`` + .. index:: + single: -fno-state-hack + + Turn off the "state hack" whereby any lambda with a ``State#`` token + as argument is considered to be single-entry, hence it is considered + OK to inline things inside it. This can improve performance of IO + and ST monad code, but it runs the risk of reducing sharing. + +``-fomit-interface-pragmas`` + .. index:: + single: -fomit-interface-pragmas + + Tells GHC to omit all inessential information from the interface + file generated for the module being compiled (say M). This means + that a module importing M will see only the *types* of the functions + that M exports, but not their unfoldings, strictness info, etc. + Hence, for example, no function exported by M will be inlined into + an importing module. The benefit is that modules that import M will + need to be recompiled less often (only when M's exports change their + type, not when they change their implementation). + +``-fomit-yields`` + .. index:: + single: -fomit-yields + + *On by default.* Tells GHC to omit heap checks when no allocation is + being performed. While this improves binary sizes by about 5%, it + also means that threads run in tight non-allocating loops will not + get preempted in a timely fashion. If it is important to always be + able to interrupt such threads, you should turn this optimization + off. Consider also recompiling all libraries with this optimization + turned off, if you need to guarantee interruptibility. + +``-fpedantic-bottoms`` + .. index:: + single: -fpedantic-bottoms + + Make GHC be more precise about its treatment of bottom (but see also + ``-fno-state-hack``). In particular, stop GHC eta-expanding through + a case expression, which is good for performance, but bad if you are + using ``seq`` on partial applications. + +``-fregs-graph`` + .. index:: + single: -fregs-graph + + *Off by default due to a performance regression bug. Only applies in + combination with the native code generator.* Use the graph colouring + register allocator for register allocation in the native code + generator. By default, GHC uses a simpler, faster linear register + allocator. The downside being that the linear register allocator + usually generates worse code. + +``-fregs-iterative`` + .. index:: + single: -fregs-iterative + + *Off by default, only applies in combination with the native code + generator.* Use the iterative coalescing graph colouring register + allocator for register allocation in the native code generator. This + is the same register allocator as the ``-fregs-graph`` one but also + enables iterative coalescing during register allocation. + +``-fsimplifier-phases=n`` + .. index:: + single: -fsimplifier-phases + + *default: 2.* Set the number of phases for the simplifier. Ignored + with -O0. + +``-fsimpl-tick-factor=n`` + .. index:: + single: -fsimpl-tick-factor + + *default: 100.* GHC's optimiser can diverge if you write rewrite rules + (:ref:`rewrite-rules`) that don't terminate, or (less satisfactorily) + if you code up recursion through data types (:ref:`bugs-ghc`). To + avoid making the compiler fall into an infinite loop, the optimiser + carries a "tick count" and stops inlining and applying rewrite rules + when this count is exceeded. The limit is set as a multiple of the + program size, so bigger programs get more ticks. The + ``-fsimpl-tick-factor`` flag lets you change the multiplier. The + default is 100; numbers larger than 100 give more ticks, and numbers + smaller than 100 give fewer. + + If the tick-count expires, GHC summarises what simplifier steps it + has done; you can use ``-fddump-simpl-stats`` to generate a much + more detailed list. Usually that identifies the loop quite + accurately, because some numbers are very large. + +``-fspec-constr`` + .. index:: + single: -fspec-constr + + *Off by default, but enabled by -O2.* Turn on call-pattern + specialisation; see `Call-pattern specialisation for Haskell + programs <http://research.microsoft.com/en-us/um/people/simonpj/papers/spec-constr/index.htm>`__. + + This optimisation specializes recursive functions according to their + argument "shapes". This is best explained by example so consider: + + :: + + last :: [a] -> a + last [] = error "last" + last (x : []) = x + last (x : xs) = last xs + + In this code, once we pass the initial check for an empty list we + know that in the recursive case this pattern match is redundant. As + such ``-fspec-constr`` will transform the above code to: + + :: + + last :: [a] -> a + last [] = error "last" + last (x : xs) = last' x xs + where + last' x [] = x + last' x (y : ys) = last' y ys + + As well avoid unnecessary pattern matching it also helps avoid + unnecessary allocation. This applies when a argument is strict in + the recursive call to itself but not on the initial entry. As strict + recursive branch of the function is created similar to the above + example. + + It is also possible for library writers to instruct GHC to perform + call-pattern specialisation extremely aggressively. This is + necessary for some highly optimized libraries, where we may want to + specialize regardless of the number of specialisations, or the size + of the code. As an example, consider a simplified use-case from the + ``vector`` library: + + :: + + import GHC.Types (SPEC(..)) + + foldl :: (a -> b -> a) -> a -> Stream b -> a + {-# INLINE foldl #-} + foldl f z (Stream step s _) = foldl_loop SPEC z s + where + foldl_loop !sPEC z s = case step s of + Yield x s' -> foldl_loop sPEC (f z x) s' + Skip -> foldl_loop sPEC z s' + Done -> z + + Here, after GHC inlines the body of ``foldl`` to a call site, it + will perform call-pattern specialisation very aggressively on + ``foldl_loop`` due to the use of ``SPEC`` in the argument of the + loop body. ``SPEC`` from ``GHC.Types`` is specifically recognised by + the compiler. + + (NB: it is extremely important you use ``seq`` or a bang pattern on + the ``SPEC`` argument!) + + In particular, after inlining this will expose ``f`` to the loop + body directly, allowing heavy specialisation over the recursive + cases. + +``-fspec-constr-count=n`` + .. index:: + single: -fspec-constr-count + + *default: 3.* Set the maximum number of specialisations that will be created for + any one function by the SpecConstr transformation. + +``-fspec-constr-threshold=n`` + .. index:: + single: -fspec-constr-threshold + + *default: 2000.* Set the size threshold for the SpecConstr transformation. + +``-fspecialise`` + .. index:: + single: -fspecialise + + *On by default.* Specialise each type-class-overloaded function + defined in this module for the types at which it is called in this + module. If ``-fcross-module-specialise`` is set imported functions + that have an INLINABLE pragma (:ref:`inlinable-pragma`) will be + specialised as well. + +``-fcross-module-specialise`` + .. index:: + single: -fcross-module-specialise + + *On by default.* Specialise ``INLINABLE`` (:ref:`inlinable-pragma`) + type-class-overloaded functions imported from other modules for the types at + which they are called in this module. Note that specialisation must be + enabled (by ``-fspecialise``) for this to have any effect. + +``-fstatic-argument-transformation`` + .. index:: + single: -fstatic-argument-transformation + + Turn on the static argument transformation, which turns a recursive + function into a non-recursive one with a local recursive loop. See + Chapter 7 of `Andre Santos's PhD + thesis <http://research.microsoft.com/en-us/um/people/simonpj/papers/santos-thesis.ps.gz>`__ + +``-fstrictness`` + .. index:: + single: -fstrictness + + *On by default.*. Switch on the strictness analyser. There is a very + old paper about GHC's strictness analyser, `Measuring the + effectiveness of a simple strictness + analyser <http://research.microsoft.com/en-us/um/people/simonpj/papers/simple-strictnes-analyser.ps.gz>`__, + but the current one is quite a bit different. + + The strictness analyser figures out when arguments and variables in + a function can be treated 'strictly' (that is they are always + evaluated in the function at some point). This allow GHC to apply + certain optimisations such as unboxing that otherwise don't apply as + they change the semantics of the program when applied to lazy + arguments. + +``-fstrictness-before=⟨n⟩`` + .. index:: + single: -fstrictness-before + + Run an additional strictness analysis before simplifier phase ⟨n⟩. + +``-funbox-small-strict-fields`` + .. index:: + single: -funbox-small-strict-fields + single: strict constructor fields + single: constructor fields, strict + + *On by default.*. This option causes all constructor fields which + are marked strict (i.e. “!”) and which representation is smaller or + equal to the size of a pointer to be unpacked, if possible. It is + equivalent to adding an ``UNPACK`` pragma (see :ref:`unpack-pragma`) + to every strict constructor field that fulfils the size restriction. + + For example, the constructor fields in the following data types + + :: + + data A = A !Int + data B = B !A + newtype C = C B + data D = D !C + + would all be represented by a single ``Int#`` (see + :ref:`primitives`) value with ``-funbox-small-strict-fields`` + enabled. + + This option is less of a sledgehammer than + ``-funbox-strict-fields``: it should rarely make things worse. If + you use ``-funbox-small-strict-fields`` to turn on unboxing by + default you can disable it for certain constructor fields using the + ``NOUNPACK`` pragma (see :ref:`nounpack-pragma`). + + Note that for consistency ``Double``, ``Word64``, and ``Int64`` + constructor fields are unpacked on 32-bit platforms, even though + they are technically larger than a pointer on those platforms. + +``-funbox-strict-fields`` + .. index:: + single: -funbox-strict-fields + single: strict constructor fields + single: constructor fields, strict + + This option causes all constructor fields which are marked strict + (i.e. “!”) to be unpacked if possible. It is equivalent to adding an + ``UNPACK`` pragma to every strict constructor field (see + :ref:`unpack-pragma`). + + This option is a bit of a sledgehammer: it might sometimes make + things worse. Selectively unboxing fields by using ``UNPACK`` + pragmas might be better. An alternative is to use + ``-funbox-strict-fields`` to turn on unboxing by default but disable + it for certain constructor fields using the ``NOUNPACK`` pragma (see + :ref:`nounpack-pragma`). + +``-funfolding-creation-threshold=n`` + .. index:: + single: -funfolding-creation-threshold + single: inlining, controlling + single: unfolding, controlling + + *default: 750.* Governs the maximum size that GHC will allow a + function unfolding to be. (An unfolding has a “size” that reflects + the cost in terms of “code bloat” of expanding (aka inlining) that + unfolding at a call site. A bigger function would be assigned a + bigger cost.) + + Consequences: (a) nothing larger than this will be inlined (unless + it has an INLINE pragma); (b) nothing larger than this will be + spewed into an interface file. + + Increasing this figure is more likely to result in longer compile + times than faster code. The ``-funfolding-use-threshold`` is more + useful. + +``-funfolding-dict-discount=n`` + .. index:: + single: -funfolding-dict-discount + single: inlining, controlling + single: unfolding, controlling + + Default: 30 + +``-funfolding-fun-discount=n`` + .. index:: + single: -funfolding-fun-discount + single: inlining, controlling + single: unfolding, controlling + + Default: 60 + +``-funfolding-keeness-factor=n`` + .. index:: + single: -funfolding-keeness-factor + single: inlining, controlling + single: unfolding, controlling + + Default: 1.5 + +``-funfolding-use-threshold=n`` + .. index:: + single: -funfolding-use-threshold + single: inlining, controlling + single: unfolding, controlling + + *default: 60.* This is the magic cut-off figure for unfolding (aka + inlining): below this size, a function definition will be unfolded + at the call-site, any bigger and it won't. The size computed for a + function depends on two things: the actual size of the expression + minus any discounts that apply depending on the context into which + the expression is to be inlined. + + The difference between this and ``-funfolding-creation-threshold`` + is that this one determines if a function definition will be inlined + *at a call site*. The other option determines if a function + definition will be kept around at all for potential inlining. + +``-fvectorisation-avoidance`` + .. index:: + single: -fvectorisation-avoidance + + Part of :ref:`Data Parallel Haskell (DPH) <dph>`. + + *On by default.* Enable the *vectorisation* avoidance optimisation. + This optimisation only works when used in combination with the + ``-fvectorise`` transformation. + + While vectorisation of code using DPH is often a big win, it can + also produce worse results for some kinds of code. This optimisation + modifies the vectorisation transformation to try to determine if a + function would be better of unvectorised and if so, do just that. + +``-fvectorise`` + .. index:: + single: -fvectorise + + Part of :ref:`Data Parallel Haskell (DPH) <dph>`. + + *Off by default.* Enable the *vectorisation* optimisation + transformation. This optimisation transforms the nested data + parallelism code of programs using DPH into flat data parallelism. + Flat data parallel programs should have better load balancing, + enable SIMD parallelism and friendlier cache behaviour. diff --git a/docs/users_guide/using-warnings.rst b/docs/users_guide/using-warnings.rst new file mode 100644 index 0000000000..0b3faa4105 --- /dev/null +++ b/docs/users_guide/using-warnings.rst @@ -0,0 +1,861 @@ +.. _options-sanity: + +Warnings and sanity-checking +---------------------------- + +.. index:: + single: sanity-checking options + single: warnings + +GHC has a number of options that select which types of non-fatal error +messages, otherwise known as warnings, can be generated during +compilation. By default, you get a standard set of warnings which are +generally likely to indicate bugs in your program. These are: +``-fwarn-overlapping-patterns``, ``-fwarn-warnings-deprecations``, +``-fwarn-deprecated-flags``, ``-fwarn-unrecognised-pragmas``, +``-fwarn-missed-specialisations``, ``-fwarn-duplicate-constraints``, +``-fwarn-duplicate-exports``, ``-fwarn-overflowed-literals``, +``-fwarn-empty-enumerations``, ``-fwarn-missing-fields``, +``-fwarn-missing-methods``, ``-fwarn-wrong-do-bind``, +``-fwarn-unsupported-calling-conventions``, +``-fwarn-dodgy-foreign-imports``, ``-fwarn-inline-rule-shadowing``, +``-fwarn-unsupported-llvm-version``, ``-fwarn-context-quantification``, +and ``-fwarn-tabs``. The following flags are simple ways to select +standard “packages” of warnings: + +``-W`` + .. index:: + single: -W option + + Provides the standard warnings plus ``-fwarn-unused-binds``, + ``-fwarn-unused-matches``, ``-fwarn-unused-imports``, + ``-fwarn-incomplete-patterns``, ``-fwarn-dodgy-exports``, and + ``-fwarn-dodgy-imports``. + +``-Wall`` + .. index:: + single: -Wall + + Turns on all warning options that indicate potentially suspicious + code. The warnings that are *not* enabled by ``-Wall`` are + ``-fwarn-incomplete-uni-patterns``, + ``-fwarn-incomplete-record-updates``, + ``-fwarn-monomorphism-restriction``, ``-fwarn-auto-orphans``, + ``-fwarn-implicit-prelude``, ``-fwarn-missing-local-sigs``, + ``-fwarn-missing-exported-sigs``, ``-fwarn-missing-import-lists`` + and ``-fwarn-identities``. + +``-w`` + .. index:: + single: -w + + Turns off all warnings, including the standard ones and those that + ``-Wall`` doesn't enable. + +``-Werror`` + .. index:: + single: -Werror + + Makes any warning into a fatal error. Useful so that you don't miss + warnings when doing batch compilation. + +``-Wwarn`` + .. index:: + single: -Wwarn + + Warnings are treated only as warnings, not as errors. This is the + default, but can be useful to negate a ``-Werror`` flag. + +The full set of warning options is described below. To turn off any +warning, simply give the corresponding ``-fno-warn-...`` option on the +command line. + +``-fwarn-typed-holes`` + .. index:: + single: -fwarn-typed-holes + single: warnings + + Determines whether the compiler reports typed holes warnings. Has no + effect unless typed holes errors are deferred until runtime. See + :ref:`typed-holes` and :ref:`defer-type-errors` + + This warning is on by default. + +``-fwarn-type-errors`` + .. index:: + single: -fwarn-type-errors + single: warnings + + Causes a warning to be reported when a type error is deferred until + runtime. See :ref:`defer-type-errors` + + This warning is on by default. + +``-fdefer-type-errors`` + .. index:: + single: -fdefer-type-errors + single: warnings + + Defer as many type errors as possible until runtime. At compile time + you get a warning (instead of an error). At runtime, if you use a + value that depends on a type error, you get a runtime error; but you + can run any type-correct parts of your code just fine. See + :ref:`defer-type-errors` + +``-fdefer-typed-holes`` + .. index:: + single: -fdefer-typed-holes + single: warnings + + Defer typed holes errors until runtime. This will turn the errors + produced by :ref:`typed holes <typed-holes>` into warnings. Using a value + that depends on a typed hole produces a runtime error, the same as + ``-fdefer-type-errors`` (which implies this option). See :ref:`typed-holes` + and :ref:`defer-type-errors`. + + Implied by ``-fdefer-type-errors``. See also ``-fwarn-typed-holes``. + +``-fwarn-partial-type-signatures`` + .. index:: + single: -fwarn-partial-type-signatures + single: warnings + + Determines whether the compiler reports holes in partial type + signatures as warnings. Has no effect unless + ``-XPartialTypeSignatures`` is enabled, which controls whether + errors should be generated for holes in types or not. See + :ref:`partial-type-signatures`. + + This warning is on by default. + +``-fhelpful-errors`` + .. index:: + single: -fhelpful-errors + single: warnings + + When a name or package is not found in scope, make suggestions for + the name or package you might have meant instead. + + This option is on by default. + +``-fwarn-unrecognised-pragmas`` + .. index:: + single: -fwarn-unrecognised-pragmas + single: warnings + single: pragmas + + Causes a warning to be emitted when a pragma that GHC doesn't + recognise is used. As well as pragmas that GHC itself uses, GHC also + recognises pragmas known to be used by other tools, e.g. + ``OPTIONS_HUGS`` and ``DERIVE``. + + This option is on by default. + +``-fwarn-missed-specialisations``, ``-fwarn-all-missed-specialisations`` + .. index:: + single: -fwarn-missed-specialisations + single: -fwarn-all-missed-specialisations + single: warnings + single: pragmas + + Emits a warning if GHC cannot specialise a function that is imported + and overloaded, usually because the function needs an ``INLINEABLE`` + pragma.. The "all" form reports all such situations. The "non-all" + form only reports when the situation arises during specialisation of + an imported function; presumably teh latter was marked + ``INLINEABLE`` so that it would specialise but if it, in turn, calls + other functions that are not specialised you won't get the + performance boost you expect. + + ``-fwarn-missed-specialisations`` is on by default; + ``-fwarn-all-missed-specialisations`` is implied by ``-Wall``. + +``-fwarn-warnings-deprecations`` + .. index:: + single: -fwarn-warnings-deprecations + single: warnings + single: deprecations + + Causes a warning to be emitted when a module, function or type with + a ``WARNING`` or ``DEPRECATED pragma`` is used. See + :ref:`warning-deprecated-pragma` for more details on the pragmas. + + This option is on by default. + +``-fwarn-amp`` + .. index:: + single: -fwarn-amp + single: AMP + single: Applicative-Monad Proposal + + Causes a warning to be emitted when a definition is in conflict with + the AMP (Applicative-Monad proosal), namely: 1. Instance of Monad + without Applicative; 2. Instance of MonadPlus without Alternative; + 3. Custom definitions of join/pure/<\*> + + This option is on by default. + +``-fwarn-deprecated-flags`` + .. index:: + single: -fwarn-deprecated-flags + single: deprecated-flags + + Causes a warning to be emitted when a deprecated command-line flag + is used. + + This option is on by default. + +``-fwarn-unsupported-calling-conventions`` + .. index:: + single: -fwarn-unsupported-calling-conventions + + Causes a warning to be emitted for foreign declarations that use + unsupported calling conventions. In particular, if the ``stdcall`` + calling convention is used on an architecture other than i386 then + it will be treated as ``ccall``. + +``-fwarn-dodgy-foreign-imports`` + .. index:: + single: -fwarn-dodgy-foreign-imports + + Causes a warning to be emitted for foreign imports of the following + form: + + :: + + foreign import "f" f :: FunPtr t + + on the grounds that it probably should be + + :: + + foreign import "&f" f :: FunPtr t + + The first form declares that \`f\` is a (pure) C function that takes + no arguments and returns a pointer to a C function with type \`t\`, + whereas the second form declares that \`f\` itself is a C function + with type \`t\`. The first declaration is usually a mistake, and one + that is hard to debug because it results in a crash, hence this + warning. + +``-fwarn-dodgy-exports`` + .. index:: + single: -fwarn-dodgy-exports + + Causes a warning to be emitted when a datatype ``T`` is exported + with all constructors, i.e. ``T(..)``, but is it just a type + synonym. + + Also causes a warning to be emitted when a module is re-exported, + but that module exports nothing. + +``-fwarn-dodgy-imports`` + .. index:: + single: -fwarn-dodgy-imports + + Causes a warning to be emitted in the following cases: + + - When a datatype ``T`` is imported with all constructors, i.e. + ``T(..)``, but has been exported abstractly, i.e. ``T``. + + - When an ``import`` statement hides an entity that is not + exported. + +``-fwarn-overflowed-literals`` + .. index:: + single: -fwarn-overflowed-literals + + Causes a warning to be emitted if a literal will overflow, e.g. + ``300 :: Word8``. + +``-fwarn-empty-enumerations`` + .. index:: + single: -fwarn-empty-enumerations + + Causes a warning to be emitted if an enumeration is empty, e.g. + ``[5 .. 3]``. + +``-fwarn-lazy-unlifted-bindings`` + .. index:: + single: -fwarn-lazy-unlifted-bindings + + This flag is a no-op, and will be removed in GHC 7.10. + +``-fwarn-duplicate-constraints`` + .. index:: + single: -fwarn-duplicate-constraints + single: duplicate constraints, warning + + Have the compiler warn about duplicate constraints in a type + signature. For example + + :: + + f :: (Eq a, Show a, Eq a) => a -> a + + The warning will indicate the duplicated ``Eq a`` constraint. + + This option is now deprecated in favour of + ``-fwarn-redundant-constraints``. + +``-fwarn-redundant-constraints`` + .. index:: + single: -fwarn-redundant-constraints + single: redundant constraints, warning + + Have the compiler warn about redundant constraints in a type + signature. In particular: + + - A redundant constraint within the type signature itself: + + :: + + f :: (Eq a, Ord a) => a -> a + + The warning will indicate the redundant ``Eq a`` constraint: it + is subsumed by the ``Ord a`` constraint. + + - A constraint in the type signature is not used in the code it + covers: + + :: + + f :: Eq a => a -> a -> Bool + f x y = True + + The warning will indicate the redundant ``Eq a`` constraint: : it + is not used by the definition of ``f``.) + + Similar warnings are given for a redundant constraint in an instance + declaration. + + This option is on by default. As usual you can suppress it on a + per-module basis with ``-fno-warn-redundant-constraints``. + Occasionally you may specifically want a function to have a more + constrained signature than necessary, perhaps to leave yourself + wiggle-room for changing the implementation without changing the + API. In that case, you can suppress the warning on a per-function + basis, using a call in a dead binding. For example: + + :: + + f :: Eq a => a -> a -> Bool + f x y = True + where + _ = x == x -- Suppress the redundant-constraint warning for (Eq a) + + Here the call to ``(==)`` makes GHC think that the ``(Eq a)`` + constraint is needed, so no warning is issued. + +``-fwarn-duplicate-exports`` + .. index:: + single: -fwarn-duplicate-exports + single: duplicate exports, warning + single: export lists, duplicates + + Have the compiler warn about duplicate entries in export lists. This + is useful information if you maintain large export lists, and want + to avoid the continued export of a definition after you've deleted + (one) mention of it in the export list. + + This option is on by default. + +``-fwarn-hi-shadowing`` + .. index:: + single: -fwarn-hi-shadowing + single: shadowing; interface files + + Causes the compiler to emit a warning when a module or interface + file in the current directory is shadowing one with the same module + name in a library or other directory. + +``-fwarn-identities`` + .. index:: + single: -fwarn-identities + + Causes the compiler to emit a warning when a Prelude numeric + conversion converts a type T to the same type T; such calls are + probably no-ops and can be omitted. The functions checked for are: + ``toInteger``, ``toRational``, ``fromIntegral``, and ``realToFrac``. + +``-fwarn-implicit-prelude`` + .. index:: + single: -fwarn-implicit-prelude + single: implicit prelude, warning + + Have the compiler warn if the Prelude is implicitly imported. This + happens unless either the Prelude module is explicitly imported with + an ``import ... Prelude ...`` line, or this implicit import is + disabled (either by ``-XNoImplicitPrelude`` or a + ``LANGUAGE NoImplicitPrelude`` pragma). + + Note that no warning is given for syntax that implicitly refers to + the Prelude, even if ``-XNoImplicitPrelude`` would change whether it + refers to the Prelude. For example, no warning is given when ``368`` + means ``Prelude.fromInteger (368::Prelude.Integer)`` (where + ``Prelude`` refers to the actual Prelude module, regardless of the + imports of the module being compiled). + + This warning is off by default. + +``-fwarn-incomplete-patterns``, ``-fwarn-incomplete-uni-patterns`` + .. index:: + single: -fwarn-incomplete-patterns + single: -fwarn-incomplete-uni-patterns + single: incomplete patterns, warning + single: patterns, incomplete + + The option ``-fwarn-incomplete-patterns`` warns about places where a + pattern-match might fail at runtime. The function ``g`` below will + fail when applied to non-empty lists, so the compiler will emit a + warning about this when ``-fwarn-incomplete-patterns`` is enabled. + + :: + + g [] = 2 + + This option isn't enabled by default because it can be a bit noisy, + and it doesn't always indicate a bug in the program. However, it's + generally considered good practice to cover all the cases in your + functions, and it is switched on by ``-W``. + + The flag ``-fwarn-incomplete-uni-patterns`` is similar, except that + it applies only to lambda-expressions and pattern bindings, + constructs that only allow a single pattern: + + :: + + h = \[] -> 2 + Just k = f y + +``-fwarn-incomplete-record-updates`` + .. index:: + single: -fwarn-incomplete-record-updates + single: incomplete record updates, warning + single: record updates, incomplete + + The function ``f`` below will fail when applied to ``Bar``, so the + compiler will emit a warning about this when + ``-fwarn-incomplete-record-updates`` is enabled. + + :: + + data Foo = Foo { x :: Int } + | Bar + + f :: Foo -> Foo + f foo = foo { x = 6 } + + This option isn't enabled by default because it can be very noisy, + and it often doesn't indicate a bug in the program. + +``-fwarn-missing-fields`` + .. index:: + single: -fwarn-missing-fields + single: missing fields, warning + single: fields, missing + + This option is on by default, and warns you whenever the + construction of a labelled field constructor isn't complete, missing + initialisers for one or more fields. While not an error (the missing + fields are initialised with bottoms), it is often an indication of a + programmer error. + +``-fwarn-missing-import-lists`` + .. index:: + single: -fwarn-import-lists + single: missing import lists, warning + single: import lists, missing + + This flag warns if you use an unqualified ``import`` declaration + that does not explicitly list the entities brought into scope. For + example + + :: + + module M where + import X( f ) + import Y + import qualified Z + p x = f x x + + The ``-fwarn-import-lists`` flag will warn about the import of ``Y`` + but not ``X`` If module ``Y`` is later changed to export (say) + ``f``, then the reference to ``f`` in ``M`` will become ambiguous. + No warning is produced for the import of ``Z`` because extending + ``Z``\'s exports would be unlikely to produce ambiguity in ``M``. + +``-fwarn-missing-methods`` + .. index:: + single: -fwarn-missing-methods + single: missing methods, warning + single: methods, missing + + This option is on by default, and warns you whenever an instance + declaration is missing one or more methods, and the corresponding + class declaration has no default declaration for them. + + The warning is suppressed if the method name begins with an + underscore. Here's an example where this is useful: + + :: + + class C a where + _simpleFn :: a -> String + complexFn :: a -> a -> String + complexFn x y = ... _simpleFn ... + + The idea is that: (a) users of the class will only call + ``complexFn``; never ``_simpleFn``; and (b) instance declarations + can define either ``complexFn`` or ``_simpleFn``. + + The ``MINIMAL`` pragma can be used to change which combination of + methods will be required for instances of a particular class. See + :ref:`minimal-pragma`. + +``-fwarn-missing-signatures`` + .. index:: + single: -fwarn-missing-signatures + single: type signatures, missing + + If you would like GHC to check that every top-level function/value + has a type signature, use the ``-fwarn-missing-signatures`` option. + As part of the warning GHC also reports the inferred type. The + option is off by default. + +``-fwarn-missing-exported-sigs`` + .. index:: + single: -fwarn-missing-exported-sigs + single: type signatures, missing + + If you would like GHC to check that every exported top-level + function/value has a type signature, but not check unexported + values, use the ``-fwarn-missing-exported-sigs`` option. This option + takes precedence over ``-fwarn-missing-signatures``. As part of the + warning GHC also reports the inferred type. The option is off by + default. + +``-fwarn-missing-local-sigs`` + .. index:: + single: -fwarn-missing-local-sigs + single: type signatures, missing + + If you use the ``-fwarn-missing-local-sigs`` flag GHC will warn you + about any polymorphic local bindings. As part of the warning GHC + also reports the inferred type. The option is off by default. + +``-fwarn-name-shadowing`` + .. index:: + single: -fwarn-name-shadowing + single: shadowing, warning + + This option causes a warning to be emitted whenever an inner-scope + value has the same name as an outer-scope value, i.e. the inner + value shadows the outer one. This can catch typographical errors + that turn into hard-to-find bugs, e.g., in the inadvertent capture + of what would be a recursive call in + ``f = ... let f = id in ... f ...``. + + The warning is suppressed for names beginning with an underscore. + For example + + :: + + f x = do { _ignore <- this; _ignore <- that; return (the other) } + +``-fwarn-orphans, -fwarn-auto-orphans`` + .. index:: + single: -fwarn-orphans + single: -fwarn-auto-orphans + single: orphan instances, warning + single: orphan rules, warning + + These flags cause a warning to be emitted whenever the module + contains an "orphan" instance declaration or rewrite rule. An + instance declaration is an orphan if it appears in a module in which + neither the class nor the type being instanced are declared in the + same module. A rule is an orphan if it is a rule for a function + declared in another module. A module containing any orphans is + called an orphan module. + + The trouble with orphans is that GHC must pro-actively read the + interface files for all orphan modules, just in case their instances + or rules play a role, whether or not the module's interface would + otherwise be of any use. See :ref:`orphan-modules` for details. + + The flag ``-fwarn-orphans`` warns about user-written orphan rules or + instances. The flag ``-fwarn-auto-orphans`` warns about + automatically-generated orphan rules, notably as a result of + specialising functions, for type classes (``Specialise``) or + argument values (``-fspec-constr``). + +``-fwarn-overlapping-patterns`` + .. index:: + single: -fwarn-overlapping-patterns + single: overlapping patterns, warning + single: patterns, overlapping + + By default, the compiler will warn you if a set of patterns are + overlapping, e.g., + + :: + + f :: String -> Int + f [] = 0 + f (_:xs) = 1 + f "2" = 2 + + where the last pattern match in ``f`` won't ever be reached, as the + second pattern overlaps it. More often than not, redundant patterns + is a programmer mistake/error, so this option is enabled by default. + +``-fwarn-tabs`` + .. index:: + single: -fwarn-tabs + single: tabs, warning + + Have the compiler warn if there are tabs in your source file. + +``-fwarn-type-defaults`` + .. index:: + single: -fwarn-type-defaults + single: defaulting mechanism, warning + + Have the compiler warn/inform you where in your source the Haskell + defaulting mechanism for numeric types kicks in. This is useful + information when converting code from a context that assumed one + default into one with another, e.g., the ‘default default’ for + Haskell 1.4 caused the otherwise unconstrained value ``1`` to be + given the type ``Int``, whereas Haskell 98 and later defaults it to + ``Integer``. This may lead to differences in performance and + behaviour, hence the usefulness of being non-silent about this. + + This warning is off by default. + +``-fwarn-monomorphism-restriction`` + .. index:: + single: -fwarn-monomorphism-restriction + single: monomorphism restriction, warning + + Have the compiler warn/inform you where in your source the Haskell + Monomorphism Restriction is applied. If applied silently the MR can + give rise to unexpected behaviour, so it can be helpful to have an + explicit warning that it is being applied. + + This warning is off by default. + +``-fwarn-unticked-promoted-constructors`` + .. index:: + single: -fwarn-unticked-promoted-constructors + single: promoted constructor, warning + + Warn if a promoted data constructor is used without a tick preceding + its name. + + For example: + + :: + + data Nat = Succ Nat | Zero + + data Vec n s where + Nil :: Vec Zero a + Cons :: a -> Vec n a -> Vec (Succ n) a + + Will raise two warnings because ``Zero`` and ``Succ`` are not + written as ``'Zero`` and ``'Succ``. + + This warning is is enabled by default in ``-Wall`` mode. + +``-fwarn-unused-binds`` + .. index:: + single: -fwarn-unused-binds + single: unused binds, warning + single: binds, unused + + Report any function definitions (and local bindings) which are + unused. An alias for + + - ``-fwarn-unused-top-binds`` + - ``-fwarn-unused-local-binds`` + - ``-fwarn-unused-pattern-binds`` + +``-fwarn-unused-top-binds`` + .. index:: + single: -fwarn-unused-top-binds + single: unused binds, warning + single: binds, unused + + Report any function definitions which are unused. + + More precisely, warn if a binding brings into scope a variable that + is not used, except if the variable's name starts with an + underscore. The "starts-with-underscore" condition provides a way to + selectively disable the warning. + + A variable is regarded as "used" if + + - It is exported, or + + - It appears in the right hand side of a binding that binds at + least one used variable that is used + + For example + + :: + + module A (f) where + f = let (p,q) = rhs1 in t p -- No warning: q is unused, but is locally bound + t = rhs3 -- No warning: f is used, and hence so is t + g = h x -- Warning: g unused + h = rhs2 -- Warning: h is only used in the + -- right-hand side of another unused binding + _w = True -- No warning: _w starts with an underscore + +``-fwarn-unused-local-binds`` + .. index:: + single: -fwarn-unused-local-binds + single: unused binds, warning + single: binds, unused + + Report any local definitions which are unused. For example + + :: + + module A (f) where + f = let (p,q) = rhs1 in t p -- Warning: q is unused + g = h x -- No warning: g is unused, but is a top-level binding + +``-fwarn-unused-pattern-binds`` + .. index:: + single: -fwarn-unused-pattern-binds + single: unused binds, warning + single: binds, unused + + Warn if a pattern binding binds no variables at all, unless it is a + lone, possibly-banged, wild-card pattern. For example: + + :: + + Just _ = rhs3 -- Warning: unused pattern binding + (_, _) = rhs4 -- Warning: unused pattern binding + _ = rhs3 -- No warning: lone wild-card pattern + !_ = rhs4 -- No warning: banged wild-card pattern; behaves like seq + + The motivation for allowing lone wild-card patterns is they are not + very different from ``_v = rhs3``, which elicits no warning; and + they can be useful to add a type constraint, e.g. ``_ = x::Int``. A + lone banged wild-card pattern is useful as an alternative (to + ``seq``) way to force evaluation. + +``-fwarn-unused-imports`` + .. index:: + single: -fwarn-unused-imports + single: unused imports, warning + single: imports, unused + + Report any modules that are explicitly imported but never used. + However, the form ``import M()`` is never reported as an unused + import, because it is a useful idiom for importing instance + declarations, which are anonymous in Haskell. + +``-fwarn-unused-matches`` + .. index:: + single: -fwarn-unused-matches + single: unused matches, warning + single: matches, unused + + Report all unused variables which arise from pattern matches, + including patterns consisting of a single variable. For instance + ``f x y = []`` would report ``x`` and ``y`` as unused. The warning + is suppressed if the variable name begins with an underscore, thus: + + :: + + f _x = True + +``-fwarn-unused-do-bind`` + .. index:: + single: -fwarn-unused-do-bind + single: unused do binding, warning + single: do binding, unused + + Report expressions occurring in ``do`` and ``mdo`` blocks that + appear to silently throw information away. For instance + ``do { mapM popInt xs ; return 10 }`` would report the first + statement in the ``do`` block as suspicious, as it has the type + ``StackM [Int]`` and not ``StackM ()``, but that ``[Int]`` value is + not bound to anything. The warning is suppressed by explicitly + mentioning in the source code that your program is throwing + something away: + + :: + + do { _ <- mapM popInt xs ; return 10 } + + Of course, in this particular situation you can do even better: + + :: + + do { mapM_ popInt xs ; return 10 } + +``-fwarn-context-quantification`` + .. index:: + single: -fwarn-context-quantification + single: implicit context quantification, warning + single: context, implicit quantification + + Report if a variable is quantified only due to its presence in a + context (see :ref:`universal-quantification`). For example, + + :: + + type T a = Monad m => a -> f a + + It is recommended to write this polymorphic type as + + :: + + type T a = forall m. Monad m => a -> f a + + instead. + +``-fwarn-wrong-do-bind`` + .. index:: + single: -fwarn-wrong-do-bind + single: apparently erroneous do binding, warning + single: do binding, apparently erroneous + + Report expressions occurring in ``do`` and ``mdo`` blocks that + appear to lack a binding. For instance + ``do { return (popInt 10) ; return 10 }`` would report the first + statement in the ``do`` block as suspicious, as it has the type + ``StackM (StackM Int)`` (which consists of two nested applications + of the same monad constructor), but which is not then "unpacked" by + binding the result. The warning is suppressed by explicitly + mentioning in the source code that your program is throwing + something away: + + :: + + do { _ <- return (popInt 10) ; return 10 } + + For almost all sensible programs this will indicate a bug, and you + probably intended to write: + + :: + + do { popInt 10 ; return 10 } + +``-fwarn-inline-rule-shadowing`` + .. index:: + single: -fwarn-inline-rule-shadowing + + Warn if a rewrite RULE might fail to fire because the function might + be inlined before the rule has a chance to fire. See + :ref:`rules-inline`. + +If you're feeling really paranoid, the ``-dcore-lint`` option is a good choice. +It turns on heavyweight intra-pass sanity-checking within GHC. (It checks GHC's +sanity, not yours.) + diff --git a/docs/users_guide/using.rst b/docs/users_guide/using.rst new file mode 100644 index 0000000000..6964ce48a1 --- /dev/null +++ b/docs/users_guide/using.rst @@ -0,0 +1,778 @@ +.. _using-ghc: + +Using GHC +========= + +.. index:: + single: GHC, using + single: using GHC + +Getting started: compiling programs +----------------------------------- + +In this chapter you'll find a complete reference to the GHC command-line +syntax, including all 400+ flags. It's a large and complex system, and +there are lots of details, so it can be quite hard to figure out how to +get started. With that in mind, this introductory section provides a +quick introduction to the basic usage of GHC for compiling a Haskell +program, before the following sections dive into the full syntax. + +Let's create a Hello World program, and compile and run it. First, +create a file ``hello.hs`` containing the Haskell code: + +:: + + main = putStrLn "Hello, World!" + +To compile the program, use GHC like this: + +:: + + $ ghc hello.hs + +(where ``$`` represents the prompt: don't type it). GHC will compile the +source file ``hello.hs``, producing an object file ``hello.o`` and an +interface file ``hello.hi``, and then it will link the object file to +the libraries that come with GHC to produce an executable called +``hello`` on Unix/Linux/Mac, or ``hello.exe`` on Windows. + +By default GHC will be very quiet about what it is doing, only printing +error messages. If you want to see in more detail what's going on behind +the scenes, add ``-v`` to the command line. + +Then we can run the program like this: + +:: + + $ ./hello + Hello World! + +If your program contains multiple modules, then you only need to tell +GHC the name of the source file containing the ``Main`` module, and GHC +will examine the ``import`` declarations to find the other modules that +make up the program and find their source files. This means that, with +the exception of the ``Main`` module, every source file should be named +after the module name that it contains (with dots replaced by directory +separators). For example, the module ``Data.Person`` would be in the +file ``Data/Person.hs`` on Unix/Linux/Mac, or ``Data\Person.hs`` on +Windows. + +Options overview +---------------- + +GHC's behaviour is controlled by options, which for historical reasons +are also sometimes referred to as command-line flags or arguments. +Options can be specified in three ways: + +Command-line arguments +~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: structure, command-line + single: command-line; arguments + single: arguments; command-line + +An invocation of GHC takes the following form: + +:: + + ghc [argument...] + +Command-line arguments are either options or file names. + +Command-line options begin with ``-``. They may *not* be grouped: +``-vO`` is different from ``-v -O``. Options need not precede filenames: +e.g., ``ghc *.o -o foo``. All options are processed and then applied to +all files; you cannot, for example, invoke +``ghc -c -O1 Foo.hs -O2 Bar.hs`` to apply different optimisation levels +to the files ``Foo.hs`` and ``Bar.hs``. + +.. _source-file-options: + +Command line options in source files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: source-file options + +Sometimes it is useful to make the connection between a source file and +the command-line options it requires quite tight. For instance, if a +Haskell source file deliberately uses name shadowing, it should be +compiled with the ``-fno-warn-name-shadowing`` option. Rather than +maintaining the list of per-file options in a ``Makefile``, it is +possible to do this directly in the source file using the +``OPTIONS_GHC`` :ref:`pragma <options-pragma>`. + +:: + + {-# OPTIONS_GHC -fno-warn-name-shadowing #-} + module X where + ... + +``OPTIONS_GHC`` is a *file-header pragma* (see :ref:`options-pragma`). + +Only *dynamic* flags can be used in an ``OPTIONS_GHC`` pragma (see +:ref:`static-dynamic-flags`). + +Note that your command shell does not get to the source file options, +they are just included literally in the array of command-line arguments +the compiler maintains internally, so you'll be desperately disappointed +if you try to glob etc. inside ``OPTIONS_GHC``. + +.. note:: + The contents of ``OPTIONS_GHC`` are appended to the command-line + options, so options given in the source file override those given on the + command-line. + +It is not recommended to move all the contents of your Makefiles into +your source files, but in some circumstances, the ``OPTIONS_GHC`` pragma +is the Right Thing. (If you use ``-keep-hc-file`` and have ``OPTION`` flags in +your module, the ``OPTIONS_GHC`` will get put into the generated ``.hc`` file). + +Setting options in GHCi +~~~~~~~~~~~~~~~~~~~~~~~ + +Options may also be modified from within GHCi, using the ``:set`` +command. See :ref:`ghci-set` for more details. + +.. _static-dynamic-flags: + +Static, Dynamic, and Mode options +--------------------------------- + +.. index:: + single: static; options + single: dynamic; options + single: mode; options + +Each of GHC's command line options is classified as static, dynamic or +mode: + + For example, ``--make`` or ``-E``. There may only be a single mode + flag on the command line. The available modes are listed in + :ref:`modes`. + + Most non-mode flags fall into this category. A dynamic flag may be + used on the command line, in a ``OPTIONS_GHC`` pragma in a source + file, or set using ``:set`` in GHCi. + + A few flags are "static", which means they can only be used on the + command-line, and remain in force over the entire GHC/GHCi run. + +The flag reference tables (:ref:`flag-reference`) lists the status of +each flag. + +There are a few flags that are static except that they can also be used +with GHCi's ``:set`` command; these are listed as “static/\ ``:set``\ ” +in the table. + +.. _file-suffixes: + +Meaningful file suffixes +------------------------ + +.. index:: + single: suffixes, file + single: file suffixes for GHC + +File names with "meaningful" suffixes (e.g., ``.lhs`` or ``.o``) cause +the "right thing" to happen to those files. + +``.hs`` + A Haskell module. + +``.lhs`` + .. index:: + single: lhs file extension + + A “literate Haskell” module. + +``.hspp`` + A file created by the preprocessor. + +``.hi`` + A Haskell interface file, probably compiler-generated. + +``.hc`` + Intermediate C file produced by the Haskell compiler. + +``.c`` + A C file not produced by the Haskell compiler. + +``.ll`` + An llvm-intermediate-language source file, usually produced by the + compiler. + +``.bc`` + An llvm-intermediate-language bitcode file, usually produced by the + compiler. + +``.s`` + An assembly-language source file, usually produced by the compiler. + +``.o`` + An object file, produced by an assembler. + +Files with other suffixes (or without suffixes) are passed straight to +the linker. + +.. _modes: + +Modes of operation +------------------ + +.. index:: + single: help options + +GHC's behaviour is firstly controlled by a mode flag. Only one of these +flags may be given, but it does not necessarily need to be the first +option on the command-line. + +If no mode flag is present, then GHC will enter make mode +(:ref:`make-mode`) if there are any Haskell source files given on the +command line, or else it will link the objects named on the command line +to produce an executable. + +The available mode flags are: + +``ghc --interactive`` + .. index:: + single: interactive mode + single: GHCi + + Interactive mode, which is also available as ``ghci``. Interactive + mode is described in more detail in :ref:`ghci`. + +``ghc --make`` + .. index:: + single: make mode; of GHC + single: --make + + In this mode, GHC will build a multi-module Haskell program + automatically, figuring out dependencies for itself. If you have a + straightforward Haskell program, this is likely to be much easier, + and faster, than using ``make``. Make mode is described in + :ref:`make-mode`. + + This mode is the default if there are any Haskell source files + mentioned on the command line, and in this case the ``--make`` + option can be omitted. + +``ghc -e`` ⟨expr⟩ + .. index:: + single: eval mode; of GHC + + Expression-evaluation mode. This is very similar to interactive + mode, except that there is a single expression to evaluate (⟨expr⟩) + which is given on the command line. See :ref:`eval-mode` for more + details. + +``ghc -E`` ``ghc -C`` ``ghc -S`` ``ghc -c`` + .. index:: + single: -E; GHC option + single: -C; GHC option + single: -S; GHC option + single: -c; GHC option + + This is the traditional batch-compiler mode, in which GHC can + compile source files one at a time, or link objects together into an + executable. See :ref:`options-order`. + +``ghc -M`` + .. index:: + single: dependency-generation mode; of GHC + + Dependency-generation mode. In this mode, GHC can be used to + generate dependency information suitable for use in a ``Makefile``. + See :ref:`makefile-dependencies`. + +``ghc --mk-dll`` + .. index:: + single: DLL-creation mode + + DLL-creation mode (Windows only). See :ref:`win32-dlls-create`. + +``ghc --help``, ``ghc -?`` + .. index:: + single: --help; GHC option + + Cause GHC to spew a long usage message to standard output and then + exit. + +``ghc --show-iface ⟨file⟩`` + .. index:: + single: --show-iface; GHC option + + Read the interface in ⟨file⟩ and dump it as text to ``stdout``. For + example ``ghc --show-iface M.hi``. + +``ghc --supported-extensions``, ``ghc --supported-languages`` + .. index:: + single: --supported-extensions; GHC option + single: --supported-languages; GHC option + + Print the supported language extensions. + +``ghc --show-options`` + .. index:: + single: --show-options; GHC option + + Print the supported command line options. This flag can be used for + autocompletion in a shell. + +``ghc --info`` + .. index:: + single: --info + + Print information about the compiler. + +``ghc --version``, ``ghc -V`` + .. index:: + single: -V + single: --version + + Print a one-line string including GHC's version number. + +``ghc --numeric-version`` + .. index:: + single: --numeric-version + + Print GHC's numeric version number only. + +``ghc --print-libdir`` + .. index:: + single: --print-libdir + single: libdir + + Print the path to GHC's library directory. This is the top of the + directory tree containing GHC's libraries, interfaces, and include + files (usually something like ``/usr/local/lib/ghc-5.04`` on Unix). + This is the value of ``$libdir`` in the package + configuration file (see :ref:`packages`). + +.. _make-mode: + +Using ``ghc`` ``--make`` +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: --make; mode of GHC + single: separate compilation + +In this mode, GHC will build a multi-module Haskell program by following +dependencies from one or more root modules (usually just ``Main``). For +example, if your ``Main`` module is in a file called ``Main.hs``, you +could compile and link the program like this: + +:: + + ghc --make Main.hs + +In fact, GHC enters make mode automatically if there are any Haskell +source files on the command line and no other mode is specified, so in +this case we could just type + +:: + + ghc Main.hs + +Any number of source file names or module names may be specified; GHC +will figure out all the modules in the program by following the imports +from these initial modules. It will then attempt to compile each module +which is out of date, and finally, if there is a ``Main`` module, the +program will also be linked into an executable. + +The main advantages to using ``ghc --make`` over traditional +``Makefile``\s are: + +- GHC doesn't have to be restarted for each compilation, which means it + can cache information between compilations. Compiling a multi-module + program with ``ghc --make`` can be up to twice as fast as running + ``ghc`` individually on each source file. + +- You don't have to write a ``Makefile``. + + .. index:: + single: Makefiles; avoiding + +- GHC re-calculates the dependencies each time it is invoked, so the + dependencies never get out of sync with the source. + +- Using the ``-j`` flag, you can compile modules in parallel. Specify + ``-j⟨N⟩`` to compile ⟨N⟩ jobs in parallel. + +Any of the command-line options described in the rest of this chapter +can be used with ``--make``, but note that any options you give on the +command line will apply to all the source files compiled, so if you want +any options to apply to a single source file only, you'll need to use an +``OPTIONS_GHC`` pragma (see :ref:`source-file-options`). + +If the program needs to be linked with additional objects (say, some +auxiliary C code), then the object files can be given on the command +line and GHC will include them when linking the executable. + +For backward compatibility with existing make scripts, when used in +combination with ``-c``, the linking phase is omitted (same as +``--make -no-link``). + +Note that GHC can only follow dependencies if it has the source file +available, so if your program includes a module for which there is no +source file, even if you have an object and an interface file for the +module, then GHC will complain. The exception to this rule is for +package modules, which may or may not have source files. + +The source files for the program don't all need to be in the same +directory; the ``-i`` option can be used to add directories to the +search path (see :ref:`search-path`). + +.. _eval-mode: + +Expression evaluation mode +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This mode is very similar to interactive mode, except that there is a +single expression to evaluate which is specified on the command line as +an argument to the ``-e`` option: + +:: + + ghc -e expr + +Haskell source files may be named on the command line, and they will be +loaded exactly as in interactive mode. The expression is evaluated in +the context of the loaded modules. + +For example, to load and run a Haskell program containing a module +``Main``, we might say + +:: + + ghc -e Main.main Main.hs + +or we can just use this mode to evaluate expressions in the context of +the ``Prelude``: + +:: + + $ ghc -e "interact (unlines.map reverse.lines)" + hello + olleh + +.. _options-order: + +Batch compiler mode +~~~~~~~~~~~~~~~~~~~ + +In *batch mode*, GHC will compile one or more source files given on the +command line. + +The first phase to run is determined by each input-file suffix, and the +last phase is determined by a flag. If no relevant flag is present, then +go all the way through to linking. This table summarises: + ++-----------------------------------+------------------------------+----------------------------+---------------------------+ +| Phase of the compilation system | Suffix saying “start here” | Flag saying “stop after” | (suffix of) output file | ++===================================+==============================+============================+===========================+ +| literate pre-processor | ``.lhs`` | | ``.hs`` | ++-----------------------------------+------------------------------+----------------------------+---------------------------+ +| C pre-processor (opt.) | ``.hs`` (with ``-cpp``) | ``-E`` | ``.hspp`` | ++-----------------------------------+------------------------------+----------------------------+---------------------------+ +| Haskell compiler | ``.hs`` | ``-C``, ``-S`` | ``.hc``, ``.s`` | ++-----------------------------------+------------------------------+----------------------------+---------------------------+ +| C compiler (opt.) | ``.hc`` or ``.c`` | ``-S`` | ``.s`` | ++-----------------------------------+------------------------------+----------------------------+---------------------------+ +| assembler | ``.s`` | ``-c`` | ``.o`` | ++-----------------------------------+------------------------------+----------------------------+---------------------------+ +| linker | ⟨other⟩ | | ``a.out`` | ++-----------------------------------+------------------------------+----------------------------+---------------------------+ + +.. index:: + single: -C + single: -E + single: -S + single: -c + +Thus, a common invocation would be: + +:: + + ghc -c Foo.hs + +to compile the Haskell source file ``Foo.hs`` to an object file +``Foo.o``. + +.. note:: + What the Haskell compiler proper produces depends on what backend + code generator is used. See :ref:`code-generators` for more details. + +.. note:: + Pre-processing is optional, the ``-cpp``\ ``-cpp`` flag turns it + on. See :ref:`c-pre-processor` for more details. + +.. note:: + The option ``-E`` runs just the pre-processing passes of + the compiler, dumping the result in a file. + +.. note:: + The option ``-C`` is only available when GHC is built in + unregisterised mode. See :ref:`unreg` for more details. + +.. _overriding-suffixes: + +Overriding the default behaviour for a file +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As described above, the way in which a file is processed by GHC depends +on its suffix. This behaviour can be overridden using the ``-x`` option: + +``-x``\ ⟨suffix⟩ + .. index:: + single: -x + + Causes all files following this option on the command line to be + processed as if they had the suffix ⟨suffix⟩. For example, to + compile a Haskell module in the file ``M.my-hs``, use + ``ghc -c -x hs M.my-hs``. + +.. _options-help: + +Verbosity options +----------------- + +.. index:: + single: verbosity options + +See also the ``--help``, ``--version``, ``--numeric-version``, and +``--print-libdir`` modes in :ref:`modes`. + +``-v`` + .. index:: + single: -v + + The ``-v`` option makes GHC *verbose*: it reports its version number + and shows (on stderr) exactly how it invokes each phase of the + compilation system. Moreover, it passes the ``-v`` flag to most + phases; each reports its version number (and possibly some other + information). + + Please, oh please, use the ``-v`` option when reporting bugs! + Knowing that you ran the right bits in the right order is always the + first thing we want to verify. + +``-v⟨n⟩`` + .. index:: + single: -v + + To provide more control over the compiler's verbosity, the ``-v`` + flag takes an optional numeric argument. Specifying ``-v`` on its + own is equivalent to ``-v3``, and the other levels have the + following meanings: + + ``-v0`` + Disable all non-essential messages (this is the default). + + ``-v1`` + Minimal verbosity: print one line per compilation (this is the + default when ``--make`` or ``--interactive`` is on). + + ``-v2`` + Print the name of each compilation phase as it is executed. + (equivalent to ``-dshow-passes``). + + ``-v3`` + The same as ``-v2``, except that in addition the full command + line (if appropriate) for each compilation phase is also + printed. + + ``-v4`` + The same as ``-v3`` except that the intermediate program + representation after each compilation phase is also printed + (excluding preprocessed and C/assembly files). + +``--fprint-potential-instances`` + .. index:: + single: -fprint-potential-instances + + When GHC can't find an instance for a class, it displays a short + list of some in the instances it knows about. With this flag it + prints *all* the instances it knows about. + +``-fprint-explicit-foralls, -fprint-explicit-kinds, -fprint-unicode-syntax`` + .. index:: + single: -fprint-explicit-foralls + single: -fprint-explicit-kinds + single: -fprint-unicode-syntax + + These three flags control the way in which GHC displays types, in + error messages and in GHCi. Using ``-fprint-explicit-foralls`` makes + GHC print explicit ``forall`` quantification at the top level of a + type; normally this is suppressed. For example, in GHCi: + + :: + + ghci> let f x = x + ghci> :t f + f :: a -> a + ghci> :set -fprint-explicit-foralls + ghci> :t f + f :: forall a. a -> a + + However, regardless of the flag setting, the quantifiers are printed + under these circumstances: + + - For nested ``foralls``, e.g. + + :: + + ghci> :t GHC.ST.runST + GHC.ST.runST :: (forall s. GHC.ST.ST s a) -> a + + - If any of the quantified type variables has a kind that mentions + a kind variable, e.g. + + :: + + ghci> :i Data.Type.Equality.sym + Data.Type.Equality.sym :: + forall (k :: BOX) (a :: k) (b :: k). + (a Data.Type.Equality.:~: b) -> b Data.Type.Equality.:~: a + -- Defined in Data.Type.Equality + + Using ``-fprint-explicit-kinds`` makes GHC print kind arguments in + types, which are normally suppressed. This can be important when you + are using kind polymorphism. For example: + + :: + + ghci> :set -XPolyKinds + ghci> data T a = MkT + ghci> :t MkT + MkT :: forall (k :: BOX) (a :: k). T a + ghci> :set -fprint-explicit-foralls + ghci> :t MkT + MkT :: forall (k :: BOX) (a :: k). T k a + + When ``-fprint-unicode-syntax`` is enabled, GHC prints type + signatures using the unicode symbols from the ``-XUnicodeSyntax`` + extension. + + :: + + ghci> :set -fprint-unicode-syntax + ghci> :t (>>) + (>>) :: ∀ (m :: * → *) a b. Monad m ⇒ m a → m b → m b + +``-fprint-expanded-synonyms`` + .. index:: + single: -fprint-expanded-synonyms + + When enabled, GHC also prints type-synonym-expanded types in type + errors. For example, with this type synonyms: + + :: + + type Foo = Int + type Bar = Bool + type MyBarST s = ST s Bar + + This error message: + + :: + + Couldn't match type 'Int' with 'Bool' + Expected type: ST s Foo + Actual type: MyBarST s + + Becomes this: + + :: + + Couldn't match type 'Int' with 'Bool' + Expected type: ST s Foo + Actual type: MyBarST s + Type synonyms expanded: + Expected type: ST s Int + Actual type: ST s Bool + +``-ferror-spans`` + .. index:: + single: -ferror-spans + + Causes GHC to emit the full source span of the syntactic entity + relating to an error message. Normally, GHC emits the source + location of the start of the syntactic entity only. + + For example: + + :: + + test.hs:3:6: parse error on input `where' + + becomes: + + :: + + test296.hs:3:6-10: parse error on input `where' + + And multi-line spans are possible too: + + :: + + test.hs:(5,4)-(6,7): + Conflicting definitions for `a' + Bound at: test.hs:5:4 + test.hs:6:7 + In the binding group for: a, b, a + + Note that line numbers start counting at one, but column numbers + start at zero. This choice was made to follow existing convention + (i.e. this is how Emacs does it). + +``-H⟨size⟩`` + .. index:: + single: -H + + Set the minimum size of the heap to ⟨size⟩. This option is + equivalent to ``+RTS -Hsize``, see :ref:`rts-options-gc`. + +``-Rghc-timing`` + .. index:: + single: -Rghc-timing + + Prints a one-line summary of timing statistics for the GHC run. This + option is equivalent to ``+RTS -tstderr``, see + :ref:`rts-options-gc`. + +.. _options-platform: + +Platform-specific Flags +----------------------- + +.. index:: + single: -m\* options + single: platform-specific options + single: machine-specific options + +Some flags only make sense for particular target platforms. + +``-msse2`` + (x86 only, added in GHC 7.0.1) Use the SSE2 registers and + instruction set to implement floating point operations when using + the :ref:`native code generator <native-code-gen>`. This gives a + substantial performance improvement for floating point, but the + resulting compiled code will only run on processors that support + SSE2 (Intel Pentium 4 and later, or AMD Athlon 64 and later). The + :ref:`LLVM backend <llvm-code-gen>` will also use SSE2 if your + processor supports it but detects this automatically so no flag is + required. + + SSE2 is unconditionally used on x86-64 platforms. + +``-msse4.2`` + (x86 only, added in GHC 7.4.1) Use the SSE4.2 instruction set to + implement some floating point and bit operations when using the + :ref:`native code generator <native-code-gen>`. The resulting compiled + code will only run on processors that support SSE4.2 (Intel Core i7 + and later). The :ref:`LLVM backend <llvm-code-gen>` will also use + SSE4.2 if your processor supports it but detects this automatically + so no flag is required. diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml deleted file mode 100644 index 797e78485f..0000000000 --- a/docs/users_guide/using.xml +++ /dev/null @@ -1,3648 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<chapter id="using-ghc"> - <title>Using GHC</title> - - <indexterm><primary>GHC, using</primary></indexterm> - <indexterm><primary>using GHC</primary></indexterm> - - <sect1> - <title>Getting started: compiling programs</title> - - <para> - In this chapter you'll find a complete reference to the GHC - command-line syntax, including all 400+ flags. It's a large and - complex system, and there are lots of details, so it can be - quite hard to figure out how to get started. With that in mind, - this introductory section provides a quick introduction to the - basic usage of GHC for compiling a Haskell program, before the - following sections dive into the full syntax. - </para> - - <para> - Let's create a Hello World program, and compile and run it. - First, create a file <filename>hello.hs</filename> containing - the Haskell code: - </para> - -<programlisting> -main = putStrLn "Hello, World!" -</programlisting> - - <para>To compile the program, use GHC like this:</para> - -<screen> -$ ghc hello.hs -</screen> - - <para>(where <literal>$</literal> represents the prompt: don't - type it). GHC will compile the source - file <filename>hello.hs</filename>, producing - an <firstterm>object - file</firstterm> <filename>hello.o</filename> and - an <firstterm>interface - file</firstterm> <filename>hello.hi</filename>, and then it - will link the object file to the libraries that come with GHC - to produce an executable called <filename>hello</filename> on - Unix/Linux/Mac, or <filename>hello.exe</filename> on - Windows.</para> - - <para> - By default GHC will be very quiet about what it is doing, only - printing error messages. If you want to see in more detail - what's going on behind the scenes, add <option>-v</option> to - the command line. - </para> - - <para> - Then we can run the program like this: - </para> - -<screen> -$ ./hello -Hello World! -</screen> - - <para> - If your program contains multiple modules, then you only need to - tell GHC the name of the source file containing - the <filename>Main</filename> module, and GHC will examine - the <literal>import</literal> declarations to find the other - modules that make up the program and find their source files. - This means that, with the exception of - the <literal>Main</literal> module, every source file should be - named after the module name that it contains (with dots replaced - by directory separators). For example, the - module <literal>Data.Person</literal> would be in the - file <filename>Data/Person.hs</filename> on Unix/Linux/Mac, - or <filename>Data\Person.hs</filename> on Windows. - </para> - </sect1> - - <sect1> - <title>Options overview</title> - - <para>GHC's behaviour is controlled by - <firstterm>options</firstterm>, which for historical reasons are - also sometimes referred to as command-line flags or arguments. - Options can be specified in three ways:</para> - - <sect2> - <title>Command-line arguments</title> - - <indexterm><primary>structure, command-line</primary></indexterm> - <indexterm><primary>command-line</primary><secondary>arguments</secondary></indexterm> - <indexterm><primary>arguments</primary><secondary>command-line</secondary></indexterm> - - <para>An invocation of GHC takes the following form:</para> - -<screen> -ghc [argument...] -</screen> - - <para>Command-line arguments are either options or file names.</para> - - <para>Command-line options begin with <literal>-</literal>. - They may <emphasis>not</emphasis> be grouped: - <option>-vO</option> is different from <option>-v -O</option>. - Options need not precede filenames: e.g., <literal>ghc *.o -o - foo</literal>. All options are processed and then applied to - all files; you cannot, for example, invoke <literal>ghc -c -O1 - Foo.hs -O2 Bar.hs</literal> to apply different optimisation - levels to the files <filename>Foo.hs</filename> and - <filename>Bar.hs</filename>.</para> - </sect2> - - <sect2 id="source-file-options"> - <title>Command line options in source files</title> - - <indexterm><primary>source-file options</primary></indexterm> - - <para>Sometimes it is useful to make the connection between a - source file and the command-line options it requires quite - tight. For instance, if a Haskell source file deliberately - uses name shadowing, it should be compiled with the - <option>-fno-warn-name-shadowing</option> option. Rather than maintaining - the list of per-file options in a <filename>Makefile</filename>, - it is possible to do this directly in the source file using the - <literal>OPTIONS_GHC</literal> pragma <indexterm><primary>OPTIONS_GHC - pragma</primary></indexterm>:</para> - -<programlisting> -{-# OPTIONS_GHC -fno-warn-name-shadowing #-} -module X where -... -</programlisting> - - <para><literal>OPTIONS_GHC</literal> is a <emphasis>file-header pragma</emphasis> - (see <xref linkend="pragmas"/>).</para> - - <para>Only <emphasis>dynamic</emphasis> flags can be used in an <literal>OPTIONS_GHC</literal> pragma - (see <xref linkend="static-dynamic-flags"/>).</para> - - <para>Note that your command shell does not - get to the source file options, they are just included literally - in the array of command-line arguments the compiler - maintains internally, so you'll be desperately disappointed if - you try to glob etc. inside <literal>OPTIONS_GHC</literal>.</para> - - <para>NOTE: the contents of OPTIONS_GHC are appended to the - command-line options, so options given in the source file - override those given on the command-line.</para> - - <para>It is not recommended to move all the contents of your - Makefiles into your source files, but in some circumstances, the - <literal>OPTIONS_GHC</literal> pragma is the Right Thing. (If you - use <option>-keep-hc-file</option> and have OPTION flags in - your module, the OPTIONS_GHC will get put into the generated .hc - file).</para> - </sect2> - - <sect2> - <title>Setting options in GHCi</title> - - <para>Options may also be modified from within GHCi, using the - <literal>:set</literal> command. See <xref linkend="ghci-set"/> - for more details.</para> - </sect2> - </sect1> - - <sect1 id="static-dynamic-flags"> - <title>Static, Dynamic, and Mode options</title> - <indexterm><primary>static</primary><secondary>options</secondary> - </indexterm> - <indexterm><primary>dynamic</primary><secondary>options</secondary> - </indexterm> - <indexterm><primary>mode</primary><secondary>options</secondary> - </indexterm> - - <para>Each of GHC's command line options is classified as - <firstterm>static</firstterm>, <firstterm>dynamic</firstterm> or - <firstterm>mode</firstterm>:</para> - - <variablelist> - <varlistentry> - <term>Mode flags</term> - <listitem> - <para>For example, <option>--make</option> or <option>-E</option>. - There may only be a single mode flag on the command line. The - available modes are listed in <xref linkend="modes"/>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>Dynamic Flags</term> - <listitem> - <para>Most non-mode flags fall into this category. A dynamic flag - may be used on the command line, in a - <literal>OPTIONS_GHC</literal> pragma in a source file, or set - using <literal>:set</literal> in GHCi.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>Static Flags</term> - <listitem> - <para>A few flags are "static", which means they can only be used on - the command-line, and remain in force over the entire GHC/GHCi - run.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The flag reference tables (<xref - linkend="flag-reference"/>) lists the status of each flag.</para> - - <para>There are a few flags that are static except that they can - also be used with GHCi's <literal>:set</literal> command; these - are listed as “static/<literal>:set</literal>” in the - table.</para> - </sect1> - - <sect1 id="file-suffixes"> - <title>Meaningful file suffixes</title> - - <indexterm><primary>suffixes, file</primary></indexterm> - <indexterm><primary>file suffixes for GHC</primary></indexterm> - - <para>File names with “meaningful” suffixes (e.g., - <filename>.lhs</filename> or <filename>.o</filename>) cause the - “right thing” to happen to those files.</para> - - <variablelist> - - <varlistentry> - <term><filename>.hs</filename></term> - <listitem> - <para>A Haskell module.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <filename>.lhs</filename> - <indexterm><primary><literal>lhs</literal> suffix</primary></indexterm> - </term> - <listitem> - <para>A “literate Haskell” module.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.hspp</filename></term> - <listitem> - <para>A file created by the preprocessor.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.hi</filename></term> - <listitem> - <para>A Haskell interface file, probably - compiler-generated.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.hc</filename></term> - <listitem> - <para>Intermediate C file produced by the Haskell - compiler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.c</filename></term> - <listitem> - <para>A C file not produced by the Haskell - compiler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.ll</filename></term> - <listitem> - <para>An llvm-intermediate-language source file, usually - produced by the compiler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.bc</filename></term> - <listitem> - <para>An llvm-intermediate-language bitcode file, usually - produced by the compiler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.s</filename></term> - <listitem> - <para>An assembly-language source file, usually produced by - the compiler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.o</filename></term> - <listitem> - <para>An object file, produced by an assembler.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Files with other suffixes (or without suffixes) are passed - straight to the linker.</para> - - </sect1> - - <sect1 id="modes"> - <title>Modes of operation</title> - <indexterm><primary>help options</primary></indexterm> - - <para> - GHC's behaviour is firstly controlled by a mode flag. Only one - of these flags may be given, but it does not necessarily need to - be the first option on the command-line. - </para> - - <para> - If no mode flag is present, then GHC will enter make mode - (<xref linkend="make-mode" />) if there are any Haskell source - files given on the command line, or else it will link the - objects named on the command line to produce an executable. - </para> - - <para>The available mode flags are:</para> - - <variablelist> - <varlistentry> - <term> - <cmdsynopsis><command>ghc --interactive</command> - </cmdsynopsis> - <indexterm><primary>interactive mode</primary></indexterm> - <indexterm><primary>ghci</primary></indexterm> - </term> - <listitem> - <para>Interactive mode, which is also available as - <command>ghci</command>. Interactive mode is described in - more detail in <xref linkend="ghci"/>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis><command>ghc --make</command> - </cmdsynopsis> - <indexterm><primary>make mode</primary></indexterm> - <indexterm><primary><option>--make</option></primary></indexterm> - </term> - <listitem> - <para>In this mode, GHC will build a multi-module Haskell - program automatically, figuring out dependencies for itself. - If you have a straightforward Haskell program, this is - likely to be much easier, and faster, than using - <command>make</command>. Make mode is described in <xref - linkend="make-mode"/>.</para> - - <para> - This mode is the default if there are any Haskell - source files mentioned on the command line, and in this case - the <option>--make</option> option can be omitted. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis><command>ghc -e</command> - <arg choice='plain'><replaceable>expr</replaceable></arg> - </cmdsynopsis> - <indexterm><primary>eval mode</primary></indexterm> - </term> - <listitem> - <para>Expression-evaluation mode. This is very similar to - interactive mode, except that there is a single expression - to evaluate (<replaceable>expr</replaceable>) which is given - on the command line. See <xref linkend="eval-mode"/> for - more details.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis> - <command>ghc -E</command> - <command>ghc -C</command> - <command>ghc -S</command> - <command>ghc -c</command> - </cmdsynopsis> - <indexterm><primary><option>-E</option></primary></indexterm> - <indexterm><primary><option>-C</option></primary></indexterm> - <indexterm><primary><option>-S</option></primary></indexterm> - <indexterm><primary><option>-c</option></primary></indexterm> - </term> - <listitem> - <para>This is the traditional batch-compiler mode, in which - GHC can compile source files one at a time, or link objects - together into an executable. See <xref - linkend="options-order"/>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis> - <command>ghc -M</command> - </cmdsynopsis> - <indexterm><primary>dependency-generation mode</primary></indexterm> - </term> - <listitem> - <para>Dependency-generation mode. In this mode, GHC can be - used to generate dependency information suitable for use in - a <literal>Makefile</literal>. See <xref - linkend="makefile-dependencies"/>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis> - <command>ghc --mk-dll</command> - </cmdsynopsis> - <indexterm><primary>DLL-creation mode</primary></indexterm> - </term> - <listitem> - <para>DLL-creation mode (Windows only). See <xref - linkend="win32-dlls-create"/>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis> - <command>ghc --help</command> <command>ghc -?</command> - </cmdsynopsis> - <indexterm><primary><option>--help</option></primary></indexterm> - </term> - <listitem> - <para>Cause GHC to spew a long usage message to standard - output and then exit.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis> - <command>ghc --show-iface <replaceable>file</replaceable></command> - </cmdsynopsis> - <indexterm><primary><option>--show-iface</option></primary></indexterm> - </term> - <listitem> - <para>Read the interface in - <replaceable>file</replaceable> and dump it as text to - <literal>stdout</literal>. For example <literal>ghc --show-iface M.hi</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis> - <command>ghc --supported-extensions</command> - <command>ghc --supported-languages</command> - </cmdsynopsis> - <indexterm><primary><option>--supported-extensions</option></primary><primary><option>--supported-languages</option></primary></indexterm> - </term> - <listitem> - <para>Print the supported language extensions.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis> - <command>ghc --show-options</command> - </cmdsynopsis> - <indexterm><primary><option>--show-options</option></primary></indexterm> - </term> - <listitem> - <para>Print the supported command line options. This flag can be used for autocompletion in a shell.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis> - <command>ghc --info</command> - </cmdsynopsis> - <indexterm><primary><option>--info</option></primary></indexterm> - </term> - <listitem> - <para>Print information about the compiler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis> - <command>ghc --version</command> - <command>ghc -V</command> - </cmdsynopsis> - <indexterm><primary><option>-V</option></primary></indexterm> - <indexterm><primary><option>--version</option></primary></indexterm> - </term> - <listitem> - <para>Print a one-line string including GHC's version number.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis> - <command>ghc --numeric-version</command> - </cmdsynopsis> - <indexterm><primary><option>--numeric-version</option></primary></indexterm> - </term> - <listitem> - <para>Print GHC's numeric version number only.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis> - <command>ghc --print-libdir</command> - </cmdsynopsis> - <indexterm><primary><option>--print-libdir</option></primary></indexterm> - </term> - <listitem> - <para>Print the path to GHC's library directory. This is - the top of the directory tree containing GHC's libraries, - interfaces, and include files (usually something like - <literal>/usr/local/lib/ghc-5.04</literal> on Unix). This - is the value of - <literal>$libdir</literal><indexterm><primary><literal>libdir</literal></primary></indexterm> - in the package configuration file - (see <xref linkend="packages"/>).</para> - </listitem> - </varlistentry> - - </variablelist> - - <sect2 id="make-mode"> - <title>Using <command>ghc</command> <option>--make</option></title> - <indexterm><primary><option>--make</option></primary></indexterm> - <indexterm><primary>separate compilation</primary></indexterm> - - <para>In this mode, GHC will build a multi-module Haskell program by following - dependencies from one or more root modules (usually just - <literal>Main</literal>). For example, if your - <literal>Main</literal> module is in a file called - <filename>Main.hs</filename>, you could compile and link the - program like this:</para> - -<screen> -ghc --make Main.hs -</screen> - - <para> - In fact, GHC enters make mode automatically if there are any - Haskell source files on the command line and no other mode is - specified, so in this case we could just type - </para> - -<screen> -ghc Main.hs -</screen> - - <para>Any number of source file names or module names may be - specified; GHC will figure out all the modules in the program by - following the imports from these initial modules. It will then - attempt to compile each module which is out of date, and - finally, if there is a <literal>Main</literal> module, the - program will also be linked into an executable.</para> - - <para>The main advantages to using <literal>ghc - --make</literal> over traditional - <literal>Makefile</literal>s are:</para> - - <itemizedlist> - <listitem> - <para>GHC doesn't have to be restarted for each compilation, - which means it can cache information between compilations. - Compiling a multi-module program with <literal>ghc - --make</literal> can be up to twice as fast as - running <literal>ghc</literal> individually on each source - file.</para> - </listitem> - <listitem> - <para>You don't have to write a <literal>Makefile</literal>.</para> - <indexterm><primary><literal>Makefile</literal>s</primary><secondary>avoiding</secondary></indexterm> - </listitem> - <listitem> - <para>GHC re-calculates the dependencies each time it is - invoked, so the dependencies never get out of sync with the - source.</para> - </listitem> - <listitem> - <para>Using the <literal>-j</literal> flag, you can compile - modules in parallel. Specify <literal>-jN</literal> to - compile <replaceable>N</replaceable> jobs in parallel.</para> - </listitem> - </itemizedlist> - - <para>Any of the command-line options described in the rest of - this chapter can be used with - <option>--make</option>, but note that any options - you give on the command line will apply to all the source files - compiled, so if you want any options to apply to a single source - file only, you'll need to use an <literal>OPTIONS_GHC</literal> - pragma (see <xref linkend="source-file-options"/>).</para> - - <para>If the program needs to be linked with additional objects - (say, some auxiliary C code), then the object files can be - given on the command line and GHC will include them when linking - the executable.</para> - - <para>For backward compatibility with existing make scripts, when - used in combination with <option>-c</option>, the linking phase - is omitted (same as <option>--make</option> - <option>-no-link</option>).</para> - - <para>Note that GHC can only follow dependencies if it has the - source file available, so if your program includes a module for - which there is no source file, even if you have an object and an - interface file for the module, then GHC will complain. The - exception to this rule is for package modules, which may or may - not have source files.</para> - - <para>The source files for the program don't all need to be in - the same directory; the <option>-i</option> option can be used - to add directories to the search path (see <xref - linkend="search-path"/>).</para> - </sect2> - - <sect2 id="eval-mode"> - <title>Expression evaluation mode</title> - - <para>This mode is very similar to interactive mode, except that - there is a single expression to evaluate which is specified on - the command line as an argument to the <option>-e</option> - option:</para> - -<screen> -ghc -e <replaceable>expr</replaceable> -</screen> - - <para>Haskell source files may be named on the command line, and - they will be loaded exactly as in interactive mode. The - expression is evaluated in the context of the loaded - modules.</para> - - <para>For example, to load and run a Haskell program containing - a module <literal>Main</literal>, we might say</para> - -<screen> -ghc -e Main.main Main.hs -</screen> - - <para>or we can just use this mode to evaluate expressions in - the context of the <literal>Prelude</literal>:</para> - -<screen> -$ ghc -e "interact (unlines.map reverse.lines)" -hello -olleh -</screen> - </sect2> - - <sect2 id="options-order"> - <title>Batch compiler mode</title> - - <para>In <emphasis>batch mode</emphasis>, GHC will compile one or more source files - given on the command line.</para> - - <para>The first phase to run is determined by each input-file - suffix, and the last phase is determined by a flag. If no - relevant flag is present, then go all the way through to linking. - This table summarises:</para> - - <informaltable> - <tgroup cols="4"> - <colspec align="left"/> - <colspec align="left"/> - <colspec align="left"/> - <colspec align="left"/> - - <thead> - <row> - <entry>Phase of the compilation system</entry> - <entry>Suffix saying “start here”</entry> - <entry>Flag saying “stop after”</entry> - <entry>(suffix of) output file</entry> - </row> - </thead> - <tbody> - <row> - <entry>literate pre-processor</entry> - <entry><literal>.lhs</literal></entry> - <entry>-</entry> - <entry><literal>.hs</literal></entry> - </row> - - <row> - <entry>C pre-processor (opt.) </entry> - <entry><literal>.hs</literal> (with - <option>-cpp</option>)</entry> - <entry><option>-E</option></entry> - <entry><literal>.hspp</literal></entry> - </row> - - <row> - <entry>Haskell compiler</entry> - <entry><literal>.hs</literal></entry> - <entry><option>-C</option>, <option>-S</option></entry> - <entry><literal>.hc</literal>, <literal>.s</literal></entry> - </row> - - <row> - <entry>C compiler (opt.)</entry> - <entry><literal>.hc</literal> or <literal>.c</literal></entry> - <entry><option>-S</option></entry> - <entry><literal>.s</literal></entry> - </row> - - <row> - <entry>assembler</entry> - <entry><literal>.s</literal></entry> - <entry><option>-c</option></entry> - <entry><literal>.o</literal></entry> - </row> - - <row> - <entry>linker</entry> - <entry><replaceable>other</replaceable></entry> - <entry>-</entry> - <entry><filename>a.out</filename></entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <indexterm><primary><option>-C</option></primary></indexterm> - <indexterm><primary><option>-E</option></primary></indexterm> - <indexterm><primary><option>-S</option></primary></indexterm> - <indexterm><primary><option>-c</option></primary></indexterm> - - <para>Thus, a common invocation would be: </para> - -<screen> -ghc -c Foo.hs -</screen> - - <para>to compile the Haskell source file - <filename>Foo.hs</filename> to an object file - <filename>Foo.o</filename>.</para> - - <para>Note: What the Haskell compiler proper produces depends on what - backend code generator is used. See <xref linkend="code-generators"/> - for more details.</para> - - <para>Note: C pre-processing is optional, the - <option>-cpp</option><indexterm><primary><option>-cpp</option></primary></indexterm> - flag turns it on. See <xref linkend="c-pre-processor"/> for more - details.</para> - - <para>Note: The option <option>-E</option><indexterm><primary>-E - option</primary></indexterm> runs just the pre-processing passes - of the compiler, dumping the result in a file.</para> - - <para>Note: The option <option>-C</option> is only available when - GHC is built in unregisterised mode. See <xref linkend="unreg"/> - for more details.</para> - - <sect3 id="overriding-suffixes"> - <title>Overriding the default behaviour for a file</title> - - <para>As described above, the way in which a file is processed by GHC - depends on its suffix. This behaviour can be overridden using the - <option>-x</option> option:</para> - - <variablelist> - <varlistentry> - <term><option>-x</option> <replaceable>suffix</replaceable> - <indexterm><primary><option>-x</option></primary> - </indexterm></term> - <listitem> - <para>Causes all files following this option on the command - line to be processed as if they had the suffix - <replaceable>suffix</replaceable>. For example, to compile a - Haskell module in the file <literal>M.my-hs</literal>, - use <literal>ghc -c -x hs M.my-hs</literal>.</para> - </listitem> - </varlistentry> - </variablelist> - </sect3> - - </sect2> - </sect1> - - <sect1 id="options-help"> - <title>Verbosity options</title> - - <indexterm><primary>verbosity options</primary></indexterm> - - <para>See also the <option>--help</option>, <option>--version</option>, <option>--numeric-version</option>, - and <option>--print-libdir</option> modes in <xref linkend="modes"/>.</para> - <variablelist> - <varlistentry> - <term> - <option>-v</option> - <indexterm><primary><option>-v</option></primary></indexterm> - </term> - <listitem> - <para>The <option>-v</option> option makes GHC - <emphasis>verbose</emphasis>: it reports its version number - and shows (on stderr) exactly how it invokes each phase of - the compilation system. Moreover, it passes the - <option>-v</option> flag to most phases; each reports its - version number (and possibly some other information).</para> - - <para>Please, oh please, use the <option>-v</option> option - when reporting bugs! Knowing that you ran the right bits in - the right order is always the first thing we want to - verify.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-v</option><replaceable>n</replaceable> - <indexterm><primary><option>-v</option></primary></indexterm> - </term> - <listitem> - <para>To provide more control over the compiler's verbosity, - the <option>-v</option> flag takes an optional numeric - argument. Specifying <option>-v</option> on its own is - equivalent to <option>-v3</option>, and the other levels - have the following meanings:</para> - - <variablelist> - <varlistentry> - <term><option>-v0</option></term> - <listitem> - <para>Disable all non-essential messages (this is the - default).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-v1</option></term> - <listitem> - <para>Minimal verbosity: print one line per - compilation (this is the default when - <option>--make</option> or - <option>--interactive</option> is on).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-v2</option></term> - <listitem> - <para>Print the name of each compilation phase as it - is executed. (equivalent to - <option>-dshow-passes</option>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-v3</option></term> - <listitem> - <para>The same as <option>-v2</option>, except that in - addition the full command line (if appropriate) for - each compilation phase is also printed.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-v4</option></term> - <listitem> - <para>The same as <option>-v3</option> except that the - intermediate program representation after each - compilation phase is also printed (excluding - preprocessed and C/assembly files).</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--fprint-potential-instances</option> - <indexterm><primary><option>-fprint-potential-instances</option></primary></indexterm> - </term> - <listitem> - <para>When GHC can't find an instance for a class, it displays a short list of some - in the instances it knows about. With this flag it prints <emphasis>all</emphasis> - the instances it knows about. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-fprint-explicit-foralls, -fprint-explicit-kinds, -fprint-unicode-syntax</option> - <indexterm><primary><option>-fprint-explicit-foralls</option></primary></indexterm> - <indexterm><primary><option>-fprint-explicit-kinds</option></primary></indexterm> - <indexterm><primary><option>-fprint-unicode-syntax</option></primary></indexterm> - </term> - <listitem> - <para>These three flags control the way in which GHC displays types, in error messages and in GHCi. - Using <option>-fprint-explicit-foralls</option> makes GHC print explicit <literal>forall</literal> - quantification at the top level of a type; normally this is suppressed. For example, in GHCi: -<screen> -ghci> let f x = x -ghci> :t f -f :: a -> a -ghci> :set -fprint-explicit-foralls -ghci> :t f -f :: forall a. a -> a -</screen> -However, regardless of the flag setting, the quantifiers are printed under these circumstances: -<itemizedlist> -<listitem><para>For nested <literal>foralls</literal>, e.g. -<screen> -ghci> :t GHC.ST.runST -GHC.ST.runST :: (forall s. GHC.ST.ST s a) -> a -</screen> -</para></listitem> -<listitem><para>If any of the quantified type variables has a kind -that mentions a kind variable, e.g. -<screen> -ghci> :i Data.Type.Equality.sym -Data.Type.Equality.sym :: - forall (k :: BOX) (a :: k) (b :: k). - (a Data.Type.Equality.:~: b) -> b Data.Type.Equality.:~: a - -- Defined in Data.Type.Equality -</screen> -</para></listitem> -</itemizedlist> - </para> - <para> - Using <option>-fprint-explicit-kinds</option> makes GHC print kind arguments - in types, which are normally suppressed. This can be important when you are using kind polymorphism. - For example: -<screen> -ghci> :set -XPolyKinds -ghci> data T a = MkT -ghci> :t MkT -MkT :: forall (k :: BOX) (a :: k). T a -ghci> :set -fprint-explicit-foralls -ghci> :t MkT -MkT :: forall (k :: BOX) (a :: k). T k a -</screen> - </para> - <para> - When <option>-fprint-unicode-syntax</option> is enabled, GHC prints type signatures using - the unicode symbols from the <option>-XUnicodeSyntax</option> extension. -<screen> -ghci> :set -fprint-unicode-syntax -ghci> :t (>>) -(>>) :: ∀ (m :: * → *) a b. Monad m ⇒ m a → m b → m b -</screen> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fprint-expanded-synonyms</option> - <indexterm><primary><option>-fprint-expanded-synonyms</option></primary></indexterm> - </term> - <listitem> - <para> - When enabled, GHC also prints type-synonym-expanded types in type - errors. - - For example, with this type synonyms: - -<screen> -type Foo = Int -type Bar = Bool -type MyBarST s = ST s Bar -</screen> - - This error message: - -<screen> -Couldn't match type 'Int' with 'Bool' -Expected type: ST s Foo - Actual type: MyBarST s -</screen> - - Becomes this: - -<screen> -Couldn't match type 'Int' with 'Bool' -Expected type: ST s Foo - Actual type: MyBarST s -Type synonyms expanded: -Expected type: ST s Int - Actual type: ST s Bool -</screen> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-ferror-spans</option> - <indexterm><primary><option>-ferror-spans</option></primary> - </indexterm> - </term> - <listitem> - <para>Causes GHC to emit the full source span of the - syntactic entity relating to an error message. Normally, GHC - emits the source location of the start of the syntactic - entity only.</para> - - <para>For example:</para> - -<screen> -test.hs:3:6: parse error on input `where' -</screen> - - <para>becomes:</para> - -<screen> -test296.hs:3:6-10: parse error on input `where' -</screen> - - <para>And multi-line spans are possible too:</para> - -<screen> -test.hs:(5,4)-(6,7): - Conflicting definitions for `a' - Bound at: test.hs:5:4 - test.hs:6:7 - In the binding group for: a, b, a -</screen> - - <para>Note that line numbers start counting at one, but - column numbers start at zero. This choice was made to - follow existing convention (i.e. this is how Emacs does - it).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-H</option><replaceable>size</replaceable> - <indexterm><primary><option>-H</option></primary></indexterm> - </term> - <listitem> - <para>Set the minimum size of the heap to - <replaceable>size</replaceable>. - This option is equivalent to - <literal>+RTS -H<replaceable>size</replaceable></literal>, - see <xref linkend="rts-options-gc" />. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-Rghc-timing</option> - <indexterm><primary><option>-Rghc-timing</option></primary></indexterm> - </term> - <listitem> - <para>Prints a one-line summary of timing statistics for the - GHC run. This option is equivalent to - <literal>+RTS -tstderr</literal>, see <xref - linkend="rts-options-gc" />. - </para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - &separate; - - <sect1 id="options-sanity"> - <title>Warnings and sanity-checking</title> - - <indexterm><primary>sanity-checking options</primary></indexterm> - <indexterm><primary>warnings</primary></indexterm> - - - <para>GHC has a number of options that select which types of - non-fatal error messages, otherwise known as warnings, can be - generated during compilation. By default, you get a standard set - of warnings which are generally likely to indicate bugs in your - program. These are: - <option>-fwarn-overlapping-patterns</option>, - <option>-fwarn-warnings-deprecations</option>, - <option>-fwarn-deprecated-flags</option>, - <option>-fwarn-unrecognised-pragmas</option>, - <option>-fwarn-missed-specialisations</option>, - <option>-fwarn-duplicate-constraints</option>, - <option>-fwarn-duplicate-exports</option>, - <option>-fwarn-overflowed-literals</option>, - <option>-fwarn-empty-enumerations</option>, - <option>-fwarn-missing-fields</option>, - <option>-fwarn-missing-methods</option>, - <option>-fwarn-wrong-do-bind</option>, - <option>-fwarn-unsupported-calling-conventions</option>, - <option>-fwarn-dodgy-foreign-imports</option>, - <option>-fwarn-inline-rule-shadowing</option>, - <option>-fwarn-unsupported-llvm-version</option>, - <option>-fwarn-context-quantification</option>, and - <option>-fwarn-tabs</option>. - The following flags are simple ways to select standard - “packages” of warnings: - </para> - - <variablelist> - - <varlistentry> - <term><option>-W</option>:</term> - <listitem> - <indexterm><primary>-W option</primary></indexterm> - <para>Provides the standard warnings plus - <option>-fwarn-unused-binds</option>, - <option>-fwarn-unused-matches</option>, - <option>-fwarn-unused-imports</option>, - <option>-fwarn-incomplete-patterns</option>, - <option>-fwarn-dodgy-exports</option>, and - <option>-fwarn-dodgy-imports</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-Wall</option>:</term> - <listitem> - <indexterm><primary><option>-Wall</option></primary></indexterm> - <para>Turns on all warning options that indicate potentially - suspicious code. The warnings that are - <emphasis>not</emphasis> enabled by <option>-Wall</option> - are - <option>-fwarn-incomplete-uni-patterns</option>, - <option>-fwarn-incomplete-record-updates</option>, - <option>-fwarn-monomorphism-restriction</option>, - <option>-fwarn-auto-orphans</option>, - <option>-fwarn-implicit-prelude</option>, - <option>-fwarn-missing-local-sigs</option>, - <option>-fwarn-missing-exported-sigs</option>, - <option>-fwarn-missing-import-lists</option> and - <option>-fwarn-identities</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-w</option>:</term> - <listitem> - <indexterm><primary><option>-w</option></primary></indexterm> - <para>Turns off all warnings, including the standard ones and - those that <literal>-Wall</literal> doesn't enable.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-Werror</option>:</term> - <listitem> - <indexterm><primary><option>-Werror</option></primary></indexterm> - <para>Makes any warning into a fatal error. Useful so that you don't - miss warnings when doing batch compilation. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-Wwarn</option>:</term> - <listitem> - <indexterm><primary><option>-Wwarn</option></primary></indexterm> - <para>Warnings are treated only as warnings, not as errors. This is - the default, but can be useful to negate a - <option>-Werror</option> flag.</para> - </listitem> - </varlistentry> - - </variablelist> - - <para>The full set of warning options is described below. To turn - off any warning, simply give the corresponding - <option>-fno-warn-...</option> option on the command line.</para> - - <variablelist> - - <varlistentry> - <term><option>-fwarn-typed-holes</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-typed-holes</option></primary> - </indexterm> - <indexterm><primary>warnings</primary></indexterm> - <para> - Determines whether the compiler reports typed holes warnings. Has - no effect unless typed holes errors are deferred until runtime. - See <xref linkend="typed-holes"/> and <xref linkend="defer-type-errors"/> - </para> - - <para>This warning is on by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-type-errors</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-type-errors</option></primary> - </indexterm> - <indexterm><primary>warnings</primary></indexterm> - <para>Causes a warning to be reported when a type error is deferred - until runtime. See <xref linkend="defer-type-errors"/></para> - <para>This warning is on by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fdefer-type-errors</option>:</term> - <listitem> - <indexterm><primary><option>-fdefer-type-errors</option></primary> - </indexterm> - <indexterm><primary>warnings</primary></indexterm> - <para>Defer as many type errors as possible until runtime. - At compile time you get a warning (instead of an error). At - runtime, if you use a value that depends on a type error, you - get a runtime error; but you can run any type-correct parts of your code - just fine. See <xref linkend="defer-type-errors"/></para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fdefer-typed-holes</option>:</term> - <listitem> - <indexterm><primary><option>-fdefer-typed-holes</option></primary> - </indexterm> - <indexterm><primary>warnings</primary></indexterm> - <para> - Defer typed holes errors until runtime. This will turn the errors - produced by <link linked="typed-holes">typed holes</link> into - warnings. Using a value that depends on a typed hole produces a - runtime error, the same as <option>-fdefer-type-errors</option> - (which implies this option). See <xref linkend="typed-holes"/> - and <xref linkend="defer-type-errors"/>. - </para> - <para> - Implied by <option>-fdefer-type-errors</option>. See also - <option>-fwarn-typed-holes</option>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-partial-type-signatures</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-partial-type-signatures</option></primary> - </indexterm> - <indexterm><primary>warnings</primary></indexterm> - <para> - Determines whether the compiler reports holes in partial type - signatures as warnings. Has no effect unless - <option>-XPartialTypeSignatures</option> is enabled, which - controls whether errors should be generated for holes in types - or not. See <xref linkend="partial-type-signatures"/>. - </para> - - <para>This warning is on by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fhelpful-errors</option>:</term> - <listitem> - <indexterm><primary><option>-fhelpful-errors</option></primary> - </indexterm> - <indexterm><primary>warnings</primary></indexterm> - <para>When a name or package is not found in scope, make - suggestions for the name or package you might have meant instead.</para> - <para>This option is on by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-unrecognised-pragmas</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-unrecognised-pragmas</option></primary> - </indexterm> - <indexterm><primary>warnings</primary></indexterm> - <indexterm><primary>pragmas</primary></indexterm> - <para>Causes a warning to be emitted when a - pragma that GHC doesn't recognise is used. As well as pragmas - that GHC itself uses, GHC also recognises pragmas known to be used - by other tools, e.g. <literal>OPTIONS_HUGS</literal> and - <literal>DERIVE</literal>.</para> - - <para>This option is on by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-missed-specialisations</option>, <option>-fwarn-all-missed-specialisations</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-missed-specialisations</option></primary></indexterm> - <indexterm><primary><option>-fwarn-all-missed-specialisations</option></primary></indexterm> - <indexterm><primary>warnings</primary></indexterm> - <indexterm><primary>pragmas</primary></indexterm> - <para>Emits a warning if GHC cannot specialise a function that is - imported and overloaded, usually because the function needs an - <literal>INLINEABLE</literal> pragma.. The "all" form reports all - such situations. The "non-all" form only reports when the situation - arises during specialisation of an imported function; presumably teh latter - was marked <literal>INLINEABLE</literal> so that it would specialise - but if it, in turn, calls other functions that are not specialised - you won't get the performance boost you expect.</para> - - <para><option>-fwarn-missed-specialisations</option> is on by default; - <option>-fwarn-all-missed-specialisations</option> is implied by <option>-Wall</option>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-warnings-deprecations</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-warnings-deprecations</option></primary> - </indexterm> - <indexterm><primary>warnings</primary></indexterm> - <indexterm><primary>deprecations</primary></indexterm> - <para>Causes a warning to be emitted when a - module, function or type with a WARNING or DEPRECATED pragma - is used. See <xref linkend="warning-deprecated-pragma"/> for more - details on the pragmas.</para> - - <para>This option is on by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-amp</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-amp</option></primary> - </indexterm> - <indexterm><primary>amp</primary></indexterm> - <indexterm><primary>applicative-monad proposal</primary></indexterm> - <para>Causes a warning to be emitted when a definition - is in conflict with the AMP (Applicative-Monad proosal), - namely: - 1. Instance of Monad without Applicative; - 2. Instance of MonadPlus without Alternative; - 3. Custom definitions of join/pure/<*></para> - - <para>This option is on by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-deprecated-flags</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-deprecated-flags</option></primary> - </indexterm> - <indexterm><primary>deprecated-flags</primary></indexterm> - <para>Causes a warning to be emitted when a deprecated - command-line flag is used.</para> - - <para>This option is on by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-unsupported-calling-conventions</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-unsupported-calling-conventions</option></primary> - </indexterm> - <para>Causes a warning to be emitted for foreign declarations - that use unsupported calling conventions. In particular, - if the <literal>stdcall</literal> calling convention is used - on an architecture other than i386 then it will be treated - as <literal>ccall</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-dodgy-foreign-imports</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-dodgy-foreign-imports</option></primary> - </indexterm> - <para>Causes a warning to be emitted for foreign imports of - the following form:</para> - -<programlisting> -foreign import "f" f :: FunPtr t -</programlisting> - - <para>on the grounds that it probably should be</para> - -<programlisting> -foreign import "&f" f :: FunPtr t -</programlisting> - - <para>The first form declares that `f` is a (pure) C - function that takes no arguments and returns a pointer to a - C function with type `t`, whereas the second form declares - that `f` itself is a C function with type `t`. The first - declaration is usually a mistake, and one that is hard to - debug because it results in a crash, hence this - warning.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-dodgy-exports</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-dodgy-exports</option></primary> - </indexterm> - <para>Causes a warning to be emitted when a datatype - <literal>T</literal> is exported - with all constructors, i.e. <literal>T(..)</literal>, but is it - just a type synonym.</para> - <para>Also causes a warning to be emitted when a module is - re-exported, but that module exports nothing.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-dodgy-imports</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-dodgy-imports</option></primary> - </indexterm> - <para>Causes a warning to be emitted in the following cases:</para> - <itemizedlist> - <listitem> - <para>When a datatype <literal>T</literal> is imported with all - constructors, i.e. <literal>T(..)</literal>, but has been - exported abstractly, i.e. <literal>T</literal>. - </para> - </listitem> - <listitem> - <para>When an <literal>import</literal> statement hides an - entity that is not exported.</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-overflowed-literals</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-overflowed-literals</option></primary> - </indexterm> - <para> - Causes a warning to be emitted if a literal will overflow, - e.g. <literal>300 :: Word8</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-empty-enumerations</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-empty-enumerations</option></primary> - </indexterm> - <para> - Causes a warning to be emitted if an enumeration is - empty, e.g. <literal>[5 .. 3]</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-lazy-unlifted-bindings</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-lazy-unlifted-bindings</option></primary> - </indexterm> - <para>This flag is a no-op, and will be removed in GHC 7.10.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-duplicate-constraints</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-duplicate-constraints</option></primary></indexterm> - <indexterm><primary>duplicate constraints, warning</primary></indexterm> - - <para>Have the compiler warn about duplicate constraints in a type signature. For - example - <programlisting> - f :: (Eq a, Show a, Eq a) => a -> a - </programlisting> - The warning will indicate the duplicated <literal>Eq a</literal> constraint. - </para> - - <para>This option is now deprecated in favour of <option>-fwarn-redundant-constraints</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-redundant-constraints</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-redundant-constraints</option></primary></indexterm> - <indexterm><primary>redundant constraints, warning</primary></indexterm> - - <para>Have the compiler warn about redundant constraints in a type signature. - In particular: - <itemizedlist> - <listitem><para> - A redundant constraint within the type signature itself: - <programlisting> - f :: (Eq a, Ord a) => a -> a - </programlisting> - The warning will indicate the redundant <literal>Eq a</literal> constraint: - it is subsumed by the <literal>Ord a</literal> constraint. - </para></listitem> - <listitem><para> - A constraint in the type signature is not used in the code it covers: - <programlisting> - f :: Eq a => a -> a -> Bool - f x y = True - </programlisting> - The warning will indicate the redundant <literal>Eq a</literal> constraint: - : it is not used by the definition of <literal>f</literal>.) - </para></listitem> - </itemizedlist> - Similar warnings are given for a redundant constraint in an instance declaration. - </para> - <para>This option is on by default. As usual you can suppress it on a per-module basis - with <option>-fno-warn-redundant-constraints</option>. Occasionally you may specifically - want a function to have a more constrained signature than necessary, perhaps to - leave yourself wiggle-room for changing the implementation without changing the - API. In that case, you can suppress the warning on a per-function basis, using a - call in a dead binding. For example: - <programlisting> - f :: Eq a => a -> a -> Bool - f x y = True - where - _ = x == x -- Suppress the redundant-constraint warning for (Eq a) - </programlisting> - Here the call to <literal>(==)</literal> makes GHC think that the <literal>(Eq a)</literal> - constraint is needed, so no warning is issued. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-duplicate-exports</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-duplicate-exports</option></primary></indexterm> - <indexterm><primary>duplicate exports, warning</primary></indexterm> - <indexterm><primary>export lists, duplicates</primary></indexterm> - - <para>Have the compiler warn about duplicate entries in - export lists. This is useful information if you maintain - large export lists, and want to avoid the continued export - of a definition after you've deleted (one) mention of it in - the export list.</para> - - <para>This option is on by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-hi-shadowing</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-hi-shadowing</option></primary></indexterm> - <indexterm><primary>shadowing</primary> - <secondary>interface files</secondary></indexterm> - - <para>Causes the compiler to emit a warning when a module or - interface file in the current directory is shadowing one - with the same module name in a library or other - directory.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-identities</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-identities</option></primary></indexterm> - <para>Causes the compiler to emit a warning when a Prelude numeric - conversion converts a type T to the same type T; such calls - are probably no-ops and can be omitted. The functions checked for - are: <literal>toInteger</literal>, - <literal>toRational</literal>, - <literal>fromIntegral</literal>, - and <literal>realToFrac</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-implicit-prelude</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-implicit-prelude</option></primary></indexterm> - <indexterm><primary>implicit prelude, warning</primary></indexterm> - <para>Have the compiler warn if the Prelude is implicitly - imported. This happens unless either the Prelude module is - explicitly imported with an <literal>import ... Prelude ...</literal> - line, or this implicit import is disabled (either by - <option>-XNoImplicitPrelude</option> or a - <literal>LANGUAGE NoImplicitPrelude</literal> pragma).</para> - - <para>Note that no warning is given for syntax that implicitly - refers to the Prelude, even if <option>-XNoImplicitPrelude</option> - would change whether it refers to the Prelude. - For example, no warning is given when - <literal>368</literal> means - <literal>Prelude.fromInteger (368::Prelude.Integer)</literal> - (where <literal>Prelude</literal> refers to the actual Prelude module, - regardless of the imports of the module being compiled).</para> - - <para>This warning is off by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-incomplete-patterns</option>, - <option>-fwarn-incomplete-uni-patterns</option>: - </term> - <listitem> - <indexterm><primary><option>-fwarn-incomplete-patterns</option></primary></indexterm> - <indexterm><primary><option>-fwarn-incomplete-uni-patterns</option></primary></indexterm> - <indexterm><primary>incomplete patterns, warning</primary></indexterm> - <indexterm><primary>patterns, incomplete</primary></indexterm> - - <para>The option <option>-fwarn-incomplete-patterns</option> warns - about places where - a pattern-match might fail at runtime. - The function - <function>g</function> below will fail when applied to - non-empty lists, so the compiler will emit a warning about - this when <option>-fwarn-incomplete-patterns</option> is - enabled. - -<programlisting> -g [] = 2 -</programlisting> - - This option isn't enabled by default because it can be - a bit noisy, and it doesn't always indicate a bug in the - program. However, it's generally considered good practice - to cover all the cases in your functions, and it is switched - on by <option>-W</option>.</para> - - <para>The flag <option>-fwarn-incomplete-uni-patterns</option> is - similar, except that it - applies only to lambda-expressions and pattern bindings, constructs - that only allow a single pattern: - -<programlisting> -h = \[] -> 2 -Just k = f y -</programlisting> - - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-incomplete-record-updates</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-incomplete-record-updates</option></primary></indexterm> - <indexterm><primary>incomplete record updates, warning</primary></indexterm> - <indexterm><primary>record updates, incomplete</primary></indexterm> - - <para>The function - <function>f</function> below will fail when applied to - <literal>Bar</literal>, so the compiler will emit a warning about - this when <option>-fwarn-incomplete-record-updates</option> is - enabled.</para> - -<programlisting> -data Foo = Foo { x :: Int } - | Bar - -f :: Foo -> Foo -f foo = foo { x = 6 } -</programlisting> - - <para>This option isn't enabled by default because it can be - very noisy, and it often doesn't indicate a bug in the - program.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fwarn-missing-fields</option>: - <indexterm><primary><option>-fwarn-missing-fields</option></primary></indexterm> - <indexterm><primary>missing fields, warning</primary></indexterm> - <indexterm><primary>fields, missing</primary></indexterm> - </term> - <listitem> - - <para>This option is on by default, and warns you whenever - the construction of a labelled field constructor isn't - complete, missing initialisers for one or more fields. While - not an error (the missing fields are initialised with - bottoms), it is often an indication of a programmer error.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fwarn-missing-import-lists</option>: - <indexterm><primary><option>-fwarn-import-lists</option></primary></indexterm> - <indexterm><primary>missing import lists, warning</primary></indexterm> - <indexterm><primary>import lists, missing</primary></indexterm> - </term> - <listitem> - - <para>This flag warns if you use an unqualified - <literal>import</literal> declaration - that does not explicitly list the entities brought into scope. For - example - </para> - -<programlisting> -module M where - import X( f ) - import Y - import qualified Z - p x = f x x -</programlisting> - - <para> - The <option>-fwarn-import-lists</option> flag will warn about the import - of <literal>Y</literal> but not <literal>X</literal> - If module <literal>Y</literal> is later changed to export (say) <literal>f</literal>, - then the reference to <literal>f</literal> in <literal>M</literal> will become - ambiguous. No warning is produced for the import of <literal>Z</literal> - because extending <literal>Z</literal>'s exports would be unlikely to produce - ambiguity in <literal>M</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-missing-methods</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-missing-methods</option></primary></indexterm> - <indexterm><primary>missing methods, warning</primary></indexterm> - <indexterm><primary>methods, missing</primary></indexterm> - - <para>This option is on by default, and warns you whenever - an instance declaration is missing one or more methods, and - the corresponding class declaration has no default - declaration for them.</para> - <para>The warning is suppressed if the method name - begins with an underscore. Here's an example where this is useful: - <programlisting> - class C a where - _simpleFn :: a -> String - complexFn :: a -> a -> String - complexFn x y = ... _simpleFn ... - </programlisting> - The idea is that: (a) users of the class will only call <literal>complexFn</literal>; - never <literal>_simpleFn</literal>; and (b) - instance declarations can define either <literal>complexFn</literal> or <literal>_simpleFn</literal>. - </para> - <para>The MINIMAL pragma can be used to change which combination of methods will be required for instances of a particular class. See <xref linkend="minimal-pragma"/>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-missing-signatures</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-missing-signatures</option></primary></indexterm> - <indexterm><primary>type signatures, missing</primary></indexterm> - - <para>If you would like GHC to check that every top-level - function/value has a type signature, use the - <option>-fwarn-missing-signatures</option> option. As part of - the warning GHC also reports the inferred type. The - option is off by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-missing-exported-sigs</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-missing-exported-sigs</option></primary></indexterm> - <indexterm><primary>type signatures, missing</primary></indexterm> - - <para>If you would like GHC to check that every exported top-level - function/value has a type signature, but not check unexported values, use the - <option>-fwarn-missing-exported-sigs</option> option. This option - takes precedence over <option>-fwarn-missing-signatures</option>. - As part of the warning GHC also reports the inferred type. The - option is off by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-missing-local-sigs</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-missing-local-sigs</option></primary></indexterm> - <indexterm><primary>type signatures, missing</primary></indexterm> - - <para>If you use the - <option>-fwarn-missing-local-sigs</option> flag GHC will warn - you about any polymorphic local bindings. As part of - the warning GHC also reports the inferred type. The - option is off by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-name-shadowing</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-name-shadowing</option></primary></indexterm> - <indexterm><primary>shadowing, warning</primary></indexterm> - - <para>This option causes a warning to be emitted whenever an - inner-scope value has the same name as an outer-scope value, - i.e. the inner value shadows the outer one. This can catch - typographical errors that turn into hard-to-find bugs, e.g., - in the inadvertent capture of what would be a recursive call in - <literal>f = ... let f = id in ... f ...</literal>.</para> - <para>The warning is suppressed for names beginning with an underscore. For example - <programlisting> - f x = do { _ignore <- this; _ignore <- that; return (the other) } - </programlisting> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-orphans, -fwarn-auto-orphans</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-orphans</option></primary></indexterm> - <indexterm><primary><option>-fwarn-auto-orphans</option></primary></indexterm> - <indexterm><primary>orphan instances, warning</primary></indexterm> - <indexterm><primary>orphan rules, warning</primary></indexterm> - - <para>These flags cause a warning to be emitted whenever the - module contains an "orphan" instance declaration or rewrite rule. - An instance declaration is an orphan if it appears in a module in - which neither the class nor the type being instanced are declared - in the same module. A rule is an orphan if it is a rule for a - function declared in another module. A module containing any - orphans is called an orphan module.</para> - <para>The trouble with orphans is that GHC must pro-actively read the interface - files for all orphan modules, just in case their instances or rules - play a role, whether or not the module's interface would otherwise - be of any use. See <xref linkend="orphan-modules"/> for details. - </para> - <para>The flag <option>-fwarn-orphans</option> warns about user-written - orphan rules or instances. The flag <option>-fwarn-auto-orphans</option> - warns about automatically-generated orphan rules, notably as a result of - specialising functions, for type classes (<literal>Specialise</literal>) - or argument values (<literal>-fspec-constr</literal>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fwarn-overlapping-patterns</option>: - <indexterm><primary><option>-fwarn-overlapping-patterns</option></primary></indexterm> - <indexterm><primary>overlapping patterns, warning</primary></indexterm> - <indexterm><primary>patterns, overlapping</primary></indexterm> - </term> - <listitem> - <para>By default, the compiler will warn you if a set of - patterns are overlapping, e.g.,</para> - -<programlisting> -f :: String -> Int -f [] = 0 -f (_:xs) = 1 -f "2" = 2 -</programlisting> - - <para>where the last pattern match in <function>f</function> - won't ever be reached, as the second pattern overlaps - it. More often than not, redundant patterns is a programmer - mistake/error, so this option is enabled by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-tabs</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-tabs</option></primary></indexterm> - <indexterm><primary>tabs, warning</primary></indexterm> - <para>Have the compiler warn if there are tabs in your source - file.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-type-defaults</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-type-defaults</option></primary></indexterm> - <indexterm><primary>defaulting mechanism, warning</primary></indexterm> - <para>Have the compiler warn/inform you where in your source - the Haskell defaulting mechanism for numeric types kicks - in. This is useful information when converting code from a - context that assumed one default into one with another, - e.g., the ‘default default’ for Haskell 1.4 caused the - otherwise unconstrained value <constant>1</constant> to be - given the type <literal>Int</literal>, whereas Haskell 98 - and later - defaults it to <literal>Integer</literal>. This may lead to - differences in performance and behaviour, hence the - usefulness of being non-silent about this.</para> - - <para>This warning is off by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-monomorphism-restriction</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-monomorphism-restriction</option></primary></indexterm> - <indexterm><primary>monomorphism restriction, warning</primary></indexterm> - <para>Have the compiler warn/inform you where in your source - the Haskell Monomorphism Restriction is applied. If applied silently - the MR can give rise to unexpected behaviour, so it can be helpful - to have an explicit warning that it is being applied.</para> - - <para>This warning is off by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-unticked-promoted-constructors</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-unticked-promoted-constructors</option></primary></indexterm> - <indexterm><primary>promoted constructor, warning</primary></indexterm> - <para>Warn if a promoted data constructor is used without a tick preceding it's name. - </para> - <para>For example: - </para> -<programlisting> -data Nat = Succ Nat | Zero - -data Vec n s where - Nil :: Vec Zero a - Cons :: a -> Vec n a -> Vec (Succ n) a -</programlisting> - <para> Will raise two warnings because <function>Zero</function> - and <function>Succ</function> are not written as <function>'Zero</function> and - <function>'Succ</function>. - </para> - <para>This warning is is enabled by default in <literal>-Wall</literal> mode.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-unused-binds</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-unused-binds</option></primary></indexterm> - <indexterm><primary>unused binds, warning</primary></indexterm> - <indexterm><primary>binds, unused</primary></indexterm> - <para>Report any function definitions (and local bindings) which are unused. An alias for - <itemizedlist> - <listitem><option>-fwarn-unused-top-binds</option></listitem> - <listitem><option>-fwarn-unused-local-binds</option></listitem> - <listitem><option>-fwarn-unused-pattern-binds</option></listitem> - </itemizedlist> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-unused-top-binds</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-unused-top-binds</option></primary></indexterm> - <indexterm><primary>unused binds, warning</primary></indexterm> - <indexterm><primary>binds, unused</primary></indexterm> - <para>Report any function definitions which are unused.</para> - - <para>More precisely, warn if a binding brings into scope a variable that is not used, - except if the variable's name starts with an underscore. The "starts-with-underscore" - condition provides a way to selectively disable the warning. - </para> - <para> - A variable is regarded as "used" if - <itemizedlist> - <listitem><para>It is exported, or</para></listitem> - <listitem><para>It appears in the right hand side of a binding that binds at - least one used variable that is used</para></listitem> - </itemizedlist> - For example - <programlisting> -module A (f) where -f = let (p,q) = rhs1 in t p -- No warning: q is unused, but is locally bound -t = rhs3 -- No warning: f is used, and hence so is t -g = h x -- Warning: g unused -h = rhs2 -- Warning: h is only used in the right-hand side of another unused binding -_w = True -- No warning: _w starts with an underscore - </programlisting> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-unused-local-binds</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-unused-local-binds</option></primary></indexterm> - <indexterm><primary>unused binds, warning</primary></indexterm> - <indexterm><primary>binds, unused</primary></indexterm> - <para>Report any local definitions which are unused. For example - <programlisting> -module A (f) where -f = let (p,q) = rhs1 in t p -- Warning: q is unused -g = h x -- No warning: g is unused, but is a top-level binding - </programlisting> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-unused-pattern-binds</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-unused-pattern-binds</option></primary></indexterm> - <indexterm><primary>unused binds, warning</primary></indexterm> - <indexterm><primary>binds, unused</primary></indexterm> - <para> - Warn if a pattern binding binds no variables at all, unless it is a lone, possibly-banged, wild-card pattern. - For example: - <programlisting> -Just _ = rhs3 -- Warning: unused pattern binding -(_, _) = rhs4 -- Warning: unused pattern binding -_ = rhs3 -- No warning: lone wild-card pattern -!_ = rhs4 -- No warning: banged wild-card pattern; behaves like seq - </programlisting> - The motivation for allowing lone wild-card patterns is they - are not very different from <literal>_v = rhs3</literal>, - which elicits no warning; and they can be useful to add a type - constraint, e.g. <literal>_ = x::Int</literal>. A lone - banged wild-card pattern is useful as an alternative - (to <literal>seq</literal>) way to force evaluation. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-unused-imports</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-unused-imports</option></primary></indexterm> - <indexterm><primary>unused imports, warning</primary></indexterm> - <indexterm><primary>imports, unused</primary></indexterm> - - <para>Report any modules that are explicitly imported but - never used. However, the form <literal>import M()</literal> is - never reported as an unused import, because it is a useful idiom - for importing instance declarations, which are anonymous in Haskell.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-unused-matches</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-unused-matches</option></primary></indexterm> - <indexterm><primary>unused matches, warning</primary></indexterm> - <indexterm><primary>matches, unused</primary></indexterm> - - <para>Report all unused variables which arise from pattern - matches, including patterns consisting of a single variable. - For instance <literal>f x y = []</literal> would report - <varname>x</varname> and <varname>y</varname> as unused. The - warning is suppressed if the variable name begins with an underscore, thus: - <programlisting> - f _x = True - </programlisting> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-unused-do-bind</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-unused-do-bind</option></primary></indexterm> - <indexterm><primary>unused do binding, warning</primary></indexterm> - <indexterm><primary>do binding, unused</primary></indexterm> - - <para>Report expressions occurring in <literal>do</literal> and <literal>mdo</literal> blocks - that appear to silently throw information away. - For instance <literal>do { mapM popInt xs ; return 10 }</literal> would report - the first statement in the <literal>do</literal> block as suspicious, - as it has the type <literal>StackM [Int]</literal> and not <literal>StackM ()</literal>, but that - <literal>[Int]</literal> value is not bound to anything. The warning is suppressed by - explicitly mentioning in the source code that your program is throwing something away: - <programlisting> - do { _ <- mapM popInt xs ; return 10 } - </programlisting> - Of course, in this particular situation you can do even better: - <programlisting> - do { mapM_ popInt xs ; return 10 } - </programlisting> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-context-quantification</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-context-quantification</option></primary></indexterm> - <indexterm><primary>implicit context quantification, warning</primary></indexterm> - <indexterm><primary>context, implicit quantification</primary></indexterm> - - <para>Report if a variable is quantified only due to its presence - in a context (see <xref linkend="universal-quantification"/>). For example, - <programlisting> - type T a = Monad m => a -> f a - </programlisting> - It is recommended to write this polymorphic type as - <programlisting> - type T a = forall m. Monad m => a -> f a - </programlisting> - instead. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-wrong-do-bind</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-wrong-do-bind</option></primary></indexterm> - <indexterm><primary>apparently erroneous do binding, warning</primary></indexterm> - <indexterm><primary>do binding, apparently erroneous</primary></indexterm> - - <para>Report expressions occurring in <literal>do</literal> and <literal>mdo</literal> blocks - that appear to lack a binding. - For instance <literal>do { return (popInt 10) ; return 10 }</literal> would report - the first statement in the <literal>do</literal> block as suspicious, - as it has the type <literal>StackM (StackM Int)</literal> (which consists of two nested applications - of the same monad constructor), but which is not then "unpacked" by binding the result. - The warning is suppressed by explicitly mentioning in the source code that your program is throwing something away: - <programlisting> - do { _ <- return (popInt 10) ; return 10 } - </programlisting> - For almost all sensible programs this will indicate a bug, and you probably intended to write: - <programlisting> - do { popInt 10 ; return 10 } - </programlisting> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-inline-rule-shadowing</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-inline-rule-shadowing</option></primary></indexterm> - <para>Warn if a rewrite RULE might fail to fire because the function might be - inlined before the rule has a chance to fire. See <xref linkend="rules-inline"/>. - </para> - </listitem> - </varlistentry> - - </variablelist> - - <para>If you're feeling really paranoid, the - <option>-dcore-lint</option> - option<indexterm><primary><option>-dcore-lint</option></primary></indexterm> - is a good choice. It turns on heavyweight intra-pass - sanity-checking within GHC. (It checks GHC's sanity, not - yours.)</para> - - </sect1> - - &packages; - - <sect1 id="options-optimise"> - <title>Optimisation (code improvement)</title> - - <indexterm><primary>optimisation</primary></indexterm> - <indexterm><primary>improvement, code</primary></indexterm> - - <para>The <option>-O*</option> options specify convenient - “packages” of optimisation flags; the - <option>-f*</option> options described later on specify - <emphasis>individual</emphasis> optimisations to be turned on/off; - the <option>-m*</option> options specify - <emphasis>machine-specific</emphasis> optimisations to be turned - on/off.</para> - - <para>Most of these options are boolean and have options to turn them both - “on” and “off” (beginning with the prefix - <option>no-</option>). For instance, while <option>-fspecialise</option> - enables specialisation, <option>-fno-specialise</option> disables it. When - multiple flags for the same option appear in the command-line they are - evaluated from left to right. For instance <option>-fno-specialise - -fspecialise</option> will enable specialisation. - </para> - - <para>It is important to note that the <option>-O*</option> flags are roughly - equivalent to combinations of <option>-f*</option> flags. For this reason, - the effect of the <option>-O*</option> and <option>-f*</option> flags is - dependent upon the order in which they occur on the command line. - </para> - - <para>For instance, take the example of <option>-fno-specialise - -O1</option>. Despite the <option>-fno-specialise</option> appearing in the - command line, specialisation will still be enabled. This is the case - as <option>-O1</option> implies <option>-fspecialise</option>, overriding - the previous flag. By contrast, <option>-O1 -fno-specialise</option> will - compile without specialisation, as one would expect. - </para> - - <sect2 id="optimise-pkgs"> - <title><option>-O*</option>: convenient “packages” of optimisation flags.</title> - - <para>There are <emphasis>many</emphasis> options that affect - the quality of code produced by GHC. Most people only have a - general goal, something like “Compile quickly” or - “Make my program run like greased lightning.” The - following “packages” of optimisations (or lack - thereof) should suffice.</para> - - <para>Note that higher optimisation levels cause more - cross-module optimisation to be performed, which can have an - impact on how much of your program needs to be recompiled when - you change something. This is one reason to stick to - no-optimisation when developing code.</para> - - <variablelist> - - <varlistentry> - <term> - No <option>-O*</option>-type option specified: - <indexterm><primary>-O* not specified</primary></indexterm> - </term> - <listitem> - <para>This is taken to mean: “Please compile - quickly; I'm not over-bothered about compiled-code - quality.” So, for example: <command>ghc -c - Foo.hs</command></para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-O0</option>: - <indexterm><primary><option>-O0</option></primary></indexterm> - </term> - <listitem> - <para>Means “turn off all optimisation”, - reverting to the same settings as if no - <option>-O</option> options had been specified. Saying - <option>-O0</option> can be useful if - eg. <command>make</command> has inserted a - <option>-O</option> on the command line already.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-O</option> or <option>-O1</option>: - <indexterm><primary>-O option</primary></indexterm> - <indexterm><primary>-O1 option</primary></indexterm> - <indexterm><primary>optimise</primary><secondary>normally</secondary></indexterm> - </term> - <listitem> - <para>Means: “Generate good-quality code without - taking too long about it.” Thus, for example: - <command>ghc -c -O Main.lhs</command></para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-O2</option>: - <indexterm><primary>-O2 option</primary></indexterm> - <indexterm><primary>optimise</primary><secondary>aggressively</secondary></indexterm> - </term> - <listitem> - <para>Means: “Apply every non-dangerous - optimisation, even if it means significantly longer - compile times.”</para> - - <para>The avoided “dangerous” optimisations - are those that can make runtime or space - <emphasis>worse</emphasis> if you're unlucky. They are - normally turned on or off individually.</para> - - <para>At the moment, <option>-O2</option> is - <emphasis>unlikely</emphasis> to produce better code than - <option>-O</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-Odph</option>: - <indexterm><primary>-Odph</primary></indexterm> - <indexterm><primary>optimise</primary><secondary>DPH</secondary></indexterm> - </term> - <listitem> - <para>Enables all <option>-O2</option> optimisation, sets - <option>-fmax-simplifier-iterations=20</option> - and <option>-fsimplifier-phases=3</option>. Designed for use with - <link linkend="dph">Data Parallel Haskell (DPH)</link>.</para> - </listitem> - </varlistentry> - - </variablelist> - - <para>We don't use a <option>-O*</option> flag for day-to-day - work. We use <option>-O</option> to get respectable speed; - e.g., when we want to measure something. When we want to go for - broke, we tend to use <option>-O2</option> (and we go for - lots of coffee breaks).</para> - - <para>The easiest way to see what <option>-O</option> (etc.) - “really mean” is to run with <option>-v</option>, - then stand back in amazement.</para> - </sect2> - - <sect2 id="options-f"> - <title><option>-f*</option>: platform-independent flags</title> - - <indexterm><primary>-f* options (GHC)</primary></indexterm> - <indexterm><primary>-fno-* options (GHC)</primary></indexterm> - - <para>These flags turn on and off individual optimisations. - Flags marked as <emphasis>Enabled by default</emphasis> are - enabled by <option>-O</option>, and as such you shouldn't - need to set any of them explicitly. A flag <option>-fwombat</option> - can be negated by saying <option>-fno-wombat</option>. - See <xref linkend="options-f-compact"/> for a compact list. - </para> - - <variablelist> - <varlistentry> - <term> - <option>-fcase-merge</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis> - Merge immediately-nested case expressions that scrutinse the same variable. Example -<programlisting> - case x of - Red -> e1 - _ -> case x of - Blue -> e2 - Green -> e3 -==> - case x of - Red -> e1 - Blue -> e2 - Green -> e2 -</programlisting> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fcall-arity</option> - <indexterm><primary><option>-fcall-arity</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fcmm-elim-common-blocks</option> - <indexterm><primary><option>-felim-common-blocks</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis>. Enables the common block - elimination optimisation in the code generator. This optimisation - attempts to find identical Cmm blocks and eliminate the duplicates. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fcmm-sink</option> - <indexterm><primary><option>-fcmm-sink</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis>. Enables the sinking pass - in the code generator. This optimisation - attempts to find identical Cmm blocks and eliminate the duplicates - attempts to move variable bindings closer to their usage sites. It - also inlines simple expressions like literals or registers. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fcpr-off</option> - <indexterm><primary><option>-fcpr-Off</option></primary></indexterm> - </term> - <listitem> - <para>Switch off CPR analysis in the demand analyser. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fcse</option> - <indexterm><primary><option>-fcse</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis>. Enables the common-sub-expression - elimination optimisation. - Switching this off can be useful if you have some <literal>unsafePerformIO</literal> - expressions that you don't want commoned-up.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fdicts-cheap</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para>A very experimental flag that makes dictionary-valued - expressions seem cheap to the optimiser. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fdicts-strict</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para>Make dictionaries strict. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fdmd-tx-dict-sel</option> - <indexterm><primary><option>-fdmd-tx-dict-sel</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default for <option>-O0</option>, <option>-O</option>, - <option>-O2</option>.</emphasis> - </para> - <para>Use a special demand transformer for dictionary selectors. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fdo-eta-reduction</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis> - Eta-reduce lambda expressions, if doing so gets rid of a whole - group of lambdas. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fdo-lambda-eta-expansion</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis> - Eta-expand let-bindings to increase their arity. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-feager-blackholing</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para>Usually GHC black-holes a thunk only when it switches - threads. This flag makes it do so as soon as the thunk is - entered. See <ulink url="http://research.microsoft.com/en-us/um/people/simonpj/papers/parallel/"> - Haskell on a shared-memory multiprocessor</ulink>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fexcess-precision</option> - <indexterm><primary><option>-fexcess-precision</option></primary></indexterm> - </term> - <listitem> - <para>When this option is given, intermediate floating - point values can have a <emphasis>greater</emphasis> - precision/range than the final type. Generally this is a - good thing, but some programs may rely on the exact - precision/range of - <literal>Float</literal>/<literal>Double</literal> values - and should not use this option for their compilation.</para> - - <para> - Note that the 32-bit x86 native code generator only - supports excess-precision mode, so neither - <option>-fexcess-precision</option> nor - <option>-fno-excess-precision</option> has any effect. - This is a known bug, see <xref linkend="bugs-ghc" />. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fexpose-all-unfoldings</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para>An experimental flag to expose all unfoldings, even for very - large or recursive functions. This allows for all functions to be - inlined while usually GHC would avoid inlining larger functions. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ffloat-in</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis> - Float let-bindings inwards, nearer their binding site. See - <ulink url="http://research.microsoft.com/en-us/um/people/simonpj/papers/float.ps.gz"> - Let-floating: moving bindings to give faster programs (ICFP'96)</ulink>. - </para> - - <para>This optimisation moves let bindings closer to their use - site. The benefit here is that this may avoid unnecessary - allocation if the branch the let is now on is never executed. It - also enables other optimisation passes to work more effectively - as they have more information locally. - </para> - - <para>This optimisation isn't always beneficial though (so GHC - applies some heuristics to decide when to apply it). The details - get complicated but a simple example is that it is often beneficial - to move let bindings outwards so that multiple let bindings can be - grouped into a larger single let binding, effectively batching - their allocation and helping the garbage collector and allocator. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ffull-laziness</option> - <indexterm><primary><option>-ffull-laziness</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis> - Run the full laziness optimisation (also known as let-floating), - which floats let-bindings outside enclosing lambdas, in the hope - they will be thereby be computed less often. See - <ulink url="http://research.microsoft.com/en-us/um/people/simonpj/papers/float.ps.gz">Let-floating: - moving bindings to give faster programs (ICFP'96)</ulink>. - Full laziness increases sharing, which can lead to increased memory - residency. - </para> - - <para>NOTE: GHC doesn't implement complete full-laziness. - When optimisation in on, and <option>-fno-full-laziness</option> - is not given, some transformations that increase sharing are - performed, such as extracting repeated computations from a loop. - These are the same transformations that a fully lazy - implementation would do, the difference is that GHC doesn't - consistently apply full-laziness, so don't rely on it. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ffun-to-thunk</option> - <indexterm><primary><option>-ffun-to-thunk</option></primary></indexterm> - </term> - <listitem> - <para>Worker-wrapper removes unused arguments, but usually we do - not remove them all, lest it turn a function closure into a thunk, - thereby perhaps creating a space leak and/or disrupting inlining. - This flag allows worker/wrapper to remove <emphasis>all</emphasis> - value lambdas. Off by default. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fignore-asserts</option> - <indexterm><primary><option>-fignore-asserts</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis>. - Causes GHC to ignore uses of the function - <literal>Exception.assert</literal> in source code (in - other words, rewriting <literal>Exception.assert p - e</literal> to <literal>e</literal> (see <xref - linkend="assertions"/>). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fignore-interface-pragmas</option> - <indexterm><primary><option>-fignore-interface-pragmas</option></primary></indexterm> - </term> - <listitem> - <para>Tells GHC to ignore all inessential information when reading interface files. - That is, even if <filename>M.hi</filename> contains unfolding or strictness information - for a function, GHC will ignore that information.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-flate-dmd-anal</option> - <indexterm><primary><option>-flate-dmd-anal</option></primary></indexterm> - </term> - <listitem> - <para>Run demand analysis - again, at the end of the simplification pipeline. We found some opportunities - for discovering strictness that were not visible earlier; and optimisations like - <literal>-fspec-constr</literal> can create functions with unused arguments which - are eliminated by late demand analysis. Improvements are modest, but so is the - cost. See notes on the <ulink url="http://ghc.haskell.org/trac/ghc/wiki/LateDmd">Trac wiki page</ulink>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fliberate-case</option> - <indexterm><primary><option>-fliberate-case</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>Off by default, but enabled by -O2.</emphasis> - Turn on the liberate-case transformation. This unrolls recursive - function once in its own RHS, to avoid repeated case analysis of - free variables. It's a bit like the call-pattern specialiser - (<option>-fspec-constr</option>) but for free variables rather than - arguments. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fliberate-case-threshold=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fliberate-case-threshold</option></primary></indexterm> - </term> - <listitem> - <para>Set the size threshold for the liberate-case transformation. Default: 2000 - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-floopification</option> - <indexterm><primary><option>-floopification</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis> - </para> - <para>When this optimisation is enabled the code generator will turn - all self-recursive saturated tail calls into local jumps rather - than function calls. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fmax-inline-alloc-size=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fmax-inline-alloc-size</option></primary></indexterm> - </term> - <listitem> - <para>Set the maximum size of inline array allocations to n bytes - (default: 128). GHC will allocate non-pinned arrays of statically - known size in the current nursery block if they're no bigger - than n bytes, ignoring GC overheap. This value should be quite - a bit smaller than the block size (typically: 4096). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fmax-inline-memcpy-insn=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fmax-inline-memcpy-insn</option></primary></indexterm> - </term> - <listitem> - <para>Inline <literal>memcpy</literal> calls if they would generate - no more than n pseudo instructions (default: 32). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fmax-inline-memset-insns=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fmax-inline-memset-insns</option></primary></indexterm> - </term> - <listitem> - <para>Inline <literal>memset</literal> calls if they would generate - no more than n pseudo instructions (default: 32). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fmax-relevant-binds=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fmax-relevant-bindings</option></primary></indexterm> - </term> - <listitem> - <para>The type checker sometimes displays a fragment of the type environment - in error messages, but only up to some maximum number, set by this flag. - The default is 6. Turning it off with <option>-fno-max-relevant-bindings</option> - gives an unlimited number. Syntactically top-level bindings are also - usually excluded (since they may be numerous), but - <option>-fno-max-relevant-bindings</option> includes them too. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fmax-simplifier-iterations=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fmax-simplifier-iterations</option></primary></indexterm> - </term> - <listitem> - <para>Sets the maximal number of iterations for the simplifier. Defult: 4. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fmax-worker-args=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fmax-worker-args</option></primary></indexterm> - </term> - <listitem> - <para>If a worker has that many arguments, none will be unpacked anymore (default: 10) - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fno-opt-coercion</option> - <indexterm><primary><option>-fno-opt-coercion</option></primary></indexterm> - </term> - <listitem> - <para>Turn off the coercion optimiser. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fno-pre-inlining</option> - <indexterm><primary><option>-fno-pre-inlining</option></primary></indexterm> - </term> - <listitem> - <para>Turn off pre-inlining. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fno-state-hack</option> - <indexterm><primary><option>-fno-state-hack</option></primary></indexterm> - </term> - <listitem> - <para>Turn off the "state hack" whereby any lambda with a - <literal>State#</literal> token as argument is considered to be - single-entry, hence it is considered OK to inline things inside - it. This can improve performance of IO and ST monad code, but it - runs the risk of reducing sharing. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fomit-interface-pragmas</option> - <indexterm><primary><option>-fomit-interface-pragmas</option></primary></indexterm> - </term> - <listitem> - <para>Tells GHC to omit all inessential information from the - interface file generated for the module being compiled (say M). - This means that a module importing M will see only the - <emphasis>types</emphasis> of the functions that M exports, but - not their unfoldings, strictness info, etc. Hence, for example, - no function exported by M will be inlined into an importing module. - The benefit is that modules that import M will need to be - recompiled less often (only when M's exports change their type, not - when they change their implementation).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fomit-yields</option> - <indexterm><primary><option>-fomit-yields</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis> Tells GHC to omit - heap checks when no allocation is being performed. While this improves - binary sizes by about 5%, it also means that threads run in - tight non-allocating loops will not get preempted in a timely - fashion. If it is important to always be able to interrupt such - threads, you should turn this optimization off. Consider also - recompiling all libraries with this optimization turned off, if you - need to guarantee interruptibility. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fpedantic-bottoms</option> - <indexterm><primary><option>-fpedantic-bottoms</option></primary></indexterm> - </term> - <listitem> - <para>Make GHC be more precise about its treatment of bottom (but see also - <option>-fno-state-hack</option>). In particular, stop GHC - eta-expanding through a case expression, which is good for - performance, but bad if you are using <literal>seq</literal> on - partial applications. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fregs-graph</option> - <indexterm><primary><option>-fregs-graph</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>Off by default due to a performance regression bug. - Only applies in combination with the native code generator.</emphasis> - Use the graph colouring register allocator for register allocation - in the native code generator. By default, GHC uses a simpler, - faster linear register allocator. The downside being that the - linear register allocator usually generates worse code. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fregs-iterative</option> - <indexterm><primary><option>-fregs-iterative</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>Off by default, only applies in combination with - the native code generator.</emphasis> - Use the iterative coalescing graph colouring register allocator for - register allocation in the native code generator. This is the same - register allocator as the <option>-fregs-graph</option> one but also - enables iterative coalescing during register allocation. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fsimplifier-phases=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fsimplifier-phases</option></primary></indexterm> - </term> - <listitem> - <para>Set the number of phases for the simplifier (default 2). Ignored with -O0. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fsimpl-tick-factor=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fsimpl-tick-factor</option></primary></indexterm> - </term> - <listitem> - <para>GHC's optimiser can diverge if you write rewrite rules ( - <xref linkend="rewrite-rules"/>) that don't terminate, or (less - satisfactorily) if you code up recursion through data types - (<xref linkend="bugs-ghc"/>). To avoid making the compiler fall - into an infinite loop, the optimiser carries a "tick count" and - stops inlining and applying rewrite rules when this count is - exceeded. The limit is set as a multiple of the program size, so - bigger programs get more ticks. The - <option>-fsimpl-tick-factor</option> flag lets you change the - multiplier. The default is 100; numbers larger than 100 give more - ticks, and numbers smaller than 100 give fewer. - </para> - - <para>If the tick-count expires, GHC summarises what simplifier - steps it has done; you can use - <option>-fddump-simpl-stats</option> to generate a much more - detailed list. Usually that identifies the loop quite - accurately, because some numbers are very large. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fspec-constr</option> - <indexterm><primary><option>-fspec-constr</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>Off by default, but enabled by -O2.</emphasis> - Turn on call-pattern specialisation; see - <ulink url="http://research.microsoft.com/en-us/um/people/simonpj/papers/spec-constr/index.htm"> - Call-pattern specialisation for Haskell programs</ulink>. - </para> - - <para>This optimisation specializes recursive functions according to - their argument "shapes". This is best explained by example so - consider: -<programlisting> -last :: [a] -> a -last [] = error "last" -last (x : []) = x -last (x : xs) = last xs -</programlisting> - In this code, once we pass the initial check for an empty list we - know that in the recursive case this pattern match is redundant. As - such <option>-fspec-constr</option> will transform the above code - to: -<programlisting> -last :: [a] -> a -last [] = error "last" -last (x : xs) = last' x xs - where - last' x [] = x - last' x (y : ys) = last' y ys -</programlisting> - </para> - - <para>As well avoid unnecessary pattern matching it also helps avoid - unnecessary allocation. This applies when a argument is strict in - the recursive call to itself but not on the initial entry. As - strict recursive branch of the function is created similar to the - above example. - </para> - - <para>It is also possible for library writers to instruct - GHC to perform call-pattern specialisation extremely - aggressively. This is necessary for some highly optimized - libraries, where we may want to specialize regardless of - the number of specialisations, or the size of the code. As - an example, consider a simplified use-case from the - <literal>vector</literal> library:</para> -<programlisting> -import GHC.Types (SPEC(..)) - -foldl :: (a -> b -> a) -> a -> Stream b -> a -{-# INLINE foldl #-} -foldl f z (Stream step s _) = foldl_loop SPEC z s - where - foldl_loop !sPEC z s = case step s of - Yield x s' -> foldl_loop sPEC (f z x) s' - Skip -> foldl_loop sPEC z s' - Done -> z -</programlisting> - - <para>Here, after GHC inlines the body of - <literal>foldl</literal> to a call site, it will perform - call-pattern specialisation very aggressively on - <literal>foldl_loop</literal> due to the use of - <literal>SPEC</literal> in the argument of the loop - body. <literal>SPEC</literal> from - <literal>GHC.Types</literal> is specifically recognised by - the compiler.</para> - - <para>(NB: it is extremely important you use - <literal>seq</literal> or a bang pattern on the - <literal>SPEC</literal> argument!)</para> - - <para>In particular, after inlining this will - expose <literal>f</literal> to the loop body directly, - allowing heavy specialisation over the recursive - cases.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fspec-constr-count=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fspec-constr-count</option></primary></indexterm> - </term> - <listitem> - <para>Set the maximum number of specialisations - that will be created for any one function by the SpecConstr - transformation (default: 3). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fspec-constr-threshold=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fspec-constr-threshold</option></primary></indexterm> - </term> - <listitem> - <para>Set the size threshold for the SpecConstr transformation (default: 2000). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fspecialise</option> - <indexterm><primary><option>-fspecialise</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis> - Specialise each type-class-overloaded function defined in this - module for the types at which it is called in this module. If - <literal>-fcross-module-specialise</literal> is set imported - functions that have an INLINABLE pragma - (<xref linkend="inlinable-pragma"/>) will be specialised as well. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fcross-module-specialise</option> - <indexterm><primary><option>-fcross-module-specialise</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis> - Specialise <literal>INLINABLE</literal> (<xref linkend="inlinable-pragma"/>) - type-class-overloaded functions imported from other modules for the - types at which they are called in this module. Note that specialisation must - be enabled (by <literal>-fspecialise</literal>) for this to have any effect. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fstatic-argument-transformation</option> - <indexterm><primary><option>-fstatic-argument-transformation</option></primary></indexterm> - </term> - <listitem> - <para>Turn on the static argument transformation, which turns a - recursive function into a non-recursive one with a local - recursive loop. See Chapter 7 of - <ulink url="http://research.microsoft.com/en-us/um/people/simonpj/papers/santos-thesis.ps.gz"> - Andre Santos's PhD thesis</ulink> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fstrictness</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para> <emphasis>On by default.</emphasis>. - Switch on the strictness analyser. There is a very old paper about GHC's - strictness analyser, <ulink url="http://research.microsoft.com/en-us/um/people/simonpj/papers/simple-strictnes-analyser.ps.gz"> - Measuring the effectiveness of a simple strictness analyser</ulink>, - but the current one is quite a bit different. - </para> - - <para>The strictness analyser figures out when arguments and - variables in a function can be treated 'strictly' (that is they - are always evaluated in the function at some point). This allow - GHC to apply certain optimisations such as unboxing that - otherwise don't apply as they change the semantics of the program - when applied to lazy arguments. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fstrictness-before=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fstrictness-before</option></primary></indexterm> - </term> - <listitem> - <para>Run an additional strictness analysis before simplifier phase n. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-funbox-small-strict-fields</option>: - <indexterm><primary><option>-funbox-small-strict-fields</option></primary></indexterm> - <indexterm><primary>strict constructor fields</primary></indexterm> - <indexterm><primary>constructor fields, strict</primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis>. This option - causes all constructor fields which are marked strict - (i.e. “!”) and which representation is smaller - or equal to the size of a pointer to be unpacked, if - possible. It is equivalent to adding an - <literal>UNPACK</literal> pragma (see <xref - linkend="unpack-pragma"/>) to every strict constructor - field that fulfils the size restriction. - </para> - - <para>For example, the constructor fields in the following - data types -<programlisting> -data A = A !Int -data B = B !A -newtype C = C B -data D = D !C -</programlisting> - would all be represented by a single - <literal>Int#</literal> (see <xref linkend="primitives"/>) - value with - <option>-funbox-small-strict-fields</option> enabled. - </para> - - <para>This option is less of a sledgehammer than - <option>-funbox-strict-fields</option>: it should rarely make things - worse. If you use <option>-funbox-small-strict-fields</option> - to turn on unboxing by default you can disable it for certain - constructor fields using the <literal>NOUNPACK</literal> pragma (see - <xref linkend="nounpack-pragma"/>).</para> - - <para> - Note that for consistency <literal>Double</literal>, - <literal>Word64</literal>, and <literal>Int64</literal> constructor - fields are unpacked on 32-bit platforms, even though they are - technically larger than a pointer on those platforms. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-funbox-strict-fields</option>: - <indexterm><primary><option>-funbox-strict-fields</option></primary></indexterm> - <indexterm><primary>strict constructor fields</primary></indexterm> - <indexterm><primary>constructor fields, strict</primary></indexterm> - </term> - <listitem> - <para>This option causes all constructor fields which are marked - strict (i.e. “!”) to be unpacked if possible. It is - equivalent to adding an <literal>UNPACK</literal> pragma to every - strict constructor field (see <xref linkend="unpack-pragma"/>). - </para> - - <para>This option is a bit of a sledgehammer: it might sometimes - make things worse. Selectively unboxing fields by using - <literal>UNPACK</literal> pragmas might be better. An alternative - is to use <option>-funbox-strict-fields</option> to turn on - unboxing by default but disable it for certain constructor - fields using the <literal>NOUNPACK</literal> pragma (see - <xref linkend="nounpack-pragma"/>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-funfolding-creation-threshold=<replaceable>n</replaceable></option>: - <indexterm><primary><option>-funfolding-creation-threshold</option></primary></indexterm> - <indexterm><primary>inlining, controlling</primary></indexterm> - <indexterm><primary>unfolding, controlling</primary></indexterm> - </term> - <listitem> - <para>(Default: 750) Governs the maximum size that GHC will allow a - function unfolding to be. (An unfolding has a “size” - that reflects the cost in terms of “code bloat” of - expanding (aka inlining) that unfolding at a call site. A bigger - function would be assigned a bigger cost.) - </para> - - <para>Consequences: (a) nothing larger than this will be inlined - (unless it has an INLINE pragma); (b) nothing larger than this - will be spewed into an interface file. - </para> - - <para>Increasing this figure is more likely to result in longer - compile times than faster code. The - <option>-funfolding-use-threshold</option> is more useful. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-funfolding-dict-discount=<replaceable>n</replaceable></option>: - <indexterm><primary><option>-funfolding-dict-discount</option></primary></indexterm> - <indexterm><primary>inlining, controlling</primary></indexterm> - <indexterm><primary>unfolding, controlling</primary></indexterm> - </term> - <listitem> - <para>Default: 30 - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-funfolding-fun-discount=<replaceable>n</replaceable></option>: - <indexterm><primary><option>-funfolding-fun-discount</option></primary></indexterm> - <indexterm><primary>inlining, controlling</primary></indexterm> - <indexterm><primary>unfolding, controlling</primary></indexterm> - </term> - <listitem> - <para>Default: 60 - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-funfolding-keeness-factor=<replaceable>n</replaceable></option>: - <indexterm><primary><option>-funfolding-keeness-factor</option></primary></indexterm> - <indexterm><primary>inlining, controlling</primary></indexterm> - <indexterm><primary>unfolding, controlling</primary></indexterm> - </term> - <listitem> - <para>Default: 1.5 - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-funfolding-use-threshold=<replaceable>n</replaceable></option> - <indexterm><primary><option>-funfolding-use-threshold</option></primary></indexterm> - <indexterm><primary>inlining, controlling</primary></indexterm> - <indexterm><primary>unfolding, controlling</primary></indexterm> - </term> - <listitem> - <para>(Default: 60) This is the magic cut-off figure for unfolding - (aka inlining): below this size, a function definition will be - unfolded at the call-site, any bigger and it won't. The size - computed for a function depends on two things: the actual size of - the expression minus any discounts that apply depending on the - context into which the expression is to be inlined. - </para> - - <para>The difference between this and - <option>-funfolding-creation-threshold</option> is that this one - determines if a function definition will be inlined <emphasis>at - a call site</emphasis>. The other option determines if a - function definition will be kept around at all for potential - inlining. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fvectorisation-avoidance</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para>Part of <link linkend="dph">Data Parallel Haskell - (DPH)</link>.</para> - - <para><emphasis>On by default.</emphasis> Enable the - <emphasis>vectorisation</emphasis> avoidance optimisation. This - optimisation only works when used in combination with the - <option>-fvectorise</option> transformation.</para> - - <para>While vectorisation of code using DPH is often a big win, it - can also produce worse results for some kinds of code. This - optimisation modifies the vectorisation transformation to try to - determine if a function would be better of unvectorised and if - so, do just that.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fvectorise</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para>Part of <link linkend="dph">Data Parallel Haskell - (DPH)</link>.</para> - - <para><emphasis>Off by default.</emphasis> Enable the - <emphasis>vectorisation</emphasis> optimisation transformation. This - optimisation transforms the nested data parallelism code of programs - using DPH into flat data parallelism. Flat data parallel programs - should have better load balancing, enable SIMD parallelism and - friendlier cache behaviour.</para> - </listitem> - </varlistentry> - - </variablelist> - - </sect2> - - </sect1> - - &code-gens; - - &phases; - - &shared_libs; - - <sect1 id="using-concurrent"> - <title>Using Concurrent Haskell</title> - <indexterm><primary>Concurrent Haskell</primary><secondary>using</secondary></indexterm> - - <para>GHC supports Concurrent Haskell by default, without requiring a - special option or libraries compiled in a certain way. To get access to - the support libraries for Concurrent Haskell, just import - <ulink - url="&libraryBaseLocation;/Control-Concurrent.html"><literal>Control.Concurrent</literal></ulink>. More information on Concurrent Haskell is provided in the documentation for that module.</para> - - <para> - Optionally, the program may be linked with - the <option>-threaded</option> option (see - <xref linkend="options-linker" />. This provides two benefits: - - <itemizedlist> - <listitem> - <para>It enables the <option>-N</option><indexterm><primary><option>-N<replaceable>x</replaceable></option></primary><secondary>RTS option</secondary></indexterm> RTS option to be - used, which allows threads to run in - parallel<indexterm><primary>parallelism</primary></indexterm> - on a - multiprocessor<indexterm><primary>multiprocessor</primary></indexterm><indexterm><primary>SMP</primary></indexterm> - or - multicore<indexterm><primary>multicore</primary></indexterm> - machine. See <xref linkend="using-smp" />.</para> - </listitem> - <listitem> - <para>If a thread makes a foreign call (and the call is - not marked <literal>unsafe</literal>), then other - Haskell threads in the program will continue to run - while the foreign call is in progress. - Additionally, <literal>foreign export</literal>ed - Haskell functions may be called from multiple OS - threads simultaneously. See - <xref linkend="ffi-threads" />.</para> - </listitem> - </itemizedlist> - </para> - - <para>The following RTS option(s) affect the behaviour of Concurrent - Haskell programs:<indexterm><primary>RTS options, concurrent</primary></indexterm></para> - - <variablelist> - <varlistentry> - <term><option>-C<replaceable>s</replaceable></option></term> - <listitem> - <para><indexterm><primary><option>-C<replaceable>s</replaceable></option></primary><secondary>RTS option</secondary></indexterm> - Sets the context switch interval to <replaceable>s</replaceable> - seconds. A context switch will occur at the next heap block - allocation after the timer expires (a heap block allocation occurs - every 4k of allocation). With <option>-C0</option> or - <option>-C</option>, context switches will occur as often as - possible (at every heap block allocation). By default, context - switches occur every 20ms.</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1 id="using-smp"> - <title>Using SMP parallelism</title> - <indexterm><primary>parallelism</primary> - </indexterm> - <indexterm><primary>SMP</primary> - </indexterm> - - <para>GHC supports running Haskell programs in parallel on an SMP - (symmetric multiprocessor).</para> - - <para>There's a fine distinction between - <emphasis>concurrency</emphasis> and <emphasis>parallelism</emphasis>: - parallelism is all about making your program run - <emphasis>faster</emphasis> by making use of multiple processors - simultaneously. Concurrency, on the other hand, is a means of - abstraction: it is a convenient way to structure a program that must - respond to multiple asynchronous events.</para> - - <para>However, the two terms are certainly related. By making use of - multiple CPUs it is possible to run concurrent threads in parallel, - and this is exactly what GHC's SMP parallelism support does. But it - is also possible to obtain performance improvements with parallelism - on programs that do not use concurrency. This section describes how to - use GHC to compile and run parallel programs, in <xref - linkend="lang-parallel" /> we describe the language features that affect - parallelism.</para> - - <sect2 id="parallel-compile-options"> - <title>Compile-time options for SMP parallelism</title> - - <para>In order to make use of multiple CPUs, your program must be - linked with the <option>-threaded</option> option (see <xref - linkend="options-linker" />). Additionally, the following - compiler options affect parallelism:</para> - - <variablelist> - <varlistentry> - <term><option>-feager-blackholing</option></term> - <indexterm><primary><option>-feager-blackholing</option></primary></indexterm> - <listitem> - <para> - Blackholing is the act of marking a thunk (lazy - computuation) as being under evaluation. It is useful for - three reasons: firstly it lets us detect certain kinds of - infinite loop (the <literal>NonTermination</literal> - exception), secondly it avoids certain kinds of space - leak, and thirdly it avoids repeating a computation in a - parallel program, because we can tell when a computation - is already in progress.</para> - - <para> - The option <option>-feager-blackholing</option> causes - each thunk to be blackholed as soon as evaluation begins. - The default is "lazy blackholing", whereby thunks are only - marked as being under evaluation when a thread is paused - for some reason. Lazy blackholing is typically more - efficient (by 1-2% or so), because most thunks don't - need to be blackholed. However, eager blackholing can - avoid more repeated computation in a parallel program, and - this often turns out to be important for parallelism. - </para> - - <para> - We recommend compiling any code that is intended to be run - in parallel with the <option>-feager-blackholing</option> - flag. - </para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="parallel-options"> - <title>RTS options for SMP parallelism</title> - - <para>There are two ways to run a program on multiple - processors: - call <literal>Control.Concurrent.setNumCapabilities</literal> from your - program, or use the RTS <option>-N</option> option.</para> - - <variablelist> - <varlistentry> - <term><option>-N<optional><replaceable>x</replaceable></optional></option></term> - <listitem> - <para><indexterm><primary><option>-N<replaceable>x</replaceable></option></primary><secondary>RTS option</secondary></indexterm> - Use <replaceable>x</replaceable> simultaneous threads when - running the program.</para> - - <para>The runtime manages a set of virtual processors, - which we call <emphasis>capabilities</emphasis>, the - number of which is determined by the <option>-N</option> - option. Each capability can run one Haskell thread at a - time, so the number of capabilities is equal to the - number of Haskell threads that can run physically in - parallel. A capability is animated by one or more OS - threads; the runtime manages a pool of OS threads for - each capability, so that if a Haskell thread makes a - foreign call (see <xref linkend="ffi-threads" />) - another OS thread can take over that capability. - </para> - - <para>Normally <replaceable>x</replaceable> should be - chosen to match the number of CPU cores on the - machine<footnote><para>Whether hyperthreading cores - should be counted or not is an open question; please - feel free to experiment and let us know what results you - find.</para></footnote>. For example, on a dual-core - machine we would probably use <literal>+RTS -N2 - -RTS</literal>.</para> - - <para>Omitting <replaceable>x</replaceable>, - i.e. <literal>+RTS -N -RTS</literal>, lets the runtime - choose the value of <replaceable>x</replaceable> itself - based on how many processors are in your machine.</para> - - <para>Be careful when using all the processors in your - machine: if some of your processors are in use by other - programs, this can actually harm performance rather than - improve it.</para> - - <para>Setting <option>-N</option> also has the effect of - enabling the parallel garbage collector (see - <xref linkend="rts-options-gc" />).</para> - - <para>The current value of the <option>-N</option> option - is available to the Haskell program via - <literal>Control.Concurrent.getNumCapabilities</literal>, - and it may be changed while the program is running by - calling - <literal>Control.Concurrent.setNumCapabilities</literal>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The following options affect the way the runtime schedules - threads on CPUs:</para> - - <variablelist> - <varlistentry> - <term><option>-qa</option></term> - <indexterm><primary><option>-qa</option></primary><secondary>RTS - option</secondary></indexterm> - <listitem> - <para>Use the OS's affinity facilities to try to pin OS - threads to CPU cores.</para> - - <para>When this option is enabled, the OS threads for a - capability <emphasis>i</emphasis> are bound to the CPU - core <emphasis>i</emphasis> using the API provided by the - OS for setting thread affinity. e.g. on Linux - GHC uses <literal>sched_setaffinity()</literal>.</para> - - <para>Depending on your workload and the other activity on - the machine, this may or may not result in a performance - improvement. We recommend trying it out and measuring the - difference.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-qm</option></term> - <indexterm><primary><option>-qm</option></primary><secondary>RTS - option</secondary></indexterm> - <listitem> - <para>Disable automatic migration for load balancing. - Normally the runtime will automatically try to schedule - threads across the available CPUs to make use of idle - CPUs; this option disables that behaviour. Note that - migration only applies to threads; sparks created - by <literal>par</literal> are load-balanced separately - by work-stealing.</para> - - <para> - This option is probably only of use for concurrent - programs that explicitly schedule threads onto CPUs - with <literal>Control.Concurrent.forkOn</literal>. - </para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>Hints for using SMP parallelism</title> - - <para>Add the <literal>-s</literal> RTS option when - running the program to see timing stats, which will help to tell you - whether your program got faster by using more CPUs or not. If the user - time is greater than - the elapsed time, then the program used more than one CPU. You should - also run the program without <literal>-N</literal> for - comparison.</para> - - <para>The output of <literal>+RTS -s</literal> tells you how - many “sparks” were created and executed during the - run of the program (see <xref linkend="rts-options-gc" />), which - will give you an idea how well your <literal>par</literal> - annotations are working.</para> - - <para>GHC's parallelism support has improved in 6.12.1 as a - result of much experimentation and tuning in the runtime - system. We'd still be interested to hear how well it works - for you, and we're also interested in collecting parallel - programs to add to our benchmarking suite.</para> - </sect2> - </sect1> - - <sect1 id="options-platform"> - <title>Platform-specific Flags</title> - - <indexterm><primary>-m* options</primary></indexterm> - <indexterm><primary>platform-specific options</primary></indexterm> - <indexterm><primary>machine-specific options</primary></indexterm> - - <para>Some flags only make sense for particular target - platforms.</para> - - <variablelist> - - <varlistentry> - <term><option>-msse2</option>:</term> - <listitem> - <para> - (x86 only, added in GHC 7.0.1) Use the SSE2 registers and - instruction set to implement floating point operations when using - the <link linkend="native-code-gen">native code generator</link>. - This gives a substantial performance improvement for floating - point, but the resulting compiled code - will only run on processors that support SSE2 (Intel Pentium 4 and - later, or AMD Athlon 64 and later). The - <link linkend="llvm-code-gen">LLVM backend</link> will also use SSE2 - if your processor supports it but detects this automatically so no - flag is required. - </para> - <para> - SSE2 is unconditionally used on x86-64 platforms. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-msse4.2</option>:</term> - <listitem> - <para> - (x86 only, added in GHC 7.4.1) Use the SSE4.2 instruction set to - implement some floating point and bit operations when using the - <link linkend="native-code-gen">native code generator</link>. The - resulting compiled code will only run on processors that - support SSE4.2 (Intel Core i7 and later). The - <link linkend="llvm-code-gen">LLVM backend</link> will also use - SSE4.2 if your processor supports it but detects this automatically - so no flag is required. - </para> - </listitem> - </varlistentry> - - </variablelist> - - </sect1> - -&runtime; -&debug; -&flags; - -</chapter> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> diff --git a/docs/users_guide/utils.rst b/docs/users_guide/utils.rst new file mode 100644 index 0000000000..9c1237dd02 --- /dev/null +++ b/docs/users_guide/utils.rst @@ -0,0 +1,278 @@ +.. _utils: + +Other Haskell utility programs +============================== + +.. index:: + single: utilities, Haskell + +This section describes other program(s) which we distribute, that help +with the Great Haskell Programming Task. + +.. _happy: + +"Yacc for Haskell": ``happy`` +----------------------------- + +.. index:: + single: Happy + single: Yacc for Haskell + single: parser generator for Haskell + single: happy parser generator + +Andy Gill and Simon Marlow have written a parser-generator for Haskell, +called ``happy``. ``Happy`` is to Haskell what ``Yacc`` is to C. + +You can get ``happy`` from `the Happy +Homepage <http://www.haskell.org/happy/>`__. + +``Happy`` is at its shining best when compiled by GHC. + +.. _hsc2hs: + +Writing Haskell interfaces to C code: ``hsc2hs`` +------------------------------------------------ + +.. index:: + single: hsc2hs + +The ``hsc2hs`` command can be used to automate some parts of the process +of writing Haskell bindings to C code. It reads an almost-Haskell source +with embedded special constructs, and outputs a real Haskell file with +these constructs processed, based on information taken from some C +headers. The extra constructs deal with accessing C data from Haskell. + +It may also output a C file which contains additional C functions to be +linked into the program, together with a C header that gets included +into the C code to which the Haskell module will be compiled (when +compiled via C) and into the C file. These two files are created when +the ``#def`` construct is used (see below). + +Actually ``hsc2hs`` does not output the Haskell file directly. It +creates a C program that includes the headers, gets automatically +compiled and run. That program outputs the Haskell code. + +In the following, "Haskell file" is the main output (usually a ``.hs`` +file), "compiled Haskell file" is the Haskell file after ``ghc`` has +compiled it to C (i.e. a ``.hc`` file), "C program" is the program that +outputs the Haskell file, "C file" is the optionally generated C file, +and "C header" is its header file. + +command line syntax +~~~~~~~~~~~~~~~~~~~ + +``hsc2hs`` takes input files as arguments, and flags that modify its +behavior: + +``-o FILE``, ``--output=FILE`` + Name of the Haskell file. + +``-t FILE``, ``--template=FILE`` + The template file (see below). + +``-c PROG``, ``--cc=PROG`` + The C compiler to use (default: ``gcc``) + +``-l PROG``, ``--ld=PROG`` + The linker to use (default: ``gcc``). + +``-C FLAG``, ``--cflag=FLAG`` + An extra flag to pass to the C compiler. + +``-I DIR`` + Passed to the C compiler. + +``-L FLAG``, ``--lflag=FLAG`` + An extra flag to pass to the linker. + +``-i FILE``, ``--include=FILE`` + As if the appropriate ``#include`` directive was placed in the + source. + +``-D NAME[=VALUE]``, ``--define=NAME[=VALUE]`` + As if the appropriate ``#define`` directive was placed in the + source. + +``--no-compile`` + Stop after writing out the intermediate C program to disk. The file + name for the intermediate C program is the input file name with + ``.hsc`` replaced with ``_hsc_make.c``. + +``-k``, ``--keep-files`` + Proceed as normal, but do not delete any intermediate files. + +``-x``, ``--cross-compile`` + Activate cross-compilation mode (see :ref:`hsc2hs_cross`). + +``--cross-safe`` + Restrict the .hsc directives to those supported by the + ``--cross-compile`` mode (see :ref:`hsc2hs_cross`). This should be + useful if your ``.hsc`` files must be safely cross-compiled and you + wish to keep non-cross-compilable constructs from creeping into + them. + +``-?``, ``--help`` + Display a summary of the available flags and exit successfully. + +``-V``, ``--version`` + Output version information and exit successfully. + +The input file should end with .hsc (it should be plain Haskell source +only; literate Haskell is not supported at the moment). Output files by +default get names with the ``.hsc`` suffix replaced: + ++--------------+----------------+ +| ``.hs`` | Haskell file | ++--------------+----------------+ +| ``_hsc.h`` | C header | ++--------------+----------------+ +| ``_hsc.c`` | C file | ++--------------+----------------+ + +The C program is compiled using the Haskell compiler. This provides the +include path to ``HsFFI.h`` which is automatically included into the C +program. + +Input syntax +~~~~~~~~~~~~ + +All special processing is triggered by the ``#`` operator. To output a +literal ``#``, write it twice: ``##``. Inside string literals and +comments ``#`` characters are not processed. + +A ``#`` is followed by optional spaces and tabs, an alphanumeric keyword +that describes the kind of processing, and its arguments. Arguments look +like C expressions separated by commas (they are not written inside +parens). They extend up to the nearest unmatched ``)``, ``]`` or ``}``, +or to the end of line if it occurs outside any ``() [] {} '' "" /**/`` +and is not preceded by a backslash. Backslash-newline pairs are +stripped. + +In addition ``#{stuff}`` is equivalent to ``#stuff`` except that it's +self-delimited and thus needs not to be placed at the end of line or in +some brackets. + +Meanings of specific keywords: + +``#include <file.h>``, ``#include "file.h"`` + The specified file gets included into the C program, the compiled + Haskell file, and the C header. ``<HsFFI.h>`` is included + automatically. + +``#define ⟨name⟩``, ``#define ⟨name ⟨value⟩``, ``#undef ⟨name⟩`` + Similar to ``#include``. Note that ``#includes`` and ``#defines`` + may be put in the same file twice so they should not assume + otherwise. + +``#let ⟨name⟩ ⟨parameters⟩ = "⟨definition⟩"`` + Defines a macro to be applied to the Haskell source. Parameter names + are comma-separated, not inside parens. Such macro is invoked as + other ``#``-constructs, starting with ``#name``. The definition will + be put in the C program inside parens as arguments of ``printf``. To + refer to a parameter, close the quote, put a parameter name and open + the quote again, to let C string literals concatenate. Or use + ``printf``'s format directives. Values of arguments must be given as + strings, unless the macro stringifies them itself using the C + preprocessor's ``#parameter`` syntax. + +``#def ⟨C_definition⟩`` + The definition (of a function, variable, struct or typedef) is + written to the C file, and its prototype or extern declaration to + the C header. Inline functions are handled correctly. struct + definitions and typedefs are written to the C program too. The + ``inline``, ``struct`` or ``typedef`` keyword must come just after + ``def``. + +``#if ⟨condition⟩``, ``#ifdef ⟨name⟩``, ``#ifndef ⟨name⟩``, ``#elif ⟨condition⟩``, ``#else``, ``#endif``, ``#error ⟨message⟩``, ``#warning ⟨message⟩`` + Conditional compilation directives are passed unmodified to the C + program, C file, and C header. Putting them in the C program means + that appropriate parts of the Haskell file will be skipped. + +``#const ⟨C_expression⟩`` + The expression must be convertible to ``long`` or ``unsigned long``. + Its value (literal or negated literal) will be output. + +``#const_str ⟨C_expression⟩`` + The expression must be convertible to const char pointer. Its value + (string literal) will be output. + +``#type ⟨C_type⟩`` + A Haskell equivalent of the C numeric type will be output. It will + be one of ``{Int,Word}{8,16,32,64}``, ``Float``, ``Double``, + ``LDouble``. + +``#peek ⟨struct_type⟩, ⟨field⟩`` + A function that peeks a field of a C struct will be output. It will + have the type ``Storable b => Ptr a -> IO b``. The intention is that + ``#peek`` and ``#poke`` can be used for implementing the operations + of class ``Storable`` for a given C struct (see the + ``Foreign.Storable`` module in the library documentation). + +``#poke ⟨struct_type⟩, ⟨field⟩`` + Similarly for poke. It will have the type + ``Storable b => Ptr a -> b -> IO ()``. + +``#ptr ⟨struct_type⟩, ⟨field⟩`` + Makes a pointer to a field struct. It will have the type + ``Ptr a -> Ptr b``. + +``#offset ⟨struct_type⟩, ⟨field⟩`` + Computes the offset, in bytes, of ``field`` in ``struct_type``. It + will have type ``Int``. + +``#size ⟨struct_type⟩`` + Computes the size, in bytes, of ``struct_type``. It will have type + ``Int``. + +``#enum ⟨type⟩, ⟨constructor⟩, ⟨value⟩, ⟨value⟩, ...`` + A shortcut for multiple definitions which use ``#const``. Each + ``value`` is a name of a C integer constant, e.g. enumeration value. + The name will be translated to Haskell by making each letter + following an underscore uppercase, making all the rest lowercase, + and removing underscores. You can supply a different translation by + writing ``hs_name = c_value`` instead of a ``value``, in which case + ``c_value`` may be an arbitrary expression. The ``hs_name`` will be + defined as having the specified ``type``. Its definition is the + specified ``constructor`` (which in fact may be an expression or be + empty) applied to the appropriate integer value. You can have + multiple ``#enum`` definitions with the same ``type``; this + construct does not emit the type definition itself. + +Custom constructs +~~~~~~~~~~~~~~~~~ + +``#const``, ``#type``, ``#peek``, ``#poke`` and ``#ptr`` are not +hardwired into the ``hsc2hs``, but are defined in a C template that is +included in the C program: ``template-hsc.h``. Custom constructs and +templates can be used too. Any ``#``\-construct with unknown key is +expected to be handled by a C template. + +A C template should define a macro or function with name prefixed by +``hsc_`` that handles the construct by emitting the expansion to stdout. +See ``template-hsc.h`` for examples. + +Such macros can also be defined directly in the source. They are useful +for making a ``#let``\-like macro whose expansion uses other ``#let`` +macros. Plain ``#let`` prepends ``hsc_`` to the macro name and wraps the +definition in a ``printf`` call. + +.. _hsc2hs_cross: + +Cross-compilation +~~~~~~~~~~~~~~~~~ + +``hsc2hs`` normally operates by creating, compiling, and running a C +program. That approach doesn't work when cross-compiling — in this +case, the C compiler's generates code for the target machine, not the +host machine. For this situation, there's a special mode +``hsc2hs --cross-compile`` which can generate the .hs by extracting +information from compilations only — specifically, whether or not +compilation fails. + +Only a subset of ``.hsc`` syntax is supported by ``--cross-compile``. +The following are unsupported: + +- ``#{const_str}`` +- ``#{let}`` +- ``#{def}`` +- Custom constructs diff --git a/docs/users_guide/utils.xml b/docs/users_guide/utils.xml deleted file mode 100644 index eeb22128ec..0000000000 --- a/docs/users_guide/utils.xml +++ /dev/null @@ -1,607 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<chapter id="utils"> - <title>Other Haskell utility programs</title> - <indexterm><primary>utilities, Haskell</primary></indexterm> - - <para>This section describes other program(s) which we distribute, - that help with the Great Haskell Programming Task.</para> - -<!-- comment: hasktags was dropped in GHC 6.12 - -<sect1 id ="hasktags"> - <title>Ctags and Etags for Haskell: <command>hasktags</command></title> - <indexterm><primary><command>hasktags</command></primary></indexterm> - <indexterm><primary>CTAGS for Haskell</primary></indexterm> - - <para><command>hasktags</command> is a very simple Haskell program that produces ctags "tags" and etags "TAGS" files for Haskell programs.</para> - - <para>When loaded into an editor such an NEdit, Vim, or Emacs, this allows one to easily navigate around a multi-file program, finding definitions of functions, types, and constructors.</para> - - <para>Invocation Syntax:</para> - -<screen> -hasktags files -</screen> - -<para>This will read all the files listed in <option>files</option> and produce a ctags "tags" file and an etags "TAGS" file in the current directory.</para> - - <para>Example usage</para> - -<screen> -find -name \*.\*hs | xargs hasktags -</screen> - -<para>This will find all haskell source files in the current directory and below, and create tags files indexing them in the current directory.</para> - - <para><command>hasktags</command> is a simple program that uses simple - parsing rules to find definitions of functions, constructors, and types. It isn't guaranteed to find everything, and will sometimes create false index entries, but it usually gets the job done fairly well. In particular, at present, functions are only indexed if a type signature is given for them.</para> - - <para>Before hasktags, there used to be <command>fptags</command> and <command>hstags</command>, which did essentially the same job, however neither of these seem to be maintained any more.</para> - -<sect2> -<title>Using tags with your editor</title> - -<para>With NEdit, load the "tags" file using "File/Load Tags File". Use "Ctrl-D" to search for a tag.</para> - -<para>With XEmacs, load the "TAGS" file using "visit-tags-table". Use "M-." to search for a tag.</para> - - -</sect2> - -</sect1> - ---> -<!-- comment: hstags doesn't work anymore - - <sect1 id="hstags"> - <title>Emacs `TAGS' for Haskell: <command>hstags</command></title> - <indexterm><primary><command>hstags</command></primary></indexterm> - <indexterm><primary>TAGS for Haskell</primary></indexterm> - - <para>`Tags' is a facility for indexing the definitions of - programming-language things in a multi-file program, and then - using that index to jump around among these definitions.</para> - - <para>Rather than scratch your head, saying “Now where did - we define `foo'?”, you just do (in Emacs) <Literal>M-. foo - RET</Literal>, and You're There! Some people go wild over this - stuff…</para> - - <para>GHC comes with a program <command>hstags</command>, which - build Emacs-able TAGS files. The invocation syntax is:</para> - -<screen> -hstags [GHC-options] file [files...] -</screen> - - <para>The best thing is just to feed it your GHC command-line - flags. A good Makefile entry might be:</para> - -<programlisting> -tags: - $(RM) TAGS - hstags $(GHC_FLAGS) *.lhs -</programlisting> - - <para>The only flags of its own are: <Option>-v</Option> to be - verbose; <Option>-a</Option> to <Emphasis>APPEND</Emphasis> to the - TAGS file, rather than write to it.</para> - - <para>Shortcomings: (1) Instance declarations don't get into - the TAGS file (but the definitions inside them do); as instances - aren't named, this is probably just as well. - (2) Data-constructor definitions don't get in. Go for the - corresponding type constructor instead.</para> - - <para>Actually, GHC also comes with <command>etags</command> - [for C], and <command>perltags</command> [for You - Know What]. And—I cannot tell a lie—there is - Denis Howe's <command>fptags</command> [for Haskell, - etc.] in the <Filename>ghc/CONTRIB</Filename> - section…)</para> - - </sect1> ---> - - <sect1 id="happy"> - <title>“Yacc for Haskell”: <command>happy</command></title> - - <indexterm><primary>Happy</primary></indexterm> - <indexterm><primary>Yacc for Haskell</primary></indexterm> - <indexterm><primary>parser generator for Haskell</primary></indexterm> - - <para>Andy Gill and Simon Marlow have written a parser-generator - for Haskell, called - <command>happy</command>.<indexterm><primary>happy parser - generator</primary></indexterm> <command>Happy</command> is to - Haskell what <command>Yacc</command> is to C.</para> - - <para>You can get <command>happy</command> from <ulink - url="http://www.haskell.org/happy/">the Happy - Homepage</ulink>.</para> - - <para><command>Happy</command> is at its shining best when - compiled by GHC.</para> - - </sect1> - -<!-- we don't distribute this anymore - <sect1 id="pphs"> - <title>Pretty-printing Haskell: <command>pphs</command></title> - <indexterm><primary>pphs</primary></indexterm> - <indexterm><primary>pretty-printing Haskell code</primary></indexterm> - - <para>Andrew Preece has written - <command>pphs</command>,<indexterm><primary>pphs</primary></indexterm><indexterm><primary>pretty-printing - Haskell</primary></indexterm> a utility to pretty-print Haskell - code in LaTeX documents. Keywords in bolds, variables in - italics—that sort of thing. It is good at lining up program - clauses and equals signs, things that are very tiresome to do by - hand.</para> - - <para>The code is distributed with GHC in - <Filename>ghc/CONTRIB/pphs</Filename>.</para> - </sect1> ---> - - <sect1 id="hsc2hs"> - <title>Writing Haskell interfaces to C code: - <command>hsc2hs</command></title> - <indexterm><primary><command>hsc2hs</command></primary> - </indexterm> - - <para>The <command>hsc2hs</command> command can be used to automate - some parts of the process of writing Haskell bindings to C code. - It reads an almost-Haskell source with embedded special - constructs, and outputs a real Haskell file with these constructs - processed, based on information taken from some C headers. The - extra constructs deal with accessing C data from Haskell.</para> - - <para>It may also output a C file which contains additional C - functions to be linked into the program, together with a C header - that gets included into the C code to which the Haskell module - will be compiled (when compiled via C) and into the C file. These - two files are created when the <literal>#def</literal> construct - is used (see below).</para> - - <para>Actually <command>hsc2hs</command> does not output the Haskell - file directly. It creates a C program that includes the headers, - gets automatically compiled and run. That program outputs the - Haskell code.</para> - - <para>In the following, “Haskell file” is the main - output (usually a <literal>.hs</literal> file), “compiled - Haskell file” is the Haskell file after - <command>ghc</command> has compiled it to C (i.e. a - <literal>.hc</literal> file), “C program” is the - program that outputs the Haskell file, “C file” is the - optionally generated C file, and “C header” is its - header file.</para> - - <sect2> - <title>command line syntax</title> - - <para><command>hsc2hs</command> takes input files as arguments, - and flags that modify its behavior:</para> - - <variablelist> - <varlistentry> - <term><literal>-o FILE</literal> or - <literal>--output=FILE</literal></term> - <listitem> - <para>Name of the Haskell file.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>-t FILE</literal> or - <literal>--template=FILE</literal></term> - <listitem> - <para>The template file (see below).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>-c PROG</literal> or - <literal>--cc=PROG</literal></term> - <listitem> - <para>The C compiler to use (default: - <command>gcc</command>)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>-l PROG</literal> or - <literal>--ld=PROG</literal></term> - <listitem> - <para>The linker to use (default: - <command>gcc</command>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>-C FLAG</literal> or - <literal>--cflag=FLAG</literal></term> - <listitem> - <para>An extra flag to pass to the C compiler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>-I DIR</literal></term> - <listitem> - <para>Passed to the C compiler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>-L FLAG</literal> or - <literal>--lflag=FLAG</literal></term> - <listitem> - <para>An extra flag to pass to the linker.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>-i FILE</literal> or - <literal>--include=FILE</literal></term> - <listitem> - <para>As if the appropriate <literal>#include</literal> - directive was placed in the source.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>-D NAME[=VALUE]</literal> or - <literal>--define=NAME[=VALUE]</literal></term> - <listitem> - <para>As if the appropriate <literal>#define</literal> - directive was placed in the source.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>--no-compile</literal></term> - <listitem> - <para>Stop after writing out the intermediate C program to disk. - The file name for the intermediate C program is the input file name - with <literal>.hsc</literal> replaced with <literal>_hsc_make.c</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>-k</literal> or - <literal>--keep-files</literal></term> - <listitem> - <para>Proceed as normal, but do not delete any intermediate files.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>-x</literal> or - <literal>--cross-compile</literal></term> - <listitem> - <para>Activate cross-compilation mode (see <xref linkend="hsc2hs_cross"/>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>--cross-safe</literal></term> - <listitem> - <para>Restrict the .hsc directives to those supported by the - <literal>--cross-compile</literal> mode (see <xref linkend="hsc2hs_cross"/>). - This should be useful if your <literal>.hsc</literal> files - must be safely cross-compiled and you wish to keep - non-cross-compilable constructs from creeping into them.</para> - </listitem> - </varlistentry> - - - <varlistentry> - <term><literal>-?</literal> or <literal>--help</literal></term> - <listitem> - <para>Display a summary of the available flags and exit successfully.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>-V</literal> or <literal>--version</literal></term> - <listitem> - <para>Output version information and exit successfully.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The input file should end with .hsc (it should be plain - Haskell source only; literate Haskell is not supported at the - moment). Output files by default get names with the - <literal>.hsc</literal> suffix replaced:</para> - - <informaltable> - <tgroup cols="2"> - <tbody> - <row> - <entry><literal>.hs</literal></entry> - <entry>Haskell file</entry> - </row> - <row> - <entry><literal>_hsc.h</literal></entry> - <entry>C header</entry> - </row> - <row> - <entry><literal>_hsc.c</literal></entry> - <entry>C file</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>The C program is compiled using the Haskell compiler. This - provides the include path to <filename>HsFFI.h</filename> which - is automatically included into the C program.</para> - - </sect2> - <sect2><title>Input syntax</title> - - <para>All special processing is triggered by - the <literal>#</literal> operator. To output - a literal <literal>#</literal>, write it twice: - <literal>##</literal>. Inside string literals and comments - <literal>#</literal> characters are not processed.</para> - - <para>A <literal>#</literal> is followed by optional - spaces and tabs, an alphanumeric keyword that describes - the kind of processing, and its arguments. Arguments look - like C expressions separated by commas (they are not - written inside parens). They extend up to the nearest - unmatched <literal>)</literal>, <literal>]</literal> or - <literal>}</literal>, or to the end of line if it occurs outside - any <literal>() [] {} '' "" /**/</literal> and is not preceded - by a backslash. Backslash-newline pairs are stripped.</para> - - <para>In addition <literal>#{stuff}</literal> is equivalent - to <literal>#stuff</literal> except that it's self-delimited - and thus needs not to be placed at the end of line or in some - brackets.</para> - - <para>Meanings of specific keywords:</para> - - <variablelist> - - <varlistentry> - <term><literal>#include <file.h></literal></term> - <term><literal>#include "file.h"</literal></term> - <listitem> - <para>The specified file gets included into the C program, - the compiled Haskell file, and the C header. - <literal><HsFFI.h></literal> is included - automatically.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>#define name</literal></term> - <term><literal>#define name value</literal></term> - <term><literal>#undef name</literal></term> - <listitem> - <para>Similar to <literal>#include</literal>. Note that - <literal>#includes</literal> and - <literal>#defines</literal> may be put in the same file - twice so they should not assume otherwise.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>#let name parameters = "definition"</literal></term> - <listitem> - <para>Defines a macro to be applied to the Haskell - source. Parameter names are comma-separated, not - inside parens. Such macro is invoked as other - <literal>#</literal>-constructs, starting with - <literal>#name</literal>. The definition will be - put in the C program inside parens as arguments of - <literal>printf</literal>. To refer to a parameter, - close the quote, put a parameter name and open the - quote again, to let C string literals concatenate. - Or use <literal>printf</literal>'s format directives. - Values of arguments must be given as strings, unless the - macro stringifies them itself using the C preprocessor's - <literal>#parameter</literal> syntax.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>#def C_definition</literal></term> - <listitem> - <para>The definition (of a function, variable, struct or - typedef) is written to the C file, and its prototype or - extern declaration to the C header. Inline functions are - handled correctly. struct definitions and typedefs are - written to the C program too. The - <literal>inline</literal>, <literal>struct</literal> or - <literal>typedef</literal> keyword must come just after - <literal>def</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>#if condition</literal></term> - <term><literal>#ifdef name</literal></term> - <term><literal>#ifndef name</literal></term> - <term><literal>#elif condition</literal></term> - <term><literal>#else</literal></term> - <term><literal>#endif</literal></term> - <term><literal>#error message</literal></term> - <term><literal>#warning message</literal></term> - <listitem> - <para>Conditional compilation directives are passed - unmodified to the C program, C file, and C header. Putting - them in the C program means that appropriate parts of the - Haskell file will be skipped.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>#const C_expression</literal></term> - <listitem> - <para>The expression must be convertible to - <literal>long</literal> or <literal>unsigned - long</literal>. Its value (literal or negated literal) - will be output.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>#const_str C_expression</literal></term> - <listitem> - <para>The expression must be convertible to const char - pointer. Its value (string literal) will be output.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>#type C_type</literal></term> - <listitem> - <para>A Haskell equivalent of the C numeric type will be - output. It will be one of - <literal>{Int,Word}{8,16,32,64}</literal>, - <literal>Float</literal>, <literal>Double</literal>, - <literal>LDouble</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>#peek struct_type, field</literal></term> - <listitem> - <para>A function that peeks a field of a C struct will be - output. It will have the type - <literal>Storable b => Ptr a -> IO b</literal>. - - The intention is that <literal>#peek</literal> and - <literal>#poke</literal> can be used for implementing the - operations of class <literal>Storable</literal> for a - given C struct (see the - <literal>Foreign.Storable</literal> module in the library - documentation).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>#poke struct_type, field</literal></term> - <listitem> - <para>Similarly for poke. It will have the type - <literal>Storable b => Ptr a -> b -> IO ()</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>#ptr struct_type, field</literal></term> - <listitem> - <para>Makes a pointer to a field struct. It will have the type - <literal>Ptr a -> Ptr b</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>#offset struct_type, field</literal></term> - <listitem> - <para>Computes the offset, in bytes, of - <literal>field</literal> in - <literal>struct_type</literal>. It will have type - <literal>Int</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>#size struct_type</literal></term> - <listitem> - <para>Computes the size, in bytes, of - <literal>struct_type</literal>. It will have type - <literal>Int</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>#enum type, constructor, value, value, ...</literal></term> - <listitem> - <para>A shortcut for multiple definitions which use - <literal>#const</literal>. Each <literal>value</literal> - is a name of a C integer constant, e.g. enumeration value. - The name will be translated to Haskell by making each - letter following an underscore uppercase, making all the rest - lowercase, and removing underscores. You can supply a different - translation by writing <literal>hs_name = c_value</literal> - instead of a <literal>value</literal>, in which case - <literal>c_value</literal> may be an arbitrary expression. - The <literal>hs_name</literal> will be defined as having the - specified <literal>type</literal>. Its definition is the specified - <literal>constructor</literal> (which in fact may be an expression - or be empty) applied to the appropriate integer value. You can - have multiple <literal>#enum</literal> definitions with the same - <literal>type</literal>; this construct does not emit the type - definition itself.</para> - </listitem> - </varlistentry> - </variablelist> - - </sect2> - - <sect2> - <title>Custom constructs</title> - - <para><literal>#const</literal>, <literal>#type</literal>, - <literal>#peek</literal>, <literal>#poke</literal> and - <literal>#ptr</literal> are not hardwired into the - <command>hsc2hs</command>, but are defined in a C template that is - included in the C program: <filename>template-hsc.h</filename>. - Custom constructs and templates can be used too. Any - <literal>#</literal>-construct with unknown key is expected to - be handled by a C template.</para> - - <para>A C template should define a macro or function with name - prefixed by <literal>hsc_</literal> that handles the construct - by emitting the expansion to stdout. See - <filename>template-hsc.h</filename> for examples.</para> - - <para>Such macros can also be defined directly in the - source. They are useful for making a <literal>#let</literal>-like - macro whose expansion uses other <literal>#let</literal> macros. - Plain <literal>#let</literal> prepends <literal>hsc_</literal> - to the macro name and wraps the definition in a - <literal>printf</literal> call.</para> - - </sect2> - - <sect2 id="hsc2hs_cross"> - <title>Cross-compilation</title> - - <para><command>hsc2hs</command> normally operates by creating, compiling, - and running a C program. That approach doesn't work when cross-compiling -- - in this case, the C compiler's generates code for the target machine, - not the host machine. For this situation, there's - a special mode <command>hsc2hs --cross-compile</command> which can generate - the .hs by extracting information from compilations only -- specifically, - whether or not compilation fails. - </para> - - <para>Only a subset of <literal>.hsc</literal> syntax is supported by - <literal>--cross-compile</literal>. The following are unsupported: - <itemizedlist> - <listitem><literal>#{const_str}</literal></listitem> - <listitem><literal>#{let}</literal></listitem> - <listitem><literal>#{def}</literal></listitem> - <listitem>Custom constructs</listitem> - </itemizedlist> - </para> - </sect2> - - </sect1> - -</chapter> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> diff --git a/docs/users_guide/win32-dlls.rst b/docs/users_guide/win32-dlls.rst new file mode 100644 index 0000000000..b1495d9503 --- /dev/null +++ b/docs/users_guide/win32-dlls.rst @@ -0,0 +1,388 @@ +.. _win32: + +Running GHC on Win32 systems +============================ + +.. _ghc-windows: + +Starting GHC on Windows platforms +--------------------------------- + +The installer that installs GHC on Win32 also sets up the file-suffix +associations for ".hs" and ".lhs" files so that double-clicking them +starts ``ghci``. + +Be aware of that ``ghc`` and ``ghci`` do require filenames containing +spaces to be escaped using quotes: + +:: + + c:\ghc\bin\ghci "c:\\Program Files\\Haskell\\Project.hs" + +If the quotes are left off in the above command, ``ghci`` will interpret +the filename as two, ``c:\\\\Program`` and +``Files\\\\Haskell\\\\Project.hs``. + +.. _ghci-windows: + +Running GHCi on Windows +----------------------- + +We recommend running GHCi in a standard Windows console: select the +``GHCi`` option from the start menu item added by the GHC installer, or +use ``Start->Run->cmd`` to get a Windows console and invoke ``ghci`` +from there (as long as it's in your ``PATH``). + +If you run GHCi in a Cygwin or MSYS shell, then the Control-C behaviour +is adversely affected. In one of these environments you should use the +``ghcii.sh`` script to start GHCi, otherwise when you hit Control-C +you'll be returned to the shell prompt but the GHCi process will still +be running. However, even using the ``ghcii.sh`` script, if you hit +Control-C then the GHCi process will be killed immediately, rather than +letting you interrupt a running program inside GHCi as it should. This +problem is caused by the fact that the Cygwin and MSYS shell +environments don't pass Control-C events to non-Cygwin child processes, +because in order to do that there needs to be a Windows console. + +There's an exception: you can use a Cygwin shell if the ``CYGWIN`` +environment variable does *not* contain ``tty``. In this mode, the +Cygwin shell behaves like a Windows console shell and console events are +propagated to child processes. Note that the ``CYGWIN`` environment +variable must be set *before* starting the Cygwin shell; changing it +afterwards has no effect on the shell. + +This problem doesn't just affect GHCi, it affects any GHC-compiled +program that wants to catch console events. See the +:base-ref:`GHC.ConsoleHandler <GHC-ConsoleHandler.html>` +module. + +.. _terminal-interaction: + +Interacting with the terminal +----------------------------- + +By default GHC builds applications that open a console window when they +start. If you want to build a GUI-only application, with no console +window, use the flag ``-optl-mwindows`` in the link step. + +.. warning:: + Windows GUI-only programs have no stdin, stdout or stderr so + using the ordinary Haskell input/output functions will cause your + program to fail with an IO exception, such as: + + :: + + Fail: <stdout>: hPutChar: failed (Bad file descriptor) + + However using Debug.Trace.trace is alright because it uses Windows + debugging output support rather than ``stderr``. + +For some reason, Mingw ships with the ``readline`` library, but not with +the ``readline`` headers. As a result, GHC (like Hugs) does not use +``readline`` for interactive input on Windows. You can get a close +simulation by using an emacs shell buffer! + +.. _library-differences: + +Differences in library behaviour +-------------------------------- + +Some of the standard Haskell libraries behave slightly differently on +Windows. + +- On Windows, the ``^Z`` character is interpreted as an end-of-file + character, so if you read a file containing this character the file + will appear to end just before it. To avoid this, use + ``IOExts.openFileEx`` to open a file in binary (untranslated) mode or + change an already opened file handle into binary mode using + ``IOExts.hSetBinaryMode``. The ``IOExts`` module is part of the + ``lang`` package. + +.. _ghci-cygwin: + +Using GHC (and other GHC-compiled executables) with Cygwin +---------------------------------------------------------- + +Background +~~~~~~~~~~ + +The Cygwin tools aim to provide a Unix-style API on top of the windows +libraries, to facilitate ports of Unix software to windows. To this end, +they introduce a Unix-style directory hierarchy under some root +directory (typically ``/`` is ``C:\cygwin\``). Moreover, everything +built against the Cygwin API (including the Cygwin tools and programs +compiled with Cygwin's GHC) will see ``/`` as the root of their file system, +happily pretending to work in a typical unix environment, and finding +things like ``/bin`` and ``/usr/include`` without ever explicitly +bothering with their actual location on the windows system (probably +``C:\cygwin\bin`` and ``C:\cygwin\usr\include``). + +The problem +~~~~~~~~~~~ + +GHC, by default, no longer depends on cygwin, but is a native Windows +program. It is built using mingw, and it uses mingw's GHC while +compiling your Haskell sources (even if you call it from cygwin's bash), +but what matters here is that - just like any other normal windows +program - neither GHC nor the executables it produces are aware of +Cygwin's pretended unix hierarchy. GHC will happily accept either ``/`` or +``\\`` as path separators, but it won't know where to find ``/home/joe/Main.hs`` +or ``/bin/bash`` or the like. This causes all kinds of fun when GHC is used from +within Cygwin's bash, or in make-sessions running under Cygwin. + +Things to do +~~~~~~~~~~~~ + +- Don't use absolute paths in ``make``, ``configure`` & co if there is any + chance that those might be passed to GHC (or to GHC-compiled + programs). Relative paths are fine because cygwin tools are happy + with them and GHC accepts ``/`` as path-separator. And relative paths + don't depend on where Cygwin's root directory is located, or on which + partition or network drive your source tree happens to reside, as + long as you ``cd`` there first. + +- If you have to use absolute paths (beware of the innocent-looking + ``ROOT=$(pwd)`` in makefile hierarchies or configure scripts), Cygwin + provides a tool called ``cygpath`` that can convert Cygwin's + Unix-style paths to their actual Windows-style counterparts. Many + Cygwin tools actually accept absolute Windows-style paths (remember, + though, that you either need to escape ``\\`` or convert ``\\`` to ``/``), + so you should be fine just using those everywhere. If you need to use + tools that do some kind of path-mangling that depends on unix-style + paths (one fun example is trying to interpret ``:`` as a separator in + path lists), you can still try to convert paths using ``cygpath`` + just before they are passed to GHC and friends. + +- If you don't have ``cygpath``, you probably don't have cygwin and + hence no problems with it... unless you want to write one build + process for several platforms. Again, relative paths are your friend, + but if you have to use absolute paths, and don't want to use + different tools on different platforms, you can simply write a short + Haskell program to print the current directory (thanks to George + Russell for this idea): compiled with GHC, this will give you the + view of the file system that GHC depends on (which will differ + depending on whether GHC is compiled with cygwin's gcc or mingw's gcc + or on a real Unix system..) - that little program can also deal with + escaping ``\\`` in paths. Apart from the banner and the startup time, + something like this would also do: + + :: + + $ echo "Directory.getCurrentDirectory >>= putStrLn . init . tail . show " | ghci + +.. _win32-dlls: + +Building and using Win32 DLLs +----------------------------- + +Dynamic link libraries, Win32 DLLs, Win32 On Win32 platforms, the +compiler is capable of both producing and using dynamic link libraries +(DLLs) containing ghc-compiled code. This section shows you how to make +use of this facility. + +There are two distinct ways in which DLLs can be used: + +- You can turn each Haskell package into a DLL, so that multiple + Haskell executables using the same packages can share the DLL files. + (As opposed to linking the libraries statically, which in effect + creates a new copy of the RTS and all libraries for each executable + produced.) + + That is the same as the dynamic linking on other platforms, and it is + described in :ref:`using-shared-libs`. + +- You can package up a complete Haskell program as a DLL, to be called + by some external (usually non-Haskell) program. This is usually used + to implement plugins and the like, and is described below. + +.. _win32-dlls-create: + +Creating a DLL +~~~~~~~~~~~~~~ + +Creating a Win32 DLL -shared Sealing up your Haskell library inside a +DLL is straightforward; compile up the object files that make up the +library, and then build the DLL by issuing a command of the form: + +:: + + ghc -shared -o foo.dll bar.o baz.o wibble.a -lfooble + +By feeding the ghc compiler driver the option ``-shared``, it will build +a DLL rather than produce an executable. The DLL will consist of all the +object files and archives given on the command line. + +A couple of things to notice: + +- By default, the entry points of all the object files will be exported + from the DLL when using ``-shared``. Should you want to constrain + this, you can specify the *module definition file* to use on the + command line as follows: + + :: + + ghc -shared -o .... MyDef.def + + See Microsoft documentation for details, but a module definition file + simply lists what entry points you want to export. Here's one that's + suitable when building a Haskell COM server DLL: + + :: + + EXPORTS + DllCanUnloadNow = DllCanUnloadNow@0 + DllGetClassObject = DllGetClassObject@12 + DllRegisterServer = DllRegisterServer@0 + DllUnregisterServer = DllUnregisterServer@0 + +- In addition to creating a DLL, the ``-shared`` option also creates an + import library. The import library name is derived from the name of + the DLL, as follows: + + :: + + DLL: HScool.dll ==> import lib: libHScool.dll.a + + The naming scheme may look a bit weird, but it has the purpose of + allowing the co-existence of import libraries with ordinary static + libraries (e.g., ``libHSfoo.a`` and ``libHSfoo.dll.a``. Additionally, + when the compiler driver is linking in non-static mode, it will + rewrite occurrence of ``-lHSfoo`` on the command line to + ``-lHSfoo.dll``. By doing this for you, switching from non-static to + static linking is simply a question of adding ``-static`` to your + command line. + +.. _win32-dlls-foreign: + +Making DLLs to be called from other languages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to create DLLs to be called from other +languages, such as Visual Basic or C++. This is a special case of +:ref:`ffi-library`; we'll deal with the DLL-specific issues that arise +below. Here's an example: + +Use foreign export declarations to export the Haskell functions you want +to call from the outside. For example: + +:: + + -- Adder.hs + {-# LANGUAGE ForeignFunctionInterface #-} + module Adder where + + adder :: Int -> Int -> IO Int -- gratuitous use of IO + adder x y = return (x+y) + + foreign export stdcall adder :: Int -> Int -> IO Int + +Add some helper code that starts up and shuts down the Haskell RTS: + +:: + + // StartEnd.c + #include <Rts.h> + + void HsStart() + { + int argc = 1; + char* argv[] = {"ghcDll", NULL}; // argv must end with NULL + + // Initialize Haskell runtime + char** args = argv; + hs_init(&argc, &args); + } + + void HsEnd() + { + hs_exit(); + } + +Here, ``Adder`` is the name of the root module in the module tree (as +mentioned above, there must be a single root module, and hence a single +module tree in the DLL). Compile everything up: + +:: + + ghc -c Adder.hs + ghc -c StartEnd.c + ghc -shared -o Adder.dll Adder.o Adder_stub.o StartEnd.o + +Now the file ``Adder.dll`` can be used from other programming languages. +Before calling any functions in Adder it is necessary to call +``HsStart``, and at the very end call ``HsEnd``. + +.. warning:: + It may appear tempting to use ``DllMain`` to call + ``hs_init``/``hs_exit``, but this won't work (particularly if you + compile with ``-threaded``). There are severe restrictions on which + actions can be performed during ``DllMain``, and ``hs_init`` violates + these restrictions, which can lead to your DLL freezing during startup + (see :ghc-ticket:`3605`). + +.. _win32-dlls-vba: + +Using from VBA +^^^^^^^^^^^^^^ + +An example of using ``Adder.dll`` from VBA is: + +:: + + Private Declare Function Adder Lib "Adder.dll" Alias "adder@8" _ + (ByVal x As Long, ByVal y As Long) As Long + + Private Declare Sub HsStart Lib "Adder.dll" () + Private Declare Sub HsEnd Lib "Adder.dll" () + + Private Sub Document_Close() + HsEnd + End Sub + + Private Sub Document_Open() + HsStart + End Sub + + Public Sub Test() + MsgBox "12 + 5 = " & Adder(12, 5) + End Sub + +This example uses the ``Document_Open``/``Close`` functions of Microsoft +Word, but provided ``HsStart`` is called before the first function, and +``HsEnd`` after the last, then it will work fine. + +.. _win32-dlls-c++: + +Using from C++ +^^^^^^^^^^^^^^ + +An example of using ``Adder.dll`` from C++ is: + +:: + + // Tester.cpp + #include "HsFFI.h" + #include "Adder_stub.h" + #include <stdio.h> + + extern "C" { + void HsStart(); + void HsEnd(); + } + + int main() + { + HsStart(); + // can now safely call functions from the DLL + printf("12 + 5 = %i\n", adder(12,5)) ; + HsEnd(); + return 0; + } + +This can be compiled and run with: + +:: + + $ ghc -o tester Tester.cpp Adder.dll.a + $ tester + 12 + 5 = 17 diff --git a/docs/users_guide/win32-dlls.xml b/docs/users_guide/win32-dlls.xml deleted file mode 100644 index 1168871c10..0000000000 --- a/docs/users_guide/win32-dlls.xml +++ /dev/null @@ -1,575 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<chapter id="win32"> -<title>Running GHC on Win32 systems</title> - -<sect1 id="ghc-windows"> -<title> -Starting GHC on Windows platforms</title> - -<para> -The installer that installs GHC on Win32 also sets up the file-suffix associations -for ".hs" and ".lhs" files so that double-clicking them starts <command>ghci</command>. -</para> -<para> -Be aware of that <command>ghc</command> and <command>ghci</command> do -require filenames containing spaces to be escaped using quotes: -<programlisting> - c:\ghc\bin\ghci "c:\\Program Files\\Haskell\\Project.hs" -</programlisting> -If the quotes are left off in the above command, <command>ghci</command> will -interpret the filename as two, "c:\\Program" and "Files\\Haskell\\Project.hs". -</para> - -<!-- not clear whether there are current editions of Win32 OSes that - doesn't do this by default. - -<para> Solution: don't use "Open With...", avoid spaces in file names, -or fiddle with the appropriate registry setting: -<programlisting> - HKEY_CLASSES_ROOT\Unknown\shell\openas\command -</programlisting> -Notice how the "%1" argument is quoted (or not). -</para> -<para> This problem doesn't occur when double-clicking. -</para> ---> - -</sect1> - -<sect1 id="ghci-windows"> -<title>Running GHCi on Windows</title> - - <para>We recommend running GHCi in a standard Windows console: - select the <literal>GHCi</literal> option from the start menu item - added by the GHC installer, or use - <literal>Start->Run->cmd</literal> to get a Windows console and - invoke <literal>ghci</literal> from there (as long as it's in your - <literal>PATH</literal>).</para> - - <para>If you run GHCi in a Cygwin or MSYS shell, then the Control-C - behaviour is adversely affected. In one of these environments you - should use the <literal>ghcii.sh</literal> script to start GHCi, - otherwise when you hit Control-C you'll be returned to the shell - prompt but the GHCi process will still be running. However, even - using the <literal>ghcii.sh</literal> script, if you hit Control-C - then the GHCi process will be killed immediately, rather than - letting you interrupt a running program inside GHCi as it should. - This problem is caused by the fact that the Cygwin and MSYS shell - environments don't pass Control-C events to non-Cygwin child - processes, because in order to do that there needs to be a Windows - console.</para> - - <para>There's an exception: you can use a Cygwin shell if the - <literal>CYGWIN</literal> environment variable does - <emphasis>not</emphasis> contain <literal>tty</literal>. In this - mode, the Cygwin shell behaves like a Windows console shell and - console events are propagated to child processes. Note that the - <literal>CYGWIN</literal> environment variable must be set - <emphasis>before</emphasis> starting the Cygwin shell; changing it - afterwards has no effect on the shell.</para> - - <para>This problem doesn't just affect GHCi, it affects any - GHC-compiled program that wants to catch console events. See the - <ulink - url="&libraryBaseLocation;/GHC-ConsoleHandler.html">GHC.ConsoleHandler</ulink> - module.</para> -</sect1> - -<sect1 id="terminal-interaction"> -<title> -Interacting with the terminal</title> - -<para>By default GHC builds applications that open a console window when they start. -If you want to build a GUI-only application, with no console window, use the flag -<literal>-optl-mwindows</literal> in the link step. -</para> - -<para> <emphasis>Warning:</emphasis> Windows GUI-only programs have no - stdin, stdout or stderr so using the ordinary Haskell - input/output functions will cause your program to fail with an - IO exception, such as: -<screen> - Fail: <stdout>: hPutChar: failed (Bad file descriptor) -</screen> - However using Debug.Trace.trace is alright because it uses - Windows debugging output support rather than stderr.</para> - -<para>For some reason, Mingw ships with the <literal>readline</literal> library, -but not with the <literal>readline</literal> headers. As a result, GHC (like Hugs) does not -use <literal>readline</literal> for interactive input on Windows. -You can get a close simulation by using an emacs shell buffer! -</para> - -</sect1> - -<sect1 id="library-differences"> -<title> -Differences in library behaviour </title> - -<para> -Some of the standard Haskell libraries behave slightly differently on Windows. - -<itemizedlist> -<listitem> <para> -On Windows, the '<literal>^Z</literal>' character is interpreted as an -end-of-file character, so if you read a file containing this character -the file will appear to end just before it. To avoid this, -use <literal>IOExts.openFileEx</literal> to open a file in binary -(untranslated) mode or change an already opened file handle into -binary mode using <literal>IOExts.hSetBinaryMode</literal>. The -<literal>IOExts</literal> module is part of the -<literal>lang</literal> package. -</para> -</listitem> -</itemizedlist> -</para> -</sect1> - -<sect1 id="ghci-cygwin"> -<title> -Using GHC (and other GHC-compiled executables) with cygwin</title> - -<sect2> -<title>Background</title> <para>The cygwin tools aim to provide a -unix-style API on top of the windows libraries, to facilitate ports of -unix software to windows. To this end, they introduce a unix-style -directory hierarchy under some root directory (typically -<filename>/</filename> is <filename>C:\cygwin\</filename>). Moreover, -everything built against the cygwin API (including the cygwin tools -and programs compiled with cygwin's ghc) will see / as the root of -their file system, happily pretending to work in a typical unix -environment, and finding things like <filename>/bin</filename> and <filename>/usr/include</filename> without -ever explicitly bothering with their actual location on the windows -system (probably <filename>C:\cygwin\bin</filename> and <filename>C:\cygwin\usr\include</filename>). -</para> -</sect2> - -<sect2><title>The problem</title> -<para>GHC, by default, no longer depends on cygwin, but is a native -windows program. It is built using mingw, and it uses mingw's ghc -while compiling your Haskell sources (even if you call it from -cygwin's bash), but what matters here is that - just like any other -normal windows program - neither GHC nor the executables it produces -are aware of cygwin's pretended unix hierarchy. GHC will happily -accept either '/' or '\' as path separators, but it won't know where -to find <filename>/home/joe/Main.hs</filename> or <filename>/bin/bash</filename> -or the like. This causes all -kinds of fun when GHC is used from within cygwin's bash, or in -make-sessions running under cygwin. -</para> -</sect2> - -<sect2><title>Things to do</title> -<itemizedlist> -<listitem> -<para> Don't use absolute paths in make, configure & co if there is any chance - that those might be passed to GHC (or to GHC-compiled programs). Relative - paths are fine because cygwin tools are happy with them and GHC accepts - '/' as path-separator. And relative paths don't depend on where cygwin's - root directory is located, or on which partition or network drive your source - tree happens to reside, as long as you 'cd' there first. -</para></listitem> - -<listitem> -<para> If you have to use absolute paths (beware of the innocent-looking - <literal>ROOT=`pwd`</literal> in makefile hierarchies or configure scripts), cygwin provides - a tool called <command>cygpath</command> that can convert cygwin's unix-style paths to their - actual windows-style counterparts. Many cygwin tools actually accept - absolute windows-style paths (remember, though, that you either need - to escape '\' or convert '\' to '/'), so you should be fine just using those - everywhere. If you need to use tools that do some kind of path-mangling - that depends on unix-style paths (one fun example is trying to interpret ':' - as a separator in path lists..), you can still try to convert paths using - <command>cygpath</command> just before they are passed to GHC and friends. -</para></listitem> - -<listitem> -<para> If you don't have <command>cygpath</command>, you probably don't have cygwin and hence - no problems with it... unless you want to write one build process for several - platforms. Again, relative paths are your friend, but if you have to use - absolute paths, and don't want to use different tools on different platforms, - you can simply write a short Haskell program to print the current directory - (thanks to George Russell for this idea): compiled with GHC, this will give - you the view of the file system that GHC depends on (which will differ - depending on whether GHC is compiled with cygwin's gcc or mingw's - gcc or on a real unix system..) - that little program can also deal with - escaping '\' in paths. Apart from the banner and the startup time, - something like this would also do: -<programlisting> - $ echo "Directory.getCurrentDirectory >>= putStrLn . init . tail . show " | ghci -</programlisting> -</para></listitem> -</itemizedlist> -</sect2> -</sect1> - - -<sect1 id="win32-dlls"> -<title>Building and using Win32 DLLs -</title> - -<para> -<indexterm><primary>Dynamic link libraries, Win32</primary></indexterm> -<indexterm><primary>DLLs, Win32</primary></indexterm> -On Win32 platforms, the compiler is capable of both producing and using -dynamic link libraries (DLLs) containing ghc-compiled code. This -section shows you how to make use of this facility. -</para> - -<para> -There are two distinct ways in which DLLs can be used: -<itemizedlist> - <listitem> - <para> - You can turn each Haskell package into a DLL, so that multiple - Haskell executables using the same packages can share the DLL files. - (As opposed to linking the libraries statically, which in effect - creates a new copy of the RTS and all libraries for each executable - produced.) - </para> - <para> - That is the same as the dynamic linking on other platforms, and it - is described in <xref linkend="using-shared-libs"/>. - </para> - </listitem> - <listitem> - <para> - You can package up a complete Haskell program as a DLL, to be called - by some external (usually non-Haskell) program. This is usually used - to implement plugins and the like, and is described below. - </para> - </listitem> -</itemizedlist> -</para> - -<!-- -<para> -Until recently, <command>strip</command> didn't work reliably on DLLs, so you -should test your version with care, or make sure you have the latest -binutils. Unfortunately, we don't know exactly which version of binutils -cured the problem (it was supposedly fixed some years ago). -</para> - - -<sect2 id="win32-dlls-link"> -<title>Linking with DLLs</title> - -<para> -The default on Win32 platforms is to link applications in such a way -that the executables will use the Prelude and system libraries DLLs, -rather than contain (large chunks of) them. This is transparent at the -command-line, so -</para> - -<para> -<screen> -sh$ cat main.hs -module Main where -main = putStrLn "hello, world!" -sh$ ghc -o main main.hs -ghc: module version changed to 1; reason: no old .hi file -sh$ strip main.exe -sh$ ls -l main.exe --rwxr-xr-x 1 544 everyone 4608 May 3 17:11 main.exe* -sh$ ./main -hello, world! -sh$ -</screen> -</para> - -<para> -will give you a binary as before, but the <filename>main.exe</filename> -generated will use the Prelude and RTS DLLs instead of linking them in -statically. -</para> - -<para> -4K for a <literal>"hello, world"</literal> application—not bad, huh? :-) -</para> - -</sect2> - -<sect2 id="win32-dlls-linking-static"> -<title>Not linking with DLLs -<indexterm><primary>-static option (Win32)</primary></indexterm></title> - -<para> -If you want to build an executable that doesn't depend on any -ghc-compiled DLLs, use the <option>-static</option> option to link in -the code statically. -</para> - -<para> -Notice that you cannot mix code that has been compiled with -<option>-static</option> and not, so you have to use the <option>-static</option> -option on all the Haskell modules that make up your application. -</para> - -</sect2> ---> - -<sect2 id="win32-dlls-create"> -<title>Creating a DLL</title> - -<para> -<indexterm><primary>Creating a Win32 DLL</primary></indexterm> -<indexterm><primary>-shared</primary></indexterm> -Sealing up your Haskell library inside a DLL is straightforward; -compile up the object files that make up the library, and then build -the DLL by issuing a command of the form: -</para> - -<para> -<screen> -ghc -shared -o foo.dll bar.o baz.o wibble.a -lfooble -</screen> -</para> - -<para> -By feeding the ghc compiler driver the option <option>-shared</option>, it -will build a DLL rather than produce an executable. The DLL will -consist of all the object files and archives given on the command -line. -</para> - -<!-- -<para> -To create a `static' DLL, i.e. one that does not depend on the GHC DLLs, -use the <option>-static</option> when compiling up your Haskell code and -building the DLL. -</para> ---> - -<para> -A couple of things to notice: -</para> - -<para> - -<itemizedlist> -<!-- -<listitem> -<para> -Since DLLs correspond to packages (see <xref linkend="packages"/>) you need -to use <option>-package-name dll-name</option> when compiling modules that -belong to a DLL if you're going to call them from Haskell. Otherwise, Haskell -code that calls entry points in that DLL will do so incorrectly, and crash. -For similar reasons, you can only compile a single module tree into a DLL, -as <function>startupHaskell</function> needs to be able to call its -initialisation function, and only takes one such argument (see <xref -linkend="win32-dlls-foreign"/>). Hence the modules -you compile into a DLL must have a common root. -</para> -</listitem> ---> - -<listitem> -<para> -By default, the entry points of all the object files will be exported from -the DLL when using <option>-shared</option>. Should you want to constrain -this, you can specify the <emphasis>module definition file</emphasis> to use -on the command line as follows: - -<screen> -ghc -shared -o .... MyDef.def -</screen> - -See Microsoft documentation for details, but a module definition file -simply lists what entry points you want to export. Here's one that's -suitable when building a Haskell COM server DLL: - -<programlisting> -EXPORTS - DllCanUnloadNow = DllCanUnloadNow@0 - DllGetClassObject = DllGetClassObject@12 - DllRegisterServer = DllRegisterServer@0 - DllUnregisterServer = DllUnregisterServer@0 -</programlisting> -</para> -</listitem> - -<listitem> -<para> -In addition to creating a DLL, the <option>-shared</option> option also -creates an import library. The import library name is derived from the -name of the DLL, as follows: - -<programlisting> -DLL: HScool.dll ==> import lib: libHScool.dll.a -</programlisting> - -The naming scheme may look a bit weird, but it has the purpose of allowing -the co-existence of import libraries with ordinary static libraries (e.g., -<filename>libHSfoo.a</filename> and -<filename>libHSfoo.dll.a</filename>. - -Additionally, when the compiler driver is linking in non-static mode, it -will rewrite occurrence of <option>-lHSfoo</option> on the command line to -<option>-lHSfoo.dll</option>. By doing this for you, switching from -non-static to static linking is simply a question of adding -<option>-static</option> to your command line. - -</para> -</listitem> -</itemizedlist> -</para> - -</sect2> - - -<sect2 id="win32-dlls-foreign"> -<title>Making DLLs to be called from other languages</title> - -<para> - This section describes how to create DLLs to be called from other languages, - such as Visual Basic or C++. This is a special case of - <xref linkend="ffi-library" />; we'll deal with the DLL-specific issues that - arise below. Here's an example: -</para> -<para> - Use foreign export declarations to export the Haskell functions you want to - call from the outside. For example: -</para> -<programlisting> --- Adder.hs -{-# LANGUAGE ForeignFunctionInterface #-} -module Adder where - -adder :: Int -> Int -> IO Int -- gratuitous use of IO -adder x y = return (x+y) - -foreign export stdcall adder :: Int -> Int -> IO Int -</programlisting> -<para> - Add some helper code that starts up and shuts down the Haskell RTS: -</para> -<programlisting> -// StartEnd.c -#include <Rts.h> - -void HsStart() -{ - int argc = 1; - char* argv[] = {"ghcDll", NULL}; // argv must end with NULL - - // Initialize Haskell runtime - char** args = argv; - hs_init(&argc, &args); -} - -void HsEnd() -{ - hs_exit(); -} -</programlisting> -<para> - Here, <literal>Adder</literal> is the name of the root module in the module - tree (as mentioned above, there must be a single root module, and hence a - single module tree in the DLL). Compile everything up: -</para> -<screen> -ghc -c Adder.hs -ghc -c StartEnd.c -ghc -shared -o Adder.dll Adder.o Adder_stub.o StartEnd.o -</screen> -<para> - Now the file <filename>Adder.dll</filename> can be used from other - programming languages. Before calling any functions in Adder it is necessary - to call <literal>HsStart</literal>, and at the very end call - <literal>HsEnd</literal>. -</para> -<para> - <emphasis>Warning:</emphasis> It may appear tempting to use - <literal>DllMain</literal> to call - <literal>hs_init</literal>/<literal>hs_exit</literal>, but this won't work - (particularly if you compile with <literal>-threaded</literal>). There are - severe restrictions on which actions can be performed during - <literal>DllMain</literal>, and <literal>hs_init</literal> violates these - restrictions, which can lead to your dll freezing during startup (see - <ulink url="http://ghc.haskell.org/trac/ghc/ticket/3605">bug - #3605</ulink>). -</para> - -<sect3 id="win32-dlls-vba"> -<title>Using from VBA</title> - -<para> - An example of using <filename>Adder.dll</filename> from VBA is: -</para> -<programlisting> -Private Declare Function Adder Lib "Adder.dll" Alias "adder@8" _ - (ByVal x As Long, ByVal y As Long) As Long - -Private Declare Sub HsStart Lib "Adder.dll" () -Private Declare Sub HsEnd Lib "Adder.dll" () - -Private Sub Document_Close() -HsEnd -End Sub - -Private Sub Document_Open() -HsStart -End Sub - -Public Sub Test() -MsgBox "12 + 5 = " & Adder(12, 5) -End Sub -</programlisting> -<para> - This example uses the - <literal>Document_Open</literal>/<literal>Close</literal> functions of - Microsoft Word, but provided <literal>HsStart</literal> is called before the - first function, and <literal>HsEnd</literal> after the last, then it will - work fine. -</para> -</sect3> - -<sect3 id="win32-dlls-c++"> -<title>Using from C++</title> - -<para> - An example of using <filename>Adder.dll</filename> from C++ is: -</para> - -<programlisting> -// Tester.cpp -#include "HsFFI.h" -#include "Adder_stub.h" -#include <stdio.h> - -extern "C" { - void HsStart(); - void HsEnd(); -} - -int main() -{ - HsStart(); - // can now safely call functions from the DLL - printf("12 + 5 = %i\n", adder(12,5)) ; - HsEnd(); - return 0; -} -</programlisting> -<para> - This can be compiled and run with: -</para> -<screen> -$ ghc -o tester Tester.cpp Adder.dll.a -$ tester -12 + 5 = 17 -</screen> - -</sect3> - -</sect2> - -</sect1> -</chapter> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> @@ -14,8 +14,6 @@ # # * remove old Makefiles, add new stubs for building in subdirs # * docs/Makefile -# * docs/docbook-cheat-sheet/Makefile -# * docs/man/Makefile # * docs/storage-mgmt/Makefile # * docs/vh/Makefile # * rts/dotnet/Makefile @@ -170,23 +168,18 @@ $(error p is not in $$(GhcLibWays), and $$(GhcProfiled) is YES) endif endif -ifeq "$(BUILD_DOCBOOK_HTML)" "YES" -ifeq "$(XSLTPROC)" "" -$(error BUILD_DOCBOOK_HTML=YES, but `xsltproc` was not found. \ - Install `xsltproc`, then rerun `./configure`. \ - See https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation) -endif -ifeq "$(HAVE_DOCBOOK_XSL)" "NO" -$(error BUILD_DOCBOOK_HTML=YES, but DocBook XSL stylesheets were not found. \ - Install `docbook-xsl`, then rerun `./configure`. \ +ifeq "$(BUILD_SPHINX_HTML)" "YES" +ifeq "$(SPHINXBUILD)" "" +$(error BUILD_SPHINX_HTML=YES, but `sphinx-build` was not found. \ + Install `sphinx-build`, then rerun `./configure`. \ See https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation) endif endif -ifneq "$(BUILD_DOCBOOK_PS) $(BUILD_DOCBOOK_PDF)" "NO NO" -ifeq "$(DBLATEX)" "" -$(error BUILD_DOCBOOK_PS or BUILD_DOCBOOK_PDF=YES, but `dblatex` was not found. \ - Install `dblatex`, then rerun `./configure`. \ +ifeq "$(BUILD_SPHINX_PDF)" "YES" +ifeq "$(XELATEX)" "" +$(error BUILD_SPHINX_PDF=YES, but `xelatex` was not found. \ + Install `xelatex`, then rerun `./configure`. \ See https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation) endif endif @@ -347,7 +340,7 @@ include rules/manual-package-config.mk # ----------------------------------------------------------------------------- # Docs -include rules/docbook.mk +include rules/sphinx.mk # ----------------------------------------------------------------------------- # Making bindists and sdists @@ -666,7 +659,6 @@ BUILD_DIRS += utils/runghc BUILD_DIRS += ghc BUILD_DIRS += utils/mkUserGuidePart BUILD_DIRS += docs/users_guide -BUILD_DIRS += docs/man BUILD_DIRS += utils/count_lines BUILD_DIRS += utils/compare_sizes @@ -689,7 +681,7 @@ ifeq "$(HADDOCK_DOCS)" "NO" BUILD_DIRS := $(filter-out utils/haddock,$(BUILD_DIRS)) BUILD_DIRS := $(filter-out utils/haddock/doc,$(BUILD_DIRS)) endif -ifeq "$(BUILD_DOCBOOK_HTML) $(BUILD_DOCBOOK_PS) $(BUILD_DOCBOOK_PDF)" "NO NO NO" +ifeq "$(BUILD_SPHINX_HTML) $(BUILD_SPHINX_PDF)" "NO NO NO" # Don't to build this little utility if we're not building the User's Guide. BUILD_DIRS := $(filter-out utils/mkUserGuidePart,$(BUILD_DIRS)) endif @@ -927,7 +919,12 @@ endif ifneq "$(INSTALL_HTML_DOC_DIRS)" "" for i in $(INSTALL_HTML_DOC_DIRS); do \ $(INSTALL_DIR) "$(DESTDIR)$(docdir)/html/`basename $$i`"; \ - $(INSTALL_DOC) $(INSTALL_OPTS) $$i/* "$(DESTDIR)$(docdir)/html/`basename $$i`"; \ + for f in $$i/*; do \ +# We filter out the directories so install doesn't choke on them \ + if test -f $$f; then \ + $(INSTALL_DOC) $(INSTALL_OPTS) "$$f" "$(DESTDIR)$(docdir)/html/`basename $$i`"; \ + fi \ + done \ done endif @@ -1052,9 +1049,8 @@ unix-binary-dist-prep: "$(MKDIRHIER)" $(BIN_DIST_PREP_DIR) set -e; for i in packages LICENSE compiler ghc rts libraries utils docs libffi includes driver mk rules Makefile aclocal.m4 config.sub config.guess install-sh settings.in ghc.mk inplace distrib/configure.ac distrib/README distrib/INSTALL; do ln -s ../../$$i $(BIN_DIST_PREP_DIR)/; done echo "HADDOCK_DOCS = $(HADDOCK_DOCS)" >> $(BIN_DIST_MK) - echo "BUILD_DOCBOOK_HTML = $(BUILD_DOCBOOK_HTML)" >> $(BIN_DIST_MK) - echo "BUILD_DOCBOOK_PS = $(BUILD_DOCBOOK_PS)" >> $(BIN_DIST_MK) - echo "BUILD_DOCBOOK_PDF = $(BUILD_DOCBOOK_PDF)" >> $(BIN_DIST_MK) + echo "BUILD_SPHINX_HTML = $(BUILD_SPHINX_HTML)" >> $(BIN_DIST_MK) + echo "BUILD_SPHINX_PDF = $(BUILD_SPHINX_PDF)" >> $(BIN_DIST_MK) echo "BUILD_MAN = $(BUILD_MAN)" >> $(BIN_DIST_MK) echo "override ghc-cabal_INPLACE = utils/ghc-cabal/dist-install/build/tmp/ghc-cabal-bindist" >> $(BIN_DIST_MK) echo "UseSystemLibFFI = $(UseSystemLibFFI)" >> $(BIN_DIST_MK) @@ -1340,6 +1336,7 @@ distclean : clean $(call removeFiles,settings) $(call removeFiles,docs/users_guide/ug-book.xml) $(call removeFiles,docs/users_guide/ug-ent.xml) + $(call removeFiles,docs/users_guide/ghc_config.py) $(call removeFiles,docs/index.html) $(call removeFiles,libraries/prologue.txt) $(call removeFiles,distrib/configure.ac) diff --git a/mk/config.mk.in b/mk/config.mk.in index 1b46ed73f7..a2ca97eafd 100644 --- a/mk/config.mk.in +++ b/mk/config.mk.in @@ -755,21 +755,14 @@ HSCOLOUR_CMD = @HSCOLOUR@ TIME_CMD = @TimeCmd@ #----------------------------------------------------------------------------- -# DocBook XML stuff - -BUILD_DOCBOOK_HTML = @BUILD_DOCBOOK_HTML@ -BUILD_DOCBOOK_PS = @BUILD_DOCBOOK_PS@ -BUILD_DOCBOOK_PDF = @BUILD_DOCBOOK_PDF@ -DBLATEX = @DblatexCmd@ -# filename.as.url=0 is needed with dblatex 0.3.4 (#7486) -DBLATEX_OPTS = -P 'filename.as.url=0' -P 'latex.unicode.use=1' -XSLTPROC = @XsltprocCmd@ -XMLLINT = @XmllintCmd@ -HAVE_DOCBOOK_XSL = @HAVE_DOCBOOK_XSL@ -XSLTPROC_HTML_STYLESHEET = http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl -XSLTPROC_LABEL_OPTS = --stringparam toc.section.depth 3 \ - --stringparam section.autolabel 1 \ - --stringparam section.label.includes.component.label 1 +# Sphinx stuff + +SPHINXBUILD = @SPHINXBUILD@ +BUILD_MAN = @BUILD_MAN@ +BUILD_SPHINX_HTML = @BUILD_SPHINX_HTML@ +BUILD_SPHINX_PDF = @BUILD_SPHINX_PDF@ +SPHINXOPTS = -D latex_paper_size=letter +XELATEX = @XELATEX@ #----------------------------------------------------------------------------- # FPtools support software diff --git a/mk/flavours/bench-cross.mk b/mk/flavours/bench-cross.mk index 496d38acc7..0dea042e51 100644 --- a/mk/flavours/bench-cross.mk +++ b/mk/flavours/bench-cross.mk @@ -5,9 +5,9 @@ GhcLibHcOpts = -O2 -fllvm BUILD_PROF_LIBS = NO SplitObjs = NO HADDOCK_DOCS = NO -BUILD_DOCBOOK_HTML = NO -BUILD_DOCBOOK_PS = NO -BUILD_DOCBOOK_PDF = NO +BUILD_SPHINX_HTML = NO +BUILD_SPHINX_PS = NO +BUILD_SPHINX_PDF = NO INTEGER_LIBRARY = integer-simple Stage1Only = YES diff --git a/mk/flavours/bench-llvm.mk b/mk/flavours/bench-llvm.mk index 816d7c7b0d..8a73f551c0 100644 --- a/mk/flavours/bench-llvm.mk +++ b/mk/flavours/bench-llvm.mk @@ -5,6 +5,6 @@ GhcLibHcOpts = -O2 BUILD_PROF_LIBS = NO SplitObjs = NO HADDOCK_DOCS = NO -BUILD_DOCBOOK_HTML = NO -BUILD_DOCBOOK_PS = NO -BUILD_DOCBOOK_PDF = NO +BUILD_SPHINX_HTML = NO +BUILD_SPHINX_PS = NO +BUILD_SPHINX_PDF = NO diff --git a/mk/flavours/bench.mk b/mk/flavours/bench.mk index ea4b18e3d5..edf73f4270 100644 --- a/mk/flavours/bench.mk +++ b/mk/flavours/bench.mk @@ -5,6 +5,6 @@ GhcLibHcOpts = -O2 BUILD_PROF_LIBS = NO SplitObjs = NO HADDOCK_DOCS = NO -BUILD_DOCBOOK_HTML = NO -BUILD_DOCBOOK_PS = NO -BUILD_DOCBOOK_PDF = NO +BUILD_SPHINX_HTML = NO +BUILD_SPHINX_PS = NO +BUILD_SPHINX_PDF = NO diff --git a/mk/flavours/devel1.mk b/mk/flavours/devel1.mk index b06b64f72d..6b69adf8f9 100644 --- a/mk/flavours/devel1.mk +++ b/mk/flavours/devel1.mk @@ -5,8 +5,8 @@ GhcLibHcOpts = -O -dcore-lint BUILD_PROF_LIBS = NO SplitObjs = NO HADDOCK_DOCS = NO -BUILD_DOCBOOK_HTML = NO -BUILD_DOCBOOK_PS = NO -BUILD_DOCBOOK_PDF = NO +BUILD_SPHINX_HTML = NO +BUILD_SPHINX_PS = NO +BUILD_SPHINX_PDF = NO LAX_DEPENDENCIES = YES diff --git a/mk/flavours/devel2.mk b/mk/flavours/devel2.mk index 156522687d..c7998229cf 100644 --- a/mk/flavours/devel2.mk +++ b/mk/flavours/devel2.mk @@ -5,8 +5,8 @@ GhcLibHcOpts = -O -dcore-lint BUILD_PROF_LIBS = NO SplitObjs = NO HADDOCK_DOCS = NO -BUILD_DOCBOOK_HTML = NO -BUILD_DOCBOOK_PS = NO -BUILD_DOCBOOK_PDF = NO +BUILD_SPHINX_HTML = NO +BUILD_SPHINX_PS = NO +BUILD_SPHINX_PDF = NO LAX_DEPENDENCIES = YES diff --git a/mk/flavours/perf-cross.mk b/mk/flavours/perf-cross.mk index 0dd9c33cfe..4fa8417494 100644 --- a/mk/flavours/perf-cross.mk +++ b/mk/flavours/perf-cross.mk @@ -5,9 +5,9 @@ GhcLibHcOpts = -O2 -fllvm BUILD_PROF_LIBS = YES #SplitObjs HADDOCK_DOCS = NO -BUILD_DOCBOOK_HTML = NO -BUILD_DOCBOOK_PS = NO -BUILD_DOCBOOK_PDF = NO +BUILD_SPHINX_HTML = NO +BUILD_SPHINX_PS = NO +BUILD_SPHINX_PDF = NO INTEGER_LIBRARY = integer-simple Stage1Only = YES diff --git a/mk/flavours/perf-llvm.mk b/mk/flavours/perf-llvm.mk index c49849fd36..4a93d6b6bc 100644 --- a/mk/flavours/perf-llvm.mk +++ b/mk/flavours/perf-llvm.mk @@ -5,6 +5,6 @@ GhcLibHcOpts = -O2 BUILD_PROF_LIBS = YES #SplitObjs #HADDOCK_DOCS -#BUILD_DOCBOOK_HTML -#BUILD_DOCBOOK_PS -#BUILD_DOCBOOK_PDF +#BUILD_SPHINX_HTML +#BUILD_SPHINX_PS +#BUILD_SPHINX_PDF diff --git a/mk/flavours/perf.mk b/mk/flavours/perf.mk index d68f2f9102..c94b860af1 100644 --- a/mk/flavours/perf.mk +++ b/mk/flavours/perf.mk @@ -5,6 +5,6 @@ GhcLibHcOpts = -O2 BUILD_PROF_LIBS = YES #SplitObjs #HADDOCK_DOCS -#BUILD_DOCBOOK_HTML -#BUILD_DOCBOOK_PS -#BUILD_DOCBOOK_PDF +#BUILD_SPHINX_HTML +#BUILD_SPHINX_PS +#BUILD_SPHINX_PDF diff --git a/mk/flavours/prof.mk b/mk/flavours/prof.mk index 553cb120f7..c751332743 100644 --- a/mk/flavours/prof.mk +++ b/mk/flavours/prof.mk @@ -5,8 +5,8 @@ GhcLibHcOpts = -O BUILD_PROF_LIBS = YES SplitObjs = NO HADDOCK_DOCS = NO -BUILD_DOCBOOK_HTML = NO -BUILD_DOCBOOK_PS = NO -BUILD_DOCBOOK_PDF = NO +BUILD_SPHINX_HTML = NO +BUILD_SPHINX_PS = NO +BUILD_SPHINX_PDF = NO GhcProfiled = YES diff --git a/mk/flavours/quick-cross.mk b/mk/flavours/quick-cross.mk index 9b6fc27e67..3851bbfd13 100644 --- a/mk/flavours/quick-cross.mk +++ b/mk/flavours/quick-cross.mk @@ -5,9 +5,9 @@ GhcLibHcOpts = -O -fllvm BUILD_PROF_LIBS = NO SplitObjs = NO HADDOCK_DOCS = NO -BUILD_DOCBOOK_HTML = NO -BUILD_DOCBOOK_PS = NO -BUILD_DOCBOOK_PDF = NO +BUILD_SPHINX_HTML = NO +BUILD_SPHINX_PS = NO +BUILD_SPHINX_PDF = NO INTEGER_LIBRARY = integer-simple Stage1Only = YES diff --git a/mk/flavours/quick-llvm.mk b/mk/flavours/quick-llvm.mk index e565327822..7a19d0b1be 100644 --- a/mk/flavours/quick-llvm.mk +++ b/mk/flavours/quick-llvm.mk @@ -5,6 +5,6 @@ GhcLibHcOpts = -O BUILD_PROF_LIBS = NO SplitObjs = NO HADDOCK_DOCS = NO -BUILD_DOCBOOK_HTML = NO -BUILD_DOCBOOK_PS = NO -BUILD_DOCBOOK_PDF = NO +BUILD_SPHINX_HTML = NO +BUILD_SPHINX_PS = NO +BUILD_SPHINX_PDF = NO diff --git a/mk/flavours/quick.mk b/mk/flavours/quick.mk index eef6dc5c1a..ab8d7b3bf0 100644 --- a/mk/flavours/quick.mk +++ b/mk/flavours/quick.mk @@ -5,6 +5,6 @@ GhcLibHcOpts = -O BUILD_PROF_LIBS = NO SplitObjs = NO HADDOCK_DOCS = NO -BUILD_DOCBOOK_HTML = NO -BUILD_DOCBOOK_PS = NO -BUILD_DOCBOOK_PDF = NO +BUILD_SPHINX_HTML = NO +BUILD_SPHINX_PS = NO +BUILD_SPHINX_PDF = NO diff --git a/mk/flavours/quickest.mk b/mk/flavours/quickest.mk index 71e7c5e94c..63dd5ebc13 100644 --- a/mk/flavours/quickest.mk +++ b/mk/flavours/quickest.mk @@ -5,6 +5,6 @@ GhcLibHcOpts = -O0 BUILD_PROF_LIBS = NO SplitObjs = NO HADDOCK_DOCS = NO -BUILD_DOCBOOK_HTML = NO -BUILD_DOCBOOK_PS = NO -BUILD_DOCBOOK_PDF = NO +BUILD_SPHINX_HTML = NO +BUILD_SPHINX_PS = NO +BUILD_SPHINX_PDF = NO diff --git a/mk/flavours/validate.mk b/mk/flavours/validate.mk index 7f74356f05..0bb7b92398 100644 --- a/mk/flavours/validate.mk +++ b/mk/flavours/validate.mk @@ -5,9 +5,9 @@ GhcLibHcOpts = -O -dcore-lint BUILD_PROF_LIBS = NO SplitObjs = NO HADDOCK_DOCS = YES -BUILD_DOCBOOK_HTML = YES -BUILD_DOCBOOK_PS = NO -BUILD_DOCBOOK_PDF = NO +BUILD_SPHINX_HTML = YES +BUILD_SPHINX_PS = NO +BUILD_SPHINX_PDF = NO ifeq "$(ValidateHpc)" "YES" GhcStage2HcOpts += -fhpc -hpcdir $(TOP)/testsuite/hpc_output/ diff --git a/rules/docbook.mk b/rules/docbook.mk deleted file mode 100644 index c7c7991cb7..0000000000 --- a/rules/docbook.mk +++ /dev/null @@ -1,86 +0,0 @@ -# ----------------------------------------------------------------------------- -# -# (c) 2009 The University of Glasgow -# -# This file is part of the GHC build system. -# -# To understand how the build system works and how to modify it, see -# http://ghc.haskell.org/trac/ghc/wiki/Building/Architecture -# http://ghc.haskell.org/trac/ghc/wiki/Building/Modifying -# -# ----------------------------------------------------------------------------- - - -# Build docbook docs - -define docbook -$(call trace, docbook($1,$2)) -$(call profStart, docbook($1,$2)) -# $1 = dir -# $2 = docname - -$(call clean-target,$1,docbook,$1/$2 $1/$2.pdf $1/$2.ps) - -# empty "all_$1" target just in case we're not building docs at all -$(call all-target,$1,) - -.PHONY: html_$1 - -ifeq "$$(phase)" "final" -ifeq "$$(BUILD_DOCBOOK_HTML)" "YES" -$(call all-target,$1,html_$1) -INSTALL_HTML_DOC_DIRS += $1/$2 -endif -endif - -html_$1 : $1/$2/index.html - -ifneq "$$(BINDIST)" "YES" -$1/$2/index.html: $$($1_DOCBOOK_SOURCES) - $$(call removeTrees,$$(dir $$@)) - "$$(XSLTPROC)" --stringparam base.dir $$(dir $$@) \ - --stringparam use.id.as.filename 1 \ - --stringparam html.stylesheet fptools.css \ - --nonet \ - $$(XSLTPROC_LABEL_OPTS) $$(XSLTPROC_OPTS) \ - $$(XSLTPROC_HTML_STYLESHEET) \ - $1/$2.xml - cp mk/fptools.css $$(dir $$@) -endif - - -.PHONY: ps_$1 -ifeq "$$(phase)" "final" -ifeq "$$(BUILD_DOCBOOK_PS)" "YES" -$(call all-target,$1,ps_$1) -INSTALL_DOCS += $1/$2.ps -endif -endif - -ps_$1 : $1/$2.ps - -ifneq "$$(BINDIST)" "YES" -$1/$2.ps: $$($1_DOCBOOK_SOURCES) - "$$(DBLATEX)" $$(DBLATEX_OPTS) $1/$2.xml --ps -o $$@ - [ -f $$@ ] -endif - -ifeq "$$(phase)" "final" -ifeq "$$(BUILD_DOCBOOK_PDF)" "YES" -$(call all-target,$1,pdf_$1) -INSTALL_DOCS += $1/$2.pdf -endif -endif - -.PHONY: pdf_$1 -pdf_$1 : $1/$2.pdf - -ifneq "$$(BINDIST)" "YES" -$1/$2.pdf: $$($1_DOCBOOK_SOURCES) - "$$(DBLATEX)" $$(DBLATEX_OPTS) $1/$2.xml --pdf -o $$@ - [ -f $$@ ] -endif - -$(call profEnd, docbook($1,$2)) -endef - diff --git a/rules/sphinx.mk b/rules/sphinx.mk new file mode 100644 index 0000000000..87b57d6e07 --- /dev/null +++ b/rules/sphinx.mk @@ -0,0 +1,65 @@ +# ----------------------------------------------------------------------------- +# +# (c) 2009 The University of Glasgow +# +# This file is part of the GHC build system. +# +# To understand how the build system works and how to modify it, see +# http://ghc.haskell.org/trac/ghc/wiki/Building/Architecture +# http://ghc.haskell.org/trac/ghc/wiki/Building/Modifying +# +# ----------------------------------------------------------------------------- + + +# Build Sphinx documentation + +define sphinx +$(call trace, sphinx($1,$2)) +$(call profStart, sphinx($1,$2)) +# $1 = dir +# $2 = docname + +$(call clean-target,$1,sphinx,$1/.doctrees $1/build-html/ $1/build-pdf $1/$2.pdf) + +# empty "all_$1" target just in case we're not building docs at all +$(call all-target,$1,) + +.PHONY: html_$1 +ifeq "$$(phase)" "final" +ifeq "$$(BUILD_SPHINX_HTML)" "YES" +$(call all-target,$1,html_$1) +INSTALL_HTML_DOC_DIRS += $1/build-html/$2 $1/build-html/$2/_static $1/build-html/$2/_sources +endif +endif + +html_$1 : $1/build-html/$2/index.html +html : html_$1 + +ifneq "$$(BINDIST)" "YES" +$1/build-html/$2/index.html: $1/conf.py $$($1_RST_SOURCES) + $(SPHINXBUILD) -b html -d $1/.doctrees $(SPHINXOPTS) $1 $1/build-html/$2 +endif + + +.PHONY: pdf_$1 +ifeq "$$(phase)" "final" +ifeq "$$(BUILD_SPHINX_PDF)" "YES" +$(call all-target,$1,pdf_$1) +INSTALL_DOCS += $1/$2.pdf +endif +endif + +pdf_$1 : $1/$2.pdf +pdf : pdf_$1 + +ifneq "$$(BINDIST)" "YES" +$1/$2.pdf: $$($1_RST_SOURCES) + $(SPHINXBUILD) -b latex -d $1/.doctrees $(SPHINXOPTS) $1 $1/build-pdf/$2 + cd $1/build-pdf/$2 ; xelatex $2.tex + cd $1/build-pdf/$2 ; xelatex $2.tex + cp $1/build-pdf/$2/$2.pdf $1/$2.pdf +endif + + +$(call profEnd, sphinx($1,$2)) +endef diff --git a/utils/mkUserGuidePart/DList.hs b/utils/mkUserGuidePart/DList.hs new file mode 100644 index 0000000000..c4b9283e52 --- /dev/null +++ b/utils/mkUserGuidePart/DList.hs @@ -0,0 +1,13 @@ +module DList where + +newtype DList a = DList ([a] -> [a]) + +snoc :: DList a -> a -> DList a +DList f `snoc` x = DList (f . (x:)) + +toList :: DList a -> [a] +toList (DList f) = f [] + +instance Monoid (DList a) where + mempty = DList id + DList a `mappend` DList b = DList (a . b) diff --git a/utils/mkUserGuidePart/Main.hs b/utils/mkUserGuidePart/Main.hs index c415eb4f49..9bc8caa216 100644 --- a/utils/mkUserGuidePart/Main.hs +++ b/utils/mkUserGuidePart/Main.hs @@ -1,62 +1,107 @@ - module Main (main) where import DynFlags +import Data.List (stripPrefix) +import Control.Monad (forM_) +import Types hiding (flag) +import Table +import Options -import Data.List -import System.Environment +-- | A ReStructuredText fragment +type ReST = String main :: IO () -main = do args <- getArgs - case args of - [] -> error "Need to give filename to generate as an argument" - [f] -> - case f of - "docs/users_guide/users_guide.xml" -> - writeFile f userGuideMain - "docs/users_guide/what_glasgow_exts_does.gen.xml" -> - writeFile f whatGlasgowExtsDoes - _ -> - error ("Don't know what to do for " ++ show f) - _ -> error "Bad args" - --- Hack: dblatex normalises the name of the main input file using --- os.path.realpath, which means that if we're in a linked build tree, --- it find the real source files rather than the symlinks in our link --- tree. This is fine for the static sources, but it means it can't --- find the generated sources. --- We therefore also generate the main input file, so that it really --- is in the link tree, and thus dblatex can find everything. -userGuideMain :: String -userGuideMain = unlines [ - "<?xml version=\"1.0\" encoding=\"iso-8859-1\"?>", - "<!DOCTYPE book PUBLIC \"-//OASIS//DTD DocBook XML V4.2//EN\"", - " \"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd\" [", - "<!ENTITY % ug-ent SYSTEM \"ug-ent.xml\">", - "%ug-ent;", - "<!ENTITY ug-book SYSTEM \"ug-book.xml\">", - "]>", - "", - "<book id=\"users-guide\">", - "&ug-book;", - "</book>"] +main = do + -- users guide + writeRestFile (usersGuideFile "what_glasgow_exts_does.gen.rst") + $ whatGlasgowExtsDoes + forM_ groups $ \(Group name _ theFlags) -> + let fname = usersGuideFile $ "flags-"++name++".gen.rst" + in writeRestFile fname (flagsTable theFlags) + + -- man page + writeRestFile (usersGuideFile "all-flags.gen.rst") (flagsList groups) + +usersGuideFile :: FilePath -> FilePath +usersGuideFile fname = "docs/users_guide/"++fname + +writeRestFile :: FilePath -> ReST -> IO () +writeRestFile fname content = + writeFile fname $ unlines + [ ".. This file is generated by utils/mkUserGuidePart" + , "" + , content + ] whatGlasgowExtsDoes :: String -whatGlasgowExtsDoes = case maybeInitLast glasgowExtsFlags of - Just (xs, x) -> - let xs' = map mkInitLine xs - x' = mkLastLine x - in unlines (xs' ++ [x']) - Nothing -> - error "glasgowExtsFlags is empty?" - where mkInitLine = mkLine ',' - mkLastLine = mkLine '.' - mkLine c f = case stripPrefix "Opt_" (show f) of - Just ext -> "<option>-X" ++ ext ++ "</option>" ++ [c] - Nothing -> error ("Can't parse extension: " ++ show f) - -maybeInitLast :: [a] -> Maybe ([a], a) -maybeInitLast xs = case reverse xs of - (y : ys) -> Just (reverse ys, y) - _ -> Nothing +whatGlasgowExtsDoes = unlines + $ [ ".. hlist::", ""] + ++ map ((" * "++) . parseExt) glasgowExtsFlags + where + parseExt f + | Just ext <- stripPrefix "Opt_" (show f) + = inlineCode $ "-X" ++ ext + | otherwise + = error ("Can't parse extension: " ++ show f) + +-- | Generate a reference table of the given set of flags. This is used in +-- the users guide. +flagsTable :: [Flag] -> ReST +flagsTable theFlags = + table [50, 100, 30, 50] + ["Flag", "Description", "Static/Dynamic", "Reverse"] + (map flagRow theFlags) + where + code "" = "" + code str = "``"++str++"``" + flagRow flag = + [ code (flagName flag) + , flagDescription flag + , type_ + , code (flagReverse flag) + ] + where + type_ = case flagType flag of + StaticFlag -> "static" + DynamicFlag -> "dynamic" + DynamicSettableFlag -> "dynamic/``:set``" + ModeFlag -> "mode" + +-- | Place the given text in an ReST inline code element. +inlineCode :: String -> ReST +inlineCode s = "``" ++ s ++ "``" + +-- | Generate a ReST substitution definition. +substitution :: String -> ReST -> ReST +substitution substName content = + unlines [".. |" ++ substName ++ "| ", content] + +heading :: Char -> String -> ReST +heading chr title = unlines + [ title + , replicate (length title) chr + , "" + ] + +-- | Generate a listing of all the flags known to GHC. +-- Used in the man page. +flagsList :: [Group] -> ReST +flagsList grps = unlines $ + map doGroup grps ++ map flagDescriptions grps + where + doGroup grp = unlines + [ grpTitle grp + , " " ++ unwords (map (inlineCode . flagName) (grpFlags grp)) + , "" + ] +-- | Generate a definition list of the known flags. +-- Used in the man page. +flagDescriptions :: Group -> ReST +flagDescriptions (Group _ title fs) = + unlines $ [ heading '~' title ] ++ map doFlag fs + where + doFlag flag = + unlines $ [ inlineCode (flagName flag) + , " " ++ flagDescription flag + ] diff --git a/utils/mkUserGuidePart/Options.hs b/utils/mkUserGuidePart/Options.hs new file mode 100644 index 0000000000..ab1ab696fe --- /dev/null +++ b/utils/mkUserGuidePart/Options.hs @@ -0,0 +1,66 @@ +module Options (Group(..), groups) where + +import Types + +import Options.CodeGen +import Options.CompilerDebugging +import Options.Cpp +import Options.FindingImports +import Options.Interactive +import Options.InterfaceFiles +import Options.KeepingIntermediates +import Options.Language +import Options.Linking +import Options.Misc +import Options.Modes +import Options.Optimizations +import Options.OptimizationLevels +import Options.Packages +import Options.Phases +import Options.PhasePrograms +import Options.PhaseSpecific +import Options.PlatformSpecific +import Options.Plugin +import Options.Profiling +import Options.ProgramCoverage +import Options.RecompilationChecking +import Options.RedirectingOutput +import Options.TemporaryFiles +import Options.Verbosity +import Options.Warnings + +-- | A group of flags +data Group = Group { grpName :: String -- ^ Internal name + , grpTitle :: String -- ^ Human-readable title + , grpFlags :: [Flag] -- ^ Flags in group + } + +groups :: [Group] +groups = + [ Group "codegen" "Code generation" codegenOptions + , Group "compiler-debugging" "Debugging the compiler" compilerDebuggingOptions + , Group "cpp" "C pre-processor" cppOptions + , Group "finding-imports" "Finding imports" findingImportsOptions + , Group "interactive" "Interactive mode" interactiveOptions + , Group "interface-files" "Interface files" interfaceFilesOptions + , Group "keeping-intermediates" "Keeping intermediate files" keepingIntermediatesOptions + , Group "language" "Language options" languageOptions + , Group "linking" "Linking options" linkingOptions + , Group "misc" "Miscellaneous options" miscOptions + , Group "modes" "Modes of operation" modeOptions + , Group "optimization" "Individual optimizations " optimizationsOptions + , Group "optimization-levels" "Optimization levels" optimizationLevelsOptions + , Group "packages" "Package options" packagesOptions + , Group "phases" "Phases of compilation" phaseOptions + , Group "phase-programs" "Overriding external programs" phaseProgramsOptions + , Group "phase-specific" "Phase-specific options" phaseSpecificOptions + , Group "platform-specific" "Platform-specific options" platformSpecificOptions + , Group "plugin" "Compiler plugins" pluginOptions + , Group "profiling" "Profiling" profilingOptions + , Group "program-coverage" "Program coverage" programCoverageOptions + , Group "recompilation-checking" "Recompilation checking" recompilationCheckingOptions + , Group "redirecting-output" "Redirecting output" redirectingOutputOptions + , Group "temporary-files" "Temporary files" temporaryFilesOptions + , Group "verbosity" "Verbosity options" verbosityOptions + , Group "warnings" "Warnings" warningsOptions + ] diff --git a/utils/mkUserGuidePart/Options/CodeGen.hs b/utils/mkUserGuidePart/Options/CodeGen.hs new file mode 100644 index 0000000000..0d9cabb27d --- /dev/null +++ b/utils/mkUserGuidePart/Options/CodeGen.hs @@ -0,0 +1,35 @@ +module Options.CodeGen where + +import Types + +codegenOptions :: [Flag] +codegenOptions = + [ flag { flagName = "-fasm" + , flagDescription = + "Use the :ref:`native code generator <native-code-gen>`" + , flagType = DynamicFlag + , flagReverse = "-fllvm" + } + , flag { flagName = "-fllvm" + , flagDescription = + "Compile using the :ref:`LLVM code generator <llvm-code-gen>`" + , flagType = DynamicFlag + , flagReverse = "-fasm" + } + , flag { flagName = "-fno-code" + , flagDescription = "Omit code generation" + , flagType = DynamicFlag + } + , flag { flagName = "-fwrite-interface" + , flagDescription = "Always write interface files" + , flagType = DynamicFlag + } + , flag { flagName = "-fbyte-code" + , flagDescription = "Generate byte-code" + , flagType = DynamicFlag + } + , flag { flagName = "-fobject-code" + , flagDescription = "Generate object code" + , flagType = DynamicFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/CompilerDebugging.hs b/utils/mkUserGuidePart/Options/CompilerDebugging.hs new file mode 100644 index 0000000000..6160f01e8c --- /dev/null +++ b/utils/mkUserGuidePart/Options/CompilerDebugging.hs @@ -0,0 +1,272 @@ +module Options.CompilerDebugging where + +import Types + +compilerDebuggingOptions :: [Flag] +compilerDebuggingOptions = + [ flag { flagName = "-dcore-lint" + , flagDescription = "Turn on internal sanity checking" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-to-file" + , flagDescription = "Dump to files instead of stdout" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-asm" + , flagDescription = "Dump assembly" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-bcos" + , flagDescription = "Dump interpreter byte code" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-cmm" + , flagDescription = "Dump C-- output" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-core-stats" + , flagDescription = + "Print a one-line summary of the size of the Core program at the "++ + "end of the optimisation pipeline" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-cse" + , flagDescription = "Dump CSE output" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-deriv" + , flagDescription = "Dump deriving output" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-ds" + , flagDescription = "Dump desugarer output" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-foreign" + , flagDescription = "Dump ``foreign export`` stubs" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-hpc" + , flagDescription = "Dump after instrumentation for program coverage" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-inlinings" + , flagDescription = "Dump inlining info" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-llvm" + , flagDescription = "Dump LLVM intermediate code" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-occur-anal" + , flagDescription = "Dump occurrence analysis output" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-opt-cmm" + , flagDescription = "Dump the results of C-- to C-- optimising passes" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-parsed" + , flagDescription = "Dump parse tree" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-prep" + , flagDescription = "Dump prepared core" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-rn" + , flagDescription = "Dump renamer output" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-rule-firings" + , flagDescription = "Dump rule firing info" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-rule-rewrites" + , flagDescription = "Dump detailed rule firing info" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-rules" + , flagDescription = "Dump rules" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-vect" + , flagDescription = "Dump vectoriser input and output" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-simpl" + , flagDescription = "Dump final simplifier output" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-simpl-iterations" + , flagDescription = "Dump output from each simplifier iteration" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-spec" + , flagDescription = "Dump specialiser output" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-splices" + , flagDescription = + "Dump TH spliced expressions, and what they evaluate to" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-stg" + , flagDescription = "Dump final STG" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-stranal" + , flagDescription = "Dump strictness analyser output" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-strsigs" + , flagDescription = "Dump strictness signatures" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-tc" + , flagDescription = "Dump typechecker output" + , flagType = DynamicFlag + } + , flag { flagName = "-dth-dec-file" + , flagDescription = + "Show evaluated TH declarations in a .th.hs file" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-types" + , flagDescription = "Dump type signatures" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-worker-wrapper" + , flagDescription = "Dump worker-wrapper output" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-if-trace" + , flagDescription = "Trace interface files" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-tc-trace" + , flagDescription = "Trace typechecker" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-vt-trace" + , flagDescription = "Trace vectoriser" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-rn-trace" + , flagDescription = "Trace renamer" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-rn-stats" + , flagDescription = "Renamer stats" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-simpl-stats" + , flagDescription = "Dump simplifier stats" + , flagType = DynamicFlag + } + , flag { flagName = "-dno-debug-output" + , flagDescription = "Suppress unsolicited debugging output" + , flagType = StaticFlag + } + , flag { flagName = "-dppr-debug" + , flagDescription = "Turn on debug printing (more verbose)" + , flagType = StaticFlag + } + , flag { flagName = "-dppr-user-length" + , flagDescription = + "Set the depth for printing expressions in error msgs" + , flagType = DynamicFlag + } + , flag { flagName = "-dppr-cols⟨N⟩" + , flagDescription = + "Set the width of debugging output. For example ``-dppr-cols200``" + , flagType = DynamicFlag + } + , flag { flagName = "-dppr-case-as-let" + , flagDescription = + "Print single alternative case expressions as strict lets." + , flagType = DynamicFlag + } + , flag { flagName = "-dsuppress-all" + , flagDescription = + "In core dumps, suppress everything (except for uniques) that is "++ + "suppressible." + , flagType = DynamicFlag + } + , flag { flagName = "-dsuppress-uniques" + , flagDescription = + "Suppress the printing of uniques in debug output (easier to use "++ + "``diff``)" + , flagType = DynamicFlag + } + , flag { flagName = "-dsuppress-idinfo" + , flagDescription = + "Suppress extended information about identifiers where they "++ + "are bound" + , flagType = DynamicFlag + } + , flag { flagName = "-dsuppress-unfoldings" + , flagDescription = + "Suppress the printing of the stable unfolding of a variable at "++ + "its binding site" + , flagType = DynamicFlag + } + , flag { flagName = "-dsuppress-module-prefixes" + , flagDescription = + "Suppress the printing of module qualification prefixes" + , flagType = DynamicFlag + } + , flag { flagName = "-dsuppress-type-signatures" + , flagDescription = "Suppress type signatures" + , flagType = DynamicFlag + } + , flag { flagName = "-dsuppress-type-applications" + , flagDescription = "Suppress type applications" + , flagType = DynamicFlag + } + , flag { flagName = "-dsuppress-coercions" + , flagDescription = + "Suppress the printing of coercions in Core dumps to make them "++ + "shorter" + , flagType = DynamicFlag + } + , flag { flagName = "-dsource-stats" + , flagDescription = "Dump haskell source stats" + , flagType = DynamicFlag + } + , flag { flagName = "-dcmm-lint" + , flagDescription = "C-- pass sanity checking" + , flagType = DynamicFlag + } + , flag { flagName = "-dstg-lint" + , flagDescription = "STG pass sanity checking" + , flagType = DynamicFlag + } + , flag { flagName = "-dstg-stats" + , flagDescription = "Dump STG stats" + , flagType = DynamicFlag + } + , flag { flagName = "-dverbose-core2core" + , flagDescription = "Show output from each core-to-core pass" + , flagType = DynamicFlag + } + , flag { flagName = "-dverbose-stg2stg" + , flagDescription = "Show output from each STG-to-STG pass" + , flagType = DynamicFlag + } + , flag { flagName = "-dshow-passes" + , flagDescription = "Print out each pass name as it happens" + , flagType = DynamicFlag + } + , flag { flagName = "-dfaststring-stats" + , flagDescription = + "Show statistics for fast string usage when finished" + , flagType = DynamicFlag + } + , flag { flagName = "-frule-check" + , flagDescription = + "Report sites with rules that could have fired but didn't. "++ + "Takes a string argument." + , flagType = DynamicFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/Cpp.hs b/utils/mkUserGuidePart/Options/Cpp.hs new file mode 100644 index 0000000000..ae5b122bf9 --- /dev/null +++ b/utils/mkUserGuidePart/Options/Cpp.hs @@ -0,0 +1,25 @@ +module Options.Cpp where + +import Types + +cppOptions :: [Flag] +cppOptions = + [ flag { flagName = "-cpp" + , flagDescription = "Run the C pre-processor on Haskell source files" + , flagType = DynamicFlag + } + , flag { flagName = "-D⟨symbol⟩[=⟨value⟩]" + , flagDescription = "Define a symbol in the C pre-processor" + , flagType = DynamicFlag + , flagReverse = "-U⟨symbol⟩" + } + , flag { flagName = "-U⟨symbol⟩" + , flagDescription = "Undefine a symbol in the C pre-processor" + , flagType = DynamicFlag + } + , flag { flagName = "-I⟨dir⟩" + , flagDescription = + "Add ⟨dir⟩ to the directory search list for ``#include`` files" + , flagType = DynamicFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/FindingImports.hs b/utils/mkUserGuidePart/Options/FindingImports.hs new file mode 100644 index 0000000000..4302055c82 --- /dev/null +++ b/utils/mkUserGuidePart/Options/FindingImports.hs @@ -0,0 +1,15 @@ +module Options.FindingImports where + +import Types + +findingImportsOptions :: [Flag] +findingImportsOptions = + [ flag { flagName = "-i ⟨dir1⟩:⟨dir2⟩:..." + , flagDescription = "add ⟨dir⟩, ⟨dir2⟩, etc. to import path" + , flagType = DynamicSettableFlag + } + , flag { flagName = "-i" + , flagDescription = "Empty the import directory list" + , flagType = DynamicSettableFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/Interactive.hs b/utils/mkUserGuidePart/Options/Interactive.hs new file mode 100644 index 0000000000..142e207e67 --- /dev/null +++ b/utils/mkUserGuidePart/Options/Interactive.hs @@ -0,0 +1,65 @@ +module Options.Interactive where + +import Types + +interactiveOptions :: [Flag] +interactiveOptions = + [ flag { flagName = "-ignore-dot-ghci" + , flagDescription = "Disable reading of ``.ghci`` files" + , flagType = DynamicFlag + } + , flag { flagName = "-ghci-script" + , flagDescription = "Read additional ``.ghci`` files" + , flagType = DynamicFlag + } + , flag { flagName = "-fbreak-on-error" + , flagDescription = + ":ref:`Break on uncaught exceptions and errors " ++ + "<ghci-debugger-exceptions>`" + , flagType = DynamicFlag + , flagReverse = "-fno-break-on-error" + } + , flag { flagName = "-fbreak-on-exception" + , flagDescription = + ":ref:`Break on any exception thrown <ghci-debugger-exceptions>`" + , flagType = DynamicFlag + , flagReverse = "-fno-break-on-exception" + } + , flag { flagName = "-fghci-hist-size=⟨n⟩" + , flagDescription = + "Set the number of entries GHCi keeps for ``:history``." ++ + " See :ref:`ghci-debugger`." + , flagType = DynamicFlag + , flagReverse = "(default is 50)" + } + , flag { flagName = "-fprint-evld-with-show" + , flagDescription = + "Enable usage of ``Show`` instances in ``:print``. "++ + "See :ref:`breakpoints`." + , flagType = DynamicFlag + , flagReverse = "-fno-print-evld-with-show" + } + , flag { flagName = "-fprint-bind-result" + , flagDescription = + ":ref:`Turn on printing of binding results in GHCi <ghci-stmts>`" + , flagType = DynamicFlag + , flagReverse = "-fno-print-bind-result" + } + , flag { flagName = "-fno-print-bind-contents" + , flagDescription = + ":ref:`Turn off printing of binding contents in GHCi <breakpoints>`" + , flagType = DynamicFlag + } + , flag { flagName = "-fno-implicit-import-qualified" + , flagDescription = + ":ref:`Turn off implicit qualified import of everything in GHCi " ++ + "<ghci-import-qualified>`" + , flagType = DynamicFlag + } + , flag { flagName = "-interactive-print" + , flagDescription = + ":ref:`Select the function to use for printing evaluated " ++ + "expressions in GHCi <ghci-interactive-print>`" + , flagType = DynamicFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/InterfaceFiles.hs b/utils/mkUserGuidePart/Options/InterfaceFiles.hs new file mode 100644 index 0000000000..314e0ebb69 --- /dev/null +++ b/utils/mkUserGuidePart/Options/InterfaceFiles.hs @@ -0,0 +1,23 @@ +module Options.InterfaceFiles where + +import Types + +interfaceFilesOptions :: [Flag] +interfaceFilesOptions = + [ flag { flagName = "-ddump-hi" + , flagDescription = "Dump the new interface to stdout" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-hi-diffs" + , flagDescription = "Show the differences vs. the old interface" + , flagType = DynamicFlag + } + , flag { flagName = "-ddump-minimal-imports" + , flagDescription = "Dump a minimal set of imports" + , flagType = DynamicFlag + } + , flag { flagName = "--show-iface ⟨file⟩" + , flagDescription = "See :ref:`modes`." + , flagType = ModeFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/KeepingIntermediates.hs b/utils/mkUserGuidePart/Options/KeepingIntermediates.hs new file mode 100644 index 0000000000..9c93aedfeb --- /dev/null +++ b/utils/mkUserGuidePart/Options/KeepingIntermediates.hs @@ -0,0 +1,23 @@ +module Options.KeepingIntermediates where + +import Types + +keepingIntermediatesOptions :: [Flag] +keepingIntermediatesOptions = + [ flag { flagName = "-keep-hc-file, -keep-hc-files" + , flagDescription = "retain intermediate ``.hc`` files" + , flagType = DynamicFlag + } + , flag { flagName = "-keep-llvm-file, -keep-llvm-files" + , flagDescription = "retain intermediate LLVM ``.ll`` files" + , flagType = DynamicFlag + } + , flag { flagName = "-keep-s-file, -keep-s-files" + , flagDescription = "retain intermediate ``.s`` files" + , flagType = DynamicFlag + } + , flag { flagName = "-keep-tmp-files" + , flagDescription = "retain all intermediate temporary files" + , flagType = DynamicFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/Language.hs b/utils/mkUserGuidePart/Options/Language.hs new file mode 100644 index 0000000000..17416ffbf1 --- /dev/null +++ b/utils/mkUserGuidePart/Options/Language.hs @@ -0,0 +1,735 @@ +module Options.Language where + +import Types + +languageOptions :: [Flag] +languageOptions = + [ flag { flagName = "-fconstraint-solver-iterations=⟨n⟩" + , flagDescription = + "*default: 4.* Set the iteration limit for the type-constraint "++ + "solver. Typically one iteration suffices; so please "++ + "yell if you find you need to set it higher than the default. "++ + "Zero means infinity." + , flagType = DynamicFlag + } + , flag { flagName = "-freduction-depth=⟨n⟩" + , flagDescription = + "*default: 200.* Set the :ref:`limit for type simplification "++ + "<undecidable-instances>`. Zero means infinity." + , flagType = DynamicFlag + } + , flag { flagName = "-fcontext-stack=⟨n⟩" + , flagDescription = + "Deprecated. Use ``-freduction-depth=⟨n⟩`` instead." + , flagType = DynamicFlag + } + , flag { flagName = "-fglasgow-exts" + , flagDescription = + "Deprecated. Enable most language extensions; "++ + "see :ref:`options-language` for exactly which ones." + , flagType = DynamicFlag + , flagReverse = "-fno-glasgow-exts" + } + , flag { flagName = "-firrefutable-tuples" + , flagDescription = "Make tuple pattern matching irrefutable" + , flagType = DynamicFlag + , flagReverse = "-fno-irrefutable-tuples" + } + , flag { flagName = "-fpackage-trust" + , flagDescription = + "Enable :ref:`Safe Haskell <safe-haskell>` trusted package "++ + "requirement for trustworthy modules." + , flagType = DynamicFlag + } + , flag { flagName = "-ftype-function-depth=⟨n⟩" + , flagDescription = "Deprecated. Use ``-freduction-depth=⟨n⟩`` instead." + , flagType = DynamicFlag + } + , flag { flagName = "-XAllowAmbiguousTypes" + , flagDescription = + "Allow the user to write :ref:`ambiguous types <ambiguity>`, and "++ + "the type inference engine to infer them." + , flagType = DynamicFlag + , flagReverse = "-XNoAllowAmbiguousTypes" + , flagSince = "7.8.1" + } + , flag { flagName = "-XArrows" + , flagDescription = + "Enable :ref:`arrow notation <arrow-notation>` extension" + , flagType = DynamicFlag + , flagReverse = "-XNoArrows" + , flagSince = "6.8.1" + } + , flag { flagName = "-XApplicativeDo" + , flagDescription = + "Enable :ref:`Applicative do-notation desugaring <applicative-do>`" + , flagType = DynamicFlag + , flagReverse = "-XNoApplicativeDo" + , flagSince = "7.12.1" + } + , flag { flagName = "-XAutoDeriveTypeable" + , flagDescription = + "As of GHC 7.10, this option is not needed, and should not be "++ + "used. Previously this would automatically :ref:`derive Typeable "++ + "instances for every datatype and type class declaration "++ + "<deriving-typeable>`. Implies ``-XDeriveDataTypeable``." + , flagType = DynamicFlag + , flagReverse = "-XNoAutoDeriveTypeable" + , flagSince = "7.8.1" + } + , flag { flagName = "-XBangPatterns" + , flagDescription = "Enable :ref:`bang patterns <bang-patterns>`." + , flagType = DynamicFlag + , flagReverse = "-XNoBangPatterns" + , flagSince = "6.8.1" + } + , flag { flagName = "-XBinaryLiterals" + , flagDescription = + "Enable support for :ref:`binary literals <binary-literals>`." + , flagType = DynamicFlag + , flagReverse = "-XNoBinaryLiterals" + , flagSince = "7.10.1" + } + , flag { flagName = "-XCApiFFI" + , flagDescription = + "Enable :ref:`the CAPI calling convention <ffi-capi>`." + , flagType = DynamicFlag + , flagReverse = "-XNoCAPIFFI" + , flagSince = "7.10.1" + } + , flag { flagName = "-XConstrainedClassMethods" + , flagDescription = + "Enable :ref:`constrained class methods <class-method-types>`." + , flagType = DynamicFlag + , flagReverse = "-XNoConstrainedClassMethods" + , flagSince = "6.8.1" + } + , flag { flagName = "-XConstraintKinds" + , flagDescription = + "Enable a :ref:`kind of constraints <constraint-kind>`." + , flagType = DynamicFlag + , flagReverse = "-XNoConstraintKinds" + , flagSince = "7.4.1" + } + , flag { flagName = "-XCPP" + , flagDescription = + "Enable the :ref:`C preprocessor <c-pre-processor>`." + , flagType = DynamicFlag + , flagReverse = "-XNoCPP" + , flagSince = "6.8.1" + } + , flag { flagName = "-XDataKinds" + , flagDescription = "Enable :ref:`datatype promotion <promotion>`." + , flagType = DynamicFlag + , flagReverse = "-XNoDataKinds" + , flagSince = "7.4.1" + } + , flag { flagName = "-XDefaultSignatures" + , flagDescription = + "Enable :ref:`default signatures <class-default-signatures>`." + , flagType = DynamicFlag + , flagReverse = "-XNoDefaultSignatures" + , flagSince = "7.2.1" + } + , flag { flagName = "-XDeriveAnyClass" + , flagDescription = + "Enable :ref:`deriving for any class <derive-any-class>`." + , flagType = DynamicFlag + , flagReverse = "-XNoDeriveAnyClass" + , flagSince = "7.10.1" + } + , flag { flagName = "-XDeriveDataTypeable" + , flagDescription = + "Enable ``deriving`` for the :ref:`Data class "++ + "<deriving-typeable>`. Implied by ``-XAutoDeriveTypeable``." + , flagType = DynamicFlag + , flagReverse = "-XNoDeriveDataTypeable" + , flagSince = "6.8.1" + } + , flag { flagName = "-XDeriveFunctor" + , flagDescription = + "Enable :ref:`deriving for the Functor class <deriving-extra>`. "++ + "Implied by ``-XDeriveTraversable``." + , flagType = DynamicFlag + , flagReverse = "-XNoDeriveFunctor" + , flagSince = "7.10.1" + } + , flag { flagName = "-XDeriveFoldable" + , flagDescription = + "Enable :ref:`deriving for the Foldable class <deriving-extra>`. "++ + "Implied by ``-XDeriveTraversable``." + , flagType = DynamicFlag + , flagReverse = "-XNoDeriveFoldable" + , flagSince = "7.10.1" + } + , flag { flagName = "-XDeriveGeneric" + , flagDescription = + "Enable :ref:`deriving for the Generic class <deriving-typeable>`." + , flagType = DynamicFlag + , flagReverse = "-XNoDeriveGeneric" + , flagSince = "7.2.1" + } + , flag { flagName = "-XDeriveGeneric" + , flagDescription = + "Enable :ref:`deriving for the Generic class <deriving-typeable>`." + , flagType = DynamicFlag + , flagReverse = "-XNoDeriveGeneric" + , flagSince = "7.2.1" + } + , flag { flagName = "-XDeriveLift" + , flagDescription = + "Enable :ref:`deriving for the Lift class <deriving-lift>`" + , flagType = DynamicFlag + , flagReverse = "-XNoDeriveLift" + , flagSince = "7.2.1" + } + , flag { flagName = "-XDeriveTraversable" + , flagDescription = + "Enable :ref:`deriving for the Traversable class <deriving-extra>`. "++ + "Implies ``-XDeriveFunctor`` and ``-XDeriveFoldable``." + , flagType = DynamicFlag + , flagReverse = "-XNoDeriveTraversable" + , flagSince = "7.10.1" + } + , flag { flagName = "-XDisambiguateRecordFields" + , flagDescription = + "Enable :ref:`record field disambiguation <disambiguate-fields>`. "++ + "Implied by ``-XRecordWildCards``." + , flagType = DynamicFlag + , flagReverse = "-XNoDisambiguateRecordFields" + , flagSince = "6.8.1" + } + , flag { flagName = "-XEmptyCase" + , flagDescription = + "Allow :ref:`empty case alternatives <empty-case>`." + , flagType = DynamicFlag + , flagReverse = "-XNoEmptyCase" + , flagSince = "7.8.1" + } + , flag { flagName = "-XEmptyDataDecls" + , flagDescription = "Enable empty data declarations." + , flagType = DynamicFlag + , flagReverse = "-XNoEmptyDataDecls" + , flagSince = "6.8.1" + } + , flag { flagName = "-XExistentialQuantification" + , flagDescription = + "Enable :ref:`existential quantification <existential-quantification>`." + , flagType = DynamicFlag + , flagReverse = "-XNoExistentialQuantification" + , flagSince = "6.8.1" + } + , flag { flagName = "-XExplicitForAll" + , flagDescription = + "Enable :ref:`explicit universal quantification <explicit-foralls>`."++ + " Implied by ``-XScopedTypeVariables``, ``-XLiberalTypeSynonyms``,"++ + " ``-XRankNTypes`` and ``-XExistentialQuantification``." + , flagType = DynamicFlag + , flagReverse = "-XNoExplicitForAll" + , flagSince = "6.12.1" + } + , flag { flagName = "-XExplicitNamespaces" + , flagDescription = + "Enable using the keyword ``type`` to specify the namespace of "++ + "entries in imports and exports (:ref:`explicit-namespaces`). "++ + "Implied by ``-XTypeOperators`` and ``-XTypeFamilies``." + , flagType = DynamicFlag + , flagReverse = "-XNoExplicitNamespaces" + , flagSince = "7.6.1" + } + , flag { flagName = "-XExtendedDefaultRules" + , flagDescription = + "Use GHCi's :ref:`extended default rules <extended-default-rules>` "++ + "in a normal module." + , flagType = DynamicFlag + , flagReverse = "-XNoExtendedDefaultRules" + , flagSince = "6.8.1" + } + , flag { flagName = "-XFlexibleContexts" + , flagDescription = + "Enable :ref:`flexible contexts <flexible-contexts>`. Implied by "++ + "``-XImplicitParams``." + , flagType = DynamicFlag + , flagReverse = "-XNoFlexibleContexts" + , flagSince = "6.8.1" + } + , flag { flagName = "-XFlexibleInstances" + , flagDescription = + "Enable :ref:`flexible instances <instance-rules>`. "++ + "Implies ``-XTypeSynonymInstances``. "++ + "Implied by ``-XImplicitParams``." + , flagType = DynamicFlag + , flagReverse = "-XNoFlexibleInstances" + , flagSince = "6.8.1" + } + , flag { flagName = "-XForeignFunctionInterface" + , flagDescription = + "Enable :ref:`foreign function interface <ffi>`." + , flagType = DynamicFlag + , flagReverse = "-XNoForeignFunctionInterface" + , flagSince = "6.8.1" + } + , flag { flagName = "-XFunctionalDependencies" + , flagDescription = + "Enable :ref:`functional dependencies <functional-dependencies>`. "++ + "Implies ``-XMultiParamTypeClasses``." + , flagType = DynamicFlag + , flagReverse = "-XNoFunctionalDependencies" + , flagSince = "6.8.1" + } + , flag { flagName = "-XGADTs" + , flagDescription = + "Enable :ref:`generalised algebraic data types <gadt>`. "++ + "Implies ``-XGADTSyntax`` and ``-XMonoLocalBinds``." + , flagType = DynamicFlag + , flagReverse = "-XNoGADTs" + , flagSince = "6.8.1" + } + , flag { flagName = "-XGADTSyntax" + , flagDescription = + "Enable :ref:`generalised algebraic data type syntax <gadt-style>`." + , flagType = DynamicFlag + , flagReverse = "-XNoGADTSyntax" + , flagSince = "7.2.1" + } + , flag { flagName = "-XGeneralizedNewtypeDeriving" + , flagDescription = + "Enable :ref:`newtype deriving <newtype-deriving>`." + , flagType = DynamicFlag + , flagReverse = "-XNoGeneralizedNewtypeDeriving" + , flagSince = "6.8.1" + } + , flag { flagName = "-XGenerics" + , flagDescription = + "Deprecated, does nothing. No longer enables "++ + ":ref:`generic classes <generic-classes>`. See also GHC's support "++ + "for :ref:`generic programming <generic-programming>`." + , flagType = DynamicFlag + , flagReverse = "-XNoGenerics" + , flagSince = "6.8.1" + } + , flag { flagName = "-XImplicitParams" + , flagDescription = + "Enable :ref:`Implicit Parameters <implicit-parameters>`. "++ + "Implies ``-XFlexibleContexts`` and ``-XFlexibleInstances``." + , flagType = DynamicFlag + , flagReverse = "-XNoImplicitParams" + , flagSince = "6.8.1" + } + , flag { flagName = "-XNoImplicitPrelude" + , flagDescription = + "Don't implicitly ``import Prelude``. "++ + "Implied by ``-XRebindableSyntax``." + , flagType = DynamicFlag + , flagReverse = "-XImplicitPrelude" + , flagSince = "6.8.1" + } + , flag { flagName = "-XImpredicativeTypes" + , flagDescription = + "Enable :ref:`impredicative types <impredicative-polymorphism>`. "++ + "Implies ``-XRankNTypes``." + , flagType = DynamicFlag + , flagReverse = "-XNoImpredicativeTypes" + , flagSince = "6.10.1" + } + , flag { flagName = "-XIncoherentInstances" + , flagDescription = + "Enable :ref:`incoherent instances <instance-overlap>`. "++ + "Implies ``-XOverlappingInstances``." + , flagType = DynamicFlag + , flagReverse = "-XNoIncoherentInstances" + , flagSince = "6.8.1" + } + , flag { flagName = "-XInstanceSigs" + , flagDescription = + "Enable :ref:`instance signatures <instance-sigs>`." + , flagType = DynamicFlag + , flagReverse = "-XNoInstanceSigs" + , flagSince = "7.10.1" + } + , flag { flagName = "-XInterruptibleFFI" + , flagDescription = "Enable interruptible FFI." + , flagType = DynamicFlag + , flagReverse = "-XNoInterruptibleFFI" + , flagSince = "7.2.1" + } + , flag { flagName = "-XKindSignatures" + , flagDescription = + "Enable :ref:`kind signatures <kinding>`. "++ + "Implied by ``-XTypeFamilies`` and ``-XPolyKinds``." + , flagType = DynamicFlag + , flagReverse = "-XNoKindSignatures" + , flagSince = "6.8.1" + } + , flag { flagName = "-XLambdaCase" + , flagDescription = + "Enable :ref:`lambda-case expressions <lambda-case>`." + , flagType = DynamicFlag + , flagReverse = "-XNoLambdaCase" + , flagSince = "7.6.1" + } + , flag { flagName = "-XLiberalTypeSynonyms" + , flagDescription = + "Enable :ref:`liberalised type synonyms <type-synonyms>`." + , flagType = DynamicFlag + , flagReverse = "-XNoLiberalTypeSynonyms" + , flagSince = "6.8.1" + } + , flag { flagName = "-XMagicHash" + , flagDescription = + "Allow ``#`` as a :ref:`postfix modifier on identifiers <magic-hash>`." + , flagType = DynamicFlag + , flagReverse = "-XNoMagicHash" + , flagSince = "6.8.1" + } + , flag { flagName = "-XMonadComprehensions" + , flagDescription = + "Enable :ref:`monad comprehensions <monad-comprehensions>`." + , flagType = DynamicFlag + , flagReverse = "-XNoMonadComprehensions" + , flagSince = "7.2.1" + } + , flag { flagName = "-XMonoLocalBinds" + , flagDescription = + "Enable :ref:`do not generalise local bindings <mono-local-binds>`. "++ + "Implied by ``-XTypeFamilies`` and ``-XGADTs``." + , flagType = DynamicFlag + , flagReverse = "-XNoMonoLocalBinds" + , flagSince = "6.12.1" + } + , flag { flagName = "-XNoMonomorphismRestriction" + , flagDescription = + "Disable the :ref:`monomorphism restriction <monomorphism>`." + , flagType = DynamicFlag + , flagReverse = "-XMonomorphismRestriction" + , flagSince = "6.8.1" + } + , flag { flagName = "-XMultiParamTypeClasses" + , flagDescription = + "Enable :ref:`multi parameter type classes "++ + "<multi-param-type-classes>`. Implied by "++ + "``-XFunctionalDependencies``." + , flagType = DynamicFlag + , flagReverse = "-XNoMultiParamTypeClasses" + , flagSince = "6.8.1" + } + , flag { flagName = "-XMultiWayIf" + , flagDescription = + "Enable :ref:`multi-way if-expressions <multi-way-if>`." + , flagType = DynamicFlag + , flagReverse = "-XNoMultiWayIf" + , flagSince = "7.6.1" + } + , flag { flagName = "-XNamedFieldPuns" + , flagDescription = "Enable :ref:`record puns <record-puns>`." + , flagType = DynamicFlag + , flagReverse = "-XNoNamedFieldPuns" + , flagSince = "6.10.1" + } + , flag { flagName = "-XNamedWildCards" + , flagDescription = "Enable :ref:`named wildcards <named-wildcards>`." + , flagType = DynamicFlag + , flagReverse = "-XNoNamedWildCards" + , flagSince = "7.10.1" + } + , flag { flagName = "-XNegativeLiterals" + , flagDescription = + "Enable support for :ref:`negative literals <negative-literals>`." + , flagType = DynamicFlag + , flagReverse = "-XNoNegativeLiterals" + , flagSince = "7.8.1" + } + , flag { flagName = "-XNoNPlusKPatterns" + , flagDescription = "Disable support for ``n+k`` patterns." + , flagType = DynamicFlag + , flagReverse = "-XNPlusKPatterns" + , flagSince = "6.12.1" + } + , flag { flagName = "-XNullaryTypeClasses" + , flagDescription = + "Deprecated, does nothing. :ref:`nullary (no parameter) type "++ + "classes <nullary-type-classes>` are now enabled using "++ + "``-XMultiParamTypeClasses``." + , flagType = DynamicFlag + , flagReverse = "-XNoNullaryTypeClasses" + , flagSince = "7.8.1" + } + , flag { flagName = "-XNumDecimals" + , flagDescription = + "Enable support for 'fractional' integer literals." + , flagType = DynamicFlag + , flagReverse = "-XNoNumDecimals" + , flagSince = "7.8.1" + } + , flag { flagName = "-XOverlappingInstances" + , flagDescription = + "Enable :ref:`overlapping instances <instance-overlap>`." + , flagType = DynamicFlag + , flagReverse = "-XNoOverlappingInstances" + , flagSince = "6.8.1" + } + , flag { flagName = "-XOverloadedLists" + , flagDescription = + "Enable :ref:`overloaded lists <overloaded-lists>`." + , flagType = DynamicFlag + , flagReverse = "-XNoOverloadedLists" + , flagSince = "7.8.1" + } + , flag { flagName = "-XOverloadedStrings" + , flagDescription = + "Enable :ref:`overloaded string literals <overloaded-strings>`." + , flagType = DynamicFlag + , flagReverse = "-XNoOverloadedStrings" + , flagSince = "6.8.1" + } + , flag { flagName = "-XPackageImports" + , flagDescription = + "Enable :ref:`package-qualified imports <package-imports>`." + , flagType = DynamicFlag + , flagReverse = "-XNoPackageImports" + , flagSince = "6.10.1" + } + , flag { flagName = "-XParallelArrays" + , flagDescription = + "Enable parallel arrays. Implies ``-XParallelListComp``." + , flagType = DynamicFlag + , flagReverse = "-XNoParallelArrays" + , flagSince = "7.4.1" + } + , flag { flagName = "-XParallelListComp" + , flagDescription = + "Enable :ref:`parallel list comprehensions "++ + "<parallel-list-comprehensions>`. "++ + "Implied by ``-XParallelArrays``." + , flagType = DynamicFlag + , flagReverse = "-XNoParallelListComp" + , flagSince = "6.8.1" + } + , flag { flagName = "-XPartialTypeSignatures" + , flagDescription = + "Enable :ref:`partial type signatures <partial-type-signatures>`." + , flagType = DynamicFlag + , flagReverse = "-XNoPartialTypeSignatures" + , flagSince = "7.10.1" + } + , flag { flagName = "-XPatternGuards" + , flagDescription = "Enable :ref:`pattern guards <pattern-guards>`." + , flagType = DynamicFlag + , flagReverse = "-XNoPatternGuards" + , flagSince = "6.8.1" + } + , flag { flagName = "-XPatternSynonyms" + , flagDescription = + "Enable :ref:`pattern synonyms <pattern-synonyms>`." + , flagType = DynamicFlag + , flagReverse = "-XNoPatternSynonyms" + , flagSince = "7.10.1" + } + , flag { flagName = "-XPolyKinds" + , flagDescription = + "Enable :ref:`kind polymorphism <kind-polymorphism>`. "++ + "Implies ``-XKindSignatures``." + , flagType = DynamicFlag + , flagReverse = "-XNoPolyKinds" + , flagSince = "7.4.1" + } + , flag { flagName = "-XPolymorphicComponents" + , flagDescription = + "Enable :ref:`polymorphic components for data constructors "++ + "<universal-quantification>`. Synonym for ``-XRankNTypes``." + , flagType = DynamicFlag + , flagReverse = "-XNoPolymorphicComponents" + , flagSince = "6.8.1" + } + , flag { flagName = "-XPostfixOperators" + , flagDescription = + "Enable :ref:`postfix operators <postfix-operators>`." + , flagType = DynamicFlag + , flagReverse = "-XNoPostfixOperators" + , flagSince = "7.10.1" + } + , flag { flagName = "-XQuasiQuotes" + , flagDescription = "Enable :ref:`quasiquotation <th-quasiquotation>`." + , flagType = DynamicFlag + , flagReverse = "-XNoQuasiQuotes" + , flagSince = "6.10.1" + } + , flag { flagName = "-XRank2Types" + , flagDescription = + "Enable :ref:`rank-2 types <universal-quantification>`. "++ + "Synonym for ``-XRankNTypes``." + , flagType = DynamicFlag + , flagReverse = "-XNoRank2Types" + , flagSince = "6.8.1" + } + , flag { flagName = "-XRankNTypes" + , flagDescription = + "Enable :ref:`rank-N types <universal-quantification>`. "++ + "Implied by ``-XImpredicativeTypes``." + , flagType = DynamicFlag + , flagReverse = "-XNoRankNTypes" + , flagSince = "6.8.1" + } + , flag { flagName = "-XRebindableSyntax" + , flagDescription = + "Employ :ref:`rebindable syntax <rebindable-syntax>`. "++ + "Implies ``-XNoImplicitPrelude``." + , flagType = DynamicFlag + , flagReverse = "-XNoRebindableSyntax" + , flagSince = "7.0.1" + } + , flag { flagName = "-XRecordWildCards" + , flagDescription = + "Enable :ref:`record wildcards <record-wildcards>`. "++ + "Implies ``-XDisambiguateRecordFields``." + , flagType = DynamicFlag + , flagReverse = "-XNoRecordWildCards" + , flagSince = "6.8.1" + } + , flag { flagName = "-XRecursiveDo" + , flagDescription = + "Enable :ref:`recursive do (mdo) notation <recursive-do-notation>`." + , flagType = DynamicFlag + , flagReverse = "-XNoRecursiveDo" + , flagSince = "6.8.1" + } + , flag { flagName = "-XRelaxedPolyRec" + , flagDescription = + "*(deprecated)* Relaxed checking for :ref:`mutually-recursive "++ + "polymorphic functions <typing-binds>`." + , flagType = DynamicFlag + , flagReverse = "-XNoRelaxedPolyRec" + , flagSince = "6.8.1" + } + , flag { flagName = "-XRoleAnnotations" + , flagDescription = + "Enable :ref:`role annotations <role-annotations>`." + , flagType = DynamicFlag + , flagReverse = "-XNoRoleAnnotations" + , flagSince = "7.10.1" + } + , flag { flagName = "-XSafe" + , flagDescription = + "Enable the :ref:`Safe Haskell <safe-haskell>` Safe mode." + , flagType = DynamicFlag + , flagSince = "7.2.1" + } + , flag { flagName = "-XScopedTypeVariables" + , flagDescription = + "Enable :ref:`lexically-scoped type variables "++ + "<scoped-type-variables>`." + , flagType = DynamicFlag + , flagReverse = "-XNoScopedTypeVariables" + , flagSince = "6.8.1" + } + , flag { flagName = "-XStandaloneDeriving" + , flagDescription = + "Enable :ref:`standalone deriving <stand-alone-deriving>`." + , flagType = DynamicFlag + , flagReverse = "-XNoStandaloneDeriving" + , flagSince = "6.8.1" + } + , flag { flagName = "-XStrictData" + , flagDescription = + "Enable :ref:`default strict datatype fields <strict-data>`." + , flagType = DynamicFlag + , flagReverse = "-XNoStrictData" + } + , flag { flagName = "-XTemplateHaskell" + , flagDescription = + "Enable :ref:`Template Haskell <template-haskell>`." + , flagType = DynamicFlag + , flagReverse = "-XNoTemplateHaskell" + , flagSince = "6.8.1" + } + , flag { flagName = "-XNoTraditionalRecordSyntax" + , flagDescription = + "Disable support for traditional record syntax "++ + "(as supported by Haskell 98) ``C {f = x}``" + , flagType = DynamicFlag + , flagReverse = "-XTraditionalRecordSyntax" + , flagSince = "7.4.1" + } + , flag { flagName = "-XTransformListComp" + , flagDescription = + "Enable :ref:`generalised list comprehensions "++ + "<generalised-list-comprehensions>`." + , flagType = DynamicFlag + , flagReverse = "-XNoTransformListComp" + , flagSince = "6.10.1" + } + , flag { flagName = "-XTrustworthy" + , flagDescription = + "Enable the :ref:`Safe Haskell <safe-haskell>` Trustworthy mode." + , flagType = DynamicFlag + , flagSince = "7.2.1" + } + , flag { flagName = "-XTupleSections" + , flagDescription = "Enable :ref:`tuple sections <tuple-sections>`." + , flagType = DynamicFlag + , flagReverse = "-XNoTupleSections" + , flagSince = "7.10.1" + } + , flag { flagName = "-XTypeFamilies" + , flagDescription = + "Enable :ref:`type families <type-families>`. "++ + "Implies ``-XExplicitNamespaces``, ``-XKindSignatures``, "++ + "and ``-XMonoLocalBinds``." + , flagType = DynamicFlag + , flagReverse = "-XNoTypeFamilies" + , flagSince = "6.8.1" + } + , flag { flagName = "-XTypeOperators" + , flagDescription = + "Enable :ref:`type operators <type-operators>`. "++ + "Implies ``-XExplicitNamespaces``." + , flagType = DynamicFlag + , flagReverse = "-XNoTypeOperators" + , flagSince = "6.8.1" + } + , flag { flagName = "-XTypeSynonymInstances" + , flagDescription = + "Enable :ref:`type synonyms in instance heads "++ + "<flexible-instance-head>`. Implied by ``-XFlexibleInstances``." + , flagType = DynamicFlag + , flagReverse = "-XNoTypeSynonymInstances" + , flagSince = "6.8.1" + } + , flag { flagName = "-XUnboxedTuples" + , flagDescription = "Enable :ref:`unboxed tuples <unboxed-tuples>`." + , flagType = DynamicFlag + , flagReverse = "-XNoUnboxedTuples" + , flagSince = "6.8.1" + } + , flag { flagName = "-XUndecidableInstances" + , flagDescription = + "Enable :ref:`undecidable instances <undecidable-instances>`." + , flagType = DynamicFlag + , flagReverse = "-XNoUndecidableInstances" + , flagSince = "6.8.1" + } + , flag { flagName = "-XUnicodeSyntax" + , flagDescription = "Enable :ref:`unicode syntax <unicode-syntax>`." + , flagType = DynamicFlag + , flagReverse = "-XNoUnicodeSyntax" + , flagSince = "6.8.1" + } + , flag { flagName = "-XUnliftedFFITypes" + , flagDescription = "Enable unlifted FFI types." + , flagType = DynamicFlag + , flagReverse = "-XNoUnliftedFFITypes" + , flagSince = "6.8.1" + } + , flag { flagName = "-XUnsafe" + , flagDescription = + "Enable :ref:`Safe Haskell <safe-haskell>` Unsafe mode." + , flagType = DynamicFlag + , flagSince = "7.4.1" + } + , flag { flagName = "-XViewPatterns" + , flagDescription = "Enable :ref:`view patterns <view-patterns>`." + , flagType = DynamicFlag + , flagReverse = "-XNoViewPatterns" + , flagSince = "6.10.1" + } + ] diff --git a/utils/mkUserGuidePart/Options/Linking.hs b/utils/mkUserGuidePart/Options/Linking.hs new file mode 100644 index 0000000000..cc42db80ff --- /dev/null +++ b/utils/mkUserGuidePart/Options/Linking.hs @@ -0,0 +1,162 @@ +module Options.Linking where + +import Types + +linkingOptions :: [Flag] +linkingOptions = + [ flag { flagName = "-shared" + , flagDescription = + "Generate a shared library (as opposed to an executable)" + , flagType = DynamicFlag + } + , flag { flagName = "-staticlib" + , flagDescription = + "On Darwin/OS X/iOS only, generate a standalone static library " ++ + "(as opposed to an executable). This is the usual way to " ++ + "compile for iOS." + , flagType = DynamicFlag + } + , flag { flagName = "-fPIC" + , flagDescription = + "Generate position-independent code (where available)" + , flagType = DynamicFlag + } + , flag { flagName = "-dynamic" + , flagDescription = "Use dynamic Haskell libraries (if available)" + , flagType = DynamicFlag + } + , flag { flagName = "-dynamic-too" + , flagDescription = + "Build dynamic object files *as well as* static object files " ++ + "during compilation" + , flagType = DynamicFlag + } + , flag { flagName = "-dyno" + , flagDescription = + "Set the output path for the *dynamically* linked objects" + , flagType = DynamicFlag + } + , flag { flagName = "-dynosuf" + , flagDescription = "Set the output suffix for dynamic object files" + , flagType = DynamicFlag + } + , flag { flagName = "-dynload" + , flagDescription = + "Selects one of a number of modes for finding shared libraries at runtime." + , flagType = DynamicFlag + } + , flag { flagName = "-framework⟨name⟩" + , flagDescription = + "On Darwin/OS X/iOS only, link in the framework ⟨name⟩. This " ++ + "option corresponds to the ``-framework`` option for Apple's Linker." + , flagType = DynamicFlag + } + , flag { flagName = "-framework-path⟨name⟩" + , flagDescription = + "On Darwin/OS X/iOS only, add ⟨dir⟩ to the list of directories " ++ + "searched for frameworks. This option corresponds to the ``-F`` "++ + "option for Apple's Linker." + , flagType = DynamicFlag + } + , flag { flagName = "-l⟨lib⟩" + , flagDescription = "Link in library ⟨lib⟩" + , flagType = DynamicFlag + } + , flag { flagName = "-L⟨dir⟩" + , flagDescription = + "Add ⟨dir⟩ to the list of directories searched for libraries" + , flagType = DynamicFlag + } + , flag { flagName = "-main-is" + , flagDescription = "Set main module and function" + , flagType = DynamicFlag + } + , flag { flagName = "--mk-dll" + , flagDescription = "DLL-creation mode (Windows only)" + , flagType = DynamicFlag + } + , flag { flagName = "-no-hs-main" + , flagDescription = "Don't assume this program contains ``main``" + , flagType = DynamicFlag + } + , flag { flagName = "-rtsopts,-rtsopts={none,some,all}" + , flagDescription = + "Control whether the RTS behaviour can be tweaked via command-line"++ + "flags and the ``GHCRTS`` environment variable. Using ``none`` " ++ + "means no RTS flags can be given; ``some`` means only a minimum " ++ + "of safe options can be given (the default), and ``all`` (or no " ++ + "argument at all) means that all RTS flags are permitted." + , flagType = DynamicFlag + } + , flag { flagName = "-with-rtsopts=opts" + , flagDescription = "Set the default RTS options to ⟨opts⟩." + , flagType = DynamicFlag + } + , flag { flagName = "-no-rtsopts-suggestions" + , flagDescription = + "Don't print RTS suggestions about linking with ``-rtsopts``." + , flagType = DynamicFlag + } + , flag { flagName = "-no-link" + , flagDescription = "Omit linking" + , flagType = DynamicFlag + } + , flag { flagName = "-split-objs" + , flagDescription = "Split objects (for libraries)" + , flagType = DynamicFlag + } + , flag { flagName = "-static" + , flagDescription = "Use static Haskell libraries" + , flagType = DynamicFlag + } + , flag { flagName = "-threaded" + , flagDescription = "Use the threaded runtime" + , flagType = DynamicFlag + } + , flag { flagName = "-debug" + , flagDescription = "Use the debugging runtime" + , flagType = DynamicFlag + } + , flag { flagName = "-ticky" + , flagDescription = + "For linking, this simply implies ``-debug``; "++ + "see :ref:`ticky-ticky`." + , flagType = DynamicFlag + } + , flag { flagName = "-eventlog" + , flagDescription = "Enable runtime event tracing" + , flagType = DynamicFlag + } + , flag { flagName = "-fno-gen-manifest" + , flagDescription = "Do not generate a manifest file (Windows only)" + , flagType = DynamicFlag + } + , flag { flagName = "-fno-embed-manifest" + , flagDescription = + "Do not embed the manifest in the executable (Windows only)" + , flagType = DynamicFlag + } + , flag { flagName = "-fno-shared-implib" + , flagDescription = + "Don't generate an import library for a DLL (Windows only)" + , flagType = DynamicFlag + } + , flag { flagName = "-dylib-install-name ⟨path⟩" + , flagDescription = + "Set the install name (via ``-install_name`` passed to Apple's " ++ + "linker), specifying the full install path of the library file. " ++ + "Any libraries or executables that link with it later will pick " ++ + "up that path as their runtime search location for it. " ++ + "(Darwin/OS X only)" + , flagType = DynamicFlag + } + , flag { flagName = "-rdynamic" + , flagDescription = + "This instructs the linker to add all symbols, not only used " ++ + "ones, to the dynamic symbol table. Currently Linux and " ++ + "Windows/MinGW32 only. This is equivalent to using " ++ + "``-optl -rdynamic`` on Linux, and ``-optl -export-all-symbols`` " ++ + "on Windows." + , flagType = DynamicFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/Misc.hs b/utils/mkUserGuidePart/Options/Misc.hs new file mode 100644 index 0000000000..d6a4c4eaec --- /dev/null +++ b/utils/mkUserGuidePart/Options/Misc.hs @@ -0,0 +1,32 @@ +module Options.Misc where + +import Types + +miscOptions :: [Flag] +miscOptions = + [ flag { flagName = "-jN" + , flagDescription = + "When compiling with ``--make``, compile ⟨N⟩ modules in parallel." + , flagType = DynamicFlag + } + , flag { flagName = "-fno-hi-version-check" + , flagDescription = "Don't complain about ``.hi`` file mismatches" + , flagType = DynamicFlag + } + , flag { flagName = "-fhistory-size" + , flagDescription = "Set simplification history size" + , flagType = DynamicFlag + } + , flag { flagName = "-fno-ghci-history" + , flagDescription = + "Do not use the load/store the GHCi command history from/to "++ + "``ghci_history``." + , flagType = DynamicFlag + } + , flag { flagName = "-fno-ghci-sandbox" + , flagDescription = + "Turn off the GHCi sandbox. Means computations are run in "++ + "the main thread, rather than a forked thread." + , flagType = DynamicFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/Modes.hs b/utils/mkUserGuidePart/Options/Modes.hs new file mode 100644 index 0000000000..57aaef26f2 --- /dev/null +++ b/utils/mkUserGuidePart/Options/Modes.hs @@ -0,0 +1,63 @@ +module Options.Modes where + +import Types + +modeOptions :: [Flag] +modeOptions = + [ flag { flagName = "--help,-?" + , flagDescription = "Display help" + , flagType = ModeFlag + } + , flag { flagName = "--interactive" + , flagDescription = + "Interactive mode - normally used by just running ``ghci``; "++ + "see :ref:`ghci` for details." + , flagType = ModeFlag + } + , flag { flagName = "--make" + , flagDescription = + "Build a multi-module Haskell program, automatically figuring out "++ + "dependencies. Likely to be much easier, and faster, than using "++ + "``make``; see :ref:`make-mode` for details." + , flagType = ModeFlag + } + , flag { flagName = "-e expr" + , flagDescription = + "Evaluate ``expr``; see :ref:`eval-mode` for details." + , flagType = ModeFlag + } + , flag { flagName = "--show-iface" + , flagDescription = "display the contents of an interface file." + , flagType = ModeFlag + } + , flag { flagName = "-M" + , flagDescription = + "denerate dependency information suitable for use in a "++ + "``Makefile``; see :ref:`makefile-dependencies` for details." + , flagType = ModeFlag + } + , flag { flagName = "--supported-extensions, --supported-languages" + , flagDescription = "display the supported language extensions" + , flagType = ModeFlag + } + , flag { flagName = "--show-options" + , flagDescription = "display the supported command line options" + , flagType = ModeFlag + } + , flag { flagName = "--info" + , flagDescription = "display information about the compiler" + , flagType = ModeFlag + } + , flag { flagName = "--version, -V" + , flagDescription = "display GHC version" + , flagType = ModeFlag + } + , flag { flagName = "--numeric-version" + , flagDescription = "display GHC version (numeric only)" + , flagType = ModeFlag + } + , flag { flagName = "--print-libdir" + , flagDescription = "display GHC library directory" + , flagType = ModeFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/OptimizationLevels.hs b/utils/mkUserGuidePart/Options/OptimizationLevels.hs new file mode 100644 index 0000000000..a57fc5291b --- /dev/null +++ b/utils/mkUserGuidePart/Options/OptimizationLevels.hs @@ -0,0 +1,29 @@ +module Options.OptimizationLevels where + +import Types + +optimizationLevelsOptions :: [Flag] +optimizationLevelsOptions = + [ flag { flagName = "-O0" + , flagDescription = "Disable optimisations (default)" + , flagType = DynamicFlag + , flagReverse = "-O" + } + , flag { flagName = "-O, -O1" + , flagDescription = "Enable level 1 optimisations" + , flagType = DynamicFlag + , flagReverse = "-O0" + } + , flag { flagName = "-O2" + , flagDescription = "Enable level 2 optimisations" + , flagType = DynamicFlag + , flagReverse = "-O0" + } + , flag { flagName = "-Odph" + , flagDescription = + "Enable level 2 optimisations, set "++ + "``-fmax-simplifier-iterations=20`` "++ + "and ``-fsimplifier-phases=3``." + , flagType = DynamicFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/Optimizations.hs b/utils/mkUserGuidePart/Options/Optimizations.hs new file mode 100644 index 0000000000..0082a210fb --- /dev/null +++ b/utils/mkUserGuidePart/Options/Optimizations.hs @@ -0,0 +1,344 @@ +module Options.Optimizations where + +import Types + +optimizationsOptions :: [Flag] +optimizationsOptions = + [ flag { flagName = "-fcall-arity" + , flagDescription = + "Enable call-arity optimisation. Implied by ``-O``." + , flagType = DynamicFlag + , flagReverse = "-fno-call-arity" + } + , flag { flagName = "-fcase-merge" + , flagDescription = "Enable case-merging. Implied by ``-O``." + , flagType = DynamicFlag + , flagReverse = "-fno-case-merge" + } + , flag { flagName = "-fcmm-elim-common-blocks" + , flagDescription = + "Enable Cmm common block elimination. Implied by ``-O``." + , flagType = DynamicFlag + , flagReverse = "-fno-cmm-elim-common-blocks" + } + , flag { flagName = "-fcmm-sink" + , flagDescription = "Enable Cmm sinking. Implied by ``-O``." + , flagType = DynamicFlag + , flagReverse = "-fno-cmm-sink" + } + , flag { flagName = "-fcpr-anal" + , flagDescription = + "Turn on CPR analysis in the demand analyser. Implied by ``-O``." + , flagType = DynamicFlag + , flagReverse = "-fno-cpr-anal" + } + , flag { flagName = "-fcse" + , flagDescription = + "Enable common sub-expression elimination. Implied by ``-O``." + , flagType = DynamicFlag + , flagReverse = "-fno-cse" + } + , flag { flagName = "-fdicts-cheap" + , flagDescription = + "Make dictionary-valued expressions seem cheap to the optimiser." + , flagType = DynamicFlag + , flagReverse = "-fno-dicts-cheap" + } + , flag { flagName = "-fdicts-strict" + , flagDescription = "Make dictionaries strict" + , flagType = DynamicFlag + , flagReverse = "-fno-dicts-strict" + } + , flag { flagName = "-fdmd-tx-dict-sel" + , flagDescription = + "Use a special demand transformer for dictionary selectors. "++ + "Always enabled by default." + , flagType = DynamicFlag + , flagReverse = "-fno-dmd-tx-dict-sel" + } + , flag { flagName = "-fdo-eta-reduction" + , flagDescription = "Enable eta-reduction. Implied by ``-O``." + , flagType = DynamicFlag + , flagReverse = "-fno-do-eta-reduction" + } + , flag { flagName = "-fdo-lambda-eta-expansion" + , flagDescription = + "Enable lambda eta-expansion. Always enabled by default." + , flagType = DynamicFlag + , flagReverse = "-fno-do-lambda-eta-expansion" + } + , flag { flagName = "-feager-blackholing" + , flagDescription = + "Turn on :ref:`eager blackholing <parallel-compile-options>`" + , flagType = DynamicFlag + } + , flag { flagName = "-fenable-rewrite-rules" + , flagDescription = + "Switch on all rewrite rules (including rules generated by "++ + "automatic specialisation of overloaded functions). Implied by "++ + "``-O``." + , flagType = DynamicFlag + , flagReverse = "-fno-enable-rewrite-rules" + } + , flag { flagName = "-fexcess-precision" + , flagDescription = "Enable excess intermediate precision" + , flagType = DynamicFlag + , flagReverse = "-fno-excess-precision" + } + , flag { flagName = "-fexpose-all-unfoldings" + , flagDescription = + "Expose all unfoldings, even for very large or recursive functions." + , flagType = DynamicFlag + , flagReverse = "-fno-expose-all-unfoldings" + } + , flag { flagName = "-ffloat-in" + , flagDescription = + "Turn on the float-in transformation. Implied by ``-O``." + , flagType = DynamicFlag + , flagReverse = "-fno-float-in" + } + , flag { flagName = "-ffull-laziness" + , flagDescription = + "Turn on full laziness (floating bindings outwards). "++ + "Implied by ``-O``." + , flagType = DynamicFlag + , flagReverse = "-fno-full-laziness" + } + , flag { flagName = "-ffun-to-thunk" + , flagDescription = + "Allow worker-wrapper to convert a function closure into a thunk "++ + "if the function does not use any of its arguments. Off by default." + , flagType = DynamicFlag + , flagReverse = "-fno-fun-to-thunk" + } + , flag { flagName = "-fignore-asserts" + , flagDescription = + "Ignore assertions in the source. Implied by ``-O``." + , flagType = DynamicFlag + , flagReverse = "-fno-ignore-asserts" + } + , flag { flagName = "-fignore-interface-pragmas" + , flagDescription = + "Ignore pragmas in interface files. Implied by ``-O0`` only." + , flagType = DynamicFlag + , flagReverse = "-fno-ignore-interface-pragmas" + } + , flag { flagName = "-flate-dmd-anal" + , flagDescription = + "Run demand analysis again, at the end of the "++ + "simplification pipeline" + , flagType = DynamicFlag + , flagReverse = "-fno-late-dmd-anal" + } + , flag { flagName = "-fliberate-case" + , flagDescription = + "Turn on the liberate-case transformation. Implied by ``-O2``." + , flagType = DynamicFlag + , flagReverse = "-fno-liberate-case" + } + , flag { flagName = "-fliberate-case-threshold=⟨n⟩" + , flagDescription = + "*default: 2000.* Set the size threshold for the liberate-case "++ + "transformation to ⟨n⟩" + , flagType = DynamicFlag + , flagReverse = "-fno-liberate-case-threshold" + } + , flag { flagName = "-floopification" + , flagDescription = + "Turn saturated self-recursive tail-calls into local jumps in the "++ + "generated assembly. Implied by ``-O``." + , flagType = DynamicFlag + , flagReverse = "-fno-loopification" + } + , flag { flagName = "-fmax-inline-alloc-size=⟨n⟩" + , flagDescription = + "*default: 128.* Set the maximum size of inline array allocations "++ + "to ⟨n⟩ bytes (default: 128). GHC will allocate non-pinned arrays "++ + "of statically known size in the current nursery block if they're "++ + "no bigger than ⟨n⟩ bytes, ignoring GC overheap. This value should "++ + "be quite a bit smaller than the block size (typically: 4096)." + , flagType = DynamicFlag + } + , flag { flagName = "-fmax-inline-memcpy-insns=⟨n⟩" + , flagDescription = + "*default: 32.* Inline ``memcpy`` calls if they would generate no "++ + "more than ⟨n⟩ pseudo instructions." + , flagType = DynamicFlag + } + , flag { flagName = "-fmax-inline-memset-insns=⟨n⟩" + , flagDescription = + "*default: 32.* Inline ``memset`` calls if they would generate no "++ + "more than ⟨n⟩ pseudo instructions" + , flagType = DynamicFlag + } + , flag { flagName = "-fmax-relevant-binds=⟨n⟩" + , flagDescription = + "*default: 6.* Set the maximum number of bindings to display in "++ + "type error messages." + , flagType = DynamicFlag + , flagReverse = "-fno-max-relevant-bindings" + } + , flag { flagName = "-fmax-simplifier-iterations=⟨n⟩" + , flagDescription = + "*default: 4.* Set the max iterations for the simplifier." + , flagType = DynamicFlag + } + , flag { flagName = "-fmax-worker-args=⟨n⟩" + , flagDescription = + "*default: 10.* If a worker has that many arguments, none will "++ + "be unpacked anymore." + , flagType = DynamicFlag + } + , flag { flagName = "-fno-opt-coercion" + , flagDescription = "Turn off the coercion optimiser" + , flagType = StaticFlag + } + , flag { flagName = "-fno-pre-inlining" + , flagDescription = "Turn off pre-inlining" + , flagType = DynamicFlag + } + , flag { flagName = "-fno-state-hack" + , flagDescription = + "Turn off the \"state hack\" whereby any lambda with a real-world "++ + "state token as argument is considered to be single-entry. Hence "++ + "OK to inline things inside it." + , flagType = StaticFlag + } + , flag { flagName = "-fomit-interface-pragmas" + , flagDescription = + "Don't generate interface pragmas. Implied by ``-O0`` only." + , flagType = DynamicFlag + , flagReverse = "-fno-omit-interface-pragmas" + } + , flag { flagName = "-fomit-yields" + , flagDescription = + "Omit heap checks when no allocation is being performed." + , flagType = DynamicFlag + , flagReverse = "-fno-omit-yields" + } + , flag { flagName = "-fpedantic-bottoms" + , flagDescription = + "Make GHC be more precise about its treatment of bottom (but see "++ + "also ``-fno-state-hack``). In particular, GHC will not "++ + "eta-expand through a case expression." + , flagType = DynamicFlag + , flagReverse = "-fno-pedantic-bottoms" + } + , flag { flagName = "-fregs-graph" + , flagDescription = + "Use the graph colouring register allocator for register "++ + "allocation in the native code generator. Implied by ``-O2``." + , flagType = DynamicFlag + , flagReverse = "-fno-regs-graph" + } + , flag { flagName = "-fregs-iterative" + , flagDescription = + "Use the iterative coalescing graph colouring register allocator "++ + "in the native code generator." + , flagType = DynamicFlag + , flagReverse = "-fno-regs-iterative" + } + , flag { flagName = "-fsimplifier-phases=⟨n⟩" + , flagDescription = + "*default: 2.* Set the number of phases for the simplifier. "++ + "Ignored with ``-O0``." + , flagType = DynamicFlag + } + , flag { flagName = "-fsimpl-tick-factor=⟨n⟩" + , flagDescription = + "*default: 100.* Set the percentage factor for simplifier ticks." + , flagType = DynamicFlag + } + , flag { flagName = "-fspec-constr" + , flagDescription = + "Turn on the SpecConstr transformation. Implied by ``-O2``." + , flagType = DynamicFlag + , flagReverse = "-fno-spec-constr" + } + , flag { flagName = "-fspec-constr-count=⟨n⟩" + , flagDescription = + "default: 3.* Set to ⟨n⟩ the maximum number of specialisations that"++ + " will be created for any one function by the SpecConstr "++ + "transformation." + , flagType = DynamicFlag + , flagReverse = "-fno-spec-constr-count" + } + , flag { flagName = "-fspec-constr-threshold=⟨n⟩" + , flagDescription = + "*default: 2000.* Set the size threshold for the SpecConstr "++ + "transformation to ⟨n⟩." + , flagType = DynamicFlag + , flagReverse = "-fno-spec-constr-threshold" + } + , flag { flagName = "-fspecialise" + , flagDescription = + "Turn on specialisation of overloaded functions. Implied by ``-O``." + , flagType = DynamicFlag + , flagReverse = "-fno-specialise" + } + , flag { flagName = "-fcross-module-specialise" + , flagDescription = + "Turn on specialisation of overloaded functions imported from "++ + "other modules." + , flagType = DynamicFlag + , flagReverse = "-fno-cross-module-specialise" + } + , flag { flagName = "-fstatic-argument-transformation" + , flagDescription = "Turn on the static argument transformation." + , flagType = DynamicFlag + , flagReverse = "-fno-static-argument-transformation" + } + , flag { flagName = "-fstrictness" + , flagDescription = "Turn on strictness analysis. Implied by ``-O``." + , flagType = DynamicFlag + , flagReverse = "-fno-strictness" + } + , flag { flagName = "-fstrictness-before=⟨n⟩" + , flagDescription = + "Run an additional strictness analysis before simplifier phase ⟨n⟩" + , flagType = DynamicFlag + } + , flag { flagName = "-funbox-small-strict-fields" + , flagDescription = + "Flatten strict constructor fields with a pointer-sized "++ + "representation. Implied by ``-O``." + , flagType = DynamicFlag + , flagReverse = "-fno-unbox-small-strict-fields" + } + , flag { flagName = "-funbox-strict-fields" + , flagDescription = "Flatten strict constructor fields" + , flagType = DynamicFlag + , flagReverse = "-fno-unbox-strict-fields" + } + , flag { flagName = "-funfolding-creation-threshold=⟨n⟩" + , flagDescription = "*default: 750.* Tweak unfolding settings." + , flagType = DynamicFlag + } + , flag { flagName = "-funfolding-dict-discount=⟨n⟩" + , flagDescription = "*default: 30.* Tweak unfolding settings." + , flagType = DynamicFlag + } + , flag { flagName = "-funfolding-fun-discount=⟨n⟩" + , flagDescription = "*default: 60.* Tweak unfolding settings." + , flagType = DynamicFlag + } + , flag { flagName = "-funfolding-keeness-factor=⟨n⟩" + , flagDescription = "*default: 1.5.* Tweak unfolding settings." + , flagType = DynamicFlag + } + , flag { flagName = "-funfolding-use-threshold=⟨n⟩" + , flagDescription = "*default: 60.* Tweak unfolding settings." + , flagType = DynamicFlag + } + , flag { flagName = "-fvectorisation-avoidance" + , flagDescription = + "Enable vectorisation avoidance. Always enabled by default." + , flagType = DynamicFlag + , flagReverse = "-fno-vectorisation-avoidance" + } + , flag { flagName = "-fvectorise" + , flagDescription = "Enable vectorisation of nested data parallelism" + , flagType = DynamicFlag + , flagReverse = "-fno-vectorise" + } + ] diff --git a/utils/mkUserGuidePart/Options/Packages.hs b/utils/mkUserGuidePart/Options/Packages.hs new file mode 100644 index 0000000000..c6dfa0b86f --- /dev/null +++ b/utils/mkUserGuidePart/Options/Packages.hs @@ -0,0 +1,67 @@ +module Options.Packages where + +import Types + +packagesOptions :: [Flag] +packagesOptions = + [ flag { flagName = "-this-package-key⟨P⟩" + , flagDescription = "Compile to be part of package ⟨P⟩" + , flagType = DynamicFlag + } + , flag { flagName = "-package⟨P⟩" + , flagDescription = "Expose package ⟨P⟩" + , flagType = DynamicSettableFlag + } + , flag { flagName = "-hide-all-packages" + , flagDescription = "Hide all packages by default" + , flagType = DynamicFlag + } + , flag { flagName = "-hide-package⟨name⟩" + , flagDescription = "Hide package ⟨P⟩" + , flagType = DynamicSettableFlag + } + , flag { flagName = "-ignore-package⟨name⟩" + , flagDescription = "Ignore package ⟨P⟩" + , flagType = DynamicSettableFlag + } + , flag { flagName = "-package-db⟨file⟩" + , flagDescription = "Add ⟨file⟩ to the package db stack." + , flagType = DynamicFlag + } + , flag { flagName = "-clear-package-db" + , flagDescription = "Clear the package db stack." + , flagType = DynamicFlag + } + , flag { flagName = "-no-global-package-db" + , flagDescription = "Remove the global package db from the stack." + , flagType = DynamicFlag + } + , flag { flagName = "-global-package-db" + , flagDescription = "Add the global package db to the stack." + , flagType = DynamicFlag + } + , flag { flagName = "-no-user-package-db" + , flagDescription = "Remove the user's package db from the stack." + , flagType = DynamicFlag + } + , flag { flagName = "-user-package-db" + , flagDescription = "Add the user's package db to the stack." + , flagType = DynamicFlag + } + , flag { flagName = "-no-auto-link-packages" + , flagDescription = "Don't automatically link in the base and rts packages." + , flagType = DynamicFlag + } + , flag { flagName = "-trust⟨P⟩" + , flagDescription = "Expose package ⟨P⟩ and set it to be trusted" + , flagType = DynamicSettableFlag + } + , flag { flagName = "-distrust⟨P⟩" + , flagDescription = "Expose package ⟨P⟩ and set it to be distrusted" + , flagType = DynamicSettableFlag + } + , flag { flagName = "-distrust-all" + , flagDescription = "Distrust all packages by default" + , flagType = DynamicSettableFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/PhasePrograms.hs b/utils/mkUserGuidePart/Options/PhasePrograms.hs new file mode 100644 index 0000000000..65ead95178 --- /dev/null +++ b/utils/mkUserGuidePart/Options/PhasePrograms.hs @@ -0,0 +1,58 @@ +module Options.PhasePrograms where + +import Types + +phaseProgramsOptions :: [Flag] +phaseProgramsOptions = + [ flag { flagName = "-pgmL⟨cmd⟩" + , flagDescription = "Use ⟨cmd⟩ as the literate pre-processor" + , flagType = DynamicFlag + } + , flag { flagName = "-pgmP⟨cmd⟩" + , flagDescription = + "Use ⟨cmd⟩ as the C pre-processor (with ``-cpp`` only)" + , flagType = DynamicFlag + } + , flag { flagName = "-pgmc⟨cmd⟩" + , flagDescription = "Use ⟨cmd⟩ as the C compiler" + , flagType = DynamicFlag + } + , flag { flagName = "-pgmlo⟨cmd⟩" + , flagDescription = "Use ⟨cmd⟩ as the LLVM optimiser" + , flagType = DynamicFlag + } + , flag { flagName = "-pgmlc⟨cmd⟩" + , flagDescription = "Use ⟨cmd⟩ as the LLVM compiler" + , flagType = DynamicFlag + } + , flag { flagName = "-pgms⟨cmd⟩" + , flagDescription = "Use ⟨cmd⟩ as the splitter" + , flagType = DynamicFlag + } + , flag { flagName = "-pgma⟨cmd⟩" + , flagDescription = "Use ⟨cmd⟩ as the assembler" + , flagType = DynamicFlag + } + , flag { flagName = "-pgml⟨cmd⟩" + , flagDescription = "Use ⟨cmd⟩ as the linker" + , flagType = DynamicFlag + } + , flag { flagName = "-pgmdll⟨cmd⟩" + , flagDescription = "Use ⟨cmd⟩ as the DLL generator" + , flagType = DynamicFlag + } + , flag { flagName = "-pgmF⟨cmd⟩" + , flagDescription = "Use ⟨cmd⟩ as the pre-processor (with ``-F`` only)" + , flagType = DynamicFlag + } + , flag { flagName = "-pgmwindres⟨cmd⟩" + , flagDescription = + "Use ⟨cmd⟩ as the program for embedding manifests on Windows." + , flagType = DynamicFlag + } + , flag { flagName = "-pgmlibtool⟨cmd⟩" + , flagDescription = + "Use ⟨cmd⟩ as the command for libtool (with ``-staticlib`` only)." + , flagType = DynamicFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/PhaseSpecific.hs b/utils/mkUserGuidePart/Options/PhaseSpecific.hs new file mode 100644 index 0000000000..cbd79f18a4 --- /dev/null +++ b/utils/mkUserGuidePart/Options/PhaseSpecific.hs @@ -0,0 +1,47 @@ +module Options.PhaseSpecific where + +import Types + +phaseSpecificOptions :: [Flag] +phaseSpecificOptions = + [ flag { flagName = "-optL⟨option⟩" + , flagDescription = "pass ⟨option⟩ to the literate pre-processor" + , flagType = DynamicFlag + } + , flag { flagName = "-optP⟨option⟩" + , flagDescription = "pass ⟨option⟩ to cpp (with ``-cpp`` only)" + , flagType = DynamicFlag + } + , flag { flagName = "-optF⟨option⟩" + , flagDescription = "pass ⟨option⟩ to the custom pre-processor" + , flagType = DynamicFlag + } + , flag { flagName = "-optc⟨option⟩" + , flagDescription = "pass ⟨option⟩ to the C compiler" + , flagType = DynamicFlag + } + , flag { flagName = "-optlo⟨option⟩" + , flagDescription = "pass ⟨option⟩ to the LLVM optimiser" + , flagType = DynamicFlag + } + , flag { flagName = "-optlc⟨option⟩" + , flagDescription = "pass ⟨option⟩ to the LLVM compiler" + , flagType = DynamicFlag + } + , flag { flagName = "-opta⟨option⟩" + , flagDescription = "pass ⟨option⟩ to the assembler" + , flagType = DynamicFlag + } + , flag { flagName = "-optl⟨option⟩" + , flagDescription = "pass ⟨option⟩ to the linker" + , flagType = DynamicFlag + } + , flag { flagName = "-optdll⟨option⟩" + , flagDescription = "pass ⟨option⟩ to the DLL generator" + , flagType = DynamicFlag + } + , flag { flagName = "-optwindres⟨option⟩" + , flagDescription = "pass ⟨option⟩ to ``windres``." + , flagType = DynamicFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/Phases.hs b/utils/mkUserGuidePart/Options/Phases.hs new file mode 100644 index 0000000000..230eda1495 --- /dev/null +++ b/utils/mkUserGuidePart/Options/Phases.hs @@ -0,0 +1,33 @@ +module Options.Phases where + +import Types + +phaseOptions :: [Flag] +phaseOptions = + [ flag { flagName = "-F" + , flagDescription = + "Enable the use of a :ref:`pre-processor <pre-processor>` "++ + "(set with ``-pgmF``)" + , flagType = DynamicFlag + } + , flag { flagName = "-E" + , flagDescription = "Stop after preprocessing (``.hspp`` file)" + , flagType = ModeFlag + } + , flag { flagName = "-C" + , flagDescription = "Stop after generating C (``.hc`` file)" + , flagType = ModeFlag + } + , flag { flagName = "-S" + , flagDescription = "Stop after generating assembly (``.s`` file)" + , flagType = ModeFlag + } + , flag { flagName = "-c" + , flagDescription = "Stop after generating object (``.o``) file" + , flagType = ModeFlag + } + , flag { flagName = "-x⟨suffix⟩" + , flagDescription = "Override default behaviour for source files" + , flagType = DynamicFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/PlatformSpecific.hs b/utils/mkUserGuidePart/Options/PlatformSpecific.hs new file mode 100644 index 0000000000..8d43665ea9 --- /dev/null +++ b/utils/mkUserGuidePart/Options/PlatformSpecific.hs @@ -0,0 +1,15 @@ +module Options.PlatformSpecific where + +import Types + +platformSpecificOptions :: [Flag] +platformSpecificOptions = + [ flag { flagName = "-msse2" + , flagDescription = "(x86 only) Use SSE2 for floating-point operations" + , flagType = DynamicFlag + } + , flag { flagName = "-msse4.2" + , flagDescription = "(x86 only) Use SSE4.2 for floating-point operations" + , flagType = DynamicFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/Plugin.hs b/utils/mkUserGuidePart/Options/Plugin.hs new file mode 100644 index 0000000000..1ae7d6e536 --- /dev/null +++ b/utils/mkUserGuidePart/Options/Plugin.hs @@ -0,0 +1,17 @@ +module Options.Plugin where + +import Types + +pluginOptions :: [Flag] +pluginOptions = + [ flag { flagName = "-fplugin=⟨module⟩" + , flagDescription = "Load a plugin exported by a given module" + , flagType = DynamicFlag + } + , flag { flagName = "-fplugin-opt=⟨module:args⟩" + , flagDescription = + "Give arguments to a plugin module; module must be specified with "++ + "``-fplugin``" + , flagType = DynamicFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/Profiling.hs b/utils/mkUserGuidePart/Options/Profiling.hs new file mode 100644 index 0000000000..af3853fafc --- /dev/null +++ b/utils/mkUserGuidePart/Options/Profiling.hs @@ -0,0 +1,44 @@ +module Options.Profiling where + +import Types + +profilingOptions :: [Flag] +profilingOptions = + [ flag { flagName = "-prof" + , flagDescription = "Turn on profiling" + , flagType = DynamicFlag + } + , flag { flagName = "-fprof-auto" + , flagDescription = + "Auto-add ``SCC``\\ s to all bindings not marked INLINE" + , flagType = DynamicFlag + , flagReverse = "-fno-prof-auto" + } + , flag { flagName = "-fprof-auto-top" + , flagDescription = + "Auto-add ``SCC``\\ s to all top-level bindings not marked INLINE" + , flagType = DynamicFlag + , flagReverse = "-fno-prof-auto" + } + , flag { flagName = "-fprof-auto-exported" + , flagDescription = + "Auto-add ``SCC``\\ s to all exported bindings not marked INLINE" + , flagType = DynamicFlag + , flagReverse = "-fno-prof-auto" + } + , flag { flagName = "-fprof-cafs" + , flagDescription = "Auto-add ``SCC``\\ s to all CAFs" + , flagType = DynamicFlag + , flagReverse = "-fno-prof-cafs" + } + , flag { flagName = "-fno-prof-count-entries" + , flagDescription = "Do not collect entry counts" + , flagType = DynamicFlag + , flagReverse = "-fprof-count-entries" + } + , flag { flagName = "-ticky" + , flagDescription = + ":ref:`Turn on ticky-ticky profiling <ticky-ticky>`" + , flagType = DynamicFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/ProgramCoverage.hs b/utils/mkUserGuidePart/Options/ProgramCoverage.hs new file mode 100644 index 0000000000..c7b2894668 --- /dev/null +++ b/utils/mkUserGuidePart/Options/ProgramCoverage.hs @@ -0,0 +1,18 @@ +module Options.ProgramCoverage where + +import Types + +programCoverageOptions :: [Flag] +programCoverageOptions = + [ flag { flagName = "-fhpc" + , flagDescription = + "Turn on Haskell program coverage instrumentation" + , flagType = DynamicFlag + } + , flag { flagName = "-hpcdir dir" + , flagDescription = + "Directory to deposit ``.mix`` files during compilation "++ + "(default is ``.hpc``)" + , flagType = DynamicFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/RecompilationChecking.hs b/utils/mkUserGuidePart/Options/RecompilationChecking.hs new file mode 100644 index 0000000000..1dec661f40 --- /dev/null +++ b/utils/mkUserGuidePart/Options/RecompilationChecking.hs @@ -0,0 +1,15 @@ +module Options.RecompilationChecking where + +import Types + +recompilationCheckingOptions :: [Flag] +recompilationCheckingOptions = + [ flag { flagName = "-fforce-recomp" + , flagDescription = + "Turn off recompilation checking. This is implied by any " ++ + "``-ddump-X`` option when compiling a single file " ++ + "(i.e. when using ``-c``)." + , flagType = DynamicFlag + , flagReverse = "-fno-force-recomp" + } + ] diff --git a/utils/mkUserGuidePart/Options/RedirectingOutput.hs b/utils/mkUserGuidePart/Options/RedirectingOutput.hs new file mode 100644 index 0000000000..9435e26668 --- /dev/null +++ b/utils/mkUserGuidePart/Options/RedirectingOutput.hs @@ -0,0 +1,47 @@ +module Options.RedirectingOutput where + +import Types + +redirectingOutputOptions :: [Flag] +redirectingOutputOptions = + [ flag { flagName = "-hcsuf ⟨suffix⟩" + , flagDescription = "set the suffix to use for intermediate C files" + , flagType = DynamicFlag + } + , flag { flagName = "-hidir ⟨dir⟩" + , flagDescription = "set directory for interface files" + , flagType = DynamicFlag + } + , flag { flagName = "-hisuf ⟨suffix⟩" + , flagDescription = "set the suffix to use for interface files" + , flagType = DynamicFlag + } + , flag { flagName = "-o ⟨filename⟩" + , flagDescription = "set output filename" + , flagType = DynamicFlag + } + , flag { flagName = "-odir ⟨dir⟩" + , flagDescription = "set directory for object files" + , flagType = DynamicFlag + } + , flag { flagName = "-ohi ⟨filename⟩" + , flagDescription = "set the filename in which to put the interface" + , flagType = DynamicFlag + } + , flag { flagName = "-osuf ⟨suffix⟩" + , flagDescription = "set the output file suffix" + , flagType = DynamicFlag + } + , flag { flagName = "-stubdir ⟨dir⟩" + , flagDescription = "redirect FFI stub files" + , flagType = DynamicFlag + } + , flag { flagName = "-dumpdir ⟨dir⟩" + , flagDescription = "redirect dump files" + , flagType = DynamicFlag + } + , flag { flagName = "-outputdir ⟨dir⟩" + , flagDescription = "set output directory" + , flagType = DynamicFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/TemporaryFiles.hs b/utils/mkUserGuidePart/Options/TemporaryFiles.hs new file mode 100644 index 0000000000..a66ca3b967 --- /dev/null +++ b/utils/mkUserGuidePart/Options/TemporaryFiles.hs @@ -0,0 +1,11 @@ +module Options.TemporaryFiles where + +import Types + +temporaryFilesOptions :: [Flag] +temporaryFilesOptions = + [ flag { flagName = "-tmpdir ⟨dir⟩" + , flagDescription = "set the directory for temporary files" + , flagType = DynamicFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/Verbosity.hs b/utils/mkUserGuidePart/Options/Verbosity.hs new file mode 100644 index 0000000000..723e5596fb --- /dev/null +++ b/utils/mkUserGuidePart/Options/Verbosity.hs @@ -0,0 +1,58 @@ +module Options.Verbosity where + +import Types + +verbosityOptions :: [Flag] +verbosityOptions = + [ flag { flagName = "-v" + , flagDescription = "verbose mode (equivalent to ``-v3``)" + , flagType = DynamicFlag + } + , flag { flagName = "-v⟨n⟩" + , flagDescription = "set verbosity level" + , flagType = DynamicFlag + , flagReverse = "" + } + , flag { flagName = "-fprint-potential-instances" + , flagDescription = + "display all available instances in type error messages" + , flagType = DynamicFlag + , flagReverse = "-fno-print-potential-instances" + } + , flag { flagName = "-fprint-explicit-foralls" + , flagDescription = + "Print explicit ``forall`` quantification in types. " ++ + "See also ``-XExplicitForAll``" + , flagType = DynamicFlag + , flagReverse = "-fno-print-explicit-foralls" + } + , flag { flagName = "-fprint-explicit-kinds" + , flagDescription = + "Print explicit kind foralls and kind arguments in types. " ++ + "See also ``-XKindSignature``" + , flagType = DynamicFlag + , flagReverse = "-fno-print-explicit-kinds" + } + , flag { flagName = "-fprint-unicode-syntax" + , flagDescription = + "Use unicode syntax when printing expressions, types and kinds. " ++ + "See also ``-XUnicodeSyntax``" + , flagType = DynamicFlag + , flagReverse = "-fno-print-unicode-syntax" + } + , flag { flagName = "-fprint-expanded-synonyms" + , flagDescription = + "In type errors, also print type-synonym-expanded types." + , flagType = DynamicFlag + , flagReverse = "-fno-print-expanded-synonyms" + } + , flag { flagName = "-ferror-spans" + , flagDescription = "Output full span in error messages" + , flagType = DynamicFlag + } + , flag { flagName = "-Rghc-timing" + , flagDescription = + "Summarise timing stats for GHC (same as ``+RTS -tstderr``)." + , flagType = DynamicFlag + } + ] diff --git a/utils/mkUserGuidePart/Options/Warnings.hs b/utils/mkUserGuidePart/Options/Warnings.hs new file mode 100644 index 0000000000..a79c3a8920 --- /dev/null +++ b/utils/mkUserGuidePart/Options/Warnings.hs @@ -0,0 +1,317 @@ +module Options.Warnings where + +import Types + +warningsOptions :: [Flag] +warningsOptions = + [ flag { flagName = "-W" + , flagDescription = "enable normal warnings" + , flagType = DynamicFlag + , flagReverse = "-w" + } + , flag { flagName = "-w" + , flagDescription = "disable all warnings" + , flagType = DynamicFlag + } + , flag { flagName = "-Wall" + , flagDescription = + "enable almost all warnings (details in :ref:`options-sanity`)" + , flagType = DynamicFlag + , flagReverse = "-w" + } + , flag { flagName = "-Werror" + , flagDescription = "make warnings fatal" + , flagType = DynamicFlag + , flagReverse = "-Wwarn" + } + , flag { flagName = "-Wwarn" + , flagDescription = "make warnings non-fatal" + , flagType = DynamicFlag + , flagReverse = "-Werror" + } + , flag { flagName = "-fdefer-type-errors" + , flagDescription = + "Turn type errors into warnings, :ref:`deferring the error until "++ + "runtime <defer-type-errors>`. Implies ``-fdefer-typed-holes``. "++ + "See also ``-fwarn-deferred-type-errors``" + , flagType = DynamicFlag + , flagReverse = "-fno-defer-type-errors" + } + , flag { flagName = "-fdefer-typed-holes" + , flagDescription = + "Convert :ref:`typed hole <typed-holes>` errors into warnings, "++ + ":ref:`deferring the error until runtime <defer-type-errors>`. "++ + "Implied by ``-fdefer-type-errors``. "++ + "See also ``-fwarn-typed-holes``." + , flagType = DynamicFlag + , flagReverse = "-fno-defer-typed-holes" + } + , flag { flagName = "-fhelpful-errors" + , flagDescription = "Make suggestions for mis-spelled names." + , flagType = DynamicFlag + , flagReverse = "-fno-helpful-errors" + } + , flag { flagName = "-fwarn-deprecated-flags" + , flagDescription = + "warn about uses of commandline flags that are deprecated" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-deprecated-flags" + } + , flag { flagName = "-fwarn-duplicate-constraints" + , flagDescription = + "warn when a constraint appears duplicated in a type signature" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-duplicate-constraints" + } + , flag { flagName = "-fwarn-duplicate-exports" + , flagDescription = "warn when an entity is exported multiple times" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-duplicate-exports" + } + , flag { flagName = "-fwarn-hi-shadowing" + , flagDescription = + "warn when a ``.hi`` file in the current directory shadows a library" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-hi-shadowing" + } + , flag { flagName = "-fwarn-identities" + , flagDescription = + "warn about uses of Prelude numeric conversions that are probably "++ + "the identity (and hence could be omitted)" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-identities" + } + , flag { flagName = "-fwarn-implicit-prelude" + , flagDescription = "warn when the Prelude is implicitly imported" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-implicit-prelude" + } + , flag { flagName = "-fwarn-incomplete-patterns" + , flagDescription = "warn when a pattern match could fail" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-incomplete-patterns" + } + , flag { flagName = "-fwarn-incomplete-uni-patterns" + , flagDescription = + "warn when a pattern match in a lambda expression or "++ + "pattern binding could fail" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-incomplete-uni-patterns" + } + , flag { flagName = "-fwarn-incomplete-record-updates" + , flagDescription = "warn when a record update could fail" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-incomplete-record-updates" + } + , flag { flagName = "-fwarn-lazy-unlifted-bindings" + , flagDescription = + "*(deprecated)* warn when a pattern binding looks lazy but "++ + "must be strict" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-lazy-unlifted-bindings" + } + , flag { flagName = "-fwarn-missing-fields" + , flagDescription = "warn when fields of a record are uninitialised" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-missing-fields" + } + , flag { flagName = "-fwarn-missing-import-lists" + , flagDescription = + "warn when an import declaration does not explicitly list all the"++ + "names brought into scope" + , flagType = DynamicFlag + , flagReverse = "-fnowarn-missing-import-lists" + } + , flag { flagName = "-fwarn-missing-methods" + , flagDescription = "warn when class methods are undefined" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-missing-methods" + } + , flag { flagName = "-fwarn-missing-signatures" + , flagDescription = "warn about top-level functions without signatures" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-missing-signatures" + } + , flag { flagName = "-fwarn-missing-exported-sigs" + , flagDescription = + "warn about top-level functions without signatures, only if they "++ + "are exported. takes precedence over -fwarn-missing-signatures" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-missing-exported-sigs" + } + , flag { flagName = "-fwarn-missing-local-sigs" + , flagDescription = + "warn about polymorphic local bindings without signatures" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-missing-local-sigs" + } + , flag { flagName = "-fwarn-monomorphism-restriction" + , flagDescription = "warn when the Monomorphism Restriction is applied" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-monomorphism-restriction" + } + , flag { flagName = "-fwarn-name-shadowing" + , flagDescription = "warn when names are shadowed" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-name-shadowing" + } + , flag { flagName = "-fwarn-orphans, -fwarn-auto-orphans" + , flagDescription = + "warn when the module contains :ref:`orphan instance declarations "++ + "or rewrite rules <orphan-modules>`" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-orphans, -fno-warn-auto-orphans" + } + , flag { flagName = "-fwarn-overlapping-patterns" + , flagDescription = "warn about overlapping patterns" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-overlapping-patterns" + } + , flag { flagName = "-fwarn-tabs" + , flagDescription = "warn if there are tabs in the source file" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-tabs" + } + , flag { flagName = "-fwarn-type-defaults" + , flagDescription = "warn when defaulting happens" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-type-defaults" + } + , flag { flagName = "-fwarn-unrecognised-pragmas" + , flagDescription = + "warn about uses of pragmas that GHC doesn't recognise" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-unrecognised-pragmas" + } + , flag { flagName = "-fwarn-unticked-promoted-constructors" + , flagDescription = "warn if promoted constructors are not ticked" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-unticked-promoted-constructors" + } + , flag { flagName = "-fwarn-unused-binds" + , flagDescription = + "warn about bindings that are unused. Alias for "++ + "``-fwarn-unused-top-binds``, ``-fwarn-unused-local-binds`` and "++ + "``-fwarn-unused-pattern-binds``" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-unused-binds" + } + , flag { flagName = "-fwarn-unused-top-binds" + , flagDescription = "warn about top-level bindings that are unused" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-unused-top-binds" + } + , flag { flagName = "-fwarn-unused-local-binds" + , flagDescription = "warn about local bindings that are unused" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-unused-local-binds" + } + , flag { flagName = "-fwarn-unused-pattern-binds" + , flagDescription = "warn about pattern match bindings that are unused" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-unused-pattern-binds" + } + , flag { flagName = "-fwarn-unused-imports" + , flagDescription = "warn about unnecessary imports" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-unused-imports" + } + , flag { flagName = "-fwarn-unused-matches" + , flagDescription = "warn about variables in patterns that aren't used" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-unused-matches" + } + , flag { flagName = "-fwarn-unused-do-bind" + , flagDescription = + "warn about do bindings that appear to throw away values of types "++ + "other than ``()``" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-unused-do-bind" + } + , flag { flagName = "-fwarn-wrong-do-bind" + , flagDescription = + "warn about do bindings that appear to throw away monadic values "++ + "that you should have bound instead" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-wrong-do-bind" + } + , flag { flagName = "-fwarn-unsafe" + , flagDescription = + "warn if the module being compiled is regarded to be unsafe. "++ + "Should be used to check the safety status of modules when using "++ + "safe inference. Works on all module types, even those using "++ + "explicit :ref:`Safe Haskell <safe-haskell>` modes (such as "++ + "``-XTrustworthy``) and so can be used to have the compiler check "++ + "any assumptions made." + , flagType = DynamicFlag + , flagReverse = "-fno-warn-unsafe" + } + , flag { flagName = "-fwarn-safe" + , flagDescription = + "warn if the module being compiled is regarded to be safe. Should "++ + "be used to check the safety status of modules when using safe "++ + "inference. Works on all module types, even those using explicit "++ + ":ref:`Safe Haskell <safe-haskell>` modes (such as "++ + "``-XTrustworthy``) and so can be used to have the compiler check "++ + "any assumptions made." + , flagType = DynamicFlag + , flagReverse = "-fno-warn-safe" + } + , flag { flagName = "-fwarn-trustworthy-safe" + , flagDescription = + "warn if the module being compiled is marked as ``-XTrustworthy`` "++ + "but it could instead be marked as ``-XSafe``, a more informative "++ + "bound. Can be used to detect once a Safe Haskell bound can be "++ + "improved as dependencies are updated." + , flagType = DynamicFlag + , flagReverse = "-fno-warn-safe" + } + , flag { flagName = "-fwarn-warnings-deprecations" + , flagDescription = + "warn about uses of functions & types that have warnings or "++ + "deprecated pragmas" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-warnings-deprecations" + } + , flag { flagName = "-fwarn-amp" + , flagDescription = + "*(deprecated)* warn on definitions conflicting with the "++ + "Applicative-Monad Proposal (AMP)" + , flagType = DynamicFlag + , flagReverse = "-fno-warn-amp" + } + , flag { flagName = "-fwarn-deferred-type-errors" + , flagDescription = + "Report warnings when :ref:`deferred type errors "++ + "<defer-type-errors>` are enabled. This option is enabled by "++ + "default. See ``-fdefer-type-errors``." + , flagType = DynamicFlag + , flagReverse = "-fno-warn-deferred-type-errors" + } + , flag { flagName = "-fwarn-typed-holes" + , flagDescription = + "Report warnings when :ref:`typed hole <typed-holes>` errors are "++ + ":ref:`deferred until runtime <defer-type-errors>`. See "++ + "``-fdefer-typed-holes``." + , flagType = DynamicFlag + , flagReverse = "-fno-warn-typed-holes" + } + , flag { flagName = "-fwarn-partial-type-signatures" + , flagDescription = + "warn about holes in partial type signatures when "++ + "``-XPartialTypeSignatures`` is enabled. Not applicable when "++ + "``-XPartialTypesignatures`` is not enabled, in which case errors "++ + "are generated for such holes. See :ref:`partial-type-signatures`." + , flagType = DynamicFlag + , flagReverse = "-fno-warn-partial-type-signatures" + } + , flag { flagName = "-fwarn-deriving-typeable" + , flagDescription = + "warn when encountering a request to derive an instance of class "++ + "``Typeable``. As of GHC 7.10, such declarations are unnecessary "++ + "and are ignored by the compiler because GHC has a custom solver "++ + "for discharging this type of constraint." + , flagType = DynamicFlag + , flagReverse = "-fno-warn-deriving-typeable" + } + ] diff --git a/utils/mkUserGuidePart/Table.hs b/utils/mkUserGuidePart/Table.hs new file mode 100644 index 0000000000..eeff8205cb --- /dev/null +++ b/utils/mkUserGuidePart/Table.hs @@ -0,0 +1,75 @@ +module Table where + +import Data.Char +import Data.List +import Data.Maybe (isJust, fromMaybe) +import qualified DList + +type Row = [String] + +type ColWidth = Int + +type WrappedString = [String] + +-- | Wrap a string to lines of at most the given length on whitespace +-- if possible. +wrapAt :: Int -> String -> WrappedString +wrapAt width = wrapLine + where + wrapLine :: String -> WrappedString + wrapLine s = + go width mempty (take width s : wrapLine (drop width s)) s + + go :: Int -- ^ remaining width + -> DList.DList Char -- ^ accumulator + -> WrappedString -- ^ last good wrapping + -> String -- ^ remaining string + -> WrappedString + go 0 _ back _ = back + go n accum _ (c:rest) + | breakable c = go (n-1) accum' + (DList.toList accum' : wrapLine rest) rest + where accum' = accum `DList.snoc` c + go n accum back (c:rest) = go (n-1) (accum `DList.snoc` c) back rest + go _ accum _ [] = [DList.toList accum] + + breakable = isSpace + +transpose' :: [[a]] -> [[Maybe a]] +transpose' = goRow + where + peel :: [a] -> (Maybe a, [a]) + peel (x:xs) = (Just x, xs) + peel [] = (Nothing, []) + + goRow xs = + case unzip $ map peel xs of + (xs', ys) + | any isJust xs' -> xs' : goRow ys + | otherwise -> [] + +table :: [ColWidth] -> Row -> [Row] -> String +table widths hdr rows = unlines $ + [rule '-'] ++ + [formatRow hdr] ++ + [rule '='] ++ + intersperse (rule '-') (map formatRow rows) ++ + [rule '-'] + where + formatRow :: Row -> String + formatRow cols = + intercalate "\n" + $ map (rawRow . map (fromMaybe "")) + $ transpose' + $ zipWith wrapAt (map (subtract 4) widths) cols + + rawRow :: Row -> String + rawRow cols = "| " ++ intercalate " | " (zipWith padTo widths cols) ++ " |" + padTo width content = take width $ content ++ repeat ' ' + + rule :: Char -> String + rule lineChar = + ['+',lineChar] + ++intercalate [lineChar,'+',lineChar] + (map (\n -> replicate n lineChar) widths) + ++[lineChar,'+'] diff --git a/utils/mkUserGuidePart/Types.hs b/utils/mkUserGuidePart/Types.hs new file mode 100644 index 0000000000..33474dae73 --- /dev/null +++ b/utils/mkUserGuidePart/Types.hs @@ -0,0 +1,20 @@ +module Types where + +data FlagType = StaticFlag + -- ^ Static flag + | DynamicFlag + -- ^ Dynamic flag + | DynamicSettableFlag + -- ^ Dynamic flag on which @:set@ can be used in GHCi + | ModeFlag + -- ^ A mode of execution (e.g. @--mode@) + +data Flag = Flag { flagName :: String + , flagDescription :: String + , flagType :: FlagType + , flagReverse :: String + , flagSince :: String + } + +flag :: Flag +flag = Flag "" "" DynamicFlag "" "" diff --git a/utils/mkUserGuidePart/ghc.mk b/utils/mkUserGuidePart/ghc.mk index 30b050e305..87c9d6552b 100644 --- a/utils/mkUserGuidePart/ghc.mk +++ b/utils/mkUserGuidePart/ghc.mk @@ -10,9 +10,49 @@ # # ----------------------------------------------------------------------------- +utils/mkUserGuidePart_GENERATED_FLAGS_SETS := \ + codegen \ + compiler-debugging \ + cpp \ + finding-imports \ + interactive \ + interface-files \ + keeping-intermediates \ + language \ + linking \ + misc \ + modes \ + optimization \ + optimization-levels \ + packages \ + phase-programs \ + phases \ + phase-specific \ + platform-specific \ + plugin \ + profiling \ + program-coverage \ + recompilating-checking \ + recompilation-checking \ + redirecting-output \ + temporary-files \ + verbosity \ + warnings + +utils/mkUserGuidePart_GENERATED_RST_SOURCES := \ + $(addprefix docs/users_guide/flags-,$(addsuffix .gen.rst,$(utils/mkUserGuidePart_GENERATED_FLAGS_SETS))) \ + docs/users_guide/what_glasgow_exts_does.gen.rst \ + docs/man/all-flags.gen.rst + utils/mkUserGuidePart_USES_CABAL = YES utils/mkUserGuidePart_PACKAGE = mkUserGuidePart utils/mkUserGuidePart_dist_PROGNAME = mkUserGuidePart utils/mkUserGuidePart_dist_INSTALL_INPLACE = YES $(eval $(call build-prog,utils/mkUserGuidePart,dist,2)) +$(eval $(call clean-target,utils/mkUserGuidePart,gen,$(utils/mkUserGuidePart_GENERATED_RST_SOURCES))) + +$(utils/mkUserGuidePart_GENERATED_RST_SOURCES) : $(mkUserGuidePart_INPLACE) + $(mkUserGuidePart_INPLACE) + +all_utils/mkUserGuidePart: $(mkUserGuidePart_INPLACE) diff --git a/utils/mkUserGuidePart/mkUserGuidePart.cabal b/utils/mkUserGuidePart/mkUserGuidePart.cabal index 112bbf6a81..5b185ee30d 100644 --- a/utils/mkUserGuidePart/mkUserGuidePart.cabal +++ b/utils/mkUserGuidePart/mkUserGuidePart.cabal @@ -14,6 +14,37 @@ cabal-version: >=1.10 Executable mkUserGuidePart Default-Language: Haskell2010 Main-Is: Main.hs + Other-Modules: + Types + DList + Table + Options + Options.CodeGen + Options.CompilerDebugging + Options.Cpp + Options.FindingImports + Options.Interactive + Options.InterfaceFiles + Options.KeepingIntermediates + Options.Language + Options.Linking + Options.Misc + Options.Modes + Options.OptimizationLevels + Options.Optimizations + Options.Packages + Options.PhasePrograms + Options.Phases + Options.PhaseSpecific + Options.PlatformSpecific + Options.Plugin + Options.Profiling + Options.ProgramCoverage + Options.RecompilationChecking + Options.RedirectingOutput + Options.TemporaryFiles + Options.Verbosity + Options.Warnings Build-Depends: base >= 3 && < 5, ghc diff --git a/utils/vagrant/bootstrap-rhel.sh b/utils/vagrant/bootstrap-rhel.sh index 5086279dc6..52cc5fca93 100755 --- a/utils/vagrant/bootstrap-rhel.sh +++ b/utils/vagrant/bootstrap-rhel.sh @@ -1,4 +1,4 @@ #!/bin/sh yum update -y yum install -y glibc-devel ncurses-devel gmp-devel autoconf automake libtool \ - gcc make perl python ghc git docbook-utils docbook-utils-pdf docbook-style-xsl + gcc make perl python ghc git |
