unofficial mirror of help-guix@gnu.org 
 help / color / mirror / Atom feed
* About packaging documentation
@ 2021-03-15 14:46 Zelphir Kaltstahl
  2021-03-15 15:43 ` Ricardo Wurmus
  0 siblings, 1 reply; 15+ messages in thread
From: Zelphir Kaltstahl @ 2021-03-15 14:46 UTC (permalink / raw)
  To: help-guix

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


^ permalink raw reply	[flat|nested] 15+ messages in thread

end of thread, other threads:[~2021-04-04 15:58 UTC | newest]

Thread overview: 15+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-03-15 14:46 About packaging documentation Zelphir Kaltstahl
2021-03-15 15:43 ` Ricardo Wurmus
2021-03-16 19:27   ` Zelphir Kaltstahl
2021-03-16 22:03     ` Ricardo Wurmus
2021-03-17 20:43       ` Zelphir Kaltstahl
2021-04-02 11:29       ` Zelphir Kaltstahl
2021-04-02 15:33         ` Zelphir Kaltstahl
2021-04-02 21:59           ` Ricardo Wurmus
2021-04-04 13:41             ` About packaging (was: About packaging documentation) Zelphir Kaltstahl
2021-04-04 14:35               ` Ricardo Wurmus
2021-04-04 15:57                 ` Zelphir Kaltstahl
2021-04-04 14:38               ` Tobias Geerinckx-Rice
2021-04-04 15:30                 ` Zelphir Kaltstahl
2021-04-02 21:56         ` About packaging documentation Ricardo Wurmus
2021-04-04 13:59           ` Zelphir Kaltstahl

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).