From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2.migadu.com ([2001:41d0:403:4876::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms1.migadu.com with LMTPS id +NFmHE2SU2akHwEAe85BDQ:P1 (envelope-from ) for ; Sun, 26 May 2024 21:49:33 +0200 Received: from aspmx1.migadu.com ([2001:41d0:403:4876::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2.migadu.com with LMTPS id +NFmHE2SU2akHwEAe85BDQ (envelope-from ) for ; Sun, 26 May 2024 21:49:33 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=excalamus.com header.s=zmail header.b=dedkiniv; spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org"; dmarc=none; arc=pass ("zohomail.com:s=zohoarc:i=1") ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1716752973; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=6dhKrONx2EHzUXasDMPj6FVZrZ3K2yrvCIm62Dw0wtQ=; b=tXatMqy1XOUrRWFsaMyafxkoT5QKmAQO2qiKfA2mwQ/SWL0NHoxaIrsimIq0jG3egynuBC JcpYkCzgLA+TLMRR1cVdZKP+tC6XY7ktqNfCiBrCsUwUMZ3etEb4TCnyv7IrAaNlEP4jSe YftG83USJrJ1IgPcg2RNwBn8UunRdrv8lcwK6NGIbFP96BqYchNCKdVrXz71oUt0VhxEG7 PU4suZ+zwi84XY6reeQ6E5qioTodZwQOwKbnXGBGgZGEVLoq6S9agxOWn/hqEUEgrl+3Jm lmjrNZCjBqkVo5VaX7S3WLMvaleZa+U4bGtqrvBHQeI/wYBokFSauMAJ3hq/eg== ARC-Authentication-Results: i=2; aspmx1.migadu.com; dkim=pass header.d=excalamus.com header.s=zmail header.b=dedkiniv; spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org"; dmarc=none; arc=pass ("zohomail.com:s=zohoarc:i=1") ARC-Seal: i=2; s=key1; d=yhetil.org; t=1716752973; a=rsa-sha256; cv=pass; b=GeGf0iCKTXMSyaPfFhv39EAqd8DDA+5+jrXLOXGpv5nW3pbbPdiCNuR6AMiOmMz5Yf/bSd k0KpXLBv0c3AykOti0ach77ZM1+OHU9tsB93BsUIe4O6Ta7CJcfu/L+WyXIYCTXlx+N63f q8BaeYUbbYkML04FunJeJ+jCRSyvEEzN/kyEAYl271bOFL5DFnqxDPd8cTwQvNZfgY3B5d +y5HZfHdtKl7WkwBc9LzYsUN5nY3+HdOt6FtyaWlKK7RNIdfYuDX4/GvDRyjBl6hVZ0jtv /1sBpasD0Pq9JcGpwq1hy4XvnfoPs+Bv7genXIdV4RUNr+8ydchBbQbrpmbCuA== 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 D0C4B735C8 for ; Sun, 26 May 2024 21:49:32 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sBJqL-0001SX-Rg; Sun, 26 May 2024 15:47:47 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sBJqH-00015y-GL for guix-devel@gnu.org; Sun, 26 May 2024 15:47:41 -0400 Received: from sender4-pp-f112.zoho.com ([136.143.188.112]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sBJqE-00008D-9v for guix-devel@gnu.org; Sun, 26 May 2024 15:47:40 -0400 ARC-Seal: i=1; a=rsa-sha256; t=1716752850; cv=none; d=zohomail.com; s=zohoarc; b=bGqnpFdFetnwImYispdjJ9rNqmeihQ23avWaUm9xh95b3RCTw0QNZ16krGEeQ+J89o0Z2lH9+kQGEWOVwnTgyVPhXL4+ncFl4w44wCRJIuioaev5rW2aSyRNxHc7ZiCqqlAHayseXI4DT/B1y1LC5XFiI9SNy8ix4dpSA70i5mw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1716752850; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:MIME-Version:Message-ID:References:Subject:Subject:To:To:Message-Id:Reply-To; bh=6dhKrONx2EHzUXasDMPj6FVZrZ3K2yrvCIm62Dw0wtQ=; b=RGu+rGKle3IPKXVNs2URmprT0D8CGel+qUgnJsJK9FUGwz7VeA96b2EL9aWkiA0uSt/e3WRXk+X5yZCUrUOdi6V+vZOshlLmCIMvc8mZyX7I/ejDOxxW95j2eMcXEurul40ZZVdqrDZYXi+pfo0G88hSFHmWH/JSMNNMAeESJ/g= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass header.i=excalamus.com; spf=pass smtp.mailfrom=matt@excalamus.com; dmarc=pass header.from= DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; t=1716752850; s=zmail; d=excalamus.com; i=matt@excalamus.com; h=Date:Date:From:From:To:To:Cc:Cc:Message-ID:In-Reply-To:References:Subject:Subject:MIME-Version:Content-Type:Content-Transfer-Encoding:Message-Id:Reply-To; bh=6dhKrONx2EHzUXasDMPj6FVZrZ3K2yrvCIm62Dw0wtQ=; b=dedkiniv7bhM3hAs24ONpeze1XEWgvCcxK+xfjZOp3iaDBcIXxvQjGoqplSlUyWV 06YiqdoL4X13fqqSncZgoSt+v+32OoqHDagCYy/ln5TdIkCv+34jJUzgRaf/JS3PHli qKRLAIQrEUqVbX5WGDogenr1gDX0i+pb3HYMFCVs= Received: from mail.zoho.com by mx.zohomail.com with SMTP id 1716752847777868.784738746188; Sun, 26 May 2024 12:47:27 -0700 (PDT) Date: Sun, 26 May 2024 21:47:27 +0200 From: Matt To: "pelzflorian (Florian Pelz)" Cc: "Vagrant Cascadian" , "guix-devel" , "dev" , "maximcournoyer" Message-ID: <18fb6719386.fd14c1f273590.3952521981871749409@excalamus.com> In-Reply-To: <87ikzksr3c.fsf@pelzflorian.de> References: <87a5p8yn4p.fsf@dadoes.de> <18f54937bf9.bbb95b97196253.976385347649899026@excalamus.com> <87y18ll5he.fsf@contorta> <18f61efac25.12b7c69ea491294.3159506289984304603@excalamus.com> <87ikzksr3c.fsf@pelzflorian.de> Subject: Re: [PATCH] doc: Clarify need to update search paths on foreign distro (was Re: Feedback of the GNU Guix manual) MIME-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Importance: Medium User-Agent: Zoho Mail X-Mailer: Zoho Mail Received-SPF: pass client-ip=136.143.188.112; envelope-from=matt@excalamus.com; helo=sender4-pp-f112.zoho.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 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, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=-0.01, RCVD_IN_MSPIKE_WL=-0.01, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: guix-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+larch=yhetil.org@gnu.org Sender: guix-devel-bounces+larch=yhetil.org@gnu.org X-Migadu-Country: US X-Migadu-Flow: FLOW_IN X-Spam-Score: -6.53 X-Migadu-Queue-Id: D0C4B735C8 X-Migadu-Scanner: mx10.migadu.com X-Migadu-Spam-Score: -6.53 X-TUID: U4s8auhTAlLA ---- On Sat, 11 May 2024 10:14:15 +0200 pelzflorian (Florian Pelz) wrote = --- > Instead, there already is advice for .config/guix/current documented in > the Guix manual=E2=80=99s Getting Started section. The advice should be = a > cross-reference that users should follow the steps from Getting Started, > so search paths are set up properly instead of advising to set PATH and > INFOPATH. > > The advice of setting PATH really should go away. Sorry for the late and lengthy reply. Life is life and when I returned to = the issue I noticed that the problem is really that the concept of profiles= could use some revision within the manual. That will make for a rather co= mplex change set. I hoped to have one ready yet, again, life is life. So,= here are my thoughts and, after hearing yours, I can put together the nec= essary changes if my points hold. I see two fundamental issues: 1. should there be a single point of reference for the concept of "profile"= and where should it be? 2. what information about profiles is relevant to addressing the reported i= ssue and where is it? We'll need to discuss possible solutions because, unfortunately, the concep= t of "profiles" isn't conveniently documented. ISSUE 1 - should there be a single point of reference for the concept of "p= rofile" and where should it be? tl;dr create a new subsection for the profile concept I find your suggestion reasonable; document concepts in a single place and = then favor references to that place. Unfortunately, there is currently no = single place of reference for the concept of "profile". Important facts about profiles are spread across the following sections (a = list is given at the end of this section): - Section 4: Getting Started (1) - Section 5.1: Features (and isn't indexed there) (1) - Section 5.2: Invoking 'guix package' (13) - Section 5.7: Invoking 'guix pull' (3) - Section 8.8: Search Paths (1) - Section 9.1: Invoking 'guix build' (1) - Section 11.3: operating-system Reference (2), and - Section 11.19.3: Service Reference (1) Should we make Section 4: Getting Started the common reference point? I say no. The Getting Started section is intended to help readers get star= ted with Guix and get a feel of what it's like. Therefore, it should conta= in a simple how-to with minimal explanation. As the GNU Press Styleguide[1= ] advises, "Move slowly. Do not impose too much of a cognitive load at once on the rea= der." I think the Getting Started section has too much profile information in it = as is. For example, GUIX_PYTHONPATH is a convention, hard-coded into packa= ge definitions whereas GUIX_PROFILE is a literary shorthand for the concept= that multiple profiles may exist and that the profile is the $HOME/.guix-p= rofile in this case. Of all the sections that discuss profiles, Invoking 'guix package' contains= the most information (13 facts). It's also given as the point of referenc= e by 5 other sections: 1. Invoking 'guix pull' (twice) 2. Invoking 'guix shell' 3. Invoking 'guix environment' 4. Invoking 'guix build' 5. operating-system Reference Should we make Invoking 'guix package' be the common reference point for pr= ofiles? Again, I say no. AFAIU, profiles have two forms: a system profile, sometime= s called the global profile, which manages Guix itself and user profiles, i= ncluding "default" or "current", which dictate package accessibility. Whil= e system and user profiles "work exactly" like each other (see Invoking gui= x pull), there are separate commands for each: 'guix package' is for user p= rofiles and 'guix pull' is for the system profile. It's easy to confuse al= l this. Therefore, it would be better to have a separate section that expl= ains profiles and let Invoking 'guix package' and Invoking 'guix pull' focu= s on the command options. The best common reference point for profiles is in a new section just below= Section 5.1: Features. As the Styleguide[1] says, "Put important notes to the reader in subsections of their own. This tells = the reader the notes really are important." Profiles are first introduced in Section 4: Getting Started. It does a goo= d job introducing the idea and could actually provide less information. Th= e concept, however, is first explained in Section 5.1: Features. The major= ity of Features is about how profiles are useful and a core concept of Guix= . I think we could switch the focus of Features to be about the benefits o= f the store, the symlink forest, transactions, control of the build environ= ment, and provenance tracking and move the explanation and details of profi= les to a new subsection. Information about profiles grouped by section: - Getting Started + A profile is a directory containing installed packages - Features (not indexed) + A profile is a reference to the store kept in each user's home directory managed by 'guix package' - Invoking 'guix package' + a profile is a directory of installed packages + profiles exist per user + there exists a "default" profile + guix package operations create and modify profiles + profiles are created in $HOME/.guix-profile + $HOME/.guix-profile is a symlink + In a multi-user setup, user profiles are stored in a place registered as a "garbage-collector root" + there is a notion of "current profile" + profiles have generations + generations within a profile are linear, starting with a "zeroth generation", which contains no files apart from its own metadata. + multiple profiles may be referenced at a time + removing a profile means removing the symlink previously specified by "guix project --profile" as well as any corresponding '-*-link' suffixed symlinks + profiles are handles on state (that is, the state of which software is installed and available) - Invoking guix pull + the latest Guix is determined by a profile + 'guix pull' and 'guix package' both create profiles and how these profiles work is similar + there are two types of profiles; those managed by 'guix pull' and those managed by 'guix package' - Search Paths + installing packages in the default profile creates the file '~/.guix-profile/etc/profile' which defines search path environment variables - Invoking 'guix build' + modifying the user's profile is the job of 'guix package' - operating-system Reference + the global profile is accessible at '/run/current-system/profile' + it is good practice to install non-core utilities in user profiles - Service Reference + the "system profile" is the programs under '/run/current-system/profile' ISSUE 2- what information about profiles is relevant to addressing the repo= rted issue and where is it? tldr; we should create a new subsection rather than expand Getting Started I'm able to reduce the information necessary to address the reported issue = to: 1. the user environment must be configured so that the shell and other appl= ications can find software installed with Guix 2. Guix provides a file, $GUIX_PROFILE/etc/profile, to configure the user e= nvironment 3. $GUIX_PROFILE/etc/profile is created for *each* profile 4. $GUIX_PROFILE/etc/profile must be sourced Section 4: Getting Started explicitly states the first and forth points and= implies the second. AFAICT, the third isn't actually in the manual (altho= ugh it is in the Cookbook)! I think explaining $GUIX_PROFILE/etc/profile in more detail within Getting = Started wouldn't make sense. Therefore, because of this, and the points I = made above, we should consider breaking out profiles into their own section= . [1] https://www.fsf.org/licensing/gnu-press/GNU-Press-styleguide.pdf