[bug#57643] [PATCH 0/3] Document the image API.

[Maxime Devos]

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.

OpenPGP_0x49E3EE22191725EE.asc
Description: OpenPGP public key

OpenPGP_signature
Description: OpenPGP digital signature