diff --git a/CHANGELOG.md b/CHANGELOG.md index 535c7d2..45be77b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,22 +1,80 @@ # Changelog -`dr-cabal` uses [PVP Versioning][1]. -The changelog is available [on GitHub][2]. +All notable changes to this project will be documented in this file. -## 0.1.0.0 — August 6, 2022 📚 +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [PVP Versioning][1]. The changelog is also +available [on GitHub][2]. + +[1]: https://pvp.haskell.org +[2]: https://github.com/chshersh/dr-cabal/releases + +## [Unreleased] + +## [0.2.0.0] — 2022-11-20 ✨ + +### Added + +* [#28](https://github.com/chshersh/dr-cabal/issues/28): + Implement interactive mode + (by [@Bodigrim][Bodigrim]) +* [#24](https://github.com/chshersh/dr-cabal/issues/24): + Compute the critical path + (by [@Bodigrim][Bodigrim]) +* [#26](https://github.com/chshersh/dr-cabal/issues/26), + [#30](https://github.com/chshersh/dr-cabal/issues/30): + Multiple documentation improvements: suggest `--store-dir`, + `--dependencies-only`, `mktemp`, interactive mode by default + (by [@Bodigrim][Bodigrim], [@chshersh][chshersh]) + +### Removed + +* Remove `watch` command. Now `dr-cabal profile` can watch and build + the profiling output at the same time. + +### Changed + +* [#31](https://github.com/chshersh/dr-cabal/issues/31): + Refactor CLI significantly: + + + Remove `watch` command + + Use interactive mode by default (via alternate terminal screen) + + (by [@chshersh][chshersh]) + +## [0.1.0.0] — 2022-08-06 📚 + +### Added * [#10](https://github.com/chshersh/dr-cabal/issues/10): Support `Haddock` phase in `cabal build` output - (by [@diasbruno](https://github.com/diasbruno)) + (by [@diasbruno][diasbruno]) * [#14](https://github.com/chshersh/dr-cabal/issues/14): Enrich _Summary_ with more info: parallelism level, total dependencies summary - (by [@bradrn](https://github.com/bradrn)) + (by [@bradrn][bradrn]) * Module structure refactoring to add new profiling modes easier - (by [@diasbruno](https://github.com/diasbruno)) + (by [@diasbruno][diasbruno]) -## 0.0.0.0 — July 31, 2022 🌇 +### Fixed -* Initially created. +* Fixed type in the profile example + (by [@tonyday567][tonyday567]) -[1]: https://pvp.haskell.org -[2]: https://github.com/chshersh/dr-cabal/releases +## [0.0.0.0] — 2022-07-31 🌇 + +Initial release prepared by [@chshersh][chshersh]. + + + +[Bodigrim]: https://github.com/Bodigrim +[bradrn]: https://github.com/bradrn +[chshersh]: https://github.com/chshersh +[diasbruno]: https://github.com/diasbruno +[tonyday567]: https://github.com/tonyday567 + + + +[Unreleased]: https://github.com/chshersh/dr-cabal/compare/v0.2.0.0...HEAD +[0.2.0.0]: https://github.com/chshersh/dr-cabal/compare/v0.1.0.0...v0.2.0.0 +[0.1.0.0]: https://github.com/chshersh/dr-cabal/compare/v0.0.0.0...v0.1.0.0 +[0.0.0.0]: https://github.com/chshersh/dr-cabal/releases/tag/v0.0.0.0 diff --git a/README.md b/README.md index 49f1ad3..9775222 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ `dr-cabal` is a CLI tool for profiling Haskell dependencies build times. -![dr-cabal example](https://raw.githubusercontent.com/chshersh/dr-cabal/main/images/dr-cabal-example.png) +![dr-cabal demo](https://raw.githubusercontent.com/chshersh/dr-cabal/main/images/dr-cabal-demo.gif) > ℹī¸ **DISCLAIMER:** This project is developed and maintained in > free time by volunteers. The development may continue for decades or @@ -16,8 +16,8 @@ ## Install -`dr-cabal` is a Haskell CLI tool and can be installed either from -Hackage or from this repository. +`dr-cabal` is a CLI tool written in Haskell and can be installed +either from Hackage or from this repository. ### Prerequisites @@ -41,13 +41,12 @@ follow these steps: ``` 2. Build `dr-cabal` from Hackage and copy the resulting executable - into the desired location: + into the desired location (e.g. `$HOME/.local/bin`): ```shell cabal install dr-cabal \ --install-method=copy \ --overwrite-policy=always \ - --with-compiler=ghc-9.0.2 \ --installdir=$HOME/.local/bin ``` @@ -81,53 +80,59 @@ follow these steps: > ℹī¸ **NOTE:** Make sure the `~/.local/bin` directory or the > directory of your choice is listed in `$PATH`. -## How to use? +## Quick start guide -`dr-cabal` usages comprises two steps: +Run the following command to view interactive profiling report: -1. 👀 Watching `cabal build` output and recording data into a JSON file. -2. 🌈 Producing pretty profiling results. - -### Watch +```shell +cabal --store-dir=$(mktemp -d) build --dependencies-only all | dr-cabal profile +``` -> ⚠ī¸ **WARNING:** To get meaningful results, the `dr-cabal watch` -> command needs to be run when none of the dependencies are build. If -> you've already build you project, including dependencies, you can -> purge global Cabal cache using the following command: +### Explanation + +This section explains the above command: + +1. `dr-cabal` watches the output of the `cabal build` command to + produce the profiling report. Step into the directory of the + Haskell project you want to profile and pipe the output of + `cabal build` to `dr-cabal profile`. +2. Currently, `dr-cabal` can profile only dependencies. So you can + pass the `--dependencies-only` to avoid extra wait. +3. `cabal` caches built dependencies. You can specify a custom + directory for storing build artifacts using the `--store-dir` flag + to build the dependencies anew. +4. The `$(mktemp -d)` command generates a temporary directory so you + can run the build time profiler in an isolated location. + +> ⚠ī¸ **WARNING:** To get meaningful results, including downloading +> of packages, the `dr-cabal watch` command needs to be run when +> none of the dependencies are build (i.e. with cold cabal +> cache). If you've already build you project, including +> dependencies, you can purge global Cabal cache using the +> following command: > > ```shell > rm -rf ~/.cabal > ``` -> -> A less invasive approach is to point Cabal to a fresh store folder, -> but in this case you won't see the `Downloading` phase in the profiling -> output: -> -> ```shell -> cabal --store-dir=$(mktemp -d) build all -> ``` -Run the following command inside the project directory, for which you -want to build the profile chart: +## Usage -```shell -cabal build all | dr-cabal watch --output=dr-cabal-debug.json -``` +> ℹī¸ In this section, a more verbose `cabal-install` command from +> "Quick start guide" is replaced with shorter `cabal build`. -This command watches the `cabal build` output and records all the -relevant steps in the `dr-cabal-debug.json` file. +`dr-cabal` supports profiling of documentation as well, you only need +to pass relevant flags to `cabal build`: -If everything is good, you should see output similar to the below one: - -![dr-cabal watch example](https://raw.githubusercontent.com/chshersh/dr-cabal/main/images/dr-cabal-watch.gif) +```shell +cabal build --enable-documentation --haddock-all | dr-cabal profile +``` -> It's also possible to see the time spent on Haddock. You can run with: -> -> ```shell -> cabal build all --enable-documentation --haddock-all | dr-cabal watch --output=dr-cabal-debug.json -> ``` +To cache the profiling results in JSON (and avoid building the project +again), use the `--output` flag: -### Profile +```shell +cabal build | dr-cabal profile --output=my_file.json +``` Once you successfully produced a JSON file with all the recorded steps, run the following command to pretty-print the profiling output: @@ -135,7 +140,7 @@ steps, run the following command to pretty-print the profiling output: > ⚠ī¸ **WARNING:** For better results, make your terminal full-screen. ```shell -dr-cabal profile --input=dr-cabal-debug.json +dr-cabal profile --input=my_file.json ``` You'll see the output like on the image below: diff --git a/dr-cabal.cabal b/dr-cabal.cabal index 94d2c02..4a4ca97 100644 --- a/dr-cabal.cabal +++ b/dr-cabal.cabal @@ -1,6 +1,6 @@ cabal-version: 3.0 name: dr-cabal -version: 0.1.0.0 +version: 0.2.0.0 synopsis: See README for more info description: CLI tool for profiling Haskell dependencies build times. diff --git a/images/dr-cabal-demo.gif b/images/dr-cabal-demo.gif new file mode 100644 index 0000000..d5eafac Binary files /dev/null and b/images/dr-cabal-demo.gif differ diff --git a/images/dr-cabal-example.png b/images/dr-cabal-example.png deleted file mode 100644 index d723011..0000000 Binary files a/images/dr-cabal-example.png and /dev/null differ diff --git a/images/dr-cabal-itself.png b/images/dr-cabal-itself.png index 9d079de..62fafd0 100644 Binary files a/images/dr-cabal-itself.png and b/images/dr-cabal-itself.png differ diff --git a/images/dr-cabal-watch.gif b/images/dr-cabal-watch.gif deleted file mode 100644 index 422c64c..0000000 Binary files a/images/dr-cabal-watch.gif and /dev/null differ