From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1 ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms11 with LMTPS id eHMWA1xzT2BnLgAA0tVLHw (envelope-from ) for ; Mon, 15 Mar 2021 14:46:52 +0000 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1 with LMTPS id SHltOltzT2DUYQAAbx9fmQ (envelope-from ) for ; Mon, 15 Mar 2021 14:46:51 +0000 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 6F9EA15E8C for ; Mon, 15 Mar 2021 15:46:51 +0100 (CET) Received: from localhost ([::1]:35242 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lLoUc-0001GC-84 for larch@yhetil.org; Mon, 15 Mar 2021 10:46:50 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:60342) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lLoU0-0001FL-EU for help-guix@gnu.org; Mon, 15 Mar 2021 10:46:12 -0400 Received: from mout02.posteo.de ([185.67.36.66]:37103) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lLoTt-00009t-Lp for help-guix@gnu.org; Mon, 15 Mar 2021 10:46:12 -0400 Received: from submission (posteo.de [89.146.220.130]) by mout02.posteo.de (Postfix) with ESMTPS id DE2CD2400FB for ; Mon, 15 Mar 2021 15:46:02 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.de; s=2017; t=1615819562; bh=7NWTXm8Q2npTZjX8867mhhVxS8qHFKFRAJOo0hbHofo=; h=To:From:Subject:Date:From; b=PKerD5QwhiYbtkUJy7ZdfoTHE2pf3a0GtBowqnABqirouTGwBs5dvu+UtUD11knP4 5N07uGV34HOcc1qLjfP7FDoJg5dMP0KGoxL1tavrY/kwE/mO1SaO0v6BxSAu+mkRs7 jgU5tkz462rCl+wdUL8xXqBCicKmDj6k3wAtKBcvTrQgMxBckCXwkGS/gtujY7dL/I 5/Dio0ZwcHfxFsWxxW/FmUXCpDXcSR6jdX7VfAWAa/knvb81VUi/mBazCXXViBIskE gvr6GpaplRPguvAVTiZlaeH1LXD8HowAsk8hupZcZljm4hnz67ZNMIvbCsfH3F0x3B UGmndp7bqlbMA== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4DzfP60KZYz9rxH for ; Mon, 15 Mar 2021 15:46:01 +0100 (CET) To: help-guix From: Zelphir Kaltstahl Subject: About packaging documentation Message-ID: Date: Mon, 15 Mar 2021 15:46:01 +0100 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.7.1 MIME-Version: 1.0 Content-Language: en-US Received-SPF: pass client-ip=185.67.36.66; envelope-from=zelphirkaltstahl@posteo.de; helo=mout02.posteo.de X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_SBL=1.623 autolearn=ham autolearn_force=no X-Spam_action: no action Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Content-Filtered-By: Mailman/MimeDel 2.1.23 X-BeenThere: help-guix@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-guix-bounces+larch=yhetil.org@gnu.org Sender: "Help-Guix" X-Migadu-Flow: FLOW_IN ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1615819611; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=pIUY0vDukSZ3JWGqNPWYHQug7dHcf1/zAZHwXbh9ClY=; b=TMqotZ2aWqEoU6kVoK1O6PlHy7JiUVoBjChw5DpKj5UcAPFt+V4G9EVR7JeLdT5yGnhQja c5whWVFEweS3Njz7k/1NJqomob2gOL6qFZ4AKve+npitMxgt9Fo1Pr0lMeSEYBcu/G0Htz vc5YS312X7hVLG5aH7V+G4sOy2+Esn09Z7wVqssxDLgeya6+5BKykUhvaHrKV+OT1c4qpM rGu3sXBsNMygkZW1WSv80dmqotFMU34MDQ78U11Ii5MORctf+yw9sP1mM/1d4H/U3/mAps pyCD0ubh92m1MQwhaQYYdeEP5v2iuRBve/MZxZ4kIz903otalNhqWiUhgXelFg== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1615819611; a=rsa-sha256; cv=none; b=V4cfi6IuC4HkUKKDVGYk9Hf6cOZh7BtVtGi0QyS2kVaWchG2ZrFjsTLOQBmEIuv1AFC+Vl qqOx/eHGeVN6FhkeZOHuBRKXLsySqOAWG/8njspXIiHpcskRxtF20OsykecahMwRgJe2dv nAUuBryDXUwLdLUK8cXEK2dlkBmF8p/J5LX7RpiVHHYSopSCi9g32DOSXsL7UsTadewfcE WtLhaLG6JCPtp1plgICd/wtAgTn7Hb45+fbodT4TQAiVkkV57SDHQ4JbmuiUVtxY1UU8AT 0nvUtfzjj9Pjlm9dZmh3tOxPuWALs6AKRRCvRd8nRyv1OanrddhgzYx5ght+VQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("body hash did not verify") header.d=posteo.de header.s=2017 header.b=PKerD5Qw; spf=pass (aspmx1.migadu.com: domain of help-guix-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=help-guix-bounces@gnu.org X-Migadu-Spam-Score: 0.20 Authentication-Results: aspmx1.migadu.com; dkim=fail ("body hash did not verify") header.d=posteo.de header.s=2017 header.b=PKerD5Qw; dmarc=fail reason="SPF not aligned (strict)" header.from=posteo.de (policy=none); spf=pass (aspmx1.migadu.com: domain of help-guix-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=help-guix-bounces@gnu.org X-Migadu-Queue-Id: 6F9EA15E8C X-Spam-Score: 0.20 X-Migadu-Scanner: scn0.migadu.com X-TUID: FdpwTquJnqFI 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 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  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