Browse Source
doc: Add Simplified Chinese translation.
doc: Add Simplified Chinese translation.
* doc/local.mk (info_TEXINFOS): Add guix.zh_CN.texi. (TRANSLATED_INFO): Add guix.zh_CN.texi and contributing.zh_CN.texi. * po/doc/local.mk (DOC_PO_FILES): Add guix-manual.zh_CN.po. * doc/contributing.zh_CN.texi, doc/guix.zh_CN.texi: New files.version-1.0.0
Ludovic Courtès
3 years ago
No known key found for this signature in database
GPG Key ID: 90B11993D9AEBB5
4 changed files with 26268 additions and 15 deletions
@ -0,0 +1,897 @@ |
|||
@node 贡献 |
|||
@chapter 贡献 |
|||
|
|||
这个项目是大家合作的成果，我们需要你的帮助以更好地发展。请通过 |
|||
@email{guix-devel@@gnu.org} 和 Freenode IRC 上的 @code{#guix} 联系我们。我们欢迎 |
|||
您的想法、bug反馈、补丁，以及任何可能对项目有帮助的贡献。我们特别欢迎帮助我们打 |
|||
包（@pxref{打包指导}）。 |
|||
|
|||
@cindex 行为准则和贡献者 |
|||
@cindex 贡献者契约 |
|||
我们希望提供一个温暖、友好，并且没有骚扰的的环境，这样每个人都能尽最大努力贡献。 |
|||
为了这个目的，我们的项目遵循“贡献者契约”，这个契约是根据 |
|||
@url{http://contributor-covenant.org/}制定的。你可以在源代码目录里的 |
|||
@file{CODE-OF-CONDUCT}文件里找到一份本地版。 |
|||
|
|||
贡献者在提交补丁和网上交流时不需要使用法律认可的名字。他们可以使用任何名字或者假 |
|||
名。 |
|||
|
|||
@menu |
|||
* 从Git编译:: 最新的并且最好的. |
|||
* 在安装之前运行Guix:: 黑客技巧。 |
|||
* 完美的配置:: 正确的工具。 |
|||
* 打包指导:: Growing the distribution. |
|||
* 代码风格:: 开发者的卫生情况 |
|||
* 提交补丁:: 分享你的工作。 |
|||
@end menu |
|||
|
|||
@node 从Git编译 |
|||
@section 从Git编译 |
|||
|
|||
如果你想折腾Guix本身，建议使用Git仓库里最新的版本： |
|||
|
|||
@example |
|||
git clone https://git.savannah.gnu.org/git/guix.git |
|||
@end example |
|||
|
|||
当从Git检出构建Guix时，除安装指导（@pxref{Requirements}）里提及的软件包之外还需 |
|||
要这些包。 |
|||
|
|||
@itemize |
|||
@item @url{http://gnu.org/software/autoconf/, GNU Autoconf}; |
|||
@item @url{http://gnu.org/software/automake/, GNU Automake}; |
|||
@item @url{http://gnu.org/software/gettext/, GNU Gettext}; |
|||
@item @url{http://gnu.org/software/texinfo/, GNU Texinfo}; |
|||
@item @url{http://www.graphviz.org/, Graphviz}; |
|||
@item @url{http://www.gnu.org/software/help2man/, GNU Help2man （可选）}。 |
|||
@end itemize |
|||
|
|||
设置Guix开发环境的最简单的方式当然是使用Guix！下面这些命令启动一个shell，所有的 |
|||
依赖和环境变量都为折腾Guix设置好了： |
|||
|
|||
@example |
|||
guix environment guix |
|||
@end example |
|||
|
|||
这个命令更多的信息请参考@xref{Invoking guix environment}。额外的依赖可以通过 |
|||
@option{--ad-hoc}选项添加： |
|||
|
|||
@example |
|||
guix environment guix --ad-hoc help2man git strace |
|||
@end example |
|||
|
|||
运行 @command{./bootstrap} 以使用Autoconf和Automake生成编译系统的基础框架。如果 |
|||
你的得到这样的错误： |
|||
|
|||
@example |
|||
configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES |
|||
@end example |
|||
|
|||
@noindent |
|||
它可能意味着Autoconf无法找到由pkg-config提供的@file{pkg.m4}。请确保@file{pkg.m4} |
|||
可用。由Guile提供的@file{guile.m4}宏也类似。假如你的Automake安装在 |
|||
@file{/usr/local}，那么它不会从@file{/usr/share}里寻找@file{.m4}文件。这种情况下， |
|||
你必须执行下面这个命令： |
|||
|
|||
@example |
|||
export ACLOCAL_PATH=/usr/share/aclocal |
|||
@end example |
|||
|
|||
参考@xref{Macro Search Path,,, automake, The GNU Automake Manual}. |
|||
|
|||
然后，像正常一样运行@command{./configure}。确保提供 |
|||
@code{--localstatedir=@var{directory}}参数，@var{directory}是你当前系统的 |
|||
@code{localstatedir}的值。（@pxref{The Store}） |
|||
|
|||
最后，用@code{make check}执行测试（@pxref{Running the Test Suite}）。如果遇到任 |
|||
何错误，请参考“安装指导”（@pxref{Installation}）或者给 |
|||
@email{guix-devel@@gnu.org, 邮件列表}发邮件。 |
|||
|
|||
|
|||
@node 在安装之前运行Guix |
|||
@section 在安装之前运行Guix |
|||
|
|||
为了保持一个合适的工作环境，你会发现在你的本地代码树里测试修改而不用安装它们会很 |
|||
有用。TODO: So that you can distinguish between your ``end-user'' hat and your |
|||
``motley'' costume. |
|||
|
|||
这样，即使你没有运行@code{make install}，所有的命令行工具都可以使用。为此，你先 |
|||
要有一个包含全部依赖的环境（@pxref{从Git编译}），然后，为所有的命令添加 |
|||
前缀@command{./pre-inst-env}（@file{pre-inst-env}脚本在Guix编译树的最顶层，它由 |
|||
@command{./configure}生成），如@footnote{@command{sudo}命令的@option{-E}参数 |
|||
确保@code{GUILE_LOAD_PATH}被正确设置，从而@command{guix-daemon}和它使用的工具可 |
|||
以找到它们需要的Guile模块。}： |
|||
|
|||
@example |
|||
$ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild |
|||
$ ./pre-inst-env guix build hello |
|||
@end example |
|||
|
|||
@noindent |
|||
类似的，对于使用Guix模块的Guile会话： |
|||
|
|||
@example |
|||
$ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))' |
|||
|
|||
;;; ("x86_64-linux") |
|||
@end example |
|||
|
|||
@noindent |
|||
@cindex REPL |
|||
@cindex read-eval-print loop |
|||
@dots{} and for a REPL (@pxref{Using Guile Interactively,,, guile, Guile |
|||
Reference Manual}): |
|||
|
|||
@example |
|||
$ ./pre-inst-env guile |
|||
scheme@@(guile-user)> ,use(guix) |
|||
scheme@@(guile-user)> ,use(gnu) |
|||
scheme@@(guile-user)> (define snakes |
|||
(fold-packages |
|||
(lambda (package lst) |
|||
(if (string-prefix? "python" |
|||
(package-name package)) |
|||
(cons package lst) |
|||
lst)) |
|||
'())) |
|||
scheme@@(guile-user)> (length snakes) |
|||
$1 = 361 |
|||
@end example |
|||
|
|||
@command{pre-inst-env}脚本设置为此好了所有必要的的环境变量，包括@env{PATH}和 |
|||
@env{GUILE_LOAD_PATH}。 |
|||
|
|||
@command{./pre-inst-env guix pull} @emph{不} 会更新本地源代码树，它只更新符号链 |
|||
接@file{~/.config/guix/current} (@pxref{Invoking guix pull})。如果你想更新本地源 |
|||
代码树，请运行@command{git pull}。 |
|||
|
|||
|
|||
@node 完美的配置 |
|||
@section 完美的配置 |
|||
|
|||
折腾Guix的完美配置也是折腾Guile的完美配置@pxref{Using Guile in Emacs,,, guile, |
|||
Guile Reference Manual})。首先，你需要的不仅是一个编辑器，你需要 |
|||
@url{http://www.gnu.org/software/emacs, Emacs}，以及美妙的 |
|||
@url{http://nongnu.org/geiser/, Geiser}。为此，请运行： |
|||
|
|||
@example |
|||
guix package -i emacs guile emacs-geiser |
|||
@end example |
|||
|
|||
Geiser允许在Emacs里进行交互式的、增长式的开发：buffer里的代码补全和执行，获取一 |
|||
行的文档（docstrings），上下文敏感的补全，@kbd{M-.}跳转到对象定义，测试代码的 |
|||
REPL，及更多（@pxref{Introduction,,, geiser, Geiser User Manual}）。为了方便的 |
|||
Guix开发，请确保修改Guile的加载路径（load path）以使其能从你的项目里找到源代码文 |
|||
件。 |
|||
|
|||
@lisp |
|||
;; @r{假设Guix项目在 ~/src/guix.} |
|||
(with-eval-after-load 'geiser-guile |
|||
(add-to-list 'geiser-guile-load-path "~/src/guix")) |
|||
@end lisp |
|||
|
|||
真正编辑代码时别忘了Emacs自带了方便的Scheme模式。而且，一定不要错过 |
|||
@url{http://www.emacswiki.org/emacs/ParEdit, Paredit}。它提供了直接操作语法树的 |
|||
的功能，例如，用S-表达式替换父节点，为S-表达式添加、删除前后的括号，删除后面的S- |
|||
表达式，等等。 |
|||
|
|||
@cindex 代码片段 |
|||
@cindex 模板 |
|||
@cindex reducing boilerplate |
|||
在@file{etc/snippets}文件夹里，我们还为普通的git commit信息和软件包定义提供模板。 |
|||
这些模板可以通过@url{http://joaotavora.github.io/yasnippet/, YASnippet}使用，它 |
|||
可以把短的触发字符串扩展成交互式的文字片段。你可能希望将这个文件夹添加到Emacs的 |
|||
@var{yas-snippet-dirs}变量里。 |
|||
|
|||
@lisp |
|||
;; @r{假设Guix项目在 ~/src/guix.} |
|||
(with-eval-after-load 'yasnippet |
|||
(add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets")) |
|||
@end lisp |
|||
|
|||
commit信息片段显示staged文件需要依赖@url{https://magit.vc/, Magit}。编辑commit信 |
|||
息时，输入@code{add}，然后按@kbd{TAB}就可以插入一段用于新增软件包的模板；输入 |
|||
@code{update}，然后按@kbd{TAB}可以插入一段更新软件包的模板；输入@code{https}然后 |
|||
按@kbd{TAB}可以插入一段修改主页URI为HTTPS的模板。 |
|||
|
|||
@code{scheme-mode}最重要的模板可以通过输入@code{package...}，然后按@kbd{TAB}触发。 |
|||
这个片段还插入了触发字符串@code{origin...}，以进一步展开。@code{origin}片段更进 |
|||
一步的可能插入其它以@code{...}结尾的触发字符串，它们可以被继续展开。 |
|||
|
|||
|
|||
@node 打包指导 |
|||
@section 打包指导 |
|||
|
|||
@cindex 软件包, 创建 |
|||
这个GNU发行版正在开发的早期阶段，可能缺少一些你喜欢的软件。这个章节介绍你可以怎 |
|||
样帮助这个发行版成长。 |
|||
|
|||
自由软件通常以@dfn{源代码包}的形式分发，通常是包含完整代码的@file{tar.gz}包。添 |
|||
加软件包到这个发行版意味着两件事：添加描述如何编译包的@dfn{配方}和一系列依赖软件， |
|||
以及添加配方之外的@dfn{软件包元数据}，如一段文字描述和证书信息。 |
|||
|
|||
在Guix里所有这些信息都包含在@dfn{软件包定义}里。软件包定义提供了软件包的高层视角。 |
|||
它们使用Scheme编程语言编写，事实上，对每个软件包我们都定义一个绑定到软件包定义的 |
|||
的变量，并且从模块（@pxref{Package Modules}）中导出那个变量。然而，深入的Scheme |
|||
知识@emph{不}是创建软件包的前提条件。若要了解软件包的更多信息，@pxref{Defining |
|||
Packages}。 |
|||
|
|||
一旦软件包定义准备好了，并且包存在Guix代码树的一个文件里，你可以用@command{guix |
|||
build} (@pxref{Invoking guix build})命令测试它。假设这个新软件包的名字叫做 |
|||
@code{gnew}，你可以在Guix编译树里运行这个命令(@pxref{在安装之前运行Guix})： |
|||
|
|||
@example |
|||
./pre-inst-env guix build gnew --keep-failed |
|||
@end example |
|||
|
|||
使用@code{--keep-failed}参数会保留失败的编译树，这可以使调试编译错误更容易。 |
|||
@code{--log-file}也是一个调试时很有用的参数，它可以用来访问编译日志。 |
|||
|
|||
如果@command{guix}命令找不到这个软件包，那可能是因为源文件包含语法错误，或者缺少 |
|||
导出软件包的@code{define-public}语句。为了查找错误，你可以用Guile导入这个模块以 |
|||
了解这个错误的详情： |
|||
|
|||
@example |
|||
./pre-inst-env guile -c '(use-modules (gnu packages gnew))' |
|||
@end example |
|||
|
|||
一旦你的软件包可以正确编译，请给我们发送补丁（@pxref{提交补丁}）。当然， |
|||
如果你需要帮助，我们也会很乐意帮助你。一旦补丁被提交到Guix仓库里，这个新的软件包 |
|||
会被自动地在支持的平台上编译@url{http://hydra.gnu.org/jobset/gnu/master, our |
|||
continuous integration system}。 |
|||
|
|||
@cindex substituter |
|||
用户可以通过运行@command{guix pull}命令获取最新的软件包定义（@pxref{Invoking |
|||
guix pull}）。当@code{@value{SUBSTITUTE-SERVER}}编译好这些软件包之后，安装这些软 |
|||
件包时会自动从服务器（@pxref{Substitutes}）上下载编译好的二进制包。唯一需要人工 |
|||
干预的地方是评审和应用代码补丁。 |
|||
|
|||
|
|||
@menu |
|||
* 软件自由:: 什么可以进入这个发行版。 |
|||
* 软件包命名:: 名字里包含什么？ |
|||
* 版本号:: 当名字不够时 |
|||
* 简介和描述:: 帮助用户寻找合适的软件包 |
|||
* Python模块:: 接触英式的喜剧 |
|||
* Perl模块:: 小珍珠。 |
|||
* Java包:: 喝咖啡休息。 |
|||
* 字体:: 字体的乐趣。 |
|||
@end menu |
|||
|
|||
@node 软件自由 |
|||
@subsection 软件自由 |
|||
|
|||
@c =========================================================================== |
|||
@c |
|||
@c This file was generated with po4a. Translate the source file. |
|||
@c |
|||
@c =========================================================================== |
|||
@c Adapted from http://www.gnu.org/philosophy/philosophy.html. |
|||
@cindex 自由软件 |
|||
开发GNU操作系统是为了用户拥有计算的自由。GNU是@dfn{自由软件}，这意味着它有 |
|||
@url{http://www.gnu.org/philosophy/free-sw.html,四项重要的自由}：运行程序的自由， |
|||
以源代码形式学习和修改程序的自由，原样重新分发副本的自由，和分发修改后的版本的自 |
|||
由。GNU发行版里包含的软件包只提供遵守这四项自由的软件。 |
|||
|
|||
此外，GNU发行版遵循 |
|||
@url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,自由软 |
|||
件发行版准则}。这些准则拒绝非自由的固件和对非自由软件的推荐，并讨论解决商标和专 |
|||
利的方法。 |
|||
|
|||
某些上游的软件包源代码包含一小部分违反上述准则的可选的子集，比如这个子集本身就是 |
|||
非自由代码。这时，这些讨厌的代码需要用合适的补丁或者软件包定义（@pxref{Defining |
|||
Packages}）里的@code{origin}里的代码片段移除。这样，@code{guix build --source}就 |
|||
可以返回自由的源代码而不是未经修改的上游源代码。 |
|||
|
|||
|
|||
@node 软件包命名 |
|||
@subsection 软件包命名 |
|||
|
|||
@cindex 软件包名字 |
|||
一个软件包事实上有两个名字：第一个是@emph{Scheme变量}的名字，即用 |
|||
@code{define-public}定义的名字。通过这个名字，软件包可以被Scheme代码找到，如用作 |
|||
其它软件包的输入。第二个名字是软件包定义里的@code{name}属性的字符串值。这个名字 |
|||
用于软件包管理命令，如：@command{guix package}，@command{guix build} |
|||
|
|||
两个名字通常是相同的，常是上游项目名字转成小写字母并把下划线替换成连字符的结果。 |
|||
比如，GNUnet转成@code{gnunet}，SDL_net转成@code{sdl-net}。 |
|||
|
|||
我们不给库软件包添加@code{lib}前缀，除非它是项目官方名字的一部分。但是 |
|||
@pxref{Python模块}和@ref{Perl模块}有关于Python和Perl语言的特殊规则。 |
|||
|
|||
字体软件包的名字处理起来不同，@pxref{字体}. |
|||
|
|||
|
|||
@node 版本号 |
|||
@subsection 版本号 |
|||
|
|||
@cindex 软件包版本 |
|||
我们通常只为每个自由软件的最新版本打包。但是有时候，比如对于版本不兼容的库，需要 |
|||
有同一个软件包的两个或更多版本。它们需要使用不同的Scheme变量名。我们为最新的版本 |
|||
使用@ref{软件包命名}里规定的名字，旧的版本使用加上后缀的名字，后缀是@code{-} |
|||
和可以区分开版本号的版本号的最小前缀。 |
|||
|
|||
软件包定义里的名字对于同一个软件包的所有版本都是相同的，并且不含有版本号。 |
|||
|
|||
例如，GTK+的2.24.20和3.9.12两个版本可以这样打包： |
|||
|
|||
@example |
|||
(define-public gtk+ |
|||
(package |
|||
(name "gtk+") |
|||
(version "3.9.12") |
|||
...)) |
|||
(define-public gtk+-2 |
|||
(package |
|||
(name "gtk+") |
|||
(version "2.24.20") |
|||
...)) |
|||
@end example |
|||
如果我们还需要GTK+ 3.8.2，就这样打包 |
|||
@example |
|||
(define-public gtk+-3.8 |
|||
(package |
|||
(name "gtk+") |
|||
(version "3.8.2") |
|||
...)) |
|||
@end example |
|||
|
|||
@c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>, |
|||
@c for a discussion of what follows. |
|||
@cindex 用于版本控制快照的版本号 |
|||
有时候，我们为软件包上游的版本控制系统（VCS）的快照而不是正式发布版打包。这是特 |
|||
殊情况，因为决定哪个是稳定版的权力应该属于上游开发者。然而，有时候这是必须的。那 |
|||
么，我们该如何决定写在@code{version}里的版本号呢？ |
|||
|
|||
显然，我们需要让VCS快照的commit ID在版本号中体现出来，但是我们也需要确保版本号单 |
|||
调递增，以便@command{guix package --upgrade}决定哪个版本号更新。由于commit ID， |
|||
尤其是Git的commit ID，不是单调递增的，我们添加一个每次升级快照时都手动增长的 |
|||
revision数字。最后的版本号字符串看起来是这样： |
|||
|
|||
@example |
|||
2.0.11-3.cabba9e |
|||
^ ^ ^ |
|||
| | `-- 上游的commit ID |
|||
| | |
|||
| `--- Guix软件包的revision |
|||
| |
|||
最新的上游版本号 |
|||
@end example |
|||
|
|||
把@code{版本号}里的commit ID截短，比如只取7个数字，是一个好主意。它避免了美学上 |
|||
的烦恼（假设美学在这里很重要），以及操作系统限制引起的问题（比如Linux内核的127字 |
|||
节）。尽管如此，在@code{origin}里最好使用完整的commit ID，以避免混淆。 |
|||
|
|||
@example |
|||
(define my-package |
|||
(let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7") |
|||
(revision "1")) ;Guix软件包的revision |
|||
(package |
|||
(version (git-version "0.9" revision commit)) |
|||
(source (origin |
|||
(method git-fetch) |
|||
(uri (git-reference |
|||
(url "git://example.org/my-package.git") |
|||
(commit commit))) |
|||
(sha256 (base32 "1mbikn@dots{}")) |
|||
(file-name (git-file-name name version)))) |
|||
;; @dots{} |
|||
))) |
|||
@end example |
|||
|
|||
@node 简介和描述 |
|||
@subsection 简介和描述 |
|||
|
|||
@cindex 软件包描述 |
|||
@cindex 软件包简介 |
|||
我们已经看到，GNU@tie{}Guix里的每个软件包都包含一个简介（synopsis）和一个描述 |
|||
（description）（@pxref{Defining Packages}）。简介和描述很重要：它们是 |
|||
@command{guix package --search}搜索的信息，并且是帮助用户决定一个软件包是否符合 |
|||
自己需求的重要信息。因此，打包的人应该关注怎样写它们的内容。 |
|||
|
|||
简介必须以大写字母开头，并且不能以句号结尾。它们不能以 ``a'' 或者 ``the'' 等没有 |
|||
意义的词开头。例如 ``File-frobbing tool'' 要比 ``A tool that frobs files'' 更好。 |
|||
简介需要说明软件包是什么－－如 ``Core GNU utilities (file, text, shell)''，或者 |
|||
它的用途－－如 GNU@tie{}grep 的简介是 ``Print lines matching a pattern''。 |
|||
|
|||
Keep in mind that the synopsis must be meaningful for a very wide audience. |
|||
For example, ``Manipulate alignments in the SAM format'' might make sense |
|||
for a seasoned bioinformatics researcher, but might be fairly unhelpful or |
|||
even misleading to a non-specialized audience. It is a good idea to come up |
|||
with a synopsis that gives an idea of the application domain of the |
|||
package. In this example, this might give something like ``Manipulate |
|||
nucleotide sequence alignments'', which hopefully gives the user a better |
|||
idea of whether this is what they are looking for. |
|||
|
|||
Descriptions should take between five and ten lines. Use full sentences, |
|||
and avoid using acronyms without first introducing them. Please avoid |
|||
marketing phrases such as ``world-leading'', ``industrial-strength'', and |
|||
``next-generation'', and avoid superlatives like ``the most |
|||
advanced''---they are not helpful to users looking for a package and may |
|||
even sound suspicious. Instead, try to be factual, mentioning use cases and |
|||
features. |
|||
|
|||
@cindex Texinfo markup, in package descriptions |
|||
Descriptions can include Texinfo markup, which is useful to introduce |
|||
ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or hyperlinks |
|||
(@pxref{Overview,,, texinfo, GNU Texinfo}). However you should be careful |
|||
when using some characters for example @samp{@@} and curly braces which are |
|||
the basic special characters in Texinfo (@pxref{Special Characters,,, |
|||
texinfo, GNU Texinfo}). User interfaces such as @command{guix package |
|||
--show} take care of rendering it appropriately. |
|||
|
|||
Synopses and descriptions are translated by volunteers |
|||
@uref{http://translationproject.org/domain/guix-packages.html, at the |
|||
Translation Project} so that as many users as possible can read them in |
|||
their native language. User interfaces search them and display them in the |
|||
language specified by the current locale. |
|||
|
|||
To allow @command{xgettext} to extract them as translatable strings, |
|||
synopses and descriptions @emph{must be literal strings}. This means that |
|||
you cannot use @code{string-append} or @code{format} to construct these |
|||
strings: |
|||
|
|||
@lisp |
|||
(package |
|||
;; @dots{} |
|||
(synopsis "This is translatable") |
|||
(description (string-append "This is " "*not*" " translatable."))) |
|||
@end lisp |
|||
|
|||
Translation is a lot of work so, as a packager, please pay even more |
|||
attention to your synopses and descriptions as every change may entail |
|||
additional work for translators. In order to help them, it is possible to |
|||
make recommendations or instructions visible to them by inserting special |
|||
comments like this (@pxref{xgettext Invocation,,, gettext, GNU Gettext}): |
|||
|
|||
@example |
|||
;; TRANSLATORS: "X11 resize-and-rotate" should not be translated. |
|||
(description "ARandR is designed to provide a simple visual front end |
|||
for the X11 resize-and-rotate (RandR) extension. @dots{}") |
|||
@end example |
|||
|
|||
|
|||
@node Python模块 |
|||
@subsection Python模块 |
|||
|
|||
@cindex python |
|||
We currently package Python 2 and Python 3, under the Scheme variable names |
|||
@code{python-2} and @code{python} as explained in @ref{版本号}. To |
|||
avoid confusion and naming clashes with other programming languages, it |
|||
seems desirable that the name of a package for a Python module contains the |
|||
word @code{python}. |
|||
|
|||
Some modules are compatible with only one version of Python, others with |
|||
both. If the package Foo compiles only with Python 3, we name it |
|||
@code{python-foo}; if it compiles only with Python 2, we name it |
|||
@code{python2-foo}. If it is compatible with both versions, we create two |
|||
packages with the corresponding names. |
|||
|
|||
If a project already contains the word @code{python}, we drop this; for |
|||
instance, the module python-dateutil is packaged under the names |
|||
@code{python-dateutil} and @code{python2-dateutil}. If the project name |
|||
starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as |
|||
described above. |
|||
|
|||
@subsubsection Specifying Dependencies |
|||
@cindex inputs, for Python packages |
|||
|
|||
Dependency information for Python packages is usually available in the |
|||
package source tree, with varying degrees of accuracy: in the |
|||
@file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}. |
|||
|
|||
Your mission, when writing a recipe for a Python package, is to map these |
|||
dependencies to the appropriate type of ``input'' (@pxref{package Reference, |
|||
inputs}). Although the @code{pypi} importer normally does a good job |
|||
(@pxref{Invoking guix import}), you may want to check the following check |
|||
list to determine which dependency goes where. |
|||
|
|||
@itemize |
|||
|
|||
@item |
|||
We currently package Python 2 with @code{setuptools} and @code{pip} |
|||
installed like Python 3.4 has per default. Thus you don't need to specify |
|||
either of these as an input. @command{guix lint} will warn you if you do. |
|||
|
|||
@item |
|||
Python dependencies required at run time go into @code{propagated-inputs}. |
|||
They are typically defined with the @code{install_requires} keyword in |
|||
@file{setup.py}, or in the @file{requirements.txt} file. |
|||
|
|||
@item |
|||
Python packages required only at build time---e.g., those listed with the |
|||
@code{setup_requires} keyword in @file{setup.py}---or only for |
|||
testing---e.g., those in @code{tests_require}---go into |
|||
@code{native-inputs}. The rationale is that (1) they do not need to be |
|||
propagated because they are not needed at run time, and (2) in a |
|||
cross-compilation context, it's the ``native'' input that we'd want. |
|||
|
|||
Examples are the @code{pytest}, @code{mock}, and @code{nose} test |
|||
frameworks. Of course if any of these packages is also required at |
|||
run-time, it needs to go to @code{propagated-inputs}. |
|||
|
|||
@item |
|||
Anything that does not fall in the previous categories goes to |
|||
@code{inputs}, for example programs or C libraries required for building |
|||
Python packages containing C extensions. |
|||
|
|||
@item |
|||
If a Python package has optional dependencies (@code{extras_require}), it is |
|||
up to you to decide whether to add them or not, based on their |
|||
usefulness/overhead ratio (@pxref{提交补丁, @command{guix size}}). |
|||
|
|||
@end itemize |
|||
|
|||
|
|||
@node Perl模块 |
|||
@subsection Perl模块 |
|||
|
|||
@cindex perl |
|||
Perl programs standing for themselves are named as any other package, using |
|||
the lowercase upstream name. For Perl packages containing a single class, |
|||
we use the lowercase class name, replace all occurrences of @code{::} by |
|||
dashes and prepend the prefix @code{perl-}. So the class @code{XML::Parser} |
|||
becomes @code{perl-xml-parser}. Modules containing several classes keep |
|||
their lowercase upstream name and are also prepended by @code{perl-}. Such |
|||
modules tend to have the word @code{perl} somewhere in their name, which |
|||
gets dropped in favor of the prefix. For instance, @code{libwww-perl} |
|||
becomes @code{perl-libwww}. |
|||
|
|||
|
|||
@node Java包 |
|||
@subsection Java包 |
|||
|
|||
@cindex java |
|||
Java programs standing for themselves are named as any other package, using |
|||
the lowercase upstream name. |
|||
|
|||
To avoid confusion and naming clashes with other programming languages, it |
|||
is desirable that the name of a package for a Java package is prefixed with |
|||
@code{java-}. If a project already contains the word @code{java}, we drop |
|||
this; for instance, the package @code{ngsjava} is packaged under the name |
|||
@code{java-ngs}. |
|||
|
|||
For Java packages containing a single class or a small class hierarchy, we |
|||
use the lowercase class name, replace all occurrences of @code{.} by dashes |
|||
and prepend the prefix @code{java-}. So the class @code{apache.commons.cli} |
|||
becomes package @code{java-apache-commons-cli}. |
|||
|
|||
|
|||
@node 字体 |
|||
@subsection 字体 |
|||
|
|||
@cindex fonts |
|||
For fonts that are in general not installed by a user for typesetting |
|||
purposes, or that are distributed as part of a larger software package, we |
|||
rely on the general packaging rules for software; for instance, this applies |
|||
to the fonts delivered as part of the X.Org system or fonts that are part of |
|||
TeX Live. |
|||
|
|||
To make it easier for a user to search for fonts, names for other packages |
|||
containing only fonts are constructed as follows, independently of the |
|||
upstream package name. |
|||
|
|||
The name of a package containing only one font family starts with |
|||
@code{font-}; it is followed by the foundry name and a dash @code{-} if the |
|||
foundry is known, and the font family name, in which spaces are replaced by |
|||
dashes (and as usual, all upper case letters are transformed to lower |
|||
case). For example, the Gentium font family by SIL is packaged under the |
|||
name @code{font-sil-gentium}. |
|||
|
|||
For a package containing several font families, the name of the collection |
|||
is used in the place of the font family name. For instance, the Liberation |
|||
fonts consist of three families, Liberation Sans, Liberation Serif and |
|||
Liberation Mono. These could be packaged separately under the names |
|||
@code{font-liberation-sans} and so on; but as they are distributed together |
|||
under a common name, we prefer to package them together as |
|||
@code{font-liberation}. |
|||
|
|||
In the case where several formats of the same font family or font collection |
|||
are packaged separately, a short form of the format, prepended by a dash, is |
|||
added to the package name. We use @code{-ttf} for TrueType fonts, |
|||
@code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1 |
|||
fonts. |
|||
|
|||
|
|||
@node 代码风格 |
|||
@section 代码风格 |
|||
|
|||
In general our code follows the GNU Coding Standards (@pxref{Top,,, |
|||
standards, GNU Coding Standards}). However, they do not say much about |
|||
Scheme, so here are some additional rules. |
|||
|
|||
@menu |
|||
* Programming Paradigm:: How to compose your elements. |
|||
* Modules:: Where to store your code? |
|||
* Data Types and Pattern Matching:: Implementing data structures. |
|||
* Formatting Code:: Writing conventions. |
|||
@end menu |
|||
|
|||
@node Programming Paradigm |
|||
@subsection Programming Paradigm |
|||
|
|||
Scheme code in Guix is written in a purely functional style. One exception |
|||
is code that involves input/output, and procedures that implement low-level |
|||
concepts, such as the @code{memoize} procedure. |
|||
|
|||
@node Modules |
|||
@subsection Modules |
|||
|
|||
Guile modules that are meant to be used on the builder side must live in the |
|||
@code{(guix build @dots{})} name space. They must not refer to other Guix |
|||
or GNU modules. However, it is OK for a ``host-side'' module to use a |
|||
build-side module. |
|||
|
|||
Modules that deal with the broader GNU system should be in the @code{(gnu |
|||
@dots{})} name space rather than @code{(guix @dots{})}. |
|||
|
|||
@node Data Types and Pattern Matching |
|||
@subsection Data Types and Pattern Matching |
|||
|
|||
The tendency in classical Lisp is to use lists to represent everything, and |
|||
then to browse them ``by hand'' using @code{car}, @code{cdr}, @code{cadr}, |
|||
and co. There are several problems with that style, notably the fact that |
|||
it is hard to read, error-prone, and a hindrance to proper type error |
|||
reports. |
|||
|
|||
Guix code should define appropriate data types (for instance, using |
|||
@code{define-record-type*}) rather than abuse lists. In addition, it should |
|||
use pattern matching, via Guile’s @code{(ice-9 match)} module, especially |
|||
when matching lists. |
|||
|
|||
@node Formatting Code |
|||
@subsection Formatting Code |
|||
|
|||
@cindex formatting code |
|||
@cindex coding style |
|||
When writing Scheme code, we follow common wisdom among Scheme programmers. |
|||
In general, we follow the @url{http://mumble.net/~campbell/scheme/style.txt, |
|||
Riastradh's Lisp Style Rules}. This document happens to describe the |
|||
conventions mostly used in Guile’s code too. It is very thoughtful and well |
|||
written, so please do read it. |
|||
|
|||
Some special forms introduced in Guix, such as the @code{substitute*} macro, |
|||
have special indentation rules. These are defined in the |
|||
@file{.dir-locals.el} file, which Emacs automatically uses. Also note that |
|||
Emacs-Guix provides @code{guix-devel-mode} mode that indents and highlights |
|||
Guix code properly (@pxref{Development,,, emacs-guix, The Emacs-Guix |
|||
Reference Manual}). |
|||
|
|||
@cindex indentation, of code |
|||
@cindex formatting, of code |
|||
If you do not use Emacs, please make sure to let your editor knows these |
|||
rules. To automatically indent a package definition, you can also run: |
|||
|
|||
@example |
|||
./etc/indent-code.el gnu/packages/@var{file}.scm @var{package} |
|||
@end example |
|||
|
|||
@noindent |
|||
This automatically indents the definition of @var{package} in |
|||
@file{gnu/packages/@var{file}.scm} by running Emacs in batch mode. To |
|||
indent a whole file, omit the second argument: |
|||
|
|||
@example |
|||
./etc/indent-code.el gnu/services/@var{file}.scm |
|||
@end example |
|||
|
|||
@cindex Vim, Scheme code editing |
|||
If you are editing code with Vim, we recommend that you run @code{:set |
|||
autoindent} so that your code is automatically indented as you type. |
|||
Additionally, @uref{https://www.vim.org/scripts/script.php?script_id=3998, |
|||
@code{paredit.vim}} may help you deal with all these parentheses. |
|||
|
|||
We require all top-level procedures to carry a docstring. This requirement |
|||
can be relaxed for simple private procedures in the @code{(guix build |
|||
@dots{})} name space, though. |
|||
|
|||
Procedures should not have more than four positional parameters. Use |
|||
keyword parameters for procedures that take more than four parameters. |
|||
|
|||
|
|||
@node 提交补丁 |
|||
@section 提交补丁 |
|||
|
|||
Development is done using the Git distributed version control system. Thus, |
|||
access to the repository is not strictly necessary. We welcome |
|||
contributions in the form of patches as produced by @code{git format-patch} |
|||
sent to the @email{guix-patches@@gnu.org} mailing list. |
|||
|
|||
This mailing list is backed by a Debbugs instance accessible at |
|||
@uref{https://bugs.gnu.org/guix-patches}, which allows us to keep track of |
|||
submissions. Each message sent to that mailing list gets a new tracking |
|||
number assigned; people can then follow up on the submission by sending |
|||
email to @code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is the tracking |
|||
number (@pxref{Sending a Patch Series}). |
|||
|
|||
Please write commit logs in the ChangeLog format (@pxref{Change Logs,,, |
|||
standards, GNU Coding Standards}); you can check the commit history for |
|||
examples. |
|||
|
|||
Before submitting a patch that adds or modifies a package definition, please |
|||
run through this check list: |
|||
|
|||
@enumerate |
|||
@item |
|||
If the authors of the packaged software provide a cryptographic signature |
|||
for the release tarball, make an effort to verify the authenticity of the |
|||
archive. For a detached GPG signature file this would be done with the |
|||
@code{gpg --verify} command. |
|||
|
|||
@item |
|||
Take some time to provide an adequate synopsis and description for the |
|||
package. @xref{简介和描述}, for some guidelines. |
|||
|
|||
@item |
|||
Run @code{guix lint @var{package}}, where @var{package} is the name of the |
|||
new or modified package, and fix any errors it reports (@pxref{Invoking guix |
|||
lint}). |
|||
|
|||
@item |
|||
Make sure the package builds on your platform, using @code{guix build |
|||
@var{package}}. |
|||
|
|||
@item |
|||
We recommend you also try building the package on other supported |
|||
platforms. As you may not have access to actual hardware platforms, we |
|||
recommend using the @code{qemu-binfmt-service-type} to emulate them. In |
|||
order to enable it, add the following service to the list of services in |
|||
your @code{operating-system} configuration: |
|||
|
|||
@example |
|||
(service qemu-binfmt-service-type |
|||
(qemu-binfmt-configuration |
|||
(platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el")) |
|||
(guix-support? #t))) |
|||
@end example |
|||
|
|||
Then reconfigure your system. |
|||
|
|||
You can then build packages for different platforms by specifying the |
|||
@code{--system} option. For example, to build the "hello" package for the |
|||
armhf, aarch64, or mips64 architectures, you would run the following |
|||
commands, respectively: |
|||
@example |
|||
guix build --system=armhf-linux --rounds=2 hello |
|||
guix build --system=aarch64-linux --rounds=2 hello |
|||
guix build --system=mips64el-linux --rounds=2 hello |
|||
@end example |
|||
|
|||
@item |
|||
@cindex bundling |
|||
Make sure the package does not use bundled copies of software already |
|||
available as separate packages. |
|||
|
|||
Sometimes, packages include copies of the source code of their dependencies |
|||
as a convenience for users. However, as a distribution, we want to make |
|||
sure that such packages end up using the copy we already have in the |
|||
distribution, if there is one. This improves resource usage (the dependency |
|||
is built and stored only once), and allows the distribution to make |
|||
transverse changes such as applying security updates for a given software |
|||
package in a single place and have them affect the whole system---something |
|||
that bundled copies prevent. |
|||
|
|||
@item |
|||
Take a look at the profile reported by @command{guix size} (@pxref{Invoking |
|||
guix size}). This will allow you to notice references to other packages |
|||
unwillingly retained. It may also help determine whether to split the |
|||
package (@pxref{Packages with Multiple Outputs}), and which optional |
|||
dependencies should be used. In particular, avoid adding @code{texlive} as |
|||
a dependency: because of its extreme size, use @code{texlive-tiny} or |
|||
@code{texlive-union} instead. |
|||
|
|||
@item |
|||
For important changes, check that dependent package (if applicable) are not |
|||
affected by the change; @code{guix refresh --list-dependent @var{package}} |
|||
will help you do that (@pxref{Invoking guix refresh}). |
|||
|
|||
@c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>. |
|||
@cindex branching strategy |
|||
@cindex rebuild scheduling strategy |
|||
Depending on the number of dependent packages and thus the amount of |
|||
rebuilding induced, commits go to different branches, along these lines: |
|||
|
|||
@table @asis |
|||
@item 300 dependent packages or less |
|||
@code{master} branch (non-disruptive changes). |
|||
|
|||
@item between 300 and 1,200 dependent packages |
|||
@code{staging} branch (non-disruptive changes). This branch is intended to |
|||
be merged in @code{master} every 3 weeks or so. Topical changes (e.g., an |
|||
update of the GNOME stack) can instead go to a specific branch (say, |
|||
@code{gnome-updates}). |
|||
|
|||
@item more than 1,200 dependent packages |
|||
@code{core-updates} branch (may include major and potentially disruptive |
|||
changes). This branch is intended to be merged in @code{master} every 2.5 |
|||
months or so. |
|||
@end table |
|||
|
|||
All these branches are @uref{https://hydra.gnu.org/project/gnu, tracked by |
|||
our build farm} and merged into @code{master} once everything has been |
|||
successfully built. This allows us to fix issues before they hit users, and |
|||
to reduce the window during which pre-built binaries are not available. |
|||
|
|||
@c TODO: It would be good with badges on the website that tracks these |
|||
@c branches. Or maybe even a status page. |
|||
Generally, branches other than @code{master} are considered @emph{frozen} if |
|||
there has been a recent evaluation, or there is a corresponding @code{-next} |
|||
branch. Please ask on the mailing list or IRC if unsure where to place a |
|||
patch. |
|||
|
|||
@item |
|||
@cindex determinism, of build processes |
|||
@cindex reproducible builds, checking |
|||
Check whether the package's build process is deterministic. This typically |
|||
means checking whether an independent build of the package yields the exact |
|||
same result that you obtained, bit for bit. |
|||
|
|||
A simple way to do that is by building the same package several times in a |
|||
row on your machine (@pxref{Invoking guix build}): |
|||
|
|||
@example |
|||
guix build --rounds=2 my-package |
|||
@end example |
|||
|
|||
This is enough to catch a class of common non-determinism issues, such as |
|||
timestamps or randomly-generated output in the build result. |
|||
|
|||
Another option is to use @command{guix challenge} (@pxref{Invoking guix |
|||
challenge}). You may run it once the package has been committed and built |
|||
by @code{@value{SUBSTITUTE-SERVER}} to check whether it obtains the same |
|||
result as you did. Better yet: Find another machine that can build it and |
|||
run @command{guix publish}. Since the remote build machine is likely |
|||
different from yours, this can catch non-determinism issues related to the |
|||
hardware---e.g., use of different instruction set extensions---or to the |
|||
operating system kernel---e.g., reliance on @code{uname} or @file{/proc} |
|||
files. |
|||
|
|||
@item |
|||
When writing documentation, please use gender-neutral wording when referring |
|||
to people, such as @uref{https://en.wikipedia.org/wiki/Singular_they, |
|||
singular ``they''@comma{} ``their''@comma{} ``them''}, and so forth. |
|||
|
|||
@item |
|||
Verify that your patch contains only one set of related changes. Bundling |
|||
unrelated changes together makes reviewing harder and slower. |
|||
|
|||
Examples of unrelated changes include the addition of several packages, or a |
|||
package update along with fixes to that package. |
|||
|
|||
@item |
|||
Please follow our code formatting rules, possibly running the |
|||
@command{etc/indent-code.el} script to do that automatically for you |
|||
(@pxref{Formatting Code}). |
|||
|
|||
@item |
|||
When possible, use mirrors in the source URL (@pxref{Invoking guix |
|||
download}). Use reliable URLs, not generated ones. For instance, GitHub |
|||
archives are not necessarily identical from one generation to the next, so |
|||
in this case it's often better to clone the repository. Don't use the |
|||
@command{name} field in the URL: it is not very useful and if the name |
|||
changes, the URL will probably be wrong. |
|||
|
|||
@end enumerate |
|||
|
|||
When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as a |
|||
subject. You may use your email client or the @command{git send-email} |
|||
command (@pxref{Sending a Patch Series}). We prefer to get patches in plain |
|||
text messages, either inline or as MIME attachments. You are advised to pay |
|||
attention if your email client changes anything like line breaks or |
|||
indentation which could potentially break the patches. |
|||
|
|||
When a bug is resolved, please close the thread by sending an email to |
|||
@email{@var{NNN}-done@@debbugs.gnu.org}. |
|||
|
|||
@unnumberedsubsec Sending a Patch Series |
|||
@anchor{Sending a Patch Series} |
|||
@cindex patch series |
|||
@cindex @code{git send-email} |
|||
@cindex @code{git-send-email} |
|||
|
|||
@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html |
|||
When sending a patch series (e.g., using @code{git send-email}), please |
|||
first send one message to @email{guix-patches@@gnu.org}, and then send |
|||
subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure they |
|||
are kept together. See @uref{https://debbugs.gnu.org/Advanced.html, the |
|||
Debbugs documentation} for more information. |
|||
25352
doc/guix.zh_CN.texi
File diff suppressed because it is too large
View File
File diff suppressed because it is too large
View File
Write
Preview
Loading…
Cancel
Save
Reference in new issue