From mboxrd@z Thu Jan 1 00:00:00 1970 From: Ricardo Wurmus Subject: Re: Blog: Guix packaging tutorial Date: Mon, 8 Oct 2018 17:18:59 +0200 Message-ID: <87o9c4qxek.fsf@elephly.net> References: <87in397jsd.fsf@ambrevar.xyz> <20180913191151.GA1865@jurong> <87woro5ocf.fsf@ambrevar.xyz> <20180914113302.elqrk3tvdkln2cde@thebird.nl> <87o9cmj0fc.fsf@ambrevar.xyz> <87mus6iypf.fsf@ambrevar.xyz> <87zhw02ea9.fsf@mdc-berlin.de> <87o9cex112.fsf@ambrevar.xyz> <87efdau5x2.fsf@gnu.org> <87murywuvn.fsf@ambrevar.xyz> <87lg7go8cv.fsf@gnu.org> <87va6kuyk4.fsf@ambrevar.xyz> <87sh1ot9m5.fsf@elephly.net> <87bm8bv4ao.fsf@ambrevar.xyz> <874le2j3ox.fsf@ambrevar.xyz> Mime-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:54599) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g9XJo-0001Dx-BI for guix-devel@gnu.org; Mon, 08 Oct 2018 11:19:39 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1g9XJj-0005x2-66 for guix-devel@gnu.org; Mon, 08 Oct 2018 11:19:36 -0400 In-Reply-To: <874le2j3ox.fsf@ambrevar.xyz> 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" To: Pierre Neidhardt Cc: guix-devel , guix-blog@gnu.org Hi Pierre, > Find the last revision attached. I've taken all comments into > consideration and I'm quite happy with the result. I like it! Thanks for your patience. Here are some more comments: * In the section =E2=80=9CA "Hello World" package=E2=80=9D you use the word =E2=80=9Ccommandline=E2=80=9D, but it should be =E2=80=9Ccommand line=E2= =80=9D. (Same in the Scheme tutorial and other places throughout.) * The sentence: =E2=80=9CAs with the ritualistic "Hello World" taught with = most programming language, [=E2=80=A6]=E2=80=9D should say =E2=80=9Cprogrammin= g languages=E2=80=9D. * I wonder if maybe we should avoid using =E2=80=9Cguix package=E2=80=9D fo= r the first example and use =E2=80=9Cguix build=E2=80=9D instead. The reason is that= =E2=80=9Cguix package=E2=80=9D might cause additional builds to be performed dependent = on the state of the user=E2=80=99s default profile (because of profile hooks= ). Using =E2=80=9Cguix build=E2=80=9D bypasses this issue completely. What = do you think? * Missing period after =E2=80=9C(or /s-expression/ in Lisp lingo)=E2=80=9D. * =E2=80=9CIt can be a literal[=E2=80=A6]=E2=80=9D =E2=80=93> =E2=80=9CAn e= xpression can be a literal[=E2=80=A6]=E2=80=9D, because in the previous sentence we used the plural =E2=80=9Cexpressions= =E2=80=9D. * =E2=80=9CEvery function returns the last evaluated expression as value.= =E2=80=9D =E2=80=93> =E2=80=9CEvery function returns the value of the last evaluated expressio= n.=E2=80=9D * =E2=80=9CUse ~let*~ to re-allows the initializers of later variables to r= efer to the earlier variables.=E2=80=9D =E2=80=93> =E2=80=9CUse ~let*~ to allo= w later variable declarations to refer to earlier definitions.=E2=80=9D * =E2=80=9CCreate a folder=E2=80=9D =E2=80=93> =E2=80=9CCreate a directory= =E2=80=9D; =E2=80=9Cfolder=E2=80=9D is a GUI metaphor, but that=E2=80=99s nitpicking to be fair. I prefer =E2=80=9Cdirectory=E2= =80=9D, but use =E2=80=9Cfolder=E2=80=9D if you find it better :) * =E2=80=9CNotice that we have wrapped the package into a ~define-public~ record=E2=80=9D =E2=80=93 I would not use the term =E2=80=9Crecord=E2=80= =9D here, because it could be confused with Scheme records. How about =E2=80=9CNote that we have assig= ned the package value to an exported variable name with ~define-public~.=E2= =80=9D You=E2=80=99re saying as much in the following sentence, but I think it w= ould be better to avoid the words =E2=80=9Cwarp=E2=80=9D and =E2=80=9Crecord= =E2=80=9D here. * =E2=80=9C$GUIX_CHECKOUT=E2=80=9D is not defined anywhere. You reference = it in the introduction before telling people to clone the git repository: =E2=80=9Clicense :: See =3D$GUIX_CHECKOUT/guix/licenses.scm=3D for a ful= l list.=E2=80=9D I think it would be best to remove any mention of this from the introduction. After telling the readers to =E2=80=9Cgit clone=E2=80=9D I= think the meaning of $GUIX_CHECKOUT would be obvious, but earlier it is not. * Why use =E2=80=9Cruby=E2=80=9D as an example after checking out? Should = this be mentioned e.g. =E2=80=9CSearch packages, such as Ruby:=E2=80=9D to show t= hat this is arbitrary? * =E2=80=9CLet's looks at another=E2=80=9D =E2=80=93> =E2=80=9CLet's look a= t another=E2=80=9D * This paragraph is a little difficult to understand for me: When downloaded to the store, the source should be different from version to version. Since Git repositories don't contain a specific version in their name, we've got to force the download folder using ~(file-name (git-file-name name version))~. How about this: To ensure that the source code from the git repository is stored in a unique directory with a readable name we use ~(file-name (git-file-name name version))~. * =E2=80=9CSnippets are quoted (i.e. non-evaluated) Scheme code that are a = mean of patching the source.=E2=80=9D =E2=80=93> =E2=80=9C=E2=80=A6a means of= patching=E2=80=A6=E2=80=9D * =E2=80=9Cnative-inputs :: Required for building but not runtime -- instal= ling a package through a substitute won't install these inputs.=E2=80=9D This is usually true, but the meaning of =E2=80=9Cnative-inputs=E2=80=9D = is primarily important for cross-building packages. A native input will be used on the build machine and should thus be available for the build machine=E2= =80=99s architecture, not for the target machine. Since Guix scans for references, packages that are only needed at build time will not be installed even when they are among the plain =E2=80=9Cinputs=E2=80=9D. L= ikewise, packages that are in the =E2=80=9Cnative-inputs=E2=80=9D may end up leavi= ng a reference behind, which will cause them to be downloaded. (This is often a bug, such as in the icedtea packages, which keep unwanted references.) Not sure if we should change this in the tutorial, because it=E2=80=99s a finer point. The distinction between inputs and propagated-inputs is more important and I think it=E2=80=99s done well in your draft. * =E2=80=9Cconcern to the package, no to the user=E2=80=9D =E2=80=93> =E2= =80=9C=E2=80=A6not to the user=E2=80=9D * =E2=80=9CThe end user can choose=E2=80=9D =E2=80=93> I=E2=80=99d prefer j= ust =E2=80=9Cuser=E2=80=9D instead of =E2=80=9Cend user=E2=80=9D. * =E2=80=9CIt's advised to separate outputs only when you've shown it worth= :=E2=80=9D =E2=80=93> =E2=80=9C=E2=80=A6it=E2=80=99s worth it:=E2=80=9D. * In the configure-flags example I would not use quasiquotation, so this: #:configure-flags `(,(string-append =E2=80=A6 would become this: #:configure-flags (list (string-append =E2=80=A6 * =E2=80=9COr from the REPL (assuming the Guix source is in your Guile load path):=E2=80=9D =E2=80=93> you could remove the assumption by adding an add-to-load-path expression to the example. * =E2=80=9Cconsult the associated functions=E2=80=9D =E2=80=93> nitpick: th= ese are =E2=80=9Cprocedures=E2=80=9D not =E2=80=9Cfunctions=E2=80=9D. * The segment starting with =E2=80=9CTo manipulate the phases,=E2=80=9D see= ms incomplete as it does not introduce the =E2=80=9Cmodify-phases=E2=80=9D macro itself. * =E2=80=9Cthis is needed to avoid clashes between, say, the =3Dzlib=3D var= iable from =3Dlicenses.scm=3D and the =3Dzlib=3D variable from =3Dcompression.s= cm=3D.=E2=80=9D =E2=80=94 I suggest adding parenthetical remarks after the modules to clarify that these are different types: =E2=80=9C(a license value)=E2=80=9D and = =E2=80=9C(a package value)=E2=80=9D. * =E2=80=9C=E2=80=A6process is very similar to the GNU build system but for= a few specialized arguments.=E2=80=9D =E2=80=93> Maybe replace =E2=80=9Cbut=E2= =80=9D with =E2=80=9Cexcept=E2=80=9D.e * =E2=80=9CFind more about build systems in=E2=80=A6=E2=80=9D =E2=80=93> Ma= ybe replace =E2=80=9CFind=E2=80=9D with =E2=80=9CLearn=E2=80=9D or =E2=80=9CFind out=E2=80=9D. * I don=E2=80=99t know if there should be a section =E2=80=9CCommon pitfall= s and best practices=E2=80=9D other than to point to the checklist in the manual. I= f the list in the manual misses one of the points I=E2=80=99d rather add them t= here and only link to the list. * The section on =E2=80=9CRecursive importers=E2=80=9D does not mention any= recursive importers :) How about using the CRAN importer here, which supports recursive importing with the =E2=80=9C-r=E2=80=9D option? * =E2=80=9CAll unspecified fields inherit from the parent package=E2=80=9D = =E2=80=93 I think =E2=80=9Care inherited from=E2=80=9D would be better. * =E2=80=9CSadly some applications can be tough to package=E2=80=9D =E2=80= =94 missing comma after =E2=80=9CSadly=E2=80=9D. * I find this sentence a bit confusing: =E2=80=9CThe GNU build system is the flagship of the high-level abstraction layers Guix makes possible to build.=E2=80=9D =E2=80=94 what does it mean to =E2=80=9Cbuild =E2=80=A6 = an abstraction layer=E2=80=9D? Finally, I think the conclusion is a bit anti-climatic :) I feel like it misses a sentence after presenting the outlook to the future; maybe an announcement of a follow-up blog post? Or encouragement to get started packaging today? I=E2=80=99m very happy to see this tutorial so close to being published! T= hanks again for your efforts! -- Ricardo