From mboxrd@z Thu Jan 1 00:00:00 1970 From: Ricardo Wurmus Subject: Re: Blog: Guix packaging tutorial Date: Sat, 29 Sep 2018 23:18:38 +0200 Message-ID: <87zhw02ea9.fsf@mdc-berlin.de> References: <87in397jsd.fsf@ambrevar.xyz> <20180913191151.GA1865@jurong> <87woro5ocf.fsf@ambrevar.xyz> <20180914113302.elqrk3tvdkln2cde@thebird.nl> <87o9cmj0fc.fsf@ambrevar.xyz> <87mus6iypf.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]:46585) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g6MdV-0002Eu-3u for guix-devel@gnu.org; Sat, 29 Sep 2018 17:18:50 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1g6MdU-00057m-91 for guix-devel@gnu.org; Sat, 29 Sep 2018 17:18:49 -0400 In-Reply-To: <87mus6iypf.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, thank you for writing this draft! This is a good start. Below are some comments about the beginning and some general thoughts about the idea of a tutorial. > I'm not satisfied with the advanced example: I took ~mg~ because it has a= lot of > typical customization (snippets, inputs, arguments) but it does not have > - in-input sources > - %build-inputs > - propagated-inputs > > I've made up a "my-mg" package but it relies on made-up inputs, so it won= 't > build. > Better suggestions anyone? I wonder if a complicated example like that really has a place in a tutorial. To me it seems a bit scary. I image people who are used to Conda to browse the tutorial and recoil in horror at seeing a complicated example with all sorts of customizations. Here some more comments: > Want to rebuild everything from source for a specific > architecture? Pass the ~#:system "YOUR-ARCH"~ argument to the list of > packages. People would rather use the =E2=80=9C--system=E2=80=9D option on the comman= d line instead of overwriting the arguments field, I think, so maybe that=E2=80=99= s not a good example. > =3DGNU hello=3D is a dummy project that serves as an idiomatic example for > packaging. If uses the GNU build chain (~./configure && make && make ins= tall~). s/If uses/It uses/ I would also replace =E2=80=9Cbuild chain=E2=80=9D with =E2=80=9Cbuild syst= em=E2=80=9D. > - source :: The ~origin~ record gather all the information required for a > source. Among which: How about: =E2=80=9CThis field contains a description of the source code or= igin. The ~origin~ record contains these fields:=E2=80=9D ? > abstracts away the famous ~./configure && make && make > install~ shell invocations: If the package can be built just > those commands, then Guix can often handle the complete > packaging process automatically. [=E2=80=A6] =E2=80=9Cbe built [+with] just those commands=E2=80=9D. What do you mean by =E2=80=9Cpackaging process=E2=80=9D? What does Guix = =E2=80=9Chandle=E2=80=9D here? I think it is less confusing to remove the sentence after the colon. > - synopsis :: It should be a concise and explicit summary of what the pac= kage > does. Many projects homepage already provide a synopsis, i= t's > fine to re-use it. I=E2=80=99d remove =E2=80=9Cand explicit=E2=80=9D. I=E2=80=99d also remove= the =E2=80=9CMany projects homepage..=E2=80=9D sentence as we often tweak synopses to remove advertisi= ng statements or to turn funny taglines into more informative, descriptive statements. You could also say =E2=80=9CFor many packages a tagline from t= he project=E2=80=99s home page can be used as the synopsis.=E2=80=9D > dummy "my-hello", a copycat of the above declaration. s/copycat/copy/ =E2=80=9Ccopycat=E2=80=9D is an imitator, not an imitation. > Indeed, Guix refuses to build anything if the source fails to verify > the checksum. It isn=E2=80=99t clear here who verifies what. The checksum and the source= are both passive in this situation, but the sentence makes it seem like the source is active. How about =E2=80=9Cif the given checksum does not match = the computed checksum of the source code=E2=80=9D? > To compute the correct checksum of the package declaration, we need to do= wnload the > source, compute the sha256 checksum and convert it to base32. To avoid the duplication of =E2=80=9Ccompute=E2=80=9D let=E2=80=99s replace= the first instance with =E2=80=9Cobtain=E2=80=9D. > Thankfully Guix can automate this task for us, all we need is to > provide the URI: There should be a comma after the first word; I=E2=80=99d replace the comma before =E2=80=9Call=E2=80=9D with a semicolon. > update you =3Dmy-hello=3D declaration accordingly. s/you/your/ > your desire to write more and more complex packages will grow s/will grow/grows/ > returns an anonymous function, which can in turn be called over an argume= nt: Maybe better: =E2=80=9Ccan in turn be applied to an argument:=E2=80=9D > Thus it enables us with fine-grained control over what is evaluated and w= hat is not. s/enables/provides/ FWIW, I think that maybe we should avoid quasi-quotation in the tutorial, or at least at this point. It could be a little overwhelming to be introduced to so many new concepts at once before seeing how they might be useful. Maybe this could be interleaved and motivated by packaging features. For example, at the very beginning we define a package and then evaluate it at the end so that we can use it with =E2=80=9Cguix package -f=E2=80=9D.= Maybe it would be better to avoid defining things and using the plain =E2=80=9Cpacka= ge=E2=80=9D form. Definitions could then be introduced later. What do you think? (I need to go now, but if you want I can comment on the next sections tomorrow.) -- Ricardo