X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Futils.lit;fp=ghc%2Fdocs%2Fusers_guide%2Futils.lit;h=ff15c0088f447dfa26f03da4b98c0cffbcd59603;hb=60c952e33a3dc3731c6744c88237d04788057971;hp=94de71b1f4002e892347ebeae3f44e4fec6b32bb;hpb=f7a05b5365038440db3ec7e648e12b15c2b54334;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/utils.lit b/ghc/docs/users_guide/utils.lit index 94de71b..ff15c00 100644 --- a/ghc/docs/users_guide/utils.lit +++ b/ghc/docs/users_guide/utils.lit @@ -17,71 +17,109 @@ with the Great Haskell Programming Task. %* * %************************************************************************ -It is reasonably straightforward to set up a \tr{Makefile} to use with -GHC, assuming you name your source files the same as your modules. -Thus: +You run @mkdependHS@ like this: \begin{verbatim} -HC = ghc -HCFLAGS = -recomp -cpp -hi-diffs $(EXTRA_HC_OPTS) - -SRCS = Main.lhs Foo.lhs Bar.lhs -OBJS = Main.o Foo.o Bar.o - -.SUFFIXES : .o .hi .lhs -.o.hi: - @: -.lhs.o: - $(RM) $@ - $(HC) -c $< $(HCFLAGS) - -cool_pgm : $(OBJS) - $(RM) $@ - $(HC) -o $@ $(HCFLAGS) $(OBJS) + mkdependHS [mkdependHS options] [-- GHC options --] srcfile1 [srcfile2 ...] \end{verbatim} - -Note the cheesy \tr{.o.hi} rule: It records the dependency of the -interface (\tr{.hi}) file on the source. The rule says a \tr{.hi} -file can be made from a \tr{.o} file by doing... nothing. Which is -true. - -(Sophisticated \tr{make} variants may achieve some of the above more -elegantly. What we've shown should work with any \tr{make}.) - -The only thing lacking in the above \tr{Makefile} is interface-file -dependencies. If \tr{Foo.lhs} imports module \tr{Bar} and the -\tr{Bar} interface changes, then \tr{Foo.lhs} needs to be recompiled. - -Putting dependencies of the form \tr{Foo.o : Bar.hi} into your -\tr{Makefile} by hand is rather error-prone. Don't worry---never -fear, \tr{mkdependHS} is here! (and is distributed as part of GHC) -Add the following to your \tr{Makefile}: +or \begin{verbatim} -depend : - mkdependHS -- $(HCFLAGS) -- $(SRCS) + ghc -M [mkdependHS options(prefix with -optdep)] [ GHC options ] srcfile1 [srcfile2 ...] \end{verbatim} - -Now, before you start compiling, and any time you change the -\tr{imports} in your program, do \tr{make depend} before you do -\tr{make cool_pgm}. \tr{mkdependHS} will append the needed -dependencies to your \tr{Makefile}. - -Please note the use of the recompilation checker (the \tr{-recomp} -\index{-recomp option} flag). Without it, your dependencies will be -{\em inadequate} to cope with the Haskell~1.3 module system! See -\sectionref{recomp} for more details about the recompilation checker! - -A few caveats about this simple scheme: (a)~You may need to compile -some modules explicitly to create their interfaces in the first place -(e.g., \tr{make Bar.o} to create \tr{Bar.hi}). (b)~You may have to -type \tr{make} more than once for the dependencies to have full -effect. However, a \tr{make} run that does nothing {\em does} mean -``everything's up-to-date.'' (c) This scheme will work with -mutually-recursive modules but, again, it may take multiple -iterations to ``settle.'' - To see \tr{mkdependHS}'s command-line flags, give it a duff flag, e.g., \tr{mkdependHS -help}. +In general, if module @A@ contains the line +\begin{verbatim} + import B ...blah... +\end{verbatim} +then @mkdependHS@ will generate a dependency line of the form: +\begin{verbatim} + A.o : B.hi +\end{verbatim} +If module @A@ contains the line +\begin{verbatim} + import {-# SOURCE #-} B ...blah... +\end{verbatim} +then @mkdependHS@ will generate a dependency line of the form: +\begin{verbatim} + A.o : B.hi-boot +\end{verbatim} +(See \Sectionref{hi-boot} for details of @.hi-boot@ files.) +If @A@ imports multiple modules, then there will be multiple lines with @A.o@ as the +target. + +By default, @mkdependHS@ generates all the dependencies, and then +concatenates them onto the end of +@makefile@ (or @Makefile@ if @makefile@ doesn't exist) bracketed by +the lines "@# DO NOT DELETE: Beginning of Haskell dependencies@" and +"@# DO NOT DELETE: End of Haskell dependencies@". If these lines +already exist in the @makefile@, @mkdependHS@ deletes the old +dependencies first. + +@mkdependHS@ takes GHC options between @--@ brackets. +It understands the following ones. Any options between @--@ brackets +that it doesn't understand are simply ignored; this way you can feed your +Makefile's standard GHC options to @mkdependHS@ un-filtered. +\begin{description} + +\item[@-D@] A cpp @#define@; usual meaning. + +\item[@-i@] Add @@ (colon-separated) to list of directories + to search for "import"ed modules. + +\item[@-I@] Add @@ to list of directories to search for + .h files (i.e., usual meaning). + +\item[@-syslib @] This program uses this GHC system library; take + appropriate action (e.g., recognise when they are + "import"ing a module from that library). + +\item[@-ignore @] +\end{description} + +Here are the @mkdependHS@-specific options (not between @--@'s): +\begin{description} +\item[@-v@] Be verbose. +\item[@-v -v@] Be very verbose. +\item[@-f blah@] + Use @blah@ as the makefile, rather than @makefile@ + or @Makefile@. If @blah@ doesn't exist, @mkdependHS@ creates it. + We often use @-f .depend@ to put the dependencies in @.depend@ and + then @include@ the file @.depend@ into @Makefilpe@. + +\item[@-o @] + Use @.@ as the "target file" suffix ( default: @o@). + Multiple @-o@ flags are permitted (GHC2.05 onwards). Thus "@-o hc -o o@" + will generate dependencies for @.hc@ and @.o@ files. + +\item[@-s @] + Make extra dependencies that declare that files with + suffix @._@ depend on interface files with suffix @._hi@, or + (for @{-# SOURCE #-}@ imports) on @.hi-boot@. + Multiple @-s@ flags are permitted. + For example, "@-o hc -s a -s b@" will + make dependencies for @.hc@ on @.hi@, @.a_hc@ on @.a_hi@, and @.b_hc@ on @.b_hi@. + (Useful in conjunction with NoFib "ways".) + +\item[@--exclude-module=@] + Regard @@ as "stable"; i.e., exclude it from having + dependencies on it. + +\item[@-x@] same as @--exclude-module@ + +\item[@--exclude-directory=@] + Regard the colon-separated list of directories @@ as containing stable, + don't generate any dependencies on modules therein. + +\item[@-Xdirs@] same as @--exclude-directory@. + +\item[@--include-module=@] + Regard @@ as not "stable"; i.e., generate dependencies + on it (if any). This option is normally used in conjunction + with the @--exclude-directory@ option. +\end{description} + + %************************************************************************ %* * \subsection[hstags]{Emacs `TAGS' for Haskell: \tr{hstags}}