Using the Honeywell Product Independent Buildroot Layer
=======================================================

The Honeywell Product Independent Buildroot Layer is designed for use with a Product Specific
Buildroot layer to create a bespoke Linux Kernel, root file system, and bootloader using the
Buildroot Layered Customisation mechanisms described in section 9 of the Buildroot Manual
(https://buildroot.org/downloads/manual/manual.html).

The layered structure allows the core Buildroot components, the Honeywell specific product
independent modifications, and the product specific modifications to be maintained separately. This
provides decoupling of these layers to simplify reuse and avoid multiple product specific Buildroot
and kernel variants.

The product independent layer is packaged as a separate repository that will be referenced by individual
product build processes, for example by inclusion as a sub-module in individual product repositories.

When new CVE issues or Buildroot upgrades are identified they can be addressed by modification to the
product independent layer, making the resolution available to all products that use it.

The Honeywell Product Independent Buildroot Layer consists of:
  the unmodified Buildroot environment.
  Honeywell specific modifications that are not specific to any produce. This includes patches
  to address CVE issues identified in the packages used by Buildroot.

A Product Specific Layer consists of:
  the product specific configuration definitions for Buildroot, the kernel, the device tree, and the
  bootloader;
  any product hardware or functionality specific kernel, bootloader, and package patches; and
  any additional packages that may be required by the product.

The Honeywell specific product independent modifications and the Product Specific Layer are
integrated into the Buildroot build process using the br2-external mechanism described in section
9.2 of the Buildroot Manual.

Further decoupling from the Buildroot core is achieved by building out-of-tree as defined in
section 8.5 of the Buildroot Manual.

The Product Specific Buildroot Layer
====================================

The product Specific Buildroot Layer should be constructed as follows:

  <product>_buildroot_tree
    external.desc
      This file describes the Product Specific br2-external tree. It must include a "name" definition
      that is used to set the BR2_EXTERNAL_$(NAME)_PATH to the absolute path that can be used to refer
      to the components of the layer.
    Config.in
    external.mk
      These files (which may each be empty) can be used to define product specific package recipes or
      other custom configuration options or make logic as described in section 9.2.1 of the Buildroot
      manual.

    board
      <product variant>
        busybox-config
          busybox.config
            This file contains any product specific BusyBox configuration that may be required.
          Alternative configuration files can be added here, for example separate configurations for
          development and release builds.
        linux-config
          kernel.config
            This file contains the product specific Linux kernel configuration
          <product variant>.dts
            This file contains the product specific Device Tree configuration
          Alternative Linux and/or DTS configuration files can be added here, for example separate
          configurations for development and release builds.
        patches
          This directory contains product hardware or functionality specific kernel, bootloader, and package
          patches. The patches for individual components are held in sub-directories with names that match
          associated package name as described in section 9.8 of the Buildroot Manual.
        rootfs-overlay
          This directory contains the Buildroot Root File system overlay tree. The contents of this
          directory will be recursively copied onto the generated root file system during the build process
          as described in section 9.5 of the Buildroot Manual.
        <product>-build-script.sh
          Any product specific build scripts, such as post-build scrips as described in section 9.5 of the
          Buildroot Manual, are added here.

    configs
      <product>_defconfig
        This file defines the Buildroot configuration for the product. It contains the normal Buildroot
        configuration information and can access the Honeywell Product Independent Buildroot Layer components
        using the BR2_EXTERNAL_HONEYWELL_BUILDROOT_PATH variable and the Product Specific Buildroot Layer
        components using the BR2_EXTERNAL_$(NAME)_PATH (the $(NAME) portion is replaced by the "name"
        definition in the external.desc file described above). For example, if the name is defined
        as PRODUCT_A:
          BR2_GLOBAL_PATCH_DIR="$(BR2_EXTERNAL_HONEYWELL_BUILDROOT_PATH)/cve_patches/ $(BR2_EXTERNAL_PRODUCT_A_PATH)/patches/"
          BR2_ROOTFS_OVERLAY="$(BR2_EXTERNAL_PRODUCT_A_PATH)/board/<product variant>/rootfs-overlay/"
          BR2_ROOTFS_POST_IMAGE_SCRIPT="$(BR2_EXTERNAL_PRODUCT_A_PATH)/board/<product variant>/post-image.sh"
          BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE="$(BR2_EXTERNAL_PRODUCT_A_PATH)/board/<product variant>/linux-config/kernel.config"

      Alternative configuration files can be added here, for example separate configurations for
      development and release builds.

The layer can also use any of the additional configuration features described in section 9.2.1 of the
Buildroot manual.

The Build Process
=================

The build process requires direct access to a clone of the Honeywell Product Independent Buildroot Layer.
This can be achieved by: cloning the Honeywell Product Independent Buildroot Layer near to, or directly into, the
product's build tree (the cloning could be performed by the product's build process makefile) or including the
Honeywell Product Independent Buildroot Layer as a sub-module of the product's repository and performing a
recursive clone.

Build Instructions

  1) Create an out-of-tree build directory
       mkdir output
  2) Change to the build directory:
       cd output
  3) Configure Buildroot for an out-of-tree build. In the following example: <PIBL path> is either an
     absolute or relative path to the Honeywell Product Independent Buildroot Layer; and <relative PSBL path>
     is the path to the Product Specific Buildroot Layer which MUST be specified as relative to the
     buildroot subdirectory of the Honeywell Product Independent Buildroot Layer.
       make O=$PWD -C <PIBL path>/buildroot \
          BR2_EXTERNAL=../honeywell-buildroot-tree:<relative PSBL path>/<product>_buildroot_tree \
          <product>_defconfig
  4) Perform the build:
       make

The build will now run to completion without further user intervention and the build products are
created in the output/images directory.

The Buildroot Download Directory
================================

During the build process, Buildroot will download all the source files that are required to build
the configured software. By default these files will be downloaded to a dl subdirectory in the
buildroot sudirectory of the Honeywell Product Independent Buildroot Layer.

An alternative location for the download files can be specified using the BR2_DL_DIR environment
variable as defined in section 8.13.4 of the Buildroot manual. This can be used to reference a
directory that already contains all the required files to avoid repeated downloads.
