How To Build and Use an RFS Overlay with Factory

Table of Contents

Summary

This HOWTO covers the process for creating an RFS Overlay to add custom files to a Factory generated target RFS.

NOTE: This HOWTO assumes that the Desktop Factory has been configured and built prior to adding custom files via an RFS Overlay. If these Factory configuration and build steps have not been completed yet, please do so before continuing with this HOWTO.

Automatically adding custom files to a Factory-generated RFS during the BSP/SDK build process can be broken up into two distinct tasks each of which is covered within this HOWTO:

  1. Create RFS Overlay Archive
    1. Create Overlay Directory Structure
    2. Add Custom Files
    3. Archive the Overlay
  2. Integrate RFS Overlay with Factory
    1. Copy Overlay Archive to an Accessible Location
    2. Enable RFS Overlay in Workorder
    3. Clean and Rebuild RFS and Installer

RFS Overlay Introduction

You can create and use an RFS content archive to overlay an archive on top of your target's RFS. New content contained within this RFS overlay is added to the RFS, while content already existing in the RFS is overwritten by the custom files included in the overlay.

During the BSP/SDK build, as each selected package is built, it is then typically installed to the target RFS working directory (build_[arch]-timesys-linux-[libc]), as necessary. In this manner, the target's RFS is gradually built up until it contains all the necessary components for the target's running system. This RFS working directory is the location that the RFS Overlay is applied prior to the RFS image creation. The Desktop Factory buildsystem will change directory into this RFS working area and explode the archive on top of the existing contents. The RFS images included in the BSP/SDK are then created from this RFS working directory.

NOTE This must be a static tarball that exists prior to invoking the build system. The files included in the RFS Overlay archive need to be organized with respect to the root directory (/) of the target's RFS.

Create RFS Overlay Archive

Create Overlay Directory Structure

The first step to creating an RFS Overlay archive is setting up a directory structure to add custom files to. This can be done in any location, but for purposes of this HOWTO, this will be completed within the user-created directory src/local/ in the top-level Factory directory. A temporary directory can be created within the src/local/ directory as a location that will be analogous to the root (/) of the target RFS with the following command run from the top-level Factory directory:

mkdir -p src/local/overlay_root_tmp/

From here, any additional directories can be created as they would be seen from the root directory of the target RFS. For example, if a custom password (etc/passwd) or modified fstab (etc/fstab) file is to be added to the overlay, the etc/ directory would need to be created within the src/local/overlay_root_tmp/ directory created above.

mkdir -p src/local/overlay_root_tmp/etc/

The directory structure here is what will be applied to the target RFS working directory prior to the creation of the RFS images.

Add Custom Files

Next we add any files we need to include in the target RFS to the appropriate location in the src/local/overlay_root_tmp/ directory. In this example, a passwd file that was created with the passwd command executed on the booted target board is copied from a mounted NFS along with the fstab which was modified on the target system as well.

cp -t src/local/overlay_root_tmp/etc/ /mnt/NFS/etc/passwd /mnt/NFS/etc/fstab

In this case, the etc/passwd will simply be added to the target's RFS with the use of the overlay, though since the etc/fstab file already exists in the target RFS working directory, that original file will be overwritten with the fstab included in the overlay archive (the modified one copied from the running target system). In this manner, we can both replace or add new files to the target RFS with the use of the RFS overlay archive.

Archive the Overlay

Once the overlay_root_tmp/ directory is laid out and populated as needed, the contents of this directory must be archived. It is important to archive the contents of the directory as opposed to the directory itself. This is because the src/local/overlay_root_tmp/ directory is intended to act as a placeholder for the root (/) of the target RFS. In order to accomplish this, we first change directory to src/local/overlay_root_tmp/ prior to archiving it's contents.

cd src/local/overlay_root_tmp/ 
tar -czvf ../overlay.tar.gz ./*

This generates the overlay.tar.gz tar archive (compressed with gzip) in the src/local/ directory that can now be utilized with Factory's RFS Overlay facility.

Integrate RFS Overlay with Factory

Once the RFS overlay archive has been created (or obtained), it can be put to use within Factory to expand or otherwise modify the contents of the target system's RFS. The option to use the overlay is enabled in the Factory workorder as explained in the steps below.

Copy Overlay Archive to an Accessible Location

If the RFS overlay archive has been not been created from the steps listed above, ensure it is copied to a location accessible to the Desktop Factory (where elevated privileges are not needed).

Enable RFS Overlay in Workorder

The RFS Overlay is enabled by listing the overlay tar archive file with a fully qualified path in the Factory workorder. This can be done via the menuconfig interface.

  1. Run make menuconfig from the top-level Factory directory
  2. Navigate to Target Configuration > Build RFS > RFS overlay tarball
  3. Enter overlay tarball file and location - in our example, file://$(BASE_DIR)/src/local/overlay.tar.gz
  4. Exit menuconfig and save workorder

    Now that Factory knows that an RFS overlay archive is in use and where to find it, the only thing left to do is clean and regenerate the target RFS and Installer.

Clean and Rebuild RFS and Installer

In order to rebuild the RFS images, the rfs build state in Factory needs to be reset. This is accomplished with the rfs-distclean make target, run from the top level Factory directory.

make rfs-distclean

With the RFS reset and ready to be rebuilt, the following can be run from the top-level Factory directory to regenerate the RFS images and SDK Installer:

make rfs && installers

or simply running "make" will automatically rebuild both the RFS images and the SDK installer to reflect the modifications to the RFS based on the newly applied RFS overlay archive.