Another way to go about this is to create a manual for packagers. My guix-notes is more general (mostly to help my memory), and then there is the wiki-thing. But I agree we don't have a very helpful starting point for packagers considering they need to learn multiple things at the same time (not least Guile ;).
Pj. On Mon, Dec 14, 2015 at 02:36:54PM -0500, Leo Famulari wrote: > On Mon, Dec 14, 2015 at 10:28:57AM +0100, Pjotr Prins wrote: > > The problem with the main text is that it is written from the view > > point of technology. I would like something more human that reads like > > an instruction for packagers. Be great if we had something useful > > there, otherwise questions will be asked again and again :). And I > > will have to point to guix-notes every time. > > It's true, an extremely technical explanation will be completely useful > and accurate and ... it won't help many of the readers who actually need > help. It is very easy to package simple programs for Guix. But I have > found that as soon as the program deviates from the Autotools or > setup.py script at all, you really need some domain-specific technical > knowledge to finish the package. I have personally learned a lot about > many subjects while packaging for Guix. > > See the recent ML thread about packaging 'sent'. > > > > > I agree my version is less accurate, but it acts like a summing up and > > (actually) is precisely the way I look at these statements. We can > > have both. I am not saying we should replace your section. > > I think we are all loath to include inaccuracies in the manual. But on > the other hand, I think we need to find a way to summarize the > distinction that is close to what Pjotr is proposing. > > Some of us have an understanding of the subject that is directly based > on the Guix / Nix source code. The rest of us have learned by > trial-and-error and rough heuristics like Pjotr's summary (hopefully we > will all 'use the source' eventually ;) . > > The difficult thing is explaining it in a way that "sets up" the reader > for further learning. You must be accurate, but you must not be too > verbose, because when you are banging your head against the wall, it is > difficult to read a long text. > > The other day, this helpful jewel was shared by mark_weaver on #guix [0]: > fhmgufs: the distinction between build and runtime dependencies is > determined by scanning the outputs of the build for references to > /gnu/store/.... > > Learning the mechanism made it clear to me. This is why Python inputs > must be propagated: there is nowhere in the main Python program to link > to dependencies in the store, so the inputs must be propagated onto > PYTHONPATH. I already understood the difference between 'native-inputs' > and 'inputs', and this doesn't really get to the heart of the > difference, but it does draw a line between them. > > I propose we adapt this statement for use in the manual (assuming that > is accurate). > > If there is no updated patch in a few hours, I will write one, but I > can't do it at the moment. > > [0] > https://gnunet.org/bot/log/guix/2015-12-09 > > PS— I can't follow the "flow" of this conversation because some people > are replying in-line while others are top-posting. Please, let's pick > one (I vote for in-line). > > > > > Anyway, maybe I am the only one seeing it like this. > > > > Pj. > > > > On Mon, Dec 14, 2015 at 09:58:19AM +0100, Ludovic Courtès wrote: > > > Pjotr Prins <pjotr.publi...@thebird.nl> skribis: > > > > > > > Thanks Ludo. I still think it could be made a little clearer from the > > > > packager's > > > > perspective. How about concluding it with something like: > > > > > > > > In short, to create a package, by default you should use 'inputs' for > > > > dependencies. Use 'native-inputs' for tools used at build-time, but > > > > not at runtime and use propagated-inputs when the other two do not > > > > suffice. > > > > > > This is certainly shorter, but the problem I have with that is that it > > > does not accurately explain what’s going on. The current text is > > > admittedly more verbose, but I think it is more accurate. > > > > > > Hope that makes sense. > > > > > > Ludo’. > > > > > > > -- > > > --
