Update user guide for new --[library-]profiling-detail flags

Cabal/doc/developing-packages.markdown

@@ -1370,12 +1370,22 @@ values for these fields.
 
 `ghc-prof-options:` _token list_
 :   Additional options for GHC when the package is built with profiling
-    enabled. For libraries, `-fprof-auto-exported` is enabled by
-    default, automatically adding cost center annotations to all
-    exported bindings. For executables, `-fprof-auto-top` is enabled
-    by default, automatically adding cost center annotations to all
-    top-level bindings. In either case, set `-fno-prof-auto` to
-    override the default.
+    enabled.
+
+    Note that as of Cabal-1.24, the default profiling detail level defaults to
+    `exported-functions` for libraries and `toplevel-funcitons` for
+    executables. For GHC these correspond to the flags `-fprof-auto-exported`
+    and `-fprof-auto-top`. Prior to Cabal-1.24 the level defaulted to `none`.
+    These levels can be adjusted by the person building the package with the
+    `--profiling-detail` and `--library-profiling-detail` flags.
+
+    It is typically better for the person building the package to pick the
+    profiling detail level rather than for the package author. So unless you
+    have special needs it is probably better not to specify any of the GHC
+    `-fprof-auto*` flags here. However if you wish to override the profiling
+    detail level, you can do so using the `ghc-prof-options` field: use
+    `-fno-prof-auto` or one of the other `-fprof-auto*` flags.
+
 
 `ghc-shared-options:` _token list_
 :   Additional options for GHC when the package is built as shared library.

Cabal/doc/installing-packages.markdown

@@ -626,24 +626,80 @@ be controlled with the following command line options.
 :   Build without optimization. This is suited for development: building
     will be quicker, but the resulting library or programs will be slower.
 
+`--enable-profiling`
+:   Build libraries and executables with profiling enabled (for compilers
+    that support profiling as a separate mode). For this to work, all
+    libraries used by this package must also have been built with profiling
+    support. For libraries this involves building an additional instance of
+    the library in addition to the normal non-profiling instance. For
+    executables it changes the single executable to be built in profiling mode.
+
+    This flag covers both libraries and executables, but can be overridden
+    by the `--enable-library-profiling` flag.
+
+    See also the `--profiling-detail` flag below.
+
+`--disable-profiling`
+:   (default) Do not enable profiling in generated libraries and executables.
+
 `--enable-library-profiling` or `-p`
-:   Request that an additional version of the library with profiling
-    features enabled be built and installed (only for implementations
-    that support profiling).
+:   As with `--enable-profiling` above, but it applies only for libraries. So
+    this generates an additional profiling instance of the library in addition
+    to the normal non-profiling instance.
+
+    The `--enable-profiling` flag controls the profiling mode for both
+    libraries and executables, but if different modes are desired for
+    libraries versus executables then use `--enable-library-profiling` as well.
 
 `--disable-library-profiling`
 :   (default) Do not generate an additional profiling version of the
     library.
 
-`--enable-profiling`
-:   Any executables generated should have profiling enabled (only for
-    implementations that support profiling). For this to work, all
-    libraries used by these executables must also have been built with
-    profiling support. The library will be built with profiling enabled (if
-    supported) unless `--disable-library-profiling` is specified.
+`--profiling-detail`[=_level_]
+:   Some compilers that support profiling, notably GHC, can allocate costs to
+    different parts of the program and there are different levels of
+    granularity or detail with which this can be done. In particular for GHC
+    this concept is called "cost centers", and GHC can automatically add cost
+    centers, and can do so in different ways.
+
+    This flag covers both libraries and executables, but can be overridden
+    by the `--library-profiling-detail` flag.
+
+    Currently this setting is ignored for compilers other than GHC. The levels
+    that cabal currently supports are:
+
+    `default`
+    :    For GHC this uses `exported-functions` for libraries and
+         `toplevel-functions` for executables.
+
+    `none`
+    :    No costs will be assigned to any code within this component.
+
+    `exported-functions`
+    :    Costs will be assigned at the granularity of all top level functions
+         exported from each module. In GHC specifically, this is for non-inline
+         functions.
+
+    `toplevel-functions`
+    :    Costs will be assigned at the granularity of all top level functions
+         in each module, whether they are exported from the module or not.
+         In GHC specifically, this is for non-inline functions.
+
+    `all-functions`
+    :    Costs will be assigned at the granularity of all functions in each
+         module, whether top level or local. In GHC specifically, this is for
+         non-inline toplevel or where-bound functions or values.
+
+    This flag is new in Cabal-1.24. Prior versions used the equivalent of
+    `none` above.
+
+`--library-profiling-detail`[=_level_]
+:   As with `--profiling-detail` above, but it applies only for libraries.
+
+    The level for both libraries and executables is set by the
+    `--profiling-detail` flag, but if different levels are desired for
+    libraries versus executables then use `--library-profiling-detail` as well.
 
-`--disable-profiling`
-:   (default) Do not enable profiling in generated executables.
 
 `--enable-library-vanilla`
 :   (default) Build ordinary libraries (as opposed to profiling