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¶
Classes¶
|
Helper class to manage command execution with error handling. |
Functions¶
|
Allow function to be called with blank arguments. |
|
Clone or update a GitHub repository. |
|
Copy all Verilog files from source directory to the destination directory. |
|
Create a FABulous project containing all required files. |
|
Get the file path for the specified file extension. |
|
Install FABulator and set FABULATOR_ROOT environment variable. |
|
Download and extract the latest OSS CAD Suite. |
|
Convert a binary file into hex file. |
|
Remove a directory and all its contents. |
|
Set up the loguru logger with custom formatting based on verbosity level. |
|
Update the project version in the .env file. |
|
Wrap function with 'fun_to_wrap' with exception handling. |
Module Contents¶
CommandPipeline¶
- CommandPipeline(cli_instance, force = False) :module:
Helper class to manage command execution with error handling.
- param cli_instance:
The CLI instance to use for command execution.
- type cli_instance:
FABulous_CLI
- param force:
If True, continues executing commands even if one fails.
- type force:
bool
- add_stepcommand, error_message = 'Command failed' :module:
Add a command step to the pipeline.
- param command:
The command string to execute.
- type command:
str
- param error_message:
Custom error message to use if the command fails. Defaults to “Command failed”.
- type error_message:
str, optional
- returns:
Returns self to allow method chaining.
- rtype:
CommandPipeline
- execute :module:
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.
- rtype:
bool
- raises PipelineCommandError:
If any command in the pipeline fails during execution.
- execute_parallel :module:
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 :module:
Get the final exit code from pipeline execution.
- allow_blank(func)[source]¶
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.
- Return type:
Callable
- clone_git_repo(repo_url, target_dir, branch='main')[source]¶
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
- Return type:
- Raises:
FileNotFoundError – If git application not found in PATH
- copy_verilog_files(src, dst)[source]¶
Copy all Verilog files from source directory to the destination directory.
- Parameters:
src (Path) – Source directory.
dst (Path) – Destination directory
- Return type:
None
- create_project(project_dir, lang=HDLType.VERILOG)[source]¶
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.
- Return type:
None
- get_file_path(project_dir, args, file_extension, show_count=0)[source]¶
Get the file path for the specified file extension.
- install_fabulator(install_dir)[source]¶
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.
- Return type:
None
- install_oss_cad_suite(destination_folder, update=False)[source]¶
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.
- Return type:
None
- make_hex(binfile, outfile)[source]¶
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.
- Return type:
None
- remove_dir(path)[source]¶
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.
- Return type:
None
- setup_logger(verbosity, debug, log_file=Path())[source]¶
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.
- Return type:
None
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)[source]¶
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.
- Return type:
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.