Commit 8f19c65c authored by Ben Gamari's avatar Ben Gamari Committed by Ben Gamari
Browse files

Rip out mkUserGuidePart

Reviewers: austin, hvr

Subscribers: rwbarton, thomie, erikd

Differential Revision: https://phabricator.haskell.org/D3886
parent 76e59a27
......@@ -232,14 +232,8 @@ import Foreign (Ptr) -- needed for 2nd stage
-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--
-- If you modify anything in this file please make sure that your changes are
-- described in the User's Guide. Usually at least two sections need to be
-- updated:
--
-- * Flag Reference section generated from the modules in
-- utils/mkUserGuidePart/Options
--
-- * Flag description in docs/users_guide/using.rst provides a detailed
-- explanation of flags' usage.
-- described in the User's Guide. Please update the flag description in the
-- users guide (docs/users_guide) whenever you add or change a flag.
-- Note [Supporting CLI completion]
-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......@@ -4132,8 +4126,7 @@ impliedXFlags
-- If you change the list of flags enabled for particular optimisation levels
-- please remember to update the User's Guide. The relevant files are:
--
-- * utils/mkUserGuidePart/Options/
-- * docs/users_guide/using.rst
-- docs/users_guide/using-optimisation.rst
--
-- The first contains the Flag Reference section, which briefly lists all
-- available flags. The second contains a detailed description of the
......@@ -4208,8 +4201,7 @@ removes an assertion failure. -}
-- If you change the list of warning enabled by default
-- please remember to update the User's Guide. The relevant file is:
--
-- * utils/mkUserGuidePart/
-- * docs/users_guide/using-warnings.rst
-- docs/users_guide/using-warnings.rst
-- | Warning groups.
--
......
......@@ -1249,7 +1249,7 @@ checkMake380() {
checkMake380 make
checkMake380 gmake
AC_CONFIG_FILES([mk/config.mk mk/install.mk mk/project.mk compiler/ghc.cabal ghc/ghc-bin.cabal utils/runghc/runghc.cabal libraries/ghc-boot/ghc-boot.cabal libraries/ghc-boot-th/ghc-boot-th.cabal libraries/ghci/ghci.cabal settings docs/users_guide/ghc_config.py docs/index.html libraries/prologue.txt utils/mkUserGuidePart/mkUserGuidePart.cabal distrib/configure.ac])
AC_CONFIG_FILES([mk/config.mk mk/install.mk mk/project.mk compiler/ghc.cabal ghc/ghc-bin.cabal utils/runghc/runghc.cabal libraries/ghc-boot/ghc-boot.cabal libraries/ghc-boot-th/ghc-boot-th.cabal libraries/ghci/ghci.cabal settings docs/users_guide/ghc_config.py docs/index.html libraries/prologue.txt distrib/configure.ac])
AC_OUTPUT
[
if test "$print_make_warning" = "true"; then
......
......@@ -2,6 +2,3 @@ dir = docs/users_guide
TOP = ../..
include $(TOP)/mk/sub-makefile.mk
# This makes 'make fast' work: assume that mkUserGuidePart exists
FAST_MAKE_OPTS += utils/mkUserGuidePart_dist_NOT_NEEDED=YES
......@@ -419,17 +419,6 @@ user-substitutable tokens. In this document we use the convention, ``⟨subst⟩
less-than/greater-than signs).
.. _references:
GHC command-line options reference
----------------------------------
The tabular nature of GHC flags reference (:file:`flags.rst`) makes it very
difficult to maintain as ReST. For this reason it is generated by
:file:`utils/mkUserGuidePart`. Any command-line options added to GHC should
be added to the appropriate file in :file:`utils/mkUserGuidePart/Options`.
ReST reference materials
------------------------
......
......@@ -203,16 +203,6 @@ $(error Can not build haddock docs when CrossCompiling or Stage1Only. \
endif
endif
ifneq "$(BUILD_SPHINX_HTML) $(BUILD_SPHINX_PDF)" "NO NO"
# The User's Guide requires mkUserGuidePart, which uses the GHC API.
ifneq "$(CrossCompiling) $(Stage1Only)" "NO NO"
$(error Can not build User's Guide when CrossCompiling or Stage1Only. \
Set BUILD_SPHINX_HTML=NO, BUILD_SPHINX_PDF=NO in your \
mk/build.mk file. \
See Note [No stage2 packages when CrossCompiling or Stage1Only])
endif
endif
endif # CLEANING
# -----------------------------------------------------------------------------
......@@ -568,7 +558,6 @@ utils/haddock/dist/package-data.mk: compiler/stage2/package-data.mk
utils/ghctags/dist-install/package-data.mk: compiler/stage2/package-data.mk
utils/check-api-annotations/dist-install/package-data.mk: compiler/stage2/package-data.mk
utils/check-ppr/dist-install/package-data.mk: compiler/stage2/package-data.mk
utils/mkUserGuidePart/dist/package-data.mk: compiler/stage2/package-data.mk
# add the final package.conf dependency: ghc-prim depends on RTS
libraries/ghc-prim/dist-install/package-data.mk : rts/dist/package.conf.inplace
......@@ -695,7 +684,6 @@ BUILD_DIRS += utils/ghc-cabal
BUILD_DIRS += utils/hpc
BUILD_DIRS += utils/runghc
BUILD_DIRS += ghc
BUILD_DIRS += utils/mkUserGuidePart
BUILD_DIRS += docs/users_guide
BUILD_DIRS += utils/count_lines
BUILD_DIRS += utils/compare_sizes
......@@ -714,7 +702,6 @@ BUILD_DIRS := $(filter-out utils/mkdirhier,$(BUILD_DIRS))
BUILD_DIRS := $(filter-out utils/genprimopcode,$(BUILD_DIRS))
BUILD_DIRS := $(filter-out bindisttest,$(BUILD_DIRS))
BUILD_DIRS := $(filter-out utils/genapply,$(BUILD_DIRS))
BUILD_DIRS := $(filter-out utils/mkUserGuidePart,$(BUILD_DIRS))
endif
ifeq "$(HADDOCK_DOCS)" "NO"
BUILD_DIRS := $(filter-out utils/haddock,$(BUILD_DIRS))
......@@ -723,7 +710,6 @@ endif
ifeq "$(BUILD_SPHINX_HTML) $(BUILD_SPHINX_PDF)" "NO NO"
BUILD_DIRS := $(filter-out docs/users_guide,$(BUILD_DIRS))
# Don't to build this little utility if we're not building the User's Guide.
BUILD_DIRS := $(filter-out utils/mkUserGuidePart,$(BUILD_DIRS))
endif
ifeq "$(Windows_Host)" "NO"
BUILD_DIRS := $(filter-out utils/touchy,$(BUILD_DIRS))
......@@ -1518,8 +1504,8 @@ endif
# - neither do we register the ghc library (compiler/stage1) that we build
# with stage0. TODO Why not? We do build it...
# - as a result, we need to a) use ghc-stage2 to build packages that depend on
# the ghc library (e.g. ghctags [4] and mkUserGuidePart) and b) exclude
# those packages when ghc-stage2 is not available.
# the ghc library (e.g. ghctags [4]) and b) exclude those packages when
# ghc-stage2 is not available.
# - when Stage1Only=YES, it's clear that ghc-stage2 is not available (we just
# said we didn't want it), so we have to exclude the stage2 packages from
# the build. This includes the case where Stage1Only=YES is combined with
......
module DList where
newtype DList a = DList ([a] -> [a])
snoc :: DList a -> a -> DList a
DList f `snoc` x = DList (f . (x:))
toList :: DList a -> [a]
toList (DList f) = f []
instance Monoid (DList a) where
mempty = DList id
DList a `mappend` DList b = DList (a . b)
module Main (main) where
import DynFlags
import Control.Monad (forM_)
import Types hiding (flag)
import Table
import Options
import System.IO
writeFileUtf8 :: FilePath -> String -> IO ()
writeFileUtf8 f txt = withFile f WriteMode (\ hdl -> hSetEncoding hdl utf8 >> hPutStr hdl txt)
-- | A ReStructuredText fragment
type ReST = String
main :: IO ()
main = do
-- user's guide
writeRestFile (usersGuideFile "what_glasgow_exts_does.gen.rst")
$ whatGlasgowExtsDoes
forM_ groups $ \(Group name _ theFlags) ->
let fname = usersGuideFile $ "flags-"++name++".gen.rst"
in writeRestFile fname (flagsTable theFlags)
-- man page
writeRestFile (usersGuideFile "all-flags.gen.rst") (flagsList groups)
usersGuideFile :: FilePath -> FilePath
usersGuideFile fname = "docs/users_guide/"++fname
writeRestFile :: FilePath -> ReST -> IO ()
writeRestFile fname content =
writeFileUtf8 fname $ unlines
[ ".. This file is generated by utils/mkUserGuidePart"
, ""
, content
]
whatGlasgowExtsDoes :: String
whatGlasgowExtsDoes = unlines
$ [ ".. hlist::", ""]
++ map ((" * "++) . parseExt) glasgowExtsFlags
where
parseExt ext = inlineCode $ "-X" ++ show ext
-- | Generate a reference table of the given set of flags. This is used in
-- the user's guide.
flagsTable :: [Flag] -> ReST
flagsTable theFlags =
table [60, 100, 30, 55]
["Flag", "Description", "Type", "Reverse"]
(map flagRow theFlags)
where
flagRow flag =
[ role "ghc-flag" (flagName flag)
, flagDescription flag
, type_
, role "ghc-flag" (flagReverse flag)
]
where
type_ = case flagType flag of
DynamicFlag -> "dynamic"
DynamicSettableFlag -> "dynamic/``:set``"
ModeFlag -> "mode"
-- | Place the given text in an ReST inline code element.
inlineCode :: String -> ReST
inlineCode s = "``" ++ s ++ "``"
-- | @role "hi" "Hello world"@ produces the ReST inline role element
-- @:hi:`Hello world`@.
role :: String -> String -> ReST
role _ "" = ""
role r c = concat [":",r,":`",flag,"`",next]
where
-- Handle multiple comma separated flags
(flag, rest) = span (/= ',') c
next | rest == "" = rest
| otherwise = concat [", ", role r $ dropWhile (/= '-') rest]
heading :: Char -> String -> ReST
heading chr title = unlines
[ title
, replicate (length title) chr
, ""
]
-- | Generate a listing of all the flags known to GHC.
-- Used in the man page.
flagsList :: [Group] -> ReST
flagsList grps = unlines $
map doGroup grps ++ map flagDescriptions grps
where
doGroup grp = unlines
[ grpTitle grp
, " " ++ unwords (map (inlineCode . flagName) (grpFlags grp))
, ""
]
-- | Generate a definition list of the known flags.
-- Used in the man page.
flagDescriptions :: Group -> ReST
flagDescriptions (Group _ title fs) =
unlines $ [ heading '~' title ] ++ map doFlag fs
where
doFlag flag =
unlines $ [ inlineCode (flagName flag)
, " " ++ flagDescription flag
]
# -----------------------------------------------------------------------------
#
# (c) 2009 The University of Glasgow
#
# This file is part of the GHC build system.
#
# To understand how the build system works and how to modify it, see
# http://ghc.haskell.org/trac/ghc/wiki/Building/Architecture
# http://ghc.haskell.org/trac/ghc/wiki/Building/Modifying
#
# -----------------------------------------------------------------------------
dir = utils/mkUserGuidePart
TOP = ../..
include $(TOP)/mk/sub-makefile.mk
module Options (Group(..), groups) where
import Types
import Options.CodeGen
import Options.CompilerDebugging
import Options.Cpp
import Options.FindingImports
import Options.Interactive
import Options.InterfaceFiles
import Options.KeepingIntermediates
import Options.Language
import Options.Linking
import Options.Misc
import Options.Modes
import Options.Optimizations
import Options.OptimizationLevels
import Options.Packages
import Options.Phases
import Options.PhasePrograms
import Options.PhaseSpecific
import Options.PlatformSpecific
import Options.Plugin
import Options.Profiling
import Options.ProgramCoverage
import Options.RecompilationChecking
import Options.RedirectingOutput
import Options.TemporaryFiles
import Options.Verbosity
import Options.Warnings
-- | A group of flags
data Group = Group { grpName :: String -- ^ Internal name
, grpTitle :: String -- ^ Human-readable title
, grpFlags :: [Flag] -- ^ Flags in group
}
groups :: [Group]
groups =
[ Group "codegen" "Code generation" codegenOptions
, Group "compiler-debugging" "Debugging the compiler" compilerDebuggingOptions
, Group "cpp" "C pre-processor" cppOptions
, Group "finding-imports" "Finding imports" findingImportsOptions
, Group "interactive" "Interactive mode" interactiveOptions
, Group "interface-files" "Interface files" interfaceFilesOptions
, Group "keeping-intermediates" "Keeping intermediate files" keepingIntermediatesOptions
, Group "language" "Language options" languageOptions
, Group "linking" "Linking options" linkingOptions
, Group "misc" "Miscellaneous options" miscOptions
, Group "modes" "Modes of operation" modeOptions
, Group "optimization" "Individual optimizations " optimizationsOptions
, Group "optimization-levels" "Optimization levels" optimizationLevelsOptions
, Group "packages" "Package options" packagesOptions
, Group "phases" "Phases of compilation" phaseOptions
, Group "phase-programs" "Overriding external programs" phaseProgramsOptions
, Group "phase-specific" "Phase-specific options" phaseSpecificOptions
, Group "platform-specific" "Platform-specific options" platformSpecificOptions
, Group "plugin" "Compiler plugins" pluginOptions
, Group "profiling" "Profiling" profilingOptions
, Group "program-coverage" "Program coverage" programCoverageOptions
, Group "recompilation-checking" "Recompilation checking" recompilationCheckingOptions
, Group "redirecting-output" "Redirecting output" redirectingOutputOptions
, Group "temporary-files" "Temporary files" temporaryFilesOptions
, Group "verbosity" "Verbosity options" verbosityOptions
, Group "warnings" "Warnings" warningsOptions
]
module Options.CodeGen where
import Types
codegenOptions :: [Flag]
codegenOptions =
[ flag { flagName = "-fasm"
, flagDescription =
"Use the :ref:`native code generator <native-code-gen>`"
, flagType = DynamicFlag
, flagReverse = "-fllvm"
}
, flag { flagName = "-fllvm"
, flagDescription =
"Compile using the :ref:`LLVM code generator <llvm-code-gen>`"
, flagType = DynamicFlag
, flagReverse = "-fasm"
}
, flag { flagName = "-fno-code"
, flagDescription = "Omit code generation"
, flagType = DynamicFlag
}
, flag { flagName = "-fwrite-interface"
, flagDescription = "Always write interface files"
, flagType = DynamicFlag
}
, flag { flagName = "-fbyte-code"
, flagDescription = "Generate byte-code"
, flagType = DynamicFlag
}
, flag { flagName = "-fobject-code"
, flagDescription = "Generate object code"
, flagType = DynamicFlag
}
, flag { flagName = "-g⟨n⟩"
, flagDescription =
"Produce DWARF debug information in compiled object files." ++
"⟨n⟩ can be 0, 1, or 2, with higher numbers producing richer " ++
"output. If ⟨n⟩ is omitted level 2 is assumed."
, flagType = DynamicFlag
}
, flag { flagName = "-dynamic"
, flagDescription = "Build dynamically-linked object files and executables"
, flagType = DynamicFlag
}
, flag { flagName = "-dynamic-too"
, flagDescription =
"Build dynamic object files *as well as* static object files " ++
"during compilation"
, flagType = DynamicFlag
}
]
module Options.CompilerDebugging where
import Types
compilerDebuggingOptions :: [Flag]
compilerDebuggingOptions =
[ flag { flagName = "-dcore-lint"
, flagDescription = "Turn on internal sanity checking"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-to-file"
, flagDescription = "Dump to files instead of stdout"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-asm"
, flagDescription = "Dump assembly"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-bcos"
, flagDescription = "Dump interpreter byte code"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-cmm-from-stg"
, flagDescription = "Dump STG-to-C-- output"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-cmm-verbose"
, flagDescription = "Show output from each C-- pipeline pass"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-cmm"
, flagDescription = "Dump the final C-- output"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-core-stats"
, flagDescription =
"Print a one-line summary of the size of the Core program at the "++
"end of the optimisation pipeline"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-cse"
, flagDescription = "Dump CSE output"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-deriv"
, flagDescription = "Dump deriving output"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-ds"
, flagDescription = "Dump desugarer output"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-foreign"
, flagDescription = "Dump ``foreign export`` stubs"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-hpc"
, flagDescription = "Dump after instrumentation for program coverage"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-inlinings"
, flagDescription = "Dump inlining info"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-llvm"
, flagDescription = "Dump LLVM intermediate code. "++
"Implies :ghc-flag:`-fllvm`."
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-occur-anal"
, flagDescription = "Dump occurrence analysis output"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-opt-cmm"
, flagDescription = "Dump the results of C-- to C-- optimising passes"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-parsed"
, flagDescription = "Dump parse tree"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-prep"
, flagDescription = "Dump prepared core"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-rn"
, flagDescription = "Dump renamer output"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-rule-firings"
, flagDescription = "Dump rule firing info"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-rule-rewrites"
, flagDescription = "Dump detailed rule firing info"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-rules"
, flagDescription = "Dump rules"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-vect"
, flagDescription = "Dump vectoriser input and output"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-simpl"
, flagDescription = "Dump final simplifier output"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-simpl-iterations"
, flagDescription = "Dump output from each simplifier iteration"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-spec"
, flagDescription = "Dump specialiser output"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-splices"
, flagDescription =
"Dump TH spliced expressions, and what they evaluate to"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-stg"
, flagDescription = "Dump final STG"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-stranal"
, flagDescription = "Dump strictness analyser output"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-str-signatures"
, flagDescription = "Dump strictness signatures"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-tc"
, flagDescription = "Dump typechecker output"
, flagType = DynamicFlag
}
, flag { flagName = "-dth-dec-file=⟨file⟩"
, flagDescription =
"Show evaluated TH declarations in a .th.hs file"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-types"
, flagDescription = "Dump type signatures"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-worker-wrapper"
, flagDescription = "Dump worker-wrapper output"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-if-trace"
, flagDescription = "Trace interface files"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-tc-trace"
, flagDescription = "Trace typechecker"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-vt-trace"
, flagDescription = "Trace vectoriser"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-rn-trace"
, flagDescription = "Trace renamer"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-rn-stats"
, flagDescription = "Renamer stats"
, flagType = DynamicFlag
}
, flag { flagName = "-ddump-simpl-stats"
, flagDescription = "Dump simplifier stats"
, flagType = DynamicFlag
}
, flag { flagName = "-dno-debug-output"
, flagDescription = "Suppress unsolicited debugging output"
, flagType = DynamicFlag
}
, flag { flagName = "-dppr-debug"
, flagDescription = "Turn on debug printing (more verbose)"
, flagType = DynamicFlag
}
, flag { flagName = "-dppr-user-length"
, flagDescription =
"Set the depth for printing expressions in error msgs"
, flagType = DynamicFlag
}
, flag { flagName = "-dppr-cols=⟨n⟩"
, flagDescription =
"Set the width of debugging output. For example ``-dppr-cols200``"
, flagType = DynamicFlag
}
, flag { flagName = "-dppr-case-as-let"
, flagDescription =
"Print single alternative case expressions as strict lets."
, flagType = DynamicFlag
}
, flag { flagName = "-dsuppress-all"
, flagDescription =
"In core dumps, suppress everything (except for uniques) that is "++
"suppressible."
, flagType = DynamicFlag
}
, flag { flagName = "-dsuppress-uniques"
, flagDescription =
"Suppress the printing of uniques in debug output (easier to use "++
"``diff``)"
, flagType = DynamicFlag
}
, flag { flagName = "-dsuppress-idinfo"
, flagDescription =
"Suppress extended information about identifiers where they "++
"are bound"