From mboxrd@z Thu Jan 1 00:00:00 1970 From: Pierre-Antoine Rault Subject: [patch] - Packaging guideline documentation update Date: Sun, 09 Mar 2014 17:46:27 +0100 Message-ID: <531C9AE3.8090402@rigelk.eu> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="------------030202070100050306090600" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:53031) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WMgrJ-0003Po-Om for guix-devel@gnu.org; Sun, 09 Mar 2014 12:45:59 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WMgr7-00064x-Ko for guix-devel@gnu.org; Sun, 09 Mar 2014 12:45:53 -0400 Received: from relay3-d.mail.gandi.net ([2001:4b98:c:538::195]:39269) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WMgr7-00063O-An for guix-devel@gnu.org; Sun, 09 Mar 2014 12:45:41 -0400 Received: from mfilter14-d.gandi.net (mfilter14-d.gandi.net [217.70.178.142]) by relay3-d.mail.gandi.net (Postfix) with ESMTP id 82A35A80B4 for ; Sun, 9 Mar 2014 17:45:36 +0100 (CET) Received: from relay3-d.mail.gandi.net ([217.70.183.195]) by mfilter14-d.gandi.net (mfilter14-d.gandi.net [10.0.15.180]) (amavisd-new, port 10024) with ESMTP id BFf3sqRdJoLR for ; Sun, 9 Mar 2014 17:45:34 +0100 (CET) Received: from [192.168.1.12] (ANantes-656-1-50-107.w90-59.abo.wanadoo.fr [90.59.65.107]) (Authenticated sender: par@rigelk.eu) by relay3-d.mail.gandi.net (Postfix) with ESMTPSA id 8F1E7A8075 for ; Sun, 9 Mar 2014 17:45:34 +0100 (CET) List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org To: guix-devel@gnu.org This is a multi-part message in MIME format. --------------030202070100050306090600 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit 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 --------------030202070100050306090600 Content-Type: text/x-patch; name="0001-doc-Updated-packaging-guidelines.patch" Content-Disposition: attachment; filename="0001-doc-Updated-packaging-guidelines.patch" Content-Transfer-Encoding: quoted-printable >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 @@ =20 Copyright =C2=A9 2012, 2013 Ludovic Court=C3=A8s Copyright =C2=A9 2013 Nikita Karetnikov +Copyright =C2=A9 2014 Pierre-Antoine Rault =20 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 =C2=A9 2013 Nikita Karetnikov =20 * Building from Git =20 -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: =20 - [[http://www.gnu.org/software/autoconf/][GNU Autoconf]] - [[http://www.gnu.org/software/automake/][GNU Automake]] @@ -51,7 +53,11 @@ take a look at =E2=80=9Cinfo '(guix) Installation'=E2=80= =9D or send a message to =20 * Running Guix before it is installed =20 -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'.=20 + To do that, prefix each command with =E2=80=98./pre-inst-env=E2=80=99, a= s in: =20 ./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. T= hus, access to the repository is not strictly necessary. We welcome contribu= tions in the form of patches as produced by =E2=80=98git format-patch=E2=80=99= sent to -guix-devel@gnu.org. Please write commit logs in the [[http://www.gnu.or= g/prep/standards/html_node/Change-Logs.html#Change-Logs][GNU ChangeLog fo= rmat]]. +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#Chang= e-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,=20 +0002-commit-title and so on. Then just do: + +$ git send-email --to guix-devel@gnu.org --in-reply-to 000*.patch + +And we'll get all your patches in a nice thread :) =20 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 thre= e +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, modul= e +name and name (both lower case), version, uri, description (add two spac= es 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 eithe= r +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, bot= h +will be needed on the system, but it avoids a end user to have to downlo= ad +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 cor= es. + +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 othe= r +guix devs and submitting a patch. (see previous section) =20 * Coding Style =20 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 packag= e definitions, @ref{Defining Packages}. =20 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: =20 @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. =20 +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 wo= rking +.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}= . =20 @cindex substituter Users can obtain the new package definition simply by running @@ -2753,10 +2763,10 @@ deco,,, dmd, GNU dmd Manual}). @chapter Contributing =20 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}). =20 Please see the @url{http://git.savannah.gnu.org/cgit/guix.git/tree/HACKING, --=20 1.9.0 --------------030202070100050306090600--