[Nexthop] Add basic utilities for FBOSS Image Builder

Provide basic tools and utiulities for the distro_cli build system.

- Add custom exception classes for structured error handling
- Define shared constants for Docker configuration and build settings
- Implement path resolution utilities for components
- Define test data fixture for image manifest validation

These core utilities provide the base infrastructure required by all downstream components including Docker integration, artifact handling, and build orchestration.

Author: raghav-nexthop

fboss-image/distro_cli/lib/constants.py

@@ -0,0 +1,11 @@
+# Copyright (c) 2004-present, Facebook, Inc.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree. An additional grant
+# of patent rights can be found in the PATENTS file in the same directory.
+
+"""Constants for FBOSS image builder."""
+
+# Docker image names
+FBOSS_BUILDER_IMAGE = "fboss_builder"

fboss-image/distro_cli/lib/exceptions.py

@@ -0,0 +1,57 @@
+# Copyright (c) 2004-present, Facebook, Inc.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree. An additional grant
+# of patent rights can be found in the PATENTS file in the same directory.
+
+"""Exception definitions for FBOSS image builder."""
+
+
+class FbossImageError(Exception):
+    """Base exception for all fboss-image errors.
+
+    All custom exceptions in the fboss-image tool should inherit from this.
+    This allows the top-level CLI handler to catch and format errors appropriately
+    before returning a non-zero exit code.
+    """
+
+
+class BuildError(FbossImageError):
+    """Build command failed.
+
+    Raised when a component build fails, including:
+    - Build script/command not found
+    - Build process returned non-zero exit code
+    - Build output validation failed
+    """
+
+
+class ManifestError(FbossImageError):
+    """Manifest parsing or validation failed.
+
+    Raised when:
+    - Manifest file not found or invalid JSON
+    - Required fields missing
+    - Invalid manifest structure
+    """
+
+
+class ArtifactError(FbossImageError):
+    """Artifact operation failed.
+
+    Raised when:
+    - Expected artifact not found after build
+    - Artifact download failed
+    - Artifact cache operation failed
+    """
+
+
+class ComponentError(FbossImageError):
+    """Component-specific error.
+
+    Raised when:
+    - Component not found in manifest
+    - Component configuration invalid
+    - Component builder not implemented
+    """

fboss-image/distro_cli/lib/paths.py

@@ -0,0 +1,38 @@
+# Copyright (c) 2004-present, Facebook, Inc.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree. An additional grant
+# of patent rights can be found in the PATENTS file in the same directory.
+
+"""Path resolution utilities for FBOSS image builder."""
+
+from pathlib import Path
+
+
+def get_root_dir(dir_name: str = "fboss-image") -> Path:
+    """Find the root directory containing the specified directory.
+
+    This works by walking up from the current file until we find
+    the specified directory, then returning its parent.
+
+    Args:
+        dir_name: Name of the directory to search for (default: "fboss-image")
+
+    Returns:
+        Path to root directory (parent of dir_name)
+
+    Raises:
+        RuntimeError: If the root directory cannot be determined
+    """
+    current = Path(__file__).resolve()
+
+    # Walk up the directory tree looking for dir_name
+    for parent in current.parents:
+        if (parent / dir_name).is_dir():
+            return parent
+
+    raise RuntimeError(
+        f"Could not find root from {current}. "
+        f"Expected to find '{dir_name}' directory in parent path."
+    )

fboss-image/distro_cli/tests/data/dev_image.json

@@ -0,0 +1,29 @@
+{
+  "distribution_formats": {
+    "onie": "FBOSS-k6.4.3.bin",
+    "usb": "FBOSS-k6.4.3.iso"
+  },
+  "kernel": {
+    "download": "https://artifact.github.com/nexthop-ai/fboss/fboss-oss_kernel_v6.4.3.tar"
+  },
+  "other_dependencies": [
+    {"download": "https://artifact.github.com/nexthop-ai/fsdb/fsdb.rpm"},
+    {"download": "file:vendor_debug_tools/tools.rpm"}
+  ],
+  "fboss-platform-stack": {
+    "execute": ["../../../../fboss/fboss/oss/scripts/build.py", "platformstack"]
+  },
+  "bsps": [
+    {"execute": ["../../../../vendor_bsp/build.make"]},
+    {"execute": ["../../../../fboss/oss/reference_bsp/build.py"]}
+  ],
+  "sai": {
+    "execute": ["../../../../fboss_brcm_sai/build.sh"]
+  },
+  "fboss-forwarding-stack": {
+    "execute": ["../../../../fboss/fboss/oss/scripts/build.py", "forwardingstack"]
+  },
+  "image_build_hooks": {
+    "after_pkgs": "additional_os_pkgs.xml"
+  }
+}

fboss-image/kernel/configs/fboss-reference.config

@@ -29,7 +29,7 @@ CONFIG_INIT_ENV_ARG_LIMIT=32
 # CONFIG_COMPILE_TEST is not set
 # CONFIG_WERROR is not set
 CONFIG_LOCALVERSION=""
-CONFIG_LOCALVERSION_AUTO=y
+# CONFIG_LOCALVERSION_AUTO is not set
 CONFIG_BUILD_SALT=""
 CONFIG_HAVE_KERNEL_GZIP=y
 CONFIG_HAVE_KERNEL_BZIP2=y
@@ -234,7 +234,7 @@ CONFIG_RD_ZSTD=y
 CONFIG_BOOT_CONFIG=y
 # CONFIG_BOOT_CONFIG_FORCE is not set
 CONFIG_BOOT_CONFIG_EMBED=y
-CONFIG_BOOT_CONFIG_EMBED_FILE="common.bootconfig"
+CONFIG_BOOT_CONFIG_EMBED_FILE="facebook/config/common.bootconfig"
 CONFIG_INITRAMFS_PRESERVE_MTIME=y
 CONFIG_CC_OPTIMIZE_FOR_PERFORMANCE=y
 # CONFIG_CC_OPTIMIZE_FOR_SIZE is not set
@@ -5583,7 +5583,7 @@ CONFIG_MODULE_SIG_KEY="certs/signing_key.pem"
 CONFIG_MODULE_SIG_KEY_TYPE_RSA=y
 # CONFIG_MODULE_SIG_KEY_TYPE_ECDSA is not set
 CONFIG_SYSTEM_TRUSTED_KEYRING=y
-CONFIG_SYSTEM_TRUSTED_KEYS="kmod-hsm.pem"
+CONFIG_SYSTEM_TRUSTED_KEYS="facebook/fbinfra-kmod-hsm.pem"
 # CONFIG_SYSTEM_EXTRA_CERTIFICATE is not set
 # CONFIG_SECONDARY_TRUSTED_KEYRING is not set
 # CONFIG_SYSTEM_BLACKLIST_KEYRING is not set

fboss-image/kernel/scripts/merge_config.py

@@ -12,6 +12,7 @@
 import pathlib
 import re
 
+
 def main(argv):
     if len(argv) != 3:
         sys.stderr.write("Usage: merge_config.py <config_path> <overlay_path>\n")
@@ -20,8 +21,8 @@ def main(argv):
     cfg_lines = pathlib.Path(cfg_path).read_text().splitlines()
     overlay_lines = pathlib.Path(overlay_path).read_text().splitlines()
 
-    VAL_RE = re.compile(r'^CONFIG_([^=]+)=(.*)$')
-    NS_RE  = re.compile(r'^#\s*CONFIG_([^\s]+)\s+is\s+not\s+set\s*$')
+    VAL_RE = re.compile(r"^CONFIG_([^=]+)=(.*)$")
+    NS_RE = re.compile(r"^#\s*CONFIG_([^\s]+)\s+is\s+not\s+set\s*$")
 
     # Build updates from overlay, keeping only the last occurrence per key
     updates = {}
@@ -31,14 +32,16 @@ def main(argv):
         if not line:
             continue
         # Skip pure comments except the canonical "not set" form
-        if line.startswith('#') and not NS_RE.match(line):
+        if line.startswith("#") and not NS_RE.match(line):
             continue
         m_val = VAL_RE.match(line)
         m_ns = None if m_val else NS_RE.match(line)
         if not (m_val or m_ns):
             continue
         key = (m_val or m_ns).group(1)
-        repl = f'CONFIG_{key}={m_val.group(2)}' if m_val else f'# CONFIG_{key} is not set'
+        repl = (
+            f"CONFIG_{key}={m_val.group(2)}" if m_val else f"# CONFIG_{key} is not set"
+        )
         if key in updates:
             try:
                 order.remove(key)
@@ -61,8 +64,9 @@ def main(argv):
     for k in order:
         out.append(updates[k])
 
-    pathlib.Path(cfg_path).write_text('\n'.join(out) + '\n')
+    pathlib.Path(cfg_path).write_text("\n".join(out) + "\n")
     return 0
 
+
 if __name__ == "__main__":
     sys.exit(main(sys.argv))

fboss-image/kernel/scripts/prepare_config.sh

@@ -23,39 +23,39 @@ PROGNAME=$(basename "$0")
 SCRIPTS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 usage() {
-    echo "Usage: $PROGNAME <kernel_source_path> <fboss_reference_config> [local_overrides_config]"
-    echo ""
-    echo "Create kernel config by merging FBOSS reference config with kernel defaults"
-    echo ""
-    echo "Arguments:"
-    echo "  kernel_source_path     Path to Linux kernel source directory"
-    echo "  fboss_reference_config Path to FBOSS reference kernel config file"
-    echo "  local_overrides_config Optional path to local config overrides file"
-    echo ""
-    echo "Examples:"
-    echo "  $PROGNAME /path/to/linux-6.4.3 fboss-reference.config"
-    echo "  $PROGNAME /path/to/linux-6.4.3 fboss-reference.config fboss-local-overrides.config"
+  echo "Usage: $PROGNAME <kernel_source_path> <fboss_reference_config> [local_overrides_config]"
+  echo ""
+  echo "Create kernel config by merging FBOSS reference config with kernel defaults"
+  echo ""
+  echo "Arguments:"
+  echo "  kernel_source_path     Path to Linux kernel source directory"
+  echo "  fboss_reference_config Path to FBOSS reference kernel config file"
+  echo "  local_overrides_config Optional path to local config overrides file"
+  echo ""
+  echo "Examples:"
+  echo "  $PROGNAME /path/to/linux-6.4.3 fboss-reference.config"
+  echo "  $PROGNAME /path/to/linux-6.4.3 fboss-reference.config fboss-local-overrides.config"
 }
 
 validate_inputs() {
-    local kernel_source="$1"
-    local fboss_config="$2"
+  local kernel_source="$1"
+  local fboss_config="$2"
 
-    if [ ! -d "$kernel_source" ]; then
-        echo "$PROGNAME: Error: Kernel source directory '$kernel_source' does not exist"
-        exit 1
-    fi
+  if [ ! -d "$kernel_source" ]; then
+    echo "$PROGNAME: Error: Kernel source directory '$kernel_source' does not exist"
+    exit 1
+  fi
 
-    if [ ! -f "$fboss_config" ]; then
-        echo "$PROGNAME: Error: FBOSS reference config '$fboss_config' does not exist"
-        exit 2
-    fi
+  if [ ! -f "$fboss_config" ]; then
+    echo "$PROGNAME: Error: FBOSS reference config '$fboss_config' does not exist"
+    exit 2
+  fi
 }
 
 # Main script logic
 if [ $# -lt 2 ] || [ $# -gt 3 ]; then
-    usage
-    exit 3
+  usage
+  exit 3
 fi
 
 KERNEL_SOURCE="$1"
@@ -67,8 +67,8 @@ validate_inputs "$KERNEL_SOURCE" "$FBOSS_CONFIG"
 echo "Preparing kernel config..."
 echo "Kernel source: $KERNEL_SOURCE"
 echo "FBOSS config: $FBOSS_CONFIG"
-if [[ -n "$LOCAL_OVERRIDES" ]]; then
-    echo "Local overrides: $LOCAL_OVERRIDES"
+if [[ -n $LOCAL_OVERRIDES ]]; then
+  echo "Local overrides: $LOCAL_OVERRIDES"
 fi
 
 # Create default config
@@ -81,8 +81,8 @@ make defconfig
 python3 "$SCRIPTS_DIR/merge_config.py" ".config" "$FBOSS_CONFIG"
 
 # Apply local overrides (third layer)
-if [[ -n "$LOCAL_OVERRIDES" ]]; then
-    python3 "$SCRIPTS_DIR/merge_config.py" ".config" "$LOCAL_OVERRIDES"
+if [[ -n $LOCAL_OVERRIDES ]]; then
+  python3 "$SCRIPTS_DIR/merge_config.py" ".config" "$LOCAL_OVERRIDES"
 fi
 
 # Reconcile any dependency-driven defaults after all merges

fboss-image/kernel/specs/kernel.spec

@@ -28,7 +28,8 @@ Source0: https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-%{version}.tar.xz
 Source1: fboss-reference.config
 Source2: fboss-local-overrides.config
 
-%global container_scripts_dir /var/FBOSS/fboss/fboss-image/kernel/scripts
+# Default in-container scripts dir (override via --define container_scripts_dir if needed)
+%{!?container_scripts_dir:%global container_scripts_dir /src/fboss-image/kernel/scripts}
 
 # Build requirements
 BuildRequires: gcc, make

fboss-image/kernel/test/test_prepare_config.sh

@@ -33,14 +33,14 @@ trap cleanup EXIT
 # Use the first kernel version from FBOSS_KERNEL_VERSIONS array
 TEST_KERNEL_VERSION="${FBOSS_KERNEL_VERSIONS[0]}"
 python3 "$KERNEL_SCRIPTS_DIR/generate_config_overrides.py" \
-    "$KERNEL_CONFIGS_DIR/fboss-local-overrides.yaml" \
-    "$TEST_KERNEL_VERSION" \
-    "$OVR_CONFIG"
+  "$KERNEL_CONFIGS_DIR/fboss-local-overrides.yaml" \
+  "$TEST_KERNEL_VERSION" \
+  "$OVR_CONFIG"
 
 mkdir -p "$FAKE_KERNEL_DIR"
 
 # Minimal fake kernel Makefile providing defconfig and olddefconfig
-cat > "$FAKE_KERNEL_DIR/Makefile" << 'EOF'
+cat >"$FAKE_KERNEL_DIR/Makefile" <<'EOF'
 ARCH ?= x86_64
 
 defconfig:
@@ -60,7 +60,9 @@ cd "$FAKE_KERNEL_DIR"
 
 # Helper: assert a grep matches
 assert_grep() {
-  local pattern="$1"; local file="$2"; local msg="$3"
+  local pattern="$1"
+  local file="$2"
+  local msg="$3"
   if ! grep -qE "$pattern" "$file"; then
     echo "FAIL: $msg" >&2
     echo "Searched pattern: $pattern" >&2
@@ -72,7 +74,9 @@ assert_grep() {
 
 # Helper: assert a grep does NOT match
 assert_not_grep() {
-  local pattern="$1"; local file="$2"; local msg="$3"
+  local pattern="$1"
+  local file="$2"
+  local msg="$3"
   if grep -qE "$pattern" "$file"; then
     echo "FAIL: $msg" >&2
     echo "Unexpectedly matched pattern: $pattern" >&2
@@ -85,9 +89,9 @@ assert_not_grep() {
 CFG=".config"
 
 # 1) FBOSS reference presence (pick stable, known entries)
-assert_grep '^CONFIG_NET_NS=y$'        "$CFG" "FBOSS ref: NET_NS present"
-assert_grep '^CONFIG_BRIDGE=m$'        "$CFG" "FBOSS ref: BRIDGE=m present"
-assert_grep '^CONFIG_VLAN_8021Q=m$'    "$CFG" "FBOSS ref: VLAN_8021Q=m present"
+assert_grep '^CONFIG_NET_NS=y$' "$CFG" "FBOSS ref: NET_NS present"
+assert_grep '^CONFIG_BRIDGE=m$' "$CFG" "FBOSS ref: BRIDGE=m present"
+assert_grep '^CONFIG_VLAN_8021Q=m$' "$CFG" "FBOSS ref: VLAN_8021Q=m present"
 
 # 2) Overrides are applied exactly (set to empty string) and no duplicates remain
 # CONFIG_BOOT_CONFIG_EMBED_FILE
@@ -118,7 +122,7 @@ else
 fi
 
 # 3) Sanity: defconfig contributions still present
-assert_grep '^CONFIG_64BIT=y$'  "$CFG" "defconfig: 64BIT present"
+assert_grep '^CONFIG_64BIT=y$' "$CFG" "defconfig: 64BIT present"
 assert_grep '^CONFIG_X86_64=y$' "$CFG" "defconfig: X86_64 present"
 
 echo "All real-merge assertions passed."