You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

898 lines
38 KiB

  1. @node 贡献
  2. @chapter 贡献
  3. 这个项目是大家合作的成果,我们需要你的帮助以更好地发展。请通过
  4. @email{guix-devel@@gnu.org} 和 Freenode IRC 上的 @code{#guix} 联系我们。我们欢迎
  5. 您的想法、bug反馈、补丁,以及任何可能对项目有帮助的贡献。我们特别欢迎帮助我们打
  6. 包(@pxref{打包指导})。
  7. @cindex 行为准则和贡献者
  8. @cindex 贡献者契约
  9. 我们希望提供一个温暖、友好,并且没有骚扰的的环境,这样每个人都能尽最大努力贡献。
  10. 为了这个目的,我们的项目遵循“贡献者契约”,这个契约是根据
  11. @url{http://contributor-covenant.org/}制定的。你可以在源代码目录里的
  12. @file{CODE-OF-CONDUCT}文件里找到一份本地版。
  13. 贡献者在提交补丁和网上交流时不需要使用法律认可的名字。他们可以使用任何名字或者假
  14. 名。
  15. @menu
  16. * 从Git编译:: 最新的并且最好的.
  17. * 在安装之前运行Guix:: 黑客技巧。
  18. * 完美的配置:: 正确的工具。
  19. * 打包指导:: Growing the distribution.
  20. * 代码风格:: 开发者的卫生情况
  21. * 提交补丁:: 分享你的工作。
  22. @end menu
  23. @node 从Git编译
  24. @section 从Git编译
  25. 如果你想折腾Guix本身,建议使用Git仓库里最新的版本:
  26. @example
  27. git clone https://git.savannah.gnu.org/git/guix.git
  28. @end example
  29. 当从Git检出构建Guix时,除安装指导(@pxref{Requirements})里提及的软件包之外还需
  30. 要这些包。
  31. @itemize
  32. @item @url{http://gnu.org/software/autoconf/, GNU Autoconf};
  33. @item @url{http://gnu.org/software/automake/, GNU Automake};
  34. @item @url{http://gnu.org/software/gettext/, GNU Gettext};
  35. @item @url{http://gnu.org/software/texinfo/, GNU Texinfo};
  36. @item @url{http://www.graphviz.org/, Graphviz};
  37. @item @url{http://www.gnu.org/software/help2man/, GNU Help2man (可选)}。
  38. @end itemize
  39. 设置Guix开发环境的最简单的方式当然是使用Guix!下面这些命令启动一个shell,所有的
  40. 依赖和环境变量都为折腾Guix设置好了:
  41. @example
  42. guix environment guix
  43. @end example
  44. 这个命令更多的信息请参考@xref{Invoking guix environment}。额外的依赖可以通过
  45. @option{--ad-hoc}选项添加:
  46. @example
  47. guix environment guix --ad-hoc help2man git strace
  48. @end example
  49. 运行 @command{./bootstrap} 以使用Autoconf和Automake生成编译系统的基础框架。如果
  50. 你的得到这样的错误:
  51. @example
  52. configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
  53. @end example
  54. @noindent
  55. 它可能意味着Autoconf无法找到由pkg-config提供的@file{pkg.m4}。请确保@file{pkg.m4}
  56. 可用。由Guile提供的@file{guile.m4}宏也类似。假如你的Automake安装在
  57. @file{/usr/local},那么它不会从@file{/usr/share}里寻找@file{.m4}文件。这种情况下,
  58. 你必须执行下面这个命令:
  59. @example
  60. export ACLOCAL_PATH=/usr/share/aclocal
  61. @end example
  62. 参考@xref{Macro Search Path,,, automake, The GNU Automake Manual}.
  63. 然后,像正常一样运行@command{./configure}。确保提供
  64. @code{--localstatedir=@var{directory}}参数,@var{directory}是你当前系统的
  65. @code{localstatedir}的值。(@pxref{The Store})
  66. 最后,用@code{make check}执行测试(@pxref{Running the Test Suite})。如果遇到任
  67. 何错误,请参考“安装指导”(@pxref{Installation})或者给
  68. @email{guix-devel@@gnu.org, 邮件列表}发邮件。
  69. @node 在安装之前运行Guix
  70. @section 在安装之前运行Guix
  71. 为了保持一个合适的工作环境,你会发现在你的本地代码树里测试修改而不用安装它们会很
  72. 有用。TODO: So that you can distinguish between your ``end-user'' hat and your
  73. ``motley'' costume.
  74. 这样,即使你没有运行@code{make install},所有的命令行工具都可以使用。为此,你先
  75. 要有一个包含全部依赖的环境(@pxref{从Git编译}),然后,为所有的命令添加
  76. 前缀@command{./pre-inst-env}(@file{pre-inst-env}脚本在Guix编译树的最顶层,它由
  77. @command{./configure}生成),如@footnote{@command{sudo}命令的@option{-E}参数
  78. 确保@code{GUILE_LOAD_PATH}被正确设置,从而@command{guix-daemon}和它使用的工具可
  79. 以找到它们需要的Guile模块。}:
  80. @example
  81. $ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
  82. $ ./pre-inst-env guix build hello
  83. @end example
  84. @noindent
  85. 类似的,对于使用Guix模块的Guile会话:
  86. @example
  87. $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
  88. ;;; ("x86_64-linux")
  89. @end example
  90. @noindent
  91. @cindex REPL
  92. @cindex read-eval-print loop
  93. @dots{} and for a REPL (@pxref{Using Guile Interactively,,, guile, Guile
  94. Reference Manual}):
  95. @example
  96. $ ./pre-inst-env guile
  97. scheme@@(guile-user)> ,use(guix)
  98. scheme@@(guile-user)> ,use(gnu)
  99. scheme@@(guile-user)> (define snakes
  100. (fold-packages
  101. (lambda (package lst)
  102. (if (string-prefix? "python"
  103. (package-name package))
  104. (cons package lst)
  105. lst))
  106. '()))
  107. scheme@@(guile-user)> (length snakes)
  108. $1 = 361
  109. @end example
  110. @command{pre-inst-env}脚本设置为此好了所有必要的的环境变量,包括@env{PATH}和
  111. @env{GUILE_LOAD_PATH}。
  112. @command{./pre-inst-env guix pull} @emph{不} 会更新本地源代码树,它只更新符号链
  113. 接@file{~/.config/guix/current} (@pxref{Invoking guix pull})。如果你想更新本地源
  114. 代码树,请运行@command{git pull}。
  115. @node 完美的配置
  116. @section 完美的配置
  117. 折腾Guix的完美配置也是折腾Guile的完美配置@pxref{Using Guile in Emacs,,, guile,
  118. Guile Reference Manual})。首先,你需要的不仅是一个编辑器,你需要
  119. @url{http://www.gnu.org/software/emacs, Emacs},以及美妙的
  120. @url{http://nongnu.org/geiser/, Geiser}。为此,请运行:
  121. @example
  122. guix package -i emacs guile emacs-geiser
  123. @end example
  124. Geiser允许在Emacs里进行交互式的、增长式的开发:buffer里的代码补全和执行,获取一
  125. 行的文档(docstrings),上下文敏感的补全,@kbd{M-.}跳转到对象定义,测试代码的
  126. REPL,及更多(@pxref{Introduction,,, geiser, Geiser User Manual})。为了方便的
  127. Guix开发,请确保修改Guile的加载路径(load path)以使其能从你的项目里找到源代码文
  128. 件。
  129. @lisp
  130. ;; @r{假设Guix项目在 ~/src/guix.}
  131. (with-eval-after-load 'geiser-guile
  132. (add-to-list 'geiser-guile-load-path "~/src/guix"))
  133. @end lisp
  134. 真正编辑代码时别忘了Emacs自带了方便的Scheme模式。而且,一定不要错过
  135. @url{http://www.emacswiki.org/emacs/ParEdit, Paredit}。它提供了直接操作语法树的
  136. 的功能,例如,用S-表达式替换父节点,为S-表达式添加、删除前后的括号,删除后面的S-
  137. 表达式,等等。
  138. @cindex 代码片段
  139. @cindex 模板
  140. @cindex reducing boilerplate
  141. 在@file{etc/snippets}文件夹里,我们还为普通的git commit信息和软件包定义提供模板。
  142. 这些模板可以通过@url{http://joaotavora.github.io/yasnippet/, YASnippet}使用,它
  143. 可以把短的触发字符串扩展成交互式的文字片段。你可能希望将这个文件夹添加到Emacs的
  144. @var{yas-snippet-dirs}变量里。
  145. @lisp
  146. ;; @r{假设Guix项目在 ~/src/guix.}
  147. (with-eval-after-load 'yasnippet
  148. (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets"))
  149. @end lisp
  150. commit信息片段显示staged文件需要依赖@url{https://magit.vc/, Magit}。编辑commit信
  151. 息时,输入@code{add},然后按@kbd{TAB}就可以插入一段用于新增软件包的模板;输入
  152. @code{update},然后按@kbd{TAB}可以插入一段更新软件包的模板;输入@code{https}然后
  153. 按@kbd{TAB}可以插入一段修改主页URI为HTTPS的模板。
  154. @code{scheme-mode}最重要的模板可以通过输入@code{package...},然后按@kbd{TAB}触发。
  155. 这个片段还插入了触发字符串@code{origin...},以进一步展开。@code{origin}片段更进
  156. 一步的可能插入其它以@code{...}结尾的触发字符串,它们可以被继续展开。
  157. @node 打包指导
  158. @section 打包指导
  159. @cindex 软件包, 创建
  160. 这个GNU发行版正在开发的早期阶段,可能缺少一些你喜欢的软件。这个章节介绍你可以怎
  161. 样帮助这个发行版成长。
  162. 自由软件通常以@dfn{源代码包}的形式分发,通常是包含完整代码的@file{tar.gz}包。添
  163. 加软件包到这个发行版意味着两件事:添加描述如何编译包的@dfn{配方}和一系列依赖软件,
  164. 以及添加配方之外的@dfn{软件包元数据},如一段文字描述和证书信息。
  165. 在Guix里所有这些信息都包含在@dfn{软件包定义}里。软件包定义提供了软件包的高层视角。
  166. 它们使用Scheme编程语言编写,事实上,对每个软件包我们都定义一个绑定到软件包定义的
  167. 的变量,并且从模块(@pxref{Package Modules})中导出那个变量。然而,深入的Scheme
  168. 知识@emph{不}是创建软件包的前提条件。若要了解软件包的更多信息,@pxref{Defining
  169. Packages}。
  170. 一旦软件包定义准备好了,并且包存在Guix代码树的一个文件里,你可以用@command{guix
  171. build} (@pxref{Invoking guix build})命令测试它。假设这个新软件包的名字叫做
  172. @code{gnew},你可以在Guix编译树里运行这个命令(@pxref{在安装之前运行Guix}):
  173. @example
  174. ./pre-inst-env guix build gnew --keep-failed
  175. @end example
  176. 使用@code{--keep-failed}参数会保留失败的编译树,这可以使调试编译错误更容易。
  177. @code{--log-file}也是一个调试时很有用的参数,它可以用来访问编译日志。
  178. 如果@command{guix}命令找不到这个软件包,那可能是因为源文件包含语法错误,或者缺少
  179. 导出软件包的@code{define-public}语句。为了查找错误,你可以用Guile导入这个模块以
  180. 了解这个错误的详情:
  181. @example
  182. ./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
  183. @end example
  184. 一旦你的软件包可以正确编译,请给我们发送补丁(@pxref{提交补丁})。当然,
  185. 如果你需要帮助,我们也会很乐意帮助你。一旦补丁被提交到Guix仓库里,这个新的软件包
  186. 会被自动地在支持的平台上编译@url{http://hydra.gnu.org/jobset/gnu/master, our
  187. continuous integration system}。
  188. @cindex substituter
  189. 用户可以通过运行@command{guix pull}命令获取最新的软件包定义(@pxref{Invoking
  190. guix pull})。当@code{@value{SUBSTITUTE-SERVER}}编译好这些软件包之后,安装这些软
  191. 件包时会自动从服务器(@pxref{Substitutes})上下载编译好的二进制包。唯一需要人工
  192. 干预的地方是评审和应用代码补丁。
  193. @menu
  194. * 软件自由:: 什么可以进入这个发行版。
  195. * 软件包命名:: 名字里包含什么?
  196. * 版本号:: 当名字不够时
  197. * 简介和描述:: 帮助用户寻找合适的软件包
  198. * Python模块:: 接触英式的喜剧
  199. * Perl模块:: 小珍珠。
  200. * Java包:: 喝咖啡休息。
  201. * 字体:: 字体的乐趣。
  202. @end menu
  203. @node 软件自由
  204. @subsection 软件自由
  205. @c ===========================================================================
  206. @c
  207. @c This file was generated with po4a. Translate the source file.
  208. @c
  209. @c ===========================================================================
  210. @c Adapted from http://www.gnu.org/philosophy/philosophy.html.
  211. @cindex 自由软件
  212. 开发GNU操作系统是为了用户拥有计算的自由。GNU是@dfn{自由软件},这意味着它有
  213. @url{http://www.gnu.org/philosophy/free-sw.html,四项重要的自由}:运行程序的自由,
  214. 以源代码形式学习和修改程序的自由,原样重新分发副本的自由,和分发修改后的版本的自
  215. 由。GNU发行版里包含的软件包只提供遵守这四项自由的软件。
  216. 此外,GNU发行版遵循
  217. @url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,自由软
  218. 件发行版准则}。这些准则拒绝非自由的固件和对非自由软件的推荐,并讨论解决商标和专
  219. 利的方法。
  220. 某些上游的软件包源代码包含一小部分违反上述准则的可选的子集,比如这个子集本身就是
  221. 非自由代码。这时,这些讨厌的代码需要用合适的补丁或者软件包定义(@pxref{Defining
  222. Packages})里的@code{origin}里的代码片段移除。这样,@code{guix build --source}就
  223. 可以返回自由的源代码而不是未经修改的上游源代码。
  224. @node 软件包命名
  225. @subsection 软件包命名
  226. @cindex 软件包名字
  227. 一个软件包事实上有两个名字:第一个是@emph{Scheme变量}的名字,即用
  228. @code{define-public}定义的名字。通过这个名字,软件包可以被Scheme代码找到,如用作
  229. 其它软件包的输入。第二个名字是软件包定义里的@code{name}属性的字符串值。这个名字
  230. 用于软件包管理命令,如:@command{guix package},@command{guix build}
  231. 两个名字通常是相同的,常是上游项目名字转成小写字母并把下划线替换成连字符的结果。
  232. 比如,GNUnet转成@code{gnunet},SDL_net转成@code{sdl-net}。
  233. 我们不给库软件包添加@code{lib}前缀,除非它是项目官方名字的一部分。但是
  234. @pxref{Python模块}和@ref{Perl模块}有关于Python和Perl语言的特殊规则。
  235. 字体软件包的名字处理起来不同,@pxref{字体}.
  236. @node 版本号
  237. @subsection 版本号
  238. @cindex 软件包版本
  239. 我们通常只为每个自由软件的最新版本打包。但是有时候,比如对于版本不兼容的库,需要
  240. 有同一个软件包的两个或更多版本。它们需要使用不同的Scheme变量名。我们为最新的版本
  241. 使用@ref{软件包命名}里规定的名字,旧的版本使用加上后缀的名字,后缀是@code{-}
  242. 和可以区分开版本号的版本号的最小前缀。
  243. 软件包定义里的名字对于同一个软件包的所有版本都是相同的,并且不含有版本号。
  244. 例如,GTK+的2.24.20和3.9.12两个版本可以这样打包:
  245. @example
  246. (define-public gtk+
  247. (package
  248. (name "gtk+")
  249. (version "3.9.12")
  250. ...))
  251. (define-public gtk+-2
  252. (package
  253. (name "gtk+")
  254. (version "2.24.20")
  255. ...))
  256. @end example
  257. 如果我们还需要GTK+ 3.8.2,就这样打包
  258. @example
  259. (define-public gtk+-3.8
  260. (package
  261. (name "gtk+")
  262. (version "3.8.2")
  263. ...))
  264. @end example
  265. @c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
  266. @c for a discussion of what follows.
  267. @cindex 用于版本控制快照的版本号
  268. 有时候,我们为软件包上游的版本控制系统(VCS)的快照而不是正式发布版打包。这是特
  269. 殊情况,因为决定哪个是稳定版的权力应该属于上游开发者。然而,有时候这是必须的。那
  270. 么,我们该如何决定写在@code{version}里的版本号呢?
  271. 显然,我们需要让VCS快照的commit ID在版本号中体现出来,但是我们也需要确保版本号单
  272. 调递增,以便@command{guix package --upgrade}决定哪个版本号更新。由于commit ID,
  273. 尤其是Git的commit ID,不是单调递增的,我们添加一个每次升级快照时都手动增长的
  274. revision数字。最后的版本号字符串看起来是这样:
  275. @example
  276. 2.0.11-3.cabba9e
  277. ^ ^ ^
  278. | | `-- 上游的commit ID
  279. | |
  280. | `--- Guix软件包的revision
  281. |
  282. 最新的上游版本号
  283. @end example
  284. 把@code{版本号}里的commit ID截短,比如只取7个数字,是一个好主意。它避免了美学上
  285. 的烦恼(假设美学在这里很重要),以及操作系统限制引起的问题(比如Linux内核的127字
  286. 节)。尽管如此,在@code{origin}里最好使用完整的commit ID,以避免混淆。
  287. @example
  288. (define my-package
  289. (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
  290. (revision "1")) ;Guix软件包的revision
  291. (package
  292. (version (git-version "0.9" revision commit))
  293. (source (origin
  294. (method git-fetch)
  295. (uri (git-reference
  296. (url "git://example.org/my-package.git")
  297. (commit commit)))
  298. (sha256 (base32 "1mbikn@dots{}"))
  299. (file-name (git-file-name name version))))
  300. ;; @dots{}
  301. )))
  302. @end example
  303. @node 简介和描述
  304. @subsection 简介和描述
  305. @cindex 软件包描述
  306. @cindex 软件包简介
  307. 我们已经看到,GNU@tie{}Guix里的每个软件包都包含一个简介(synopsis)和一个描述
  308. (description)(@pxref{Defining Packages})。简介和描述很重要:它们是
  309. @command{guix package --search}搜索的信息,并且是帮助用户决定一个软件包是否符合
  310. 自己需求的重要信息。因此,打包的人应该关注怎样写它们的内容。
  311. 简介必须以大写字母开头,并且不能以句号结尾。它们不能以 ``a'' 或者 ``the'' 等没有
  312. 意义的词开头。例如 ``File-frobbing tool'' 要比 ``A tool that frobs files'' 更好。
  313. 简介需要说明软件包是什么--如 ``Core GNU utilities (file, text, shell)'',或者
  314. 它的用途--如 GNU@tie{}grep 的简介是 ``Print lines matching a pattern''。
  315. Keep in mind that the synopsis must be meaningful for a very wide audience.
  316. For example, ``Manipulate alignments in the SAM format'' might make sense
  317. for a seasoned bioinformatics researcher, but might be fairly unhelpful or
  318. even misleading to a non-specialized audience. It is a good idea to come up
  319. with a synopsis that gives an idea of the application domain of the
  320. package. In this example, this might give something like ``Manipulate
  321. nucleotide sequence alignments'', which hopefully gives the user a better
  322. idea of whether this is what they are looking for.
  323. Descriptions should take between five and ten lines. Use full sentences,
  324. and avoid using acronyms without first introducing them. Please avoid
  325. marketing phrases such as ``world-leading'', ``industrial-strength'', and
  326. ``next-generation'', and avoid superlatives like ``the most
  327. advanced''---they are not helpful to users looking for a package and may
  328. even sound suspicious. Instead, try to be factual, mentioning use cases and
  329. features.
  330. @cindex Texinfo markup, in package descriptions
  331. Descriptions can include Texinfo markup, which is useful to introduce
  332. ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or hyperlinks
  333. (@pxref{Overview,,, texinfo, GNU Texinfo}). However you should be careful
  334. when using some characters for example @samp{@@} and curly braces which are
  335. the basic special characters in Texinfo (@pxref{Special Characters,,,
  336. texinfo, GNU Texinfo}). User interfaces such as @command{guix package
  337. --show} take care of rendering it appropriately.
  338. Synopses and descriptions are translated by volunteers
  339. @uref{http://translationproject.org/domain/guix-packages.html, at the
  340. Translation Project} so that as many users as possible can read them in
  341. their native language. User interfaces search them and display them in the
  342. language specified by the current locale.
  343. To allow @command{xgettext} to extract them as translatable strings,
  344. synopses and descriptions @emph{must be literal strings}. This means that
  345. you cannot use @code{string-append} or @code{format} to construct these
  346. strings:
  347. @lisp
  348. (package
  349. ;; @dots{}
  350. (synopsis "This is translatable")
  351. (description (string-append "This is " "*not*" " translatable.")))
  352. @end lisp
  353. Translation is a lot of work so, as a packager, please pay even more
  354. attention to your synopses and descriptions as every change may entail
  355. additional work for translators. In order to help them, it is possible to
  356. make recommendations or instructions visible to them by inserting special
  357. comments like this (@pxref{xgettext Invocation,,, gettext, GNU Gettext}):
  358. @example
  359. ;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
  360. (description "ARandR is designed to provide a simple visual front end
  361. for the X11 resize-and-rotate (RandR) extension. @dots{}")
  362. @end example
  363. @node Python模块
  364. @subsection Python模块
  365. @cindex python
  366. We currently package Python 2 and Python 3, under the Scheme variable names
  367. @code{python-2} and @code{python} as explained in @ref{版本号}. To
  368. avoid confusion and naming clashes with other programming languages, it
  369. seems desirable that the name of a package for a Python module contains the
  370. word @code{python}.
  371. Some modules are compatible with only one version of Python, others with
  372. both. If the package Foo compiles only with Python 3, we name it
  373. @code{python-foo}; if it compiles only with Python 2, we name it
  374. @code{python2-foo}. If it is compatible with both versions, we create two
  375. packages with the corresponding names.
  376. If a project already contains the word @code{python}, we drop this; for
  377. instance, the module python-dateutil is packaged under the names
  378. @code{python-dateutil} and @code{python2-dateutil}. If the project name
  379. starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
  380. described above.
  381. @subsubsection Specifying Dependencies
  382. @cindex inputs, for Python packages
  383. Dependency information for Python packages is usually available in the
  384. package source tree, with varying degrees of accuracy: in the
  385. @file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}.
  386. Your mission, when writing a recipe for a Python package, is to map these
  387. dependencies to the appropriate type of ``input'' (@pxref{package Reference,
  388. inputs}). Although the @code{pypi} importer normally does a good job
  389. (@pxref{Invoking guix import}), you may want to check the following check
  390. list to determine which dependency goes where.
  391. @itemize
  392. @item
  393. We currently package Python 2 with @code{setuptools} and @code{pip}
  394. installed like Python 3.4 has per default. Thus you don't need to specify
  395. either of these as an input. @command{guix lint} will warn you if you do.
  396. @item
  397. Python dependencies required at run time go into @code{propagated-inputs}.
  398. They are typically defined with the @code{install_requires} keyword in
  399. @file{setup.py}, or in the @file{requirements.txt} file.
  400. @item
  401. Python packages required only at build time---e.g., those listed with the
  402. @code{setup_requires} keyword in @file{setup.py}---or only for
  403. testing---e.g., those in @code{tests_require}---go into
  404. @code{native-inputs}. The rationale is that (1) they do not need to be
  405. propagated because they are not needed at run time, and (2) in a
  406. cross-compilation context, it's the ``native'' input that we'd want.
  407. Examples are the @code{pytest}, @code{mock}, and @code{nose} test
  408. frameworks. Of course if any of these packages is also required at
  409. run-time, it needs to go to @code{propagated-inputs}.
  410. @item
  411. Anything that does not fall in the previous categories goes to
  412. @code{inputs}, for example programs or C libraries required for building
  413. Python packages containing C extensions.
  414. @item
  415. If a Python package has optional dependencies (@code{extras_require}), it is
  416. up to you to decide whether to add them or not, based on their
  417. usefulness/overhead ratio (@pxref{提交补丁, @command{guix size}}).
  418. @end itemize
  419. @node Perl模块
  420. @subsection Perl模块
  421. @cindex perl
  422. Perl programs standing for themselves are named as any other package, using
  423. the lowercase upstream name. For Perl packages containing a single class,
  424. we use the lowercase class name, replace all occurrences of @code{::} by
  425. dashes and prepend the prefix @code{perl-}. So the class @code{XML::Parser}
  426. becomes @code{perl-xml-parser}. Modules containing several classes keep
  427. their lowercase upstream name and are also prepended by @code{perl-}. Such
  428. modules tend to have the word @code{perl} somewhere in their name, which
  429. gets dropped in favor of the prefix. For instance, @code{libwww-perl}
  430. becomes @code{perl-libwww}.
  431. @node Java包
  432. @subsection Java包
  433. @cindex java
  434. Java programs standing for themselves are named as any other package, using
  435. the lowercase upstream name.
  436. To avoid confusion and naming clashes with other programming languages, it
  437. is desirable that the name of a package for a Java package is prefixed with
  438. @code{java-}. If a project already contains the word @code{java}, we drop
  439. this; for instance, the package @code{ngsjava} is packaged under the name
  440. @code{java-ngs}.
  441. For Java packages containing a single class or a small class hierarchy, we
  442. use the lowercase class name, replace all occurrences of @code{.} by dashes
  443. and prepend the prefix @code{java-}. So the class @code{apache.commons.cli}
  444. becomes package @code{java-apache-commons-cli}.
  445. @node 字体
  446. @subsection 字体
  447. @cindex fonts
  448. For fonts that are in general not installed by a user for typesetting
  449. purposes, or that are distributed as part of a larger software package, we
  450. rely on the general packaging rules for software; for instance, this applies
  451. to the fonts delivered as part of the X.Org system or fonts that are part of
  452. TeX Live.
  453. To make it easier for a user to search for fonts, names for other packages
  454. containing only fonts are constructed as follows, independently of the
  455. upstream package name.
  456. The name of a package containing only one font family starts with
  457. @code{font-}; it is followed by the foundry name and a dash @code{-} if the
  458. foundry is known, and the font family name, in which spaces are replaced by
  459. dashes (and as usual, all upper case letters are transformed to lower
  460. case). For example, the Gentium font family by SIL is packaged under the
  461. name @code{font-sil-gentium}.
  462. For a package containing several font families, the name of the collection
  463. is used in the place of the font family name. For instance, the Liberation
  464. fonts consist of three families, Liberation Sans, Liberation Serif and
  465. Liberation Mono. These could be packaged separately under the names
  466. @code{font-liberation-sans} and so on; but as they are distributed together
  467. under a common name, we prefer to package them together as
  468. @code{font-liberation}.
  469. In the case where several formats of the same font family or font collection
  470. are packaged separately, a short form of the format, prepended by a dash, is
  471. added to the package name. We use @code{-ttf} for TrueType fonts,
  472. @code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
  473. fonts.
  474. @node 代码风格
  475. @section 代码风格
  476. In general our code follows the GNU Coding Standards (@pxref{Top,,,
  477. standards, GNU Coding Standards}). However, they do not say much about
  478. Scheme, so here are some additional rules.
  479. @menu
  480. * Programming Paradigm:: How to compose your elements.
  481. * Modules:: Where to store your code?
  482. * Data Types and Pattern Matching:: Implementing data structures.
  483. * Formatting Code:: Writing conventions.
  484. @end menu
  485. @node Programming Paradigm
  486. @subsection Programming Paradigm
  487. Scheme code in Guix is written in a purely functional style. One exception
  488. is code that involves input/output, and procedures that implement low-level
  489. concepts, such as the @code{memoize} procedure.
  490. @node Modules
  491. @subsection Modules
  492. Guile modules that are meant to be used on the builder side must live in the
  493. @code{(guix build @dots{})} name space. They must not refer to other Guix
  494. or GNU modules. However, it is OK for a ``host-side'' module to use a
  495. build-side module.
  496. Modules that deal with the broader GNU system should be in the @code{(gnu
  497. @dots{})} name space rather than @code{(guix @dots{})}.
  498. @node Data Types and Pattern Matching
  499. @subsection Data Types and Pattern Matching
  500. The tendency in classical Lisp is to use lists to represent everything, and
  501. then to browse them ``by hand'' using @code{car}, @code{cdr}, @code{cadr},
  502. and co. There are several problems with that style, notably the fact that
  503. it is hard to read, error-prone, and a hindrance to proper type error
  504. reports.
  505. Guix code should define appropriate data types (for instance, using
  506. @code{define-record-type*}) rather than abuse lists. In addition, it should
  507. use pattern matching, via Guile’s @code{(ice-9 match)} module, especially
  508. when matching lists.
  509. @node Formatting Code
  510. @subsection Formatting Code
  511. @cindex formatting code
  512. @cindex coding style
  513. When writing Scheme code, we follow common wisdom among Scheme programmers.
  514. In general, we follow the @url{http://mumble.net/~campbell/scheme/style.txt,
  515. Riastradh's Lisp Style Rules}. This document happens to describe the
  516. conventions mostly used in Guile’s code too. It is very thoughtful and well
  517. written, so please do read it.
  518. Some special forms introduced in Guix, such as the @code{substitute*} macro,
  519. have special indentation rules. These are defined in the
  520. @file{.dir-locals.el} file, which Emacs automatically uses. Also note that
  521. Emacs-Guix provides @code{guix-devel-mode} mode that indents and highlights
  522. Guix code properly (@pxref{Development,,, emacs-guix, The Emacs-Guix
  523. Reference Manual}).
  524. @cindex indentation, of code
  525. @cindex formatting, of code
  526. If you do not use Emacs, please make sure to let your editor knows these
  527. rules. To automatically indent a package definition, you can also run:
  528. @example
  529. ./etc/indent-code.el gnu/packages/@var{file}.scm @var{package}
  530. @end example
  531. @noindent
  532. This automatically indents the definition of @var{package} in
  533. @file{gnu/packages/@var{file}.scm} by running Emacs in batch mode. To
  534. indent a whole file, omit the second argument:
  535. @example
  536. ./etc/indent-code.el gnu/services/@var{file}.scm
  537. @end example
  538. @cindex Vim, Scheme code editing
  539. If you are editing code with Vim, we recommend that you run @code{:set
  540. autoindent} so that your code is automatically indented as you type.
  541. Additionally, @uref{https://www.vim.org/scripts/script.php?script_id=3998,
  542. @code{paredit.vim}} may help you deal with all these parentheses.
  543. We require all top-level procedures to carry a docstring. This requirement
  544. can be relaxed for simple private procedures in the @code{(guix build
  545. @dots{})} name space, though.
  546. Procedures should not have more than four positional parameters. Use
  547. keyword parameters for procedures that take more than four parameters.
  548. @node 提交补丁
  549. @section 提交补丁
  550. Development is done using the Git distributed version control system. Thus,
  551. access to the repository is not strictly necessary. We welcome
  552. contributions in the form of patches as produced by @code{git format-patch}
  553. sent to the @email{guix-patches@@gnu.org} mailing list.
  554. This mailing list is backed by a Debbugs instance accessible at
  555. @uref{https://bugs.gnu.org/guix-patches}, which allows us to keep track of
  556. submissions. Each message sent to that mailing list gets a new tracking
  557. number assigned; people can then follow up on the submission by sending
  558. email to @code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is the tracking
  559. number (@pxref{Sending a Patch Series}).
  560. Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
  561. standards, GNU Coding Standards}); you can check the commit history for
  562. examples.
  563. Before submitting a patch that adds or modifies a package definition, please
  564. run through this check list:
  565. @enumerate
  566. @item
  567. If the authors of the packaged software provide a cryptographic signature
  568. for the release tarball, make an effort to verify the authenticity of the
  569. archive. For a detached GPG signature file this would be done with the
  570. @code{gpg --verify} command.
  571. @item
  572. Take some time to provide an adequate synopsis and description for the
  573. package. @xref{简介和描述}, for some guidelines.
  574. @item
  575. Run @code{guix lint @var{package}}, where @var{package} is the name of the
  576. new or modified package, and fix any errors it reports (@pxref{Invoking guix
  577. lint}).
  578. @item
  579. Make sure the package builds on your platform, using @code{guix build
  580. @var{package}}.
  581. @item
  582. We recommend you also try building the package on other supported
  583. platforms. As you may not have access to actual hardware platforms, we
  584. recommend using the @code{qemu-binfmt-service-type} to emulate them. In
  585. order to enable it, add the following service to the list of services in
  586. your @code{operating-system} configuration:
  587. @example
  588. (service qemu-binfmt-service-type
  589. (qemu-binfmt-configuration
  590. (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el"))
  591. (guix-support? #t)))
  592. @end example
  593. Then reconfigure your system.
  594. You can then build packages for different platforms by specifying the
  595. @code{--system} option. For example, to build the "hello" package for the
  596. armhf, aarch64, or mips64 architectures, you would run the following
  597. commands, respectively:
  598. @example
  599. guix build --system=armhf-linux --rounds=2 hello
  600. guix build --system=aarch64-linux --rounds=2 hello
  601. guix build --system=mips64el-linux --rounds=2 hello
  602. @end example
  603. @item
  604. @cindex bundling
  605. Make sure the package does not use bundled copies of software already
  606. available as separate packages.
  607. Sometimes, packages include copies of the source code of their dependencies
  608. as a convenience for users. However, as a distribution, we want to make
  609. sure that such packages end up using the copy we already have in the
  610. distribution, if there is one. This improves resource usage (the dependency
  611. is built and stored only once), and allows the distribution to make
  612. transverse changes such as applying security updates for a given software
  613. package in a single place and have them affect the whole system---something
  614. that bundled copies prevent.
  615. @item
  616. Take a look at the profile reported by @command{guix size} (@pxref{Invoking
  617. guix size}). This will allow you to notice references to other packages
  618. unwillingly retained. It may also help determine whether to split the
  619. package (@pxref{Packages with Multiple Outputs}), and which optional
  620. dependencies should be used. In particular, avoid adding @code{texlive} as
  621. a dependency: because of its extreme size, use @code{texlive-tiny} or
  622. @code{texlive-union} instead.
  623. @item
  624. For important changes, check that dependent package (if applicable) are not
  625. affected by the change; @code{guix refresh --list-dependent @var{package}}
  626. will help you do that (@pxref{Invoking guix refresh}).
  627. @c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>.
  628. @cindex branching strategy
  629. @cindex rebuild scheduling strategy
  630. Depending on the number of dependent packages and thus the amount of
  631. rebuilding induced, commits go to different branches, along these lines:
  632. @table @asis
  633. @item 300 dependent packages or less
  634. @code{master} branch (non-disruptive changes).
  635. @item between 300 and 1,200 dependent packages
  636. @code{staging} branch (non-disruptive changes). This branch is intended to
  637. be merged in @code{master} every 3 weeks or so. Topical changes (e.g., an
  638. update of the GNOME stack) can instead go to a specific branch (say,
  639. @code{gnome-updates}).
  640. @item more than 1,200 dependent packages
  641. @code{core-updates} branch (may include major and potentially disruptive
  642. changes). This branch is intended to be merged in @code{master} every 2.5
  643. months or so.
  644. @end table
  645. All these branches are @uref{https://hydra.gnu.org/project/gnu, tracked by
  646. our build farm} and merged into @code{master} once everything has been
  647. successfully built. This allows us to fix issues before they hit users, and
  648. to reduce the window during which pre-built binaries are not available.
  649. @c TODO: It would be good with badges on the website that tracks these
  650. @c branches. Or maybe even a status page.
  651. Generally, branches other than @code{master} are considered @emph{frozen} if
  652. there has been a recent evaluation, or there is a corresponding @code{-next}
  653. branch. Please ask on the mailing list or IRC if unsure where to place a
  654. patch.
  655. @item
  656. @cindex determinism, of build processes
  657. @cindex reproducible builds, checking
  658. Check whether the package's build process is deterministic. This typically
  659. means checking whether an independent build of the package yields the exact
  660. same result that you obtained, bit for bit.
  661. A simple way to do that is by building the same package several times in a
  662. row on your machine (@pxref{Invoking guix build}):
  663. @example
  664. guix build --rounds=2 my-package
  665. @end example
  666. This is enough to catch a class of common non-determinism issues, such as
  667. timestamps or randomly-generated output in the build result.
  668. Another option is to use @command{guix challenge} (@pxref{Invoking guix
  669. challenge}). You may run it once the package has been committed and built
  670. by @code{@value{SUBSTITUTE-SERVER}} to check whether it obtains the same
  671. result as you did. Better yet: Find another machine that can build it and
  672. run @command{guix publish}. Since the remote build machine is likely
  673. different from yours, this can catch non-determinism issues related to the
  674. hardware---e.g., use of different instruction set extensions---or to the
  675. operating system kernel---e.g., reliance on @code{uname} or @file{/proc}
  676. files.
  677. @item
  678. When writing documentation, please use gender-neutral wording when referring
  679. to people, such as @uref{https://en.wikipedia.org/wiki/Singular_they,
  680. singular ``they''@comma{} ``their''@comma{} ``them''}, and so forth.
  681. @item
  682. Verify that your patch contains only one set of related changes. Bundling
  683. unrelated changes together makes reviewing harder and slower.
  684. Examples of unrelated changes include the addition of several packages, or a
  685. package update along with fixes to that package.
  686. @item
  687. Please follow our code formatting rules, possibly running the
  688. @command{etc/indent-code.el} script to do that automatically for you
  689. (@pxref{Formatting Code}).
  690. @item
  691. When possible, use mirrors in the source URL (@pxref{Invoking guix
  692. download}). Use reliable URLs, not generated ones. For instance, GitHub
  693. archives are not necessarily identical from one generation to the next, so
  694. in this case it's often better to clone the repository. Don't use the
  695. @command{name} field in the URL: it is not very useful and if the name
  696. changes, the URL will probably be wrong.
  697. @end enumerate
  698. When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as a
  699. subject. You may use your email client or the @command{git send-email}
  700. command (@pxref{Sending a Patch Series}). We prefer to get patches in plain
  701. text messages, either inline or as MIME attachments. You are advised to pay
  702. attention if your email client changes anything like line breaks or
  703. indentation which could potentially break the patches.
  704. When a bug is resolved, please close the thread by sending an email to
  705. @email{@var{NNN}-done@@debbugs.gnu.org}.
  706. @unnumberedsubsec Sending a Patch Series
  707. @anchor{Sending a Patch Series}
  708. @cindex patch series
  709. @cindex @code{git send-email}
  710. @cindex @code{git-send-email}
  711. @c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
  712. When sending a patch series (e.g., using @code{git send-email}), please
  713. first send one message to @email{guix-patches@@gnu.org}, and then send
  714. subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure they
  715. are kept together. See @uref{https://debbugs.gnu.org/Advanced.html, the
  716. Debbugs documentation} for more information.