From 3092faa7bbee99ca6cd56425d8ea67f3dc9555b2 Mon Sep 17 00:00:00 2001 From: simonmar Date: Mon, 21 Jul 2003 15:24:43 +0000 Subject: [PATCH] [project @ 2003-07-21 15:24:42 by simonmar] Update the documentation for filenames and related options to reflect the new story. Now we talk about hierarchical modules from the outset, and hopefully the whole description is somewhat clearer than before. --- ghc/docs/users_guide/flags.sgml | 2 +- ghc/docs/users_guide/ghci.sgml | 2 +- ghc/docs/users_guide/glasgow_exts.sgml | 6 +- ghc/docs/users_guide/separate_compilation.sgml | 609 +++++++++++++++++++----- ghc/docs/users_guide/using.sgml | 265 +---------- 5 files changed, 496 insertions(+), 388 deletions(-) diff --git a/ghc/docs/users_guide/flags.sgml b/ghc/docs/users_guide/flags.sgml index 0afa9df..8dc22af 100644 --- a/ghc/docs/users_guide/flags.sgml +++ b/ghc/docs/users_guide/flags.sgml @@ -240,7 +240,7 @@ - Finding imports (<xref linkend="options-finding-imports">) + Finding imports (<xref linkend="search-path">) diff --git a/ghc/docs/users_guide/ghci.sgml b/ghc/docs/users_guide/ghci.sgml index 405f7b2..d87c1db 100644 --- a/ghc/docs/users_guide/ghci.sgml +++ b/ghc/docs/users_guide/ghci.sgml @@ -196,7 +196,7 @@ Ok, modules loaded: Main. source files, whereas in standard batch-compilation mode the option is used to specify the search path for interface files, see . + linkend="search-path">. One consequence of the way that GHCi follows dependencies to find modules to load is that every module must have a source diff --git a/ghc/docs/users_guide/glasgow_exts.sgml b/ghc/docs/users_guide/glasgow_exts.sgml index ded5567..c41e999 100644 --- a/ghc/docs/users_guide/glasgow_exts.sgml +++ b/ghc/docs/users_guide/glasgow_exts.sgml @@ -415,9 +415,9 @@ tuples to avoid unnecessary allocation during sequences of operations. import qualified Control.Monad.ST.Strict as ST - Hierarchical modules have an impact on the way that GHC - searches for files. For a description, see . + For details on how GHC searches for source and interface + files in the presence of hierarchical modules, see . GHC comes with a large collection of libraries arranged hierarchically; see the accompanying library documentation. diff --git a/ghc/docs/users_guide/separate_compilation.sgml b/ghc/docs/users_guide/separate_compilation.sgml index 42abfee..713b6a3 100644 --- a/ghc/docs/users_guide/separate_compilation.sgml +++ b/ghc/docs/users_guide/separate_compilation.sgml @@ -1,160 +1,530 @@ - Separate compilation + Filenames and separate compilation separate compilation recompilation checker make and recompilation - This section describes how GHC supports separate - compilation. + This section describes what files GHC expects to find, what + files it creates, where these files are stored, and what options + affect this behaviour. + + Note that this section is written with + hierarchical modules in mind (see ); hierarchical modules are an + extension to Haskell 98 which extends the lexical syntax of + module names to include a dot ‘.’. Non-hierarchical + modules are thus a special case in which none of the module names + contain dots. + + Pathname conventions vary from system to system. In + particular, the directory separator is + ‘/’ on Unix systems and + ‘\’ on Windows systems. In the + sections that follow, we shall consistently use + ‘/’ as the directory separator; + substitute this for the appropriate character for your + system. + + + Haskell source files + + Each Haskell source module should be placed in a file on + its own. + + The file should usually be named after the module name, by + replacing dots in the module name by directory separators. For + example, on a Unix system, the module A.B.C + should be placed in the file A/B/C.hs, + relative to some base directory. GHC's behaviour if this rule + is not followed is fully defined by the following section (). + + + + Output files - - Interface files - interface files .hi files + object files + .o files - When GHC compiles a source file A.hs - which contains a module A, say, it generates - an object A.o, and a - companion interface file - A.hi. The interface file is merely there - to help the compiler compile other modules in the same program. - Interfaces are in a binary format, so don't try to look at one; - however you can see the contents of an - interface file by using GHC with the - option (see , below). - - NOTE: In general, the name of a file containing module - M should be named M.hs - or M.lhs. The only exception to this rule is - module Main, which can be placed in any - file.filenamesfor - modules - - The interface file for A contains - information needed by the compiler when it compiles any module - B that imports A, whether - directly or indirectly. When compiling B, - GHC will read A.hi to find the details that - it needs to know about things defined in - A. - - The interface file may contain all sorts of things that - aren't explicitly exported from A by the - programmer. For example, even though a data type is exported - abstractly, A.hi will contain the full data - type definition. For small function definitions, - A.hi will contain the complete definition - of the function. For bigger functions, - A.hi will contain strictness information - about the function. And so on. GHC puts much more information - into .hi files when optimisation is turned - on with the flag (see ). Without it - puts in just the minimum; with it lobs in a - whole pile of stuff. optimsation, effect on - .hi files - - A.hi should really be thought of as a - compiler-readable version of A.o. If you - use a .hi file that wasn't generated by the - same compilation run that generates the .o - file the compiler may assume all sorts of incorrect things about - A, resulting in core dumps and other - unpleasant happenings. + When asked to compile a source file, GHC normally + generates two files: an object file, and + an interface file. + + The object file, which normally ends in a + .o suffix (or .obj if + you're on Windows), contains the compiled code for the module. + + The interface file, + which normally ends in a .hi suffix, contains + the information that GHC needs in order to compile further + modules that depend on this module. It contains things like the + types of exported functions, definitions of data types, and so + on. It is stored in a binary format, so don't try to read one; + use the option instead (see ). + + You should think of the object file and the interface file as a + pair, since the interface file is in a sense a compiler-readable + description of the contents of the object file. If the + interface file and object file get out of sync for any reason, + then the compiler may end up making assumptions about the object + file that aren't true; trouble will almost certainly follow. + For this reason, we recommend keeping object files and interface + files in the same place (GHC does this by default, but it is + possible to override the defaults as we'll explain + shortly). + + Every module has a module name + defined in its source code (module A.B.C where + ...). Unless overridden with the + -o and -ohi flags + respectively, GHC always puts the object file for module + A.B.C in + odir/A/B/C.osuf, + and the interface file in the file + hidir/A/B/C.hisuf, + where hidir, + hisuf, + odir, and + osuf, defined as follows: + + + + hidir + + is the value of the option if + one was given (see below), or + root-path otherwise. + + + + hisuf + + is the value of the option if + one was given (see below), or hi + otherwise. + + + + + odir + + is the value of the option if + one was given (see below), or + root-path otherwise. + + + + osuf + + is the value of the option if + one was given (see below), or o + otherwise (obj on Windows). + + + + + The root-path, used in the above definitions, is derived from the + location of the source file, source-filename, as follows: + + + + Rule 1 + + GHC matches source-filename against the pattern: + + root-path/A/B/C.extension + + where: + + + extension + + is the source file extension (usually + .hs or .lhs). + + + + root-path + + is what is left after A/B/C.extension + has been stripped off the end of source-file. + + + + + + + + + Rule 2 + + If source-filename does not match the pattern + above (presumably because it doesn't finish with A/B/C.hs + or A/B/C.lhs) + then root-path becomes the + whole of the directory portion of the filename. + + + + + For example, if GHC compiles the module + A.B.C in the file + src/A/B/C.hs, with no -odir or -hidir flags, + the interface file will be put in src/A/B/C.hi and the object file in + src/A/B/C.o (using Rule 1). + If the same module A.B.C was in file + src/ABC.hs, + the interface file will still be put in src/A/B/C.hi and the object file in + src/A/B/C.o (using Rule 2). + + A common use for Rule 2 is to have many modules all called Main held in + files Test1.hs Test2.hs, etc. Beware, though: when compiling + (say) Test2.hs, GHC will consult Main.hi for version information + from the last recompilation. Currently (a bug, really) GHC is not clever enough to spot that the source file has changed, + and so there is a danger that the recompilation checker will declare that no recompilation is needed when in fact it is. + Solution: delete the interface file first. + + Notice that (unless overriden with or ) the filenames + of the object and interface files are always based on the module name. The reason for this is so that + GHC can find the interface file for module A.B.C when compiling the declaration + "import A.B.C". + - - Finding interface files + + The search path + search path + interface files, finding them finding interface files In your program, you import a module Foo by saying import Foo. - GHC goes looking for an interface file, - Foo.hi. It has a builtin list of - directories (notably including .) where it - looks. + In mode or GHCi, GHC will look for a + source file for Foo and arrange to compile it + first. Without , GHC will look for the + interface file for Foo, which should have + been created by an earlier compilation of + Foo. GHC uses the same strategy in each of + these cases for finding the appropriate file. + + This strategy is as follows: GHC keeps a list of + directories called the search path. For + each of these directories, it tries appending + basename.extension + to the directory, and checks whether the file exists. The value + of basename is the module name with + dots replaced by the directory separator ('/' or '\', depending + on the system), and extension is a + source extension (hs, lhs) + if we are in mode and GHCi, or + hisuf otherwise. + + For example, suppose the search path contains directories + d1, d2, and + d3, and we are in --make + mode looking for the source file for a module + A.B.C. GHC will look in + d1/A/B/C.hs, d1/A/B/C.lhs, + d2/A/B/C.hs, and so on. + + The search path by default contains a single directory: + . (i.e. the current directory). The following + options can be used to add to or change the contents of the + search path: - - + - + This flag appends a colon-separated - list of dirs to the “import - directories” list, which initially contains a single - entry: .. - - This list is scanned before any package directories - (see ) when looking for imports, - but note that if you have a home module with the same name - as a package module then this is likely to cause trouble - in other ways, with link errors being the least nasty - thing that can go wrong... - - See also for the - significance of using relative and absolute pathnames in - the list. + list of dirs to the search path. - resets the “import directories” list - back to nothing. + resets the search path back to nothing. + + + + + This isn't the whole story: GHC also looks for modules in + pre-compiled libraries, known as packages. See the section on + packages (), for details. + + + + Redirecting the compilation output(s) + + output-directing options + redirecting compilation output + + + + file + + + GHC's compiled output normally goes into a + .hc, .o, etc., + file, depending on the last-run compilation phase. The + option + re-directs the output of that last-run phase to + file. + + Note: this “feature” can be + counterintuitive: ghc -C -o foo.o + foo.hs will put the intermediate C code in the + file foo.o, name + notwithstanding! + + This option is most often used when creating an + executable file, to set the filename of the executable. + For example: + ghc -o prog --make Main + + will compile the program starting with module + Main and put the executable in the + file prog. + + Note: on Windows, if the result is an executable + file, the extension ".exe" is added + if the specified filename does not already have an + extension. Thus + + ghc -o foo Main.hs + + will compile and link the module + Main.hs, and put the resulting + executable in foo.exe (not + foo). + + dir + + + Redirects object files to directory + dir. For example: + + +$ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` + + + The object files, Foo.o, + Bar.o, and + Bumble.o would be put into a + subdirectory named after the architecture of the executing + machine (x86, + mips, etc). + + Note that the option does + not affect where the interface files + are put; use the option for that. + In the above example, they would still be put in + parse/Foo.hi, + parse/Bar.hi, and + gurgle/Bumble.hi. + + + + + file + + + + The interface output may be directed to another file + bar2/Wurble.iface with the option + (not + recommended). + + WARNING: if you redirect the interface file + somewhere that GHC can't find it, then the recompilation + checker may get confused (at the least, you won't get any + recompilation avoidance). We recommend using a + combination of and + options instead, if + possible. + + To avoid generating an interface at all, you could + use this option to redirect the interface into the bit + bucket: -ohi /dev/null, for + example. + + + + + dir + + + + Redirects all generated interface files into + dir, instead of the + default. + + + + + suffix + suffix + suffix + + + + + EXOTICA: The + suffix will change the + .o file suffix for object files to + whatever you specify. We use this when compiling + libraries, so that objects for the profiling versions of + the libraries don't clobber the normal ones. + + Similarly, the + suffix will change the + .hi file suffix for non-system + interface files (see ). + + Finally, the option + suffix will change the + .hc file suffix for compiler-generated + intermediate C files. + + The / + game is particularly useful if you want to compile a + program both with and without profiling, in the same + directory. You can say: + + ghc ... + to get the ordinary version, and + + ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all + to get the profiled version. + + + + + + Keeping Intermediate Files + intermediate files, saving + + .hc files, saving + + .s files, saving + + + The following options are useful for keeping certain + intermediate files around, when normally GHC would throw these + away after compilation: + + + + + + + + + Keep intermediate .hc files when + doing .hs-to-.o + compilations via C (NOTE: .hc files + aren't generated when using the native code generator, you + may need to use to force them + to be produced). + + + + + + + + + + Keep intermediate .s files. + + - See also the section on packages (), which describes how to use installed - libraries. + + + + + + + Keep intermediate .raw-s files. + These are the direct output from the C compiler, before + GHC does “assembly mangling” to produce the + .s file. Again, these are not produced + when using the native code generator. + + + + + + + + + temporary files + keeping + + + Instructs the GHC driver not to delete any of its + temporary files, which it normally keeps in + /tmp (or possibly elsewhere; see ). Running GHC with + will show you what temporary files + were generated along the way. + + + - - Finding interfaces for hierarchical modules - - GHC supports a hierarchical module namespace as an - extension to Haskell 98 (see ). - - A module name in general consists of a sequence of - components separated by dots - (‘.’). When looking for - interface files for a hierarchical module, the compiler turns - the dots into path separators, so for example a module - A.B.C becomes A/B/C (or - A\B\C under Windows). Then each component of - the import directories list is tested in turn; so for example if - the list contains directories - D1 to - Dn, then the compiler - will look for the interface in - D1/A/B/C.hi first, - then D2/A/B/C.hi and - so on. - - Note that it's perfectly reasonable to have a module which - is both a leaf and a branch of the tree. For example, if we - have modules A.B and - A.B.C, then A.B's - interface file will be in A/B.hi and - A.B.C's interface file will be in - A/B/C.hi. - - For GHCi and , the search strategy - for source files is exactly the same, just replace the - .hi suffix in the above description with - .hs or .lhs. + + Redirecting temporary files + + + temporary files + redirecting + + + + + + + + If you have trouble because of running out of space + in /tmp (or wherever your + installation thinks temporary files should go), you may + use the -tmpdir + <dir> option option to specify + an alternate directory. For example, says to put temporary files in the current + working directory. + + Alternatively, use your TMPDIR + environment variable.TMPDIR + environment variable Set it to the + name of the directory where temporary files should be put. + GCC and other programs will honour the + TMPDIR variable as well. + + Even better idea: Set the + DEFAULT_TMPDIR make variable when + building GHC, and never worry about + TMPDIR again. (see the build + documentation). + + + @@ -216,7 +586,6 @@ - diff --git a/ghc/docs/users_guide/using.sgml b/ghc/docs/users_guide/using.sgml index e1222c0..bf8f5b7 100644 --- a/ghc/docs/users_guide/using.sgml +++ b/ghc/docs/users_guide/using.sgml @@ -448,7 +448,7 @@ ghc ––make Main.hs The source files for the program don't all need to be in the same directory; the option can be used to add directories to the search path (see ). + linkend="search-path">). @@ -552,267 +552,7 @@ ghc ––make Main.hs standard output. - - Re-directing the compilation output(s) - - output-directing options - redirecting compilation output - - - - - - - - GHC's compiled output normally goes into a - .hc, .o, etc., - file, depending on the last-run compilation phase. The - option -o - option re-directs the output of that - last-run phase to file foo. - - Note: this “feature” can be - counterintuitive: ghc -C -o foo.o foo.hs - will put the intermediate C code in the file - foo.o, name notwithstanding! - - Note: on Windows, if the result is an executable file, the - extension ".exe" is added if the specified filename - does not already have an extension. Thus - - ghc -o foo Main.hs - - will compile and link the module Main.hs, and put the - resulting executable in foo.exe (not foo). - - - - - - - - - The option isn't of much use if - you have several input files… - Non-interface output files are normally put in the same - directory as their corresponding input file came from. You - may specify that they be put in another directory using the - -odir - <dir> option (the “Oh, - dear” option). For example: - - -% ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` - - - The output files, Foo.o, - Bar.o, and - Bumble.o would be put into a - subdirectory named after the architecture of the executing - machine (sun4, - mips, etc). The directory must already - exist; it won't be created. - - Note that the option does - not affect where the interface files - are put. In the above example, they would still be put in - parse/Foo.hi, - parse/Bar.hi, and - gurgle/Bumble.hi. - - - - - file - - - - The interface output may be directed to another file - bar2/Wurble.iface with the option - (not - recommended). - - WARNING: if you redirect the interface file somewhere - that GHC can't find it, then the recompilation checker may - get confused (at the least, you won't get any recompilation - avoidance). We recommend using a combination of - and options - instead, if possible. - - To avoid generating an interface at all, you could use - this option to redirect the interface into the bit bucket: - -ohi /dev/null, for example. - - - - - directory - - - - Redirects all generated interface files into - directory, instead of the default - which is to place the interface file in the same directory - as the source file. - - - - - suffix - suffix - suffix - - - - - EXOTICA: The - suffix will change the - .o file suffix for object files to - whatever you specify. We use this when compiling libraries, - so that objects for the profiling versions of the libraries - don't clobber the normal ones. - - Similarly, the - suffix will change the - .hi file suffix for non-system interface - files (see ). - - Finally, the option - suffix will change the - .hc file suffix for compiler-generated - intermediate C files. - - The / - game is particularly useful if you want to compile a program both with and without - profiling, in the same directory. You can say: - - ghc ... - - to get the ordinary version, and - - ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all - - to get the profiled version. - - - - - - Keeping Intermediate Files - intermediate files, saving - - .hc files, saving - - .s files, saving - - - - The following options are useful for keeping certain - intermediate files around, when normally GHC would throw these - away after compilation: - - - - - - - - - Keep intermediate .hc files when - doing .hs-to-.o - compilations via C (NOTE: .hc files - aren't generated when using the native code generator, you - may need to use to force them - to be produced). - - - - - - - - - - Keep intermediate .s files. - - - - - - - - - - Keep intermediate .raw-s files. - These are the direct output from the C compiler, before - GHC does “assembly mangling” to produce the - .s file. Again, these are not produced - when using the native code generator. - - - - - - - - - - temporary files - keeping - - - Instructs the GHC driver not to delete any of its - temporary files, which it normally keeps in - /tmp (or possibly elsewhere; see ). Running GHC with - will show you what temporary files - were generated along the way. - - - - - - - Redirecting temporary files - - - temporary files - redirecting - - - - - - - - If you have trouble because of running out of space - in /tmp (or wherever your - installation thinks temporary files should go), you may - use the -tmpdir - <dir> option option to specify - an alternate directory. For example, says to put temporary files in the current - working directory. - - Alternatively, use your TMPDIR - environment variable.TMPDIR - environment variable Set it to the - name of the directory where temporary files should be put. - GCC and other programs will honour the - TMPDIR variable as well. - - Even better idea: Set the - DEFAULT_TMPDIR make variable when - building GHC, and never worry about - TMPDIR again. (see the build - documentation). - - - - - - + &separate; Warnings and sanity-checking @@ -1157,7 +897,6 @@ f "2" = 2 - &separate; &packages; -- 1.7.10.4