Merge #33671

.devcontainer/develop-docker-computop/devcontainer.json

@@ -5,16 +5,13 @@
     "containerEnv": {
         "MAKE": "make -j4"
     },
-    // Run commands after the container is created.
     // Install build tools, get rid of sourcing /sage/activate in non-login shells.
     // libgmp.a is broken and leads to a build failure of ecm.
-    "postCreateCommand": ".devcontainer/post_create.sh --sudo && sudo rm -f /sage/local/lib/libgmp.a && sed -i.bak '/sage.*activate/d' ~/.bashrc",
-    // Run commands after the container is started.
+    "onCreateCommand": ".devcontainer/post_create.sh --sudo && sudo rm -f /sage/local/lib/libgmp.a && sed -i.bak '/sage.*activate/d' ~/.bashrc",
     // Do not run configure within a sage-env (see #29485).
     // The pari package is broken in the computop/sage 9.5 image, need to reinstall.
     // Also libnauty is broken.
-
-    "postStartCommand": "make configure && (export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin && unset CFLAGS LDFLAGS CXXFLAGS CPATH LIBRARY_PATH && ./configure --prefix=/sage/local --with-sage-venv) && make pari-clean nauty-clean build V=0",
+    "updateContentCommand": "make configure && (export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin && unset CFLAGS LDFLAGS CXXFLAGS CPATH LIBRARY_PATH && ./configure --prefix=/sage/local --with-sage-venv) && make pari-clean nauty-clean build V=0",
     "extensions": [
         "ms-python.python"
     ]

.devcontainer/downstream-archlinux-latest/devcontainer.json

@@ -2,12 +2,10 @@
 {
     "name": "archlinux:latest downstream Sage",
     "image": "archlinux:latest",
-    // Run commands after the container is created.
     // Create an empty bashrc to avoid the error "No such file or directory" when opening a terminal.
-    "postCreateCommand": "EXTRA_SYSTEM_PACKAGES='sagemath sagemath-doc' EXTRA_SAGE_PACKAGES='notebook pip' .devcontainer/post_create.sh && touch ~/.bashrc",
-    // Run commands after the container is started.
+    "onCreateCommand": "EXTRA_SYSTEM_PACKAGES='sagemath sagemath-doc' EXTRA_SAGE_PACKAGES='notebook pip' .devcontainer/post_create.sh && touch ~/.bashrc",
     // There's no SAGE_LOCAL, so remove the symlink 'prefix'.
-    "postStartCommand": "rm -f prefix && ln -sf /usr venv",
+    "updateContentCommand": "rm -f prefix && ln -sf /usr venv",
     "extensions": [
         "ms-python.python"
     ]

.devcontainer/downstream-conda-forge-latest/devcontainer.json

@@ -2,9 +2,8 @@
 {
     "name": "condaforge/mambaforge:latest downstream Sage",
     "image": "condaforge/mambaforge:latest",
-    // Run commands after the container is created.
-    "postCreateCommand": "mamba install --yes sage",
-    // Run commands after the container is started.
+    // Install Sage from the conda-forge package.
+    "onCreateCommand": "mamba install --yes sage",
     // * If the workspace directory looks like a copy of the Sage source tree (SAGE_ROOT):
     //   - it bootstraps and configures the Sage distribution,
     //   - thus, the script ``./sage`` and the symlinks ``prefix``, ``venv`` are set as expected,
@@ -13,7 +12,7 @@
     //   - however, it does not start the build.
     // * Otherwise, it does nothing. This is so that users can copy this devcontainer.json file as is
     //   into their projects.
-    "postStartCommand": "if [ -d pkgs/sagemath-standard ]; then make configure && ln -sf $CONDA_PREFIX venv; else echo 'Edit .devcontainer/devcontainer.json (postStartCommand) to run project-specific startup commands'; fi",
+    "updateContentCommand": "if [ -d pkgs/sagemath-standard ]; then make configure && ln -sf $CONDA_PREFIX venv; else echo 'Edit .devcontainer/devcontainer.json (updateContentCommand) to run project-specific startup commands'; fi",
     "extensions": [
         "ms-python.python"
     ]

.devcontainer/downstream-docker-cocalc/devcontainer.json

@@ -5,16 +5,14 @@
     "containerEnv": {
         "MAKE": "make -j4"
     },
-    // Run commands after the container is created.
     // libgmp.a is broken and leads to a build failure of ecm.
-    "postCreateCommand": ".devcontainer/post_create.sh && rm -f /usr/local/sage/local/lib/libgmp.a",
-    // Run commands after the container is started.
+    "onCreateCommand": ".devcontainer/post_create.sh && rm -f /usr/local/sage/local/lib/libgmp.a",
     // * If the workspace directory looks like a copy of the Sage source tree (SAGE_ROOT):
     //   - it bootstraps the Sage distribution,
     //   - sets the symlink ``venv`` as expected,
     // * Otherwise, it does nothing. This is so that users can copy this devcontainer.json file as is
     //   into their projects.
-    "postStartCommand": "if [ -d pkgs/sagemath-standard ]; then make configure && ./configure --enable-build-as-root --prefix=/usr/local/sage/local --with-sage-venv; else echo 'Edit .devcontainer/devcontainer.json (postStartCommand) to run project-specific startup commands'; fi",
+    "updateContentCommand": "if [ -d pkgs/sagemath-standard ]; then make configure && ./configure --enable-build-as-root --prefix=/usr/local/sage/local --with-sage-venv; else echo 'Edit .devcontainer/devcontainer.json (updateContentCommand) to run project-specific startup commands'; fi",
     "extensions": [
         "ms-python.python"
     ]

.devcontainer/downstream-docker-computop/devcontainer.json

@@ -5,16 +5,13 @@
     "containerEnv": {
         "MAKE": "make -j4"
     },
-    // Run commands after the container is created.
     // Install build tools, get rid of sourcing /sage/activate in non-login shells.
     // libgmp.a is broken and leads to a build failure of ecm.
-    "postCreateCommand": ".devcontainer/post_create.sh --sudo && sudo rm -f /sage/local/lib/libgmp.a && sed -i.bak '/sage.*activate/d' ~/.bashrc",
-    // Run commands after the container is started.
+    "onCreateCommand": ".devcontainer/post_create.sh --sudo && sudo rm -f /sage/local/lib/libgmp.a && sed -i.bak '/sage.*activate/d' ~/.bashrc",
     // Do not run configure within a sage-env (see #29485).
     // The pari package is broken in the computop/sage 9.5 image, need to reinstall.
     // Also libnauty is broken.
-
-    "postStartCommand": "make configure && (export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin && unset CFLAGS LDFLAGS CXXFLAGS CPATH LIBRARY_PATH && ./configure --prefix=/sage/local --with-sage-venv)",
+    "updateContentCommand": "make configure && (export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin && unset CFLAGS LDFLAGS CXXFLAGS CPATH LIBRARY_PATH && ./configure --prefix=/sage/local --with-sage-venv)",
     "extensions": [
         "ms-python.python"
     ]

.devcontainer/portability-ubuntu-jammy-standard/devcontainer.json

@@ -1,23 +1,22 @@
 // See https://aka.ms/devcontainer.json for format details.
 {
-	"name": "Ubuntu jammy",
-	"build": {
-		"dockerfile": "portability-Dockerfile",
-	    // See tox.ini for definitions
-	    "args": { "SYSTEM_FACTOR":	"ubuntu-jammy",
-		      "PACKAGE_FACTOR": "standard",
-		      "DOCKER_TARGET":	"with-targets",
-		      "DOCKER_TAG":	"dev"
-		    }
-	},
-	"containerEnv": {
-	    "MAKE": "make -j4"
-	},
-	// Run commands after the container is created.
-	"postCreateCommand": ".devcontainer/post_create.sh",
-	// Run commands after the container is started.
-	"postStartCommand": ".devcontainer/portability-post_start.sh",
-	"extensions": [
-	    "ms-python.python"
-        ]
+    "name": "Ubuntu jammy",
+    "build": {
+        "dockerfile": "portability-Dockerfile",
+        // See tox.ini for definitions
+        "args": {
+            "SYSTEM_FACTOR": "ubuntu-jammy",
+            "PACKAGE_FACTOR": "standard",
+            "DOCKER_TARGET": "with-targets",
+            "DOCKER_TAG": "dev"
+        }
+    },
+    "containerEnv": {
+        "MAKE": "make -j4"
+    },
+    "onCreateCommand": ".devcontainer/post_create.sh",
+    "updateContentCommand": ".devcontainer/portability-post_start.sh",
+    "extensions": [
+        "ms-python.python"
+    ]
 }

.devcontainer/portability-ubuntu-jammy-standard/portability-Dockerfile

@@ -0,0 +1 @@
+../portability-Dockerfile

.vscode/settings.json

@@ -3,7 +3,7 @@
     "files.exclude": {
         "**/__pycache__": true,
         "src/**/*.cpp": true,
-        "src/**/*.so": true,
+        "src/**/*.so": true
     },
     "search.exclude": {
         "build/pkgs/sagemath_categories/src": true,
@@ -12,13 +12,13 @@
         "pkgs/sage-conf_pypi/sage_root/build": true,
         "pkgs/sagemath-categories/sage": true,
         "pkgs/sagemath-objects/sage": true,
-        "pkgs/sagemath-standard/sage": true,
+        "pkgs/sagemath-standard/sage": true
     },
     "python.testing.pytestEnabled": true,
     "python.testing.pytestArgs": [
         "--rootdir=src/sage",
         "-c=src/tox.ini",
-        "--doctest-modules",
+        "--doctest-modules"
     ],
     "python.testing.unittestEnabled": false,
     "python.linting.pycodestyleEnabled": true,
@@ -28,5 +28,5 @@
         "Conda",
         "sagemath",
         "Cython"
-    ],
+    ]
 }

src/doc/en/developer/portability_testing.rst

@@ -1190,7 +1190,7 @@ application, then in the command palette of VS Code, enter "Remote-Containers:
 Open Folder in Container", and hit :kbd:`Enter`, and choose the directory
 ``$SAGE_ROOT`` of your local Sage repository.
 
-Once VS Code starts running the dev container, by clicking on "show log",
+Once VS Code starts configuring the dev container, by clicking on "show log",
 you can see what it does:
 
 - It pulls the prebuilt image from ghcr.io (via
@@ -1206,10 +1206,13 @@ you can see what it does:
   reusing the installation (:envvar:`SAGE_LOCAL`, :envvar:`SAGE_VENV`)
   from the prebuilt image.
 
-After VS Code finished configuring the dev container, your local Sage
-repository at ``$SAGE_ROOT`` is available in the container at the directory
-``/workspaces/<repository name>``. You may need to open a new Terminal to start
-working from the directory.
+After VS Code finished configuring the dev container (when the message "Done.
+Press any key to close the terminal." appears in the terminal named
+"Configuring"), your local Sage repository at ``$SAGE_ROOT`` is available in
+the container at the directory ``/workspaces/<repository name>``. To use Sage
+in a terminal, `open a new terminal in VS Code
+<https://code.visualstudio.com/docs/terminal/basics>`_, type ``./sage`` and hit
+:kbd:`Enter`.
 
 .. NOTE::
 
@@ -1218,7 +1221,7 @@ working from the directory.
    (possibly) ``$SAGE_ROOT/logs`` will be symbolic links that work inside the dev
    container, but not in your local file system; and also the script
    ``$SAGE_ROOT/sage`` will not work. Hence after working with the dev container,
-   you will want to remove ``logs`` if it is a symbolic link, and to re-run the
+   you will want to remove ``logs`` if it is a symbolic link, and rerun the
    ``configure`` script.
 
 You can edit a copy of the configuration file to change to a different platform, another
@@ -1235,6 +1238,22 @@ In addition to the
 provides several other sample ``devcontainer.json`` configuration files in the
 directory ``$SAGE_ROOT/.devcontainer``.
 
+Files named ``$SAGE_ROOT/.devcontainer/develop-.../devcontainer.json`` configure
+containers from a public Docker image that provides SageMath and then updates the
+installation of SageMath in this container by building from the current source tree.
+
+- `develop-docker-computop/devcontainer.json
+  <https://github.com/sagemath/sage/tree/develop/.devcontainer/develop-docker-computop/devcontainer.json>`_
+  configures a container with the `Docker image from the 3-manifolds
+  project <https://hub.docker.com/r/computop/sage/>`_, providing
+  SnapPy, Regina, PHCPack, etc.
+
+If you want to use one of these ``devcontainer.json`` files, copy (or symlink)
+it and start VS Code as explained above. After VS Code finished configuring the
+dev container, to use Sage in a terminal, `open a new terminal in VS Code
+<https://code.visualstudio.com/docs/terminal/basics>`_, type ``./sage`` and hit
+:kbd:`Enter`.
+
 Files named ``$SAGE_ROOT/.devcontainer/downstream-.../devcontainer.json`` configure
 containers with an installation of downstream packages providing SageMath from a
 package manager (``downstream-archlinux-...``, ``downstream-conda-forge``;
@@ -1247,56 +1266,28 @@ work without change) or to adapt them to your needs.
 
 - `downstream-archlinux-latest/devcontainer.json
   <https://github.com/sagemath/sage/tree/develop/.devcontainer/downstream-archlinux-latest/devcontainer.json>`_
-  configures a container with an installation of `Arch Linux <https://archlinux.org/>`_
-  and its SageMath package. (Arch Linux packaging is downstream from the Sage project,
-  hence the prefix ``downstream-...``; the suffix ``latest`` indicates
-  the most recent version of Arch Linux as available on Docker Hub.)
-
-  When the message "Done. Press any key to close the terminal." appears in the terminal
-  named "Configuring", Sage is ready for use. To use Sage in a terminal, `open a new
-  terminal in VS Code <https://code.visualstudio.com/docs/terminal/basics>`_, type ``sage``
-  and hit :kbd:`Enter`. (Do not use ``./sage``; this will not work because the source tree is
-  not configured.)
+  configures a container with an installation of `Arch Linux
+  <https://archlinux.org/>`_ and its SageMath package. (The suffix ``latest``
+  indicates the most recent version of Arch Linux as available on Docker Hub.)
 
 - `downstream-conda-forge-latest/devcontainer.json
   <https://github.com/sagemath/sage/tree/develop/.devcontainer/downstream-conda-forge-latest/devcontainer.json>`_
-  similarly configures a container with an installation of conda-forge and its SageMath package.
-
-  When the message "Done. Press any key to close the terminal." appears in the terminal
-  named "Configuring", Sage is ready for use. To use Sage in a terminal, `open a new
-  terminal in VS Code <https://code.visualstudio.com/docs/terminal/basics>`_, type ``sage``
-  and hit :kbd:`Enter`. (Do not use ``./sage``; this will not work because the source tree is
-  not configured.)
+  configures a container with an installation of conda-forge and its SageMath package.
 
 - `downstream-docker-cocalc/devcontainer.json
   <https://github.com/sagemath/sage/tree/develop/.devcontainer/downstream-docker-cocalc/devcontainer.json>`_
   configures a container with `the CoCalc Docker image <https://doc.cocalc.com/docker-image.html>`_.
 
-  When the message "Done. Press any key to close the terminal." appears in the terminal
-  named "Configuring", Sage is ready for use. To use Sage in a terminal, `open a new
-  terminal in VS Code <https://code.visualstudio.com/docs/terminal/basics>`_, type ``sage``
-  and hit :kbd:`Enter`. (Do not use ``./sage``; this will not work because the source tree is
-  not configured.)
-
 - `downstream-docker-computop/devcontainer.json
   <https://github.com/sagemath/sage/tree/develop/.devcontainer/develop-docker-computop/devcontainer.json>`_
   configures a container with the `Docker image from the 3-manifolds
   project <https://hub.docker.com/r/computop/sage/>`_, providing
   SnapPy, Regina, PHCPack, etc.
 
-  When the message "Done. Press any key to close the terminal." appears in the terminal
-  named "Configuring", Sage is ready for use. To use Sage in a terminal, `open a new
-  terminal in VS Code <https://code.visualstudio.com/docs/terminal/basics>`_, type ``sage``
-  and hit :kbd:`Enter`. (Do not use ``./sage``; this will not work because the source tree is
-  not configured.)
+If you want to use one of these ``devcontainer.json`` files, copy (or symlink)
+it and start VS Code as explained above. After VS Code finished configuring the
+dev container, to use Sage in a terminal, `open a new terminal in VS Code
+<https://code.visualstudio.com/docs/terminal/basics>`_, type ``sage`` and hit
+:kbd:`Enter`. (Do not use ``./sage``; this will not work because the source
+tree is not configured.)
 
-Files named ``$SAGE_ROOT/.devcontainer/develop-.../devcontainer.json`` configure
-containers from a public Docker image that provides SageMath and then updates the
-installation of SageMath in this container by building from the current source tree.
-
-- `develop-docker-computop/devcontainer.json
-  <https://github.com/sagemath/sage/tree/develop/.devcontainer/develop-docker-computop/devcontainer.json>`_
-  configures a container with the `Docker image from the 3-manifolds
-  project <https://hub.docker.com/r/computop/sage/>`_, providing
-  SnapPy, Regina, PHCPack, etc. It then updates the installation of
-  SageMath in this container by building from the current source tree.