From mboxrd@z Thu Jan 1 00:00:00 1970 From: =?utf-8?Q?Ludovic_Court=C3=A8s?= Subject: Re: guile scheme tutorial Date: Wed, 08 May 2019 14:46:09 +0200 Message-ID: <87ftppxgfi.fsf@gnu.org> References: <60f73aa7-e1ae-2c5d-cf47-c179a54a65ce@s.rendaw.me> <87pnoy7g1c.fsf@gnu.org> <3b95f670-336a-c7e9-b2e0-768e2bb99342@s.rendaw.me> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([209.51.188.92]:54742) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hOLxg-0000TZ-5z for help-guix@gnu.org; Wed, 08 May 2019 08:46:17 -0400 In-Reply-To: <3b95f670-336a-c7e9-b2e0-768e2bb99342@s.rendaw.me> (rendaw's message of "Tue, 7 May 2019 13:35:19 +0900") 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: rendaw <7e9wc56emjakcm@s.rendaw.me> Cc: help-guix@gnu.org Hello! rendaw <7e9wc56emjakcm@s.rendaw.me> skribis: > The areas that were important for me but weren't well documented were: Thanks for explaining! That=E2=80=99s a lot of things to digest. :-) I=E2=80=99m not entirely sure I agree with or understand everything you men= tion, I=E2=80=99ll comment on some of these below. However, I think you should r= eally propose incremental improvements to the manual in these areas; it=E2=80=99l= l be easier to discuss specific sections or paragraphs. > 1. Concepts > > * What is functional package management?=C2=A0 What is garbage collection= ?=C2=A0 > How do these work? =E2=80=9C(guix) Managing Software the Guix Way=E2=80=9D has a paragraph abo= ut functional package management, but that=E2=80=99s (purposefully) the only place where = FPM is discussed. > What is a package?=C2=A0 How does Guix determine what makes a package > unique?=C2=A0 What's a derivation, and what's the relationship between > derivations and packages?=C2=A0 The best I could find is that a derivation > communicates an action to the store, but that uses vocabulary in ways > that 99% of readers won't be familiar with ("communicate", "action", > isn't the "store" a directory?) and is so abstract that it won't help > people make choices dependent on that.=C2=A0 What's a tangible example of= a > derivation?=C2=A0 Where and why would someone use a derivation directly? =E2=80=9C(guix) Defining Packages=E2=80=9D explains: Behind the scenes, a derivation corresponding to the =E2=80=98=E2=80=99 object is first computed by the =E2=80=98package-derivation=E2=80=99 proc= edure. That derivation is stored in a =E2=80=98.drv=E2=80=99 file under =E2=80=98/gnu= /store=E2=80=99. The build actions it prescribes may then be realized by using the =E2=80=98build-derivations=E2=80=99 procedure (*note The Store::). =E2=80=A6 with cross-references. > The only gc documentation says that anything reachable from a root won't > be deleted, but doesn't explain what a root is, how they're created, how > they're identified, how they're removed, etc. =E2=80=9C(guix) Invoking guix gc=E2=80=9D has a paragraph that I think expl= ains what a GC root is: The garbage collector has a set of known =E2=80=9Croots=E2=80=9D: any = file under =E2=80=98/gnu/store=E2=80=99 reachable from a root is considered =E2=80= =9Clive=E2=80=9D and cannot be deleted; any other file is considered =E2=80=9Cdead=E2=80=9D and may be d= eleted. The set of garbage collector roots (=E2=80=9CGC roots=E2=80=9D for short) inc= ludes default user profiles; by default, the symlinks under =E2=80=98/var/guix/gcroots= =E2=80=99 represent these GC roots. New GC roots can be added with =E2=80=98guix b= uild --root=E2=80=99, for example (*note Invoking guix build::). The =E2=80= =98guix gc --list-roots=E2=80=99 command lists them. > * What happens when running guix system? How does =E2=80=9C(guix) Using the Configuration System=E2=80=9D fall short= here? > What does guix system do with the definition once it's returned?=C2=A0 How > does install happen on a live system?=C2=A0 What stages are there in the = install? > > How does this process change for the different install targets? (vm, > disk-image, docker image, etc) Likewise, how does =E2=80=9C(guix) Invoking guix system=E2=80=9D fail to ex= plain this? > * G-expressions > > The analogy to quotes is useful, but how do these actually work?=C2=A0 > They're relocatable - how does one store them to disk?=C2=A0 Read them fr= om > disk an execute them?=C2=A0 Or execute them from memory?=C2=A0 Quotes can= be > converted back from data using `eval` - what's the g-expression > equivalent?=C2=A0 Where can they be used (maybe this is more a reference > thing - which functions take g-expression arguments)? I think that =E2=80=9C(guix) G-Expressions=E2=80=9D answers some of these q= uestions, but perhaps you could propose a patch to clarify that. Keep in mind that this section is not about the design and implementation of G-Expressions=E2=80=94there=E2=80=99s a paper on that top= ic. Instead, the intent is to explain why they exist in the first place, and how they can be used. > * Package creation > > Again, the documentation says "use these build systems" but not why, or > what they do. =E2=80=9C(guix) Build Systems=E2=80=9D has: Each package definition specifies a =E2=80=9Cbuild system=E2=80=9D and ar= guments for that build system (*note Defining Packages::). This =E2=80=98build-syste= m=E2=80=99 field represents the build procedure of the package, as well as implicit dependencies of that build procedure. I think that=E2=80=99s an good intro for =E2=80=9Cwhat they do=E2=80=9D, no? > IMO it would be better to start with the trivial build system, say "we > have these files, here's how we turn it into a package" then show how > the build systems make it much simpler but that they're just an > extension of first principles. I=E2=80=99m not sure. I think as a packager you=E2=80=99re first and forem= ost interested in =E2=80=98gnu-build-system=E2=80=99, =E2=80=98cmake-build-syst= em=E2=80=99, and so on, because those are the first you=E2=80=99ll use to get things done. =E2=80=98trivial-build-system=E2=80=99 is usually advanced usage. > * Services > > I've been discussing this in another thread, but it's the same thing - > what a service is is unclear because it hinges on the use of the word > "extend" which isn't defined. I think it does explain extensions in quite some detail, but Chris concurs with you that it=E2=80=99s unclear, so I guess there=E2=80=99s room= for improvement. :-) In short, I=E2=80=99m sure there=E2=80=99s room for improvement in the manu= al. I=E2=80=99m just not sure what you are criticizing or suggesting. That=E2=80=99s why I=E2= =80=99d encourage you to pick one specific example and post a patch for discussion. That would allow us to have a clearer understanding of how we could improve things. Thanks, Ludo=E2=80=99.