From 318f5f34e068077798c7642e2c40e2e177ed9775 Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Mon, 11 Mar 2024 10:37:35 -0700 Subject: [PATCH] src/doc/en/installation/index.rst: Restructure Windows section as decision tree --- src/doc/en/installation/index.rst | 170 +++++++++++++++++------------- 1 file changed, 96 insertions(+), 74 deletions(-) diff --git a/src/doc/en/installation/index.rst b/src/doc/en/installation/index.rst index 849b80851a1..cd8bbe8bf61 100644 --- a/src/doc/en/installation/index.rst +++ b/src/doc/en/installation/index.rst @@ -58,90 +58,47 @@ macOS Windows ======= -Approach 1: Use Visual Studio Code with SageMath dev containers ---------------------------------------------------------------- - -`Visual Studio Code `_ is a popular -and powerful code editor developed by Microsoft and made available -free of charge. We recommmend it because of a key feature, the `Visual -Studio Code Dev Containers extension -`_, which -provides a very convenient way to install and use SageMath running in -a Linux container. - -We recommend this installation method in particular to users who are not already -familiar with Windows Subsystem for Linux. It is also suitable for machines that -cannot run WSL 2 (because of hardware constraints or policy set by system -administrators) but can run Docker. - -Note that although the source code of VS Code is open source (MIT -License), the Dev Containers extension is only known to work with the -Visual Studio Code product, but not with fully open source builds such -as `VSCodium `_. +SageMath does not run natively on Windows. Using SageMath on this +platform requires a virtualization method. Hence, as a first step: - Make sure that hardware-assisted virtualization is enabled in the EFI or BIOS of your system. If in doubt, refer to your system's documentation for instructions on how to do this. -- `Download and install VS Code `_. - -- In VS Code, if the `Visual Studio Code Dev Containers - `_ extension - is not already installed, click the "Extension" icon on the left - (or press :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`X`) to open a list of - extensions. Search for "Dev Containers" and install it. - - The extension will walk you through the installation of Docker - Desktop and activating Windows Subsystem for Linux (WSL 2). - -**Do you want to do SageMath development?** - -- **Yes, development:** - - - In VS Code, `clone - `_ - the `SageMath git repository - `_. For example, use the VS Code - Command Palette (:kbd:`Ctrl` + :kbd:`Shift` + :kbd:`P`), enter the - command "Git: Clone", hit :kbd:`Enter`, paste the URL https://github.com/sagemath/sage - and hit :kbd:`Enter` again. - - - Use the command palette (:kbd:`Ctrl` + :kbd:`Shift` + :kbd:`P`), - enter the command "Dev Containers: Reopen Folder in Container" , and hit :kbd:`Enter`. - - By clicking on "show log", you can see what it does; it will take a while. - - - To use Sage in a terminal, `open a new terminal in VS Code - `_ and type ``./sage``. -- **No development:** +**Are you familiar with or interested in learning about using the Linux command line?** - - Open the folder of a project where you would like to use Sage in VS Code, or - just create a new folder for your work with Sage. +- **Yes, Linux command line:** - - Create a subfolder named ``.devcontainer``. Download this file from the - SageMath GitHub repository and place it in this subfolder: + Then we recommend the method described in section + :ref:`installation-guide-windows-wsl` below. - - https://github.com/sagemath/sage/blob/develop/.devcontainer/downstream-conda-forge-latest/devcontainer.json + This method is also a good choice if you are not interested in using + Visual Studio Code and if you want to have a persistent Sage + installation for use in several projects. - - Use the command palette (:kbd:`Ctrl` + :kbd:`Shift` + :kbd:`P`), - enter the command "Dev Containers: Reopen Folder in Container" , and hit :kbd:`Enter`. +- **No, prefer to use Visual Studio Code:** - By clicking on "show log", you can see what it does; it will take a while. + Then we recommend the method described in section + :ref:`installation-guide-windows-devcontainers` below. - - To use Sage in a terminal, `open a new terminal in VS Code - `_ and type ``sage``. + `Visual Studio Code `_ is a popular + and powerful code editor developed by Microsoft and made available + free of charge. We recommmend it because of a key feature, the `Visual + Studio Code Dev Containers extension + `_, which + provides a very convenient way to install and use SageMath running in + a Linux container. -To use Sage in a Jupyter notebook, click the "Extension" icon on the left (or press -:kbd:`Ctrl` + :kbd:`Shift` + :kbd:`X`) to open a list of -extensions. Install the "Jupyter" extension. In the command -palette, enter "Create: New Jupyter Notebook", and hit -:kbd:`Enter`. Click "Select Kernel" on the right (or press :kbd:`Ctrl` + -:kbd:`Alt` + :kbd:`Enter`), select SageMath, and hit :kbd:`Enter`. + We recommend this installation method in particular to users who are not already + familiar with Windows Subsystem for Linux. It is also suitable for machines that + cannot run WSL 2 (because of hardware constraints or policy set by system + administrators) but can run Docker. +.. _installation-guide-windows-wsl: -Approach 2: Manual installation using Windows Subsystem for Linux ------------------------------------------------------------------ +Installing SageMath in the Windows Subsystem for Linux +------------------------------------------------------ We recommend this installation method in particular to users who are already familiar with Linux or Windows Subsystem for Linux. It is also a good choice if @@ -151,10 +108,6 @@ Enable `Windows Subsystem for Linux (WSL) `_ and install Ubuntu as follows. -- Make sure that hardware-assisted virtualization is enabled in - the EFI or BIOS of your system. If in doubt, refer to your - system's documentation for instructions on how to do this. - - `Run the WSL install command as administrator. `_ This will install Ubuntu Linux. @@ -181,7 +134,7 @@ Start Ubuntu from the Start menu. - **Yes, development:** - Then follow the instructions for development on Linux below. + Then follow the :ref:`instructions for development on Linux ` below. - **No development:** @@ -208,6 +161,75 @@ To use Sage in a Jupyter notebook, it is convenient to use Visual Studio Code. See :ref:`sec-launching-vscode-wsl`. +.. _installation-guide-windows-devcontainers: + +Using Visual Studio Code with SageMath dev containers +----------------------------------------------------- + +- `Download and install VS Code `_. + + .. note:: + + Although the source code of VS Code is open source (MIT + License), the Dev Containers extension is only known to work with the + Visual Studio Code product, but not with fully open source builds such + as `VSCodium `_. + +- In VS Code, if the `Visual Studio Code Dev Containers + `_ extension + is not already installed, click the "Extension" icon on the left + (or press :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`X`) to open a list of + extensions. Search for "Dev Containers" and install it. + + The extension will walk you through the installation of Docker + Desktop and activating Windows Subsystem for Linux (WSL 2). + +**Do you want to do SageMath development?** + +- **Yes, development:** + + - In VS Code, `clone + `_ + the `SageMath git repository + `_. For example, use the VS Code + Command Palette (:kbd:`Ctrl` + :kbd:`Shift` + :kbd:`P`), enter the + command "Git: Clone", hit :kbd:`Enter`, paste the URL https://github.com/sagemath/sage + and hit :kbd:`Enter` again. + + - Use the command palette (:kbd:`Ctrl` + :kbd:`Shift` + :kbd:`P`), + enter the command "Dev Containers: Reopen Folder in Container" , and hit :kbd:`Enter`. + + By clicking on "show log", you can see what it does; it will take a while. + + - To use Sage in a terminal, `open a new terminal in VS Code + `_ and type ``./sage``. + +- **No development:** + + - Open the folder of a project where you would like to use Sage in VS Code, or + just create a new folder for your work with Sage. + + - Create a subfolder named ``.devcontainer``. Download this file from the + SageMath GitHub repository and place it in this subfolder: + + - https://github.com/sagemath/sage/blob/develop/.devcontainer/downstream-conda-forge-latest/devcontainer.json + + - Use the command palette (:kbd:`Ctrl` + :kbd:`Shift` + :kbd:`P`), + enter the command "Dev Containers: Reopen Folder in Container" , and hit :kbd:`Enter`. + + By clicking on "show log", you can see what it does; it will take a while. + + - To use Sage in a terminal, `open a new terminal in VS Code + `_ and type ``sage``. + +To use Sage in a Jupyter notebook, click the "Extension" icon on the left (or press +:kbd:`Ctrl` + :kbd:`Shift` + :kbd:`X`) to open a list of +extensions. Install the "Jupyter" extension. In the command +palette, enter "Create: New Jupyter Notebook", and hit +:kbd:`Enter`. Click "Select Kernel" on the right (or press :kbd:`Ctrl` + +:kbd:`Alt` + :kbd:`Enter`), select SageMath, and hit :kbd:`Enter`. + + .. _installation-guide-linux: Linux