From 7d5216deadd492dbb027753ef83f1c43ec1e9222 Mon Sep 17 00:00:00 2001 From: simonmar Date: Tue, 25 Oct 2005 10:28:59 +0000 Subject: [PATCH] [project @ 2005-10-25 10:28:59 by simonmar] - include the contents of ghc/HACKING verbatim, as a "quick start" guide - change the title to "Building and devleloping GHC", and make it a bit more GHC-centric. --- docs/building/building.xml | 160 +++++++++++++++++++++----------------------- 1 file changed, 78 insertions(+), 82 deletions(-) diff --git a/docs/building/building.xml b/docs/building/building.xml index 0375c38..6ea21e6 100644 --- a/docs/building/building.xml +++ b/docs/building/building.xml @@ -1,27 +1,23 @@ + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + +]>
-Building the Glasgow Functional Programming Tools Suite +Building and developing GHC The GHC Team
glasgow-haskell-{users,bugs}@haskell.org
- The Glasgow fptools suite is a collection of Functional - Programming related tools, including the Glasgow Haskell - Compiler (GHC). The source code for the whole suite is kept in - a single CVS repository and shares a common build and - installation system. - - This guide is intended for people who want to build or - modify programs from the Glasgow fptools - suite (as distinct from those who merely want to - run them). Installation instructions are - now provided in the user guide. + This Guide is primarily aimed at those who want to build and/or + hack on GHC. It describes how to get started with building GHC on your + machine, and how to tweak the settings to get the kind of build you + want. It also describes the inner workings of the build system, so you + can extend it, modify it, and use it to build your code. The bulk of this guide applies to building on Unix systems; see for Windows notes. @@ -33,8 +29,7 @@ Getting the sources - You can get your hands on the fptools - in two ways: + You can get your hands on the GHC sources in two ways: @@ -49,8 +44,7 @@ (c) you want to hack on GHC yourself. A source distribution contains complete sources for - one or more projects in the fptools - suite. Not only that, but the more awkward + GHC. Not only that, but the more awkward machine-independent steps are done for you. For example, if you don't have happyhappy @@ -71,7 +65,7 @@ up-to-the minute (but less tested) source code then you need to get access to our CVS repository. - All the fptools source code is held + All the GHC source code is held in a CVS repository. CVS is a pretty good source-code control system, and best of all it works over the network. @@ -87,10 +81,6 @@ - - If you are going to do any building from sources (either - from a source distribution or the CVS repository) then you need to - read all of this manual in detail. @@ -903,7 +893,7 @@ $ cvs checkout nofib/spectral - What machines the Glasgow tools run on + What machines GHC runs on portsGHC GHCports @@ -1090,20 +1080,11 @@ $ cvs checkout nofib/spectral x86_64-unknown-linux x86_64-unknown-linux - - GHC currently works unregisterised. A registerised - port is in progress. - - - - - amd64-unknown-openbsd +amd64-unknown-openbsd amd64-unknown-linux - (This is the same as x86_64-unknown-openbsd). GHC - currently works unregisterised. A registerised port is in - progress. + Fully supported, with a native code generator and GHCi. @@ -1166,16 +1147,8 @@ $ cvs checkout nofib/spectral support still remains, but porting to one of these systems will certainly be a non-trivial task. - - - What machines the other tools run on - - Unless you hear otherwise, the other tools work if GHC - works. - - Installing pre-supposed utilities @@ -1242,16 +1215,12 @@ $ cvs checkout nofib/spectral GCC (GNU C compiler), pre-supposed - We recommend using GCC version 2.95.2 on all - platforms. Failing that, version 2.7.2 is stable on most - platforms. Earlier versions of GCC can be assumed not to - work, and versions in between 2.7.2 and 2.95.2 (including - egcs) have varying degrees of stability - depending on the platform. - - GCC 3.2 is currently known to have problems building - GHC on Sparc, but is stable on x86. - + Most GCC versions should work with the most recent GHC + sources. Expect trouble if you use a recent GCC with + an older GHC, though (trouble in the form of mis-compiled code, + link errors, and errors from the ghc-asm + script). + If your GCC dies with “internal error” on some GHC source file, please let us know, so we can report it and get things improved. (Exception: on x86 @@ -1279,14 +1248,23 @@ $ cvs checkout nofib/spectral Happy is a parser generator tool for Haskell, and is - used to generate GHC's parsers. Happy is written in + used to generate GHC's parsers. + + If you start from a source tarball of GHC (i.e. not a CVS + checkout), then you don't need Happy, because we supply the + pre-processed versions of the Happy parsers. If you intend to + modify the compiler and/or you're using a CVS checkout, then you + need Happy. + + Happy version 1.15 is currently required to build GHC. + + Happy is written in Haskell, and is a project in the CVS repository (fptools/happy). It can be built from source, but bear in mind that you'll need GHC installed in order to build it. To avoid the chicken/egg problem, install a binary distribution of either Happy or GHC to get - started. Happy distributions are available from Happy's Web + started. Happy distributions are available from Happy's Web Page. @@ -1297,10 +1275,15 @@ $ cvs checkout nofib/spectral Alex is a lexical-analyser generator for Haskell, - which GHC uses to generate its lexer. Like Happy, Alex is + which GHC uses to generate its lexer. + + Like Happy, you don't need Alex if you're building GHC from a + source tarball, but you do need it if you're modifying GHC and/or + building a CVS checkout. + + Alex is written in Haskell and is a project in the CVS repository. - Alex distributions are available from Alex's Web + Alex distributions are available from Alex's Web Page. @@ -1425,41 +1408,54 @@ $ cvs checkout nofib/spectral Building from source Source, building from - You've been rash enough to want to build some of the Glasgow - Functional Programming tools (GHC, Happy, nofib, etc.) from - source. You've slurped the source, from the CVS repository or - from a source distribution, and now you're sitting looking at a - huge mound of bits, wondering what to do next. - - Gingerly, you type make. Wrong - already! + “I just want to build it!” - This rest of this guide is intended for duffers like me, who - aren't really interested in Makefiles and systems configurations, - but who need a mental model of the interlocking pieces so that - they can make them work, extend them consistently when adding new - software, and lay hands on them gently when they don't - work. - - - Quick Start - - If you are starting from a source distribution, and just - want a completely standard build, then the following procedure should - work (unless you're on Windows, in which case go to ). + No problem. This recipe should build and install a working GHC with + all the default settings. (unless you're + on Windows, in which case go to ). -$ autoreconf +$ autoreconfnot necessary if you started from a source tarball + $ ./configure $ make $ make install For GHC, this will do a 2-stage bootstrap build of the compiler, with profiling libraries, and install the - results. + results in the default location (under /usr/local on + Unix, for example). + + The configure script is a standard GNU + autoconf script, and accepts the usual options for + changing install locations and the like. Run + ./configure --help for a list of options. If you want to do anything at all non-standard, or you want to do some development, read on... - + + + + Quick start for GHC developers + + This section is a copy of the file + ghc/HACKING from the GHC source tree. It describes + how to get started with setting up your build tree for developing GHC + or its libraries, and how to start building. + + +&hacking; + + + + + Working with the build system + + This rest of this guide is intended for duffers like me, who + aren't really interested in Makefiles and systems configurations, + but who need a mental model of the interlocking pieces so that + they can make them work, extend them consistently when adding new + software, and lay hands on them gently when they don't + work. Your source tree -- 1.7.10.4