>From 8138e894da83d0ad3616df049992538fd0b3ec6f Mon Sep 17 00:00:00 2001 From: Pierre-Antoine Rault 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 Copyright © 2013 Nikita Karetnikov +Copyright © 2014 Pierre-Antoine Rault 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 * 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 address@hidden Please write commit logs in the [[http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs][GNU ChangeLog format]]. address@hidden (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 + +This will generate a bunch of files called 0001-commit-title, +0002-commit-title and so on. Then just do: + +$ git send-email --to address@hidden --in-reply-to 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 ' to download the package, and print its hash in +base32. Modify the hash in the sha256 form accordingly. Note that +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 address@hidden 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 address@hidden://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 address@hidden://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