Skip to content

Commit

Permalink
gh-37030: Small update to Developer Guide section on portability testing
Browse files Browse the repository at this point in the history 
    
<!-- ^^^^^
Please provide a concise, informative and self-explanatory title.
Don't put issue numbers in there, do this in the PR body below.
For example, instead of "Fixes #1234" use "Introduce new method to
calculate 1+1"
-->
<!-- Describe your changes here in detail -->

Split out from #36954 for easier review.

<!-- Why is this change required? What problem does it solve? -->
<!-- If this PR resolves an open issue, please link to it here. For
example "Fixes #12345". -->
<!-- If your change requires a documentation PR, please link it
appropriately. -->

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->
<!-- If your change requires a documentation PR, please link it
appropriately -->
<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
<!-- Feel free to remove irrelevant items. -->

- [x] The title is concise, informative, and self-explanatory.
- [ ] The description explains in detail what this PR is about.
- [x] I have linked a relevant issue or discussion.
- [ ] I have created tests covering the changes.
- [ ] I have updated the documentation accordingly.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on
- #12345: short description why this is a dependency
- #34567: ...
-->

<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
    
URL: #37030
Reported by: Matthias Köppe
Reviewer(s): Kwankyu Lee
  • Loading branch information
Release Manager committed Jan 20, 2024
2 parents e2aef38 + 8c9332a commit 5dc4e9a
Showing 1 changed file with 29 additions and 24 deletions.
53 changes: 29 additions & 24 deletions src/doc/en/developer/portability_testing.rst
View file
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: $ make reconfigure

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

0 comments on commit 5dc4e9a

Please sign in to comment.