Note: | Prior to installing NVIDIA Build-Kit, ensure that NVIDIA DRIVE OS Linux SDK is installed on the system. A compatible version of NVIDIA DRIVE OS must be installed corresponding to the version of NVIDIA Build-Kit to be installed. |
Note: | Prior to installing NVIDIA Build-Kit, ensure that NVIDIA CopyTarget is installed on the system. A compatible version of NVIDIA CopyTarget must be installed corresponding to the version of NVIDIA Build-Kit to be installed. For installation instructions, see Installing CopyTarget. |
OS | Linux |
pre-build | 1. Setup binfmts for executing different arch binaries. 2. Extract base filesystem. 3. Update Mirrors in the target filesystem with values provided in the input CONFIG. 4. Update resolv.conf of target filesystem with host's resolv.conf. 5. Run preinstall scripts. |
build | 1. Generate comprehensive list of Debian packages to be installed. 2. Install Debian packages using package manager (apt). 3. Create users/groups and update user memberships. 4. Edit Hostname of the generated filesystem image. 5. Execute CopyTarget scripts. |
post-build | 1. Restore target filesystem mirrors to original in the target filesystem. 2. Restore target filesystem resolv.conf to original in target filesystem. 3. Run postinstall scripts. 4. Generate MANIFEST. 5. Copy MANIFEST into the target filesystem for reference |
process-output | 1. Create chosen target filesystems outputs a. Create ext4 filesystem image b. Create tarball (compressed archive) of the filesystem. |
Note: | Defaults are used if options are not used in the NVIDIA Build-Kit command line. |
Short Option | -h |
Long Option | --help |
Description | Show help message and exit. |
Short Option | -v |
Long Option | --version |
Description | Print version and exit. |
Short Option | -i JSON_PATH |
Long Option | --input=JSON_PATH |
Value Type | JSON_PATH must be a valid UNIX filepath or the value 'STDIN' |
Description | Specifies <JSON_PATH> as the absolute path to NVIDIA Build-Kit CONFIG file or 'STDIN' to inform build-kit that CONFIG file is coming from standard-input. |
Short Option | -w |
Long Option | --nv-workspace=NV_WORKSPACE |
Value Type | NV_WORKSPACE must be a valid UNIX directory path |
Description | Specifies NV_WORKSPACE as the absolute path to workspace location; this is the path to the location of NVIDIA DRIVE OS. |
Short Option | -o OUTPUT_FOLDER |
Long Option | --output=OUTPUT_FOLDER |
Value Type | OUTPUT_FOLDER must be a valid UNIX directory path |
Defaults | ${PWD} (Value of the present working directory) |
Required | No, but recommended. |
Description | Specifies <OUTPUT_FOLDER> as the absolute path to folder for output. |
Short Option | N/A |
Long Option | --create-tar=CREATE_TAR |
Value Type | CREATE_TAR must be an option in list: [yes, no] |
Defaults | No |
Required | No |
Description | Specifies to create filesystem tarball compressed as BunZip2. |
Short Option | N/A |
Long Option | --create-image=CREATE_IMAGE |
Value Type | CREATE_IMAGE must be an option in list: [yes, no] |
Defaults | Yes |
Required | No |
Description | Specifies to create ext4 filesystem image. |
Short Option | N/A |
Long Option | --copytarget-source-type=COPYTARGET_SOURCE_TYPE |
Value Type | COPYTARGET_SOURCE_TYPE must be a string with printable characters |
Defaults | pdk_sdk_installed_path |
Required | No |
Description | Specifies the type of source path in the copytarget manifest, from which files must be copied to the target filesystem directory. For more information, see CopyTarget. |
Short Option | -f FILESYSTEM_WORK_FOLDER |
Long Option | --filesystem-working-directory=FILESYSTEM_WORK_FOLDER |
Value Type | FILESYSTEM_WORK_FOLDER must be a valid UNIX directory path |
Defaults | None. |
Required | No |
Description | Allows user to override the folder in which the target filesystem is extracted and worked on. If option is not provided, target filesystem is extracted to BUILD_KIT_TMP_DIR/targetfs. Where BUILD_KIT_TMP_DIR is the temporary work directory created by the tool for storing temporary files and it is deleted once the output filesystem image/tarball is generated. |
Variable | REQUIRED_VARIABLES |
Value | Comma separated variable names |
Default | None |
Use case | Checks if the variables names specified as comma separated values are defined in the environment. Exits if they are not defined. |
Variable | QEMU_PATH |
Value | Path to qemu-aarch64-static. |
Default | /usr/bin/ |
Use case | Specifies the location of qemu-aarch64-static binary for chrooting into the Linux filesystem. |
Variable | BUILD_KIT_DIR |
Value | Path to NVIDIA Build-Kit directory. |
Default | /opt/nvidia/driveos/<release>/filesystems/build-kit/ |
Use case | Specifies NVIDIA Build-Kit location. |
Variable | COPYTARGET |
Value | Path to CopyTarget. |
Default | /opt/nvidia/driveos/<release>/filesystems/copytarget/copytarget.py |
Use case | Specifies the location of NVIDIA CopyTarget. |
Variable | PYTHON3 |
Value | Path to Python3. |
Default | /usr/bin/python3 |
Use case | Specifies the location of Python3 required for invoking copytarget. |
Variable | Description | PreInstall Scripts | PostInstall Scripts |
WORK_DIR | Assigned value of the path to NVIDIA Build-Kit's workspace. | Available | Available |
FILESYSTEM_WORK_DIR | Assigned value of the path to target filesystem directory located on host. | Available | Available |
BUILD_KIT_OUTDIR | Assigned value of the path to Build-Kit's output directory. | Available | Available |
NV_WORKSPACE | Assigned value of the path to NVIDIA DRIVE OS installation | Available | Available |
Field: List of all the keys supported by NVIDIA Build-Kit CONFIG. Type: Type of Value the keys should have. Acceptable Values: Additional information on what the Value should be. 1. Key content → If Value is of type object, then its keys should be a String and must adhere to the conditions specified here. 2. Value type → If Value is of type object, then the object's value must be of the type specified here. 3. Value contents → If Value is of type object, then the object's value must adhere to the conditions specified here. 4. Items type → If Value is of type array, then the array's values must be of the type specified here. 5. Items contents → If Value is of type array, then the array's values must adhere to the conditions specified here. 6. enum [a, b, c] → Implies Value must be one of a, b or c. 7. Valid UNIX filename → Valid String, which do not contain characters specified here: https://en.wikipedia.org/wiki/Filename#Reserved_characters_and_words 8. Valid UNIX filepath → Valid String, which is a combination of 'Valid UNIX filename'(s) joined via /, which should point to an existing file. Req: This row can have the following values: 1. Yes → The Field Must be present in the CONFIG with a non-empty value. 2. No → If the Field is not present in the CONFIG, the default shall be used, else specified value is used. Default: Specifies the Default value for 'Not Required' fields if they are absent from the CONFIG file. The row can have the following standard values apart from actual default values. 1. N/A → Cannot have a default value. (Required) 2. empty → Doesn't have a default value. (Getter shall return None) Syntax: Specifies the Syntax of usage of the field in the CONFIG file. Useful for a Visual understanding of Type and Acceptable Values. Instructions: Additional information on how the fields are used by Build-Kit and what behavior would it cause. Examples: Example usage of the field in the CONFIG file. |
Field | OS |
Type | String |
Acceptable Values | enum[linux] |
Req | Yes |
Default | N/A |
Instructions | Specifies "linux" for generating Linux target filesystem image. |
Example(s) | "OS": "linux" |
Field | Output |
Type | String |
Acceptable Values | Valid UNIX filename without extension. |
Req | Yes |
Default | N/A |
Instructions | Specifies the prefix name of the different filesystem output files generated |
Example(s) | "Output": "nvidia-driveos-build-kit-user-rfs" |
Field | Base |
Type | String |
Acceptable Values | Valid UNIX dirpath or a Valid UNIX filepath. |
Req | No |
Default | None |
Instructions | Specifies the path of the target filesystem to be used as input and to be built on top of. The value to this tag must either be: 1. A folder 2. A mountable image file with the extension .img in the filename 3. A bzip compressed tar file with the extension .tar.bz2 in the filename The filename must have an extension of .img or .tar.bz2; Base is always used when building a new filesystem. Base can be omitted when updating an existing filesystem. If Base is not provided, -f option is mandatory. |
Example(s) | "Base": "/home/nvidia/driveos/nvidia-driveos-base-rfs/" "Base": "/home/nvidia/driveos/nvidia-driveos-base-rfs.img" "Base": "/home/nvidia/driveos/nvidia-driveos-base-rfs.tar.bz2" |
Field | PreInstalls |
Type | Object |
Acceptable Values | Key content: Valid UNIX filepath to a BASH script. Value type: String Value content: enum[host, target, target_copy] |
Req | No |
Default | None |
Instructions | Specifies a list of zero, one, or more BASH scripts to be executed on the host or virtualized target during the Pre-Build stage. For each object element, the value of the element specifies whether the specific script is to be executed on the host or virtualized target. A value of: "host" is the indicator to execute existing BASH script on the host. "target" is the indicator to execute existing BASH script on the virtualized target. "target_copy" is the indicator to • copy existing BASH script on the host to /tmp/ of the target filesystem. • execute the script in /tmp/ on the virtualized target. • remove the script in /tmp/ of the target filesystem. Host BASH scripts are useful for setting up mirrors or updating DNS servers. The BASH scripts listed are executed in the order specified. The error code returned by each BASH script is validated, and NVIDIA Build-Kit will terminate upon the first error and report a message for debugging. |
Example(s) | "PreInstalls": { "${BUILD_KIT_DIR}/mirror-setup/setup-mirror.sh": "host", "setup-dns.sh": "target", "${HOME}/crypt_checker.sh": "target_copy" } |
Field | CopyTargets |
Type | Array |
Acceptable Values | Items type: String Items content: Valid UNIX filepaths to CopyTarget BASH scripts or MANIFESTS. or Items type: dict Items content: { "Manifest": "<path to copytarget yaml/script> (String) (Required)", "NvWorkspace": "<path from which files listed in copytarget are copied> (String) (Optional)", "SourceType": "<Copytarget source type> (String) (Optional)", "Args": { "Add": "<args to be added from copytarget cmdline> (String) (Optional)", "Del": "<args to be deleted from copytarget cmdline> (Str) (Optional)" } (Optional) } |
Req | No |
Default | None |
Instructions | Specifies a list of zero, one, or more CopyTarget to be executed on the host during Build stage. See CopyTarget Documentation for more details. The list of CopyTarget are executed in the order specified. Note: If item type is dict, to avoid overriding certain fields, do not specify the field in the dict. |
Example(s) | "CopyTargets": [ "${WORK_DIR}/copytargets/copytarget-libraries.yaml", "${WORK_DIR}/copytargets/copytarget-tools.yaml", { "Manifest": "${WORK_DIR}"/copytargets/copytarget-sdk.yaml", "NvWorkspace": "/usr/local/bin/sdk/", "SourceType": "custom" }, { "Manifest": "${WORK_DIR}"/copytargets/copytarget-sdk.yaml", "SourceType": "custom", "Args": { "Add": " --string-option1 val1 --bool-option2 ", "Del": " --string-option3 --bool-option2 " } } ] |
Field | PostInstalls |
Type | Object |
Acceptable Values | Key content: Valid UNIX filepath to a BASH script. Value type: String Value content: enum[host, target, target_copy] |
Req | No |
Default | None |
Instructions | Specifies a list of zero, one, or more BASH scripts to be executed on the host or virtualized target during the Post-Build stage. For each object element, the value of the element specifies whether the specific script is to be executed on the host or virtualized target. A value of: "host" is the indicator to execute existing BASH script on the host. "target" is the indicator to execute existing BASH script on the virtualized target. "target_copy" is the indicator to • copy existing BASH script on the host to /tmp/ of the target filesystem. • execute the script in /tmp/ on the virtualized target. • remove the script in /tmp/ of the target filesystem. Host BASH scripts are useful for setting up mirrors or updating DNS servers. The BASH scripts listed are executed in the order specified. The error code returned by each BASH script is validated, and NVIDIA Build-Kit will terminate upon the first error and report a message for debugging. |
Example(s) | "PostInstalls": { "${BUILD_KIT_DIR}/mirror-setup/teardown-mirror.sh": "host", "teardown-dns.sh": "target", "${HOME}/crypt_priv_files.sh": "target_copy" } |
Field | FilesystemCleanup |
Type | Array |
Acceptable Values | Items type: String Items content: Valid UNIX filepaths |
Req | No |
Default | None |
Instructions | Specifies a list of zero, one, or more target files to be deleted as part of Post-Build stage. |
Example(s) | "FilesystemCleanup": [ "/tmp/temp.txt", "/var/tmp/tmp.log" ] |
Field | ImageSize |
Type | String |
Acceptable Values | 64-bit Unsigned Integer enclosed in double quotes. |
Req | No |
Default | 8589934592 |
Instructions | The size of the partition to which the current image will be expanded to (defaults to 8GB). This is required for determining values Filesystem Metadata values like journal size, inode_size, inode_byte_ratio. This will help create the required number of inodes and journal in the smaller filesystem image generated, considering the image file expansion. |
Example(s) | "ImageSize": "4294967296" |
Field | FilesystemType |
Type | String |
Acceptable Values | String must be using characters from the set [A-Za-z0-9_-] |
Req | No |
Default | Standard |
Instructions | Specifies the type of filesystem to be created for the CONFIG. This option is forwarded to copytarget while executing the copytarget manifests, and instructs copytarget whether to copy the file, based on rules written inside the copytarget manifest. See CopyTarget Documentation for more details. |
Example(s) | "FilesystemType": "standard" |
Field | Mirrors |
Type | Array |
Acceptable Values | Items type: String Items content: Valid Debian mirrors |
Req | No |
Default | None |
Instructions | Specifies zero, one, or more Debian mirrors hosting Debians specified in DebianPackages. Ensure these mirror values adhere to the package manager's syntax of mirrors. Ordering of Debian mirrors are preserved. If the field is not provided, the default mirrors inside the filesystem is used. To remove usage of Default Mirrors, have an entry in the CONFIG "Mirrors": [] |
Example(s) | "Mirrors": [ "deb http://ports.ubuntu.com/ubuntu-ports/ bionic main universe restricted", "deb http://ports.ubuntu.com/ubuntu-ports/ bionic-updates main universe restricted", "deb http://ports.ubuntu.com/ubuntu-ports/ bionic-security main universe restricted" ] |
Field | Users |
Type | Object |
Acceptable Values | Key content: Unique user identification alphanumeric string Value type: dict Value content: { "<key >": { “UID” : "<User-Identifier in target /etc/passwd>" (String) (Required), “Password”: { “HashedPassword” : "<Hashed-Password>" (String) (Required) }, “Username” : “<Username in target /etc/passwd>”, (String) (Required) } or Key content: Valid UNIX username requirements Value type: Array with length=2 Value content: [UID(String), passwd(String)] Where UID must be a valid UNIX user identifier and password must be a valid UNIX password. The latter entry is just for legacy support and not recommended to be used. |
Req | No |
Default | None |
Instructions | Specifies a list of zero, one, or more users to be added to the target filesystem. For each key-value pair in the JSON dictionary, a user account is described by its attributes: user-identifier, username, password entry. This entry will either add and update the user account as described by workflow below. The ordering of users to be added is the order of dictionary entries. Ensure usernames, user identifiers, and user passwords are valid UNIX standards. User-identifier is recommended to be above 1000, and not conflicting with existing user identifiers; otherwise, conflicting user-identifiers will be reported as an error. The password entry (i.e. value for the key “Password”) is a dictionary with key “HashedPassword” and value hashed-password created using unix crypt algorithm. The alternate way to provide password using plain text is also supported but not preferred due to security reasons as shown below: “Password”: “<Password text>” Workflow: • Build-kit fetches the user entry’s UID attribute in the CONFIG file and then checks if there exists a user account whose identifier matches value of UID in the filesystem described by option "-f" or “Base” . • If the user account exists, Build-kit updates the username of that account to what is specified in the user entry of the CONFIG file. • If the user account does not exist, Build-kit proceeds to add the user account with the username provided in the user entry of the CONFIG file. • In all the cases, the Build-kit sets the user account password to the value corresponding to the password attribute in the user entry of the CONFIG file. Note that Build-kit updates the username’s user-group when updating the username of the user account. For example: when renaming username nvidia, with user-group nvidia and UID 1000 to username nvidia2, Build-kit updates the user’s group nvidia to nvidia2 keeping same UID 1000. Note that the previous version of Users block where one entry is : “<username>” : [“user-id”, “password”], continues to be supported to only add users for backward compatibility but not to update users. |
Example(s) | "Users": { "one": { "UID": "1001", "Username" : "nvidia2", "Password": "driveos" }, "two": { "UID": "1002", "Username" : "nvidia3", "Password": { "HashedPassword": "$6$4bhqDdYb$kxJApfqarvpuMhLweydYp7 .NqSFXWxML8N3JywqadmlEp9GF89553PNBAYBTdGmfBaUe7/7LxpP8PBBQlCJT70" }, } |
Field | Groups |
Type | Object |
Acceptable Values | Key content: Unique user identification alphanumeric string Value type: dict Value content: { "<key >": { “GID” : "<Group-Identifier in target /etc/group>" (String) (Required), “Groupname” : “<Group name in target /etc/group>”, (String) (Required) } or Key content: Valid UNIX groupname Value type: String Value content: Valid UNIX group identifier The latter entry is just for legacy support and not recommended to be used. |
Req | No |
Default | None |
Instructions | Specifies a list of zero, one, or more groups to be added to the target filesystem. For each key-value pair in the JSON, a group is described by its attributes: groupname and the group-identifier. This entry will either add or update the group as described by workflow below. Ordering of groups to be added is preserved. Ensure group names and group identifiers are valid UNIX standards. Group identifier is recommended to be above 1000, and not conflicting with existing group identifiers; otherwise, conflicting user identifiers will be reported as an error. Workflow: • Build-kit fetches the group entry’s GID attribute in the CONFIG file and then checks if there exists a group whose identifier matches value of GID in the filesystem described by -f option or “Base” . • If the group exists, Build-kit updates the groupname of that account to what is specified in the group entry of the CONFIG file. • If the group does not exist, Build-kit proceeds to add the group with the groupname provided in the group entry of the CONFIG file. Note that the previous version of Groups block where one entry is: “<groupname>”: “<group-id>”, continues to be supported to only add groups for backward compatibility but not to update groups. |
Example(s) | "Groups": { "one": { "Groupname": "automotive", "GID": "2001" } } |
Field | Memberships |
Type | Object |
Acceptable Values | Key content: valid UNIX username Value type: Array Value content: [ group1(String),...., groupN(String) ] Where group* must be a valid UNIX groupname or group identifier. |
Req | No |
Default | None |
Instructions | Specifies a list of zero, one, or more group memberships to be added to the target filesystem. |
Example(s) | "Memberships": { "nvidia": [ "1000", "audio", "cdrom", "dialout", ] } |
Field | DebianPackages |
Type | Array |
Acceptable Values | Items type: String Items content: Valid Debian package names. |
Req | No |
Default | None |
Instructions | Specifies a list of zero, one, or more Debian packages to be installed on target filesystem during Build stage. Each Debian package can be accompanied by a valid corresponding package version but is entirely optional. If no package version is specified, the latest version as reported by the Debian mirror will be acquired and installed If the list of Debians and or the specified versions conflict, an error will be reported. |
Example(s) | "DebianPackages": [ "openssh-server=1-4ubuntu0.3", "vim" ] |
Field | Hostname |
Type | String |
Acceptable Values | Valid UNIX hostname |
Req | No |
Default | None |
Instructions | Host name of the target filesystem is updated to the one specified as the value for HostName. If HostName Field is not present in the CONFIG, the host name of the Base filesystem is preserved. |
Example(s) | "HostName": "auto-ubuntu" |
Error | Variable values |
No value for NV_WORKSPACE provided with the -w option. | N/A |
NV_WORKSPACE: '<path>' doesn't exist. | path: Value provided after -w in Build-Kit command line. |
No CONFIG provided with the '-i' option. | N/A |
CONFIG file: '<json_file>' doesn't exist. | json_file: Value provided after -i in Build-Kit command line. |
<config_os> is not supported. | config_os: Value of "OS" tag in the Build-Kit CONFIG file. |
<variable> is not defined. | variable: Any required Build-Kit environment variable. |
Command returned non-zero error code: <cmd_string> | cmd_string: Command line used to execute binary outside Build-Kit python scripts. |
Unsupported execution location: '<run_target>'. Expecting a value from the list: [host, target, target_copy] | run_target: Runtime target configured for Pre-Install/ Post-Install scripts. |
Unknown Base file format: '<base>', Please provide Base in a Build-Kit supported format. | base: Value of "Base" tag in the Build-Kit CONFIG file. |
Required Field: '<field>' absent from input CONFIG file: '<config>'. | field: Field is one of the required fields of Build-Kit CONFIG. (See NVIDIA Build-Kit CONFIG Semantics for more information). config: Input CONFIG file provided to Build-Kit. |
<field>: Value is not a string in the input CONFIG file: '<config>'. | field: Field is one of the required fields of Build-Kit CONFIG. (See NVIDIA Build-Kit CONFIG Semantics for more information). config: Input CONFIG file provided to Build-Kit. |
<field>: Value is not a list in the input CONFIG file: '<config> | field: Field is one of the required fields of Build-Kit CONFIG. (See NVIDIA Build-Kit CONFIG Semantics for more information). config: Input CONFIG file provided to Build-Kit. |
<field>: Value is not a dict in the input CONFIG file: '<config> | field: Field is one of the required fields of Build-Kit CONFIG. (See NVIDIA Build-Kit CONFIG Semantics for more information). config: Input CONFIG file provided to Build-Kit. |
FileNotFoundError: [Errno 2] No such file or directory: '<file>' | file: Missing file in the host system where Build-Kit is running. |
Usage: build_kit.py [options] build_kit.py: error: no such option: <incorrect_option> | incorrect_option: Incorrect option provided in Build-Kit command line |
Usage: build_kit.py [options] build_kit.py: error: option --create-tar: invalid choice: '<val>' (choose from 'yes', 'no') | val: Value provided to --create-tar option. |
Usage: build_kit.py [options] build_kit.py: error: option --create-image: invalid choice: '<val>' (choose from 'yes', 'no') | val: Value provided to --create-image option. |