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

mkoeppe · 2022-08-14T15:13:31Z

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 · 2022-08-14T16:08:11Z

Branch: u/mkoeppe/installation_guide__document_sage_installation_on_windows_via_vs_code_devcontainers

mkoeppe · 2022-08-14T16:09:48Z

Author: Matthias Koeppe

mkoeppe · 2022-08-14T16:09:48Z

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 · 2022-08-14T16:09:48Z

Commit: 1ca0876

sagetrac-git · 2022-08-15T15:22:05Z

Changed commit from 1ca0876 to b442a41

sagetrac-git · 2022-08-15T15:22:05Z

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 · 2022-08-16T14:17:30Z

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 · 2022-08-16T15:37:31Z

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 · 2022-08-16T15:37:31Z

Changed commit from b442a41 to 8231674

mkoeppe · 2022-08-16T15:38:10Z

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 · 2022-08-16T15:40:30Z

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 · 2022-08-17T05:56:02Z

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 · 2022-08-17T05:56:02Z

Changed commit from 8231674 to 06610b8

tobiasdiez · 2022-08-17T08:35:21Z

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 · 2022-08-17T08:50:06Z

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 · 2022-08-17T14:28:46Z

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 · 2022-08-17T14:31:56Z

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 · 2022-08-17T14:35:44Z

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 · 2022-08-17T17:20:04Z

Changed commit from 06610b8 to dd5724e

sagetrac-git · 2022-08-17T17:20:04Z

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

`dd5724e`	`.devcontainer/post_create.sh: Install bootstrapping prerequisites`

sagetrac-git · 2022-08-17T17:21:57Z

Changed commit from dd5724e to 5097583

sagetrac-git · 2022-08-17T17:21:57Z

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 · 2022-08-17T19:01:19Z

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.

mkoeppe · 2022-08-18T21:20:58Z

comment:34

How about this?

sagetrac-git · 2022-08-18T21:31:31Z

Changed commit from cec1e84 to 8aa2cc4

sagetrac-git · 2022-08-18T21:31:31Z

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 · 2022-08-18T21:45:55Z

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 · 2022-08-18T23:41:06Z

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 · 2022-08-18T23:45:17Z

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 · 2022-08-19T20:47:43Z

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 · 2022-08-19T20:57:48Z

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 · 2022-08-19T21:07:00Z

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 · 2022-08-19T21:07:28Z

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 · 2022-08-21T18:59:18Z

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 · 2022-08-21T18:59:18Z

Changed commit from 8aa2cc4 to 986e676

mkoeppe · 2022-08-21T19:10:24Z

comment:44

Merged latest version of #33671.

sagetrac-git · 2022-08-23T23:34:51Z

Changed commit from 986e676 to a16b477

sagetrac-git · 2022-08-23T23:34:51Z

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 · 2022-08-31T01:54:30Z

Changed commit from a16b477 to 74448c0

sagetrac-git · 2022-08-31T01:54:30Z

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 · 2022-09-10T17:42:25Z

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 · 2022-09-10T18:01:16Z

comment:48

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

mkoeppe · 2024-03-03T22:10:16Z

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

mkoeppe added this to the sage-9.7 milestone Aug 14, 2022

mkoeppe added c: documentation labels Aug 14, 2022

This comment has been minimized.

Sign in to view

mkoeppe added the s: needs review label Aug 14, 2022

This comment has been minimized.

Sign in to view

mkoeppe added s: needs review and removed s: needs work labels Aug 18, 2022

mkoeppe modified the milestones: sage-9.7, sage-9.8 Sep 19, 2022

mkoeppe modified the milestones: sage-9.8, sage-9.9 Jan 7, 2023

mkoeppe added s: needs work and removed s: needs review labels Feb 13, 2023

mkoeppe removed this from the sage-10.0 milestone Apr 30, 2023

mkoeppe removed the s: needs work label Mar 3, 2024

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

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

Comments

mkoeppe commented Aug 14, 2022 • edited Loading

mkoeppe commented Aug 14, 2022

mkoeppe commented Aug 14, 2022

mkoeppe commented Aug 14, 2022

This comment has been minimized.

mkoeppe commented Aug 14, 2022

This comment has been minimized.

sagetrac-git mannequin commented Aug 15, 2022

sagetrac-git mannequin commented Aug 15, 2022

DavidAyotte commented Aug 16, 2022

sagetrac-git mannequin commented Aug 16, 2022

sagetrac-git mannequin commented Aug 16, 2022

mkoeppe commented Aug 16, 2022

mkoeppe commented Aug 16, 2022

sagetrac-git mannequin commented Aug 17, 2022

sagetrac-git mannequin commented Aug 17, 2022

tobiasdiez commented Aug 17, 2022

tobiasdiez commented Aug 17, 2022

mkoeppe commented Aug 17, 2022

mkoeppe commented Aug 17, 2022

mkoeppe commented Aug 17, 2022

sagetrac-git mannequin commented Aug 17, 2022

sagetrac-git mannequin commented Aug 17, 2022

sagetrac-git mannequin commented Aug 17, 2022

sagetrac-git mannequin commented Aug 17, 2022

tobiasdiez commented Aug 17, 2022

mkoeppe commented Aug 18, 2022

sagetrac-git mannequin commented Aug 18, 2022

sagetrac-git mannequin commented Aug 18, 2022

kwankyu commented Aug 18, 2022

kwankyu commented Aug 18, 2022

mkoeppe commented Aug 18, 2022

tobiasdiez commented Aug 19, 2022

tobiasdiez commented Aug 19, 2022

mkoeppe commented Aug 19, 2022

mkoeppe commented Aug 19, 2022

sagetrac-git mannequin commented Aug 21, 2022

sagetrac-git mannequin commented Aug 21, 2022

mkoeppe commented Aug 21, 2022

sagetrac-git mannequin commented Aug 23, 2022

sagetrac-git mannequin commented Aug 23, 2022

sagetrac-git mannequin commented Aug 31, 2022

sagetrac-git mannequin commented Aug 31, 2022

EmmanuelJeanBriand commented Sep 10, 2022

mkoeppe commented Sep 10, 2022

mkoeppe commented Mar 3, 2024

mkoeppe commented Aug 14, 2022 •

edited

Loading