doc: Move most 'HACKING' informations into the manual.

* HACKING (Contributing): New section.
  (Building from Git, The Perfect Setup, Coding Style, Submitting Patches):
  Move to ...
* doc/guix.texi (Running Guix Before It Is Installed): Likewise.
* doc/contributing.texi: ... here. New file.
* doc.am (EXTRA_DIST): Use it.
* README (Installation): Adapt to it.
* configure.ac (DOT): Likewise.
master
Mathieu Lirzin 2015-06-10 13:39:54 +02:00
parent 932e7204af
commit 8c01b9d05a
6 changed files with 244 additions and 185 deletions

133
HACKING
View File

@ -2,141 +2,20 @@
#+TITLE: Hacking GNU Guix and Its Incredible Distro
Copyright © 2012, 2013, 2014, 2015 Ludovic Courtès <ludo@gnu.org>
Copyright © 2013 Nikita Karetnikov <nikita@karetnikov.org>
Copyright © 2014 Pierre-Antoine Rault <par@rigelk.eu>
Copyright © 2012, 2013, 2014 Ludovic Courtès <ludo@gnu.org>
Copyright © 2015 Mathieu Lirzin <mthl@openmailbox.org>
Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.
* Contributing
* Building from Git
See the manual for useful hacking informations, either by running
When building Guix from a checkout, the following packages are required in
addition to those mentioned in the installation instructions:
info -f doc/guix.info "(guix) Contributing"
- [[http://www.gnu.org/software/autoconf/][GNU Autoconf]]
- [[http://www.gnu.org/software/automake/][GNU Automake]]
- [[http://www.gnu.org/software/gettext/][GNU Gettext]]
- [[http://www.graphviz.org/][Graphviz]]
- [[http://www.gnu.org/software/help2man/][GNU Help2man]] (optional)
Run ./bootstrap to download the Nix daemon source code and to generate the
build system infrastructure using autoconf. It reports an error if an
inappropriate version of the above packages is being used.
If you get an error like this one:
configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
it probably means that Autoconf couldnt find pkg.m4, which is provided by
pkg-config. Make sure that pkg.m4 is available. For instance, if you
installed Automake in /usr/local, it wouldnt look for .m4 files in
/usr/share. So you have to invoke the following command in that case
$ export ACLOCAL_PATH=/usr/share/aclocal
See “info '(automake) Macro Search Path'” for more information.
Then, run ./configure as usual.
Finally, you have to invoke make check to run tests. If anything fails,
take a look at “info '(guix) Installation'” or send a message to
<guix-devel@gnu.org>.
* Running Guix before it is installed
See the same-named section in the manual.
* The Perfect Setup
The Perfect Setup to hack on Guix is basically the perfect setup used
for Guile hacking (info "(guile) Using Guile in Emacs"). First, you
need more than an editor, you need [[http://www.gnu.org/software/emacs][Emacs]], empowered by the wonderful
[[http://nongnu.org/geiser/][Geiser]].
Geiser allows for interactive and incremental development from within
Emacs: code compilation and evaluation from within buffers, access to
on-line documentation (docstrings), context-sensitive completion, M-. to
jump to an object definition, a REPL to try out your code, and more.
To actually edit the code, Emacs already has a neat Scheme mode. But in
addition to that, you must not miss [[http://www.emacswiki.org/emacs/ParEdit][Paredit]]. It provides facilities to
directly operate on the syntax tree, such as raising an s-expression or
wrapping it, swallowing or rejecting the following s-expression, etc.
* Submitting Patches
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 git format-patch sent to
guix-devel@gnu.org. Please write commit logs in the [[http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs][GNU ChangeLog
format]]; you can check the commit history for examples.
Before submitting a patch that adds or modifies a package definition, please
run guix lint PACKAGE, where PACKAGE is the name of the new or modified
package, and fix any errors it reports. In addition, please make sure the
package builds on your platform, using guix build. You may also want to
check that dependent package (if applicable) are not affected by the change;
guix refresh --list-dependent PACKAGE will help you do that.
When posting a patch to the mailing list, use "[PATCH] ..." as a subject. You
may use your email client or the git send-mail command.
As you become a regular contributor, you may find it convenient to have write
access to the repository (see below.)
* Coding Style
In general our code follows the [[info:standards][GNU Coding Standards]] (GCS). However, the GCS
do not say much about Scheme, so here are some additional rules.
** 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 memoize procedure.
** Modules
Guile modules that are meant to be used on the builder side must live in the
(guix build …) 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 (gnu …) name
space rather than (guix …).
** 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 car, cdr, 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
define-record-type*) rather than abuse lists. In addition, it should use
pattern matching, via Guiles (ice-9 match) module, especially when matching
lists.
** Formatting Code
When writing Scheme code, we follow common wisdom among Scheme programmers.
In general, we follow the [[http://mumble.net/~campbell/scheme/style.txt][Riastradh's Lisp Style Rules]]. This document happens
to describe the conventions mostly used in Guiles code too. It is very
thoughtful and well written, so please do read it.
Some special forms introduced in Guix, such as the substitute* macro, have
special indentation rules. These are defined in the .dir-locals.el file,
which Emacs automatically uses. If you do not use Emacs, please make sure to
let your editor know the rules.
We require all top-level procedures to carry a docstring. This requirement
can be relaxed for simple private procedures in the (guix build …) name space,
though.
Procedures should not have more than four positional parameters. Use keyword
parameters for procedures that take more than four parameters.
or by checking the [[http://www.gnu.org/software/guix/manual/guix.html#Contributing][web copy of the manual]].
* Commit Access

4
README
View File

@ -46,8 +46,8 @@ See the manual for the installation instructions, either by running
or by checking the [[http://www.gnu.org/software/guix/manual/guix.html#Installation][web copy of the manual]].
For information on installation from a Git checkout, please see the HACKING
file.
For information on installation from a Git checkout, please see the section
"Building from Git" in the manual.
* Installing Guix from Guix

View File

@ -179,7 +179,7 @@ AC_CACHE_SAVE
m4_include([config-daemon.ac])
dnl `dot' (from the Graphviz package) is only needed for maintainers.
dnl See `HACKING' for more info.
dnl See `Building from Git' in the manual for more info.
AM_MISSING_PROG([DOT], [dot])
dnl Manual pages.

1
doc.am
View File

@ -19,6 +19,7 @@
info_TEXINFOS = doc/guix.texi
EXTRA_DIST += \
doc/contributing.texi \
doc/emacs.texi \
doc/fdl-1.3.texi \
doc/images/bootstrap-graph.dot \

216
doc/contributing.texi Normal file
View File

@ -0,0 +1,216 @@
@node Contributing
@chapter Contributing
This project is a cooperative effort, and we need your help to make it
grow! Please get in touch with us on @email{guix-devel@@gnu.org} and
@code{#guix} on the Freenode IRC network. We welcome ideas, bug
reports, patches, and anything that may be helpful to the project. We
particularly welcome help on packaging (@pxref{Packaging Guidelines}).
@menu
* Building from Git:: The latest and greatest.
* Running Guix Before It Is Installed:: Hacker tricks.
* The Perfect Setup:: The right tools.
* Coding Style:: Hygiene of the contributor.
* Submitting Patches:: Share your work.
@end menu
@node Building from Git
@section Building from Git
If you want to hack Guix itself, it is recommended to use the latest
version from the Git repository. When building Guix from a checkout,
the following packages are required in addition to those mentioned in
the installation instructions (@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://www.graphviz.org/, Graphviz};
@item @url{http://www.gnu.org/software/help2man/, GNU Help2man (optional)}.
@end itemize
Run @command{./bootstrap} to download the Nix daemon source code and to
generate the build system infrastructure using autoconf. It reports an
error if an inappropriate version of the above packages is being used.
@noindent
If you get an error like this one:
@example
configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
@end example
it probably means that Autoconf couldnt find @file{pkg.m4}, which is
provided by @command{pkg-config}. Make sure that @file{pkg.m4} is
available. For instance, if you installed Automake in
@file{/usr/local}, it wouldnt look for @file{.m4} files in
@file{/usr/share}. So you have to invoke the following command in that
case
@example
export ACLOCAL_PATH=/usr/share/aclocal
@end example
See @pxref{Macro Search Path,,, automake, The GNU Automake Manual} for
more information.
Then, run @command{./configure} as usual.
Finally, you have to invoke @code{make check} to run tests. If anything
fails, take a look at installation instructions (@pxref{Installation})
or send a message to the @email{guix-devel@@gnu.org, mailing list}.
@node Running Guix Before It Is Installed
@section Running Guix Before It Is Installed
In order to keep a sane working environment, you will find it useful to
test the changes made in your local source tree checkout without
actually installing them. So that you can distinguish between your
``end-user'' hat and your ``motley'' costume.
To that end, all the command-line tools can be used even if you have not
run @code{make install}. To do that, prefix each command with
@command{./pre-inst-env} (the @file{pre-inst-env} script lives in the
top build tree of Guix), as in:
@example
$ sudo ./pre-inst-env guix-daemon --build-users-group=guixbuild
$ ./pre-inst-env guix build hello
@end example
@noindent
Similarly, for a Guile session using the Guix modules:
@example
$ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
@end example
The @command{pre-inst-env} script sets up all the environment variables
necessary to support this, including @env{PATH} and @env{GUILE_LOAD_PATH}.
@node The Perfect Setup
@section The Perfect Setup
The Perfect Setup to hack on Guix is basically the perfect setup used
for Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference
Manual}). First, you need more than an editor, you need
@url{http://www.gnu.org/software/emacs, Emacs}, empowered by the
wonderful @url{http://nongnu.org/geiser/, Geiser}.
Geiser allows for interactive and incremental development from within
Emacs: code compilation and evaluation from within buffers, access to
on-line documentation (docstrings), context-sensitive completion,
@kbd{M-.} to jump to an object definition, a REPL to try out your code,
and more (@pxref{Introduction,,, geiser, Geiser User Manual}). For
convenient Guix development, make sure to augment Guiles load path so
that it finds source files from your checkout:
@lisp
;; @r{Assuming the Guix checkout is in ~/src/guix.}
(add-to-list 'geiser-guile-load-path "~/src/guix")
@end lisp
To actually edit the code, Emacs already has a neat Scheme mode. But in
addition to that, you must not miss
@url{http://www.emacswiki.org/emacs/ParEdit, Paredit}. It provides
facilities to directly operate on the syntax tree, such as raising an
s-expression or wrapping it, swallowing or rejecting the following
s-expression, etc.
@node Coding Style
@section Coding Style
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 Guiles @code{(ice-9 match)} module,
especially when matching lists.
@node Formatting Code
@subsection Formatting Code
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 Guiles 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. If you do
not use Emacs, please make sure to let your editor know the rules.
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 Submitting Patches
@section Submitting Patches
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-devel@@gnu.org, mailing list}.
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 @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}). In addition, please make sure the package
builds on your platform, using @code{guix build @var{package}}. You may
also want to 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}).
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-mail}
command.

View File

@ -13,6 +13,8 @@
Copyright @copyright{} 2012, 2013, 2014, 2015 Ludovic Courtès@*
Copyright @copyright{} 2013, 2014 Andreas Enge@*
Copyright @copyright{} 2013 Nikita Karetnikov@*
Copyright @copyright{} 2015 Mathieu Lirzin@*
Copyright @copyright{} 2014 Pierre-Antoine Rault@*
Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer
Permission is granted to copy, distribute and/or modify this document
@ -88,7 +90,6 @@ Installation
* Running the Test Suite:: Testing Guix.
* Setting Up the Daemon:: Preparing the build daemon's environment.
* Invoking guix-daemon:: Running the build daemon.
* Running Guix Before It Is Installed:: Hacker tricks.
Setting Up the Daemon
@ -177,6 +178,21 @@ Packaging Guidelines
* Perl Modules:: Little pearls.
* Fonts:: Fond of fonts.
Contributing
* Building from Git:: The latest and greatest.
* Running Guix Before It Is Installed:: Hacker tricks.
* The Perfect Setup:: The right tools.
* Coding Style:: Hygiene of the contributor.
* Submitting Patches:: Share your work.
Coding Style
* 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 detailmenu
@end menu
@ -253,7 +269,6 @@ instead, you want to install the complete GNU operating system,
* Running the Test Suite:: Testing Guix.
* Setting Up the Daemon:: Preparing the build daemon's environment.
* Invoking guix-daemon:: Running the build daemon.
* Running Guix Before It Is Installed:: Hacker tricks.
@end menu
@node Binary Installation
@ -847,44 +862,6 @@ useful in exceptional circumstances, such as if you need to run several
daemons on the same machine.
@end table
@node Running Guix Before It Is Installed
@section Running Guix Before It Is Installed
If you are hacking Guix itself---which is a good idea!---you will find
it useful to test the changes made in your local source tree checkout
without actually installing them.
To that end, all the command-line tools can be used even if you have not
run @command{make install}. To do that, prefix each command with
@command{./pre-inst-env} (the @file{pre-inst-env} script lives in the
top build tree of Guix), as in:
@example
$ sudo ./pre-inst-env guix-daemon --build-users-group=guixbuild
$ ./pre-inst-env guix build hello
@end example
@noindent
Similarly, for a Guile session using the Guix modules:
@example
$ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
@end example
The @command{pre-inst-env} script sets up all the environment variables
necessary to support this, including @code{PATH} and
@code{GUILE_LOAD_PATH}.
If you are hacking Guix from Emacs using the wonderful Geiser
(@pxref{Introduction,,, geiser, Geiser User Manual}), make sure to
augment Guile's load path so that it finds source files from your
checkout:
@lisp
;; Assuming the Guix checkout is in ~/src/guix.
(add-to-list 'geiser-guile-load-path "~/src/guix")
@end lisp
@c *********************************************************************
@node Package Management
@ -6788,22 +6765,8 @@ Second, some of the required packages could fail to build for that
platform. Lastly, the generated binaries could be broken for some
reason.
@c *********************************************************************
@node Contributing
@chapter Contributing
This project is a cooperative effort, and we need your help to make it
grow! Please get in touch with us on @email{guix-devel@@gnu.org} and
@code{#guix} on the Freenode IRC network. We welcome ideas, bug
reports, patches, and anything that may be helpful to the project. We
particularly welcome help on packaging (@pxref{Packaging Guidelines}).
Please see the
@url{http://git.savannah.gnu.org/cgit/guix.git/tree/HACKING,
@file{HACKING} file} that comes with the Guix source code for practical
details about contributions.
@include contributing.texi
@c *********************************************************************
@node Acknowledgments