Installation guide: Document Sage installation on Windows via VS Code devcontainers

[mkoeppe]

Based on #33671.

The new documentation:
https://github.com/sagemath/sagetrac-mirror/blob/u/mkoeppe/installation_guide__document_sage_installation_on_windows_via_vs_code_devcontainers/src/doc/en/installation/index.rst#windows

Depends on #33671
Depends on #34301

CC: @tscrim @kwankyu @slel @darijgr @tobiasdiez @saraedum @williamstein @DavidAyotte

Component: documentation

Author: Matthias Koeppe

Issue created by migration from https://trac.sagemath.org/ticket/34363

[mkoeppe]

Branch: u/mkoeppe/installation_guide__document_sage_installation_on_windows_via_vs_code_devcontainers

[mkoeppe]

Author: Matthias Koeppe

[mkoeppe]

Last 10 new commits:

c5d883c	src/doc/en/developer/portability_testing.rst: Explain the devcontainer name prefix downstream-docker-...
3016ce9	build/bin/sage-print-system-package-command (conda): Actually include options in command
84a5e13	.devcontainer/downstream-conda-forge-latest/devcontainer.json: Do not use .devcontainer/post_create.sh
193174b	Merge #33671
393808c	src/doc/en/installation/binary.rst: No more cygwin binaries
fe98ca1	README.md, src/doc/en/installation: Move all Cygwin instructions to one section of the installation manual
550b337	README.md, src/doc/en/installation/index.rst: Remove mention of Cygwin
e3af6c9	src/doc/en/installation/index.rst: Fix markup
0bd4f7f	Merge #34301
1ca0876	src/doc/en/installation/index.rst, README.md [Windows]: Recommend VS Code devcontainers

[mkoeppe]

Commit: 1ca0876

[sagetrac-git]

Changed commit from 1ca0876 to b442a41

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

945de29	.devcontainer: Reduce parallelism to 4
b29dfa7	.devcontainer/downstream-docker-sagemath: Remove
b442a41	Merge #33671

[DavidAyotte]

comment:8

Suggestion: in the alternative installation, I think I would mention that you can also use vscode, but now with extension Remote - WSL which lets you use vscode inside your WSL environment (but this is not mandatory, as someone might want to use an other code editor).

Next, I have a question: is there any performance advantages in using docker containers instead of directly running it inside WSL?

Thank you very much for simplifying the installation tutorial!

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

8231674

src/doc/en/installation/index.rst (Windows WSL): Link to launching section for VS Code Jupyter

[sagetrac-git]

Changed commit from b442a41 to 8231674

[mkoeppe]

comment:11

Replying to @DavidAyotte:

Suggestion: in the alternative installation, I think I would mention that you can also use vscode, but now with extension Remote - WSL which lets you use vscode inside your WSL environment (but this is not mandatory, as someone might want to use an other code editor).

Thanks for the feedback!

We already have a section in the manual that explains this. I've linked it.

[mkoeppe]

comment:12

Replying to @DavidAyotte:

is there any performance advantages in using docker containers instead of directly running it inside WSL?

I would think it's the same as running WSL 2 directly

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

b09e6d1	.devcontainer/downstream-archlinux-latest/devcontainer.json: Remove a 'prefix' symlink if present
f99f09f	.devcontainer/downstream-archlinux-latest/devcontainer.json: No need to bootstrap
b72ff17	Refinements for downstream-archlinux-latest
9215621	Copy instructions for downstream-conda-latest
de05f69	Copy instructions for downstream-*
43abc57	.devcontainer/develop-docker-cocalc, portability-centos-7-devtoolset-gcc_11-standard: Remove
06610b8	Merge #33671

[sagetrac-git]

Changed commit from 8231674 to 06610b8

[tobiasdiez]

comment:14

Replying to @mkoeppe:

Replying to @DavidAyotte:

is there any performance advantages in using docker containers instead of directly running it inside WSL?

I would think it's the same as running WSL 2 directly

In general, Docker is slower (for both io and cpu) then WSL2. How much depends on the particular use case and the setup (e.g. whether the files are located in the windows or linux env).

[tobiasdiez]

comment:15

In general, I'm skeptical if the devcontainer env should be indeed the recommended installation and development method on windows.

For installation, it is not clear to me how you would use the "installed" devcontainer in your own projects (i.e. outside of the vscode instance that hosts the sage source tree). For this, wouldn't it make more sense to recommend that people create a devcontainer file in their own project folder, that references a prebuild sage devcontainer?

For development, I would still favor wsl over docker for the performance. Moreover, I don't see why this should be a windows-specific recommendation in either case.

[mkoeppe]

comment:16

Replying to @tobiasdiez:

Replying to @mkoeppe:

Replying to @DavidAyotte:

is there any performance advantages in using docker containers instead of directly running it inside WSL?

I would think it's the same as running WSL 2 directly

In general, Docker is slower (for both io and cpu) then WSL2. How much depends on the particular use case and the setup (e.g. whether the files are located in the windows or linux env).

Even when using Docker's WSL2 backend?

[mkoeppe]

comment:17

Replying to @tobiasdiez:

I don't see why this should be a windows-specific recommendation in either case.

Because on macOS and Linux, it is better to run it natively

[mkoeppe]

comment:18

Replying to @tobiasdiez:

For installation, it is not clear to me how you would use the "installed" devcontainer in your own projects (i.e. outside of the vscode instance that hosts the sage source tree). For this, wouldn't it make more sense to recommend that people create a devcontainer file in their own project folder, that references a prebuild sage devcontainer?

Yes, it would also make sense to do that (not instead, but in addition to what is done here). We have a bit of this already in the "portability testing" section added in #33671; see also #34286 (Cookiecutter for Sage user projects with devcontainer).

[sagetrac-git]

Changed commit from 06610b8 to dd5724e

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

dd5724e

.devcontainer/post_create.sh: Install bootstrapping prerequisites

[sagetrac-git]

Changed commit from dd5724e to 5097583

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

bad3c16	.devcontainer/post_create.sh: Install bootstrapping prerequisites
5097583	Merge #33671

[tobiasdiez]

comment:21

Replying to @mkoeppe:

Replying to @tobiasdiez:

For installation, it is not clear to me how you would use the "installed" devcontainer in your own projects (i.e. outside of the vscode instance that hosts the sage source tree). For this, wouldn't it make more sense to recommend that people create a devcontainer file in their own project folder, that references a prebuild sage devcontainer?

Yes, it would also make sense to do that (not instead, but in addition to what is done here). We have a bit of this already in the "portability testing" section added in #33671; see also #34286 (Cookiecutter for Sage user projects with devcontainer).

Can you then please explain and document how to use the sage installation (in the devcontainer) in one's own projects. For example, it is not clear to me how to select the sage python interpreter or juptyer kernel in another instance of vscode.

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

8aa2cc4

src/doc/en/installation/index.rst (Windows): Change from Recommended/Alternative to Recommended 1/2

[kwankyu]

comment:36

The doc structure could be, as for other platforms,

   No development:

       Alternative 1:

       Alternative 2:

   Development:

       Alternative 1:

       Alternative 2:

We may put the recommended in alternative 1."No development alternative 1" would be the recommended approach for most users.

I would put "VS Code + downstream-devcontainer" approach to "No development alternative 1".

I would put "VS Code + WSL" approach to "Development alternative 1". Docker is really not necessary in sage development and conceptually more difficult than WSL, I think.

For "VS Code + downstream-devcontainer" approach, could we remove the git clone part (which is just to get devcontainer.json)?

[kwankyu]

comment:37

Replying to @kwankyu:

For "VS Code + downstream-devcontainer" approach, could we remove the git clone part (which is just to get devcontainer.json)?

Providing a zipped folder with ./devcontainer/devcontainer.json for download?

[mkoeppe]

comment:38

Replying to @kwankyu:

Replying to @kwankyu:

For "VS Code + downstream-devcontainer" approach, could we remove the git clone part (which is just to get devcontainer.json)?

Providing a zipped folder with ./devcontainer/devcontainer.json for download?

I would like to keep such things for a follow-up ticket (#34286)

[tobiasdiez]

comment:39

Replying to @mkoeppe:

Replying to @tobiasdiez:

Replying to @mkoeppe:

Replying to @tobiasdiez:

For installation, it is not clear to me how you would use the "installed" devcontainer in your own projects (i.e. outside of the vscode instance that hosts the sage source tree). For this, wouldn't it make more sense to recommend that people create a devcontainer file in their own project folder, that references a prebuild sage devcontainer?

Yes, it would also make sense to do that (not instead, but in addition to what is done here). We have a bit of this already in the "portability testing" section added in #33671; see also #34286 (Cookiecutter for Sage user projects with devcontainer).

Can you then please explain and document how to use the sage installation (in the devcontainer) in one's own projects. For example, it is not clear to me how to select the sage python interpreter or juptyer kernel in another instance of vscode.

Users who just start with Sage do not need any of this.
They can just run Sage in the devcontainer of SAGE_ROOT and save their Jupyter notebooks somewhere, maybe in a subdirectory.

Of course, we know that for running the downstream-... devcontainer, one does not really need the whole source tree of Sage. But it gives a convenient transition: If it turns out they do have to make changes to Sage, they can just switch from a downstream-... devcontainer to a develop-... devcontainer without having to change the rest of their workflow.

Creating a "project" using Sage is far beyond what most Sage users do: Note that there are only a few dozens of published user packages ("projects") out there. #34286 is about making this easier.

Sorry for being imprecise. I meant "project" in the sense of "anything that lives outside of the sagemath folder", e.g. ones own jupyter notebooks or similar stuff. To make it precise: how do I contribute to https://github.com/sagemanifolds/SageManifolds using the devcontainer approach?

[tobiasdiez]

comment:40

Replying to @kwankyu:

The doc structure could be, as for other platforms,

   No development:

       Alternative 1:

       Alternative 2:

   Development:

       Alternative 1:

       Alternative 2:

We may put the recommended in alternative 1."No development alternative 1" would be the recommended approach for most users.

I would put "VS Code + downstream-devcontainer" approach to "No development alternative 1".

I would put "VS Code + WSL" approach to "Development alternative 1". Docker is really not necessary in sage development and conceptually more difficult than WSL, I think.

For "VS Code + downstream-devcontainer" approach, could we remove the git clone part (which is just to get devcontainer.json)?

In general, I like the idea. Maybe we can go even one step further and remove the numbering completely, as there is no clear general hierarchy between the options, but the preferred one depends on the situation. So simply something like "Option: Devcontainer" and "Option: Manual compilation from source in WSL".

I would also move the good clarifications by Matthias on when to use which option to the beginning of the decision tree, not after the steps.

[mkoeppe]

comment:41

No objections if you want to make these edits to the structure.

Important point to keep: The devcontainer approach also works on machines where you can run Docker but not WSL. (I do not know how common this scenario is.)

[mkoeppe]

comment:42

Replying to @tobiasdiez:

how do I contribute to https://github.com/sagemanifolds/SageManifolds using the devcontainer approach?

Just clone it into a subfolder.

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. Last 10 new commits:

79c3bcb	.devcontainer/downstream-docker-cocalc/devcontainer.json: Use onCreateCommand, updateContentCommand
fbfab5e	.devcontainer/downstream-docker-computop/devcontainer.json: Use onCreateCommand, updateContentCommand
09289e5	.devcontainer/downstream-archlinux-latest/devcontainer.json: Use onCreateCommand, updateContentCommand
968ec53	.devcontainer/downstream-conda-forge-latest/devcontainer.json: Use onCreateCommand, updateContentCommand
1ab9559	.devcontainer/*/devcontainer.json: Use onCreateCommand, updateContentCommand
3ba737b	Minor edits
30f3453	Small edits
f1f38b1	.devcontainer/portability-ubuntu-jammy-standard: Add symlink to portability-Dockerfile
37eb95d	Remove the note for starting configured dev container
986e676	Merge #33671

[sagetrac-git]

Changed commit from 8aa2cc4 to 986e676

[mkoeppe]

comment:44

Merged latest version of #33671.

[sagetrac-git]

Changed commit from 986e676 to a16b477

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

d5610b1	Edit: prefer symlink
179406f	src/doc/en/developer/portability_testing.rst: Update references to devcontainer ...Command
4affef2	.devcontainer/onCreate.sh, portability-updateContent.sh: Rename from post_create.sh, portability-post_start.sh
a16b477	Merge #33671

[sagetrac-git]

Changed commit from a16b477 to 74448c0

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

74448c0

Merge tag '9.7.rc0' into t/34363/installation_guide__document_sage_installation_on_windows_via_vs_code_devcontainers

[EmmanuelJeanBriand]

comment:47

For Windows using VS Code, I would find useful to mention also

• to install git,
• and that if the Git: Clone command is not recognized, it is because git is not installed.

[mkoeppe]

comment:48

Do you have a VS Code documentation link that explains this well?

[mkoeppe]

Removed branch from issue description -- replaced by PR #37534