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

[Ludovic Courtès]

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’.