add tips for advanced debugging

docs/source/cli-options.md

@@ -2,6 +2,12 @@
 
 The are the command-line flags available in the installers generated by constructor.
 
+:::{admonition} Configure conda's verbosity
+:class: tip
+
+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`.
+:::
+
 ## Shell-based installers for MacOS and Linux
 
 We have the following CLI options available for MacOS and Linux:
@@ -32,22 +38,36 @@ Run the installer in batch mode and install to a custom path:
 $ bash my_installer.sh -b -p /opt/my_app
 ```
 
+:::{admonition} Extra verbosity
+:class: tip
+
+Get more verbose outputs by running the installer with `-x` and/or `CONDA_VERBOSITY=3`:
+
+```bash
+$ bash -x my_installer.sh
+# or with verbose conda:
+$ CONDA_VERBOSITY=3 bash -x my_installer.sh
+```
+:::
 
 ## Windows installers
 
 Windows installers have the following CLI options available:
 
 - `/InstallationType=[JustMe|AllUsers]`: This flag sets the installation type. The default is
-`JustMe`. `AllUsers` might require elevated privileges. - `/AddToPath=[0|1]`: Whether to add the
-installation directory to the `PATH` environment variable. The default is `0`. This is NOT
-recommended. - `/CheckPathLength=[0|1]`: Check whether the installation path is too long (>46
-characters). The default depends on how the installer was created. - `/KeepPkgCache=[0|1]`: Whether
-to keep the package cache or not. Defaults to `1`. - `/NoRegistry=[0|1]`: Whether to prevent
-registry modification or not. Defaults to `0`. - `/NoScripts=[0|1]`: If set to `1`, the installer
-will not run any post-install scripts. Defaults to `0`. - `/NoShortcuts=[0|1]`: If set to `1`, the
-installer will not create any shortcuts. Defaults to `0`. - `/RegisterPython=[0|1]`: Whether to
-register Python as default in the Windows registry. Defaults to `1`. This is preferred to
-`AddToPath`.
+  `JustMe`. `AllUsers` might require elevated privileges.
+- `/AddToPath=[0|1]`: Whether to add the installation directory to the `PATH` environment
+  variable. The default is `0`. This is NOT recommended.
+- `/CheckPathLength=[0|1]`: Check whether the installation path is too long (>46
+  characters). The default depends on how the installer was created.
+- `/KeepPkgCache=[0|1]`: Whether to keep the package cache or not. Defaults to `1`.
+- `/NoRegistry=[0|1]`: Whether to prevent registry modification or not. Defaults to `0`.
+- `/NoScripts=[0|1]`: If set to `1`, the installer will not run any post-install scripts. Defaults
+  to `0`.
+- `/NoShortcuts=[0|1]`: If set to `1`, the installer will not create any shortcuts. Defaults to
+  `0`.
+- `/RegisterPython=[0|1]`: Whether to register Python as default in the Windows registry. Defaults
+  to `1`. This is preferred to `AddToPath`.
 
 You can also supply [standard NSIS flags](https://nsis.sourceforge.io/Docs/Chapter3.html#installerusage), but only _after_ the ones mentioned above:
 
@@ -81,13 +101,45 @@ Run the uninstaller in silent mode from its original location:
 > cmd.exe /c start /wait "C:\Program Files\my_app\uninstaller.exe" /S _?=C:\Program Files\my_app
 ```
 
+:::{admonition} EXE installers with file logging
+:class: tip
+
+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).
+
+There's a way of building EXE installers that can 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 after 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.
+
+Combine this with `CONDA_VERBOSITY=3` at install time for maximum details:
+
+
+```batch
+> set "CONDA_VERBOSITY=3"
+> cmd.exe /c start /wait your-installer.exe
+```
+:::
+
 ## PKG installers
 
 The PKG installers do not offer any CLI options. Instead, you need to use the `installer`
 subcommand:
 
 ```bash
 $ installer -pkg my_installer.pkg -dumplog -target CurrentUserHomeDirectory
+# with extra verbosity from conda
+$ CONDA_VERBOSITY=3 installer -pkg my_installer.pkg -dumplog -target CurrentUserHomeDirectory
 ```
 
 Note you can't choose a custom path for the installation. Instead, you can only choose a `target`.

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 simply shell scripts that invoke `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"
+> cmd.exe /c start /wait your-installer.exe
+```
+
+### Building logging-enabled EXE installers
+
+There's a way of building EXE installers that can 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 after setting a special environment variable:
+
+```batch
+> set "NSIS_USING_LOG_BUILD=1"
+> cmd.exe /c start /wait 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.

news/752-debugging

@@ -0,0 +1,19 @@
+### Enhancements
+
+* <news item>
+
+### Bug fixes
+
+* <news item>
+
+### Deprecations
+
+* <news item>
+
+### Docs
+
+* Add some tips for debugging the creation and execution of `constructor`-made installers. (#752)
+
+### Other
+
+* <news item>