diff --git a/src/doc/en/developer/portability_testing.rst b/src/doc/en/developer/portability_testing.rst index 0ad863f4e0f..d3d770050d5 100644 --- a/src/doc/en/developer/portability_testing.rst +++ b/src/doc/en/developer/portability_testing.rst @@ -9,7 +9,7 @@ Testing on Multiple Platforms ============================= Sage is intended to build and run on a variety of platforms, -including all major Linux distributions, as well as MacOS, and +including all major Linux distributions, as well as macOS, and Windows (with WSL). There is considerable variation among these platforms. @@ -128,9 +128,9 @@ Typical Docker images provide minimal installations of packages only:: As you can see above, the image ``ubuntu:latest`` has neither a Python nor a GCC installed, which are among the build prerequisites of Sage. We -need to install them using the distribution's package manager first. +need to install them using the Linux distribution's package manager first. -Sage facilitates testing various distributions on Docker as follows. +Sage facilitates testing various Linux distributions on Docker as follows. Discovering the system's package system --------------------------------------- @@ -142,7 +142,7 @@ Discovering the system's package system Let's install gcc, hoping that the Ubuntu package providing it is simply named ``gcc``. If we forgot what the package manager on -Debian-derived distributions is called, we can ask Sage for a +Debian-derived Linux distributions is called, we can ask Sage for a reminder:: root@39d693b2a75d:/sage# build/bin/sage-print-system-package-command debian install gcc @@ -190,7 +190,8 @@ example, the file ``build/pkgs/_prereq/distros/debian.txt`` contains the followi From this information, we know that we can use the following command on our container to install the necessary build prerequisites:: - root@39d693b2a75d:/sage# apt-get install binutils make m4 perl python3 tar bc gcc g++ ca-certificates + root@39d693b2a75d:/sage# apt-get install binutils make m4 perl python3 \ + tar bc gcc g++ ca-certificates Reading package lists... Done Building dependency tree Reading state information... Done @@ -208,7 +209,8 @@ Now we can start the build:: root@39d693b2a75d:/sage# ./configure checking for a BSD-compatible install... /usr/bin/install -c checking for root user... yes - configure: error: You cannot build Sage as root, switch to an unprivileged user. (If building in a container, use --enable-build-as-root.) + configure: error: You cannot build Sage as root, switch to an unprivileged user. + (If building in a container, use --enable-build-as-root.) Let's just follow this helpful hint:: @@ -225,14 +227,16 @@ Using Sage's database of equivalent distribution packages At the end of the ``./configure`` run, Sage issued a message like the following:: - configure: notice: the following SPKGs did not find equivalent system packages: arb boost_cropped bzip2 ... zeromq zlib + configure: notice: the following SPKGs did not find equivalent system packages: + arb boost_cropped bzip2 ... zeromq zlib checking for the package system in use... debian - configure: hint: installing the following system packages is recommended and may avoid building some of the above SPKGs from source: + configure: hint: installing the following system packages is recommended and + may avoid building some of the above SPKGs from source: configure: $ sudo apt-get install libflint-arb-dev ... libzmq3-dev libz-dev configure: After installation, re-run configure using: configure: $ ./config.status --recheck && ./config.status -This information comes from Sage's database of equivalent distribution +This information comes from Sage's database of equivalent system packages. For example:: root@39d693b2a75d:/sage# ls build/pkgs/arb/distros/ @@ -268,9 +272,9 @@ corresponding to its current state:: root@39d693b2a75d:/sage# ^D [mkoeppe@sage worktree-ubuntu-latest]$ docker ps -a | head -n3 - CONTAINER ID IMAGE COMMAND CREATED STATUS - 39d693b2a75d ubuntu:latest "/bin/bash" 8 minutes ago Exited (0) 6 seconds ago - 9f3398da43c2 ubuntu:latest "/bin/bash" 8 minutes ago Exited (0) 8 minutes ago + CONTAINER ID IMAGE COMMAND CREATED STATUS + 39d693b2a75d ubuntu:latest "/bin/bash" 8 minutes ago Exited (0) 6 seconds ago + 9f3398da43c2 ubuntu:latest "/bin/bash" 8 minutes ago Exited (0) 8 minutes ago [mkoeppe@sage worktree-ubuntu-latest]$ docker commit 39d693b2a75d ubuntu-latest-minimal-17 sha256:4151c5ca4476660f6181cdb13923da8fe44082222b984c377fb4fd6cc05415c1 @@ -506,7 +510,8 @@ might not work on all platforms, ``surf``, which was marked as ... Makefile:31: recipe for target 'surf' failed make: *** [surf] Error 1 - The command '/bin/sh -c make SAGE_SPKG="sage-spkg -y -o" ${USE_MAKEFLAGS} ${TARGETS_PRE}' returned a non-zero code: 2 + The command '/bin/sh -c make SAGE_SPKG="sage-spkg -y -o" ${USE_MAKEFLAGS} ${TARGETS_PRE}' + returned a non-zero code: 2 Note that no image id is shown at the end; the build failed, and no image is created. However, the container in which the last step of @@ -688,11 +693,11 @@ the one just after running the ``configure`` script (``configured``):: Let's verify that the images are available:: - (base) egret:~/s/sage/sage-rebasing/worktree-algebraic-2018-spring (mkoeppe *$%>)$ docker images | head - REPOSITORY TAG IMAGE ID - sage-centos-8-standard-with-targets 9.1.beta9-435-g861ba33bbc-dirty 7ecfa86fceab - sage-centos-8-standard-configured 9.1.beta9-435-g861ba33bbc-dirty 4314929e2b4c - sage-centos-8-standard-with-system-packages 9.1.beta9-435-g861ba33bbc-dirty 4bb14c3d5646 + [mkoeppe@sage sage]$ docker images | head + REPOSITORY TAG IMAGE ID + sage-centos-8-standard-with-targets 9.1.beta9-435-g861ba33bbc-dirty 7ecfa86fceab + sage-centos-8-standard-configured 9.1.beta9-435-g861ba33bbc-dirty 4314929e2b4c + sage-centos-8-standard-with-system-packages 9.1.beta9-435-g861ba33bbc-dirty 4bb14c3d5646 ... @@ -1204,13 +1209,13 @@ Using our pre-built Docker images for development in VS Code `VS Code `_ is very convenient for developing with Docker containers thanks to the `Visual -Studio Code Remote - Containers -`_ extension. +Studio Code Dev Containers +`_ extension. If the extension is not already installed, then in VS Code, click the "Extension" icon on the left (or press :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`X`; on macOS, :kbd:`Command` + :kbd:`Shift` + :kbd:`X`) to open a list of -extensions. Search for "Remote - Containers" and install it. +extensions. Search for "Dev Containers" and install it. The extension needs a ``devcontainer.json`` configuration file to work. Sage provides sample ``devcontainer.json`` configuration files @@ -1220,11 +1225,11 @@ purpose. If you open the sage folder in VS Code, it may prompt you whether you would like to open the current directory in the dev container (yes). If it does not, use the command palette -(:kbd:`Ctrl` + :kbd:`Shift` + :kbd:`P`), enter the command "Remote-Containers: +(:kbd:`Ctrl` + :kbd:`Shift` + :kbd:`P`), enter the command "Dev Containers: Reopen Folder in Container" , and hit :kbd:`Enter`. If the above ``code .`` command does not work, start VS Code as a regular -application, then in the command palette of VS Code, enter "Remote-Containers: +application, then in the command palette of VS Code, enter "Dev Containers: Open Folder in Container", and hit :kbd:`Enter`, and choose the directory ``$SAGE_ROOT`` of your local Sage repository. @@ -1271,7 +1276,7 @@ in a terminal, `open a new terminal in VS Code ``configure`` script. You can edit a copy of the configuration file to change to a different platform, another -version, or build stage. After editing the configuration file, run "Remote-Containers: Rebuild Container" from the command +version, or build stage. After editing the configuration file, run "Dev Containers: Rebuild Container" from the command palette. See the `VS Code devcontainer.json reference `_ and the `GitHub introduction to dev containers