+++ /dev/null
-%************************************************************************
-%* *
-\section{How to add an optimisation pass}
-%* *
-%************************************************************************
-\subsection{Summary of the steps required}
-
-Well, with all the preliminaries out of the way, here is all that it
-takes to add your optimisation pass to the new glorious Glasgow
-Haskell compiler:
-\begin{enumerate}
-\item
-Select the input and output types for your pass; these will very
-likely be particular parameterisations of the Core or annotated Core
-data types. There is a small chance you will prefer to work at the
-STG-syntax level. (If these data types are inadequate to this
-purpose, {\em please} let us know!)
-
-\item
-Depending on exactly how you want your pass to work, set up some
-monad-ery, so as to avoid lots of horrible needless plumbing. The
-whole compiler is written in a monadic style, and there are plenty of
-examples from which you may steal. Section~\ref{sec:monadic-style}
-gives further details about how you might do this.
-
-\item
-Write your optimisation pass, and...
-
-{\em Do} use the existing types in the compiler, e.g., @UniType@,
-and the ``approved'' interfaces to them.
-
-{\em Don't} rewrite lots of utility code! Scattered around in various
-sometimes-obvious places, there is considerable code already written
-for the mangling and massaging of expressions, types, variables, etc.
-
-Section~\ref{sec:reuse-code} says more about how to re-use existing
-compiler bits.
-
-\item
-Follow our naming conventions \smiley{} Seriously, it may lead to greater
-acceptance of our code and yours if readers find a system written with
-at least a veneer of uniformity.
-\ToDo{mention Style Guide, if it ever really exists.}
-
-\item
-To hook your pass into the compiler, either add something directly to
-the @Main@ module of the compiler\srcloc{main/Main.lhs}, or into the
-Core-to-Core simplification driver\srcloc{simplCore/SimplCore.lhs}, or
-into the STG-to-STG driver\srcloc{simplStg/SimplStg.lhs}.
-
-Also add something to the compilation-system
-driver\srcloc{ghc/driver/ghc.lprl}
-(called @ghc@ here) so that appropriate user-provided command-line
-options will be transmogrified into the correct options fed to the
-@Main@ module.
-
-\item
-Add some appropriate documentation to the user's guide,
-@ghc/docs/users_guide@.
-
-\item
-Run your optimisation on {\em real programs}, measure, and improve.
-(Separate from this compiler's distribution, we provide a ``NoFib''
-suite of ``real Haskell programs'' \cite{partain92a}. We strongly
-encourage their use, so you can more readily compare your work with
-others'.)
-
-\item
-Send us your contribution so we can add it to the distribution! We
-will be happy to include anything semi-reasonable.
-This will practically ensure fame, if
-not fortune, and---with a little luck---considerable notoriety.
-\end{enumerate}
-
-%************************************************************************
-%* *
-\subsection{Using monadic code}\label{sec:monadic-style}
-%* *
-%************************************************************************
-
-{\em Monads} are one way of structuring functional programs. Phil
-Wadler is their champion, and his recent papers on the subject are a
-good place to start your investigations. ``The essence of functional
-programming'' even has a section about the use of monads in this
-compiler \cite{wadler92a}! An earlier paper describes ``monad
-comprehensions'' \cite{wadler90a}. For a smaller self-contained
-example, see his ``literate typechecker'' \cite{wadler90b}.
-
-We use monads extensively in this compiler, mainly as a way to plumb
-state around. The simplest example is a monad to plumb a
-@UniqueSupply@\srcloc{basicTypes/Unique.lhs} (i.e., name supply)
-through a function.
-
-\ToDo{Actually describe one monad thing completely.}
-
-We encourage you to use a monadic style, where appropriate, in
-the code you add to the compiler. To this end, here is a list of
-monads already in use in the compiler:
-\begin{description}
-\item[@UniqueSupply@ monad:]\srcloc{basicTypes/Unique.lhs}%
-To carry a name supply around; do a @getUnique@ when you
-need one. Used in several parts of the compiler.
-
-\item[Typechecker monad:]\srcloc{typecheck/TcMonad.lhs}%
-Quite a complicated monad; carries around a substitution, some
-source-location information, and a @UniqueSupply@; also plumbs
-typechecker success/failure back up to the right place.
-
-\item[Desugarer monad:]\srcloc{deSugar/DsMonad.lhs}%
-Carries around a @UniqueSupply@ and source-location information (to
-put in pattern-matching-failure error messages).
-
-\item[Code-generator monad:]\srcloc{codeGen/CgMonad.lhs}%
-Carries around an environment that maps variables to addressing modes
-(e.g., ``in this block, @f@ is at @Node@ offset 3''); also, carries
-around stack- and heap-usage information. Quite tricky plumbing, in
-part so that the ``Abstract~C'' output will be produced lazily.
-
-\item[Monad for underlying I/O machinery:]\srcloc{ghc/lib/io/GlaIOMonad.lhs}%
-This is the basis of our I/O implementation. See the paper about it
-\cite{peyton-jones92b}.
-\end{description}
-
-%************************************************************************
-%* *
-\subsection{Adding a new @PrimitiveOp@}\label{sec:add-primop}
-%* *
-%************************************************************************
-
-You may find yourself wanting to add a new
-@PrimitiveOp@\srcloc{prelude/PrimOps.lhs} to the compiler's
-repertoire: these are the lowest-level operations that cannot be
-expressed in Haskell---in our case, things written in C.
-
-What you would need to do to add a new op:
-\begin{itemize}
-\item
-Add it to the @PrimitiveOp@ datatype in @prelude/PrimOps.lhs@; it's
-just an enumeration type.
-\item
-Most importantly, add an entry in the @primOpInfo@ function for your
-new primitive.
-\item
-If you want your primitive to be visible to some other part of the
-compiler, export it via the @AbsPrel@\srcloc{prelude/AbsPrel.lhs}
-interface (and import it from there).
-\item
-If you want your primitive to be visible to the user (modulo some
-``show-me-nonstd-names'' compiler flag...), add your primitive to one
-or more of the appropriate lists in @buildinNameFuns@, in
-@prelude/AbsPrel.lhs@.
-\item
-If your primitive can be implemented with just a C macro, add it to
-@ghc/imports/StgMacros.lh@. If it needs a C function, put that in
-@ghc/runtime/prims/@, somewhere appropriate; you might need to put a
-declaration of some kind in a C header file in @ghc/imports/@.
-\item
-If these steps are not enough, please get in touch.
-\end{itemize}
-
-%************************************************************************
-%* *
-\section{How to add a new ``PrimOp'' (primitive operation)}
-%* *
-%************************************************************************
-
-%************************************************************************
-%* *
-\section{How to add a new ``user pragma''}
-%* *
-%************************************************************************
-
-%************************************************************************
-%* *
-\section{GHC utilities and re-usable code}\label{sec:reuse-code}
-%* *
-%************************************************************************
-
-%************************************************************************
-%* *
-\subsection{Reuse existing utilities}
-%* *
-%************************************************************************
-
-Besides the utility functions provided in Haskell's standard prelude,
-we have several modules of generally-useful utilities in \mbox{\tt utils/}
-(no need to re-invent them!):
-\begin{description}
-\item[@Maybe@ and @MaybeErr@:]
-Two very widely used types (and some operations on them):
-\begin{verbatim}
-data Maybe a = Nothing | Just a
-data MaybeErr a b = Succeeded a | Failed b
-\end{verbatim}
-
-\item[@Set@:]
-A simple implementation of sets (an abstract type). The things you
-want to have @Sets@ of must be in class @Ord@.
-
-\item[@ListSetOps@:]
-A module providing operations on lists that have @Set@-sounding names;
-e.g., @unionLists@.
-
-\item[@Digraph@:]
-A few functions to do with directed graphs, notably finding
-strongly-connected components (and cycles).
-
-\item[@Util@:]
-General grab-bag of utility functions not provided by the standard
-prelude.
-\end{description}
-
-Much of the compiler is structured around major datatypes, e.g.,
-@UniType@ or @Id@. These datatypes (often ``abstract''---you can't
-see their actual constructors) are packaged with many useful
-operations on them. So, again, look around a little for these
-functions before rolling your own. Section~\ref{sec:reuse-datatypes}
-goes into this matter in more detail.
-
-%************************************************************************
-%* *
-\subsection{Use pretty-printing and forcing machinery}
-%* *
-%************************************************************************
-
-All of the non-trivial datatypes in the compiler are in class
-@Outputable@, meaning you can pretty-print them (method: @ppr@) or
-force them (method: @frc@).
-
-Pretty-printing is by far the more common operation. @ppr@ takes a
-``style'' as its first argument; it can be one of @PprForUser@,
-@PprDebug@, or @PprShowAll@, which---in turn---are intended to show
-more and more detail. For example, @ppr PprForUser@ on a @UniType@
-should print a type that would be recognisable to a Haskell user;
-@ppr PprDebug@ prints a type in the way an implementer would normally
-want to see it (e.g., with all the ``for all...''s), and
-@ppr PprShowAll@ prints everything you could ever want to know about that
-type.
-
-@ppr@ produces a @Pretty@, which should eventually wend its way to
-@main@. @main@ can then peruse the program's command-line options to
-decide on a @PprStyle@ and column width in which to print. In
-particular, it's bad form to @ppShow@ the @Pretty@ into a @String@
-deep in the bowels of the compiler, where the user cannot control the
-printing.
-
-If you introduce non-trivial datatypes, please make them instances of
-class @Outputable@.
-
-%************************************************************************
-%* *
-\subsection{Use existing data types appropriately}\label{sec:reuse-datatypes}
-%* *
-%************************************************************************
-
-The compiler uses many datatypes. Believe it or not, these have
-carefully structured interfaces to the ``outside world''! Unfortunately,
-the current Haskell module system does not let us enforce proper
-access to these datatypes to the extent we would prefer. Here is a
-list of datatypes (and their operations) you should feel free to use,
-as well as how to access them.
-
-The first major group of datatypes are the ``syntax datatypes,'' the
-various ways in which the program text is represented as it makes its
-way through the compiler. These are notable in that you are allowed
-to see/make-use-of all of their constructors:
-\begin{description}
-\item[Prefix form:]\srcloc{reader/PrefixSyn.lhs}%
-You shouldn't need this.
-
-\item[Abstract Haskell syntax:]\srcloc{abstractSyn/AbsSyn.lhs}%
-Access via the @AbsSyn@ interface. An example of what you should {\em not}
-do is import the @AbsSynFuns@ (or @HsBinds@ or ...) interface
-directly. @AbsSyn@ tells you what you're supposed to see.
-
-\item[Core syntax:]\srcloc{coreSyn/*Core.lhs}%
-Core syntax is parameterised, and you should access it {\em via one of the
-parameterisations}. The most common is @PlainCore@; another is
-@TaggedCore@. Don't use @CoreSyn@, though.
-
-\item[STG syntax:]\srcloc{stgSyn/StgSyn.lhs}%
-Access via the @StgSyn@ interface.
-
-\item[Abstract~C syntax:]\srcloc{absCSyn/AbsCSyn.lhs}%
-Access via the @AbsCSyn@ interface.
-\end{description}
-
-The second major group of datatypes are the ``basic entity''
-datatypes; these are notable in that you don't need to know their
-representation to use them. Several have already been mentioned:
-\begin{description}
-\item[UniTypes:]\srcloc{uniType/AbsUniType.lhs}%
-This is a gigantic
-interface onto the world of @UniTypes@; accessible via the
-@AbsUniType@ interface. You should import operations on all the {\em
-pieces} of @UniTypes@ (@TyVars@, @TyVarTemplates@, @TyCons@,
-@Classes@, and @ClassOps@) from here as well---everything for the
-``type world.''
-
-{\em Please don't grab type-related functions from internal modules,
-behind @AbsUniType@'s back!} (Otherwise, we won't discover the
-shortcomings of the interface...)
-
-\item[Identifiers:]\srcloc{basicTypes/Id.lhs}%
-Interface: @Id@.
-
-\item[``Core'' literals:]\srcloc{basicTypes/CoreLit.lhs}%
-These are the unboxed literals used in Core syntax onwards. Interface: @CoreLit@.
-
-\item[Environments:]\srcloc{envs/GenericEnv.lhs}%
-A generic environment datatype, plus a generally useful set of
-operations, is provided via the @GenericEnv@ interface. We encourage
-you to use this, rather than roll your own; then your code will
-benefit when we speed up the generic code. All of the typechecker's
-environment stuff (of which there is plenty) is built on @GenericEnv@,
-so there are plenty of examples to follow.
-
-\item[@Uniques@:]\srcloc{basicTypes/Unique.lhs}%
-Essentially @Ints@.
-When you need something unique for fast comparisons. Interface:
-@Unique@. This interface also provides a simple @UniqueSupply@ monad;
-often just the thing...
-
-\item[Wired-in standard prelude knowledge:]\srcloc{prelude/}%
-The compiler has to know a lot about the standard prelude. What it knows
-is in the @compiler/prelude@ directory; all the rest of the compiler
-gets its prelude knowledge through the @AbsPrel@ interface.
-
-The prelude stuff can get hairy. There is a separate document about
-it. Check the @ghc/docs/README@ list for a pointer to it...
-\end{description}
-
-The above list isn't exhaustive. By all means, ask if you think
-``Surely a function like {\em this} is in here somewhere...''
-
-
-%************************************************************************
-%* *
-\section{Cross-module pragmatic info: the mysteries revealed}
-%* *
-%************************************************************************
-
-ToDo: mention wired-in info.
-
-%************************************************************************
-%* *
-\section{GHC hacking tips and ``good practice''}
-%* *
-%************************************************************************
-
-ASSERT
-
-%************************************************************************
-%* *
-\section{Glasgow pragmatics: build trees, etc.}
-%* *
-%************************************************************************
projects / ghc-hetmet.git / blobdiff