From 111a113bd8b23395dcbeb30de519634f4b9aa0a0 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Tue, 6 Feb 2024 17:58:23 +0100 Subject: [PATCH] add tips for advanced debugging (#752) * add tips for advanced debugging * some syntax fixes * merge with CLI options page * Apply suggestions from code review Co-authored-by: Bianca Henderson * Apply suggestions from code review Co-authored-by: Bianca Henderson --------- Co-authored-by: Bianca Henderson --- docs/source/cli-options.md | 72 ++++++++++++++++++++++++++++++++------ docs/source/debugging.md | 67 +++++++++++++++++++++++++++++++++++ news/752-debugging | 19 ++++++++++ 3 files changed, 148 insertions(+), 10 deletions(-) create mode 100644 docs/source/debugging.md create mode 100644 news/752-debugging diff --git a/docs/source/cli-options.md b/docs/source/cli-options.md index cc3466518..49b466674 100644 --- a/docs/source/cli-options.md +++ b/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,6 +101,36 @@ 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` @@ -88,6 +138,8 @@ 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`. diff --git a/docs/source/debugging.md b/docs/source/debugging.md new file mode 100644 index 000000000..c9ad88481 --- /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 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 ⌘+L. 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. diff --git a/news/752-debugging b/news/752-debugging new file mode 100644 index 000000000..669898a1d --- /dev/null +++ b/news/752-debugging @@ -0,0 +1,19 @@ +### Enhancements + +* + +### Bug fixes + +* + +### Deprecations + +* + +### Docs + +* Add some tips for debugging the creation and execution of `constructor`-made installers. (#752) + +### Other + +*