From 6532aa46a9922bbf938bacce480890e2a31a40af Mon Sep 17 00:00:00 2001 From: Simon Jakobi Date: Sat, 29 Nov 2025 11:30:48 +0100 Subject: [PATCH 1/3] Update instructions for code inspection --- CONTRIBUTING.md | 78 ++++++++++++++++++++++++++--------- cabal.project.local.dump-code | 11 +++++ unordered-containers.cabal | 5 --- 3 files changed, 70 insertions(+), 24 deletions(-) create mode 100644 cabal.project.local.dump-code diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a7466d3e..d4905b06 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -62,36 +62,76 @@ cpp-options: -DBENCH_containers_Map -DBENCH_containers_IntMap -DBENCH_hashmap_Ma ## Inspecting the generated code -The library section in `unordered-containers.cabal` contains a commented-out set of `ghc-options` for -dumping Core and other forms of generated code. To dump this code, uncomment these options and run +The file `cabal.project.local.dump-code` contains `ghc-options` for dumping Core and +other forms of generated code. To generate these dump files, run ``` +cp cabal.project.local.dump-code cabal.project.local cabal clean -cabal build +cabal build benches tests +``` + +You can find the resulting `.dump-*` files in `dist-newstyle/build/*/*/unordered-containers-*/`, e.g. + +``` +$ tree dist-newstyle/build/*/*/unordered-containers-*/ +dist-newstyle/build/x86_64-linux/ghc-9.12.2/unordered-containers-0.2.20.1/ +├── b +│   ├── fine-grained +│   │   ├── build +│   │   │   └── fine-grained +│   │   │   ├── autogen +│   │   │   │   ├── cabal_macros.h +│   │   │   │   ├── PackageInfo_unordered_containers.hs +│   │   │   │   └── Paths_unordered_containers.hs +│   │   │   ├── fine-grained +│   │   │   └── fine-grained-tmp +│   │   │   ├── benchmarks +│   │   │   │   ├── FineGrained.dump-asm +│   │   │   │   ├── FineGrained.dump-cmm +│   │   │   │   ├── FineGrained.dump-prep +│   │   │   │   ├── FineGrained.dump-simpl +... ``` -You can find the resulting `.dump-*` files in `dist-newstyle/build/**/unordered-containers-*/build/`, e.g. +To visually compare the generated code from two different states of the source tree, +you can copy the `dist-newstyle/build/*/*/unordered-containers-*/` directory from +each state to separate directories and then use a diff tool like +[Meld](https://meldmerge.org/) to compare them: ``` -$ tree dist-newstyle/build/x86_64-linux/ghc-9.2.2/unordered-containers-0.2.16.0/build/ -dist-newstyle/build/x86_64-linux/ghc-9.2.2/unordered-containers-0.2.16.0/build/ -├── Data -│   ├── HashMap -│   │   ├── Internal -│   │   │   ├── Array.dump-asm -│   │   │   ├── Array.dump-cmm -│   │   │   ├── Array.dump-simpl -│   │   │   ├── Array.dump-stg-final -... +cabal clean +cabal build benches tests +mkdir dump-$(git rev-parse HEAD) +cp -r dist-newstyle/build/*/*/unordered-containers-*/ dump-$(git rev-parse HEAD) +# Repeat at different commit +meld dump-* +``` + +Because the files with the generated code are so large, it can be helpful to +temporarily add a small "playground module" to the library: + +In `unordered-containers`: + +```diff +library: + exposed-modules: + ... + Data.HashSet + Data.HashSet.Internal ++ Playground ``` -To visually compare the generated code from two different states of the source tree, you can copy -the `dist-newstyle/build/**/unordered-containers-*/build/` directory from each state to two -directories `a` and `b` and then use a diff tool like [Meld](https://meldmerge.org/) to compare -them: +`Playground.hs`: ``` -meld a/ b/ +{-# language TypeApplications #-} +module Playground where + +import qualified Data.HashMap.Internal as HMI +import qualified Data.HashMap.Strict as HS + +f = HS.union @String ``` ### References diff --git a/cabal.project.local.dump-code b/cabal.project.local.dump-code new file mode 100644 index 00000000..a706625e --- /dev/null +++ b/cabal.project.local.dump-code @@ -0,0 +1,11 @@ +package unordered-containers + ghc-options: -ddump-simpl + ghc-options: -ddump-prep + ghc-options: -ddump-cmm + ghc-options: -ddump-asm + ghc-options: -dsuppress-coercions + ghc-options: -dsuppress-unfoldings + ghc-options: -dsuppress-module-prefixes + ghc-options: -dsuppress-uniques + ghc-options: -dsuppress-timestamps + ghc-options: -ddump-to-file diff --git a/unordered-containers.cabal b/unordered-containers.cabal index 50303153..420f6dba 100644 --- a/unordered-containers.cabal +++ b/unordered-containers.cabal @@ -73,11 +73,6 @@ library ghc-options: -Wall -O2 -fwarn-tabs -ferror-spans - -- For dumping the generated code: - -- ghc-options: -ddump-simpl -ddump-stg-final -ddump-cmm -ddump-asm -ddump-to-file - -- ghc-options: -dsuppress-coercions -dsuppress-unfoldings -dsuppress-module-prefixes - -- ghc-options: -dsuppress-uniques -dsuppress-timestamps - if flag(debug) cpp-options: -DASSERTS From 3122c1e552362741fc418b160331aa8fbfd7b850 Mon Sep 17 00:00:00 2001 From: Simon Jakobi Date: Mon, 1 Dec 2025 20:04:51 +0100 Subject: [PATCH 2/3] Add comment --- cabal.project.local.dump-code | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/cabal.project.local.dump-code b/cabal.project.local.dump-code index a706625e..0d490543 100644 --- a/cabal.project.local.dump-code +++ b/cabal.project.local.dump-code @@ -3,9 +3,12 @@ package unordered-containers ghc-options: -ddump-prep ghc-options: -ddump-cmm ghc-options: -ddump-asm + + ghc-options: -ddump-to-file + + -- Enable or disable as needed: + ghc-options: -dsuppress-timestamps + ghc-options: -dsuppress-module-prefixes ghc-options: -dsuppress-coercions ghc-options: -dsuppress-unfoldings - ghc-options: -dsuppress-module-prefixes ghc-options: -dsuppress-uniques - ghc-options: -dsuppress-timestamps - ghc-options: -ddump-to-file From 629be336c6788846dc25d8ae1396bddbdca069ad Mon Sep 17 00:00:00 2001 From: Simon Jakobi Date: Mon, 1 Dec 2025 20:20:11 +0100 Subject: [PATCH 3/3] Add link --- cabal.project.local.dump-code | 1 + 1 file changed, 1 insertion(+) diff --git a/cabal.project.local.dump-code b/cabal.project.local.dump-code index 0d490543..41255c35 100644 --- a/cabal.project.local.dump-code +++ b/cabal.project.local.dump-code @@ -1,4 +1,5 @@ package unordered-containers + -- https://downloads.haskell.org/ghc/latest/docs/users_guide/debugging.html ghc-options: -ddump-simpl ghc-options: -ddump-prep ghc-options: -ddump-cmm