Planing of repository layout

[soehms]

@kwankyu, I open this issue to find the structure of the new repository. From my point of view we need the following:

• ./LICENCE
  I would say GPL?
• ./README.md
  basic explanations, advantages and disadvantages of both approaches, links to the two .md files below. Maybe also links to directly download installation scripts from here
• ./sagemath_docker_guide.md
  my former README.md from projects_docker_guide
• ./sagemath_wsl_installer.md
  containing more information about your approach (file-names are just suggestions)
• ./src/
  containing .ps1 files from projects_docker_guide/src and in addition, if you like to extract a .ps1 template from your create-wsl-image.yml that could be here, too
• ./screenshots/
  shall we have sub-folders for both approaches?
• ./.github/workflows/
  containing the content of your create-wsl-image.yml and my docker_guide_installer_release.yml (which I created yesterday)
  maybe merged into one workflow (because they have the creation of the release note in common).

Anything else?

Previous work on this topic can be found at sagemath/sage-binder-env#20.

[kwankyu]

./icons/ containing icons for desktop shortcuts. Perhaps we should use sagemath official icons (if any) with the official sagemath logo. Or it may be ./src/icons/ if we put all parts that would make up the installers into one directory ./src/.

[kwankyu]

I don't know about licenses. ChatGPT recommends GPL v3 :-)

[kwankyu]

• ./screenshots/
  shall we have sub-folders for both approaches?

Yes. That would be clean.

[saraedum]

Are you planning to put my installer into here as well?

Source code is here: https://github.com/flatsurf/sage-flatsurf/tree/master/installer/win

plus this workflow file: https://github.com/flatsurf/sage-flatsurf/blob/master/.github/workflows/installer.yml

(I am happy to contribute this in a PR once the layout has been decided.)

[kwankyu]

• ./sagemath_docker_guide.md
  my former README.md from projects_docker_guide
• ./sagemath_wsl_installer.md
  containing more information about your approach (file-names are just suggestions)

You may name it sagemath_wsl_guide.md. But I am not sure how much content it would have. Putting all into the main README may suffice...

[soehms]

Are you planning to put my installer into here as well?

Sure! I think we should consolidate all inputs in this repo to achieve good solutions for Windows users.

Source code is here: https://github.com/flatsurf/sage-flatsurf/tree/master/installer/win

plus this workflow file: https://github.com/flatsurf/sage-flatsurf/blob/master/.github/workflows/installer.yml

That looks interesting!

(I am happy to contribute this in a PR once the layout has been decided.)

In general, I think we should work with PRs here. For a startup, in the first commit I created the layout as suggested here and added some files from my Docker Guide repo. Unfortunately, I can't do much more this week. Feel free to start without me.

[soehms]

Functionality we have in sum

As of August 2025, I have created a separate issue #3 to continue this commentary.

FYI: I made some major changes in my approach. I got rid of Docker Desktop replacing it by a custom WSL distribution based on Alpine Linux. This makes the installation much easier, faster and less resource consuming and reduces startup-time.

How do we want to proceed here?

We have four codebases:

A) the one by @saraedum, which is developed for flatsurf and installs Sage as a custom WSL distribution.
B) the one by @kwankyu, which is developed in the sage-binder repository and installs Sage as a custom WSL distribution, too.
C) the one by @soehms, which is developed as an example for a projects docker guide and installs Sage via Docker in a custom WSL Docker distribution.
D) the one by @tobiasdiez, which is developed via a native Windows build of Sage using meson (see sagemath/sage#38872 and #1 (comment) below).

All except D) have in common that they need a working WSL installation and this is the hardest part of the installation and most sensitive to system requirements. Let me try to summarize what we have in total (please correct me if I'm wrong):

1. Installing WSL
    1.1 detection of state
        A) Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux /  VirtualMachinePlatform
        B) try .. catch  with wsl --install --no-distribution
        C) wsl --status
    1.2 installation
        A) Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux / VirtualMachinePlatform -NoRestart
        B) wsl --install --no-distribution
        C) wsl --install --no-distribution
    1.3 handling of reboot (if necessary)
        A) InnoSetup asks you to reboot and otherwise it doesn't continue. It adds the installer to the autostart so that the installation continues after the reboot.
        B) Print a hint that reboot could be necesarry.
        C) Query for reboot if it is necessary and perfom it if the user agrees. Give a hint that the installer must be restarted after reboot.
    1.4 detection that virtualization needs to be enabled in BIOS.
        A) -
        B) -
        C) Via result from wsl --import.
    1.5 Update WSL kernel
        A) Using msi wsl_update_x64.msi
        B) -
        C) -
2. Setting up the custom WSL distribution.
    A) Using wsldl to create a custom distribution for each Sage release from a tar-file created by Pixi (see link below)
    B) Using wsl --import to create a custom distribution for each Sage release from a tar-file exported from a Docker container.
    C) Using wsl --import to create a custom distribution with a running Docker daemon (Docker for Powershell) from a tar-file exported from a Docker container.
3. Installation method
    A) Install-Wizard created by Inno Setup
    B) Invoking a Powershell script
    C) Invoking a Powershell script
    D) not yet known
4. Launching Sage
    A) Create three desktop icons to launch an IPython, JupyterLab or Bash environment to work with Sage
    B) Create two desktop icons to launch an IPython or JupyterLab environment to work with Sage
    C) Create one desktop icon to launch a special application which allows to install arbitrary Sage releases from registries on Docker Hub and launch Ipython, Jupyter-Notebook (Lab needs an adaption in our Docker images) or Bash environments to work with Sage.
    D) not yet known

From a user perspective, there is hardly any difference between A) and B) (asuming equal resource consumption). Therefore, I think it makes sense to consolidate the two approaches. From a technical perspective, both approaches have different advantages:

A) Is implemented as part of installers for Linux, Mac and Windows and uses a common base via Pixi.
B) Is implemented in a more down-to-earth way and therefore easier to understand.

Is there a way to merge these two approaches? Maybe it would make sense to include 1.4 here as well. For C) it would be nice to have 1.5 and 3. (creating an install-wizard using Inno Setup) as per A). Is there a way to share the WSL installation across all three approaches?

[soehms]

Is there a way to merge these two approaches?

At least one thing could be done in common by following this suggestion by @tobiasdiez in sagemath/sage-binder-env#20 (comment) (regardless of whether we use Pixi or Docker containers to generate them):

I suggest to build the wsl tar image at https://github.com/sagemath/sage/blob/develop/.github/workflows/docker_hub.yml (or in a new workflow that is triggered by it). Not sure if there is a canonical place for the powershell script but it can just be in the root (or under docker). Or it goes in it's own repo as you have suggested.

[kwankyu]

I look forward to seeing one official windows installer that combines all the merits of the three approaches. The installer at sage-binder repo would be taken down when the installer here supersedes the former. I hope that this repo would be the canonical place visited by those looking for a windows installer for sage. The Sage documentation would direct people to here.

[tobiasdiez]

I'm also working on a native windows build of sage (using conda atm) in sagemath/sage#38872. It compiles but is definitely not yet production ready. Just wanted to mention it here as a "4." approach. Since it's not based on WSL, it circumvents many problems associated with this technique (but it comes with its own challenges of course). Maybe in the future it can be given as an experimental option in the "combined windows installer".

[soehms]

I'm also working on a native windows build of sage (using conda atm) in sagemath/sage#38872. It compiles but is definitely not yet production ready. Just wanted to mention it here as a "4." approach. Since it's not based on WSL, it circumvents many problems associated with this technique (but it comes with its own challenges of course). Maybe in the future it can be given as an experimental option in the "combined windows installer".

Great! It looks like a lot of work. I hope it will be successful and less fragile than the Cygwin approach. I added it as method D) above.

[saraedum]

Just to clarify 1.3.A) InnoSetup asks you to reboot and otherwise it doesn't continue. It adds the installer to the autostart so that the installation continues after the reboot. (All of this is a feature of InnoSetup.)

[saraedum]

Is there a way to share the WSL installation across all three approaches?

Windows installers are extremely weird. What InnoSetup can and cannot do at certain steps of the process and as which user things happen took a lot of effort to get (hopefully) right. Feel free to use the WSL prerequisites part in your installer of course, but I am not sure that it is going to be easy to put the rest of your process into InnoSetup as is. For example, I do not create the WSL distribution as part of the installer. I concluded that this is not really possible; instead you have to create the WSL distribution by launching the "installed program" as the current user once the actual installation is complete.

[soehms]

Just to clarify 1.3.A) InnoSetup asks you to reboot and otherwise it doesn't continue. It adds the installer to the autostart so that the installation continues after the reboot. (All of this is a feature of InnoSetup.)

Thanks! I corrected it in the list above!

[soehms]

Is there a way to share the WSL installation across all three approaches?

Windows installers are extremely weird. What InnoSetup can and cannot do at certain steps of the process and as which user things happen took a lot of effort to get (hopefully) right. Feel free to use the WSL prerequisites part in your installer of course, but I am not sure that it is going to be easy to put the rest of your process into InnoSetup as is. For example, I do not create the WSL distribution as part of the installer. I concluded that this is not really possible; instead you have to create the WSL distribution by launching the "installed program" as the current user once the actual installation is complete.

Thanks for these useful explanations and hints. I have to look in more detail into it, to see what is possible.