Merge #837 Readme: add profiling info, overall update

Author: Anton-Latukha

ReadMe.md

@@ -49,22 +49,26 @@ Parser, evaluator and type checker for the Nix language written in Haskell.
 ## Prerequisites
 Tooling is WIP, `nix-shell` and `nix-store` are still used for their purpose, so, to access them Nix is required to be installed.
 
-*Disclaimer*: Current `derivationStrict` primOp implementation and so every evaluation of a derivation into a store path currently relies on the `hnix-store-remote`, which for those operations relies on the running `nix-daemon`, and so operations use/produce effects into the `/nix/store`. Be cautious - it is effectful.
+*Disclaimer*: Since still using Nix for some operations, current `derivationStrict` primOp implementation and so evaluations of a derivation into a store path currently rely on the `hnix-store-remote`, which for those operations relies on the running `nix-daemon`, and so operations use/produce effects into the `/nix/store`. Be cautious - it is effectful (produces `/nix/store` entries).
 
 ## Getting Started
 
+### Git clone
+
 ```shell
-# Note: --recursive
-git clone --recursive 'https://github.com/haskell-nix/hnix.git'
-cd hnix
+git clone --recursive 'https://github.com/haskell-nix/hnix.git' && cd hnix
 ```
 
 
-### Cachix prebuild binary caches
+### (optional) Cachix prebuild binary caches
+
+If you would use our Nix-shell environment for development, you can connect to our Cachix HNix build caches:
 
-If you opt in to use of Nix environment, please enable the official HNix Cachix binary cache:
+1. Run:
+    ```shell
+    nix-env -iA cachix -f https://cachix.org/api/v1/install
+    ```
 
-1. Go through https://cachix.org/ and set it up.
 
 2. Run: `cachix use hnix`
 
@@ -74,37 +78,37 @@ If you opt in to use of Nix environment, please enable the official HNix Cachix
 Cabal [Quickstart](https://cabal.readthedocs.io/en/3.4/nix-local-build.html).
 
 1. (Optional), to enter the projects reproducible Nix environment:
-```shell
-nix-shell
-```
-  
+    ```shell
+    nix-shell
+    ```
+    
 2. Building:
-```shell
-cabal v2-configure
-cabal v2-build
-```
-
+    ```shell
+    cabal v2-configure
+    cabal v2-build
+    ```
+  
 3. Loading the project into `ghci` REPL:
-```shell
-cabal v2-repl
-```
-
+    ```shell
+    cabal v2-repl
+    ```
+    
 4. Testing:
 
-* Default suite:
-```shell
-cabal v2-test
-```
-
-* All available tests:
-```shell
-env ALL_TESTS=yes cabal v2-test
-```
-
-* Selected (list of tests is in `tests/Main.hs`):
-```shell
-env NIXPKGS_TESTS=yes PRETTY_TESTS=1 cabal v2-test
-```
+  * Default suite:
+    ```shell
+    cabal v2-test
+    ```
+  
+  * All available tests:
+    ```shell
+    env ALL_TESTS=yes cabal v2-test
+    ```
+    
+  * Selected (list of tests is in `tests/Main.hs`):
+    ```shell
+    env NIXPKGS_TESTS=yes PRETTY_TESTS=1 cabal v2-test
+    ```
 
 #### Checking the project
 
@@ -123,10 +127,23 @@ GHC User Manual has a full ["Profiling"](https://ghc.gitlab.haskell.org/ghc/doc/
 To build `hnix` with profiling enabled:
 
 ```shell
-cabal v2-configure --enable-tests --enable-profiling --flags=profiling
-cabal v2-run hnix -- <args> +RTS -p
+cabal v2-run hnix --enable-profiling --flags=profiling -- <args> +RTS -p
+```
+
+Or to put simply:
+```shell
+# Run profiling for evaluation of a Firefox package.
+# Generate:
+#  * for all functions
+#  * time profiling data
+#  * memory allocation profiling data
+#  * in the JSON profiling format
+cabal v2-run --enable-profiling --flags=profiling --enable-library-profiling --profiling-detail='all-functions' hnix -- --eval --expr '(import <nixpkgs> {}).firefox.outPath' +RTS -Pj
+
+# Then, upload the `hnix.prof` to the https://www.speedscope.app/ to analyze it.
 ```
-where "RTS" stands for "RunTime System" and has a lot of options, GHC User Manual has ["Running a compiled program"/"Setting RTS options"](https://ghc.gitlab.haskell.org/ghc/doc/users_guide/runtime_control.html) sections describing them.
+
+"RTS" stands for "RunTime System" and has a lot of options, GHC User Manual has ["Running a compiled program"/"Setting RTS options"](https://ghc.gitlab.haskell.org/ghc/doc/users_guide/runtime_control.html) sections describing them.
 
 ##### Full debug info
 
@@ -267,7 +284,7 @@ hnix --reduce bug.nix --eval --expr 'import <nixpkgs> {}'
 
 ### REPL
 
-Ot enter REPL:
+To enter REPL:
 ```shell
 hnix --repl
 ```
@@ -306,26 +323,30 @@ hnix \
 
 ## Contributing
 
-There is a Wiki article: [Design of the HNix code base](https://github.com/haskell-nix/hnix/wiki/Design-of-the-HNix-code-base).
+* The Haskell Language Server (HLS) works great with our project.
 
-Haskell Language Server & Cabal development. Or development in the Nix shell environment.
+* [Design of the HNix code base Wiki article](https://github.com/haskell-nix/hnix/wiki/Design-of-the-HNix-code-base).
 
 1. If something in the [quests](https://github.com/haskell-nix/hnix/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22+no%3Aassignee) looks interesting, look through the thread and leave a comment taking it, to let others know you're working on it.
 
 2. You are free to chat with everyone on [Gitter](https://gitter.im/haskell-nix/Lobby).
 
 3. When the pull request is ready to be submitted, to save time - please, test it with:
-
-```shell
-git submodule update --init --recursive
-cabal v2-test
-```
-
-Please, check that all default tests that were passing prior are still passing for the PR, it is faster to check that locally than through CI. It's OK if no new tests are passing.
-
-
+    
+    ```shell
+    cabal v2-test
+    
+    # If forgot to clone recursively, run:
+    # git submodule update --init --recursive
+    ```
+    
+    Please, check that all default tests that were passing prior are still passing. It's OK if no new tests are passing.
+    
+    
 ### (optional) Minimalistic development status loop with amazing [`ghcid`](https://github.com/ndmitchell/ghcid)
 
+If HLS is not your cup of yea:
+
 ```shell
 ghcid --command="cabal v2-repl --repl-options=-fno-code --repl-options=-fno-break-on-exception --repl-options=-fno-break-on-error --repl-options=-v1 --repl-options=-ferror-spans --repl-options=-j"
 ```