Build Map Reference Guide ¶

Table of Contents

Introduction ¶

A Build Map file is the main user-generated input to Fuze. It contains all of the information for Fuze to perform a build operation, including packaging.

Build Map Language ¶

Build maps are plain text files in JSON format. The various key:value pairs are comprised of strings, lists and dictionaries.

Fuze contains a format validator so that prior to any execution, the validity of the JSON itself (rather than the contents) is verified.

Build Map Sections ¶

The build map is divided into 4 main sections:

General: This is a loosely coupled section that provides some general information as well as the defines the build and packaging targets.
Variables: This section defines all variables that are known and used within the build map
Build: This section defines all of the build information, such as the CBE, build commands, build dependencies, etc
Packages: This section defines all of the packaging directions.

Here is an abbreviated view of the sections of a build map:

{
    "description": "",
    "product_name": "",
    "release_version": "",
    "build_targets": [],
    "package_targets": [],
    "variables": [],
    "build": {},
    "packages": {}
}

The description, product_name, release_version, build_targets, and package_targets are considered the General section.

General ¶

The key:value pairs described in this section are loosely coupled for convenience only. The General section does not execute.

`description`¶

A string value description of the build map file.

"description": "<any_text>"

`product_name`¶

A string value product name.

"product_name": "<any_text>"

Notes:

This field relates to Fuze searches on keyword product
Fuze creates a package repository for each unique product
The string value chosen is important for the naming of the builds and releases, and should be consistent across all like products. For example, if “firmware” is used for one build, and “fw” is used for another, Fuze has no way of knowing these may in reality be the same type of build.

`release_version`¶

A string value that defines the version of the product.

"release_version": "<version_text>"

Notes:

This field relates to Fuze searches on the keyword version
Although this is free form text, the recommendation is to use a major.minor scheme
An entry is required for advancing a build to a release.
The release_version shows up in the package file names, and Fuze appends the FuzeID to the it.

For example:

If the build map has "release_version": "4.8", the package name will look similar to:

<pkg_name>-v4.8.<FuzeID>.zip

`build_targets`¶

A list of string values that define the build target names of the product.

"build_targets": [
    "TARGET0",
    "TARGET1",
    ...
    "TARGETn"
]

Notes:

These targets apply only to the build section of the build map
The values in this list are used as arguments to the --targets command line option

`package_targets`¶

A list of string values that define the package target names of the product.

"package_targets": [
    "PACKAGE0",
    "PACKAGE1",
    ...
    "PACKAGEn"
]

Notes:

These targets apply only to the packages section of the build map
The values in this list are used as arguments to the --package, --add-packages, and --update-packages command line options

Fuze allows the user to create variables for convenience and substitution purposes. The variables section is marked with the variables keyword and contains a list of dictionaries that define the variable name and substitution.

The Variables section does not execute. However, when variables are created to be used in the “build” and “packages” sections, they must adhere to the format and language to whichever section, and hence workspace, they are applicable.

`variables`¶

A list of dictionaries. Each dictionary is comprised of variable name and value substitution, both of which are strings.

"variables": [
    {
    "name": "${VAR0}",
    "value": "<value>"
    },
    {
    "name": "${VAR1}",
    "value": "<value>"
    },
    ...
    {
    "name": "${VARn}",
    "value": "<value>"
    }
]

Notes:

name formats can be free-form strings, however, the format shown (i.e., ${VAR0}) is recommended to eliminate the chance of name collisions in a build map
value is any string, and can include paths. Paths must be of the form understood by target system on which the path substitution will occur. For example, a variable used in the "build_commands" section must use the path form known to the CBE OS, and a variable used in the "packages" section must use the path form known to the local host OS.

Example:

"variables": [
    {
    "name": "${FW_ROOT}",
    "value": "firmware"
    },
    {
    "name": "${FW_SRC}",
    "value": "firmware/src"
    }
]

Standard Variables/Macros ¶

Fuze contains a set of standard variables or macros that allow universal run time substitution. These standard variables always expand to their runtime value.

`${FUZEID}`¶

String containing the full FuzeID.

This variable may be used to build commands that use the FuzeID of the current build execution. Fuze generates the FuzeID at execution start, therefore, is available to all operations.

`${FUZEIDINT}`¶

Integer containing the unique hash value portion of the FuzeID.

This variable expands to the integer portion of the hash value of the FuzeID: XXXXX

`${MAJOR}`¶

The MAJOR part of the version, assuming "release_version" follows the MAJOR.MINOR paradigm

`${MINOR}`¶

The MINOR part of the version, assuming "release_version" follows the MAJOR.MINOR paradigm

Build ¶

The "build" section contains the heart of the build operations. All values, paths, and commands specified in this section must adhere to the OS, language, and format required by the CBE.

String and path values contained in this section may use variables. If variables are used, they must adhere to CBE requirements.

Warning

Build Section Command and Path Format

The build section is executed in the CBE. Therefore, all commands and path formats, including any variables that are expanded in this section, MUST be of a language and format compatible with the target CBE. For example, if the CBE is a Windows container, then commands, paths, and formats must be compatible with Windows.

Here is an overview specification of the section:

"build": {
    "description0": "<free_form_text>",
    "description1": "<free_form_text>",
    ...
    "descriptionN": "<free_form_text>",
    "name": "<name_of_repo>"
    "path": "<root_of_src_repo>",
    "container": "<container_name_from_container-specs.json>",
    "out": [
        "<path0>",
        "<path1>",
        ...
        "<pathN>"
    ],
    "cleanup": [
        "<path0>",
        "<path1>",
        ...
        "<pathN>"
    ],
    "workspace": {
    "dirs_to_be_created": {
        "common": [
            "<dir0>",
            "<dir1>",
            ...
            "<dirN>"
        ],
        "<build_target0>": [],
        ...
        "<build_targetN>": [],
    },
    "files_to_copy": {
        "common": {
        "files": [
            {"src": "<src_file0>", "dest": "<dest_file0>"},
            {"src": "<src_file1>", "dest": "<dest_file1>"},
            ...
            {"src": "<src_fileN>", "dest": "<dest_fileN>"}
        ],
        "dirs": [
            {"src": "<src_dir0>", "dest": "<dest_dir0>"},
            {"src": "<src_dir1>", "dest": "<dest_dir1>"},
            ...
            {"src": "<src_dirN>", "dest": "<dest_dirN>"}
        ]
        }
        "<build_target0>": {},
        ...
        "<build_targetN>": {}
    }
    },
    "build_steps": {
    "build_commands": {
        "common": [
        {
            "path": "<path_from_which_to_start>",
            "build_lines": [
            "<build_command0>",
            "<build_command1>",
            ...
            "<build_commandN>"
            ]
        }
        ],
        "<build_target0>": [],
        ...
        "<build_targetN>": []
    }
    },
    "post_actions": {
    "build_commands": {
        "common": [
        {
            "path": "<path_from_which_to_start>",
            "post_action_lines": [
                "<command0>",
                "<command1>",
                ...
                "<commandN>"
            ]
        }
        ],
        "<build_target0>": [],
        ...
        "<build_targetN>": []
    }
    },
    "dependencies": [
    {
        "name": "<package_name0>",
        "fuzeid": "<optional_FuzeID>",
        "path": "<path_for_import>",
        "build_steps": {<optional_build_steps>},
        "workspace": {<optional_workspace_operations>},
        "post_actions": {<optional_post_actions>},
        "container": "<optional_container_name>"
    },
    ...
    {
        "name": "<package_nameN>",
        "fuzeid": "<optional_FuzeID>",
        "path": "<path_for_import>",
        "build_steps": {<optional_build_steps>},
        "workspace": {<optional_workspace_operations>},
        "post_actions": {<optional_post_actions>},
        "container": "<optional_container_name>"
    }
    ]
},

`description`¶

Free form string value to represent some description of the build section.

"description0": "<free_form_text>",
"description1": "<free_form_text>",
...
"descriptionN": "<free_form_text>",

Notes:

These values have no functionality
You may use any key value, not just "description" for comments or free-form text as long as that key value is not found elsewhere as a key in the build section.

Example:

"description": "This works as free-form text entry",
"description0": "so does this",
"desc0": "and this does also"

`name`¶

String value indicating the name of the source code repository.

"name": "<name_of_src_repo>",

Notes:

The name must match the source code repository

`path`¶

String value indicating the path in which to find the source code.

"path": "<root_of_src_repo>",

Notes:

The path must be to the root of the source repository.
The path is relative to the root of the workspace
The path formatting must be compatible with the target CBE

`container`¶

String value indicating a valid name of a CBE container available to Fuze.

"container": "<container_name>",

Notes:

This CBE defines the OS, languages, toolchains, and capabilities of the commands and paths in the "build" section

`out`¶

List of string values indicating files and directories that are to be copied out of the CBE back to the local host workspace upon conclusion of the build.

"out": [
    "<path0>",
    "<path1>",
    ...
    "<pathN>"
],

Notes:

These values are both source and destination. Fuze will copy the specified location (file or directory) from the CBE to the exact same location in local host workspace.

Warning

All dirs and files to be packaged must be included in this section

If a file or directory is not included here, it cannot be included in a package.

Include locations that contain the following types of output:

build artifacts

log files

version files

Example:

"out": [
    "${FW_ROOT}/cortex_m3/Releases",
    "${FW_ROOT}/cortex_m3/out",
    "${FW_ROOT}/cortex_m3/tmpbuild.log",
    "${FW_ROOT}/cortex_m3/fuzeid.txt"
],

`cleanup`¶

List of string values indicating paths to files and directories that are to be removed/deleted from within the working source code repository when performing --target clean.

"cleanup": [
    "<path0>",
    "<path1>",
    ...
    "<pathN>"
],

Notes:

Since a build operation executes in a CBE container, running a clean from a build tool such make will not affect your local workspace. The cleanup section in the build map directs Fuze on how to clean you local workspace.
Performing cleanup after a build will ensure all listed paths to files/directories are removed from the working source code repo in local host workspace ensuring a clean build environment for following builds.
Remember to include any temporary files/directories populated as part of the build including log files or created directories and zip files.
A good rule of thumb is for the cleanup section to at least mirror the out section.

`workspace`¶

Dictionary hierarchy of directories and files to create and to copy into the CBE workspace prior to the "build_commands" execution.

This section defines the content of the CBE workspace for building.

"workspace": {
    "dirs_to_be_created": {
        "common": [
            "<dir0>",
            "<dir1>",
            ...
            "<dirN>"
        ],
        "<build_target0>": [],
        ...
        "<build_targetN>": [],
    },
    "files_to_copy": {
        "common": {
            "files": [
                {"src": "<src_file0>", "dest": "<dest_file0>"},
                {"src": "<src_file1>", "dest": "<dest_file1>"},
                ...
                {"src": "<src_fileN>", "dest": "<dest_fileN>"}
            ],
            "dirs": [
                {"src": "<src_dir0>", "dest": "<dest_dir0>"},
                {"src": "<src_dir1>", "dest": "<dest_dir1>"},
                ...
                {"src": "<src_dirN>", "dest": "<dest_dirN>"}
            ]
            }
            "<build_target0>": {},
            ...
            "<build_targetN>": {}
        }
    },

Notes:

Directory creation and file copying can be specified per build target
The "common" sections for both applies to all targets and will always execute
All values are of type String.
Path formats must be compatible with the CBE OS.
If a directory referred to by the "files_to_copy" section does not exist in the local host workspace, then it must be created explicitly with the "dirs_to_be_created" section.

Example:

"workspace": {
    "dirs_to_be_created": {
        "common": [
            "${FW_ROOT}/a1mfg",
            "${FW_ROOT}/asictest"
        ]
    },
    "files_to_copy": {
        "common": {
        "files": [],
        "dirs": [
            {"src": "${A1MFG}", "dest":  "${FW_ROOT}/a1mfg"},
            {"src":  "${ASIC}", "dest":  "${FW_ROOT}/asictest"}
        ]
        }
    }
},

This example performs the following in the workspace in the CBE prior to executing the build commands:

For all build targets, creates 2 directories at the ${FW_ROOT} location
For all build targets, copies contents of 2 directories, presumably from dependencies, to the directories that were just created

`build_steps`¶

Dictionary hierarchy containing the build commands to execute in the CBE. The “build_commands” section contains a dictionary with lists for each build target that specify commands for each build target.

This is the heart of the build exeuction phase.

"build_steps": {
    "build_commands": {
        "common": [
            {
                "path": "<path_from_which_to_start>",
                "build_lines": [
                    "<build_command0>",
                    "<build_command1>",
                    ...
                    "<build_commandN>"
                ]
            }
        ],
        "<build_target0>": [],
        ...
        "<build_targetN>": []
    }
},

Notes:

"build_lines" are the CBE shell commands that execute in the order given
The "common" section applies to all targets and executes first, i.e., prior to the specific build target sections.
If the --target option is not supplied on the Fuze command line, then all build steps will be executed. i.e., all build targets defined by the build map will be executed.

Example:

"build_steps": {
    "build_commands": {
        "common": [
            {
                "path": "${FW_ROOT}/cortex_m3",
                "build_lines": [
                    "bash -c 'echo ${FUZEID} > fuzeid.txt'"
                ]
            }
        ],
        "target_debug": [
            {
                "path": "${FW_ROOT}/cortex_m3",
                "build_lines": [
                    "make target -debug -version=fuzeid.txt",
                    "cat version.h"
                ]
            }
        ],
        "target_release": [
            {
                "path": "${FW_ROOT}/cortex_m3",
                "build_lines": [
                    "make target -release -version=fuzeid.txt",
                    "cat version.h"
                ]
            }
        ]
    }
},

Notes:

The ${FUZEID} variable is used to dump the runtime FuzeID to a file for all build targets.
This build map includes two build targets and a common section.
Both targets imply that the underlying Makefile dynamically creates a header file called version.h that includes the FuzeID
Both target sections dump the version.h file to stdout in the CBE so that the contents of that file is part of the build log and easily seen for debugging purposes.

`post_actions`¶

Dictionary hierarchy containing the post build commands to execute in the local host workspace outside of the CBE, prior to exporting artifacts from CBE back to the local host workspace.

"post_actions": {
    "build_commands": {
        "common": [
            {
                "path": "<path_from_which_to_start>",
                "post_action_lines": [
                    "<command0>",
                    "<command1>",
                    ...
                    "<commandN>"
                ]
            }
        ],
        "<build_target0>": [],
        ...
        "<build_targetN>": []
        }
    },

Notes:

The "common" section applies to all targets and will always execute.
"common" commands execute prior to the specific "build_target" sections.
Post actions assume that build commands have completed, as well as any operations contained in the "workspace" section.
"post_actions" commands must be provided in the syntax of the local host OS.

`dependencies`¶

List of dictionaries that define all dependencies for both build and package. Fuze will import each specified dependency into local host workspace, and then be copied into the CBE build workspace.

Note

The dependencies section is for both build and package

The "dependencies" section, although contained hierarchically within the "build", also pertains to the "packages" section. All source and object dependencies required for building, as well as all source and object dependencies required for packaging must be defined in this section.

"dependencies": [
    {
        "name": "<package_name0>",
        "fuzeid": "<optional_FuzeID>",
        "path": "<path_for_import>",
        "build_steps": {<optional_build_steps>},
        "workspace": {<optional_workspace_operations>},
        "post_actions": {<optional_post_actions>},
        "container": "<optional_container_name>"
    },
    {
        "name": "<package_name1>",
        "fuzeid": "<optional_FuzeID>",
        "path": "<path_for_import>",
        "build_steps": {<optional_build_steps>},
        "workspace": {<optional_workspace_operations>},
        "post_actions": {<optional_post_actions>},
        "container": "<optional_container_name>"
    },
    ...
    {
        "name": "<package_nameN>",
        "fuzeid": "<optional_FuzeID>",
        "path": "<path_for_import>",
        "build_steps": {<optional_build_steps>},
        "workspace": {<optional_workspace_operations>},
        "post_actions": {<optional_post_actions>},
        "container": "<optional_container_name>"
    }
]

Notes:

"name": Required string value indicating a package name. If not building the package from source, this name must match a name known to the Fuze package cache.
"fuzeid": Optional sting value indicating a particular FuzeID to be imported. If left blank, Fuze will pull the HEAD of the package repository.
"path": Required string value indicating the path at which to copy the dependency in relation to the workspace root.
"build_steps": Required if building this dependency from source. Omitted if dependency package is to be used. This section follows the same syntax and hierarchy as the "build_steps" section above.
"workspace": Optional section that follows the same syntax and hierarchy as the "workspace" section above.
"post_actions": Optional section that follows the same syntax and hierarch as the "post_actions" section above.
"container": Required if build this dependency from source. Omitted if dependency package is to be used. String value referring to a CBE.

Example:

"dependencies": [
    {
        "name": "fptools",
        "fuzeid": "190129-68-7962",
        "path": "${FPTOOLS}",
        "build_steps": {},
        "workspace": {},
        "post_actions": {},
        "container": ""
    },
    {
        "name": "a1mfg",
        "fuzeid": "",
        "path": "${A1MFG}",
        "build_steps": {},
        "workspace": {},
        "post_actions": {},
        "container": ""
    },
    {
        "name": "asictest",
        "fuzeid": "",
        "path": "${ASICTEST}",
        "build_steps": {},
        "workspace": {},
        "post_actions": {},
        "container": ""
    }
]

Notes:

Imports 3 dependent packages that are named: "fptools", "a1mfg", and "asictest" in the Fuze package repo.
The "fptools" package will be imported from FuzeID = 190129-68-7962. Note that if that FuzeID doesn’t identify a package with name = “fptools”, the import will fail.
The latest available "a1mfg" and "asictest" packages will be imported.
All of these packages are used in whatever format they stored in package repository. There is no build directions.

Packages ¶

The "packages" section contains the operations that create packages from artifacts and other files and directories. The packaging operation executes in the user’s local host workspace. All values, paths, and commands specified in this section must adhere to the OS, language, and format required by the local host OS.

String and path values contained in this section may use variables. If variables are used, they must adhere to local host OS requirements.

Warning

Packages Section Command and Path Format

The "packages" section executes in the local host OS. Therefore, all commands and path formats, including any variables that are expanded in this section, MUST be of a language and format known to the user’s local host OS.

Fuze creates zip files for packages. Each zip file is a single package. The zip file name is the following format:

<package_filename_pefix>-<package_target>.v<release_version>.<FuzeID>.zip

Here is an overview specification of the section:

"packages": {
    "output": "<packages_output_dirname>",
    "content": {
        "<package_target0>": {
            "name": "<package_filename_prefix>",
            "main_dir": "<main_dirname>",
            "is_dependency": true | false,
            "files_to_copy": {
                "files": [
                    {
                        "src": "<src_file_with_path0>",
                        "dest": "<dest_location0>"
                    },
                ...
                    {
                        "src": "<src_file_with_pathN>",
                        "dest": "<dest_locationN>"
                    }
                ],
                "dirs": [
                    {
                        "src": "<src_dir_with_path0>",
                        "dest": "<dest_location0>"
                    },
                    ...
                    {
                        "src": "<src_dir_with_pathN>",
                        "dest": "<dest_locationN>"
                    }
                ]
            }
        }
    },
    ...
    "<package_targetN>": {}
}

`output`¶

String value indicating the directory name into which the created packages will be exported.

"output": "<packages_output_dirname>",

Notes:

This will be a directory at the root of the FTL.

`content`¶

The "content" section wraps the functional parts of the packaging operations.

"content": {
    "<package_target0>":{},
    ...
    "<package_targetN>": {}
},

Notes:

Each package target defined in the General section must have an entry in the "content" section.

Example:

"content": {
"internal":{},
"internal-test": {}
},

Notes:

This "content" section defines the packaging directions for 2 packaging targets: "internal" and "internal-test".
The dictionaries associated with each must be populated with the packaging directions.

`name`¶

A string value that defines the package filename prefix for the output package. This value also defines the name by which this package will be known and referred to in the Fuze package repo if "is_dependency" = true

"name": "<package_name>",

Notes:

Each "package_target" defined in the General section must have an entry in the "content" section.

`main_dir`¶

A string value that defines the directory name under which the resultant package will be found in FTL.

"main_dir": "<main_dirname>",

Notes:

Creates the following directory structure in FTL upon completion:

/tmp
    /<packages_output_dirname>
        /<main_dirname>
            - <package_filename_prefix><fuze_generated_postfix>.zip

Example:

"packages": {
    "output": "firmware_pkgs",
    "content": {
    "Cortex-FW": {
        "name": "INTERNAL",
        "main_dir": "internal",

Results in an FTL structure of:

/<FuzeID>
    /firmware_pkgs
        /internal
            - INTERNEL-Coretex-FW.<fuze_generated_postfix>.zip

`is_dependency`¶

A boolean that defines whether or not the package being created should be made available to other build maps to be used as dependency.

If true, this package will be made available to other all other build maps to be used as a dependency. If --update-packages option is used in the Fuze build command, then the current package will be uploaded to the package repo as the latest available to other build maps. If --add-packages option is used, then the current package can be used as a dependency, but must be referred to specifically by FuzeID.
If false, the package will be created locally, but is not available to other build maps, regardless of the presence of the --update-packages or --add-packages options.
"is_dependency": true | false,

`files_to_copy`¶

A dictionary hierarchy that contains the directions for creating the package contents, both files and whole directories.

"files_to_copy": {
    "files": [
        {
            "src": "<src_file_with_path0>",
            "dest": "<dest_location0>"
        },
        ...
        {
            "src": "<src_file_with_pathN>",
            "dest": "<dest_locationN>"
        }
    ],
    "dirs": [
        {
            "src": "<src_dir_with_path0>",
            "dest": "<dest_location0>"
        },
        ...
        {
            "src": "<src_dir_with_pathN>",
            "dest": "<dest_locationN>"
        }
    ]
}

Notes:

The "files" section can relocate and rename a particular file
The "src" strings of the "files" section can use the “*” wildcard to specify all files of a particular directory. The "dest" in this case must be a directory.
The "dirs" section can relocate and rename a particular directory
When the resultant package is unzipped, the files and directories defined here will be the contents

Example:

"files_to_copy": {
    "files": [
        {
            "src": "${FW_ROOT}/doc/release-readme.md",
            "dest": ""
        },
        {
            "src": "${FW_ROOT}/asictest.zip",
            "dest": ""
        },
        {
            "src": "${FW_ROOT}/a1mfg.zip",
            "dest": "program_a1_mfg.zip"
        }
    ],
    "dirs": [
        {
            "src": "${FW_ROOT}/Kestrel/Releases/**/${RESULT_DIR}",
            "dest": "${FW_PKG_DEST}/${RESULT_DIR}"
        }
    ]
}

Notes:

Copies 3 single files into the package, and one of which is renamed (a1mfg.zip => program_a1_mfg.zip)
Copies an entire directories into the package.

`common` package target ¶

Fuze recognizes common as a special package target that will be processed differently from other targets.

The common target will contain instructions that will span all other package targets. A common package will not be created, but instead included with all other targets as these instructions are common. The name, main_dir, is_dependency fields are ignored within the common target and should remain empty to avoid confusion.