Sage开发过程¶
本节简要概述了Sage的开发过程。在本文中,我们将了解如何对Sage源代码进行更改,并将其记录在git修订控制系统中。
在下一节中 与Git-Trac协同开发 我们将研究如何将这些变化反馈给Sage项目。我们还有一个便利的 one-page "cheat sheet" 你可以打印出来放在办公桌上的常用git命令。我们有一些 recommended references and tutorials 也。
您也可以在 GitLab 它将自动获取您的代码并在我们的trac服务器上打开一个票据。
配置Git¶
不管怎样, git
是Sage用来跟踪变化的。所以首先,打开一个shell(例如,Mac上的终端)并检查一下 git
作品::
[user@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.
不用担心庞大的子命令列表。您只需要一小部分就可以进行有效的开发,我们将在本指南中为您介绍它们。如果出现“commandnotfound”错误,则说明您没有安装git。现在是安装它的时候了;请参阅 设置Git 以获取指示。
因为我们还跟踪谁用git在Sage中做了更改,所以您必须告诉git您希望如何被人知道。只需执行一次:
[user@localhost]$ git config --global user.name "Your Name"
[user@localhost]$ git config --global user.email you@yourdomain.example.com
如果您有多个帐户/计算机,请在每个帐户/计算机上使用相同的名称。这个名字/电子邮件的组合以提交的方式结束,所以在你忘记之前现在就做吧!
获取Sage源代码¶
显然,我们需要Sage源代码来开发。您可以使用本地安装的Sage,或者(在没有Sage的情况下)从github下载它,github是我们内部git存储库的一个公共只读镜像(速度更快):
[user@localhost ~]$ git clone git://github.com/sagemath/sage.git
Cloning into 'sage'...
[...]
Checking connectivity... done.
这将创建一个名为 sage
包含Sage当前稳定和开发版本的源代码。接下来需要切换到development分支(最新的开发版本)::
[user@localhost ~]$ cd sage
[user@localhost sage]$ git checkout develop
然后你需要 compile Sage 为了使用它。如果你克隆了,你需要留在互联网上,让它下载各种Sage::
[user@localhost sage]$ make
注解
如果您的系统支持多处理,并且您希望使用多个处理器来构建Sage,请将上面最后一行替换为:
[user@localhost sage]$ MAKE='make -jNUM' make
告诉 make
要运行的程序 NUM
在建造Sage时并行作业。
注解
MacOSX允许在不使用精确大小写的情况下更改目录。在为OSX编译时要注意这种便利性。在转换为 SAGE_ROOT
可能会导致依赖项的生成错误,这些依赖项需要精确的路径名大写。
对于专家,请注意 git.sagemath.org 才是真正发生发展的地方。
分出¶
为了开始修改Sage,我们想做一个 分支 Sage的。分支是Sage源代码的副本(除了它不占用两倍的空间),您可以在其中存储对Sage源代码的修改,并可以将其上载到trac票证。
首先,键入命令 git branch
. 您将看到以下内容:
[user@localhost]$ git branch
* develop
master
星号显示您所在的分支。没有争论 git branch
命令显示所有本地分支的列表,当前分支用星号标记。
创建一个新分支很容易;首先确保您位于要从中分支的分支。也就是说,如果您当前不在 develop
branch,键入命令 git checkout develop
::
[user@localhost sage]$ git checkout develop
Switched to branch 'develop'
Your branch is up-to-date with 'origin/develop'.
然后使用 git branch
命令创建新分支,如下所示:
[user@localhost sage]$ git branch last_twin_prime
还要注意 git branch
创建新分支,但不切换到该分支。为此,你必须使用 git checkout
::
[user@localhost sage]$ git checkout last_twin_prime
Switched to branch 'last_twin_prime'
现在如果你使用命令 git branch
,您将看到以下内容:
[user@localhost]$ git branch
develop
* last_twin_prime
master
请注意,除非您显式地将分支上载(“推送”)到远程git存储库,否则该分支是一个仅在您的计算机上且对其他任何人都不可见的本地分支。
要避免键入新分支名称两次,可以使用快捷方式 git checkout -b my_new_branch
在命令中创建一个新的分支。
历史¶
检查您是否正在对您认为自己所在的版本进行编辑总是一个好主意。第一个命令向您详细显示了最上面的提交,包括它对源的更改:
[user@localhost sage]$ git show
要深入挖掘,可以检查日志:
[user@localhost sage]$ git log
默认情况下,这将按时间倒序列出所有提交。
如果您发现分支位置错误,请参阅 重置和恢复 部分。
有许多程序可以帮助您更好地可视化历史树。
tig
是一个很好的文本模式这样的工具。
编辑源代码¶
一旦你有了自己的分支,就可以随心所欲地做出任何改变。 Subsequent chapters 本开发人员指南解释了您的代码应该如何适合Sage,以及我们如何确保整个代码的高质量。
状态 可能是最重要的git命令。它告诉您哪些文件已更改,以及如何继续记录更改:
[user@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")
要更深入地了解您可以使用的文件中的更改:
[user@localhost sage]$ git diff some_file.py
向你展示不同之处。
重建Sage¶
一旦你做了任何改变,你当然想建立Sage并尝试你的编辑。只要你只修改了Sage库(即Python和Cython文件 src/sage/...
)你只要跑:
[user@localhost sage]$ ./sage -br
重建Sage库然后启动Sage。这应该很快。如果您对 third-party packages ,然后你必须跑:
[user@localhost sage]$ make
好像你是 installing Sage from scratch . 但是,这次只会重新编译已更改的包(或依赖于已更改的包),因此它应该比第一次编译Sage快得多。
注解
如果你有 pulled a branch from trac ,它可能取决于对第三方软件包的更改,因此 ./sage -br
可能会失败。如果发生这种情况(并且您认为该分支中的代码应该编译),请尝试运行 make
.
很少与其他软件包或已安装的旧版本的软件包发生冲突,在这种情况下,您必须使用以下命令重新编译所有程序:
[user@localhost sage]$ make distclean && make
另外,别忘了运行测试(请参见 运行Sage的博士学位 )并构建文档(请参见 Sage手册 )
注解
如果在基于不同版本的分支之间切换,则修改文件的时间戳将更改。无论您是否对文件进行了任何其他更改,这都会触发在后续生成上重新编译和重新编译修改过的文件。要将分支之间切换的影响降至最低,请使用以下命令安装ccache::
[user@localhost sage]$ ./sage -i ccache
重新编译时仍将发生重新编译,但重新编译阶段首先检查以前编译的文件是否缓存以供重用,然后再编译它们。这节省了相当多的重建时间。
提交(快照)¶
无论何时你达到了你的目标,一个里程碑,或者只是觉得你完成了一些你应该做的工作 犯罪 你的改变。提交只是中所有文件状态的快照 知识库 (您正在执行的程序)。
与其他版本控制程序不同,在git中,首先需要 阶段 更改的文件,它告诉git您希望哪些文件成为下一次提交的一部分:
[user@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)
[user@localhost sage]$ git add src/sage/primes/last_pair.py
[user@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
命令:
[user@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
另一个分支,您所做的所有提交都将是您创建的分支的一部分。