Skip to content

Commit 5dc4e9a

Browse files
author
Release Manager
committed
gh-37030: Small update to Developer Guide section on portability testing <!-- ^^^^^ 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
2 parents e2aef38 + 8c9332a commit 5dc4e9a

File tree

1 file changed

+29
-24
lines changed

1 file changed

+29
-24
lines changed

src/doc/en/developer/portability_testing.rst

Lines changed: 29 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Testing on Multiple Platforms
99
=============================
1010

1111
Sage is intended to build and run on a variety of platforms,
12-
including all major Linux distributions, as well as MacOS, and
12+
including all major Linux distributions, as well as macOS, and
1313
Windows (with WSL).
1414

1515
There is considerable variation among these platforms.
@@ -128,9 +128,9 @@ Typical Docker images provide minimal installations of packages only::
128128

129129
As you can see above, the image ``ubuntu:latest`` has neither a Python nor
130130
a GCC installed, which are among the build prerequisites of Sage. We
131-
need to install them using the distribution's package manager first.
131+
need to install them using the Linux distribution's package manager first.
132132

133-
Sage facilitates testing various distributions on Docker as follows.
133+
Sage facilitates testing various Linux distributions on Docker as follows.
134134

135135
Discovering the system's package system
136136
---------------------------------------
@@ -142,7 +142,7 @@ Discovering the system's package system
142142

143143
Let's install gcc, hoping that the Ubuntu package providing it is
144144
simply named ``gcc``. If we forgot what the package manager on
145-
Debian-derived distributions is called, we can ask Sage for a
145+
Debian-derived Linux distributions is called, we can ask Sage for a
146146
reminder::
147147

148148
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
190190
From this information, we know that we can use the following command
191191
on our container to install the necessary build prerequisites::
192192

193-
root@39d693b2a75d:/sage# apt-get install binutils make m4 perl python3 tar bc gcc g++ ca-certificates
193+
root@39d693b2a75d:/sage# apt-get install binutils make m4 perl python3 \
194+
tar bc gcc g++ ca-certificates
194195
Reading package lists... Done
195196
Building dependency tree
196197
Reading state information... Done
@@ -208,7 +209,8 @@ Now we can start the build::
208209
root@39d693b2a75d:/sage# ./configure
209210
checking for a BSD-compatible install... /usr/bin/install -c
210211
checking for root user... yes
211-
configure: error: You cannot build Sage as root, switch to an unprivileged user. (If building in a container, use --enable-build-as-root.)
212+
configure: error: You cannot build Sage as root, switch to an unprivileged user.
213+
(If building in a container, use --enable-build-as-root.)
212214

213215
Let's just follow this helpful hint::
214216

@@ -225,14 +227,16 @@ Using Sage's database of equivalent distribution packages
225227
At the end of the ``./configure`` run, Sage issued a message like the
226228
following::
227229

228-
configure: notice: the following SPKGs did not find equivalent system packages: arb boost_cropped bzip2 ... zeromq zlib
230+
configure: notice: the following SPKGs did not find equivalent system packages:
231+
arb boost_cropped bzip2 ... zeromq zlib
229232
checking for the package system in use... debian
230-
configure: hint: installing the following system packages is recommended and may avoid building some of the above SPKGs from source:
233+
configure: hint: installing the following system packages is recommended and
234+
may avoid building some of the above SPKGs from source:
231235
configure: $ sudo apt-get install libflint-arb-dev ... libzmq3-dev libz-dev
232236
configure: After installation, re-run configure using:
233237
configure: $ make reconfigure
234238

235-
This information comes from Sage's database of equivalent distribution
239+
This information comes from Sage's database of equivalent system
236240
packages. For example::
237241

238242
root@39d693b2a75d:/sage# ls build/pkgs/arb/distros/
@@ -268,9 +272,9 @@ corresponding to its current state::
268272

269273
root@39d693b2a75d:/sage# ^D
270274
[mkoeppe@sage worktree-ubuntu-latest]$ docker ps -a | head -n3
271-
CONTAINER ID IMAGE COMMAND CREATED STATUS
272-
39d693b2a75d ubuntu:latest "/bin/bash" 8 minutes ago Exited (0) 6 seconds ago
273-
9f3398da43c2 ubuntu:latest "/bin/bash" 8 minutes ago Exited (0) 8 minutes ago
275+
CONTAINER ID IMAGE COMMAND CREATED STATUS
276+
39d693b2a75d ubuntu:latest "/bin/bash" 8 minutes ago Exited (0) 6 seconds ago
277+
9f3398da43c2 ubuntu:latest "/bin/bash" 8 minutes ago Exited (0) 8 minutes ago
274278
[mkoeppe@sage worktree-ubuntu-latest]$ docker commit 39d693b2a75d ubuntu-latest-minimal-17
275279
sha256:4151c5ca4476660f6181cdb13923da8fe44082222b984c377fb4fd6cc05415c1
276280

@@ -506,7 +510,8 @@ might not work on all platforms, ``surf``, which was marked as
506510
...
507511
Makefile:31: recipe for target 'surf' failed
508512
make: *** [surf] Error 1
509-
The command '/bin/sh -c make SAGE_SPKG="sage-spkg -y -o" ${USE_MAKEFLAGS} ${TARGETS_PRE}' returned a non-zero code: 2
513+
The command '/bin/sh -c make SAGE_SPKG="sage-spkg -y -o" ${USE_MAKEFLAGS} ${TARGETS_PRE}'
514+
returned a non-zero code: 2
510515

511516
Note that no image id is shown at the end; the build failed, and no
512517
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``)::
688693

689694
Let's verify that the images are available::
690695

691-
(base) egret:~/s/sage/sage-rebasing/worktree-algebraic-2018-spring (mkoeppe *$%>)$ docker images | head
692-
REPOSITORY TAG IMAGE ID
693-
sage-centos-8-standard-with-targets 9.1.beta9-435-g861ba33bbc-dirty 7ecfa86fceab
694-
sage-centos-8-standard-configured 9.1.beta9-435-g861ba33bbc-dirty 4314929e2b4c
695-
sage-centos-8-standard-with-system-packages 9.1.beta9-435-g861ba33bbc-dirty 4bb14c3d5646
696+
[mkoeppe@sage sage]$ docker images | head
697+
REPOSITORY TAG IMAGE ID
698+
sage-centos-8-standard-with-targets 9.1.beta9-435-g861ba33bbc-dirty 7ecfa86fceab
699+
sage-centos-8-standard-configured 9.1.beta9-435-g861ba33bbc-dirty 4314929e2b4c
700+
sage-centos-8-standard-with-system-packages 9.1.beta9-435-g861ba33bbc-dirty 4bb14c3d5646
696701
...
697702

698703

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

12051210
`VS Code <https://code.visualstudio.com/>`_ is very
12061211
convenient for developing with Docker containers thanks to the `Visual
1207-
Studio Code Remote - Containers
1208-
<https://code.visualstudio.com/docs/remote/containers>`_ extension.
1212+
Studio Code Dev Containers
1213+
<https://code.visualstudio.com/docs/devcontainers/containers>`_ extension.
12091214

12101215
If the extension is not already installed, then in VS Code, click the
12111216
"Extension" icon on the left (or press :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`X`;
12121217
on macOS, :kbd:`Command` + :kbd:`Shift` + :kbd:`X`) to open a list of
1213-
extensions. Search for "Remote - Containers" and install it.
1218+
extensions. Search for "Dev Containers" and install it.
12141219

12151220
The extension needs a ``devcontainer.json`` configuration file to work. Sage
12161221
provides sample ``devcontainer.json`` configuration files
@@ -1220,11 +1225,11 @@ purpose.
12201225

12211226
If you open the sage folder in VS Code, it may prompt you whether you would like to open the current
12221227
directory in the dev container (yes). If it does not, use the command palette
1223-
(:kbd:`Ctrl` + :kbd:`Shift` + :kbd:`P`), enter the command "Remote-Containers:
1228+
(:kbd:`Ctrl` + :kbd:`Shift` + :kbd:`P`), enter the command "Dev Containers:
12241229
Reopen Folder in Container" , and hit :kbd:`Enter`.
12251230

12261231
If the above ``code .`` command does not work, start VS Code as a regular
1227-
application, then in the command palette of VS Code, enter "Remote-Containers:
1232+
application, then in the command palette of VS Code, enter "Dev Containers:
12281233
Open Folder in Container", and hit :kbd:`Enter`, and choose the directory
12291234
``$SAGE_ROOT`` of your local Sage repository.
12301235

@@ -1271,7 +1276,7 @@ in a terminal, `open a new terminal in VS Code
12711276
``configure`` script.
12721277

12731278
You can edit a copy of the configuration file to change to a different platform, another
1274-
version, or build stage. After editing the configuration file, run "Remote-Containers: Rebuild Container" from the command
1279+
version, or build stage. After editing the configuration file, run "Dev Containers: Rebuild Container" from the command
12751280
palette. See the `VS Code devcontainer.json reference
12761281
<https://code.visualstudio.com/docs/remote/devcontainerjson-reference>`_
12771282
and the `GitHub introduction to dev containers

0 commit comments

Comments
 (0)