flavours.md

Build flavours

Hadrian supports a few predefined build flavours, i.e. collections of build settings that fully define a GHC build (see src/Flavour.hs). Users can add their own build flavours if need be, as described here.

Arguments

The following table summarises extra arguments passed to GHC in different build flavours. There are four groups of arguments: arguments in hsDefault are passed to GHC for all Haskell source files, hsLibrary arguments are added when compiling libraries, hsCompiler when compiling the compiler library, and hsGhc when compiling/linking the GHC program.

Flavour	Split Sections	Extra arguments
		hsDefault		hsLibrary		hsCompiler		hsGhc
		stage0	stage1+	stage0	stage1+	stage0	stage1+	stage0	stage1+
default		-O -H32m	-O2 -H32m		-haddock
quick		-O0 -H64m	-O0 -H64m		-O	-O2	-O	-O
quick-validate		-O0 -H64m -Werror	-O0 -H64m -Werror		-O	-O2	-O	-O
quick-debug		-O0 -H64m	-O0 -H64m		-O	-O2	-O	-O	-debug (link)
quickest		-O0 -H64m	-O0 -H64m			-O		-O
perf	Yes (on supported platforms)	-O -H64m	-O -H64m		-O2	-O2	-O2	-O	-O2
release (same as perf with -haddock and +no_self_recomp+hash_unit_ids)		-O -H64m	-O -H64m		-O2	-O2	-O2	-O	-O2
bench		-O -H64m	-O -H64m		-O2	-O2	-O0	-O2	-O2
devel1		-O -H64m	-O -H64m		-dcore-lint	-O0 -DDEBUG		-O0 -DDEBUG
devel2		-O -H64m	-O -H64m		-dcore-lint	-O2	-O0 -DDEBUG		-O0 -DDEBUG
validate		-O0 -H64m	-fllvm-fill-undef-with-garbage -fcheck-prim-bounds		-O -dcore-lint -dno-debug-output	-O2 -DDEBUG	-O -dcore-lint -dno-debug-output	-O	-O
slow-validate		-O0 -H64m	-fllvm-fill-undef-with-garbage		-O -dcore-lint -dno-debug-output	-O2 -DDEBUG	-O -DDEBUG -dcore-lint -dno-debug-output	-O	-O
static		-O -H64m -fPIC -static	-O -H64m -fPIC -static		-O2	-O2	-O2	-O -optl -static	-O2 -optl -static

Flavour transformers

Each of the flavours described above is intended as a starting-point for configuring your GHC build. In addition, Hadrian supports a number of "flavour transformers" which modify the configuration in various ways.

These can be appended to the flavour name passed via the --flavour command-line flag, separated by the + character. For instance,

hadrian --flavour=perf+thread_sanitizer

The supported transformers are listed below:

Transformer name	Effect
werror	Use the `-Werror` flag for all stage1+ compilation.
debug_info	Enable production of native debugging information (via GHC/GCC's `-g3`) during stage1+ compilations.
ticky_ghc	Compile the GHC executable with Ticky-Ticky profiler support.
split_sections	Enable section splitting for all libraries (except for the GHC library due to the long linking times that this causes).
no_split_sections	Disable section splitting for all libraries.
thread_sanitizer	Build the runtime system with ThreadSanitizer support
llvm	Use GHC's LLVM backend (`-fllvm`) for all stage1+ compilation.
profiled_ghc	Build the GHC executable with cost-centre profiling support. It is recommended that you use this in conjunction with `no_dynamic_ghc` since GHC does not support loading of profiled libraries with the dynamic linker. You should use a flavour that builds profiling libs and rts, i.e. not quick. This flag adds cost centres with the -fprof-late flag.
no_dynamic_ghc	Linked GHC against the statically-linked RTS. This causes GHC to default to loading static rather than dynamic library when, e.g., loading libraries during TemplateHaskell evaluations.
no_dynamic_libs	Just like `no_dynamic_ghc`, this transformer ensures statically-linked libraries
native_bignum	Use the native ghc-bignum backend.
text_simdutf	Enable building the text package with simdutf support.
no_profiled_libs	Disables building of libraries in profiled build ways.
omit_pragmas	Build the stage2 compiler with -fomit-interface-pragmas to reduce recompilation.
ipe	Build the stage2 libraries with IPE debugging information for use with -hi profiling.
debug_ghc	Build the stage2 compiler linked against the debug rts
debug_stage1_ghc	Build the stage1 compiler linked against the debug rts
assertions	Build the stage2 compiler with assertions enabled.
fully_static	Produce fully statically-linked executables and build libraries suitable for static linking.
host_fully_static	Ensure host executables are fully static, while still permitting shared target libraries.
collect_timings	Collects timings while building the stage2+ compiler by adding the flags -ddump-to-file -ddump-timings.
lint	Enable Core, STG, and C-- linting in all compilation with the stage1 compiler.
haddock	Emit haddock documentation into the interface files via -haddock.
hi_core	Emit whole Core bindings into the interface files via -fwrite-if-simplified-core.
late_ccs	Enable -fprof-late in profiled libraries. Enabled in perf and release flavours.
dump_stg	Dump STG of all modules compiled by a stage1 compiler to a file
no_self_recomp	Disable including self-recompilation information in interface files via -fno-write-if-self-recomp. If you are building a distribution you can enable this flag to produce more deterministic interface files.	hash_unit_ids	Include a package hash in the unit id of built packages

Static

The static flavour does not strictly follow the groupings in the table above because it links all the executables statically, not just GHC itself, and because it passes -optc -static when delegating to a C compiler. It also turns off dynamic linking at runtime by by adding the -dynamic-system-linker cabal flag to the ghc package build because musl doesn't allow dynamic linking in executables that were statically linked against libc. Static flags are only added when building in a non-dynamic way. Some of the considerations for a static build aren't a great fit for the flavour system, so it's a little bit hacky.

Ways

Libraries and GHC can be built in different ways, e.g. with or without profiling information. The following table lists ways that are built in different flavours.

Flavour	Library ways		RTS ways
	stage0	stage1+	stage0	stage1+	stage0	stage1+
default perf prof devel1 devel2	vanilla	vanilla profiling dynamic	debug threaded threadedDebug debugDynamic threadedDynamic threadedDebugDynamic	debug threaded threadedDebug threadedProfiling debugDynamic threadedDynamic threadedDebugDynamic
static	vanilla	vanilla profiling	debug threaded threadedDebug	debug threaded threadedDebug threadedProfiling	Only in prof flavour	Only in prof flavour
quick quick-validate quick-debug	vanilla	vanilla dynamic	debug threaded threadedDebug debugDynamic threadedDynamic threadedDebugDynamic	debug threaded threadedDebug debugDynamic threadedDynamic threadedDebugDynamic
quickest bench	vanilla	vanilla	vanilla threaded	vanilla threaded