Skip to content

Commit 8f7d9a8

Browse files
sjg20sjg20
committed
Support os-release information
It is useful to have some information about an OS, e.g. to present to the user in a menu. Create a definition for this, making use of the os-release specification. Add a note into the usage section about this. Co-developed-by: Claude <[email protected]> Signed-off-by: Simon Glass <[email protected]>
1 parent a84852a commit 8f7d9a8

File tree

3 files changed

+320
-2
lines changed

3 files changed

+320
-2
lines changed

‎source/chapter2-source-file-format.rst‎

Lines changed: 310 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,6 +168,7 @@ the '/images' node should have the following layout::
168168
o hash-1 {...}
169169
o hash-2 {...}
170170
o logo-info {...}
171+
o os-info {...}
171172
...
172173

173174
Mandatory properties
@@ -399,6 +400,11 @@ logo-info
399400
Contains information about the logo image, to help describe characteristics
400401
such as image dimensions.
401402

403+
os-info
404+
Contains information about the OS image, to help identify it. This
405+
can be useful for displaying a menu for the user. The information is
406+
generally only useful for image nodes which contain an OS.
407+
402408
.. index:: Hash nodes
403409

404410
Hash nodes
@@ -613,6 +619,310 @@ background
613619

614620
.. _os_info:
615621

622+
OS Information node
623+
-------------------
624+
625+
The 'os-info' node provides information about an image, specifically targeting
626+
images which constitute an operation system. The properties are based on the
627+
freedesktop.org os-release specification [osrelease]_.
628+
629+
The 'os-info' node has the following structure::
630+
631+
o os-info
632+
|- ansi-color = "OS console presentation color"
633+
|- architecture = "OS userspace architecture"
634+
|- bug-report-url = "OS bug report URL"
635+
|- build-id = "OS build identifier"
636+
|- confext-level = "OS configuration extensions level"
637+
|- cpe-name = "OS Common Platform-Enumeration name"
638+
|- default-hostname = "OS default hostname"
639+
|- documentation-url = "OS documentation URL"
640+
|- home-url = "OS homepage URL"
641+
|- id = "OS identifier"
642+
|- id-like = "OS inherited from", ...
643+
|- image-id = "OS image identifier"
644+
|- image-version = "OS image version"
645+
|- logo-name = "OS logo icon name"
646+
|- name = "OS name"
647+
|- pretty-name = "OS pretty name"
648+
|- privacy-policy-url = "OS privacy policy URL"
649+
|- release-type = "OS release type"
650+
|- support-end = "OS support end date"
651+
|- support-url = "OS support URL"
652+
|- sysext-level = "OS system extensions level"
653+
|- variant = "OS variant"
654+
|- variant-id = "variant identifier"
655+
|- vendor-name = "OS vendor name"
656+
|- vendor-url = "OS vendor URL"
657+
|- version = "OS version"
658+
|- version-codename = "OS version codename"
659+
|- version-id = "OS version identifier"
660+
661+
Mandatory properties
662+
~~~~~~~~~~~~~~~~~~~~
663+
664+
If an 'os-info' node is included, these properties are mandatory:
665+
666+
name
667+
A string identifying the operating system, without a version component,
668+
and suitable for presentation to the user.
669+
670+
Examples::
671+
name = "Fedora Linux";
672+
673+
name = "Ubuntu";
674+
675+
version
676+
A string identifying the operating system version, excluding any OS name
677+
information, possibly including a release code name, and suitable for
678+
presentation to the user.
679+
680+
Examples::
681+
version = "32 (Workstation Edition)";
682+
683+
version = "20.04.1 LTS (Focal Fossa)";
684+
685+
Conditionally mandatory property
686+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
687+
688+
color
689+
A suggested presentation color when showing the OS name on the console, in
690+
the format 0x00bbggrr. This is mandatory if 'ansi-color' is provided.
691+
692+
Optional properties
693+
~~~~~~~~~~~~~~~~~~~
694+
695+
ansi-color
696+
A suggested presentation color when showing the OS name on the console.
697+
This should be specified as string suitable for inclusion in the ESC [ m
698+
ANSI/ECMA-48 escape code for setting graphical rendition. See also color.
699+
700+
Examples::
701+
// red
702+
ansi-color = "0;31";
703+
704+
// light blue
705+
ansi-color = "1;34";
706+
707+
// Fedora blue
708+
ansi-color = "0;38;2;60;110;180";
709+
710+
architecture
711+
A string that specifies the CPU architecture the userspace binaries
712+
require.
713+
714+
Examples::
715+
architecture = "x86_64";
716+
717+
architecture = "arm64";
718+
719+
bug-report-url
720+
Link to the main bug reporting page for the operating system, if there
721+
is one.
722+
723+
Example::
724+
bug-report-url = "https://bugzilla.redhat.com/";
725+
726+
build-id
727+
A string uniquely identifying the system image originally used as the
728+
installation base. In most cases, VERSION_ID or IMAGE_ID are updated
729+
when the entire system image is replaced during an update. BUILD_ID may
730+
be used in distributions where the original installation image version
731+
is important.
732+
733+
Example::
734+
build-id = "2013-03-20.3";
735+
736+
confext-level
737+
A lower-case string identifying the operating system configuration
738+
extensions support level, used to specify extension-release
739+
compatibility.
740+
741+
Examples::
742+
confext-level = "2";
743+
744+
confext-level = "15.14";
745+
746+
cpe-name
747+
A CPE name for the operating system, in URI binding syntax, following
748+
the Common Platform Enumeration Specification.
749+
750+
Example::
751+
cpe-name = "cpe:/o:fedoraproject:fedora:17";
752+
753+
default-hostname
754+
A string specifying the hostname if hostname(5) is not present and no
755+
other configuration source specifies the hostname.
756+
757+
Example::
758+
default-hostname = "localhost";
759+
760+
documentation-url
761+
Link to the main documentation page for this operating system.
762+
763+
Example::
764+
documentation-url = "https://docs.fedoraproject.org/";
765+
766+
home-url
767+
Link to the homepage for the operating system, or alternatively a
768+
homepage of the specific version of the operating system.
769+
770+
Example::
771+
home-url = "https://fedoraproject.org/";
772+
773+
id
774+
A lower-case string identifying the operating system, excluding version
775+
information and without spaces or other characters outside of 0-9, a-z,
776+
".", "_" and "-".
777+
778+
Examples::
779+
id = "fedora";
780+
781+
id = "debian";
782+
783+
id-like
784+
A list of operating system identifiers in the same syntax as id. This should
785+
list identifiers of operating systems that are closely related to the local
786+
operating system in regards to packaging and programming interfaces.
787+
788+
Examples::
789+
id-like = "rhel", "centos", "fedora";
790+
791+
id-like = "debian";
792+
793+
image-id
794+
A lower-case string identifying a specific image of the operating system.
795+
796+
Examples::
797+
image-id = "vendorx-cashier-system";
798+
799+
image-id = "netbook-image";
800+
801+
image-version
802+
A lower-case string identifying the OS image version.
803+
804+
Example::
805+
image-version = "33";
806+
807+
image-version = "47.1rc1"
808+
809+
logo-name
810+
A string specifying the name of an icon suitable to represent this
811+
operating system in a logo format. The file for the logo should be
812+
available within the root file system used by the operating system.
813+
814+
See the Icon Theme Specification [icontheme]_.
815+
816+
Examples::
817+
logo-name = "fedora-logo-icon";
818+
819+
logo-name = "ubuntu-logo";
820+
821+
pretty-name
822+
A pretty operating system name in a format suitable for presentation to
823+
the user. May or may not contain a release code name or OS version of
824+
some kind.
825+
826+
Examples::
827+
pretty-name = "Fedora Linux 32 (Workstation Edition)";
828+
829+
pretty-name = "Ubuntu 20.04.1 LTS";
830+
831+
privacy-policy-url
832+
Link to the privacy policy page for the operating system, if there is
833+
one.
834+
835+
Example::
836+
privacy-policy-url = "https://fedoraproject.org/wiki/Legal:PrivacyPolicy";
837+
838+
release-type
839+
Describes the release type of the operating system. May be one of:
840+
stable, lts, development, experiment.
841+
842+
Examples::
843+
release-type = "stable";
844+
845+
release-type = "lts";
846+
847+
release-type = "development";
848+
849+
support-end
850+
The time at which support for this version of the OS ends. When
851+
specified, this should be in 64-bit Unix time format, i.e. the number of
852+
seconds since 1.1.1970, 0:0:0.
853+
854+
Example::
855+
support-end = /bits 64/ <1756212516>;
856+
857+
support-url
858+
Link to the main support page for the operating system, if there is one.
859+
860+
Example::
861+
support-url = "https://fedoraproject.org/wiki/Communicating_and_getting_help";
862+
863+
sysext-level
864+
A lower-case string identifying the operating system extensions support
865+
level, used to specify extension-release compatibility.
866+
867+
Examples::
868+
sysext-level = "2";
869+
870+
sysext-level = "15.14";
871+
872+
variant
873+
A string identifying a specific variant or edition of the operating
874+
system suitable for presentation to the user.
875+
876+
Examples::
877+
variant = "Workstation Edition";
878+
879+
variant = "Server Edition";
880+
881+
variant-id
882+
A lower-case string identifying a specific variant or edition of the
883+
operating system.
884+
885+
Examples::
886+
variant-id = "workstation";
887+
888+
variant-id = "server";
889+
890+
vendor-name
891+
The name of the operating system vendor.
892+
893+
Examples::
894+
vendor-name = "Fedora Project";
895+
896+
vendor-name = "Canonical Ltd.";
897+
898+
vendor-url
899+
Link to the vendor homepage.
900+
901+
Examples::
902+
vendor-url = "https://fedoraproject.org/";
903+
904+
vendor-url = "https://canonical.com/";
905+
906+
version-codename
907+
A lower-case string identifying the operating system release code name,
908+
excluding any OS name information or release version, and suitable for
909+
processing by scripts or usage in generated filenames.
910+
911+
Examples::
912+
version-codename = "focal";
913+
914+
version-codename = "jammy";
915+
916+
version-id
917+
A lower-case string identifying the operating system release, excluding
918+
any OS name information or release code name, and suitable for processing
919+
by scripts or usage in generated filenames.
920+
921+
Examples::
922+
version-id = "32";
923+
924+
version-id = "20.04";
925+
616926

617927
'/configurations' node
618928
----------------------

‎source/chapter3-usage.rst‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -138,8 +138,12 @@ Boot menu
138138
~~~~~~~~~
139139

140140
In some cases it may desirable to show a menu of boot options and wait for the
141-
user to select one. The :ref:`logos_prop` property provides logos which can be
142-
shown in the case of a graphical menu.
141+
user to select one. In this case the :ref:`os_info` provides information which
142+
can be presented to the user to aid this choice. The :ref:`logos_prop` property
143+
provides logos which can be shown in the case of a graphical menu.
144+
145+
The OS Information can also be useful for a fully automated boot, such as to
146+
select a particular version of the OS.
143147

144148
The bootloader must support at least logos in BMP format, if it supports a
145149
graphical display.

‎source/references.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,7 @@ References
1313
https://libpng.org/pub/png/spec/1.2/PNG-Contents.html
1414
.. [svg] Scalable Vector Graphics
1515
https://www.w3.org/TR/SVG11/
16+
.. [osrelease] os-release - Operating system identification
17+
https://www.freedesktop.org/software/systemd/man/latest/os-release.html
18+
.. [icontheme] Icon Theme Specification
19+
https://standards.freedesktop.org/icon-theme-spec/latest

0 commit comments

Comments
 (0)