diff --git a/doc/conda-powershell-troubleshooting.md b/doc/conda-powershell-troubleshooting.md new file mode 100644 index 000000000..144dce874 --- /dev/null +++ b/doc/conda-powershell-troubleshooting.md @@ -0,0 +1,20 @@ +# Conda Powershell Troubleshooting + +For most of the `conda` related documentation in the `robotology-superbuild`, it is assume that the command-line interpreter to use on Windows is the [Command Prompt](https://en.wikipedia.org/wiki/Cmd.exe). + +While Powershell may work in some situations, powershell users may encounter the problems listed in the following. See https://github.com/robotology/robotology-superbuild/issues/890 for the reference issue on supporting Powershell in conda docs. + +## PowerShell and mamba init + +If you want to use `mamba`, note that it is not sufficient to run `mamba init` in PowerShell, as this is not supported: https://github.com/mamba-org/mamba/issues/1088 . + +## PowerShell profiles and ExecutionPolicy problems +If you use PowerShell, note that the `conda init` commands works by creating a [PowerShell profile script](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles). On new Windows machines, the default [Execution Policies](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies) for PowerShell is quite restrictive, and so [it does not permit to profiles to run](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7.1#profiles-and-execution-policy). If that it is the case for you, after you run `conda init` you may get a " cannot be loaded because running scripts is disabled on this system." error whenever you launch PowerShell. To fix this problem, you can just open an Windows Powershell with "Run as administrator", and set the execution policy of your system to allow running profile scripts: +~~~ +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned +~~~ + +## Gazebo and ROS problems with PowerShell + +Some conda packages that are not part of the `robotology` channel, such as [Gazebo](https://github.com/conda-forge/gazebo-feedstock/issues/42) or [ROS](https://github.com/RoboStack/ros-noetic/issues/21)) do not support PowerShell in their activation scripts. If you want to use them, make sure that you use Command Prompt. + diff --git a/doc/install-mambaforge.md b/doc/install-mambaforge.md index 7f23d225b..9153d9f95 100644 --- a/doc/install-mambaforge.md +++ b/doc/install-mambaforge.md @@ -133,6 +133,8 @@ rm -rf ~/.condarc ## Windows +**For all the following instructions, we strongly suggest to use Command Prompt as shell on Windows. If you want to use Powershell, not all the mentioned feature may work, see [conda-powershell-troubleshooting documentation page](conda-powershell-troubleshooting.md) for more info.** + First of all, download the installer from https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-Windows-x86_64.exe and install it by double clicking on it. If you already have a Python that you use in your system, make sure that you deselect the "Register Mambaforge Python as my default Python" during the installation. @@ -165,15 +167,6 @@ To activate in any terminal the `base` environment, just run: mamba activate base ~~~ - -#### PowerShell -If you use PowerShell, note that the `conda init` commands works by creating a [PowerShell profile script](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles). On new Windows machines, the default [Execution Policies](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies) for PowerShell is quite restrictive, and so [it does not permit to profiles to run](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7.1#profiles-and-execution-policy). If that it is the case for you, after you run `conda init` you may get a " cannot be loaded because running scripts is disabled on this system." error whenever you launch PowerShell. To fix this problem, you can just open an Windows Powershell with "Run as administrator", and set the execution policy of your system to allow running profile scripts: -~~~ -Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -~~~ - -As an additional note, while PowerShell is fully supported by robotology conda packages, some external conda packages (such as [Gazebo](https://github.com/conda-forge/gazebo-feedstock/issues/42) or [ROS](https://github.com/RoboStack/ros-noetic/issues/21)) do not support well PowerShell, so if you are using them you may want to consider using Command Prompt. - ### Uninstall First of all, open a command prompt and run: ~~~