FABulous.FABulous_CLI.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.
Classes#
- class CommandPipeline(cli_instance, force=False)[source]#
Helper class to manage command execution with error handling.
Initialize the command pipeline.
- Parameters:
cli_instance (FABulous_CLI) – The CLI instance to use for command execution.
force (bool)
Methods:
- add_step(command, error_message='Command failed')[source]#
Add a command step to the pipeline.
- Parameters:
- Returns:
Returns self to allow method chaining.
- Return type:
- execute()[source]#
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.
- Return type:
- Raises:
PipelineCommandError – If any command in the pipeline fails during execution.
Functions#
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.
- param func:
The function to be wrapped.
- type func:
Callable
- returns:
The wrapped function that can handle missing arguments.
- rtype:
Callable
Clone or update a GitHub repository.
- param repo_url:
GitHub repository URL (e.g., “user/repo.git”)
- type repo_url:
str
- param target_dir:
Local directory to clone/download to
- type target_dir:
Path
- param branch:
Git branch to checkout (default: “main”)
- type branch:
str
- rtype:
True if successful, False otherwise
- raises FileNotFoundError:
If git application not found in PATH
Copy all Verilog files from source directory to the destination directory.
- param src:
Source directory.
- type src:
str
- param dst:
Destination directory
- type dst:
str
- create_project(project_dir, lang='verilog')[source]#
- Parameters:
project_dir (Path)
lang (Literal['verilog', 'vhdl'])
- Return type:
None
Create a FABulous project containing all required files.
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
- param project_dir:
Directory where the project will be created.
- type project_dir:
Path
- param lang:
The language of project to create (“verilog” or “vhdl”), by default “verilog”.
- type lang:
Literal[“verilog”, “vhdl”], optional
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.
- param install_dir:
The directory where FABulator will be installed.
- type install_dir:
Path
Download and extract the latest OSS CAD Suite.
Set the FAB_OSS_CAD_SUITE environment variable in the .env file.
- param destination_folder:
The folder where the OSS CAD Suite will be installed.
- type destination_folder:
Path
- param update:
If True, it will update the existing installation if it exists.
- type update:
bool
- raises FileExistsError:
If the folder already exists and update is not set to True.
- raises requests.RequestException:
If the download fails or the request to GitHub fails.
- raises 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.
Convert a binary file into hex file.
If the binary file exceeds MAX_BITBYTES, logs error.
- param binfile:
Path to binary file.
- type binfile:
str
- param outfile:
Path to ouput hex file.
- type outfile:
str
Remove a directory and all its contents.
If the directory cannot be removed, logs OS error.
- param path:
Path of the directory to remove.
- type path:
str
Set up the loguru logger with custom formatting based on verbosity level.
- param verbosity:
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
- type verbosity:
int
- param debug:
If True, sets log level to DEBUG, otherwise sets to INFO.
- type debug:
bool
- param log_file:
Path to log file. If provided, logs will be written to file instead of stdout. Default is Path(), which results in logging to stdout.
- type log_file:
pathlib.Path, optional
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 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.
- param project_dir:
The path to the project directory containing the .FABulous/.env file.
- type project_dir:
Path
- returns:
True if the version was successfully updated, False otherwise.
- rtype:
bool
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 function with ‘fun_to_wrap’ with exception handling.
- param fun_to_wrap:
The function to be wrapped with exception handling.
- type fun_to_wrap:
callable
Module Attributes#
- MAX_BITBYTES[source]