From: panne Date: Sun, 15 Aug 2004 20:33:05 +0000 (+0000) Subject: [project @ 2004-08-15 20:32:47 by panne] X-Git-Tag: Initial_conversion_from_CVS_complete~1738 X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=69907617d58f6a97f7dc0b5e03b2fa0931ee686f;p=ghc-hetmet.git [project @ 2004-08-15 20:32:47 by panne] Converted the building guide to DocBook XML --- diff --git a/docs/building/Makefile b/docs/building/Makefile index d9400da..fb9cce6 100644 --- a/docs/building/Makefile +++ b/docs/building/Makefile @@ -1,7 +1,7 @@ TOP = ../.. include $(TOP)/mk/boilerplate.mk -SGML_DOC = building -INSTALL_SGML_DOC = building +XML_DOC = building +INSTALL_XML_DOC = building include $(TOP)/mk/target.mk diff --git a/docs/building/building.sgml b/docs/building/building.xml similarity index 98% rename from docs/building/building.sgml rename to docs/building/building.xml index 3f47334..8547e81 100644 --- a/docs/building/building.sgml +++ b/docs/building/building.xml @@ -1,8 +1,10 @@ - + +
- + Building the Glasgow Functional Programming Tools Suite The GHC Team @@ -22,10 +24,10 @@ now provided in the user guide. The bulk of this guide applies to building on Unix - systems; see for Windows notes. + systems; see for Windows notes. - + @@ -81,7 +83,7 @@ scratch. More information about our CVS repository can be found - in . + in . @@ -110,8 +112,8 @@ Getting access to the CVS Repository You can access the repository in one of two ways: - read-only (), or read-write (). + read-only (), or read-write (). Remote Read-only CVS Access @@ -149,7 +151,7 @@ - Now go to . + Now go to . @@ -233,7 +235,7 @@ Protocol 1 - Windows users: see the notes in about ssh wrinkles! + Windows users: see the notes in about ssh wrinkles! @@ -412,7 +414,7 @@ $ cvs checkout ghc hslibs libraries you need at least the ghc, hslibs and libraries modules (for a full list of the projects available, see - ). + ). Remember that if you do not have happy and/or Alex @@ -863,21 +865,21 @@ $ cvs checkout nofib/spectral Use an appropriate machine / operating system. lists the supported platforms; if + linkend="sec-port-info"/> lists the supported platforms; if yours isn't amongst these then you can try porting GHC (see - ). + ). Be sure that the “pre-supposed” utilities are - installed. + installed. elaborates. If you have any problem when building or installing the Glasgow tools, please check the “known pitfalls” (). Also check the FAQ for the + linkend="sec-build-pitfalls"/>). Also check the FAQ for the version you're building, which is part of the User's Guide and available on the GHC web site. @@ -1200,7 +1202,7 @@ $ cvs checkout nofib/spectral GHC is required to build many of the tools, including GHC itself. If you need to port GHC to your platform because there isn't a binary distribution of GHC available, - then see . + then see . Which version of GHC you need will depend on the packages you intend to build. GHC itself will normally @@ -1413,7 +1415,7 @@ $ cvs checkout nofib/spectral More tools are required if you want to format the documentation that comes with GHC and other fptools projects. See . + linkend="building-docs"/>. @@ -1535,7 +1537,7 @@ $ make install includes sources for the X11 lndir—check out fptools/glafp-utils/lndir). See for a typical invocation. + linkend="sec-storysofar"/> for a typical invocation. The build tree does not need to be anywhere near the source tree in the file system. Indeed, one advantage of @@ -1544,7 +1546,7 @@ $ make install support people from backing up untold megabytes of easily-regenerated, and rapidly-changing, gubbins. The golden rule is that (with a single exception—) absolutely everything in + linkend="sec-build-config"/>) absolutely everything in the build tree is either a symbolic link to the source tree, or else is mechanically generated. It should be perfectly OK for your build tree to vanish overnight; an hour or @@ -1618,7 +1620,7 @@ $ make install Change directory to $(FPTOOLS_TOP) and issue the command -autoreconf +$ autoreconf autoreconf (with no arguments). This GNU program (recursively) converts $(FPTOOLS_TOP)/configure.ac and @@ -1650,7 +1652,7 @@ $ make install Runs the newly-created configure script, thus: -./configure args +$ ./configure args configure's mission is to scurry round your computer working out what architecture it has, @@ -1862,7 +1864,7 @@ $ make install myfptools (it does not have to be called fptools). Make sure that you have the essential files (see ). + linkend="sec-source-tree"/>). @@ -1870,8 +1872,8 @@ $ make install (Optional) Use lndir or mkshadowdir to create a build tree. -$ cd myfptools -$ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 +$ cd myfptools +$ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 (N.B. mkshadowdir's first argument is taken relative to its second.) You probably want to give @@ -1884,14 +1886,14 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 Change directory to the build tree. Everything is going to happen there now. -$ cd /scratch/joe-bloggs/myfptools-sun4 +$ cd /scratch/joe-bloggs/myfptools-sun4 Prepare for system configuration: -$ autoreconf +$ autoreconf (You can skip this step if you are starting from a source distribution, and you already have @@ -1902,7 +1904,7 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 Do system configuration: -$ ./configure +$ ./configure Don't forget to check whether you need to add any arguments to configure; for example, a @@ -1915,7 +1917,7 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 adding definitions for your desired configuration options. -$ emacs mk/build.mk +$ emacs mk/build.mk @@ -2185,7 +2187,7 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 is only available in the root directory $(FPTOOLS_TOP); it has been discussed in . + linkend="sec-build-config"/>. @@ -2268,7 +2270,7 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 make is going to rebuild everything anyway, the following hack may be useful: -gmake FAST=YES +$ gmake FAST=YES This tells the make system to ignore dependencies and just build what you tell it to. In other words, it's equivalent to @@ -2368,7 +2370,7 @@ directive. As its name suggests, boilerplate.mk consists of a large quantity of standard Makefile code. We discuss this - boilerplate in more detail in . + boilerplate in more detail in . include, directive in Makefiles Makefile inclusion @@ -2419,7 +2421,7 @@ directive. (the executable binary to be built). We will discuss in more detail what the “standard variables” are, and how they affect what happens, in . + linkend="sec-targets"/>. The definition for SRCS uses the useful GNU make construct @@ -2439,11 +2441,11 @@ directive. target.mktarget.mk. It contains the rules that tell gmake how to make the standard targets (). Why, you ask, can't this + linkend="sec-standard-targets"/>). Why, you ask, can't this standard code be part of boilerplate.mk? Good question. We discuss the reason later, in . + linkend="sec-boiler-arch"/>. You do not have to include the @@ -2453,7 +2455,7 @@ directive. canned rules in target.mk; the price tag is that you have to understand what canned rules get enabled, and what they do (). + linkend="sec-targets"/>). @@ -2509,7 +2511,7 @@ directive. rare.) To give you the idea, here's part of the directory structure for the (rather large) GHC project: -$(FPTOOLS_TOP)/ghc/ +$(FPTOOLS_TOP)/ghc/ Makefile mk/ boilerplate.mk @@ -2524,7 +2526,7 @@ directive. Makefile parser/...source files for parser... renamer/...source files for renamer... - ...etc... + ...etc... The sub-directories docs, driver, compiler, and @@ -2643,7 +2645,7 @@ directive. target.mk contains make rules for the standard targets - described in . These + described in . These rules are selectively included, depending on the setting of certain make variables. These variables are usually set in the middle section of the @@ -2716,7 +2718,7 @@ directive. is the build configuration file we discussed at - length in . + length in . @@ -2927,7 +2929,7 @@ directive. strings to pass to each program. For example, it defines HC_OPTSHC_OPTS, the option strings to pass to the Haskell compiler. See - . + . @@ -2937,7 +2939,7 @@ directive. defines standard pattern rules—see . + linkend="sec-suffix"/>. @@ -3021,7 +3023,7 @@ directive. mp. The variable WAY_CC_OPTS holds options to pass to the C compiler when compiling the - standard way. ( dicusses + standard way. ( dicusses multi-way compilation.) @@ -3043,7 +3045,7 @@ directive. extra options to pass to all C compilations. This is intended for command line use, thus: -gmake libHS.a EXTRA_CC_OPTS="-v" +$ gmake libHS.a EXTRA_CC_OPTS="-v" @@ -3055,7 +3057,7 @@ directive. target.mk contains canned rules for all the standard targets described in . It is complicated by the fact + linkend="sec-standard-targets"/>. It is complicated by the fact that you don't want all of these rules to be active in every Makefile. Rather than have a plethora of tiny files which you can include selectively, there is a single @@ -3181,7 +3183,7 @@ directive. When SUBDIRS is defined, target.mk includes a rather neat rule for - the standard targets ( that + the standard targets ( that simply invokes make recursively in each of the sub-directories. @@ -3271,7 +3273,7 @@ directive. want these targets built for. The mechanism here is very much like the recursive invocation of make in sub-directories (). It is up to you to set + linkend="sec-subdirs"/>). It is up to you to set WAYS in your Makefile; this is how you control what ways will get built. @@ -3592,14 +3594,14 @@ $ make install 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. Proceed to - . + . 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). Proceed to . + linkend="unregisterised-porting"/>. @@ -3625,7 +3627,7 @@ $ make install supplied on the GHC download page, otherwise you'll have to compile some up yourself, or start from unregisterised HC files - see . + linkend="unregisterised-porting"/>. The following steps should result in a working GHC build with full libraries: @@ -3652,7 +3654,7 @@ $ make install command will execute the whole build process (it won't install yet): -foo% distrib/hc-build --prefix=dir +$ distrib/hc-build --prefix=dir --hc-build By default, the installation directory is @@ -3665,7 +3667,7 @@ $ make install build process, you can install the resulting system, as normal, with -foo% make install +$ make install @@ -3879,7 +3881,7 @@ $ make hc-file-bundle Project=Ghc from the intermediate C files we generated above. The process of bootstrapping from C files is automated by the script in distrib/hc-build, and is - described in . + described in . $ ./distrib/hc-build --enable-hc-boot-unregisterised @@ -3942,7 +3944,7 @@ Hello World! Macros that cooperate with the mangler (see ) to make proper tail-calls + linkend="sec-mangler"/>) to make proper tail-calls work. @@ -4178,13 +4180,13 @@ above. -and try again: gmake. (see for information about +and try again: gmake. (see for information about <module>_HC_OPTS.) Alternatively, just cut to the chase: -% cd ghc/compiler -% make EXTRA_HC_OPTS=-optCrts-M128M +$ cd ghc/compiler +$ make EXTRA_HC_OPTS=-optCrts-M128M @@ -4208,8 +4210,8 @@ this bug also suggests that you have an old GCC. You may need to re-ranlibranlib your libraries (on Sun4s). -% cd $(libdir)/ghc-x.xx/sparc-sun-sunos4 -% foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv... +$ cd $(libdir)/ghc-x.xx/sparc-sun-sunos4 +$ foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv... ? ranlib $i ? # or, on some machines: ar s $i ? end @@ -4465,7 +4467,7 @@ installing and running GHC may be found in the user guide. In general, Win95/Win98 behave the same, and WinNT/Win2k behave the same. -Make sure you read the preceding section on platforms () +Make sure you read the preceding section on platforms () before reading section. You don't need Cygwin or MSYS to use GHC, but you do need one or the other to build GHC. @@ -4658,7 +4660,7 @@ they don't recognise symlinks. -See the notes in about find and bzip, +See the notes in about find and bzip, which apply to Cygwin too. @@ -4692,7 +4694,7 @@ To determine your home directory ssh first looks in there with your userid, it'll use that entry to determine your home directory, ignoring the setting of the environment variable $HOME. If the home directory is bogus, ssh fails horribly. The best way to see what is going on is to say -ssh -v cvs.haskell.org +ssh -v cvs.haskell.org which makes ssh print out information about its activity. You can fix this problem, either by correcting the home-directory field in @@ -4756,9 +4758,9 @@ you need to add upon completion. Install an executable Happy, from http://www.haskell.org/happy. Happy is a parser generator used to compile the Haskell grammar. Under MSYS or Cygwin you can easily build it from the source distribution using -./configure -make -make install +$ ./configure +$ make +$ make install This should install it in /usr/local/bin (which maps to c:/msys/1.0/local/bin on MSYS). Make sure the installation directory is in your @@ -4775,7 +4777,7 @@ Make sure the installation directory is in your GHC uses the mingw C compiler to -generate code, so you have to install that (see ). +generate code, so you have to install that (see ). Just pick up a mingw bundle at http://www.mingw.org/. We install it in c:/mingw. @@ -4802,7 +4804,7 @@ so you will need to add emacs/bin to your PATH Finally, check out a copy of GHC sources from -the CVS repository, following the instructions above (). +the CVS repository, following the instructions above (). @@ -4812,7 +4814,7 @@ the CVS repository, following the instructions above (Building GHC OK! -Now go read the documentation above on building from source (); +Now go read the documentation above on building from source (); the bullets below only tell you about Windows-specific wrinkles. @@ -4843,9 +4845,9 @@ Solution: delete configure first. After autoreconf run ./configure in fptools/ thus: -./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc +$ ./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc This is the point at which you specify that you are building GHC-mingw -(see ). +(see ). Both these options are important! It's possible to get into trouble using the wrong C compiler! @@ -4875,9 +4877,9 @@ Be warned! -If you want to build GHC-cygwin () +If you want to build GHC-cygwin () you'll have to do something more like: -./configure --with-gcc=...the Cygwin gcc... +$ ./configure --with-gcc=...the Cygwin gcc... @@ -4890,7 +4892,7 @@ can be really confusing. You almost certainly want to set SplitObjs = NO -in your build.mk configuration file (see ). +in your build.mk configuration file (see ). This tells the build system not to split each library into a myriad of little object files, one for each function. Doing so reduces binary sizes for statically-linked binaries, but on Windows it dramatically increases the time taken to build the libraries in the first place.