How to Override Standard Files in a Yocto Project

Iain Menzies-Runciman

So you have built your Yocto Project distribution but you want to change the contents of a standard file.

In this example we are going to create our own file /etc/issue, but this applies for any file on the system.

Background

Files like /etc/issue and /etc/motd are typical ways that a system administrator can give information to users of a system every time they login.

The contents of /etc/issue are displayed by the shell before the user logs into a system. This can therefore be used for things like:

  • Displaying login instructions (Useful for training systems)
  • Displaying legal warnings (Useful as a warning for systems with restricted access)
  • General information about the system

By default this will just contain the name of the Distribution you used to build the image (which was defined in DISTRO variable in your local.conf)

The contents of /etc/motd are displayed in the shell after the user has logged in. This was typically used to inform users about things that are relevant to active authorised users, such as informing them about upcoming outages. This is probably not as useful in a Yocto based system (or at least, I have never needed to change it!). By default it is blank and I am quite happy to keep it that way.

Finding the Recipe

In order to override the file, we need to find out the recipe that we need to change. There is a little publicised tool in Yocto that is actually very useful – oe-pkgdata-util

$ oe-pkgdata-util -h
oe-pkgdata-util: error: the following arguments are required: <subcommand>
usage: oe-pkgdata-util [-h] [-d] [-p PKGDATA_DIR] <subcommand> ...

OpenEmbedded pkgdata tool - queries the pkgdata files written out during do_package

options:
  -h, --help            show this help message and exit
  -d, --debug           Enable debug output
  -p PKGDATA_DIR, --pkgdata-dir PKGDATA_DIR
                        Path to pkgdata directory (determined automatically if not specified)

subcommands:
  lookup-pkg            Translate between recipe-space package names and runtime package names
  list-pkgs             List packages
  list-pkg-files        List files within a package
  lookup-recipe         Find recipe producing one or more packages
  package-info          Show version, recipe and size information for one or more packages
  find-path             Find package providing a target path
  read-value            Read any pkgdata value for one or more packages
  glob                  Expand package name glob expression
Use oe-pkgdata-util <subcommand> --help to get help on a specific command

We are going to use the find-path option.

$ oe-pkgdata-util find-path /etc/issue
base-files: /etc/issue

So now we know that it is the base-files recipe that installs the /etc/issue so let’s find the recipe.

On my Scarthgap release, it is located at poky/meta/recipes-core/base-files/base-files_3.0.14.bb with the actual image file at poky/meta/recipes-core/base-files/base-files/issue.

Checking the recipe we can see a SRC_URI that includes file://issue along with a do_install_basefilesissue() section that has

     install -m 644 ${WORKDIR}/issue* ${D}${sysconfdir}

So we are definitely looking at the right recipe.

Note: Normally, the file would be installed using a do_install() function, so for any file other than /etc/issue, look for the do_install() function to check.

Overriding the File

Now, it would be very easy to just edit poky/meta/recipes-core/base-files/base-files/issue and add the content we want.

DO NOT DO IT

It really is a bad idea to edit files in any of the supplied layers as these will get over-written when you next upgrade your Yocto release and/or layer and all your hard work will be lost.

Create an Append file

In one of your own layers your should create a .bbappend file for the recipe. So for us, I am going to create two files

  • meta-my_distro/recipes-support/overrides/base-files_%.bbappend
  • meta-my_distro/recipes-support/overrides/files/issue

In my copy of the issue file I have just created, I am going to put the contents I want displayed

Welcome to my Yocto Demo system.
To login and explore, use
Username: yocto
Password: IsTheBest

My append file is simply going to be:

FILESEXTRAPATHS:prepend := "${THISDIR}/files:"

What this will do is put my local files directory in the search path before anything else which means that BitBake will pick up my copy of issue instead of the one supplied by the base-files recipe.

Side Note for /etc/issue file only

The /etc/issue is a special case, and this section only applies to the issue file. For any other file, you are probably done and can just build your image as normal.

Going back to the base-files recipe, you may notice that there are several things going on in the do_install_basefilesissue() function. This is non-standard install function and only applies to the issue file, as normally files get put into the image using the do_install() function.

This function is also appending the name of the distribution to the end of the /etc/issue file. If you are happy with that – all is good and you are done.

If you do want to change the default appending of the distro name, then looking through the rest of the recipe, you will find a line

BASEFILESISSUEINSTALL ?= "do_install_basefilesissue"

What this means is you could always write own install function in the .bbppend file and then in one of your conf files (e.g. local.conf or distro.conf) give a value to the BASEFILESISSUEINSTALL variable, e.g.

BASEFILESISSUEINSTALL = "do_install_myfilesissue"