From mboxrd@z Thu Jan 1 00:00:00 1970 From: ludo@gnu.org (Ludovic =?utf-8?Q?Court=C3=A8s?=) Subject: Re: Newbie packagers Date: Thu, 21 Jul 2016 17:54:03 +0200 Message-ID: <87bn1rm1gk.fsf@gnu.org> References: Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:35802) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bQGIi-00026b-17 for help-guix@gnu.org; Thu, 21 Jul 2016 11:54:17 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bQGIf-0007ev-MD for help-guix@gnu.org; Thu, 21 Jul 2016 11:54:14 -0400 In-Reply-To: (Vincent Legoll's message of "Thu, 21 Jul 2016 15:21:10 +0200") List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org Sender: "Help-Guix" To: Vincent Legoll Cc: help-guix@gnu.org --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Hi Vincent, Vincent Legoll skribis: > I put this in a separate email, as it's becoming long... > > The packaging doc: > > https://www.gnu.org/software/guix/manual/guix.html#Defining-Packages > is good, but still not enough for beginners. > > Essentially it's missing what is hidden behind "Without being a Scheme ..= ." > > It wouldn't hurt to have the scheme non-obvious parts explained: > > - the comma operator > - the backquote operator > - the quote operator > - the arobase operator (is it for list unpacking ?) > - the percent operator > - the #: operator > - the different module import things (#:use-module vs (use-modules) vs ..= .) > > (Forgive my probably-not-appropriate terms.) > > No need to explain function calls, string quoting and simple stuff, thoug= h. > > I tried to find a good tutorial explaining all of those, but couldn't. I = found > snippets that helped me understand some of those, but they were scattered, > and it's still blurry. > > Specific explanations will be more useful that a general scheme tutorial,= the > hello.scm is good as an example : > > (inputs `(("gawk" ,gawk))) > > here we use the backquote because ... > the comma is there for ... > > (arguments `(#:configure-flags '("--enable-silent-rules"))) > > here the #: means ... > we use the simple quote because ... I would propose the patch below as a start. While it does not give detailed explanations, it provides terminology and pointers, in particular to this section of the Guile manual: https://www.gnu.org/software/guile/manual/html_node/Expression-Syntax.html Unfortunately, this section of Guile=E2=80=99s manual is a reference and it lacks examples and a good overview. I think we should fix it on Guile=E2= =80=99s side instead of palliating this deficiency in Guix=E2=80=99s manual. If nobody beats me at it, I can try and improve this is in Guile=E2=80=99s manual afterwards. What do you think? Thanks, Ludo=E2=80=99. --=-=-= Content-Type: text/x-patch Content-Disposition: inline diff --git a/doc/guix.texi b/doc/guix.texi index e7b233d..8d332f6 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -2452,12 +2452,35 @@ The @code{arguments} field specifies options for the build system @var{gnu-build-system} as a request run @file{configure} with the @code{--enable-silent-rules} flag. +@cindex quote +@cindex quoting +@cindex backquote (quasiquote) +What about these backquote (@code{`}) and quote (@code{'}) characters? +They are Scheme syntax to introduce a literal data structure; @code{'} +is synonymous with @code{quote}, and @code{`} is synonymous with +@code{quasiquote}. @xref{Expression Syntax, quoting,, guile, GNU Guile +Reference Manual}, for details. Here the value of the @code{arguments} +field is a list of arguments passed to the build system. + +The hash-colon (@code{#:}) sequence defines a Scheme @dfn{keyword} +(@pxref{Keywords,,, guile, GNU Guile Reference Manual}), and +@code{#:configure-flags} is a keyword used to pass a keyword argument +to the build system (@pxref{Coding With Keywords,,, guile, GNU Guile +Reference Manual}). + @item The @code{inputs} field specifies inputs to the build process---i.e., build-time or run-time dependencies of the package. Here, we define an input called @code{"gawk"} whose value is that of the @var{gawk} variable; @var{gawk} is itself bound to a @code{} object. +@cindex comma (unquote) +Again, @code{`} (@code{quasiquote}) allows us to introduce a literal +list in the @code{inputs} field, while @code{,} (a comma, synonymous +with @code{unquote}) allows us to insert a value in the list +(@pxref{Expression Syntax, unquote,, guile, GNU Guile Reference +Manual}). + Note that GCC, Coreutils, Bash, and other essential tools do not need to be specified as inputs here. Instead, @var{gnu-build-system} takes care of ensuring that they are present (@pxref{Build Systems}). --=-=-=--