开发演练¶

本节是对Sage开发过程的简要概述。我们将了解如何对Sage源代码进行更改，并将它们记录在Git修订控制系统中。

在下一章的各节中使用GitHub ，我们将研究如何将这些更改反馈给Sage项目。对Sage源代码的所有更改都必须经过 the Sage repository 在GitHub上。

例如，我们假定您的名字为Alice。请始终将其替换为您自己的名字。

正在检查Git¶

首先，打开一个Shell(例如，Mac上的终端)并检查Git是否工作：

[alice@localhost ~]$ git
usage: git [--version] [--help] [-C <path>] [-c name=value]
...
The most commonly used git commands are:
   add        Add file contents to the index
...
   tag        Create, list, delete or verify a tag object signed with GPG

'git help -a' and 'git help -g' lists available subcommands and some
concept guides. See 'git help <command>' or 'git help <concept>'
to read about a specific subcommand or concept.

不要担心庞大的子命令列表。您真的只需要其中的一小部分就可以进行有效的开发，我们将在本指南中向您介绍它们。如果出现“命令未找到”错误，则说明您尚未安装Git；现在是安装它的时候了。看见安装Git 以获取说明。

因为我们还跟踪谁在Git上做了哪些更改，您必须告诉Git您希望如何被人知道。检查Git是否认识您：：

[alice@localhost ~]$ git config --global user.name
Alice Adventure
[alice@localhost ~]$ git config --global user.email
alice@wonderland.com

如果您有多台计算机，请在每台计算机上使用相同的名称。此名称/电子邮件组合以提交结尾。所以，如果它还没有设定，在你忘记之前，现在就开始吧！这只需要做一次。看见配置Git 以获取说明。

获取Sage源代码¶

显然，人们需要Sage源代码来开发。您可以使用本地安装的Sage(如果您从源安装了Sage)，或者(从头开始)从GitHub：：

[alice@localhost ~]$ git clone --origin upstream https://github.com/sagemath/sage.git
Cloning into 'sage'...
[...]
Checking connectivity... done.

这将创建一个名为 sage 包含Sage当前稳定版和开发版的源代码。接下来，您需要切换到开发分支(最新开发版本)：

[alice@localhost ~]$ cd sage
[alice@localhost sage]$ git checkout develop

接下来，按照文件中的说明构建Sage README.md 在……里面 SAGE_ROOT 。如果构建的所有先决条件都已就绪，则命令 ./configure && make -j4 会去做的。有关其他详细信息，请参阅 installation from source 在Sage安装指南中。如果您希望使用Conda-Forge，请参阅 conda 。

备注

MacOS允许在不使用确切大小写的情况下更改目录。在为MacOS编译时，请注意这种方便性。更改为时忽略准确的大写 SAGE_ROOT 可能会导致为路径名中要求完全大写的依赖项生成错误。

向外扩展¶

为了开始修改Sage，我们想要制作一个新的 branch 在当地的Sage回收站。分支是Sage源代码的副本(除了它不占用两倍的空间)，您可以在其中存储对Sage源代码的修改(并且可以将其推送到GitHub上的Sage存储库的分支)。

首先，键入命令 git branch 。您将看到以下内容：

[alice@localhost sage]$ git branch
* develop
  master

星号显示您所在的分支机构。没有任何争论， git branch 命令显示所有本地分支的列表，其中当前分支用星号标记。

创建一个新的分支机构很容易。首先，确保您位于要进行分支的分支上。也就是说，如果您当前不在 develop BRANCH，键入命令 git checkout develop **

[alice@localhost sage]$ git checkout develop
Switched to branch 'develop'
Your branch is up-to-date with 'origin/develop'.

然后使用 git branch 命令创建新分支，如下所示：

[alice@localhost sage]$ git branch last_twin_prime

另请注意， git branch 创建新分支，但不切换到该分支。为此，您必须使用 git checkout **

[alice@localhost sage]$ git checkout last_twin_prime
Switched to branch 'last_twin_prime'

现在，如果您使用命令 git branch ，您将看到以下内容：

[alice@localhost sage]$ git branch
  develop
* last_twin_prime
  master

请注意，除非您显式地将某个分支推送到远程Git存储库，否则该分支是仅在您的计算机上且对其他任何人都不可见的本地分支。

为了避免两次键入新分支机构名称，您可以使用快捷键 git checkout -b last_twin_prime develop 基于创建并切换到新分支的步骤 develop 一气呵成。

历史¶

检查您是否在您认为自己所在的分支上进行编辑总是一个好主意。以下命令向您详细显示最顶层的提交，包括其对文件的更改：

[alice@localhost sage]$ git show

要深入挖掘，您可以查看日志：：

[alice@localhost sage]$ git log

默认情况下，这会以相反的时间顺序列出所有提交。

如果您发现分支机构位于错误的位置，请参阅重置和恢复一节。
有许多工具可以帮助您更好地可视化历史树。例如, tig 是一个非常好的文本模式工具。

编辑源代码¶

一旦您有了自己的分支，就可以随意更改源文件。这一章为Sage编写代码解释您的代码应该如何适应Sage，以及我们如何始终确保高代码质量。

Git命令 git status 可能是所有Git命令中最重要的。它会告诉您更改了哪些文件，以及如何继续记录更改：

[alice@localhost sage]$ git status
On branch last_twin_prime
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

    modified:   some_file.py
    modified:   src/sage/primes/all.py

Untracked files:
  (use "git add <file>..." to include in what will be committed)

    src/sage/primes/last_pair.py

no changes added to commit (use "git add" and/or "git commit -a")

要更深入地了解文件中的更改内容，可以使用：

[alice@localhost sage]$ git diff some_file.py

向你展示不同之处。

重塑Sage¶

一旦您进行了任何更改，您当然希望构建Sage并尝试您的编辑。只要您只修改了Sage库(即 src/sage/... )您只需运行：：

[alice@localhost sage]$ ./sage -br

重建Sage库，然后启动Sage。

备注

重新启动Sage后，对Python文件的所有更改将立即生效(除非您已使用 ./configure --disable-editable 当您构建Sage时)。因此，您可以直接启动Sage，而不是 ./sage -br 如果只修改了Python文件就好了。

如果您更改了 third-party packages 作为Sage的一部分安装，则必须运行：：

[alice@localhost sage]$ make build

就好像你是 installing Sage from scratch 。然而，只有这一次，被更改的包(或依赖于更改的包)将被重新构建，因此它应该比第一次构建Sage快得多。

备注

如果你有 pulled a branch from the GitHub Sage repository ，它可能取决于对第三方程序包的更改，因此 ./sage -br 可能会失败。如果发生这种情况(并且您认为此分支中的代码应该进行编译)，请尝试运行 make build 。

很少会与其他程序包冲突，或者与您更改的已安装的较旧版本的程序包冲突，在这种情况下，您必须使用：

[alice@localhost sage]$ make distclean && make build

此外，不要忘记运行测试(请参见运行Sage‘s Doctest )和构建文档(请参见《Sage手册》 )。

备注

如果您在基于不同版本的分支之间切换，则修改后的文件的时间戳将会更改。无论您是否对文件进行了任何其他更改，这都会触发对后续生成中已修改文件的重新归并和重新编译。要最大限度地减少分支之间切换的影响，请使用以下命令安装ccache：

[alice@localhost sage]$ ./sage -i ccache

重新编译时仍将进行重新编译，但重新编译阶段在重新编译之前首先检查以前编译的文件是否已缓存以供重复使用。这节省了相当多的重建时间。

作出承诺¶

无论什么时候你已经达到了你的目标，一个里程碑，或者只是觉得你完成了一些工作，你就应该 commit 您的更改。提交只是存储库中所有文件状态的快照。

与其他一些修订控制程序不同，在Git中，您首先需要 stage 更改的文件，它告诉Git您希望哪些文件成为下一次提交的一部分：

[alice@localhost sage]$ git status
# On branch my_branch
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#       src/sage/primes/last_pair.py
nothing added to commit but untracked files present (use "git add" to track)

[alice@localhost sage]$ git add src/sage/primes/last_pair.py
[alice@localhost sage]$ git status
# On branch my_branch
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#   new file:   src/sage/primes/last_pair.py
#

一旦您对转移文件的列表感到满意，您就可以使用 git commit 命令：：

[alice@localhost sage]$ git commit
... editor opens ...
[my_branch 31331f7] Added the very important foobar text file
 1 file changed, 1 insertion(+)
  create mode 100644 foobar.txt

这将打开一个编辑器，供您编写提交消息。提交消息通常应包含一行描述，后跟空行，后跟进一步的说明性文本：

Added the last twin prime

This is an example commit message. You see there is a one-line
summary followed by more detailed description, if necessary.

然后，您可以继续朝着您的下一个里程碑努力，进行另一次提交，重复执行，直到完成。只要你不这样做 git checkout 另一个分支，您所做的所有提交都将是您创建的分支的一部分。

开发演练¶

正在检查Git¶

获取Sage源代码¶

向外扩展¶

历史¶

编辑源代码¶

重塑Sage¶

作出承诺¶

目录

上一主题

下一主题