Hello Guix users! Please treat the following message as a suggestion for improvement for the documentation and not as some kind of rant.
Addressing the following docs: - https://guix.gnu.org/manual/en/html_node/Packaging-Guidelines.html - https://guix.gnu.org/manual/en/html_node/Defining-Packages.html - https://guix.gnu.org/manual/en/html_node/Running-Guix-Before-It-Is-Installed.html - https://guix.gnu.org/manual/en/html_node/Building-from-Git.html - https://guix.gnu.org/manual/en/html_node/The-Store.html These are all informative and in themselves great. I am not claiming these are badly written documentation. In my quest to creating a package and making a patch to send in, I looked at the docs on multiple days after my day job and at weekends, taking notes, trying to understand the order of things. For approximately a month I am working on getting a simple package into GNU Guix. Not full-time of course, but as motivation and the day job allows. In the docs I am directed from one page to the next, every time landing on another page, that had lost all of my context (create a package and make a patch for it in the best way possible). It has cost me a lot of time and I am still not done making a simple package. The docs really need a cooking recipe style guide for this. Some set of commands, that one can run on any well known major GNU/Linux distribution. If necessary requiring an already installed guix, if that makes coming up with a set of commands to run easier or more reliable. The problem is, that the docs do not have the context. They are good general documentation, explaining some of the concepts guix uses. What do I mean by this? When I want to do one specific thing using guix, I will find the general documentation like "Building from Git", "The Store" and similar. However, they are rarely, if ever, referring to my specific use-case of making a new package. Any link contained in them will direct me to another general documentation page. Then I have to read all of it, understand it, and then try to deduce, how to use it in my use-case. I even fail at understanding it, because I do not make the connections, that one already knowledgeable in how guix works would make. Some things that are clear to someone knowing some background detail that I do not know, will be unclear to me. For example: The docs say to run `guix environment` with the --pure flag, when creating an environment to run `./bootstrap` and `./configure --localstatedir=...` in to create the pre-inst-env script. I would not guess, that I can try creating the environment leaving out the --pure flag, because my mind is set to use the flag, otherwise I am doing something wrong, because that's how the docs told me to do it. Another example: I want to make a clean test, without any previous state, with a clean store. But how would I ever guess, that I _can_ indeed use /var, when that is the store of an already installed guix binary installation? Of course, a person knowing a lot about guix already ("it works because …") or knowing from experience ("it usually simply works as follows …") can guess such things. In my opinion the guix documentation needs context specific documentation in addition to the general documentation. What are the exact steps to run, when I want to add a package. From time to time tested by someone with a lot of knowledge about guix, to make sure it is all still working. Or even better, put into a test to be run automatically. I am trying to create such documentation for the package creation of a pure GNU Guile package: https://notabug.org/ZelphirKaltstahl/gnu-guile-gnu-guix-packaging-guide/src/master/gnu-guix-patch-guide.org <https://notabug.org/ZelphirKaltstahl/gnu-guile-gnu-guix-packaging-guide/src/master/gnu-guix-patch-guide.org> I hope to write everything down once I can finally get my package installed and working. Perhaps it could be added to the guix documentation once done as an explanation for packaging guile-hall created packages of pure guile libraries? https://guix.gnu.org/cookbook/en/html_node/Packaging-Tutorial.html <https://guix.gnu.org/cookbook/en/html_node/Packaging-Tutorial.html> is a good start. It has even got cookbook in the name. Definitely the right idea to complement the general documentation. I am aware of its existence. Unfortunately, I could not get the basic approach of the "Hello World package" working for my package, even though it is pure guile, no other library required and no FFI or anything. I would have preferred not having to go through all the autotools stuff, and to have this simple way working for my package. Perhaps I did something slightly wrong. I do not know. Someone mentioned on the guile user mailing list, that this is all that should be needed for a pure guile package. Perhaps it can be updated? Here is an idea for what such an update could look like: 1. docs that includes a multi-module pure Guile example 2. then next iteration one example with dependencies of other guile libraries 3. then next step one example, in which the package uses FFI to interact with a C library @1: That is documentation I am working on currently. Once I understand everything, I should be able to write it down, so that it can be applied to any pure GNU Guile package. @2: Hopefully this will be almost the same as @1, because one only needs to add another dependency in the package definition. @3: I am not sure. Probably through defining the C library as a native-input or something. What do you think about this idea? After failing with the cookbook, I switched to the other approach of using guile-hall (e-mail thread was on guile user mailing list), which set up the whole autotools infrastructure for me. I can at least install my package locally into my installed guix now. However, that is impractical, if I have to do it for multiple projects running in separate environments. (And I usually use a new environment for each new project.) So I need to get a package into GNU Guix itself, in the official repositories or a fork, which I could use as channel. As far as I understand a fork is not encouraged, as it would not be easily available for everyone else, without specifying the fork as a channel. I will continue to try and make a package. I imagine, that the problems I ran into while trying to package are problems that could deter many from continuing and contributing packages. It feels like quite a long journey to me. Perhaps I am doing things wrong. I am trying to have a reproducible way of adding packages, that will most likely not fail on another system and trying to document that. So perhaps some complexity stems from that approach as well. Hopefully we can improve the situation to make it easier for new people to find the exact steps they need to go through. Best wishes, Zelphir -- repositories: https://notabug.org/ZelphirKaltstahl
