From b4c60e5b3da74da56fc22f3e494c5d293b80f9df Mon Sep 17 00:00:00 2001 From: simonmar Date: Tue, 13 Dec 2005 12:45:08 +0000 Subject: [PATCH] [project @ 2005-12-13 12:45:08 by simonmar] the FAQ is now in the Wiki --- ghc/docs/users_guide/faq.xml | 530 ----------------------------------- ghc/docs/users_guide/ug-book.xml.in | 1 - ghc/docs/users_guide/ug-ent.xml | 1 - 3 files changed, 532 deletions(-) delete mode 100644 ghc/docs/users_guide/faq.xml diff --git a/ghc/docs/users_guide/faq.xml b/ghc/docs/users_guide/faq.xml deleted file mode 100644 index 3250cc9..0000000 --- a/ghc/docs/users_guide/faq.xml +++ /dev/null @@ -1,530 +0,0 @@ - - - GHC FAQ - - This section has the answers to questions that get asked - regularly on the GHC mailing lists, in no particular order. Please - let us know if you think there's a question/answer that should be - added here. - - - - How do I port GHC to platform X? - - There are two distinct possibilities: either - - - The hardware architecture for your system is already - supported by GHC, but you're running an OS that isn't - supported (or perhaps has been supported in the past, but - currently isn't). This is the easiest type of porting - job, but it still requires some careful - bootstrapping. - - - - Your system's hardware architecture isn't supported - by GHC. This will be a more difficult port (though by - comparison perhaps not as difficult as porting - gcc). - - - - Both ways require you to bootstrap from intermediate - HC files: these are the stylised C files - generated by GHC when it compiles Haskell source. Basically - the idea is to take the HC files for GHC itself to the target - machine and compile them with gcc to get a - working GHC, and go from there. - - The Building - Guide has all the details on how to bootstrap GHC on a - new platform. - - - - - - Do I have to recompile all my code if I upgrade - GHC? - - Yes. There are two reasons for this: - - - GHC does a lot of cross-module optimisation, so - compiled code will include parts of the libraries it was - compiled against (including the Prelude), so will be - deeply tied to the actual version of those libraries it - was compiled against. When you upgrade GHC, the libraries - may change; even if the external interface of the - libraries doesn't change, sometimes internal details may - change because GHC optimised the code in the library - differently. - - - We sometimes change the ABI (application binary - interface) between versions of GHC. Code compiled with - one version of GHC is not necessarily compatible with code - compiled by a different version, even if you arrange to - keep the same libraries. - - - - - - - Why doesn't GHC use shared libraries? - - The subject of shared libraries has come up several - times in the past — take a look through the mailing-list - archives for some of the previous discussions. The upshot is - that shared libraries wouldn't really buy much unless you - really need to save the disk space: in all other - considerations, static linking comes out better. - - Unfortunately GHC-compiled libraries are very tightly - coupled, which means it's unlikely you'd be able to swap out a - shared library for a newer version unless it was compiled with - exactly the same compiler and set of - libraries as the old version. - - - - - I can't get string gaps to work - - If you're also using CPP, beware of the known pitfall - with string gaps mentioned in . - - - - - GHCi complains about missing symbols like - CC_LIST when loading a previously compiled .o - file. - - This probably means the .o files in question were - compiled for profiling (with ). Workaround: - recompile them without profiling. We really ought to detect - this situation and give a proper error message. - - - - - Linking a program causes the following error on Linux: - /usr/bin/ld: cannot open -lgmp: No such file or - directory - - The problem is that your system doesn't have the GMP - library installed. If this is a RedHat distribution, install - the RedHat-supplied gmp-devel package, and - the gmp package if you don't already have - it. There have been reports that installing the RedHat - packages also works for SuSE (SuSE don't supply a shared gmp - library). - - - - - I Can't run GHCi on Linux, because it complains about a - missing libreadline.so.3. - - The "correct" fix for this problem is to install the - correct RPM for the particular flavour of Linux on your - machine. If this isn't an option, however, there is a hack - that might work: make a symbolic link from - libreadline.so.4 to - libreadline.so.3 in - /usr/lib. We tried this on a SuSE 7.1 box - and it seemed to work, but YMMV. - - - - - Solaris users may sometimes get link errors due to - libraries needed by GNU Readline. - - We suggest you try linking in some combination of the - termcap, curses and - ncurses libraries, by giving - -ltermcap, -lcurses and - -lncurses respectively. If you encounter - this problem, we would appreciate feedback on it, since we - don't fully understand what's going on here. - - - - - The build fails in readline. - - It has been reported that if you have multiple versions - of the readline library installed on Linux, then this may - cause the build to fail. If you have multiple versions of - readline, try uninstalling all except the most recent - version. - - - - - When I try to start ghci (probably one I compiled myself) - it says ghc-5.02: not built for interactive - use - - To build a working ghci, you need to build GHC 5.02 with - itself; the above message appears if you build it with 4.08.X, - for example. It'll still work fine for batch-mode - compilation, though. Note that you really must build with - exactly the same version of the compiler. Building 5.02 with - 5.00.2, for example, may or may not give a working interactive - system; it probably won't, and certainly isn't supported. - Note also that you can build 5.02 with any older compiler, - back to 4.08.1, if you don't want a working interactive - system; that's OK, and supported. - - - - - When I use a foreign function that takes or returns a - float, it gives the wrong answer, or crashes. - - You should use the option to - bring the correct prototype into scope (see ). - - - - - My program that uses a really large heap crashes on - Windows. - - For utterly horrible reasons, programs that use more - than 128Mb of heap won't work when compiled dynamically on - Windows (they should be fine statically compiled). - - - - - GHC doesn't like filenames containing - +. - - Indeed not. You could change + to - p or plus. - - - - - When I open a FIFO (named pipe) and try to read from it, I - get EOF immediately. - - This is a consequence of the fact that GHC opens the - FIFO in non-blocking mode. The behaviour varies from OS to - OS: on Linux and Solaris you can wait for a writer by doing an - explicit threadWaitRead on the file - descriptor (gotten from Posix.handleToFd) - before the first read, but this doesn't work on FreeBSD - (although rumour has it that recent versions of FreeBSD - changed the behaviour to match other OSs). A workaround for - all systems is to open the FIFO for writing yourself, before - (or at the same time as) opening it for reading. - - - - - When I foreign import a function that - returns char or short, I - get garbage back. - - This is a known bug in GHC versions prior to 5.02.2. - GHC doesn't mask out the more significant bits of the result. - It doesn't manifest with gcc 2.95, but apparently shows up - with g++ and gcc 3.0. - - - - - My program is failing with head [], or - an array bounds error, or some other random error, and I have no - idea how to find the bug. Can you help? - - - Compile your program with -prof --auto-all (make sure you have the profiling libraries -installed), and run it with +RTS -xc -RTS to get a -“stack trace” at the point at which the exception was -raised. See for more -details. - - - - - How do I increase the heap size permanently for a given - binary? - - See . - - - - - I'm trying to compile my program for parallel execution - with the , and GHC complains with an - error like “failed to load interface file for - Prelude”. - - GHC doesn't ship with support for parallel execution, - that support is provided separately by the GPH project. - - - - - When is it safe to use - unsafePerformIO? - - We'll give two answers to this question, each of which - may be helpful. These criteria are not rigorous in any real - sense (you'd need a formal semantics for Haskell in order to - give a proper answer to this question), but should give you a - feel for the kind of things you can and cannot do with - unsafePerformIO. - - - - It is safe to implement a function or API using - unsafePerformIO if you could imagine - also implementing the same function or API in Haskell - without using unsafePerformIO (forget - about efficiency, just consider the semantics). - - - - In pure Haskell, the value of a function depends - only on the values of its arguments (and free variables, - if it has any). If you can implement the function using - unsafePerformIO and still retain this - invariant, then you're probably using - unsafePerformIO in a safe way. Note - that you need only consider the - observable values of the arguments - and result. - - - - For more information, see this - thread. - - - - - Why does linking take so long? - - Linking a small program should take no more than a few - seconds. Larger programs can take longer, but even linking - GHC itself only takes 3-4 seconds on our development - machines. - - Long link times have been attributed to using Sun's - linker on Solaris, as compared to GNU ld - which appears to be much faster. So if you're on a Sun box, - try switching to GNU ld. This - article from the mailing list has more - information. - - - - - If I explicitly set the buffering on a Handle to - "NoBuffering" I'm not able to enter EOF by typing - "Ctrl-D". - - - This is a consequence of Unixy terminal semantics. Unix - does line buffering on terminals in the kernel as part of the - terminal processing, unless you turn it off. However, the - Ctrl-D processing is also part of the terminal processing - which gets turned off when the kernel line buffering is - disabled. So GHC tries its best to get NoBuffering semantics - by turning off the kernel line buffering, but as a result you - lose Ctrl-D. C'est la vie. - - - - - If I print out a string using putStr, - and then attempt to read some input using - hGetLine, I don't see the output from the - putStr. - - - The stdout handle is line-buffered by - default, which means that output sent to the handle is only - flushed when a newline (/n) is output, the - buffer is full, or hFlush is called on the - Handle. The right way to make the text appear without sending - a newline is to use hFlush: - - - import System.IO - main = do - putStr "how are you today? " - hFlush stdout - input &- hGetLine - ... - - You'll probably find that the behaviour differs when - using GHCi: the hFlush isn't necessary to - make the text appear. This is because 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. - - - - - I can't get finalizers to work properly. My program - sometimes just prints - <<loop>>. - - - Chances are that your program is trying to write a - message to stdout or - stderr in the finalizer. Handles have - finalizers themselves, and since finalizers don't keep other - finalized values alive, the stdout and - stderr Handles may be finalized before your - finalizer runs. If this happens, your finalizer will block on - the handle, and probably end up receiving a - NonTermination exception (which is printed - as <<loop>>). - - - - - - Does GHC implement any kind of extensible records? - - - No, extensible records are not implemented in GHC. - Hugs - implements TRex, one extensible record variant. The problem - is that the record design space is large, and seems to lack - local optima. And all reasonable variants break backward - compatibility. As a result, nothing much happens. - - - - - Why do I get errors about missing include files when - compiling with or - ? - - - Certain options, such as , turn on - via-C compilation, instead of using the native code generator. - Include files named by options - or in foreign import declarations are only - used in via-C compilation mode. See for more details. - - - - - How do I compile my program for profiling without - overwriting the object files and hi files - I've already built? - - You can select alternative suffixes for object files and - interface files, so you can have several builds of the same - code coexisting in the same directory. For example, to - compile with profiling, you might do this: - - ghc --make -prof -o foo-prof -osuf p.o -hisuf p.hi Main - - See for more details on - the and - options. - - - - - I can't use readline under GHCi on Windows - - In order to load the readline package under GHCi on Windows, you - need to make a version of the readline library that GHCi can load. - Instructions for GHC 6.2.2. are here. - - - - - Ctrl-C doesn't work on Windows - - When running GHC under a Cygwin shell on Windows, Ctrl-C - sometimes doesn't work. The workaround is to use Ctrl-Break - instead. - - - - - I get an error message from GHCi about a "duplicate definition for - symbol __module_registered" - - An error message like this: - - -GHCi runtime linker: fatal error: I found a duplicate definition for symbol - __module_registered - whilst processing object file - /usr/local/lib/ghc-6.2/HSfgl.o - - probably indicates that when building a library for GHCi - (HSfgl.o in the above example), you should use - the option to ld. - - - - - GHC puts stdin and stdout in - non-blocking mode, which causes problems when I try to invoke a text - editor (for example) using System.Cmd.system or - System.Cmd.rawSystem. - - - The real problem is that Unix shares the non-blocking flag - between all processes accessing a file or stream. It's impossible to - set this flag locally to a single process. GHC's I/O library needs - non-blocking mode to properly support multithreaded I/O. - - Here's one possible fix, if you know that your program isn't - going to be accessing stdin from another thread - while the sub-process is running: - - -> main = do stdin `seq` return () -> bracket (setFdOption stdInput NonBlockingRead False) -> (\_ -> setFdOption stdInput NonBlockingRead True) -> (\_ -> rawSystem "nvi" []) - - - - - Why doesn't GHC have a .NET back end? - - - See this message for a detailed answer to this question. - - - - - - - - - - diff --git a/ghc/docs/users_guide/ug-book.xml.in b/ghc/docs/users_guide/ug-book.xml.in index d098df4..c5710f1 100644 --- a/ghc/docs/users_guide/ug-book.xml.in +++ b/ghc/docs/users_guide/ug-book.xml.in @@ -20,7 +20,6 @@ &utils; &win32-dll; &bugs; -&faq;