From 85fecaaf744a27058b2c570fecb8cbd05e8fd88a Mon Sep 17 00:00:00 2001
From: jaimergp <jaimergp@users.noreply.github.com>
Date: Mon, 29 Jan 2024 15:27:29 +0100
Subject: [PATCH] add tips for advanced debugging

---
 docs/source/debugging.md | 67 ++++++++++++++++++++++++++++++++++++++++
 docs/source/index.md     |  1 +
 2 files changed, 68 insertions(+)
 create mode 100644 docs/source/debugging.md

diff --git a/docs/source/debugging.md b/docs/source/debugging.md
new file mode 100644
index 000000000..2eb704860
--- /dev/null
+++ b/docs/source/debugging.md
@@ -0,0 +1,67 @@
+# Debugging tips
+
+Sometimes `constructor` fails to build the requested installer. Sometimes the installer builds, but
+there are errors when it is run in the target machine.
+
+In this section we will talk about different techniques you can use to find out was wrong with your installers.
+
+## Run `constructor` in debug mode
+
+When you run `constructor`, `conda` is called behind the scenes to solve the requested specs. You can enable advanced logging using the flags `-v` or `--debug`. These will be passed to `conda`. Be prepared for _a lot_ of output!
+
+
+## Verbose `conda`
+
+Whether it's while running `constructor` to build an installer, or while the installer is running in the target machine, some instance of `conda` will be running behind the scenes. You can request more verbose output via the `CONDA_VERBOSITY` environment variable. It can take values from `1` to `4`. You can also set `CONDA_DEBUG` to `1`.
+
+
+## Verbose shell installers
+
+The shell installers are "just" a shell script that invokes `conda` in certain events. This means you can enable `bash` verbosity via the `-x` flag:
+
+```bash
+bash -x ./Miniconda.sh
+# or with verbose conda:
+CONDA_VERBOSITY=3 bash -x ./Miniconda.sh
+```
+
+## Verbose PKG installers
+
+PKG installers are usually invoked graphically. You can check the native logs via <kbd>⌘</kbd>+<kbd>L</kbd>. Note that you will need to choose the detailed view in the dropdown menu you'll find in the top right corner.
+
+In order to get more verbosity out of conda, you now know you need the `CONDA_VERBOSITY` variable. However, it needs to be set up _before_ running the installer. One way from the command line would be:
+
+```bash
+CONDA_VERBOSITY=3 installer -pkg ./path/to/installer.pkg -target LocalSystem
+```
+
+See `man installer` for more details.
+
+## Verbose EXE installers
+
+Windows installers do not have a verbose mode. By default, the graphical logs are only available in the "progress bar" dialog, by clicking on "Show details". This text box is right-clickable, which will allow you to copy the contents to the clipboard (and then paste them in a text file, presumably).
+
+If you want `conda` to print more details, then, run it from the CMD prompt like this:
+
+```batch
+set "CONDA_VERBOSITY=3"
+start /wait your-installer.exe
+```
+
+### Building logging-enabled EXE installers
+
+There's a way of building EXE installers that do write logs to a file. For this, you need a special `nsis` package configured to do so:
+
+```batch
+conda install "nsis=*=*log*"
+```
+
+Then, you can invoke `constructor` normally, but setting a special environment variable:
+
+```batch
+set "NSIS_USING_LOG_BUILD=1"
+constructor .
+```
+
+The resulting EXE installer will always generate an `install.log` file in the target directory.
+It will contain the full logs, as available in the "Show details" dialog.
diff --git a/docs/source/index.md b/docs/source/index.md
index d3586a53b..9c909768b 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -11,4 +11,5 @@ getting-started
 howto
 construct-yaml
 cli-options
+debugging
 ```