comments on SRC_HC_OPTS (#4829)

mk/config.mk.in

@@ -386,6 +386,23 @@ WINDOWS_INSTALLER = $(WINDOWS_INSTALLER_BASE)$(exeext)
 #
 #	SRC_HC_OPTS += -O
 
+
+# SRC_HC_OPTS includes flags to be added to *every* Haskell
+# compilation.  Setting SRC_HC_OPTS is a good way to set the default
+# optimisation level (-O) and heap size (-H<size>).
+# 
+# SRC_HC_OPTS is *not* for adding flags that are required to make your
+# build work.  Examples:
+#
+#  - instead of using -pgmc/-pgma-/-pgml, use the --with-gcc option to configure
+#
+#  - if you need -optc, -opta, or -optl flags, the CONF_CC_* and CONF_LD_*
+#    variables are more appropriate (set via configure)
+#
+# Note that SRC_HC_OPTS are added to every Haskell compilation,
+# including when using the bootstrapping compiler (stage 0), So don't
+# put options here that are only supported by very recent GHCs.
+#
 SRC_HC_OPTS += -H32m -O
 
 # These flags make flex 8-bit