Recipes

A recipe defines one of the basic component types of the LFSBuilder tool: builders and components. It is composed by a directory and a file both named after the component name. Apart from that, you can include a functions.py optional file that modify the way some core functions work with the component, or your own extra functions. As an example, under the recipes/builders/toolchain directory you can find the toolchain.yaml and functions.py files.

Recipes represent a customizable extra layer on top of the core functions of the LFSBuilder tool that allows you to customize your final system without the need of modifying its code. It also isolates issues because if a component is broken due to a bad configuration or function definition, it will only affect that component.

Properties

The ${component}.yaml file is mandatory, and its minimum content is the name property. This attribute defines the value of several internal variables used by the LFSBuilder tool. You can also provide the base_component property to define the type of component you are defining. The options available for this property are:

  • SystemConfigurationComponent: this component type only modifies the final system in some way (generating files, directories, setting permissions…) but is not built using the compilation steps.
  • CompilableComponent: this component is built using the configure/make tools.

You can also define your own properties. They will be available at build time in the component_data_dict dictionary.

Available properties

  • package_name: name of the source code tarball file.
  • previous: steps to be performed before starting the build process. Patches are applied before this step, right after uncompressing the source code.
  • configure: commands to configure the component. It replaces the configure commands from the book.
  • configure_options: extra options for the configure command. Added after books’ provided options.
  • make: command that build the component. Usually make.
  • make_options: extra options for the make command.
  • install: command to run for installing the built libraries and binaries. Usually make install.
  • install_options: extra options for the previous command.
  • test: commands to run instead of make test or make check.
  • test_options: extra options for the previous command.
  • include_tests: boolean parameter that enables/disables test execution.
  • post: steps to be run after the build process.
  • env_PATH_value: custom value for the PATH environment variable that will be used to build all the components that belong to a specific builder.
  • book: the defined component belongs to that book. Valid values: lfs, blfs and custom.
  • run_as_username: username that will build the component.
  • run_into_chroot: whether a component should be build from inside the chroot or not.
  • version: component version to build.
  • comment_out_list: list of commands in the component’s XML files that will be commented out.
  • components_to_build: ordered list of components to build for a desired builder if the CUSTOM\_COMPONENTS\_TO\_BUILD property is true.
  • component_substitution_list: sustitutions to be performed in the component’s XML file.
  • chapters_list: list of book chapters that include each build step of the Linux from Scratch book: toolchain, system and configuration.
  • disable_commands_list: commands that will be ignored by the LFSXmlParser class, and therefore won be run.
  • runscript_cmd: command used to run a compilation script.

Functions

The functions.py file allows you to customize the way some core functions interact with a component. As an example. the kernel component overwrites the run_previous_steps core function to, apart from running the core logic, copy the kernel configuration file that will be used to compile it. The content of the functions.py file for the kernel component is:

import os
import sys

import config
import tools

def run_previous_steps(component_data_dict, parent_function):

    # Call parent function
    parent_function()

    print("Copying custom \'.config\' file")
    filename = os.path.join(component_data_dict["lfsbuilder_src_directory"],
                            "recipes",
                            "components",
                            "kernel",
                            "files",
                            component_data_dict["kernel_config_filename"])

    tools.copy_file(filename,
                    os.path.join(component_data_dict["extracted_directory"], ".config")
    )

As shown above, that component defines the kernel_config_filename custom property, which contains the name of the configuration file to be used. All the functions that can be overwritten always receive the same parameters:

  • component_data_dict: a Python dictionary with the current values of the component metadata (name, version, commands to run…). You can modify these values from a custom function.
  • parent_function: references the core function that is being overwriten. From a object oriented programming point of view, it allows you to run the super class function.

The list of the core functions that can be customized is present below

Available functions

  • apply_patches: looks and apply a source code patch.
  • build: required steps to build components of a specific builder.
  • extract_source_code: defines how a source code tarball is extracted.
  • get_components_to_build_list: returns the list of components that a specific builder builds. This function can be used to modify that list, for example depending on the value of a configuration property.
  • modify_xmlfile: modifies a component or builder XML file before parsing it.
  • run_post_steps: steps to run after a component is build and installed.
  • run_previous_steps: steps run right after extracting the component source code and before starting the build process.
  • set_attributes: allows you to modify the component attributes before starting the build process.