Chromium OS Recovery Kernels

All about image resources in recovery images

The code in messages.sh depends on a collection of PNG files stored in /etc/screens in the initramfs file system. The message images are generated by the make_images script. Other images are generated by the make_images script, or supplied by the chromeos-assets package.

Simple instructions if you just want to create images for review:

1. Run this command from inside the chroot: ./make_images
2. Point your browser at the ‘screens’ subdirectory in your sources (this should have been created in step 1.)
3. Review the content.

Note that the work must be done inside the chroot, in order to guarantee correct font selection.

Contents of /etc/screens, and what it's for

• screens/constants.sh
  This is a small shell fragment sourced from messages.sh. It contains parameter definitions relating to the image files.

  The shell code is generated automatically by the make_images script.

• screens/<locale>/<msgname>.png
  These are the localized individual message files displayed during recovery. is a standard locale name (e.g. “en-US”, “fr”, “zh-CN”, etc.). is the name used in “messages.sh”.

  The message source text for for each “.png” file can be found in localized_text/<locale>/<msgname>.txt.

• screens/progress_box.png
screens/progress_increment.png
  Images used for the progress bar in progress_bar. The progress_box image shows a progress bar at 0% completion. The progress_increment image is a column of pixels corresponding to a 1% increment.

  This file is generated by the make_images script.

• screens/boot_message.png
  This is a background image designed to frame all messages. The image shows a Chrome or Chromium logo at the top, with horizontal lines above and below the area for the messages.

  This file comes from the chromeos-assets package; see the ebuild for details.

• screens/spinner/*.png
  While we're installing the recovery image, we present a spinner animation. These files represent the individual frames of that animation.

  This file comes from the chromeos-assets package; see the ebuild for details.

Adding a new locale

All available locales are currently stored under localized_text; however, not all locales are included in the final output. Each Chrome computer is manufactured to be used in a specific locale; the ‘screens’ locale content is only generated for the locales to which units could actually be shipped.

The dictionary of supported locales and their associated fonts is stored in a global setting at the top of make_images. A new locale can be added by creating a mapping for the locale to an appropriate font. The list of font families assigned to a locale here should typically match the families used in Chrome's UI; see the IDS_UI_FONT_FAMILY_CROS string in Chrome.

Note that you should not accept on faith that simply updating the list of supported locales is enough to produce a good set of images. A number of things may go wrong:

• The text layout may not wrap lines properly, causing text to be truncated or otherwise mis-formatted.
• Text may be truncated for lack of space.
• Writing systems that display right-to-left are untested, and may not render properly. Most notable in this class are ‘ar’ (Arabic) and ‘iw’ (Hebrew). Give these special attention when/if they're added.
• Fonts may be missing, incomplete, or just plain illegible.
• The default font may or may not render the text correctly for the locale.
• The translators didn't have access to a Chromebook to observe the messages in context, and may have mis-translated some messages.
• Translators are human, and sometimes make mistakes.

When adding a new locale, you should at minimum visually inspect the images to confirm that it looks like the original text. If you can, it would be wise to find someone familiar with the target language to confirm there are no glaring errors.

How to generate content

All necessary graphic image content is generated automatically in the ebuild; if you intend to test simply by booting a device, you don‘t need to do anything. However, it’s a good idea to generate images manually and then use a browser to display the images. Below are the commands for the most likely use cases.

NOTE: To get proper font selection, the commands must be run inside the chroot.

To regenerate graphic images and messages for all supported locales:

./make_images

To regenerate graphic images and messages for specific locales, such as for locales not in the current supported list:

./make_images localized_text screens <locale> [ <locale> ... ]

This command will use the default font for unknown locales; this may or may not be right.

How to override user interface

The user interface for recovery program was made primarily for systems with display. For headless (without display) devices, you may need to override the console output and images (ply-image) to serial console and other peripherals like LED or speaker.

To do this, you have to:

• Override the virtual/chromeos-bsp-initramfs with your own version
• Install additional files to /var/lib/initramfs/recovery
• Override the variables and functions defined in defaults.sh by /var/lib/initramfs/recovery/lib/board_recovery.sh

Note we only allow overriding variables and functions in defaults.sh. All other variables and functions are reserved internally and may change in future.