Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Small update to Developer Guide section on portability testing #37030

Merged
merged 2 commits into from
Jan 22, 2024
Merged

Small update to Developer Guide section on portability testing #37030

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8e7cfa4
src/doc/en/developer/portability_testing.rst: Update for rename Remot…
mkoeppe Dec 25, 2023
8c9332a
src/doc/en/developer/portability_testing.rst: Reformat some examples
mkoeppe Dec 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 29 additions & 24 deletions src/doc/en/developer/portability_testing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
---------------------------------------
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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::

Expand All @@ -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/
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
...


Expand Down Expand Up @@ -1204,13 +1209,13 @@ Using our pre-built Docker images for development in VS Code

`VS Code <https://code.visualstudio.com/>`_ is very
convenient for developing with Docker containers thanks to the `Visual
Studio Code Remote - Containers
<https://code.visualstudio.com/docs/remote/containers>`_ extension.
Studio Code Dev Containers
<https://code.visualstudio.com/docs/devcontainers/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
Expand All @@ -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.

Expand Down Expand Up @@ -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
<https://code.visualstudio.com/docs/remote/devcontainerjson-reference>`_
and the `GitHub introduction to dev containers
Expand Down