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.
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.
remove_dir(path)	Remove a directory and all its contents.
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

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.

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.

run_task(task_name, task_dir, task_vars=None, verbose=False) → 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.yml.

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

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

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.