Hello! rendaw <7e9wc56emja...@s.rendaw.me> skribis:
> The areas that were important for me but weren't well documented were: Thanks for explaining! That’s a lot of things to digest. :-) I’m not entirely sure I agree with or understand everything you mention, I’ll comment on some of these below. However, I think you should really propose incremental improvements to the manual in these areas; it’ll be easier to discuss specific sections or paragraphs. > 1. Concepts > > * What is functional package management? What is garbage collection? > How do these work? “(guix) Managing Software the Guix Way” has a paragraph about functional package management, but that’s (purposefully) the only place where FPM is discussed. > What is a package? How does Guix determine what makes a package > unique? What's a derivation, and what's the relationship between > derivations and packages? 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. What's a tangible example of a > derivation? Where and why would someone use a derivation directly? “(guix) Defining Packages” explains: Behind the scenes, a derivation corresponding to the ‘<package>’ object is first computed by the ‘package-derivation’ procedure. That derivation is stored in a ‘.drv’ file under ‘/gnu/store’. The build actions it prescribes may then be realized by using the ‘build-derivations’ procedure (*note The Store::). … 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. “(guix) Invoking guix gc” has a paragraph that I think explains what a GC root is: The garbage collector has a set of known “roots”: any file under ‘/gnu/store’ reachable from a root is considered “live” and cannot be deleted; any other file is considered “dead” and may be deleted. The set of garbage collector roots (“GC roots” for short) includes default user profiles; by default, the symlinks under ‘/var/guix/gcroots’ represent these GC roots. New GC roots can be added with ‘guix build --root’, for example (*note Invoking guix build::). The ‘guix gc --list-roots’ command lists them. > * What happens when running guix system? How does “(guix) Using the Configuration System” fall short here? > What does guix system do with the definition once it's returned? How > does install happen on a live system? 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 “(guix) Invoking guix system” fail to explain this? > * G-expressions > > The analogy to quotes is useful, but how do these actually work? > They're relocatable - how does one store them to disk? Read them from > disk an execute them? Or execute them from memory? Quotes can be > converted back from data using `eval` - what's the g-expression > equivalent? Where can they be used (maybe this is more a reference > thing - which functions take g-expression arguments)? I think that “(guix) G-Expressions” answers some of these questions, 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—there’s a paper on that topic. 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. “(guix) Build Systems” has: Each package definition specifies a “build system” and arguments for that build system (*note Defining Packages::). This ‘build-system’ field represents the build procedure of the package, as well as implicit dependencies of that build procedure. I think that’s an good intro for “what they do”, 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’m not sure. I think as a packager you’re first and foremost interested in ‘gnu-build-system’, ‘cmake-build-system’, and so on, because those are the first you’ll use to get things done. ‘trivial-build-system’ 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’s unclear, so I guess there’s room for improvement. :-) In short, I’m sure there’s room for improvement in the manual. I’m just not sure what you are criticizing or suggesting. That’s why I’d 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’.