helper

Helper functions and utilities for the FABulous CLI.

This module provides various utility functions for the FABulous command-line interface, including project creation, file operations, logging setup, external application management, and OSS CAD Suite installation. It serves as a collection of common functionalities used throughout the CLI components.

Attributes

MAX_BITBYTES

Classes

CommandPipeline

Helper class to manage command execution with error handling.

Functions

allow_blank(func)	Allow function to be called with blank arguments.
clone_git_repo(repo_url, target_dir[, branch])	Clone or update a GitHub repository.
clone_tile_directory(src_dir, dst_dir, src_name, dst_name)	Copy a tile directory and rename all occurrences of src_name to dst_name.
copy_verilog_files(src, dst)	Copy all Verilog files from source directory to the destination directory.
create_project(project_dir[, lang])	Create a FABulous project containing all required files.
get_file_path(project_dir, args, file_extension[, ...])	Get the file path for the specified file extension.
install_fabulator(install_dir)	Install FABulator and set FABULATOR_ROOT environment variable.
install_oss_cad_suite(destination_folder[, update])	Download and extract the latest OSS CAD Suite.
make_hex(binfile, outfile)	Convert a binary file into hex file.
register_tile_in_fabric_csv(csv_path, dst_dir)	Append Tile/Supertile entries for dst_dir to csv_path before ParametersEnd.
remove_dir(path)	Remove a directory and all its contents.
resolve_tile(arg, tile_dir)	Resolve a tile name-or-path argument to a Path.
run_task(task_name, task_dir[, task_vars, verbose, ...])	Run a Taskfile task using the task CLI.
setup_logger(verbosity, debug[, log_file])	Set up the loguru logger with custom formatting based on verbosity level.
update_project_version(project_dir)	Update the project version in the .env file.
wrap_with_except_handling(fun_to_wrap)	Wrap function with 'fun_to_wrap' with exception handling.

Module Contents

CommandPipeline

class CommandPipeline(cli_instance, force=False)

Helper class to manage command execution with error handling.

Parameters:

• cli_instance (FABulous_CLI) – The CLI instance to use for command execution.

• force (bool) – If True, continues executing commands even if one fails.

Methods

add_step(command, error_message='Command failed') → CommandPipeline

Add a command step to the pipeline.

Parameters:

• command (str) – The command string to execute.

• error_message (str, optional) – Custom error message to use if the command fails. Defaults to “Command failed”.

Returns:

Returns self to allow method chaining.

execute() → bool

Execute all steps in the pipeline.

Executes each command step in sequence. If any command fails (exit code != 0), raises a PipelineCommandError with the associated error message.

Returns:

True if all commands executed successfully.

Raises:

PipelineCommandError – If any command in the pipeline fails during execution.

execute_parallel() → bool

Execute all steps in the pipeline concurrently using threads.

If any command fails (raises or sets a non-zero exit code), a PipelineCommandError is raised (unless force is True).

get_exit_code() → int

Get the final exit code from pipeline execution.

MAX_BITBYTES = 16384

allow_blank(func) → Callable

Allow function to be called with blank arguments.

This decorator wraps a function to handle cases where fewer arguments are provided than expected. If only one argument is provided, it calls the function with an additional empty string argument.

Parameters:

func (Callable) – The function to be wrapped.

Returns:

The wrapped function that can handle missing arguments.

clone_git_repo(repo_url, target_dir, branch='main') → bool

Clone or update a GitHub repository.

Parameters:

• repo_url (str) – GitHub repository URL (e.g., “https://github.com/user/repo.git”)

• target_dir (Path) – Local directory to clone/download to

• branch (str) – Git branch to checkout (default: “main”)

Returns:

True if successful, False otherwise

Raises:

FileNotFoundError – If git application not found in PATH

clone_tile_directory(src_dir, dst_dir, src_name, dst_name) → None

Copy a tile directory and rename all occurrences of src_name to dst_name.

Notes

Only works correctly for tiles that follow the default FABulous tile naming scheme, where the tile name is used as a prefix for all files and internal references (e.g. LUT4AB.csv, LUT4AB_switch_matrix.list).

Parameters:

• src_dir (Path) – Source tile directory to copy.

• dst_dir (Path) – Destination path for the cloned directory.

• src_name (str) – Tile name to replace in file contents and file/directory names.

• dst_name (str) – Replacement tile name.

copy_verilog_files(src, dst) → None

Copy all Verilog files from source directory to the destination directory.

Parameters:

• src (Path) – Source directory.

• dst (Path) – Destination directory

create_project(project_dir, lang=HDLType.VERILOG) → None

Create a FABulous project containing all required files.

This function will overwrite existing files in the target directory.

Copies the common files and the appropriate project template. Replaces the {HDL_SUFFIX} placeholder in all tile csv files with the appropriate file extension. Creates a .FABulous directory in the project. Also creates a .env file in the project directory with the project settings.

File structure as follows:

FABulous_project_template –> project_dir/ fabic_cad/synth –> project_dir/Test/synth

Parameters:

• project_dir (Path) – Directory where the project will be created.

• lang (HDLType, optional) – The language of project to create (“verilog” or “vhdl”), by default “verilog”.

Raises:

• FileNotFoundError – If the template files cannot be found in the package resources.

• ValueError – If an unsupported language is specified.

get_file_path(project_dir, args, file_extension, show_count=0) → str

Get the file path for the specified file extension.

install_fabulator(install_dir) → None

Install FABulator and set FABULATOR_ROOT environment variable.

Clones FABulator into the specified directory by downloading the latest release and sets the FAB_FABULATOR_ROOT environment variable in the global .env file.

Parameters:

install_dir (Path) – The directory where FABulator will be installed.

Raises:

RuntimeError – If the installation fails.

install_oss_cad_suite(destination_folder, update=False) → None

Download and extract the latest OSS CAD Suite.

Set the FAB_OSS_CAD_SUITE environment variable in the .env file.

Parameters:

• destination_folder (Path) – The folder where the OSS CAD Suite will be installed.

• update (bool) – If True, it will update the existing installation if it exists.

Raises:

• ConnectionError – If the download fails or the request to GitHub fails.

• FileExistsError – If the folder already exists and update is not set to True.

• ValueError – If the operating system or architecture is not supported. If no valid archive is found for the current OS and architecture. If the file format of the downloaded archive is unsupported.

make_hex(binfile, outfile) → None

Convert a binary file into hex file.

If the binary file exceeds MAX_BITBYTES, logs error.

Parameters:

• binfile (Path) – Path to binary file.

• outfile (Path) – Path to ouput hex file.

register_tile_in_fabric_csv(csv_path, dst_dir) → None

Append Tile/Supertile entries for dst_dir to csv_path before ParametersEnd.

The CSV paths are written relative to the directory containing csv_path (i.e. the project root), so dst_dir may be anywhere on the filesystem. Detects whether dst_dir is a supertile by checking for sub-directories (excluding macro) inside it.

Parameters:

• csv_path (Path) – Path to the fabric CSV file to update.

• dst_dir (Path) – Directory of the cloned tile.

remove_dir(path) → None

Remove a directory and all its contents.

If the directory cannot be removed, logs OS error.

Parameters:

path (Path) – Path of the directory to remove.

resolve_tile(arg, tile_dir) → Path

Resolve a tile name-or-path argument to a Path.

An argument that is absolute or contains a directory separator is treated as a filesystem path; otherwise it is treated as a bare tile name and looked up under tile_dir.

Parameters:

• arg (str) – Tile name or path supplied by the user.

• tile_dir (Path) – Project Tile/ directory used for name-based lookup.

Returns:

Resolved path (caller must validate existence as appropriate).

run_task(task_name, task_dir, task_vars=None, verbose=False, taskfile=None) → None

Run a Taskfile task using the task CLI.

Parameters:

• task_name (str) – Name of the task to run (e.g. "run-simulation").

• task_dir (Path) – Directory containing the Taskfile.

• task_vars (dict[str, str] | None) – Optional variables to pass to the task (VAR=value).

• verbose (bool) – If True, adds --verbose flag.

• taskfile (str | None) – Explicit Taskfile name (e.g. "compile.Taskfile.yml"). When None, task uses its default lookup (Taskfile.yml).

Raises:

EnvironmentNotSet – If the task binary is not found on PATH.

setup_logger(verbosity, debug, log_file=Path()) → None

Set up the loguru logger with custom formatting based on verbosity level.

Parameters:

• verbosity (int) – The verbosity level for logging. Higher values provide more detailed output. 0: Basic level and message only 1+: Includes timestamp, module name, function, line number

• debug (bool) – If True, sets log level to DEBUG, otherwise sets to INFO.

• log_file (Path) – Path to log file. If provided, logs will be written to file instead of stdout. Default is Path(), which results in logging to stdout.

Notes

This function removes any existing loggers and sets up a new one with custom formatting. The format includes color coding and adjusts based on verbosity level. When FABULOUS_TESTING environment variable is set, uses simplified formatting.

update_project_version(project_dir) → bool

Update the project version in the .env file.

This function reads the current project version from the .env file and updates it to match the currently installed FABulous package version, provided there are no major version mismatches.

Parameters:

project_dir (Path) – The path to the project directory containing the .FABulous/.env file.

Returns:

True if the version was successfully updated, False otherwise.

Notes

The function will refuse to update if there is a major version mismatch between the project version and the package version, as this could indicate incompatibility.

wrap_with_except_handling(fun_to_wrap) → Callable

Wrap function with ‘fun_to_wrap’ with exception handling.

Parameters:

fun_to_wrap (Callable) – The function to be wrapped with exception handling.

Returns:

The wrapped function with exception handling.