HORIZON HASKELLDocslts/ghc-9.10.x248f8f02026-10-05Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · 248f8f0 · 2026-10-05

Moduleghc-9.10.3GHC2021

GHC.Driver.Session

Dynamic flags

Most flags are dynamic flags, which means they can change from compilation to compilation using OPTIONS_GHC pragmas, and in a multi-session GHC each session can be using different dynamic flags. Dynamic flags can also be set at the prompt in GHCi.

(c) The University of Glasgow 2005

  • 34 types
  • 2 classes
  • 222 values
  • Packageghc-9.10.3
  • Exports259
  • LanguageGHC2021
  • LicenceBSD-3-Clause
  • SourceSession.hs

Dynamic flags and associated configuration types

86 declarations
datadata DumpFlag
#

Debugging flags

Constructors

Instances3Enum, Eq, Show
datadata GeneralFlag
#

Enumerates the simple on-or-off dynamic flags

Constructors

Instances3Enum, Eq, Show
datadata WarningFlag
#
Opt_WarnDuplicateExportsOpt_WarnDuplicateConstraintsOpt_WarnRedundantConstraintsOpt_WarnHiShadowsOpt_WarnImplicitPreludeOpt_WarnIncompletePatternsOpt_WarnIncompleteUniPatternsOpt_WarnIncompletePatternsRecUpdOpt_WarnOverflowedLiteralsOpt_WarnEmptyEnumerationsOpt_WarnMissingFieldsOpt_WarnMissingImportListOpt_WarnMissingMethodsOpt_WarnMissingSignaturesOpt_WarnMissingLocalSignaturesOpt_WarnNameShadowingOpt_WarnOverlappingPatternsOpt_WarnTypeDefaultsOpt_WarnMonomorphismOpt_WarnUnusedTopBindsOpt_WarnUnusedLocalBindsOpt_WarnUnusedPatternBindsOpt_WarnUnusedImportsOpt_WarnUnusedMatchesOpt_WarnUnusedTypePatternsOpt_WarnUnusedForallsOpt_WarnUnusedRecordWildcardsOpt_WarnRedundantBangPatternsOpt_WarnRedundantRecordWildcardsOpt_WarnDeprecatedFlagsOpt_WarnMissingMonadFailInstancesOpt_WarnSemigroupOpt_WarnDodgyExportsOpt_WarnDodgyImportsOpt_WarnOrphansOpt_WarnAutoOrphansOpt_WarnIdentitiesOpt_WarnTabsOpt_WarnUnrecognisedPragmasOpt_WarnMisplacedPragmasOpt_WarnDodgyForeignImportsOpt_WarnUnusedDoBindOpt_WarnWrongDoBindOpt_WarnAlternativeLayoutRuleTransitionalOpt_WarnUnsafeOpt_WarnSafeOpt_WarnTrustworthySafeOpt_WarnMissedSpecsOpt_WarnAllMissedSpecsOpt_WarnUnsupportedCallingConventionsOpt_WarnUnsupportedLlvmVersionOpt_WarnMissedExtraSharedLibOpt_WarnInlineRuleShadowingOpt_WarnTypedHolesOpt_WarnPartialTypeSignaturesOpt_WarnMissingExportedSignaturesOpt_WarnUntickedPromotedConstructorsOpt_WarnDerivingTypeableOpt_WarnDeferredTypeErrorsOpt_WarnDeferredOutOfScopeVariablesOpt_WarnNonCanonicalMonadInstancesOpt_WarnNonCanonicalMonadFailInstancesOpt_WarnNonCanonicalMonoidInstancesOpt_WarnMissingPatternSynonymSignaturesOpt_WarnUnrecognisedWarningFlagsOpt_WarnSimplifiableClassConstraintsOpt_WarnCPPUndefOpt_WarnUnbangedStrictPatternsOpt_WarnMissingHomeModulesOpt_WarnPartialFieldsOpt_WarnMissingExportListOpt_WarnInaccessibleCodeOpt_WarnStarIsTypeOpt_WarnStarBinderOpt_WarnImplicitKindVarsOpt_WarnSpaceAfterBangOpt_WarnMissingDerivingStrategiesOpt_WarnPrepositiveQualifiedModuleOpt_WarnUnusedPackagesOpt_WarnInferredSafeImportsOpt_WarnMissingSafeHaskellModeOpt_WarnCompatUnqualifiedImportsOpt_WarnDerivingDefaultsOpt_WarnInvalidHaddockOpt_WarnOperatorWhitespaceExtConflictOpt_WarnOperatorWhitespaceOpt_WarnAmbiguousFieldsOpt_WarnImplicitLiftOpt_WarnMissingKindSignaturesOpt_WarnMissingPolyKindSignaturesOpt_WarnMissingExportedPatternSynonymSignaturesOpt_WarnRedundantStrictnessFlagsOpt_WarnForallIdentifierOpt_WarnUnicodeBidirectionalFormatCharactersOpt_WarnGADTMonoLocalBindsOpt_WarnTypeEqualityOutOfScopeOpt_WarnTypeEqualityRequiresOperatorsOpt_WarnLoopySuperclassSolveOpt_WarnTermVariableCaptureOpt_WarnMissingRoleAnnotationsOpt_WarnImplicitRhsQuantificationOpt_WarnIncompleteExportWarningsOpt_WarnIncompleteRecordSelectorsOpt_WarnBadlyStagedTypesOpt_WarnInconsistentFlagsOpt_WarnDataKindsTCOpt_WarnDeprecatedTypeAbstractionsOpt_WarnDefaultedExceptionContext
Instances5Bounded, Enum, Eq, Ord, Show
datadata DiagnosticReason
#

The reason why a Diagnostic was emitted in the first place. Diagnostic messages are born within GHC with a very precise reason, which can be completely statically-computed (i.e. this is an error or a warning no matter what), or influenced by the specific state of the DynFlags at the moment of the creation of a new Diagnostic. For example, a parsing error is always going to be an error, whereas a 'WarningWithoutFlag Opt_WarnUnusedImports' might turn into an error due to '-Werror' or '-Werror=warn-unused-imports'. Interpreting a DiagnosticReason together with its associated Severity gives us the full picture.

Constructors

Instances3Eq, Show, Outputable
datadata Language
#
Haskell98Haskell2010GHC2021GHC2024
Instances7Bounded, Enum, Eq, Show, NFData, Outputable, …
valuegopt :: GeneralFlag -> DynFlags -> Bool
#

Test whether a GeneralFlag is set

Note that dynamicNow (i.e., dynamic objects built with `-dynamic-too`) always implicitly enables Opt_PIC, Opt_ExternalDynamicRefs, and disables Opt_SplitSections.

datadata DynFlags
#

Contains not only a collection of GeneralFlags but also a plethora of information relating to the compilation of a single file or GHC session

Constructors

classclass HasDynFlags (m :: Type -> Type) where
#

Methods

Instances13HasDynFlags, …
datadata GhcMode
#

The GhcMode tells us whether we're doing multi-module compilation (controlled via the GHC API) or one-shot (single-module) compilation. This makes a difference primarily to the GHC.Unit.Finder: in one-shot mode we look for interface files for imported modules, but in multi-module mode we look for source files in order to check whether they need to be recompiled.

Constructors

Instances2Eq, Outputable
datadata PackageArg
#

We accept flags which make packages visible, but how they select the package varies; this data type reflects what selection criterion is used.

Constructors

Instances3Eq, Show, Outputable
datadata ModRenaming
#

Represents the renaming that may be associated with an exposed package, e.g. the rns part of -package "foo (rns)".

Here are some example parsings of the package flags (where a string literal is punned to be a ModuleName:

  • -package foo is ModRenaming True []

  • -package foo () is ModRenaming False []

  • -package foo (A) is ModRenaming False [(A, A)]

  • -package foo (A as B) is ModRenaming False [(A, B)]

  • -package foo with (A as B) is ModRenaming True [(A, B)]

Constructors

Instances2Eq, Outputable
datadata Option
#

When invoking external tools as part of the compilation pipeline, we pass these a sequence of options on the command-line. Rather than just using a list of Strings, we use a type that allows us to distinguish between filepaths and 'other stuff'. The reason for this is that this type gives us a handle on transforming filenames, and filenames only, to whatever format they're expected to be on a particular platform.

Constructors

Instances1Eq
  • Eq OptionDefined in ghc-9.10.3 · GHC.Utils.CliOption
valueoptimisationFlags :: EnumSet GeneralFlag
#

The set of flags which affect optimisation for the purposes of recompilation avoidance. Specifically, these include flags which affect code generation but not the semantics of the program.

See Note [Ignoring some flag changes] in GHC.Iface.Recomp.Flags)

valuecodeGenFlags :: EnumSet GeneralFlag
#

The set of flags which affect code generation and can change a program's runtime behavior (other than performance). These include flags which affect:

  • user visible debugging information (e.g. info table provenance)

  • the ability to catch runtime errors (e.g. -fignore-asserts)

  • the runtime result of the program (e.g. -fomit-yields)

  • which code or interface file declarations are emitted

We also considered placing flags which affect asympototic space behavior (e.g. -ffull-laziness) however this would mean that changing optimisation levels would trigger recompilation even with -fignore-optim-changes, regressing #13604.

Also, arguably Opt_IgnoreAsserts should be here as well; however, we place it instead in optimisationFlags since it is implied by -O[12] and therefore would also break #13604.

See #23369.

valuepprDynFlagsDiff :: DynFlags -> DynFlags -> SDoc
#

Pretty-print the difference between 2 DynFlags.

For now only their general flags but it could be extended. Useful mostly for debugging.

Safe Haskell

valuesafeDirectImpsReq :: DynFlags -> Bool
#

Are all direct imports required to be safe for this Safe Haskell mode? Direct imports are when the code explicitly imports a module

valuesafeImplicitImpsReq :: DynFlags -> Bool
#

Are all implicit imports required to be safe for this Safe Haskell mode? Implicit imports are things in the prelude. e.g System.IO when print is used.

System tool settings and locations

valuesettings :: DynFlags -> Settings
#

"unbuild" a Settings from a DynFlags. This shouldn't be needed in the vast majority of code. But GHCi questionably uses this to produce a default DynFlags from which to compute a flags diff for printing.

valueversionedAppDir :: String -> ArchOS -> MaybeT IO FilePath
#

The directory for this version of ghc in the user's app directory The appdir used to be in ~/.ghc but to respect the XDG specification we want to move it under $XDG_DATA_HOME/ However, old tooling (like cabal) might still write package environments to the old directory, so we prefer that if a subdirectory of ~/.ghc with the correct target and GHC version suffix exists.

i.e. if ~.ghc$UNIQUE_SUBDIR exists we use that otherwise we use $XDG_DATA_HOME/$UNIQUE_SUBDIR

UNIQUE_SUBDIR is typically a combination of the target platform and GHC version

Manipulating DynFlags

valuegetOpts
  1. :: DynFlags

    DynFlags to retrieve the options from

  2. -> (DynFlags -> [a])

    Relevant record accessor: one of the opt_* accessors

  3. -> [a]

    Correctly ordered extracted options

#

Retrieve the options corresponding to a particular opt_* field in the correct order

valuegetVerbFlags :: DynFlags -> [String]
#

Gets the verbosity flag for the current verbosity level. This is fed to other tools, so GHC-specific verbosity flags like -ddump-most are not included

State

Parsing DynFlags

valueparseDynamicFlagsFull
  1. :: MonadIO m
  2. => [Flag (CmdLineP DynFlags)]

    valid flags to match against

  3. -> Bool

    are the arguments from the command line?

  4. -> DynFlags

    current dynamic flags

  5. -> [Located String]

    arguments to parse

  6. -> m (DynFlags, [Located String], Messages DriverMessage)
#

Parses the dynamically set flags for GHC. This is the most general form of the dynamic flag parser that the other methods simply wrap. It allows saying which flags are valid flags and indicating if we are parsing arguments from the command line or from a file pragma.

Available DynFlags

valueallNonDeprecatedFlags :: [String]
#

All dynamic flags option strings without the deprecated ones. These are the user facing strings for enabling and disabling options.

valueflagsForCompletion :: Bool -> [String]
#

Make a list of flags for shell completion. Filter all available flags into two groups, for interactive GHC vs all other.

valuelanguageExtensions :: Maybe Language -> [Extension]
#

The language extensions implied by the various language variants. When updating this be sure to update the flag documentation in docsusers_guideexts.

DynFlags C compiler options

DynFlags C linker options

Compiler configuration suitable for display to the user

3 declarations

SSE and AVX

10 declarations

Linker/compiler information

3 declarations

Include specifications

5 declarations
valueaddQuoteInclude :: IncludeSpecs -> [String] -> IncludeSpecs
#

Append to the list of includes a path that shall be included using `-iquote` when the C compiler is called. These paths only apply when quoted includes are used. e.g. #include "foo.h"

SDoc

3 declarations