[project @ 2001-10-23 14:53:14 by rrt]

[ghc-hetmet.git] / docs / building / building.sgml

diff --git a/docs/building/building.sgml b/docs/building/building.sgml
index d85c426..2c0b172 100644 (file)
--- a/docs/building/building.sgml
+++ b/docs/building/building.sgml
@@ -634,6 +634,15 @@ everything you need.
 </VariableList>
 </para>
 
+      <para>
+       In order to actually build any documentation, you need to set
+       <constant>SGMLDocWays</constant> in your
+       <filename>build.mk</filename>. Valid values to add to this
+       list are: <literal>dvi</literal>, <literal>ps</literal>,
+       <literal>pdf</literal>, <literal>html</literal>, and
+       <literal>rtf</literal>.
+      </para>
+      
 </Sect2>
 
 <Sect2 id="pre-supposed-other-tools">
@@ -1269,7 +1278,7 @@ file.  Typing <Command>gmake</Command> alone is generally the same as typing <Co
 <Term><Literal>install</Literal>:</Term>
 <ListItem>
 <para>
-installs the things built by <Literal>all</Literal>.  Where does it
+installs the things built by <Literal>all</Literal> (except for the documentation).  Where does it
 install them?  That is specified by
 <filename>mk/config.mk.in</filename>; you can override it in
 <filename>mk/build.mk</filename>, or by running
@@ -1279,6 +1288,13 @@ install them?  That is specified by
 </para>
 </ListItem></VarListEntry>
 <VarListEntry>
+<Term><Literal>install-docs</Literal>:</Term>
+<ListItem>
+<para>
+installs the documentation. Otherwise behaves just like <literal>install</literal>.
+</para>
+</ListItem></VarListEntry>
+<VarListEntry>
 <Term><Literal>uninstall</Literal>:</Term>
 <ListItem>
 <para>
@@ -2873,20 +2889,22 @@ I have not tried it yet.
 </Sect2>
 
 
-<Sect2><Title>Building GHC</Title>
+    <Sect2><Title>Building GHC</Title>
+      
+      <ItemizedList>
 
-<ItemizedList>
-
-<ListItem>
-<para>
-In the <filename>./configure</filename> output, ignore 
-"<Literal>
-checking whether #! works in shell scripts... 
-./configure: ./conftest: No such file or directory</Literal>", 
-and "<Literal>not updating unwritable cache ./config.cache</Literal>".
-Nobody knows why these happen, but they seem to be harmless.
-</para>
-</ListItem>
+       <ListItem>
+         <para>
+           You should give the option
+           <option>--host=i386-unknown-mingw32</option> to
+           <command>autoconf</command>, so that it doesn't try to
+           build for Cygwin (unless that's what you really
+           want). Since it's possible to get into trouble using the
+           wrong C compiler, it's wise either to avoid installing
+           Cygwin gcc, or to explicitly specify
+           <option>--with-gcc=/mingw/bin/gcc</option>.
+         </para>
+       </ListItem>
 
 <ListItem>
 <para>
@@ -2909,11 +2927,8 @@ configure: error: ./configure failed for ghc
 <ListItem>
 <para>
 You need <filename>ghc</filename> to be in your <Constant>PATH</Constant> before you run
-<Command>configure</Command>.  The default GHC InstallShield creates only
-<filename>ghc-4.08</filename>, so you may need to duplicate this file as <filename>ghc</filename>
-in the same directory, in order that <Command>configure</Command> will see it (or
-just rename <filename>ghc-4.08</filename> to <filename>ghc</filename>.
-And make sure that the directory is in your path.
+<Command>configure</Command>. The InstallShield tells you the path
+when you install it.
 </para>
 </ListItem>
 
@@ -2921,6 +2936,79 @@ And make sure that the directory is in your path.
 
 </Sect2>
 
+    <sect2>
+      <title>Building the Windows InstallShield&reg; Installer</title>
+
+      <para>
+       This section is intended for GHC developers only; no-one else
+       should need to build an InstallShield.
+      </para>
+
+      <para>
+       Having built a second-stage tree and done <command>make
+       install</command> on it, open the InstallShield
+       (<filename>.ism</filename>) file. Open the Project screen, and
+       then the Project subfolder of the Path variables folder, and
+       set <literal>SourceFiles</literal> to the top of your
+       tree. You might also need to set <literal>GHCBITS</literal> to
+       point to the tree of various external bits that are added into
+       the IS mix. You should then be able to build an InstallShield.
+      </para>
+
+      <sect3>
+       <title>Extra features of the InstallShield</title>
+
+       <para>
+         The InstallShield has some IS-specific twiddles:
+
+         <itemizedlist>
+           <listitem>
+             <para>
+               Two registry entries are set under
+               <literal>HKEY_LOCAL_MACHINE\SOFTWARE\GHC</literal>:
+               <literal>Path</literal> and
+               <literal>Version</literal>, which record respectively
+               the directory in which GHC was installed, and the
+               version number.
+             </para>
+           </listitem>
+           <listitem>
+             <para>
+               The InstallShield adds some entries to the Program
+               menu, for GHCi and for the documentation. See under
+               Setup Design and the individual components (each
+               component can add entries to the menu).
+             </para>
+           </listitem>
+         </itemizedlist>
+       </para>
+      </sect3>
+      
+      <sect3>
+       <title>External add-ins</title>
+
+       <para>
+         The external add-ins consist of Mingwin gcc and Mingwin
+         Perl. The layout of the add-ins tree is as follows:
+
+         <screen>
+extra-bin/
+  gcc.exe
+  perl.exe    (Mingwin perl)
+  perl56.dll
+gcc-lib/
+  Mingwin gcc binaries, libraries and headers
+imports/
+  com/
+    imports for HDirect's com library
+include/
+  Mingwin includes
+</screen>
+         </para>
+       </sect3>
+      
+    </sect2>
+
 </Sect1>
 
 </Article>