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..41255c35 --- /dev/null +++ b/cabal.project.local.dump-code @@ -0,0 +1,15 @@ +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 + 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-uniques 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