From 0ee9b4b3411fdf9bb45a33b9faf4ab7e62968a4f Mon Sep 17 00:00:00 2001
From: "Edward Z. Yang" <ezyang@cs.stanford.edu>
Date: Sat, 29 Oct 2016 00:28:58 -0700
Subject: [PATCH] [skip ci] Minor reorg of profiling documentation.
Signed-off-by: Edward Z. Yang <ezyang@cs.stanford.edu>
---
Cabal/doc/nix-local-build.rst | 124 +++++++++++++++++++++-------------
1 file changed, 76 insertions(+), 48 deletions(-)
diff --git a/Cabal/doc/nix-local-build.rst b/Cabal/doc/nix-local-build.rst
index 7a424bf35b..55ada8b0f9 100644
--- a/Cabal/doc/nix-local-build.rst
+++ b/Cabal/doc/nix-local-build.rst
@@ -76,6 +76,32 @@ Unlike sandboxes, there is no need to setup a sandbox or ``add-source``
projects; just check in ``cabal.project`` to your repository and
``new-build`` will just work.
+Cookbook
+========
+
+How can I profile my library/application?
+-----------------------------------------
+
+First, make sure you have HEAD; 1.24 is affected by :issue:`3790`,
+which means that if any project which transitively depends on a
+package which has a Custom setup built against Cabal 1.22 or earlier
+will silently not work.
+
+Create or edit your ``cabal.project.local``, adding the following
+line::
+
+ profiling: True
+
+Now, ``cabal new-build`` will automatically build all libraries and
+executables with profiling. You can fine-tune the profiling settings
+for each package using :cfg-field:`profiling-detail`::
+
+ package p
+ profiling-detail: toplevel-functions
+
+Alternately, you can call ``cabal new-build --enable-profiling`` to
+temporarily build with profiling.
+
How it works
============
@@ -387,8 +413,8 @@ which live inside stanzas:
In general, the accepted field names coincide with the accepted command
line flags that ``cabal install`` and other commands take. For example,
-``cabal new-configure --library-profiling`` will write out a project
-file with ``library-profiling: True``.
+``cabal new-configure --enable-profiling`` will write out a project
+file with ``profiling: True``.
The full configuration of a project is determined by combining the
following sources (later entries override earlier ones):
@@ -755,7 +781,7 @@ an external dependency) should be built with ``-fno-state-hack``::
but is one of many fields for configuring programs. They take the form
``progname-options`` and ``progname-location``, and
can only be set inside package stanzas. (TODO: They are not supported
-at top-level, see :issue:`3579`.
+at top-level, see :issue:`3579`.)
At the moment, there is no way to specify an option to apply to all
external packages or all inplace packages. Additionally, it is only
@@ -1213,47 +1239,6 @@ Profiling options
The command line variant of this flag is ``--enable-profiling`` and
``--disable-profiling``.
-.. cfg-field:: library-vanilla: boolean
- --enable-library-vanilla
- --disable-library-vanilla
- :synopsis: Build libraries without profiling.
-
- :default: True
-
- Build ordinary libraries (as opposed to profiling libraries).
- Mostly, you can set this to False to avoid building ordinary
- libraries when you are profiling.
-
- The command line variant of this flag is
- ``--enable-library-vanilla`` and ``--disable-library-vanilla``.
-
-.. cfg-field:: library-profiling: boolean
- --enable-library-profiling
- --disable-library-profiling
- :synopsis: Build libraries with profiling enabled.
- :since: 1.21
-
- :default: False
-
- Build libraries with profiling enabled.
-
- The command line variant of this flag is
- ``--enable-library-profiling`` and ``--disable-library-profiling``.
-
-.. cfg-field:: executable-profiling: boolean
- --enable-executable-profiling
- --disable-executable-profiling
- :synopsis: Build executables with profiling enabled.
- :since: 1.21
-
- :default: False
-
- Build executables with profiling enabled.
-
- The command line variant of this flag is
- ``--enable-executable-profiling`` and
- ``--disable-executable-profiling``.
-
.. cfg-field:: profiling-detail: level
--profiling-detail=level
:synopsis: Profiling detail level.
@@ -1278,18 +1263,18 @@ Profiling options
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.
+ functions exported from each module. In GHC, this
+ is for non-inline functions. Corresponds to ``-fprof-auto-exported``.
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.
+ functions. Corresponds to ``-fprof-auto-top``.
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.
+ values. Corresponds to ``-fprof-auto``.
The command line variant of this flag is
``--profiling-detail=none``.
@@ -1304,6 +1289,49 @@ Profiling options
The command line variant of this flag is
``--library-profiling-detail=none``.
+.. cfg-field:: library-vanilla: boolean
+ --enable-library-vanilla
+ --disable-library-vanilla
+ :synopsis: Build libraries without profiling.
+
+ :default: True
+
+ Build ordinary libraries (as opposed to profiling libraries).
+ Mostly, you can set this to False to avoid building ordinary
+ libraries when you are profiling.
+
+ The command line variant of this flag is
+ ``--enable-library-vanilla`` and ``--disable-library-vanilla``.
+
+.. cfg-field:: library-profiling: boolean
+ --enable-library-profiling
+ --disable-library-profiling
+ :synopsis: Build libraries with profiling enabled.
+ :since: 1.21
+
+ :default: False
+
+ Build libraries with profiling enabled. You probably want
+ to use :cfg-field:`profiling` instead.
+
+ The command line variant of this flag is
+ ``--enable-library-profiling`` and ``--disable-library-profiling``.
+
+.. cfg-field:: executable-profiling: boolean
+ --enable-executable-profiling
+ --disable-executable-profiling
+ :synopsis: Build executables with profiling enabled.
+ :since: 1.21
+
+ :default: False
+
+ Build executables with profiling enabled. You probably want
+ to use :cfg-field:`profiling` instead.
+
+ The command line variant of this flag is
+ ``--enable-executable-profiling`` and
+ ``--disable-executable-profiling``.
+
Coverage options
^^^^^^^^^^^^^^^^
--
GitLab