From: simonmar Date: Tue, 30 Apr 2002 16:34:12 +0000 (+0000) Subject: [project @ 2002-04-30 16:34:12 by simonmar] X-Git-Tag: Approx_11550_changesets_converted~2078 X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=89418e67066fb75ee08a482617106e2fa7af4d41;p=ghc-hetmet.git [project @ 2002-04-30 16:34:12 by simonmar] Add a FAQ section. This will replace the mini-FAQ on the download page (which we never really kept up to date), and will hopefully accumulate all sorts of useful Q/As over time. Please feel free to add to it... --- diff --git a/ghc/docs/users_guide/faq.sgml b/ghc/docs/users_guide/faq.sgml new file mode 100644 index 0000000..dd7225b --- /dev/null +++ b/ghc/docs/users_guide/faq.sgml @@ -0,0 +1,215 @@ + + 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 bootrap 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. + + + + + + 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. + + + + + 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 behavour 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. + + + + + + + + diff --git a/ghc/docs/users_guide/intro.sgml b/ghc/docs/users_guide/intro.sgml index 13963cf..af38b51 100644 --- a/ghc/docs/users_guide/intro.sgml +++ b/ghc/docs/users_guide/intro.sgml @@ -79,8 +79,9 @@ glasgow-haskell-users: - This list is for GHC users to chat among - themselves. + This list is for GHC users to chat among themselves. + If you have a specific question about GHC, please check the + FAQ first (). @@ -240,15 +241,22 @@ - How do I tell if my bug has already been - reported? - - Try searching the mailing list archives. The archives - don't have a built-in search facility, but we find that How do I tell if I should report my bug? + + Take a look at the FAQ () and , which will give you some guidance as to + whether the behaviour you're seeing is really a bug or + not. + + If it is a bug, then it might have been reported before: + try searching the mailing list archives. The archives don't + have a built-in search facility, but we find that Google's site search works pretty well: enter site:www.haskell.org followed by your search term into Google. + + If in doubt, just report it. diff --git a/ghc/docs/users_guide/ug-book.sgml b/ghc/docs/users_guide/ug-book.sgml index f8bcf23..10dc11e 100644 --- a/ghc/docs/users_guide/ug-book.sgml +++ b/ghc/docs/users_guide/ug-book.sgml @@ -18,3 +18,5 @@ &wrong; &utils; &win32-dll; +&faq; + diff --git a/ghc/docs/users_guide/ug-ent.sgml b/ghc/docs/users_guide/ug-ent.sgml index 8323372..e370360 100644 --- a/ghc/docs/users_guide/ug-ent.sgml +++ b/ghc/docs/users_guide/ug-ent.sgml @@ -1,4 +1,5 @@ +