在多个平台上测试

Sage旨在构建和运行在各种平台上，包括所有主要的Linux发行版，以及MacOS，以及带有WSL(Windows Subsystem For Linux)的Windows。

这些平台之间存在着相当大的差异。为了确保Sage继续在用户的计算机上正确构建，测试对Sage的更改是至关重要的，尤其是在各种平台上添加或升级外部包时。

使用GitHub操作测试PR

GitHub Actions 正在自动和持续地测试GitHub PR，以及早发现错误并确保代码质量。特别是，构建和测试工作流执行Sage的增量构建，并在包括Ubuntu、MacOS和Conda在内的一些主要平台上运行文档测试。

Sage BuildBots

在新版本发布之前，发布经理运行一系列 buildbots 以确保Sage在我们所有支持的平台上正确构建。

SAGE-Release的测试报告

我们鼓励Sage开发人员和用户测试在 Sage Release 并通过响应通知来报告结果(成功和失败)。

使用Docker在多个平台上进行测试

Docker 是一款流行的虚拟化软件，在共享的Linux内核上的容器中运行Linux操作系统镜像(“Docker镜像”)。这些容器可以在您的Linux、Mac或Windows机器上使用Docker客户端运行，也可以在各种云服务上运行。

要开始，您需要安装 Docker client 。这些客户端可用于Linux、Mac和Windows。后者的客户端称为“Docker Desktop”。

确保您的Docker客户端配置为为容器提供足够的RAM(8 GB是一个很好的选择)。在Docker Desktop中，此设置位于首选项->资源->高级。

备注

本节中的所有示例都是使用Docker Desktop for Mac获得的；但 command-line user interface 对于其他平台是相同的。

或者，您也可以使用具有Docker-in-Docker功能的容器在GitHub代码空间(或其他云服务)中运行Docker。Sage提供了合适的开发容器配置 .devcontainer/tox-docker-in-docker ：

所有主要的Linux发行版都提供现成的Docker映像，这些映像通过以下方式发布 Docker Hub 或其他容器注册表。例如，要以交互方式运行当前稳定(LTS)版本的Ubuntu，可以使用Shell命令：：

[mkoeppe@sage sage]$ docker run -it ubuntu:latest
root@9f3398da43c2:/#

这里 ubuntu 被称为“图像(名称)”，并且 latest 作为“标签”。Ubuntu的其他版本在不同的标签下可用，例如 xenial 或 devel 。

上面的命令将您放入容器：：

root@9f3398da43c2:/# uname -a
Linux 9f3398da43c2 4.19.76-linuxkit #1 SMP Thu Oct 17 19:31:58 UTC 2019 x86_64 x86_64 x86_64 GNU/Linux
root@9f3398da43c2:/# df -h
Filesystem      Size  Used Avail Use% Mounted on
overlay         181G  116G   56G  68% /
tmpfs            64M     0   64M   0% /dev
tmpfs           2.7G     0  2.7G   0% /sys/fs/cgroup
shm              64M     0   64M   0% /dev/shm
/dev/sda1       181G  116G   56G  68% /etc/hosts
tmpfs           2.7G     0  2.7G   0% /proc/acpi
tmpfs           2.7G     0  2.7G   0% /sys/firmware

退出Shell将终止容器：：

root@9f3398da43c2:/# ^D
[mkoeppe@sage sage]$

让我们使用一个完全干净的Sage源码树。如果您使用的是Git，这是一个获得Git的好方法(不会丢失 SAGE_LOCAL )是通过创建新的工作树：：

[mkoeppe@sage sage] git worktree add worktree-ubuntu-latest
[mkoeppe@sage sage] cd worktree-ubuntu-latest
[mkoeppe@sage worktree-ubuntu-latest] ls
COPYING.txt ... Makefile ... configure.ac ... src tox.ini

这不是自举的 (configure 丢失)，所以让我们引导它：：

[mkoeppe@sage worktree-ubuntu-latest] make configure
...

我们可以使用相同的图像再次启动容器， ubuntu:latest ，但这一次我们将当前目录挂载到其中：：

[mkoeppe@sage worktree-ubuntu-latest]$ docker run -it --mount type=bind,source=$(pwd),target=/sage ubuntu:latest
root@39d693b2a75d:/# mount | grep sage
osxfs on /sage type fuse.osxfs (rw,nosuid,nodev,relatime,user_id=0,group_id=0,allow_other,max_read=1048576)
root@39d693b2a75d:/# cd sage
root@39d693b2a75d:/sage# ls
COPYING.txt ... Makefile ... config configure configure.ac ... src tox.ini

典型的Docker映像仅提供最少的程序包安装：

root@39d693b2a75d:/sage# command -v python
root@39d693b2a75d:/sage# command -v gcc
root@39d693b2a75d:/sage#

正如您在上面看到的，该图像 ubuntu:latest 既没有安装 Python ，也没有安装GCC，这两个都是Sage的构建先决条件之一。我们需要首先使用Linux发行版的包管理器安装它们。

Sage为在Docker上测试各种Linux发行版提供了便利，如下所示。

发现系统的套餐系统

root@39d693b2a75d:/sage# build/bin/sage-guess-package-system
debian

让我们安装GCC，希望提供它的Ubuntu包被简单地命名为 gcc 。如果我们忘记了Debian派生的Linux发行版上的包管理器是什么，我们可以要求Sage提醒：：

root@39d693b2a75d:/sage# build/bin/sage-print-system-package-command debian install gcc
apt-get install gcc

我们记住，我们需要首先从服务器获取当前的包列表：：

root@39d693b2a75d:/sage# apt-get update
root@39d693b2a75d:/sage# apt-get install gcc

使用Sage的分发先决条件数据库

Sage发行版的源代码包含各种发行版的包管理器中的包名称数据库。例如，文件 build/pkgs/_prereq/distros/debian.txt 包含以下内容

# This file, build/pkgs/_prereq/distros/debian.txt, contains names
# of Debian/Ubuntu packages needed for installation of Sage from source.
#
# In addition, the files build/pkgs/SPKG/distros/debian.txt contain the names
# of packages that provide the equivalent of SPKG.
#
# Everything on a line after a # character is ignored.
binutils
make
m4
perl
# python3-minimal is not enough on debian buster, ubuntu bionic - it does not have urllib
python3    # system python for bootstrapping the build
tar
bc
gcc
# On debian buster, need C++ even to survive 'configure'. Otherwise:
# checking how to run the C++ preprocessor... /lib/cpp
# configure: error: in `/sage':
# configure: error: C++ preprocessor "/lib/cpp" fails sanity check
g++
# Needed if we download some packages from a https upstream URL
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
tar is already the newest version (1.29b-2ubuntu0.1).
The following additional packages will be installed:
...
Done.

《Sage》 Installation Guide 还为某些发行版提供了这样的命令行；这些命令行是从包名数据库中自动生成的。)

现在我们可以开始构建：：

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.)

让我们遵循这个有用的提示：：

root@39d693b2a75d:/sage# ./configure --enable-build-as-root
checking for a BSD-compatible install... /usr/bin/install -c
...

使用Sage的等效分发包数据库

在结束时， ./configure Run，Sage发布了如下消息：

configure: notice: the following SPKGs did not find equivalent system packages:
                   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:   $ sudo apt-get install ... libzmq3-dev libz-dev
configure: After installation, re-run configure using:
configure:   $ make reconfigure

该信息来自Sage的等效系统包数据库。例如：：

$ ls build/pkgs/flint/distros/
alpine.txt  cygwin.txt  fedora.txt   gentoo.txt    macports.txt  opensuse.txt  void.txt
conda.txt   debian.txt  freebsd.txt  homebrew.txt  nix.txt       repology.txt
$ cat build/pkgs/flint/distros/debian.txt
libflint-dev

请注意，这些包等效项是基于发行版的当前稳定或测试版本；不保证这些包存在于每个发行版或派生发行版中。

无论系统上安装了构成最低构建先决条件的包集的哪个超集，Sage发行版都可以正确构建。如果没有，这是Sage发行版的错误，应该报告并在票证上修复。错误报告的关键部分是系统的配置，特别是已安装程序包及其版本的列表。

让我们安装这些程序包的子集：

root@39d693b2a75d:/sage# apt-get install libbz2-dev bzip2 libz-dev
Reading package lists... Done
...
Setting up zlib1g-dev:amd64 (1:1.2.11.dfsg-0ubuntu2) ...
root@39d693b2a75d:/sage#

将容器提交到磁盘

终止容器后，以下命令显示您刚刚退出的容器的状态：

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

我们可以使用以下命令返回到容器：：

[mkoeppe@sage worktree-ubuntu-latest]$ docker start -a -i 39d693b2a75d
root@9f3398da43c2:/#

这里, 39d693b2a75d 是容器ID，它出现在Shell提示和 docker ps 。

我们可以创建与其当前状态对应的新映像：：

root@39d693b2a75d:/# ^D
[mkoeppe@sage worktree-ubuntu-latest]$ docker commit 39d693b2a75d ubuntu-latest-minimal-17
sha256:4151c5ca4476660f6181cdb13923da8fe44082222b984c377fb4fd6cc05415c1

哪里 ubuntu-latest-minimal-17 是新图像的任意符号名称。该命令的输出是新图像的ID。我们可以使用符号名称或ID来引用新图像。

我们可以运行映像并获得一个新容器，其状态与我们终止的容器相同。我们再次希望将工作树装载到其中；否则，因为我们没有创建副本，所以新容器将无法访问工作树：：

[mkoeppe@sage worktree-ubuntu-latest]$ docker run -it \
  --mount type=bind,source=$(pwd),target=/sage ubuntu-latest-minimal-17
root@73987568712c:/# cd sage
root@73987568712c:/sage# command -v gcc
/usr/bin/gcc
root@73987568712c:/sage# command -v bunzip2
/usr/bin/bunzip2
root@73987568712c:/sage# ^D
[mkoeppe@sage worktree-ubuntu-latest]$

形象 ubuntu-latest-minimal-17 可以在我们想要的容器中运行，也可以与其他用户或开发人员共享，这样他们就可以在自己机器的容器中运行它。(请参阅Docker文档，了解如何 share images on Docker Hub 或发送到 save images to a tar archive 。)

这有助于协作修复Sage发行版的可移植性错误。在容器上重现可移植性错误后，几个开发人员可以使用运行在他们各自机器上的容器来修复该错误。

正在生成dockerfile

Sage还提供了一个脚本来生成 Dockerfile ，这是自动构建新映像的秘诀：：

[mkoeppe@sage sage]$ build/bin/write-dockerfile.sh debian ":standard: :optional:" > Dockerfile

(第二个参数传递给 sage -package list 以查找列出的程序包类型的程序包。)

这个 Dockerfile 指示命令 docker build 建立一个新的码头工人形象。让我们快速查看一下生成的文件；这是略微简化的：

[mkoeppe@sage sage]$ cat Dockerfile
# Automatically generated by SAGE_ROOT/build/bin/write-dockerfile.sh
# the :comments: separate the generated file into sections
# to simplify writing scripts that customize this file
...

首先，它指示 docker build 要从现有基本映像开始...：：

...
ARG BASE_IMAGE=ubuntu:latest
FROM ${BASE_IMAGE}
...

然后，要安装系统包...：：

...
RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -qqq --no-install-recommends --yes binutils make m4 perl python3 ... libzmq3-dev libz-dev && apt-get clean

然后，启动和配置...：：

RUN mkdir -p /sage
WORKDIR /sage
ADD Makefile VERSION.txt README.md bootstrap configure.ac sage ./
ADD src/doc/bootstrap src/doc/bootstrap
ADD m4 ./m4
ADD build ./build
RUN ./bootstrap
ADD src/bin src/bin
ARG EXTRA_CONFIGURE_ARGS=""
RUN ./configure --enable-build-as-root ${EXTRA_CONFIGURE_ARGS} || (cat config.log; exit 1)

最后，构建和测试...：：

ARG NUMPROC=8
ENV MAKE="make -j${NUMPROC}"
ARG USE_MAKEFLAGS="-k"
RUN make ${USE_MAKEFLAGS} base-toolchain
ARG TARGETS_PRE="all-sage-local"
RUN make ${USE_MAKEFLAGS} ${TARGETS_PRE}
ADD src src
ARG TARGETS="build ptest"
RUN make ${USE_MAKEFLAGS} ${TARGETS}

您可以通过将构建参数传递给命令来自定义映像构建过程 docker build 。例如：：

[mkoeppe@sage sage]$ docker build . -f Dockerfile \
  --build-arg BASE_IMAGE=ubuntu:latest \
  --build-arg NUMPROC=4 \
  --build-arg EXTRA_CONFIGURE_ARGS="--with-python=/usr/bin/python3.42"

这些参数(及其缺省值)使用 ARG 中的命令 Dockerfile 。

上面的命令将从头开始构建Sage，因此需要相当长的时间。相反，让我们只进行部分构建，由一个小程序包组成，方法是设置参数 TARGETS_PRE 和 TARGETS 。我们使用静默构建 (make V=0 )：

[mkoeppe@sage sage]$ docker build . -f Dockerfile \
  --build-arg TARGETS_PRE=ratpoints \
  --build-arg TARGETS=ratpoints \
  --build-arg USE_MAKEFLAGS="V=0"
Sending build context to Docker daemon    285MB
Step 1/28 : ARG BASE_IMAGE=ubuntu:latest
...
Step 2/28 : FROM ${BASE_IMAGE}
 ---> 549b9b86cb8d
...
Step 25/28 : RUN make SAGE_SPKG="sage-spkg -y -o" ${USE_MAKEFLAGS} ${TARGETS_PRE}
...
make[1]: Entering directory '/sage/build/make'
sage-logger -p 'sage-spkg -y -o  ratpoints-2.1.3.p5' '/sage/logs/pkgs/ratpoints-2.1.3.p5.log'
[ratpoints-2.1.3.p5] installing. Log file: /sage/logs/pkgs/ratpoints-2.1.3.p5.log
  [ratpoints-2.1.3.p5] successfully installed.
make[1]: Leaving directory '/sage/build/make'

real  0m18.886s
user  0m1.779s
sys   0m0.314s
Sage build/upgrade complete!
...
---> 2d06689d39fa
Successfully built 2d06689d39fa

我们现在可以使用上一步中显示的图像ID启动一个容器：：

[mkoeppe@sage sage]$ docker run -it 2d06689d39fa bash
root@fab59e09a641:/sage# ls -l logs/pkgs/
total 236
-rw-r--r-- 1 root root 231169 Mar 26 22:07 config.log
-rw-r--r-- 1 root root   6025 Mar 26 22:27 ratpoints-2.1.3.p5.log
root@fab59e09a641:/sage# ls -l local/lib/*rat*
-rw-r--r-- 1 root root 177256 Mar 26 22:27 local/lib/libratpoints.a

可以进一步定制映像构建过程，方法是编辑 Dockerfile 。例如，默认情况下，生成的 Dockerfile 配置、构建和测试Sage。通过删除或注释掉后者的命令，您可以将Dockerfile调整为在 configure 例如，阶段。

Dockerfile 是Dockerfile的默认文件名。您可以将其更改为任何其他名称，但建议使用 Dockerfile 作为前缀，例如 Dockerfile-debian-standard 。它应该放在以当前目录为根的树中 (. )；如果你想把它放在其他地方，你需要了解“Docker构建上下文”的细节。

Note that in contrast to the workflow described in the above sections, the Dockerfile copies a snapshot of your Sage worktree into the build container, using ADD commands, instead of mounting the directory into it. This copying is subject to the exclusions in the .gitignore file (via a symbolic link from .dockerignore). Therefore, only the sources are copied, but not your configuration (such as the file config.status), nor the $SAGE_LOCAL tree, nor any other build artefacts.

因此，您可以使用生成的 Dockerfile 来自您的主Sage开发树。启动时不一定要是dislean，而且构建根本不会写入其中。因此，即使在运行Docker构建时，您也可以继续编辑和编译您的Sage开发树。

使用Docker调试可移植性错误

让我们再做一次局部构建。我们选择了一个我们怀疑可能不是在所有平台上都能工作的包， surf ，并于2017年被标记为“试验性”：

[mkoeppe@sage sage]$ docker build . -f Dockerfile \
  --build-arg BASE_IMAGE=ubuntu:latest \
  --build-arg NUMPROC=4 \
  --build-arg TARGETS_PRE=surf \
  --build-arg TARGETS=surf
Sending build context to Docker daemon    285MB
Step 1/28 : ARG BASE_IMAGE=ubuntu:latest
Step 2/28 : FROM ${BASE_IMAGE}
 ---> 549b9b86cb8d
...
Step 24/28 : ARG TARGETS_PRE="all-sage-local"
 ---> Running in 17d0ddb5ad7b
Removing intermediate container 17d0ddb5ad7b
 ---> 7b51411520c3
Step 25/28 : RUN make SAGE_SPKG="sage-spkg -y -o" ${USE_MAKEFLAGS} ${TARGETS_PRE}
 ---> Running in 61833bea6a6d
make -j4 build/make/Makefile --stop
...
[surf-1.0.6-gcc6] Attempting to download package surf-1.0.6-gcc6.tar.gz from mirrors
...
[surf-1.0.6-gcc6] http://mirrors.mit.edu/sage/spkg/upstream/surf/surf-1.0.6-gcc6.tar.gz
...
[surf-1.0.6-gcc6] Setting up build directory for surf-1.0.6-gcc6
...
[surf-1.0.6-gcc6] /usr/bin/ld: cannot find -lfl
[surf-1.0.6-gcc6] collect2: error: ld returned 1 exit status
[surf-1.0.6-gcc6] Makefile:504: recipe for target 'surf' failed
[surf-1.0.6-gcc6] make[3]: *** [surf] Error 1
...
[surf-1.0.6-gcc6] Error installing package surf-1.0.6-gcc6
...
Makefile:2088: recipe for target '/sage/local/var/lib/sage/installed/surf-1.0.6-gcc6' failed
make[1]: *** [/sage/local/var/lib/sage/installed/surf-1.0.6-gcc6] Error 1
make[1]: Target 'surf' not remade because of errors.
make[1]: Leaving directory '/sage/build/make'
...
Error building Sage.

The following package(s) may have failed to build (not necessarily
during this run of 'make surf'):

* package:         surf-1.0.6-gcc6
  last build time: Mar 26 22:07
  log file:        /sage/logs/pkgs/surf-1.0.6-gcc6.log
  build directory: /sage/local/var/tmp/sage/build/surf-1.0.6-gcc6

...
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

请注意，最后没有显示任何映像id；构建失败，并且没有创建任何映像。但是，尝试构建的最后一步的容器存在：

[mkoeppe@sage sage]$ docker ps -a |head -n3
CONTAINER ID        IMAGE                      COMMAND                   CREATED             STATUS
61833bea6a6d        7b51411520c3               "/bin/sh -c 'make SA…"    9 minutes ago       Exited (2) 1 minute ago
73987568712c        ubuntu-latest-minimal-17   "/bin/bash"               24 hours ago        Exited (0) 23 hours ago

我们可以从容器复制构建目录以进行检查：：

[mkoeppe@sage sage]$ docker cp 61833bea6a6d:/sage/local/var/tmp/sage/build ubuntu-build
[mkoeppe@sage sage]$ ls ubuntu-build/surf*/src
AUTHORS         TODO            curve           misc
COPYING         acinclude.m4    debug           missing
ChangeLog       aclocal.m4      dither          mkinstalldirs
INSTALL         background.pic  docs            mt
Makefile        config.guess    draw            src
Makefile.am     config.log      drawfunc        surf.1
Makefile.global config.status   examples        surf.xpm
Makefile.in     config.sub      gtkgui          yaccsrc
NEWS            configure       image-formats
README          configure.in    install-sh

或者，我们可以使用 docker commit 如前所述，要从容器创建映像：：

[mkoeppe@sage sage]$ docker commit 61833bea6a6d
sha256:003fbd511016fe305bd8494bb1747f0fbf4cb2c788b4e755e9099d9f2014a60d
[mkoeppe@sage sage]$ docker run -it 003fbd511 bash
root@2d9ac65f4572:/sage# (cd /sage/local/var/tmp/sage/build/surf* && /sage/sage --buildsh)

Starting subshell with Sage environment variables set.  Don't forget
to exit when you are done.
...
Note: SAGE_ROOT=/sage
(sage-buildsh) root@2d9ac65f4572:surf-1.0.6-gcc6$ ls /usr/lib/libfl*
/usr/lib/libflint-2.5.2.so  /usr/lib/libflint-2.5.2.so.13.5.2  /usr/lib/libflint.a  /usr/lib/libflint.so
(sage-buildsh) root@2d9ac65f4572:surf-1.0.6-gcc6$ apt-get update && apt-get install apt-file
(sage-buildsh) root@2d9ac65f4572:surf-1.0.6-gcc6$ apt-file update
(sage-buildsh) root@2d9ac65f4572:surf-1.0.6-gcc6$ apt-file search "/usr/lib/libfl.a"
flex-old: /usr/lib/libfl.a
freebsd-buildutils: /usr/lib/libfl.a
(sage-buildsh) root@2d9ac65f4572:surf-1.0.6-gcc6$ apt-get install flex-old
(sage-buildsh) root@2d9ac65f4572:surf-1.0.6-gcc6$ ./spkg-install
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
...
  /usr/bin/install -c  surf /sage/local/bin/surf
 /usr/bin/install -c -m 644 ./surf.1 /sage/local/share/man/man1/surf.1
...
make[1]: Leaving directory '/sage/local/var/tmp/sage/build/surf-1.0.6-gcc6/src'
(sage-buildsh) root@2d9ac65f4572:surf-1.0.6-gcc6$ exit
root@2d9ac65f4572:/sage# exit
[mkoeppe@sage sage]$

这是一种典型的恶作剧。

使用TOX进行基于Docker的自动构建测试

tox 是一个Python包，它被广泛用于自动化Python项目的测试。

如果您在本地使用Docker，请安装 tox 用于您的系统Python，例如使用：：

[mkoeppe@sage sage]$ pip install --user tox

如果您使用我们的dev容器配置在GitHub代码空间上运行Docker-in-Docker .devcontainer/tox-docker-in-docker ， tox 已安装。

Sage在文件中提供了复杂的毒性配置 $SAGE_ROOT/tox.ini 用于可携带性测试。

毒素“环境”由一个符号名称来标识，符号名称由几个 Tox "factors" 。

这个 technology 系数描述环境是如何运行的：

• docker 如上所述构建Docker映像。

• local 而是在主机操作系统上运行测试。我们将在后面的小节中解释这项技术。

接下来的两个因素决定了主机系统配置： system factor 描述基本操作系统映像。

• 以下是例子 ubuntu-focal ， debian-buster ， archlinux-latest ， fedora-30 ， slackware-14.2 ， centos-7-i386 ，以及 ubuntu-bionic-arm64 。

• 看见 $SAGE_ROOT/tox.ini 查看完整的列表，以及它们对应于Docker Hub上的哪些图像。

这个 packages factor 描述在构建Sage之前要在系统上安装的系统程序包列表：

• minimal 安装Sage已知的系统程序包，以提供引导和构建Sage分发的最低前提条件。这与包裹相对应 _bootstrap 和 _prereq 。

• standard 此外，还安装与Sage发行版的标准包相同的所有已知系统包，对于这些包，机制 spkg-configure.m4 已经实施了。这对应于由：：列出的包：

  [mkoeppe@sage sage]$ sage --package list --has-file=spkg-configure.m4 :standard:
  

• maximal 对所有标准和可选程序包执行相同的操作。这对应于由：：列出的包：

  [mkoeppe@sage sage]$ sage --package list :standard: :optional:
  

这些因素由连字符连接，以命名系统配置，例如 debian-buster-standard 和 centos-7-i386-minimal 。

最后， configuration 系数(允许为空)控制 configure 脚本正在运行。

这些因素由连字符连接起来，以命名毒性环境。(因子的顺序并不重要；但是，为了保持一致性，并且由于排序的名称用于缓存目的，我们建议按列出的顺序使用因子。)

要运行环境：：

[mkoeppe@sage sage]$ tox -e docker-slackware-14.2-minimal
[mkoeppe@sage sage]$ tox -e docker-ubuntu-bionic-standard

的任意额外参数 docker build 可以通过环境变量提供 EXTRA_DOCKER_BUILD_ARGS 。例如，对于非静默生成 (make V=1 )，使用：：

[mkoeppe@sage sage]$ EXTRA_DOCKER_BUILD_ARGS="--build-arg USE_MAKEFLAGS=\"V=1\"" \
  tox -e docker-ubuntu-bionic-standard

默认情况下，毒素使用 TARGETS_PRE=all-sage-local 和 TARGETS=build ，从而在没有文档的情况下完成了Sage的构建。如果将位置参数传递给tox(与tox选项之间用 -- )，则两者都有 TARGETS_PRE 和 TARGETS 都被设定为这些论点。这样，您可以构建一些特定的包，而不是Sage的所有包，例如：：

[mkoeppe@sage sage]$ tox -e docker-centos-8-standard -- ratpoints

如果构建成功，这将创建一个名为 sage-centos-8-standard-with-targets:9.1.beta9-431-gca4b5b2f33-dirty ，在哪里

• 映像名称派生自TOX环境名称和后缀 with-targets 表示本局 make 中给出的目标 TARGETS 已经建成；

• 标记名称描述了源树的GIT修订版，按照 git describe --dirty 。

您也可以要求使用TOX来创建命名的中间图像。例如，安装完所有系统包后，创建与操作系统状态对应的镜像 (with-system-packages )和刚刚运行完 configure 脚本 (configured )：

[mkoeppe@sage sage]$ DOCKER_TARGETS="with-system-packages configured with-targets" \
  tox -e docker-centos-8-standard -- ratpoints
...
Sending build context to Docker daemon ...
Step 1/109 : ARG BASE_IMAGE=fedora:latest
Step 2/109 : FROM ${BASE_IMAGE} as with-system-packages
...
Step 109/109 : RUN yum install -y zlib-devel || echo "(ignoring error)"
...
Successfully built 4bb14c3d5646
Successfully tagged sage-centos-8-standard-with-system-packages:9.1.beta9-435-g861ba33bbc-dirty
Sending build context to Docker daemon ...
...
Successfully tagged sage-centos-8-standard-configured:9.1.beta9-435-g861ba33bbc-dirty
...
Sending build context to Docker daemon ...
...
Successfully tagged sage-centos-8-standard-with-targets:9.1.beta9-435-g861ba33bbc-dirty

让我们验证这些图像是否可用：：

[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
...

使用tox-e local-Direct在主机操作系统上进行自动构建测试

这个 local 相反，技术人员在主机操作系统上运行测试。

与之相对的是 docker 技术，它不会复制源树。从一个单独的、完全不受影响的git工作树中运行它是最直接的。

让我们尝试一下第一个变种 local 技术，毒素环境被称为 local-direct 。因为所有带有TOX的构建都是从引导源代码树开始的，所以您需要在系统中安装AutoTools和其他必备组件。看见 build/pkgs/_bootstrap/distros/*.txt 以获取提供这些先决条件的系统包的列表。

我们首先创建一个全新的(版本清洁的)GIT工作树：：

[mkoeppe@sage sage] git worktree add worktree-local
[mkoeppe@sage sage] cd worktree-local
[mkoeppe@sage worktree-local] ls
COPYING.txt ... Makefile ... configure.ac ... src tox.ini

同样，我们只构建了一个小包。构建目标可以作为位置参数传递(与tox选项用 -- )：

[mkoeppe@sage worktree-local] tox -e local-direct -- ratpoints
local-direct create: /Users/mkoeppe/.../worktree-local/.tox/local-direct
local-direct run-test-pre: PYTHONHASHSEED='2211987514'
...
src/doc/bootstrap:48: installing src/doc/en/installation/debian.txt...
bootstrap:69: installing 'config/config.rpath'
configure.ac:328: installing 'config/compile'
configure.ac:113: installing 'config/config.guess'
...
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
...
sage-logger -p 'sage-spkg -y -o  ratpoints-2.1.3.p5' '.../worktree-local/logs/pkgs/ratpoints-2.1.3.p5.log'
[ratpoints-2.1.3.p5] installing. Log file: .../worktree-local/logs/pkgs/ratpoints-2.1.3.p5.log
  [ratpoints-2.1.3.p5] successfully installed.
...
  local-direct: commands succeeded
  congratulations :)

让我们调查一下这里发生的事情：：

[mkoeppe@sage worktree-local]$ ls -la
total 2576
drwxr-xr-x  35 mkoeppe  staff    1120 Mar 26 22:20 .
drwxr-xr-x  63 mkoeppe  staff    2016 Mar 27 09:35 ..
...
lrwxr-xr-x   1 mkoeppe  staff      10 Mar 26 20:34 .dockerignore -> .gitignore
-rw-r--r--   1 mkoeppe  staff      74 Mar 26 20:34 .git
...
-rw-r--r--   1 mkoeppe  staff    1212 Mar 26 20:41 .gitignore
...
drwxr-xr-x   7 mkoeppe  staff     224 Mar 26 22:11 .tox
...
-rw-r--r--   1 mkoeppe  staff    7542 Mar 26 20:41 Makefile
...
lrwxr-xr-x   1 mkoeppe  staff     114 Mar 26 20:45 config.log -> .tox/local-direct/log/config.log
-rwxr-xr-x   1 mkoeppe  staff   90411 Mar 26 20:46 config.status
-rwxr-xr-x   1 mkoeppe  staff  887180 Mar 26 20:45 configure
-rw-r--r--   1 mkoeppe  staff   17070 Mar 26 20:41 configure.ac
...
lrwxr-xr-x   1 mkoeppe  staff     103 Mar 26 20:45 logs -> .tox/local-direct/log
drwxr-xr-x  24 mkoeppe  staff     768 Mar 26 20:45 m4
lrwxr-xr-x   1 mkoeppe  staff     105 Mar 26 20:45 prefix -> .tox/local-direct/local
-rwxr-xr-x   1 mkoeppe  staff    4868 Mar 26 20:34 sage
drwxr-xr-x  16 mkoeppe  staff     512 Mar 26 20:46 src
-rw-r--r--   1 mkoeppe  staff   13478 Mar 26 20:41 tox.ini
drwxr-xr-x   4 mkoeppe  staff     128 Mar 26 20:46 upstream

没有 local 子目录。这是尽可能保持源树干净的策略的一部分。尤其是：

• tox 已将生成配置为使用单独的 $SAGE_LOCAL TOX环境目录下的目录中的层次结构 .tox/local-direct 。它创建了一个符号链接 prefix 为了方便起见，这一点如下：

  [mkoeppe@sage worktree-local]$ ls -l prefix/lib/*rat*
  -rw-r--r--  1 mkoeppe  staff  165968 Mar 26 20:46 prefix/lib/libratpoints.a
  

• 同样，它创建了一个单独的 logs 目录，同样在tox环境目录下，以及一个符号链接。

这使得高级用户可以测试多个 local 毒性环境(例如 local-direct )从一棵工作树中。但是，因为构建仍然编写配置脚本和构建构件(例如 config.status )到工作树中，只有一个 local 构建可以在给定的工作树中一次运行。

TOX环境目录将被重新用于下一个 tox 运行，这将因此执行增量构建。若要开始新的生成，可以使用 -r 选择。

使用tox-e local，在主机操作系统上使用尽力而为隔离进行自动构建测试

tox -e local (无 -direct )尝试与用户环境进行最佳隔离，如下所示：

• 所有环境变量都设置为标准值；但 MAKE 和 EXTRA_CONFIGURE_ARGS 。特别是， PATH 设置为恰好 /usr/bin:/bin:/usr/sbin:/sbin ；它不包括 /usr/local/bin 。

但是，请注意，各种包都有使用 /usr/local 或其他流行的文件系统位置，如 /opt/sfw/ 。因此，隔离是不完全的。vbl.使用 /usr/local 被认为是标准行为。另一方面，我们认为检查其他文件系统位置的包构建脚本是Sage发行版的错误，应该在票证上报告和修复。

在MacOS上使用尽力而为的独立安装HomeBREW进行自动构建测试

MacOS上的Xcode不提供引导Sage发行版的先决条件。安装它们的一个好方法是使用HomeBrew包管理器。

事实上，Sage提供了一个TOX环境，它可以自动安装HomeBREW的独立副本，并满足引导的所有先决条件：

[mkoeppe@sage worktree-local]$ tox -e local-homebrew-macos-minimal -- lrslib
local-homebrew-macos-minimal create: .../worktree-local/.tox/local-homebrew-macos-minimal
local-homebrew-macos-minimal run-test-pre: PYTHONHASHSEED='4246149402'
...
Initialized empty Git repository in .../worktree-local/.tox/local-homebrew-macos-minimal/homebrew/.git/
...
Tapped 2 commands and 4942 formulae (5,205 files, 310.7MB).
==> Downloading https://ftp.gnu.org/gnu/gettext/gettext-0.20.1.tar.xz
...
==> Pouring autoconf-2.69.catalina.bottle.4.tar.gz
...
==> Pouring pkg-config-0.29.2.catalina.bottle.1.tar.gz
  .../worktree-local/.tox/local-homebrew-macos-minimal/homebrew/Cellar/pkg-config/0.29.2: 11 files, 623.4KB
==> Caveats
==> gettext
gettext is keg-only, which means it was not symlinked into .../worktree-local/.tox/local-homebrew-macos-minimal/homebrew,
because macOS provides the BSD gettext library & some software gets confused if both are in the library path.

If you need to have gettext first in your PATH run:
  echo 'export PATH=".../worktree-local/.tox/local-homebrew-macos-minimal/homebrew/opt/gettext/bin:$PATH"' >> ~/.bash_profile

For compilers to find gettext you may need to set:
  export LDFLAGS="-L.../worktree-local/.tox/local-homebrew-macos-minimal/homebrew/opt/gettext/lib"
  export CPPFLAGS="-I.../worktree-local/.tox/local-homebrew-macos-minimal/homebrew/opt/gettext/include"
...
local-homebrew-macos-minimal run-test: commands[0] | bash -c 'export PATH=.../worktree-local/.tox/local-homebrew-macos-minimal/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin && . .homebrew-build-env && ./bootstrap && ./configure --prefix=.../worktree-local/.tox/local-homebrew-macos-minimal/local    && make -k V=0 ... lrslib'
...
bootstrap:69: installing 'config/config.rpath'
...
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
...
configure: notice: the following SPKGs did not find equivalent system packages: cbc cliquer ... tachyon xz zeromq
checking for the package system in use... homebrew
configure: hint: installing the following system packages is recommended and may avoid building some of the above SPKGs from source:
configure:   $ brew install cmake gcc gsl mpfi ninja openblas gpatch r readline xz zeromq
...
sage-logger -p 'sage-spkg -y -o  lrslib-062+autotools-2017-03-03.p1' '.../worktree-local/logs/pkgs/lrslib-062+autotools-2017-03-03.p1.log'
[lrslib-062+autotools-2017-03-03.p1] installing. Log file: .../worktree-local/logs/pkgs/lrslib-062+autotools-2017-03-03.p1.log
  [lrslib-062+autotools-2017-03-03.p1] successfully installed.
...
  local-homebrew-macos-minimal: commands succeeded
  congratulations :)

TOX环境使用子目录 homebrew 环境目录的 .tox/local-homebrew-macos-minimal 作为自制酒的前缀。此安装不会以任何方式与中的HomeBREW安装交互 /usr/local 你可能有过。

测试脚本设置 PATH 发送到 bin Homebrew前缀的目录，后跟 /usr/bin:/bin:/usr/sbin:/sbin 。然后，它使用该脚本 $SAGE_ROOT/.homebrew-build-env 要设置环境变量，以便Sage的构建脚本将找到“仅限keg”的包，例如 gettext 。

这个 local-homebrew-macos-minimal 环境未安装HomeBREW python3 包裹。它使用XCode的 /usr/bin/python3 作为系统 Python 。但是，由于缺少Sage视为依赖项的各种包，Sage构建了自己的这些包的副本和 python3 。

这个 local-homebrew-macos-standard 环境还安装(在其单独的Homebrew隔离副本中)Sage已知的所有Homebrew包， spkg-configure.m4 机制被实现；这类似于 docker-standard 前面所述的毒性环境。特别是，它安装并使用了HomeBrew python3 包裹。

通过使用配置因素，可以测试更多的变体。这个 local-homebrew-macos-standard-python3_xcode Environment安装相同的包，但使用XCode的 /usr/bin/python3 。

这个 local-homebrew-macos-standard-python3_pythonorg 预期在中安装Python3.10 /Library/Frameworks/Python.framework ；这是由python.org提供的二进制程序包自身安装的位置。

使用尽力隔离的Conda安装进行自动构建测试

Sage提供环境 local-conda-forge-standard 和 local-conda-forge-minimal 在子目录中创建独立的Miniconda安装 conda 环境目录的。它们不会以任何方式与您的系统上可能安装的其他 Python 或Minconda进行交互。

环境使用Conda-Forge通道并使用 python 包和来自此通道的编译器。

使用本地技术进行构建测试的选项

使用 local 可以通过设置环境变量来定制技术。

• 如果 SKIP_SYSTEM_PKG_INSTALL 设置为 1 (或 yes )，则在此运行中将跳过安装系统包的所有步骤。在重用以前创建的TOX环境时，此选项可以节省时间，还可以让开发人员更好地控制系统包的实验。

• 如果 SKIP_BOOTSTRAP 设置为 1 (或 yes )，则跳过引导阶段。当重复使用以前创建的毒性环境时，此选项可以节省时间。

• 如果 SKIP_CONFIGURE 设置为 1 (或 yes )，然后是 configure 脚本未显式运行。当重复使用以前创建的毒性环境时，此选项可以节省时间。( Makefile 仍可能使用以下选项重新运行配置 config.status --recheck 。)

这个 local 技术也定义了一个特殊的目标 bash ：而不是用来建造任何东西 make ，它只是启动了一个交互Shell。例如，与上述选项相结合：

[mkoeppe@sage worktree-local]$ SKIP_SYSTEM_PKG_INSTALL=yes SKIP_BOOTSTRAP=1 SKIP_CONFIGURE=1 tox -e local-homebrew-macos-minimal -- bash

基于GitHub动作的多平台自动测试

Sage源代码树包括GitHub操作的默认配置，每次将标记(但不是分支)推送到启用了GitHub操作的存储库时，该配置会在多个平台上运行可移植性测试。

特别是，它在每个版本标签上自动运行在我们的主存储库sagemath/sage上。

这是在文件中定义的

• $SAGE_ROOT/.github/workflows/ci-linux.yml (它调用 $SAGE_ROOT/.github/workflows/docker.yml )和

• $SAGE_ROOT/.github/workflows/ci-macos.yml <https://github.com/sagemath/sage/tree/develop/.github/workflows/ci-macos.yml> _.

GitHub Actions在具有7 GB RAM内存和14 GB SSD磁盘空间的双核计算机上运行这些构建作业。 here ，每个作业的时间限制为6小时。这可能仅够典型的 minimal 构建，然后 make ptest 为了成功；为了增加健壮性，我们将其拆分为两个工作。我们的工作流将与这两个作业中的各个构建阶段对应的Docker图像存储在 GitHub Packages (ghcr.io)。

构建日志可以在运行期间进行检查，并在工作流的所有作业完成后作为“构件”可用。每个作业都会生成一个tarball。“注释”突出显示在构建过程中发出的某些顶级错误或警告。

除了在我们的主存储库中自动运行之外，所有Sage开发人员都可以在Sage存储库的个人分支中对GitHub操作运行相同的测试。为了准备这个， enable GitHub Actions 在你的Sage储存库的叉子里。

像往常一样，我们假定 origin 是与Sage存储库的GitHub分支对应的远程服务器的名称：：

$ git remote -v | grep origin
origin         https://github.com/mkoeppe/sage.git (fetch)
origin         https://github.com/mkoeppe/sage.git (push)

然后，以下过程使用默认的系统配置集触发一系列测试。

• 将您的分支机构 origin (你的叉子)。

• 转到您的分支的Actions选项卡，并选择您想要运行的工作流，例如“CI Linux”。

• 点击工作流运行列表上方的“运行工作流”，并选择您的分支作为工作流运行的分支。

有关更多信息，请参见 GitHub documentation 。

或者，您也可以通过创建和推送定制标记来触发一系列测试，如下所示。

• 创建一个具有任意名称的(“轻量级”，而不是“带注释的”)标记，比如 ci (“持续融合”)：

  git tag -f ci
  

• 然后将标签推送到您的GitHub存储库：：

  git push -f origin ci
  

(在这两个命令中，“force”选项 (-f )允许覆盖该名称的先前标记。)

无论采用哪种方法，当工作流被触发时，您都可以使用存储库的“Actions”选项卡中的Workflow Status页来检查它。

以下是阅读它的方法。左窗格中的每一项都代表特定系统配置上的Sage的完整版本。如果出现以下情况，则左窗格中的测试项将在左窗格中标记为绿色复选标记 make build doc-html 已完成，没有错误。(它还运行包测试套件和Sage文档测试，但这些测试中的失败不会反映在左窗格中；请参见下文。)

右侧的面板(“Artitures”)提供了可供下载的日志存档。

在右窗格中向下滚动显示“注解”：

• 对于每个包含生成错误的日志文件，都会显示红色的“检查失败”批注。例如，您可能会看到：

  docker (fedora-28, standard)
  artifacts/logs-commit-8ca1c2df8f1fb4c6d54b44b34b4d8320ebecb164-tox-docker-fedora-28-standard/logs/pkgs/sagetex-3.4.log#L1
  ==== ERROR IN LOG FILE artifacts/logs-commit-8ca1c2df8f1fb4c6d54b44b34b4d8320ebecb164-tox-docker-fedora-28-standard/logs/pkgs/sagetex-3.4.log ====
  

• 黄色的“Check Warning”注释。有两种类型：

  1. 包测试套件或Sage文档测试失败，如下所示：

     docker (fedora-30, standard)
     artifacts/logs-commit-8ca1c2df8f1fb4c6d54b44b34b4d8320ebecb164-tox-docker-fedora-30-standard/logs/ptest.log#L1
     ==== TESTSUITE FAILURE IN LOG FILE artifacts/logs-commit-8ca1c2df8f1fb4c6d54b44b34b4d8320ebecb164-tox-docker-fedora-30-standard/logs/ptest.log ====
     

  2. 来自./CONFIGURE关于找不到等效系统包的通知，如下所示：

     docker (fedora-31, standard)
     artifacts/logs-commit-8ca1c2df8f1fb4c6d54b44b34b4d8320ebecb164-tox-docker-fedora-31-standard/config.log#L1
     configure: notice: the following SPKGs did not find equivalent system packages: cbc cddlib cmake eclib ecm fflas_ffpack flint fplll givaro gp
     

单击注释并不会将您带到非常有用的位置。要查看详细信息，请单击窗格中的一项。这会将右窗格更改为日志查看器。

这个 docker 工作流自动将图像推送到 ghcr.io 。您可以在GitHub存储库的Packages选项卡中找到它们。

为了在您的计算机上使用它们，您需要首先生成一个个人访问令牌，提供 read:packages 范围如下。访问https://github.com/settings/tokens/new(这可能会提示您输入GitHub密码)。作为“Note”，键入“Access ghcr.io”；然后在“Select Scope”中，选中复选框 read:packages 。最后，按下底部的“生成令牌”按钮。这将进入一个显示您的令牌的页面，例如 de1ec7ab1ec0ffee5ca1dedbaff1ed0ddba11 。复制此内标识并将其粘贴到命令行：：

$ echo de1ec7ab1ec0ffee5ca1dedbaff1ed0ddba11 | docker login ghcr.io --username YOUR-GITHUB-USERNAME

当然，您可以将令牌替换为您的令牌，并且 YOUR-GITHUB-USERNAME 通过您的GitHub用户名。

现在您可以提取映像并运行它：：

$ docker pull ghcr.io/YOUR-GITHUB-USERNAME/sage/sage-fedora-31-standard-configured:f4bd671
$ docker run -it ghcr.io/YOUR-GITHUB-USERNAME/sage/sage-fedora-31-standard-configured:f4bd671 bash

使用我们在ghcr.io上发布的预构建Docker映像

我们在GitHub Actions上的可移植配置项构建 Docker images 适用于所有经过测试的Linux平台(和系统包配置)，并在 GitHub Packages (ghcr.io)。

这使得开发人员可以轻松地调试在给定平台的构建日志中显示的问题。

与最新开发版本对应的镜像版本接收额外的Docker标签 dev ，例如，请参阅平台的Docker图像 ubuntu-focal-standard 。因此，例如，以下命令将起作用：

$ docker run -it ghcr.io/sagemath/sage/sage-ubuntu-focal-standard-with-targets-optional:dev bash
Unable to find image 'ghcr.io/sagemath/sage/sage-ubuntu-focal-standard-with-targets-optional:dev' locally
dev: Pulling from sagemath/sage/sage-ubuntu-focal-standard-with-targets-optional
d5fd17ec1767: Already exists
67586203f0c7: Pull complete
b63c529f4777: Pull complete
...
159775d1a3d2: Pull complete
Digest: sha256:e6ba5e12f59c6c4668692ef4cfe4ae5f242556482664fb347bf260f32bf8e698
Status: Downloaded newer image for ghcr.io/sagemath/sage/sage-ubuntu-focal-standard-with-targets-optional:dev
root@8055a7ba0607:/sage# ./sage
┌────────────────────────────────────────────────────────────────────┐
│ SageMath version 9.6, Release Date: 2022-05-15                     │
│ Using Python 3.8.10. Type "help()" for help.                       │
└────────────────────────────────────────────────────────────────────┘
sage:

名称以后缀结尾的图像 -with-targets-optional 是完整生成和一系列 make ptest 。它们还包含源代码树的副本以及构建和测试的完整日志。

还有 smaller images corresponding to earlier build stages 可用：

• -with-system-packages 提供安装了系统包的系统安装，没有源代码树，

• -configured 包含部分源代码树 (SAGE_ROOT )，并已完成引导阶段和运行 configure 脚本，

• -with-targets-pre 包含部分源代码树 (SAGE_ROOT )和所有非Python包的完整安装 (SAGE_LOCAL ),

• -with-targets 包含完整的源代码树和Sage的完整安装，包括HTML文档，但是 make ptest 尚未运行。

站台	图片
ubuntu -值得信赖-工具链-GCC_9    ‑minimal
‑standard
‑maximal
ubuntu -异种-工具链-GCC_9    ‑minimal
‑standard
‑maximal
ubuntu -仿生-GCC_8    ‑minimal
‑standard
‑maximal
ubuntu -焦点    ‑minimal
‑standard
‑maximal
ubuntu -果酱    ‑minimal
‑standard
‑maximal
ubuntu -农历    ‑minimal
‑standard
‑maximal
ubuntu -Mantic    ‑minimal
‑standard
‑maximal
debian -巴斯特-GCC_spkg    ‑minimal
‑standard
‑maximal
debian -靶心    ‑minimal
‑standard
‑maximal
debian -书呆子    ‑minimal
‑standard
‑maximal
debian --特里克西    ‑minimal
‑standard
‑maximal
debian -SID    ‑minimal
‑standard
‑maximal
linuxmint -20.1    ‑minimal
‑standard
‑maximal
linuxmint -20.2    ‑minimal
‑standard
‑maximal
linuxmint -20.3    ‑minimal
‑standard
‑maximal
linuxmint -21    ‑minimal
‑standard
‑maximal
linuxmint -21.1    ‑minimal
‑standard
‑maximal
linuxmint -21.2    ‑minimal
‑standard
‑maximal
fedora -30    ‑minimal
‑standard
‑maximal
fedora -31    ‑minimal
‑standard
‑maximal
fedora -32    ‑minimal
‑standard
‑maximal
fedora -33    ‑minimal
‑standard
‑maximal
fedora -34    ‑minimal
‑standard
‑maximal
fedora -35    ‑minimal
‑standard
‑maximal
fedora -36    ‑minimal
‑standard
‑maximal
fedora -37    ‑minimal
‑standard
‑maximal
fedora -38    ‑minimal
‑standard
‑maximal
fedora -39    ‑minimal
‑standard
‑maximal
centos -7-开发工具集-GCC_11    ‑minimal
‑standard
‑maximal
centos -STREAM-8-PYTHON 3.9    ‑minimal
‑standard
‑maximal
centos -STREAM-9-PYTHON 3.9    ‑minimal
‑standard
‑maximal
almalinux -8-吡咯烷酮3.9    ‑minimal
‑standard
‑maximal
almalinux -9-python3.11    ‑minimal
‑standard
‑maximal
gentoo - Python 3.10    ‑minimal
‑standard
‑maximal
gentoo - Python 3.11    ‑minimal
‑standard
‑maximal
archlinux -最新消息    ‑minimal
‑standard
‑maximal
opensuse -15.3-GCC_11- Python 3.9    ‑minimal
‑standard
‑maximal
opensuse -15.4-GCC_11- Python 3.10    ‑minimal
‑standard
‑maximal
opensuse -15.5-GCC_11- Python 3.11    ‑minimal
‑standard
‑maximal
opensuse -风滚草- Python 3.10    ‑minimal
‑standard
‑maximal
opensuse -风滚草    ‑minimal
‑standard
‑maximal
conda --FORGE-PYTHON 3.11    ‑standard
‑maximal
ubuntu -仿生-GCC_8-i386    ‑minimal
‑standard
‑maximal
debian -牛眼-i386    ‑minimal
‑standard
‑maximal

使用我们预构建的Docker映像在VS代码中进行开发

VS Code 对于使用Docker容器进行开发非常方便，这要归功于 Visual Studio Code Dev Containers 分机。

如果该扩展尚未安装，则在VS代码中，单击左侧的“扩展”图标(或按 Ctrl + Shift + X ；在MacOS上， Command + Shift + X )打开分机列表。搜索“Dev Containers”并安装它。

该扩展需要一个 devcontainer.json 配置文件才能工作。Sage提供样本 devcontainer.json 配置文件 $SAGE_ROOT/.devcontainer/*/devcontainer.json 为了这个目的。

如果您在VS代码中打开SAGE文件夹，它可能会提示您是否要打开dev容器中的当前目录(是)。如果没有，请使用命令选项板 (Ctrl + Shift + P )，输入命令Dev Containers：ReOpen Folders in Container，点击 Enter 。

如果出现上述情况 code . 命令不起作用，启动VS Code作为常规应用程序，然后在VS Code的命令调色板中，输入“Dev Containers：Open Folders in Container”，然后点击 Enter ，并选择目录 $SAGE_ROOT 您当地的Sage存储库的。

然后，VS代码会提示您选择开发容器配置。例如，选择“ubuntu-JAMI-Standard” .devcontainer/portability-ubuntu-jammy-standard/devcontainer.json ，它基于以下内容使用Docker映像 ubuntu-jammy-standard ，Sage的最新开发版本 (dev 标记)，以及Sage发行版的完整安装 (with-targets )。其他dev容器配置如下所述。

一旦VS代码开始配置dev容器，通过单击“show log”，您可以看到它做了什么：

• 它从ghcr.io(通过 $SAGE_ROOT/.devcontainer/portability-Dockerfile )；请注意，这些是多GB的图像，因此可能需要一段时间。

• 作为“onCreateCommand”的一部分，它安装额外的系统包以支持VS代码和用于开发。

• 然后，作为“updateContent Command”的一部分，它引导和配置源树，并开始从源构建Sage，重用安装 (SAGE_LOCAL ， SAGE_VENV )从预先构建的映像中。

在VS代码完成对dev容器的配置之后(当消息“完成。按任何键关闭终端。”出现在名为“Configuring”的终端中)，您的本地Sage存储库位于 $SAGE_ROOT 在目录中的容器中可用 /workspaces/<repository name> 。要在终端中使用Sage， open a new terminal in VS Code ，类型 ./sage 并击中了 Enter 。

备注

你的Sage在 $SAGE_ROOT 在dev容器中进行了配置和重建。特别是， $SAGE_ROOT/venv ， $SAGE_ROOT/prefix ，以及(可能) $SAGE_ROOT/logs 将是在dev容器中工作但不在本地文件系统中工作的符号链接；还有脚本 $SAGE_ROOT/sage 不会奏效的。因此，在使用dev容器之后，您将需要删除 logs 如果它是符号链接，则重新运行 configure 剧本。

Sage源代码树包含我们的可移植配置项为其构建Docker映像的所有平台的预制配置文件，这两个平台都位于 minimal 和 standard 系统包配置。可以使用以下命令生成配置文件 tox -e update_docker_platforms (见 $SAGE_ROOT/tox.ini 对于生效的环境变量)。

您可以编辑配置文件的副本，以更改为不同的平台、其他版本或生成阶段。编辑完配置文件后，从命令面板运行“Dev Containers：Rebuild Container”。请参阅 VS Code devcontainer.json reference 以及 GitHub introduction to dev containers 以获取更多信息。

除 $SAGE_ROOT/.devcontainer/portability-.../devcontainer.json 文件，Sage还提供了其他几个示例 devcontainer.json 目录中的配置文件 $SAGE_ROOT/.devcontainer 。

命名的文件 $SAGE_ROOT/.devcontainer/develop-.../devcontainer.json 从提供SageMath的公共Docker镜像配置容器，然后通过从当前源树构建来更新该容器中的SageMath安装。

• develop-docker-computop/devcontainer.json 将容器配置为 Docker image from the 3-manifolds project ，提供Snappy、Regina、PHCPack等。

在VS代码完成配置dev容器之后，要在终端中使用Sage， open a new terminal in VS Code ，类型 ./sage 并击中了 Enter 。

命名的文件 $SAGE_ROOT/.devcontainer/downstream-.../devcontainer.json 使用从包管理器提供SageMath的下游包的安装配置容器 (downstream-archlinux-... ， downstream-conda-forge ；另请参阅 the _sagemath dummy package )，或来自提供SageMath的公共Docker映像 (docker-cocalc ， docker-computop )。这些 devcontainer.json 配置文件对于在这些SageMath部署上测试用户脚本很有用。您可能还会发现，将这些配置复制到您自己的项目中很有用(它们应该无需更改即可工作)，或者使它们适应您的需求。

• downstream-archlinux-latest/devcontainer.json 将容器配置为安装 Arch Linux 和它的SageMath包。(后缀 latest 指示Docker Hub上可用的Arch Linux的最新版本。)

• downstream-conda-forge-latest/devcontainer.json 使用Conda-Forge及其SageMath包的安装配置容器。

• downstream-docker-cocalc/devcontainer.json 使用配置容器 the CoCalc Docker image 。

• downstream-docker-computop/devcontainer.json 将容器配置为 Docker image from the 3-manifolds project ，提供Snappy、Regina、PHCPack等。

在VS代码完成配置dev容器之后，要在终端中使用Sage， open a new terminal in VS Code ，类型 sage 并击中了 Enter 。(请勿使用 ./sage ；这将不起作用，因为未配置源树。)