| Message ID | 20220907124633.17013-2-othacehe@gnu.org |
|---|---|
| State | Accepted |
| Headers | show |
| Series | Document the image API. | expand |
| Context | Check | Description |
|---|---|---|
| cbaines/comparison | success | View comparision |
| cbaines/git-branch | success | View Git branch |
| cbaines/applying patch | success | View Laminar job |
| cbaines/issue | success | View issue |
Hi Mathieu, On Wed, 07 Sep 2022 at 14:46, Mathieu Othacehe <othacehe@gnu.org> wrote: > +* platform Reference:: Detail of platform declarations. -^ Why not P? > +@menu > +* platform Reference:: Detail of platform declarations. Idem. > +@item @code{system} > +The name of the corresponding system as defined in the @code{(gnu > +packages bootstrap)} module. The other items are a sentence. Here I am missing the verb. LTGM. Cheers, simon
zimoun <zimon.toutoune@gmail.com> skribis: > On Wed, 07 Sep 2022 at 14:46, Mathieu Othacehe <othacehe@gnu.org> wrote: > >> +* platform Reference:: Detail of platform declarations. > -^ > Why not P? Because it’s the reference of the ‘platform’ data type. :-) Ludo’.
Mathieu Othacehe <othacehe@gnu.org> 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 “The @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}.” > +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_node/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’t think the (gnu packages bootstrap) is all that important when 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 “It” denotes “the ‘system’ field”, then this is incorrect. :-) I’m also unsure this is the right place to discuss emulation. I would either drop this part or make it like “You will encounter system types when you perform native builds (@pxref{Native Builds}).” 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 “Glibc”, I suggest writing “the GNU C Library”, “the C library”, or “glibc” as a last resort. > +@node Supported Platforms > +@section Supported Platforms > + > +@defvr {Scheme Variable} armv7-linux Add a couple of lines above, like “The XXX module exports the following variable, each of which is bound to a @code{platform} record.” > +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 “a 64-bit CPU” (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 ‘i586-gnu’? Maybe you can write “GNU/Hurd (also referred to as ``GNU'')” to clarify the name. Ludo’.
On 24-09-2022 12:10, Ludovic Courtès wrote: >> +@defvr {Scheme Variable} i686-linux >> +Platform targeting x86 CPUs running GNU/Linux. > x/x86/Intel/? > (1) i686 is not the same as x86 -- not all x86 are 32-bit (Intel 80286 is 16-bit) and not all x86_32 are i686 (example: i586) (2) I don't think i486 / i586 / i686 is relevant for the variable name, though I suppose we could mention in the description that Guix assumes i686 or later (or otherwise compatible). (3) x86 and Intel are not equivalent -- Intel has 64-bit architectures too: x86-64 (shared with AMD) and IA-64 (shared with HP). Proposal: rename the variable to x86-32-linux. Likewise for the hurd. > +@defvr {Scheme Variable} powerpc-linux > +Platform targeting PowerPC 32 bits CPUs running GNU/Linux. > +@end defvr > + > +@defvr {Scheme Variable} powerpc64le-linux > +Platform targeting PowerPC 64 bits little endian CPUs running GNU/Linux. > +@end defvr Why is the endian mentioned for powerpc64le-linux and not powerpc (in the description and in the variable name)? This looks inconsistent. (From what I've read, PowerPC has both a little-endian and a big-endian mode.) > +@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. > +@end defvr I don't think mentioning the version of the Windows API is relevant information, similar to how we the version of glibc or linux is not mentioned for the -linux variables. I think it would be clearer to mention Microsoft Windows directly instead (and easier to search for). >> +@defvr {Scheme Variable} mips64-linux >> +Platform targeting MIPS 64 bits little endian CPUs running GNU/Linux. 'little endian' is an adjective here, so I think 'little-endian' would be appropriate here. >> +@defvr {Scheme Variable} hurd >> +Platform targeting x86 CPUs running GNU/Hurd. > > Why is not called ‘i586-gnu’? How about x86-32-gnu, for the same reasons as i686-linux? Greetings, Maxime.
Hey, > Why is not called ‘i586-gnu’? > > Maybe you can write “GNU/Hurd (also referred to as ``GNU'')” to clarify > the name. I added a preliminary patch doing this rename. Thanks, Mathieu
Hello Maxime, > Proposal: rename the variable to x86-32-linux. Likewise for the hurd. It makes sense to me. However, we would also have to rename accordingly the "system" counterpart in (gnu packages bootstrap). Something to keep in mind. > Why is the endian mentioned for powerpc64le-linux and not powerpc (in the > description and in the variable name)? This looks inconsistent. (From what > I've read, PowerPC has both a little-endian and a big-endian mode.) Fixed. > 'little endian' is an adjective here, so I think 'little-endian' would be > appropriate here. Fixed. >>> +@defvr {Scheme Variable} hurd >>> +Platform targeting x86 CPUs running GNU/Hurd. >> Why is not called ‘i586-gnu’? > > How about x86-32-gnu, for the same reasons as i686-linux? Also looks fine but has to be done at a larger scale like for the x86-32-linux renaming. Thanks for reviewing, Mathieu
Hi,
Maxime Devos <maximedevos@telenet.be> skribis:
> Proposal: rename the variable to x86-32-linux. Likewise for the hurd.
While we’re discussing the color of the bikeshed :-), I’d like to point
out that “x86_32” or “x86-32” is not a thing. The official name is
either IA32 or, more specifically, i686, etc. I’m in favor of sticking
to official (nick)names consistently.
Ludo’.
On 24-09-2022 18:33, Ludovic Courtès wrote> Hi, > > Maxime Devos<maximedevos@telenet.be> skribis: > >> Proposal: rename the variable to x86-32-linux. Likewise for the hurd. > While we’re discussing the color of the bikeshed :-), I’d like to point > out that “x86_32” or “x86-32” is not a thing. It is a thing if we let it be a thing. It also already is a thing: target-x86-32? exists, "x86-32" finds some relevant search results (though it can be confused with another meaning of "x86-32" -- an ABI where pointers are 32-bit but all of the x86-64 instruction set remains available, so far from an ideal naming.) > The official name is > either IA32 or, more specifically, i686, etc. In my experience, IA-32 is not a thing except in Intel documents and various irregular exceptions, however official it might be ... which seems similar to x86-32. > I’m in favor of sticking > to official (nick)names consistently. Going by https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html , the official name is IA-32, not IA32. IA-32 sounds nice to me though, we could make that a thing in Guix, though for consistency 'target-x86-32?' would need to be renamed to 'target-ia32?' (I don't think the original casing and hyphenation is important for procedure names). I don't see the point of going for i686 -- AFAIK, Guix might as well have chosen i586 as a minimal supported version, and if it weren't for 32-bit seemingly being phased out, there might be a i786 eventually and Guix might eventually require i786 -- the mention of a particular microarchitecture doesn't seem relevant to me. Greetings, MAxime.
Maxime Devos <maximedevos@telenet.be> skribis: > Going by > https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html > , the official name is IA-32, not IA32. > > IA-32 sounds nice to me though, we could make that a thing in Guix, > though for consistency 'target-x86-32?' would need to be renamed to > 'target-ia32?' (I don't think the original casing and hyphenation is > important for procedure names). We could make that change, yes. (I think this is secondary compared to the change you proposed to make, which is to rename ‘i686-linux’ (the variable) to something else. I think the variable name must match the system type, and the system type is non-negotiable because it’s what lets Guix distinguish between derivations for two different hardware platforms.) Ludo’.
diff --git a/doc/guix.texi b/doc/guix.texi index 20abfee772..a24278e431 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -182,6 +182,7 @@ Weblate} (@pxref{Translating Guix}). * System Configuration:: Configuring the operating system. * Home Configuration:: Configuring the home environment. * Documentation:: Browsing software user manuals. +* Platforms:: Defining platforms. * Installing Debugging Files:: Feeding the debugger. * Using TeX and LaTeX:: Typesetting. * Security Updates:: Deploying security fixes quickly. @@ -405,6 +406,11 @@ Defining Services * Shepherd Services:: A particular type of service. * Complex Configurations:: Defining bindings for complex configurations. +Platforms + +* platform Reference:: Detail of platform declarations. +* Supported Platforms:: Description of the supported platforms. + Installing Debugging Files * Separate Debug Info:: Installing 'debug' outputs. @@ -41140,6 +41146,101 @@ reader,, info-stnd, Stand-alone GNU Info}) and its Emacs counterpart bindings to navigate manuals. @xref{Getting Started,,, info, Info: An Introduction}, for an introduction to Info navigation. +@node Platforms +@chapter Platforms + +The packages and systems built by Guix are intended, like most computer +programs, to run on a CPU with a specific instruction set. Those +programs are often also targeting a specific kernel and system library. +Those constraints are captured by Guix in @code{platform} records. + +@menu +* platform Reference:: Detail of platform declarations. +* Supported Platforms:: Description of the supported platforms. +@end menu + +@node platform Reference +@section @code{platform} Reference + +@deftp {Data Type} platform +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_node/Specifying-Target-Triplets.html, +GNU triplet}, as a string. 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. It can be for instance +@code{"aarch64-linux"} or @code{"armhf-linux"}. 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}). + +@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"}. + +@end table +@end deftp + +@node Supported Platforms +@section Supported Platforms + +@defvr {Scheme Variable} armv7-linux +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. +@end defvr + +@defvr {Scheme Variable} powerpc-linux +Platform targeting PowerPC 32 bits CPUs running GNU/Linux. +@end defvr + +@defvr {Scheme Variable} powerpc64le-linux +Platform targeting PowerPC 64 bits little endian CPUs running GNU/Linux. +@end defvr + +@defvr {Scheme Variable} riscv64-linux +Platform targeting RISC-V 64 bits CPUs running GNU/Linux. +@end defvr + +@defvr {Scheme Variable} i686-linux +Platform targeting x86 CPUs running GNU/Linux. +@end defvr + +@defvr {Scheme Variable} x86_64-linux +Platform targeting x86 64 bits CPUs running GNU/Linux. +@end defvr + +@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. +@end defvr + +@defvr {Scheme Variable} hurd +Platform targeting x86 CPUs running GNU/Hurd. +@end defvr + @node Installing Debugging Files @chapter Installing Debugging Files @@ -41879,7 +41980,7 @@ connection between a GNU triplet (@pxref{Specifying Target Triplets, GNU configuration triplets,, autoconf, Autoconf}), the equivalent @var{system} in Nix notation, the name of the @var{glibc-dynamic-linker}, and the corresponding Linux architecture -name if applicable. +name if applicable (@pxref{Platforms}). Once the bootstrap tarball are built, the @code{(gnu packages bootstrap)} module needs to be updated to refer to these binaries on the
* doc/guix.texi ("Platforms"): New chapter. ("Porting"): Link it. --- doc/guix.texi | 103 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 102 insertions(+), 1 deletion(-)