Permalink
Browse files

release 1.0.0

  • Loading branch information...
1 parent 9d05ab9 commit d48aab6d9271d2304e188c4aa4dfb652d0d9e4b7 @atzedijkstra atzedijkstra committed Apr 17, 2009
Showing with 476 additions and 165 deletions.
  1. +34 −21 ANNOUNCE
  2. +1 −0 LICENSE
  3. +4 −0 configure.ac
  4. +8 −12 src/ehc/EH/PrettyAST.cag
  5. +60 −7 src/ehc/Pred/EvidenceToCore.chs
  6. +1 −1 src/ehc/Pred/Heuristics.chs
  7. +2 −2 src/rts/grinbc/grinbc.cc
  8. +6 −1 test/files.mk
  9. +360 −121 text/ToolDocEHC.cltex
View
55 ANNOUNCE
@@ -13,47 +13,60 @@ msg
========================================================
-The UHC team is happy to announce the first public release of the Utrecht Haskell
-Compiler (UHC). UHC supports almost all Haskell98 features plus
-experimental extensions. The compiler runs under MacOSX, Windows
-(cygwin), and various Unix flavors.
+The UHC team is happy to announce the first public release of the
+Utrecht Haskell Compiler (UHC). UHC supports almost all Haskell98
+features plus many experimental extensions. The compiler runs on MacOSX,
+Windows (cygwin), and various Unix flavors.
Features:
- * Multiple backends, including a bytecode interpreter backend and a
- full program analysis backend, both via C.
-
+ * Multiple backends, including a bytecode interpreter backend and a GRIN
+ based, full program analysing backend, both via C.
+
* Experimental language extensions, some of which have not been
implemented before.
- * Implementation via attribute grammars and other high-level tools.
-
- * Compiler writers should be able to experiment realtively easily
- with different language variants, thanks to an aspect-oriented
- internal organisation.
+ * Implementation via attribute grammars and other high-level tools.
+
+ * Ease of experimentation with language variants, thanks to an
+ aspect-oriented internal organisation.
Getting started & Download
--------------------------
-UHC is available in source distribution, downloadable via the UHC home page:
+UHC is available for download as source distribution via the UHC home page:
- http://www.cs.uu.nl/wiki/UHC/WebHome
+ http://www.cs.uu.nl/wiki/UHC
Here you will also find instructions to get started.
-
Status of the implementation
----------------------------
-Like any compiler UHC is work in progress. Although we feel it is mature
-enough to offer it for public availability, much work still needs to be
-done, and we welcome contributions. UHC grew out of our Haskell compiler
-project (called Essential Haskell Compiler, or EHC) over the past 5
-years. UHC internally is organised as a combination of separate aspects,
-which makes UHC also suitable for experimental use.
+Like any university project UHC is very much work in progress. We feel
+that it is mature and stable enough to offer to the public, but much
+work still needs to be done; hence we welcome contributions by others.
+
+UHC grew out of our Haskell compiler project (called Essential Haskell
+Compiler, or EHC) over the past 5 years. UHC internally is organised as
+a combination of separate aspects, which makes UHC very suitable to
+experiment with; it is relatively easy to build compilers for
+sublanguages, or to generate related tools such as documentation
+generators, all from the same code base. Extensions to the language can
+be described separately, and be switched on or of as need arises.
+
+
+Warning
+-------
+Although we think that the compiler is stable enough to compile
+subtantial Haskell programs, we do not recommend yet to use it for any
+serious development work in Haskell. We ourselves use the GHC as a
+development platform! We think however that it provides a great platform
+for experimenting with language implementations, language extensions,
+etc.
Mailing lists
View
1 LICENSE
@@ -9,6 +9,7 @@ template can be found here:
UHC uses the following libraries with their own license, both LGPL:
- GNU Multiple Precision (GMP) library, see extlibs/gmp
- Boehm Garbage Collector (BGC) library, see extlibs/bgc
+- Library code from ghe GHC distribution, see comment in the modules in ehclib
License text
============
View
4 configure.ac
@@ -162,6 +162,10 @@ case $HostPlatform in
cppEhcOptions="$cppEhcOptions -D__STDC__"
#cppEhcOptions="$cppEhcOptions -D__USE_BSD -D__USE_POSIX -D__STDC__"
;;
+ x86_64-*-linux-gnu )
+ cppEhcOptions="$cppEhcOptions -D__STDC__"
+ #cppEhcOptions="$cppEhcOptions -D__USE_BSD -D__USE_POSIX -D__STDC__"
+ ;;
*)
;;
esac
View
20 src/ehc/EH/PrettyAST.cag
@@ -691,28 +691,24 @@ SEM Expr
-- , if @lhs.isFirstLet then mkInfo1 "chrStore" (ppCHRStore @chrStore) else ("",empty)
, mkInfo1 "chrSolve1DoneConstraints" (ppBracketsCommasV @chrSolve1DoneConstraints)
, mkInfo1 "chrSolve1RemCnstrMp" (ppAssocLV $ assocLMapElt ppBracketsCommas $ Map.toList @chrSolve1RemCnstrMp)
+ , mkInfo1 "chrSolve2DoneConstraints" (ppBracketsCommasV @chrSolve2DoneConstraints)
+ , mkInfo1 "chrSolve2RemCnstrMp" (ppAssocLV $ assocLMapElt ppBracketsCommas $ Map.toList @chrSolve2RemCnstrMp)
, mkInfo1 "chrSolve1EvidMp" (ppAssocLV $ Map.toList @chrSolve1EvidMp)
%%[[(9 codegen)
+ , mkInfo1 "chrSolve1EvidCoreMp" (ppAssocLV $ assocLMapElt (\(c,s,sc) -> c >-< (ppBracketsCommas $ Set.toList s) >-< sc) $ Map.toList @chrSolve1EvidCoreMp)
, mkInfo1 "chrSolve1EvidBindMp" (ppAssocLV $ assocLMapElt ppCBindL $ Map.toList @chrSolve1EvidBindMp)
, mkInfo1 "chrSolve1ScopeBindMp" (ppAssocLV $ assocLMapElt ppCBindL $ Map.toList @chrSolve1ScopeBindMp)
-%%]]
- , mkInfo1 "chrSolve1Trace" (ppSolveTrace @chrSolve1Trace)
- , mkInfo1 "chrSolve1RedGraph" (pp $ show @chrSolve1RedGraph)
-%%[[(9 codegen)
- , mkInfo1 "chrSolve1EvidCoreMp" (ppAssocLV $ assocLMapElt (\(c,s,sc) -> c >-< show s >-< sc) $ Map.toList @chrSolve1EvidCoreMp)
+ , mkInfo1 "chrSolve2EvidBindMp" (ppAssocLV $ assocLMapElt ppCBindL $ Map.toList @chrSolve2EvidBindMp)
+ , mkInfo1 "chrSolve2ScopeBindMp" (ppAssocLV $ assocLMapElt ppCBindL $ Map.toList @chrSolve2ScopeBindMp)
+ , mkInfo1 "cSubst" (ppAssocLV . Map.toList $ @decls.cSubst)
, mkInfo1 "coeArgIdMp" (ppAssocLV $ assocLMapElt ppBracketsCommas $ Map.toList @coeArgIdMp)
%%]]
, mkInfo1 "quantPrOccL (decl)" (ppBracketsCommasV @quantPrOccL)
, mkInfo1 "quantCnstrMp" (ppAssocLV $ assocLMapElt ppBracketsCommas $ Map.toList @quantCnstrMp)
, mkInfo1 "tqoGam" (ppGam @tqoGam)
, mkInfo1 "tmpoTyVarMp" (pp @tmpoTyVarMp)
- , mkInfo1 "chrSolve2DoneConstraints" (ppBracketsCommasV @chrSolve2DoneConstraints)
- , mkInfo1 "chrSolve2RemCnstrMp" (ppAssocLV $ assocLMapElt ppBracketsCommas $ Map.toList @chrSolve2RemCnstrMp)
-%%[[(9 codegen)
- , mkInfo1 "chrSolve2EvidBindMp" (ppAssocLV $ assocLMapElt ppCBindL $ Map.toList @chrSolve2EvidBindMp)
- , mkInfo1 "chrSolve2ScopeBindMp" (ppAssocLV $ assocLMapElt ppCBindL $ Map.toList @chrSolve2ScopeBindMp)
- , mkInfo1 "cSubst" (ppAssocLV . Map.toList $ @decls.cSubst)
-%%]]
+ , mkInfo1 "chrSolve1Trace" (ppSolveTrace @chrSolve1Trace)
+ , mkInfo1 "chrSolve1RedGraph" (pp $ show @chrSolve1RedGraph)
, mkInfo1 "chrSolve2Trace" (ppSolveTrace @chrSolve2Trace)
, mkInfo1 "chrSolve2RedGraph" (pp $ show @chrSolve2RedGraph)
]
View
67 src/ehc/Pred/EvidenceToCore.chs
@@ -31,6 +31,22 @@
%%% Translation
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+Sub evidence encodes the evidence needed to construct other evidence, as in Eq Int required for Eq [Int].
+The subevidence is identified/introduced by a UID and defined in scope.
+Subevidence can be an assumption (encoded below) or an already known instance (dealt with otherwise, but must be here too. 20090416)
+
+%%[(9 codegen)
+data SubEvid
+ = SubEvid_Assume
+ { subevdId :: UID
+ , subevdScope :: PredScope
+ }
+ deriving (Eq,Ord,Show)
+
+instance PP SubEvid where
+ pp (SubEvid_Assume i s) = "SubEvd" >#< i >#< s
+%%]
+
All code fragments are identified by a UID.
The translation to core yields:
@@ -39,7 +55,7 @@ The translation to core yields:
- a set of bindings which do not depend on assumptions.
%%[(9 codegen) export(EvidKeyToCBindMap,PredScopeToCBindMap)
-type EvidKeyToCExprMap = Map.Map UID (CExpr,Set.Set (UID,PredScope),PredScope)
+type EvidKeyToCExprMap = Map.Map UID (CExpr,Set.Set SubEvid,PredScope)
type EvidKeyToCBindMap = Map.Map UID [CBind]
type PredScopeToCBindMap = Map.Map PredScope [CBind]
@@ -53,7 +69,7 @@ data ToCoreState p info
data ToCoreRes
= ToCoreRes
{ tcrCExpr :: !CExpr
- , tcrUsed :: !(Set.Set (UID,PredScope))
+ , tcrUsed :: !(Set.Set SubEvid)
, tcrScope :: !PredScope
}
%%]
@@ -99,7 +115,7 @@ evidMpToCore env evidMp
(u',evk,insk,evnm,uses)
= case info of
RedHow_ProveObl i _ -> (u,choosek i,True,choosen $ mkHNm i,Set.empty)
- RedHow_Assumption vun s -> (u,choosek i,False,choosen (vunmNm vun),Set.singleton (i,s))
+ RedHow_Assumption vun s -> (u,choosek i,False,choosen (vunmNm vun),Set.singleton (SubEvid_Assume i s))
where i = vunmId vun
_ -> (u1,choosek u2,True,choosen $ mkHNm u2,Set.empty)
where (u1,u2) = mkNewUID u
@@ -161,22 +177,22 @@ evidMpToCore env evidMp
Just r -> trp "XX" ("ev" >#< ev >#< insk >#< "k" >#< k >#< v >#< "r" >#< tcrCExpr r >#< tcrCExpr (vr r)) $ ( mkk r st,vr r)
= maybe (mkc r $ mkk (ToCoreRes c uses) st, r) (\r -> (mkk r st,vr r)) $ Map.lookup ev $ tcsEvMp st
-%%[(9 codegen) export(evidKeyCoreMpToBinds)
-
+%%[(9 codegen)
getMetaDictMbPos :: CExpr -> Maybe Int
getMetaDictMbPos (CExpr_Let _ (CBind_Bind _ (_,CMetaVal_Dict m) _ : _) _) = m
getMetaDictMbPos _ = Nothing
+%%]
-
+%%[(9 codegen) export(evidKeyCoreMpToBinds)
evidKeyCoreMpToBinds :: EvidKeyToCExprMap -> (EvidKeyToCBindMap,PredScopeToCBindMap)
evidKeyCoreMpToBinds m
= dbg "evidKeyCoreMpToBinds.res"
$!
( dbg "evidKeyCoreMpToBinds.res1"
$! Map.unionsWith (++)
$ map (\(b,uses)
- -> let deepestScope = fst . maximumBy (\(_,sc1) (_,sc2) -> sc1 `pscpCmpByLen` sc2) . Set.toList
+ -> let deepestScope = subevdId . maximumBy (\evd1 evd2 -> subevdScope evd1 `pscpCmpByLen` subevdScope evd2) . Set.toList
in Map.singleton (deepestScope uses) [b]
)
$ [ (mkCBind1Meta (mkHNm i) (CMetaVal_Dict (getMetaDictMbPos e)) e,u)
@@ -196,6 +212,43 @@ evidKeyCoreMpToBinds m
dbg m = id -- Debug.tr m (pp m)
%%]
+20090416.
+The above code accidently swaps independentOfAssumes and dependentOnAssumes in the computation of maps.
+The resulting code is ok, as long as it does not concern scope dependent instances, which is the case in Haskell98.
+Below is -for now- at least the start to do it right.
+The code using these mappings has to be checked as well.
+
+Extract from the basic bindings for prove obligations the following:
+- bindings independent of assumption or scope.
+- foreach introduced assumption, the bindings required for depending prove obligations which only require that assumption.
+- the rest, which depends on multiple assumptions, and thus can only be introduced at the deepest scope. Hence a map from scope to such bindings.
+
+%%[(9 codegen) export(EvidCBindL,evidKeyCoreMpToBinds2)
+type EvidCBindL = [CBind]
+
+evidKeyCoreMpToBinds2 :: EvidKeyToCExprMap -> (EvidCBindL,EvidKeyToCBindMap,PredScopeToCBindMap)
+evidKeyCoreMpToBinds2 m
+ = ( [ mkd i e
+ | (i,(e,_,_)) <- Map.toList independentOfAssumes
+ ]
+ , Map.unionsWith (++)
+ $ [ Map.singleton (subevdId $ head $ Set.toList u) [mkd i e]
+ | (i,(e,u,_)) <- Map.toList dependentOn1Assume
+ ]
+ , Map.unionsWith (++)
+ $ [ Map.singleton (deepestScope sc u) [mkd i e]
+ | (i,(e,u,sc)) <- Map.toList dependentOnNAssumes
+ ]
+ )
+ where (independentOfAssumes, dependentOnAssumes)
+ = Map.partition (\(_,uses,_) -> Set.null uses) m
+ (dependentOn1Assume, dependentOnNAssumes)
+ = Map.partition (\(_,uses,_) -> Set.size uses == 1) m
+ mkd i e = mkCBind1Meta (mkHNm i) (CMetaVal_Dict (getMetaDictMbPos e)) e
+ deepestScope sc u = maximumBy pscpCmpByLen $ sc : (map subevdScope $ Set.toList u)
+%%]
+
+
%%[(9 codegen) export(evidKeyBindMpToCSubst)
evidKeyBindMpToCSubst :: EvidKeyToCBindMap -> CSubst
evidKeyBindMpToCSubst
View
2 src/ehc/Pred/Heuristics.chs
@@ -7,7 +7,7 @@ Derived from work by Gerrit vd Geest.
%%[(9 hmtyinfer) module {%{EH}Pred.Heuristics} import({%{EH}Ty},{%{EH}Ty.FitsInCommon2}, {%{EH}CHR},{%{EH}VarMp},{%{EH}Pred.CHR},{%{EH}Pred.Evidence},{%{EH}CHR.Constraint})
%%]
-%%[(9 hmtyinfer) import(Data.List(nub, maximumBy, partition),Data.Maybe)
+%%[(9 hmtyinfer) import(Data.List(nub, partition),Data.Maybe)
%%]
%%[(9 hmtyinfer) import(EH.Util.Pretty,EH.Util.AGraph,EH.Util.Utils)
View
4 src/rts/grinbc/grinbc.cc
@@ -607,7 +607,7 @@ void gb_prCallInfoName( GB_CallInfo* ci )
void gb_prCallInfo( GB_CallInfo* ci )
{
- printf( "ci=%x", (int)ci ) ;
+ printf( "ci=%x", (GB_Word)ci ) ;
if ( ci != NULL )
{
printf( ": kind %d: ", ci->kind ) ;
@@ -1696,7 +1696,7 @@ void gb_exit( int i )
if ( gb_prCallInfoIsVisible( ci ) )
// if ( True )
{
- printf( " bp=%x ", (int)p ) ;
+ printf( " bp=%x ", (GB_Word)p ) ;
gb_prCallInfo( ci ) ;
printf( "\n" ) ;
}
View
7 test/files.mk
@@ -51,7 +51,12 @@ test-lists:
else \
startvariant=$(EHC_PREL_VARIANT) ; \
fi ; \
- for ((i = $${startvariant} ; i <= $${vv} ; i++)) ; do ehs="$${ehs} `echo $${i}/*.{eh,hs}`" ; done ; \
+ i=$${startvariant} ; \
+ while test $${i} -le $${vv} ; \
+ do \
+ ehs="$${ehs} `echo $${i}/*.{eh,hs}`" ; \
+ i=`expr $${i} + 1` ; \
+ done ; \
echo "$${ehs}" > $${v}.lst ; \
done
View
481 text/ToolDocEHC.cltex
@@ -11,6 +11,9 @@
\section{Check your installation (optional)}
%%@ToolDocEHC.testRegress
+\section{Shoot trouble (hopefully optional)}
+See the troubleshooting FAQ in the \eref{EhcUserDocumentation}{UHC manual}.
+
%%]
@@ -46,6 +49,14 @@ Bear in mind that these extensions are all but tried and tested!
%%@ToolDocEHC.extensions
\subsection{Higher ranked types and impredicativity}
\label{higher-ranked-types-and-impredicativity}
+\subsubsection{Higher ranked types}
+%%@ToolDocEHC.higherRankTypes
+\subsubsection{Co- and contravariance}
+%%@ToolDocEHC.coContraVariance
+\subsubsection{Impredicativity}
+%%@ToolDocEHC.impredicativity
+\subsubsection{Caveats}
+%%@ToolDocEHC.rankImpredCaveats
\subsection{Partial type signature}
\label{partial-type-signatures}
@@ -100,141 +111,28 @@ hence no documentation is currently available.
%%@ToolDocEHC.ffi
\subsection{Library modules}
+%%@ToolDocEHC.libraryModules
-The library consists of
-\begin{itemize}
-\item UHC specific modules, tightly coupled with the underlying implementation. The names of these modules start with @UHC.@.
-\item Modules from the GHC distribution, used without changes.
-\item Modules cloned + adapted from the GHC distribution. This maybe involve a couple of \verb|#ifdef|s or more extensive changes. The intention is to have these changes merged back into the GHC library as to avoid library differences between Haskell implementations.
-\end{itemize}
-
-Currently, mostly modules from the @base@ package are available, only arrays from package @array@ are available.
-For each library module in the Haskell98 report we summarize what is working and what not.
-There are no backwards compatibility wrapper modules, as this is part of the @haskell98@ package.
-
-\begin{itemize}
-\item @Prelude@: fully available.
-\item @Ratio@: in @Data.Ratio@, fully available.
-\item @Complex@: in @Data.Complex@, fully available.
-\item @Numeric@: fully available.
-\item @Ix@: in @Data.Ix@, fully available.
-\item @Array@: in @Data.Array@, fully available.
-\item @List@: in @Data.List@, fully available.
-\item @Maybe@: in @Data.Maybe@, fully available.
-\item @Monad@: in @Control.Monad@, fully available.
-\item @IO@: under construction, the @Prelude@ part is as a temporary implementation available.
-\item @Directory@: not available.
-\item @System@: in @System.Environment@ and @System.Exit@, fully available.
-\item @Time@: not available.
-\item @Locale@: not available.
-\item @CPUTime@: not available.
-\item @Random@: not available.
-\end{itemize}
-
-More library modules are incorporated, we only list those which are not fully implemented:
-
-\begin{itemize}
-\item @Prelude@:
-\item @Data.Typeable@: @cast@ (and variants) always yields @Nothing@. Equality of type representations is not done efficiently with hashing (not yet available), but with the usual structural comparison of the type representation.
-\item Foreign, Ptr, Weak, etc: garbage collection related functionality is influenced by the use of Boehm GC, e.g. only a minimal interface for weak pointers, finalizers, etc is available, not doing very much.
-\end{itemize}
-
-\subsection{Library + runtime}
-The C based backends (C, bc) use the following public domain libraries:
-
-\subsubsection{Third party libraries}
-\begin{itemize}
-\item \href{http://gmplib.org/}{GMP} GNU Multiple Precision library.
-\item \href{http://www.hpl.hp.com/personal/Hans_Boehm/gc/}{Boehm Garbage Collection} library.
- We are working on a replacement for this library.
-\end{itemize}
-
-\subsubsection{Known issues}
-\begin{itemize}
-\item Stacksize for the C based backends is fixed and not checked for overflow.
-\item Error messages involving types are difficult to decode; too much of the internals of the type system machinery is exposed.
-\item
- Compilation of a single module which uses many imports (directly or indirectly) takes noticably more time because reading in @.hi@ files takes time.
- Currently @.hi@ files are stored as text files and parsed as such, which is less efficient than a binary representation.
-\item
- Executables for code generation target @bc@ get quite large: the C encoding of bytecode files for modules is rather inefficient and linking together with the base libraries draws in most of the library code.
-\item
- Large expressions involving many class constraints take non lineair compile time, consumed by context reduction.
-\item
- When compiling with option @--cpp@ the file preprocessed by @cpp@ is put in the same directory as the source file.
- Without write permission this will fail.
-\item
- Overlapping instances are not reported as such, but indirectly by producing an error that a class constraint could not be proved.
-\item
- Local instances are not always working properly. Stick to its use without abstraction, i.e. only ground instances.
-\end{itemize}
\subsection{Packages}
-Packages can not be used, although a minimal framework for packages is already in use internally. If so desired one can build and use packages in separate locations as follows:
-
-\begin{itemize}
-\item \emph{Build} a pkg @<pkg>@:
-\begin{pre}
-uhc --target=<target> --odir=<install>/<target>/<pkg> --pkg-build-libdir=<install>/<target>/ --pkg-build=<pkg> --import-path=<install>/<target>/<pkg>/include <pkg-files>
-\end{pre}
-Optionally provide specify commandline options @--cpp@, if @cpp@ preprocessing is necessary.
-If @cpp@ includes are part of the package, these should be in @<install>/<target>/<pkg>/include@; then also pass option @--import-path=<install>/<target>/<pkg>/include@.
-Generated library files like @.hi@ interface files and a linked library are put in the location specified by @--odir@.
-\item \emph{Use} a pkg @<pkg>@:
-\begin{pre}
-uhc --lib-search-path=<install> ...
-\end{pre}
-If the package is put in the default location (usually something like @lib@ inside @/usr/local/lib/uhc-<version>@), option @--lib-search-path@ can be omitted.
-\end{itemize}
+%%@ToolDocEHC.packages
\subsection{Fully functional backends}
-\subsubsection{@bc@: GRIN based interpreter, no full program analysis}
-
-\begin{itemize}
-\item Only foreign functions with at most 3 arguments are allowed currently.
-\item The size of the stack is hardcoded. No runtime overflow check is done.
-\end{itemize}
-
-\subsubsection{@C@: GRIN based C, with full program analysis}
-
-\begin{itemize}
-\item No exceptions.
-\item The size of the stack is hardcoded. No runtime overflow check is done.
-\end{itemize}
-
-\subsection{Almost fully functional backends}
-\subsubsection{@jazy@: Core based Java, no full program analysis}
-
-\begin{itemize}
-\item Only when enabled via @configure --enable-java@.
-\item Runs for latest variant, but partial implementation of required primitives.
-\item No exceptions.
-\end{itemize}
-
-\subsection{Partially functional backends}
-\subsubsection{@llvm@: GRIN based LLVM, with full program analysis}
-
-\begin{itemize}
-\item For variant 8 only, little runtime support.
-\end{itemize}
-
-\subsubsection{@clr@: GRIN based CLR, with full program analysis}
-
-\begin{itemize}
-\item For variant 8 only, no runtime support.
-\item Only when enabled via @configure --enable-clr@.
-\end{itemize}
-
-\subsection{XX}
+%%@ToolDocEHC.backends
\section{Troubleshooting FAQ}
\glabel{TroubleshootingFAQ}
\label{TroubleshootingFAQ}
%%@ToolDocEHC.troubleShootFAQ
+\section{License}
+\glabel{UhcLicense}
+\label{UhcLicense}
+%%@ToolDocEHC.license
\section{Further reading}
%%@ToolDocEHC.andFurther
+
%%]
%%[preamble
@@ -563,9 +461,17 @@ make test-regress TEST_VARIANTS=uhc
...
%
\end{verbatim}
+
+Differences may also be reported because of platform dependent representation of linefeeds.
+This is not intended.
\end{itemize}
%%]]
+\subsubsection{Troubleshoot}
+
+See the \lref{TroubleshootingFAQ}{troubleshooting FAQ}.
+%%]]
+
\subsubsection{Build a EHC variant}
\begin{itemize}
@@ -606,6 +512,186 @@ Hello World
%%[extensions doclatex
%%]
+%%[higherRankTypes doclatex
+Higher ranked types are specified explicitly:
+
+\begin{pre}
+poly1 :: (forall a . a -> a) -> (Int,Bool)
+poly1 f = (f 1, f True)
+\end{pre}
+
+Alternatively, the type information can be specified without a separate type signature by mixing annotations throughout patterns and expressions:
+
+\begin{pre}
+poly2 (f :: forall a . a -> a) = (f (1::Int), f True)
+\end{pre}
+
+In both cases the relevant specified type information is propagated to where it is needed.
+
+Such type information may be freely mixed with tuples:
+
+\begin{pre}
+poly3 :: (b,forall a . a -> a) -> (Int,b)
+poly3 (b,f) = (f 1, f b)
+
+poly4 (b,f :: forall a . a -> a) = (f (1::Int), f b)
+\end{pre}
+
+or type constructors:
+
+\begin{pre}
+data T a b = T a b
+
+poly5 :: T b (forall a . a -> a) -> (Int,b)
+poly5 (T b f) = (f 1, f b)
+
+poly6 (T b (f :: forall a . a -> a)) = (f (1::Int), f b)
+\end{pre}
+
+Quantified types may also be used at arbitrary rank, in this case rank-3:
+
+\begin{pre}
+poly7 :: ((forall a . a -> a) -> (Int,Bool)) -> (Int,Bool)
+poly7 poly = poly id
+
+pval = poly7 poly1
+\end{pre}
+
+%%]
+
+%%[coContraVariance doclatex
+With rank co- and contravariance swap.
+For example, in the following a more general function can be used where a less general is expected; @id@ can be used as an implementation for @ii@:
+
+\begin{pre}
+ii :: Int -> Int
+ii = id
+\end{pre}
+
+However, the following does \emph{not} work because the instantiation relation swaps direction on a contravariance position.
+
+\begin{pre}
+id2 :: (forall a . a -> a) -> Int
+id2 i = i 3
+
+ii2 :: (Int -> Int) -> Int
+ii2 = id2 -- type error
+\end{pre}
+
+@ii2@ cannot pass to @id2@ a function of type \verb|forall a . a -> a| because it only gets a \verb|Int -> Int|!
+However, the other way around is perfectly ok:
+
+\begin{pre}
+id2 :: (forall a . a -> a) -> Int
+id2 = ii2
+
+ii2 :: (Int -> Int) -> Int
+ii2 i = i 3
+\end{pre}
+
+This extends to higher ranks as well:
+
+\begin{pre}
+id3 :: ((forall a . a -> a) -> Int) -> Int
+id3 i = i id
+
+ii3 :: ((Int -> Int) -> Int) -> Int
+ii3 = id3
+\end{pre}
+
+@id3@ gets a function to which it must pass a function of type \verb|forall a . a -> a|;
+it is then ok when this function is used as \verb|Int -> Int|, so as a value for @ii3@ we can use @id3@.
+Both of these invocations are therefore legal:
+
+\begin{pre}
+id3app1 = id3 id2
+id3app2 = id3 ii2
+\end{pre}
+
+However, the other way around fails for passing @ii3@ a function @id2@ which then \emph{must} be given a \verb|forall a . a -> a|.
+
+\begin{pre}
+ii3app1 = ii3 id2 -- type error
+ii3app2 = ii3 ii2
+\end{pre}
+
+The mechanism extends to the use of class predicates:
+
+\begin{pre}
+ieq :: Eq a => a -> a
+ieq = id
+
+iord :: Ord a => a -> a
+iord = ieq
+\end{pre}
+
+Similarly for rank 2 we can define:
+
+\begin{pre}
+ieq2 :: (forall a . Eq a => a -> a) -> Int
+ieq2 = iord2
+
+iord2 :: (forall a . Ord a => a -> a) -> Int
+iord2 i = i 3
+\end{pre}
+
+This is ok: @ieq2@ constructs a function accepting an @Ord@ dictionary from the function it gets passed itself,
+which can then be passed to @iord2@.
+The compiler provides this coercion automatically.
+
+Currently this mechanism has limits:
+
+\begin{itemize}
+\item Although co- and contravariance is propagated and analysed through datatypes, coercions are only derived
+ for functions and tuples.
+\end{itemize}
+
+%%]
+
+%%[impredicativity doclatex
+UHC allows impredicativity, albeit with assistance of a programmer.
+For example, in the following example impredicativity means that the type
+of the argument to @single@ propagates with quantifiers;
+this must be done explicitly by using @~@ in front of an argument:
+
+\begin{pre}
+single :: forall a . a -> [a]
+single x = [x]
+
+ids1 = single id -- :: forall a . [a->a]
+ids2 = single ~id -- :: [forall a . a->a]
+\end{pre}
+
+For @ids2@ the type \verb|forall a . a->a| has been propagated via the argument type variable of @single@ to inside the list.
+For @ids1@ the argument is first instantiated.
+
+Alternatively we can enforce this by providing a type signature:
+
+\begin{pre}
+ids3 = single id :: [forall a . a->a]
+ids4 = single (id :: forall a . a->a)
+ids5 = (single :: (forall a. a-> a) -> [forall a. a->a]) id
+\end{pre}
+
+All these result in the same type as for @ids2@.
+Without type signature or use of @~@ the type of the argument will not be propagated impredicatively.
+
+
+
+%%]
+
+%%[rankImpredCaveats doclatex
+\begin{itemize}
+\item Inference is order sensitive, and sometimes difficult to predict/characterize:
+\begin{pre}
+cons1 = (:) (\x->x) ids
+cons2 = (:) (\x->x) ~ids -- should be: [forall a. a->a], but is forall a.[a->a]
+cons2' = (:) (\x->x :: forall a . a -> a) ~ids -- the extra annotation fixes this
+\end{pre}
+\item Requires programmer assistance to remedy this.
+\end{itemize}
+%%]
+
%%[partialTySig doclatex
Partial type signatures are fully specified type signatures where parts may be omitted and then later filled in by the type inferencer.
Partial type signatures offer a middle way between
@@ -931,6 +1017,146 @@ Calling conventions @dynamic@, @wrapper@, @export@ as well as wrapping as finali
%%]
+%%[libraryModules doclatex
+The library consists of
+\begin{itemize}
+\item UHC specific modules, tightly coupled with the underlying implementation. The names of these modules start with @UHC.@.
+\item Modules from the GHC distribution, used without changes.
+\item Modules cloned + adapted from the GHC distribution. This maybe involve a couple of \verb|#ifdef|s or more extensive changes. The intention is to have these changes merged back into the GHC library as to avoid library differences between Haskell implementations.
+\end{itemize}
+
+Currently, mostly modules from the @base@ package are available, only arrays from package @array@ are available.
+For each library module in the Haskell98 report we summarize what is working and what not.
+There are no backwards compatibility wrapper modules, as this is part of the @haskell98@ package.
+
+\begin{itemize}
+\item @Prelude@: fully available.
+\item @Ratio@: in @Data.Ratio@, fully available.
+\item @Complex@: in @Data.Complex@, fully available.
+\item @Numeric@: fully available.
+\item @Ix@: in @Data.Ix@, fully available.
+\item @Array@: in @Data.Array@, fully available.
+\item @List@: in @Data.List@, fully available.
+\item @Maybe@: in @Data.Maybe@, fully available.
+\item @Monad@: in @Control.Monad@, fully available.
+\item @IO@: under construction, the @Prelude@ part is as a temporary implementation available.
+\item @Directory@: not available.
+\item @System@: in @System.Environment@ and @System.Exit@, fully available.
+\item @Time@: not available.
+\item @Locale@: not available.
+\item @CPUTime@: not available.
+\item @Random@: not available.
+\end{itemize}
+
+More library modules are incorporated, we only list those which are not fully implemented:
+
+\begin{itemize}
+\item @Prelude@:
+\item @Data.Typeable@: @cast@ (and variants) always yields @Nothing@. Equality of type representations is not done efficiently with hashing (not yet available), but with the usual structural comparison of the type representation.
+\item Foreign, Ptr, Weak, etc: garbage collection related functionality is influenced by the use of Boehm GC, e.g. only a minimal interface for weak pointers, finalizers, etc is available, not doing very much.
+\end{itemize}
+
+\subsection{Library + runtime}
+The C based backends (C, bc) use the following public domain libraries:
+
+\subsubsection{Third party libraries}
+\begin{itemize}
+\item \href{http://gmplib.org/}{GMP} GNU Multiple Precision library.
+\item \href{http://www.hpl.hp.com/personal/Hans_Boehm/gc/}{Boehm Garbage Collection} library.
+ We are working on a replacement for this library.
+\end{itemize}
+
+\subsubsection{Known issues}
+\begin{itemize}
+\item Stacksize for the C based backends is fixed and not checked for overflow.
+\item Error messages involving types are difficult to decode; too much of the internals of the type system machinery is exposed.
+\item
+ Compilation of a single module which uses many imports (directly or indirectly) takes noticably more time because reading in @.hi@ files takes time.
+ Currently @.hi@ files are stored as text files and parsed as such, which is less efficient than a binary representation.
+\item
+ Executables for code generation target @bc@ get quite large: the C encoding of bytecode files for modules is rather inefficient and linking together with the base libraries draws in most of the library code.
+\item
+ Large expressions involving many class constraints take non lineair compile time, consumed by context reduction.
+\item
+ When compiling with option @--cpp@ the file preprocessed by @cpp@ is put in the same directory as the source file.
+ Without write permission this will fail.
+\item
+ Overlapping instances are not reported as such, but indirectly by producing an error that a class constraint could not be proved.
+\item
+ Local instances are not always working properly. Stick to its use without abstraction, i.e. only ground instances.
+\item
+ Building uhc on top of a previous one, with a different version number, does not work because the settings file holding the location of libraries is not yet updated.
+ See the \lref{TroubleshootingFAQ}{troubleshooting FAQ}.
+\item
+ Regression testing may report differences because of different linefeed encoding on different platforms.
+\end{itemize}
+%%]
+
+%%[packages doclatex
+Packages can not be used, although a minimal framework for packages is already in use internally. If so desired one can build and use packages in separate locations as follows:
+
+\begin{itemize}
+\item \emph{Build} a pkg @<pkg>@:
+\begin{pre}
+uhc --target=<target> --odir=<install>/<target>/<pkg> --pkg-build-libdir=<install>/<target>/ --pkg-build=<pkg> --import-path=<install>/<target>/<pkg>/include <pkg-files>
+\end{pre}
+Optionally provide specify commandline options @--cpp@, if @cpp@ preprocessing is necessary.
+If @cpp@ includes are part of the package, these should be in @<install>/<target>/<pkg>/include@; then also pass option @--import-path=<install>/<target>/<pkg>/include@.
+Generated library files like @.hi@ interface files and a linked library are put in the location specified by @--odir@.
+\item \emph{Use} a pkg @<pkg>@:
+\begin{pre}
+uhc --lib-search-path=<install> ...
+\end{pre}
+If the package is put in the default location (usually something like @lib@ inside @/usr/local/lib/uhc-<version>@), option @--lib-search-path@ can be omitted.
+\end{itemize}
+%%]
+
+%%[backends doclatex
+\subsubsection{@bc@: GRIN based interpreter, no full program analysis}
+
+\begin{itemize}
+\item Only foreign functions with at most 3 arguments are allowed currently.
+\item The size of the stack is hardcoded. No runtime overflow check is done.
+\end{itemize}
+
+\subsubsection{@C@: GRIN based C, with full program analysis}
+
+\begin{itemize}
+\item No exceptions.
+\item The size of the stack is hardcoded. No runtime overflow check is done.
+\end{itemize}
+
+\subsection{Almost fully functional backends}
+\subsubsection{@jazy@: Core based Java, no full program analysis}
+
+\begin{itemize}
+\item Only when enabled via @configure --enable-java@.
+\item Runs for latest variant, but partial implementation of required primitives.
+\item No exceptions.
+\end{itemize}
+
+\subsection{Partially functional backends}
+\subsubsection{@llvm@: GRIN based LLVM, with full program analysis}
+
+\begin{itemize}
+\item For variant 8 only, little runtime support.
+\end{itemize}
+
+\subsubsection{@clr@: GRIN based CLR, with full program analysis}
+
+\begin{itemize}
+\item For variant 8 only, no runtime support.
+\item Only when enabled via @configure --enable-clr@.
+\end{itemize}
+
+%%]
+
+%%[license doclatex
+\begin{pre}
+%%@[file:LICENSE%%]
+\end{pre}
+%%]
+
%%[commandlineInvocation doclatex
\label{CommandLine}
As printed by \verb=install/100/bin/ehc --help=:
@@ -994,6 +1220,19 @@ Boolean options are indicated by @Bool@, where @True@ and @False@ can be indicat
%%]
%%[troubleShootFAQ doclatex
+\subsection{I have installed UHC previously, now the libraries do not compile}
+
+From a previous install the library path settings may linger around.
+This information is stored in the file reported by:
+
+\begin{pre}
+% uhc --meta-dir-env
+/Volumes/Work/.uhc-101
+%
+\end{pre}
+
+Remove this directory.
+
\subsection{I have checked out a new EHC version over a previously working one, and now it does not compile anymore}
Many things currently change, in particular also in the build process,

0 comments on commit d48aab6

Please sign in to comment.