From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp11.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id aDHCMPjXLmP3eAEAbAwnHQ (envelope-from ) for ; Sat, 24 Sep 2022 12:12:08 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp11.migadu.com with LMTPS id 0EjeMPjXLmMX7QAA9RJhRA (envelope-from ) for ; Sat, 24 Sep 2022 12:12:08 +0200 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 4582C10C6 for ; Sat, 24 Sep 2022 12:12:08 +0200 (CEST) Received: from localhost ([::1]:42370 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oc28l-00043R-FO for larch@yhetil.org; Sat, 24 Sep 2022 06:12:07 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59946) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oc28g-000439-J8 for guix-patches@gnu.org; Sat, 24 Sep 2022 06:12:02 -0400 Received: from debbugs.gnu.org ([209.51.188.43]:43310) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oc28g-0005oS-Aj for guix-patches@gnu.org; Sat, 24 Sep 2022 06:12:02 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oc28g-0004lN-0I for guix-patches@gnu.org; Sat, 24 Sep 2022 06:12:02 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#57643] [PATCH 0/3] Document the image API. Resent-From: Ludovic =?UTF-8?Q?Court=C3=A8s?= Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Sat, 24 Sep 2022 10:12:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 57643 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: Mathieu Othacehe Cc: 57643@debbugs.gnu.org Received: via spool by 57643-submit@debbugs.gnu.org id=B57643.166401427918261 (code B ref 57643); Sat, 24 Sep 2022 10:12:01 +0000 Received: (at 57643) by debbugs.gnu.org; 24 Sep 2022 10:11:19 +0000 Received: from localhost ([127.0.0.1]:42388 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oc27y-0004kS-Po for submit@debbugs.gnu.org; Sat, 24 Sep 2022 06:11:19 -0400 Received: from eggs.gnu.org ([209.51.188.92]:34380) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oc27w-0004kE-84 for 57643@debbugs.gnu.org; Sat, 24 Sep 2022 06:11:17 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:51478) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oc27q-0005gK-UF for 57643@debbugs.gnu.org; Sat, 24 Sep 2022 06:11:10 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:In-Reply-To:Date:References:Subject:To: From; bh=1DQl8CPpJqDJv7Ihp6b/152N3je+ZrTv6yCKIHAoSmA=; b=qrW1a/fBZnufutIxOQv4 UKm8djOZDloSgREUG2SRgpjJA6Efo24TMZtxL4Dlmkt/RbzgsQgkeK6eheAtT5vvPJfAIgV98ubsL koQshZhfezauyVGob1nruYZkGd81PJGWvB4AXKMt6c7YpVdbBA87pl/wpOH0yP0pOrsQp69GTipxN 2FFL/Igi7b8oocHknMzcOFsOOZPj+/V+SVHfGJjRuLs5biQ6UbpTt0NSjo67vluYELO5QAxlwv1nm IFOBuLGa5+QHy8CY7TxTkjEoqpN/ct0WrnTE451608OS8oFYHNEKNafzgPeigXm0vvpCPnn96ObXF AZNfSzFOyZ7CLA==; Received: from 91-160-117-201.subs.proxad.net ([91.160.117.201]:52778 helo=ribbon) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oc27L-0000Yj-0T; Sat, 24 Sep 2022 06:10:49 -0400 From: Ludovic =?UTF-8?Q?Court=C3=A8s?= References: <20220907124633.17013-1-othacehe@gnu.org> <20220907124633.17013-2-othacehe@gnu.org> Date: Sat, 24 Sep 2022 12:10:37 +0200 In-Reply-To: <20220907124633.17013-2-othacehe@gnu.org> (Mathieu Othacehe's message of "Wed, 7 Sep 2022 14:46:32 +0200") Message-ID: <87v8pdaxr6.fsf_-_@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+larch=yhetil.org@gnu.org Sender: "Guix-patches" X-Migadu-Flow: FLOW_IN X-Migadu-To: larch@yhetil.org X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1664014328; 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:resent-cc: resent-from:resent-sender:resent-message-id:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=1DQl8CPpJqDJv7Ihp6b/152N3je+ZrTv6yCKIHAoSmA=; b=oUHj7wOVah8RPCNnhNU+WT9ySq98EFSEPXdsVOHi5P/IySuXcJ8nYrI8iNJICtMumCi3N9 4bN/flZ1UrrzpYJUAeFGzBxjdv401Kw4kXuOVVJkzms9BUsHVIznsD9cSWWKneBZyl7F7e HI7Vv4qTDqupETOXRSAdWy4VDsTnAdV+wleICPXsJuvCZzc8wnbbtIDu0AWEI5W+W+xOmW C2zvZxydIu0Tl1LsVZOyC/X5XEe9Zc1UQ+M3VsClvd7PIkHyaXpmdZaGuc7bKknWHCpkIr Dd8luzWKleD5OZ5YgHl8m/vuZyUXIs/ntPxI2m9zvjT3BlbnWvEb+hfNBbQoCQ== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1664014328; a=rsa-sha256; cv=none; b=P5gvOYRGXGeqncEBYMiZt+SWn1xWFi1DicGaJWE5CJQf8g9TqmAn5lrQccEPhp3RUtYCAr Ahya/IMlf+ezk6y93k0nMHzwq2AH9pV8URxBCaj1d31rUCwnOF6P1XF5e5exMdIJWusQZe bac2Zqa2G2vwNHrGdDh7Sch3dGRWiwIPInf2bCjt6RRR71+vX1oj1YQFfMNRtNUbmcNxDh iT9AvrsF0ObwOdiuPhybPPAny7FEZZnNrcfqkl75LtbmKHF9Q6b1LcuDpmwWxvpAZnznoI YwhBkxLASmW+NouBMosSAm5YSkh1WW0zIPVeYZGMmIRETiGavvI0TlEFrpAcvQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gnu.org header.s=fencepost-gnu-org header.b="qrW1a/fB"; dmarc=pass (policy=none) header.from=gnu.org; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: -3.66 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gnu.org header.s=fencepost-gnu-org header.b="qrW1a/fB"; dmarc=pass (policy=none) header.from=gnu.org; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: 4582C10C6 X-Spam-Score: -3.66 X-Migadu-Scanner: scn0.migadu.com X-TUID: nU++pJG7A3Sm Mathieu Othacehe skribis: > +The packages and systems built by Guix are intended, like most computer > +programs, to run on a CPU with a specific instruction set. Those s/instruction set/instruction set, and under a specific operating system/ > +@node platform Reference > +@section @code{platform} Reference > + > +@deftp {Data Type} platform Please add a couple of lines above, like =E2=80=9CThe @code{platform} data = type describes a @dfn{platform}: an @acronym{ISA, instruction set architecture}, combined with an operating system and possibly additional system-wide settings such as the @acronym{ABI, application binary interface}.=E2=80=9D > +This is the data type representing a platform. > + > +@table @asis > +@item @code{target} > +The 'target' field must be a valid > +@uref{https://www.gnu.org/software/autoconf/manual/autoconf-2.68/html_no= de/Specifying-Target-Triplets.html, > +GNU triplet}, as a string. Rather: This field specifies the platform's GNU triplet as a string (@pxref{Specifying Target Triplets, GNU configuration triplets,, autoconf, Autoconf}). > It can be for instance, > +@code{"aarch64-linux-gnu"} and is used for cross-compilation purposes > +(@pxref{Cross-Compilation}). > + > +@item @code{system} > +The name of the corresponding system as defined in the @code{(gnu > +packages bootstrap)} module. Maybe: This string is the system type as it is known to Guix and passed, for instance, to the @option{--system} option of most commands. It usually has the form @code{"@var{cpu}-@var{kernel}"}, where @var{cpu} is the target CPU and @var{kernel} the target operating system kernel. (I don=E2=80=99t think the (gnu packages bootstrap) is all that important w= hen explaining this.) > It can be for instance > +@code{"aarch64-linux"} or @code{"armhf-linux"}. OK. > It is used to emulate a > +different host architecture, for instance @code{"i686-linux"} on > +@code{"x86_64-linux"}, or @code{"armhf-linux"} on @code{"x86_64-linux"}, > +using the QEMU binfmt transparent emulation mechanism (@pxref{Native > +Builds}). If =E2=80=9CIt=E2=80=9D denotes =E2=80=9Cthe =E2=80=98system=E2=80=99 field= =E2=80=9D, then this is incorrect. :-) I=E2=80=99m also unsure this is the right place to discuss emulation. I would either drop this part or make it like =E2=80=9CYou will encounter s= ystem types when you perform native builds (@pxref{Native Builds}).=E2=80=9D and = leave it at that. WDYT? > +@item @code{linux-architecture} (default: @code{#false}) > +This optional string field is only relevant if the kernel is Linux. In > +that case, it corresponds to the ARCH variable used when building Linux, > +@code{"mips"} for instance. > + > +@item @code{glibc-dynamic-linker} > +This field is the name of Glibc's dynamic linker for the corresponding > +system, as a string. It can be @code{"/lib/ld-linux-armhf.so.3"}. Instead of =E2=80=9CGlibc=E2=80=9D, I suggest writing =E2=80=9Cthe GNU C Li= brary=E2=80=9D, =E2=80=9Cthe C library=E2=80=9D, or =E2=80=9Cglibc=E2=80=9D as a last resort. > +@node Supported Platforms > +@section Supported Platforms > + > +@defvr {Scheme Variable} armv7-linux Add a couple of lines above, like =E2=80=9CThe XXX module exports the follo= wing variable, each of which is bound to a @code{platform} record.=E2=80=9D > +Platform targeting ARM v7 CPUs running GNU/Linux. > +@end defvr > + > +@defvr {Scheme Variable} aarch64-linux > +Platform targeting ARM v8 CPUs running GNU/Linux. > +@end defvr > + > +@defvr {Scheme Variable} mips64-linux > +Platform targeting MIPS 64 bits little endian CPUs running GNU/Linux. General note: write =E2=80=9Ca 64-bit CPU=E2=80=9D (hyphen, singular). > +@defvr {Scheme Variable} i686-linux > +Platform targeting x86 CPUs running GNU/Linux. x/x86/Intel/? > +@defvr {Scheme Variable} x86_64-linux > +Platform targeting x86 64 bits CPUs running GNU/Linux. Or x86_64? > +@defvr {Scheme Variable} i686-mingw > +Platform targeting x86 CPUs running WIN32. > +@end defvr > + > +@defvr {Scheme Variable} x86_64-mingw > +Platform targeting x86 64 bits CPUs running WIN32. s/running WIN32/running Windows, with run-time support from MinGW/ > +@defvr {Scheme Variable} hurd > +Platform targeting x86 CPUs running GNU/Hurd. Why is not called =E2=80=98i586-gnu=E2=80=99? Maybe you can write =E2=80=9CGNU/Hurd (also referred to as ``GNU'')=E2=80= =9D to clarify the name. Ludo=E2=80=99.