instructions for building the library docs
authorSimon Marlow <marlowsd@gmail.com>
Mon, 5 Jul 2010 15:48:10 +0000 (15:48 +0000)
committerSimon Marlow <marlowsd@gmail.com>
Mon, 5 Jul 2010 15:48:10 +0000 (15:48 +0000)
report/Makefile
report/README

index ca88135..7d1cc95 100644 (file)
@@ -261,13 +261,7 @@ haskell-librariesx.dvi : sigplan_haskell-libraries.dvi
 # changing anything.
 
 # To generate the library docs, we need to run Haddock against the
-# modules of the haskell2010 package.  The package is here:
-#
-#   http://darcs.haskell.org/packages/haskell2010
-#
-# I generated the documentation using a GHC build, but you could
-# probably do it using just the package sources, as long as you have
-# GHC and all the package documentation installed.
+# modules of the haskell2010 package.
 #
 # Basically the plan is to run Haddock in the same way as for
 # generating the HTML documentation, except that we
@@ -276,30 +270,37 @@ haskell-librariesx.dvi : sigplan_haskell-libraries.dvi
 #    * Add --latex-style=NONE to prevent Haddock dumping its haddock.sty
 #    * Add --odir=$(HADDOCK_DIR)
 #
-# So to get started, in a GHC build, you could run 
+# Hopefully you should be able to modify the variables below to set
+# the location of your GHC build and the versions of the relevant
+# packages, and then say 'make haddock' to build the docs.  Then you
+# can use 'darcs whatsnew' to see the differences between what you
+# just generated and what is checked into the repository.
+
+GHC_BUILD = /home/simonmar/builds/testing
+
+# Change these to match the current versions.  Use
 #
-#    $ cd libraries/haskell2010
-#    $ make html stage=0 FAST=YES
+#    $(GHC_BUILD)/inplace/bin/ghc-pkg list 
 #
-# And grab the Haddock command line that the build system emits.
+# to find out what they should be.
 #
-# The following rules will probably need a lot of manual modification,
-# sorry about that.
+HASKELL2010_PKG = haskell2010-1.0.0.0
+BASE_PKG        = base-4.3.0.0
+ARRAY_PKG       = array-0.3.0.0
 
-# Set this to Haddock (version 2.8 or later with the LaTeX back-end)
-HADDOCK = /home/simonmar/builds/testing/inplace/bin/haddock
+GHC_PRIM_PKG = ghc-prim
 
-# Set this to the location of the libraries in a GHC build
-LIBDIR = /home/simonmar/builds/testing/libraries
+HADDOCK = $(GHC_BUILD)/inplace/bin/haddock
+LIBDIR =  $(GHC_BUILD)libraries
 
 haddock :
        $(HADDOCK) --odir=$(HADDOCK_ODIR) --no-tmp-comp-dir \
           --latex --latex-style=NONE \
           --title="haskell2010-1.0.0.0: Compatibility with Haskell 2010" \
-          --read-interface=../ghc-prim,$(LIBDIR)/ghc-prim/dist-install/doc/html/ghc-prim/ghc-prim.haddock \
-          --read-interface=../array-0.3.0.0,$(LIBDIR)/array/dist-install/doc/html/array/array.haddock \
-          --read-interface=../base-4.3.0.0,$(LIBDIR)/base/dist-install/doc/html/base/base.haddock \
-          --optghc=-package-name --optghc=haskell2010-1.0.0.0 --optghc=-hide-all-packages --optghc=-i --optghc=-i$(LIBDIR)/haskell2010/. --optghc=-i$(LIBDIR)/haskell2010/dist-install/build --optghc=-i$(LIBDIR)/haskell2010/dist-install/build/autogen --optghc=-i$(LIBDIR)/haskell2010/dist-install/build --optghc=-i$(LIBDIR)/haskell2010/dist-install/build/autogen --optghc=-i$(LIBDIR)/haskell2010/. --optghc=-optP-include --optghc=-optP$(LIBDIR)/haskell2010/dist-install/build/autogen/cabal_macros.h --optghc=-package --optghc=array-0.3.0.0 --optghc=-package --optghc=base-4.3.0.0 --optghc=-package-name --optghc=haskell2010 --optghc=-XPackageImports --optghc=-XCPP --optghc=-no-user-package-conf --optghc=-rtsopts --optghc=-O --optghc=-fasm --optghc=-dcore-lint --optghc=-fno-warn-deprecated-flags --optghc=-odir --optghc=libraries/haskell2010/dist-install/build --optghc=-hidir --optghc=$(LIBDIR)/haskell2010/dist-install/build --optghc=-stubdir --optghc=$(LIBDIR)/haskell2010/dist-install/build --optghc=-hisuf --optghc=hi --optghc=-osuf --optghc=o --optghc=-hcsuf --optghc=hc \
+          --read-interface=../$(GHC_PRIM_PKG),$(LIBDIR)/ghc-prim/dist-install/doc/html/ghc-prim/ghc-prim.haddock \
+          --read-interface=../$(ARRAY_PKG),$(LIBDIR)/array/dist-install/doc/html/array/array.haddock \
+          --read-interface=../$(BASE_PKG),$(LIBDIR)/base/dist-install/doc/html/base/base.haddock \
+          --optghc=-package-name --optghc=$(HASKELL2010_PKG) --optghc=-hide-all-packages --optghc=-i --optghc=-i$(LIBDIR)/haskell2010/. --optghc=-i$(LIBDIR)/haskell2010/dist-install/build --optghc=-i$(LIBDIR)/haskell2010/dist-install/build/autogen --optghc=-i$(LIBDIR)/haskell2010/dist-install/build --optghc=-i$(LIBDIR)/haskell2010/dist-install/build/autogen --optghc=-i$(LIBDIR)/haskell2010/. --optghc=-optP-include --optghc=-optP$(LIBDIR)/haskell2010/dist-install/build/autogen/cabal_macros.h --optghc=-package --optghc=$(ARRAY_PKG) --optghc=-package --optghc=$(BASE_PKG) --optghc=-XPackageImports --optghc=-XCPP --optghc=-no-user-package-conf  --optghc=-fno-warn-deprecated-flags --optghc=-odir --optghc=libraries/haskell2010/dist-install/build --optghc=-hidir --optghc=$(LIBDIR)/haskell2010/dist-install/build --optghc=-stubdir --optghc=$(LIBDIR)/haskell2010/dist-install/build --optghc=-hisuf --optghc=hi --optghc=-osuf --optghc=o --optghc=-hcsuf --optghc=hc \
           $(patsubst %, $(LIBDIR)/haskell2010/%, $(addsuffix .hs, $(subst .,/,$(LIB_MODULES))))
        for i in $(LIB_TEX); do \
           sed 's/instance\(\\ [^\]*\)*\\ ReadP\($$\|\\\\\)//g' $$i | \
index e2c78e2..ad89f99 100644 (file)
@@ -19,6 +19,48 @@ make targets
    haddock   re-generate the library documentation using Haddock
              (see Makefile for instructions)
 
+
+Re-generating the library documentation using Haddock
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The documentation for library modules is generated automatically by
+Haddock (http://www.haskell.org/haddock) from the library source code.
+You don't need Haddock to build the report though - the generated .tex
+files have been checked into the repository.
+
+The library specifications generated for the Haskell 2010 report were
+generated using libraries from these repositories:
+
+  base        (http://darcs.haskell.org/packages/base)
+  ghc-prim    (http://darcs.haskell.org/packages/ghc-prim)
+  integer-gmp (http://darcs.haskell.org/packages/integer-gmp)
+  array       (http://darcs.haskell.org/packages/array)
+  haskell2010 (http://darcs.haskell.org/packages/haskell2010)
+
+each of the repositories was tagged with
+
+  "Haskell 2010 report generated"
+
+at the point the libray module documentation was generated, so you
+should be able to reproduce exactly what is checked into the
+repository.
+
+Right now, the only practical way to re-generate the library module
+documentation is to have a GHC build.  Fortunately building GHC isn't
+that hard these days: go to 
+
+  http://hackage.haskell.org/trac/ghc/wiki/Building
+
+and follow the instructions.  Make sure you don't disable
+documentation building, i.e. don't set HADDOCK_DOCS=NO in your
+mk/build.mk configuration file.
+
+When you have built GHC
+
+To update the library documentation see the Makefile, in the section
+"Haddock-generated library docs".
+
+
 Roadmap
 ~~~~~~~