Better document the driver pipeline.

compiler/main/DriverPhases.hs

@@ -85,9 +85,9 @@ data Phase
         | Cobjc
         | Cobjcpp
         | HCc           -- Haskellised C (as opposed to vanilla C) compilation
-        | SplitMangle   -- after mangler if splitting
-        | SplitAs
-        | As
+        | Splitter      -- Assembly file splitter (part of '-split-objs')
+        | SplitAs       -- Assembler for split assembly files (part of '-split-objs')
+        | As            -- Assembler for regular assembly files
         | LlvmOpt       -- Run LLVM opt tool over llvm assembly
         | LlvmLlc       -- LLVM bitcode to native assembly
         | LlvmMangle    -- Fix up TNTC by processing assembly produced by LLVM
@@ -113,26 +113,26 @@ isStopLn _      = False
 eqPhase :: Phase -> Phase -> Bool
 -- Equality of constructors, ignoring the HscSource field
 -- NB: the HscSource field can be 'bot'; see anyHsc above
-eqPhase (Unlit _)   (Unlit _)   = True
-eqPhase (Cpp   _)   (Cpp   _)   = True
-eqPhase (HsPp  _)   (HsPp  _)   = True
-eqPhase (Hsc   _)   (Hsc   _)   = True
-eqPhase Ccpp        Ccpp        = True
-eqPhase Cc          Cc          = True
-eqPhase Cobjc       Cobjc       = True
-eqPhase Cobjcpp     Cobjcpp     = True
-eqPhase HCc         HCc         = True
-eqPhase SplitMangle SplitMangle = True
-eqPhase SplitAs     SplitAs     = True
-eqPhase As          As          = True
-eqPhase LlvmOpt	    LlvmOpt 	= True
-eqPhase LlvmLlc	    LlvmLlc 	= True
-eqPhase LlvmMangle  LlvmMangle 	= True
-eqPhase CmmCpp      CmmCpp      = True
-eqPhase Cmm         Cmm         = True
-eqPhase MergeStub   MergeStub   = True
-eqPhase StopLn      StopLn      = True
-eqPhase _           _           = False
+eqPhase (Unlit _)   (Unlit _)  = True
+eqPhase (Cpp   _)   (Cpp   _)  = True
+eqPhase (HsPp  _)   (HsPp  _)  = True
+eqPhase (Hsc   _)   (Hsc   _)  = True
+eqPhase Ccpp        Ccpp       = True
+eqPhase Cc          Cc         = True
+eqPhase Cobjc       Cobjc      = True
+eqPhase Cobjcpp     Cobjcpp    = True
+eqPhase HCc         HCc        = True
+eqPhase Splitter    Splitter   = True
+eqPhase SplitAs     SplitAs    = True
+eqPhase As          As         = True
+eqPhase LlvmOpt	    LlvmOpt    = True
+eqPhase LlvmLlc	    LlvmLlc    = True
+eqPhase LlvmMangle  LlvmMangle = True
+eqPhase CmmCpp      CmmCpp     = True
+eqPhase Cmm         Cmm        = True
+eqPhase MergeStub   MergeStub  = True
+eqPhase StopLn      StopLn     = True
+eqPhase _           _          = False
 
 -- Partial ordering on phases: we want to know which phases will occur before
 -- which others.  This is used for sanity checking, to ensure that the
@@ -145,25 +145,25 @@ x      `happensBefore` y = after_x `eqPhase` y || after_x `happensBefore` y
 
 nextPhase :: Phase -> Phase
 -- A conservative approximation to the next phase, used in happensBefore
-nextPhase (Unlit sf)    = Cpp  sf
-nextPhase (Cpp   sf)    = HsPp sf
-nextPhase (HsPp  sf)    = Hsc  sf
-nextPhase (Hsc   _)     = HCc
-nextPhase SplitMangle   = As
-nextPhase As            = SplitAs
-nextPhase LlvmOpt       = LlvmLlc
-nextPhase LlvmLlc       = LlvmMangle
-nextPhase LlvmMangle    = As
-nextPhase SplitAs       = MergeStub
-nextPhase Ccpp          = As
-nextPhase Cc            = As
-nextPhase Cobjc         = As
-nextPhase Cobjcpp       = As
-nextPhase CmmCpp        = Cmm
-nextPhase Cmm           = HCc
-nextPhase HCc           = As
-nextPhase MergeStub     = StopLn
-nextPhase StopLn        = panic "nextPhase: nothing after StopLn"
+nextPhase (Unlit sf) = Cpp  sf
+nextPhase (Cpp   sf) = HsPp sf
+nextPhase (HsPp  sf) = Hsc  sf
+nextPhase (Hsc   _)  = HCc
+nextPhase Splitter   = SplitAs
+nextPhase LlvmOpt    = LlvmLlc
+nextPhase LlvmLlc    = LlvmMangle
+nextPhase LlvmMangle = As
+nextPhase SplitAs    = MergeStub
+nextPhase As         = MergeStub
+nextPhase Ccpp       = As
+nextPhase Cc         = As
+nextPhase Cobjc      = As
+nextPhase Cobjcpp    = As
+nextPhase CmmCpp     = Cmm
+nextPhase Cmm        = HCc
+nextPhase HCc        = As
+nextPhase MergeStub  = StopLn
+nextPhase StopLn     = panic "nextPhase: nothing after StopLn"
 
 -- the first compilation phase for a given file is determined
 -- by its suffix.
@@ -184,7 +184,7 @@ startPhase "M"        = Cobjcpp
 startPhase "mm"       = Cobjcpp
 startPhase "cc"       = Ccpp
 startPhase "cxx"      = Ccpp
-startPhase "split_s"  = SplitMangle
+startPhase "split_s"  = Splitter
 startPhase "s"        = As
 startPhase "S"        = As
 startPhase "ll"       = LlvmOpt
@@ -213,12 +213,12 @@ phaseInputExt Ccpp                = "cpp"
 phaseInputExt Cobjc               = "m"
 phaseInputExt Cobjcpp             = "mm"
 phaseInputExt Cc                  = "c"
-phaseInputExt SplitMangle         = "split_s"   -- not really generated
+phaseInputExt Splitter            = "split_s"
 phaseInputExt As                  = "s"
 phaseInputExt LlvmOpt             = "ll"
 phaseInputExt LlvmLlc             = "bc"
 phaseInputExt LlvmMangle          = "lm_s"
-phaseInputExt SplitAs             = "split_s"   -- not really generated
+phaseInputExt SplitAs             = "split_s"
 phaseInputExt CmmCpp              = "cmm"
 phaseInputExt Cmm                 = "cmmcpp"
 phaseInputExt MergeStub           = "o"

compiler/main/DriverPipeline.hs

@@ -148,7 +148,7 @@ compile' (nothingCompiler, interactiveCompiler, batchCompiler)
    -- Figure out what lang we're generating
    let hsc_lang = hscTarget dflags
    -- ... and what the next phase should be
-   let next_phase = hscNextPhase dflags src_flavour hsc_lang
+   let next_phase = hscPostBackendPhase dflags src_flavour hsc_lang
    -- ... and what file to generate the output into
    output_fn <- getOutputFilename next_phase
                         Temporary basename dflags next_phase (Just location)
@@ -921,7 +921,7 @@ runPhase (Hsc src_flavour) input_fn dflags0
                                   else return SourceModified
 
   -- get the DynFlags
-        let next_phase = hscNextPhase dflags src_flavour hsc_lang
+        let next_phase = hscPostBackendPhase dflags src_flavour hsc_lang
         output_fn  <- phaseOutputFilename next_phase
 
         let dflags' = dflags { hscTarget = hsc_lang,
@@ -987,7 +987,7 @@ runPhase Cmm input_fn dflags
         PipeEnv{src_basename} <- getPipeEnv
         let hsc_lang = hscTarget dflags
 
-        let next_phase = hscNextPhase dflags HsSrcFile hsc_lang
+        let next_phase = hscPostBackendPhase dflags HsSrcFile hsc_lang
 
         output_fn <- phaseOutputFilename next_phase
 
@@ -1141,7 +1141,7 @@ runPhase cc_phase input_fn dflags
 -----------------------------------------------------------------------------
 -- Splitting phase
 
-runPhase SplitMangle input_fn dflags
+runPhase Splitter input_fn dflags
   = do  -- tmp_pfx is the prefix used for the split .s files
 
         split_s_prefix <- io $ SysTools.newTempName dflags "split"
@@ -1164,12 +1164,13 @@ runPhase SplitMangle input_fn dflags
         io $ addFilesToClean dflags' [ split_s_prefix ++ "__" ++ show n ++ ".s"
                                      | n <- [1..n_files]]
 
-        return (SplitAs, "**splitmangle**")
-          -- we don't use the filename
+        return (SplitAs,
+                "**splitter**") -- we don't use the filename in SplitAs
 
 -----------------------------------------------------------------------------
--- As phase
+-- As, SpitAs phase : Assembler
 
+-- This is for calling the assembler on a regular assembly file (not split).
 runPhase As input_fn dflags
   = do
         -- LLVM from version 3.0 onwards doesn't support the OS X system
@@ -1220,6 +1221,8 @@ runPhase As input_fn dflags
         return (next_phase, output_fn)
 
 
+-- This is for calling the assembler on a split assembly file (so a collection
+-- of assembly files)
 runPhase SplitAs _input_fn dflags
   = do
         -- we'll handle the stub_o file in this phase, so don't MergeStub,
@@ -1360,9 +1363,8 @@ runPhase LlvmLlc input_fn dflags
                    then ["-O1", "-O2", "-O2"]
                    else ["-O1", "-O2", "-O3"]
         -- On ARMv7 using LLVM, LLVM fails to allocate floating point registers
-        -- while compiling GHC source code. It's probably due to fact
-        -- that it does not enable VFP by default. Let's do this manually
-        -- here
+        -- while compiling GHC source code. It's probably due to fact that it
+        -- does not enable VFP by default. Let's do this manually here
         fpOpts = case platformArch (targetPlatform dflags) of 
                    ArchARM ARMv7 ext -> if (elem VFPv3 ext)
                                       then ["-mattr=+v7,+vfp3"]
@@ -2100,13 +2102,14 @@ joinObjectFiles dflags o_files output_fn = do
 -- -----------------------------------------------------------------------------
 -- Misc.
 
-hscNextPhase :: DynFlags -> HscSource -> HscTarget -> Phase
-hscNextPhase _ HsBootFile _        =  StopLn
-hscNextPhase dflags _ hsc_lang =
+-- | What phase to run after one of the backend code generators has run
+hscPostBackendPhase :: DynFlags -> HscSource -> HscTarget -> Phase
+hscPostBackendPhase _ HsBootFile _    =  StopLn
+hscPostBackendPhase dflags _ hsc_lang =
   case hsc_lang of
         HscC -> HCc
-        HscAsm | dopt Opt_SplitObjs dflags -> SplitMangle
-               | otherwise -> As
+        HscAsm | dopt Opt_SplitObjs dflags -> Splitter
+               | otherwise                 -> As
         HscLlvm        -> LlvmOpt
         HscNothing     -> StopLn
         HscInterpreted -> StopLn