[patch] - Packaging guideline documentation update

[patch] - Packaging guideline documentation update

[Pierre-Antoine Rault]

[-- Attachment #1: Type: text/plain, Size: 626 bytes --]

Hello guix,

Attached is a patch with basic explaination most of you know by heart, 
but that may not be obvious for newbies (like me). The details provided 
to the doc and hacking file both cover packaging and how to avoid the 
main pitfalls I've encountered myself recently. Most of them are based 
on advice from Dave, Mark_weaver (on #guix), these slides: 
http://www.gnu.org/software/guix/guix-ghm-andreas-20130823.pdf and these 
commands
http://lists.gnu.org/archive/html/guix-devel/2013-12/msg00079.html

What do you think ? Are there things to add ? (of course there are !)

First patch here ; any advice ?

- rigelk


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-Updated-packaging-guidelines.patch --]
[-- Type: text/x-patch; name="0001-doc-Updated-packaging-guidelines.patch", Size: 9295 bytes --]

From 8138e894da83d0ad3616df049992538fd0b3ec6f Mon Sep 17 00:00:00 2001
From: Pierre-Antoine Rault <par@rigelk.eu>
Date: Sun, 9 Mar 2014 17:10:27 +0100
Subject: [PATCH] doc: Updated packaging guidelines.

* ./HACKING (Submitting Patches): detailed git commands for
  'git format-patch' and 'git send-mail'.
  (Packaging 101) New section detailing packaging contribution
  from a newbie point of view, avoiding & explaining common
  pitfalls.
* doc/guix.texi (Packaging Guidelines): Shortly explained dev
  procedure ; explaining deprecated #:export and new public-define ;
  redirection to HACKING file added.
  (Contributing) Added reference to #guix channel on freenode.
---
 HACKING       | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++----
 doc/guix.texi | 34 ++++++++++++++++---------
 2 files changed, 97 insertions(+), 17 deletions(-)

diff --git a/HACKING b/HACKING
index 0dc2908..1fb65f8 100644
--- a/HACKING
+++ b/HACKING
@@ -4,6 +4,7 @@
 
 Copyright © 2012, 2013 Ludovic Courtès <ludo@gnu.org>
 Copyright © 2013 Nikita Karetnikov <nikita@karetnikov.org>
+Copyright © 2014 Pierre-Antoine Rault <par@rigelk.eu>
 
   Copying and distribution of this file, with or without modification,
   are permitted in any medium without royalty provided the copyright
@@ -12,8 +13,9 @@ Copyright © 2013 Nikita Karetnikov <nikita@karetnikov.org>
 
 * Building from Git
 
-When building Guix from a checkout, the following packages are required in
-addition to those mentioned in the installation instructions:
+Development should be done through git. When building Guix from a git
+checkout, the following packages are required in addition to those
+mentioned in the installation instructions:
 
   - [[http://www.gnu.org/software/autoconf/][GNU Autoconf]]
   - [[http://www.gnu.org/software/automake/][GNU Automake]]
@@ -51,7 +53,11 @@ take a look at “info '(guix) Installation'” or send a message to
 
 * Running Guix before it is installed
 
-Command-line tools can be used even if you have not run "make install".
+Command-line tools can be used even if you have not run "make
+install". Actually, some developpers prefer not to run make install and
+use a script in their /usr/local/bin/ named 'guix' to call the following
+substitute to 'guix'. 
+
 To do that, prefix each command with ‘./pre-inst-env’, as in:
 
   ./pre-inst-env guix build --help
@@ -85,10 +91,74 @@ wrapping it, swallowing or rejecting the following s-expression, etc.
 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]].
+guix-devel@gnu.org (see below). Remember to please write commit logs in
+the [[http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs][GNU ChangeLog format]].
+
+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.
+
+Depending on your distribution, 'git send-mail' might be part of another
+package (git-email in Debian, for instance). It is an extremely nice
+tool. You can generate a patch series by doing:
+
+$ git format-patch <commit>
+
+This will generate a bunch of files called 0001-commit-title, 
+0002-commit-title and so on. Then just do:
+
+$ git send-email --to guix-devel@gnu.org --in-reply-to <message-id of 
+your first message> 000*.patch
+
+And we'll get all your patches in a nice thread :)
 
 As you become a regular contributor, you may find it convenient to have write
-access to the repository (see below.)
+access to the repository (see below, Commit Access.)
+
+* Packaging 101
+
+To get started adding package to the guix tree (gnu/packages/), copy
+a *.scm in the tree or create a new one. It should contain at least three
+elements:
+
+  - A licence (copy from other .scm, and put your name)
+  - A define-module form (which imports (and may export) modules)
+  - A define-public form containing the package description (one may use
+    define only, but then has to add an #:export (package_name) to the
+    define form - deprecated)
+
+Modify the define-public form according to the package: copyright, module
+name and name (both lower case), version, uri, description (add two spaces at the end of line),
+license (see guix/licenses.scm), synopsis (shouldn't repeat the package
+name), home page.
+
+Use 'guix download <uri>' to download the package, and print its hash in
+base32. Modify the hash in the sha256 form accordingly. Note that <uri>
+can be a direct http:// adress or a mirror://xxx/... (where xxx is either
+gnu, sourceforge, savannah, cpan, kernel.org, gnome, apache, xorg, or
+imagemagick). Check with gpg or hash that the downloaded package is the
+good one ;)
+
+Your package may have dependencies. Sort them between those needed to
+only compile (that is, only to build the program), and those needed by
+the program itself (that is, when the end user runs it). The former are
+called 'native-inputs', the latter 'inputs'. When building a binary, both
+will be needed on the system, but it avoids a end user to have to download
+native-inputs if he downloads a binary of the package.
+
+Once your file is done, double check its syntax. If it has errors
+(i.e: unclosed parentheses, forgotten export/defin-public method), it
+won't show with the command 'guix package -A' (add name to just output
+your package. If it shows, well done, you may proceed to the next step:
+building your package.
+
+Don't forget to use 'guix build -c', as -c will make use of all your cores.
+
+If the build shows errors, try passing configure flags and check inputs. Use the
+argument -K to keep /tmp folder even after a build fail, as it may
+contain info on how to solve the issue.
+
+Your package has built successfuly ? Consider talking about it with other
+guix devs and submitting a patch. (see previous section)
 
 * Coding Style
 
diff --git a/doc/guix.texi b/doc/guix.texi
index baa1990..68a80c7 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -2228,9 +2228,10 @@ creating packages.  For more information on package definitions,
 @ref{Defining Packages}.
 
 Once a package definition is in place, stored in a file in the Guix
-source tree, it can be tested using the @command{guix build} command
-(@pxref{Invoking guix build}).  For example, assuming the new package is
-called @code{gnew}, you may run this command from the Guix build tree:
+source tree (gnu/packages/) as a *.scm file, it can be tested using the
+@command{guix build} command (@pxref{Invoking guix build}). For
+example, assuming the new package is called @code{gnew}, you may run
+this command from the Guix build tree:
 
 @example
 ./pre-inst-env guix build gnew --keep-failed
@@ -2239,12 +2240,21 @@ called @code{gnew}, you may run this command from the Guix build tree:
 Using @code{--keep-failed} makes it easier to debug build failures since
 it provides access to the failed build tree.
 
+If the package is unknown to the guix command, it means you either made a
+syntax error (watch your parentheses, compare with other .scm in the
+guix tree), or forgot to use the @code{define-public} directive instead
+of @code{define} for your main package.
+
 Once your package builds correctly, please send us a patch
-(@pxref{Contributing}).  Well, if you need help, we will be happy to
-help you too.  Once the patch is committed in the Guix repository, the
-new package automatically gets built on the supported platforms by
-@url{http://hydra.gnu.org/gnu/master, our continuous integration
-system}.
+(@pxref{Contributing}). Remember you should use @code{git} ; once the working
+.scm file is commited, run @code{git format-patch} to prepare a patch,
+and @code{git send-email} (see the HACKING file, Packaging 101 for more
+information).
+
+Well, if you need help, we will be happy to help you too. Once the patch
+is committed in the Guix repository, the new package automatically gets
+built on the supported platforms by
+@url{http://hydra.gnu.org/gnu/master, our continuous integration system}.
 
 @cindex substituter
 Users can obtain the new package definition simply by running
@@ -2753,10 +2763,10 @@ deco,,, dmd, GNU dmd Manual}).
 @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}.  We
-welcome ideas, bug reports, patches, and anything that may be helpful to
-the project.  We particularly welcome help on packaging
-(@pxref{Packaging Guidelines}).
+grow!  Please get in touch with us on @email{guix-devel@@gnu.org} and
+#guix on irc.freenode.net.  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,
-- 
1.9.0

Re: [patch] - Packaging guideline documentation update

[Ludovic Courtès]

Hi,

Pierre-Antoine Rault <par@rigelk.eu> skribis:

> Attached is a patch with basic explaination most of you know by heart,
> but that may not be obvious for newbies (like me). The details
> provided to the doc and hacking file both cover packaging and how to
> avoid the main pitfalls I've encountered myself recently. Most of them
> are based on advice from Dave, Mark_weaver (on #guix), these slides:
> http://www.gnu.org/software/guix/guix-ghm-andreas-20130823.pdf and
> these commands
> http://lists.gnu.org/archive/html/guix-devel/2013-12/msg00079.html
>
> What do you think ? Are there things to add ? (of course there are !)

Thanks for the patch!

I’ve applied a stripped-down version of the patch: I ended up removing
“Packaging 101” because it was redundant with the “Packaging Guidelines”
section of the manual, so I moved the missing bits in that section (info
"(guix) Packaging Guidelines").  If you see anything still missing
there, please do let me know; this should be the canonical place for
such introductory material.

I also removed details about how ‘git format-patch’ and co. work,
because these commands already have their own manual.

I realize the manual can be improved when it comes to introductory
material.  If you think of other improvements, please let’s make them in
the “Packaging Guidelines” and “Defining Packages” sections.

Thanks,
Ludo’.

Re: [patch] - Packaging guideline documentation update

[Pierre-Antoine Rault]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi,

On 10/03/2014 21:56, Ludovic Courtès wrote:
> I’ve applied a stripped-down version of the patch: I ended up 
> removing “Packaging 101” because it was redundant with the 
> “Packaging Guidelines” section of the manual, so I moved the 
> missing bits in that section (info "(guix) Packaging Guidelines"). 
> I also removed details about how ‘git format-patch’ and co. work, 
> because these commands already have their own manual.

I admit it was overkill :)

> I realize the manual can be improved when it comes to introductory 
> material.

I would think of a (not so) short explaination of the guix tree as
seen in the GNUnet manuel, for instance. What do you think ?

- - rigelk
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBAgAGBQJTHkaAAAoJEHfJ0QE7gLd6XSsIAIX5kQtsZmdJ6P8kSRo+0Euo
YolTVuBs1BGbEq+sIx1nBPpzt1CYCuLkO/R/FzbKNpy2RmHwR/M2K1OEcr71hH2B
DFIW65WEkTAZeouDRmU06leg+9I3EkQpJ6rqRmIyts9drUzRQoJdzkn0uZAROvSN
hqBofvBQGvurvbBg+bjIW9UqObowsa9Bhg8lH0bLWpqA2CIzw8U3uWPTphHc5azH
ML7lNYtdr7J95yMXsl/PN2DpiWiO8pG+uXPmBUanCgmipcAW5tU1VmC9Jp+LJBPU
h1ke6Ym0wFsyFwuqzqC3INcOkwvGeM9yO7D/XNHVlQusY+FyRIkbEGeHyVkQ3Eg=
=tuXM
-----END PGP SIGNATURE-----

Re: [patch] - Packaging guideline documentation update

[Ludovic Courtès]

Pierre-Antoine Rault <par@rigelk.eu> skribis:

> On 10/03/2014 21:56, Ludovic Courtès wrote:
>> I’ve applied a stripped-down version of the patch: I ended up
>> removing “Packaging 101” because it was redundant with the
>> “Packaging Guidelines” section of the manual, so I moved the
>> missing bits in that section (info "(guix) Packaging Guidelines").
>> I also removed details about how ‘git format-patch’ and co. work,
>> because these commands already have their own manual.
>
> I admit it was overkill :)
>
>> I realize the manual can be improved when it comes to introductory
>> material.
>
> I would think of a (not so) short explaination of the guix tree as
> seen in the GNUnet manuel, for instance. What do you think ?

Hmm, perhaps.  Actually, part of the module name space is described here
in there.  For instance (gnu packages ...) is described under “Package
Modules”, (guix build ...) is described under “Derivations”, etc.
Perhaps a new section with cross-refs to these would help?

Ludo’.

Re: [patch] - Packaging guideline documentation update

[Pierre-Antoine Rault]

Cross-refs and a small glossary would help a lot to start with Guix. However, I was thinking about an explanation of folders, sub folders and main files as seen in the GNUnet manual [1].

[1] https://gnunet.org/book/export/html/37

Of course, these are just ideas to help brainstrom :)

- rigelk

ludo@gnu.org a écrit :

>Pierre-Antoine Rault <par@rigelk.eu> skribis:
>
>> On 10/03/2014 21:56, Ludovic Courtès wrote:
>>> I’ve applied a stripped-down version of the patch: I ended up
>>> removing “Packaging 101” because it was redundant with the
>>> “Packaging Guidelines” section of the manual, so I moved the
>>> missing bits in that section (info "(guix) Packaging Guidelines").
>>> I also removed details about how ‘git format-patch’ and co. work,
>>> because these commands already have their own manual.
>>
>> I admit it was overkill :)
>>
>>> I realize the manual can be improved when it comes to introductory
>>> material.
>>
>> I would think of a (not so) short explaination of the guix tree as
>> seen in the GNUnet manuel, for instance. What do you think ?
>
>Hmm, perhaps.  Actually, part of the module name space is described here
>in there.  For instance (gnu packages ...) is described under “Package
>Modules”, (guix build ...) is described under “Derivations”, etc.
>Perhaps a new section with cross-refs to these would help?
>
>Ludo’.

Re: [patch] - Packaging guideline documentation update

[Ludovic Courtès]

Pierre-Antoine Rault <par@rigelk.eu> skribis:

> Cross-refs and a small glossary would help a lot to start with Guix. However, I was thinking about an explanation of folders, sub folders and main files as seen in the GNUnet manual [1].
>
> [1] https://gnunet.org/book/export/html/37

Sure.  Again part of the information is already in the manual, but it’s
scattered in different places.  So an improvement would be to have an
overview section that would reference to the relevant sections.

Ludo’.