FABulous.FABulous_CLI.helper ============================ .. py:module:: FABulous.FABulous_CLI.helper .. autoapi-nested-parse:: 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 ------- .. py:class:: CommandPipeline(cli_instance, force = False) Helper class to manage command execution with error handling. Initialize the command pipeline. :param cli_instance: The CLI instance to use for command execution. :type cli_instance: FABulous_CLI **Methods:** .. py:method:: add_step(command, error_message = 'Command failed') 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 .. py:method:: execute() 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. .. py:method:: get_exit_code() Get the final exit code from pipeline execution. Functions --------- .. py:function:: allow_blank(func) 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 .. py:function:: clone_git_repo(repo_url, target_dir, branch = 'main') Clone or update a GitHub repository. :param repo_url: GitHub repository URL (e.g., "https://github.com/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 .. py:function:: copy_verilog_files(src, dst) 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 .. py:function:: create_project(project_dir, lang = 'verilog') 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 .. py:function:: install_fabulator(install_dir) 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 .. py:function:: install_oss_cad_suite(destination_folder, update = False) 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. .. py:function:: make_hex(binfile, outfile) 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 .. py:function:: remove_dir(path) 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 .. py:function:: setup_logger(verbosity, debug, log_file = Path()) 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 .. rubric:: 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. .. py:function:: update_project_version(project_dir) 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 .. rubric:: 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. .. py:function:: wrap_with_except_handling(fun_to_wrap) 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 ----------------- .. py:data:: MAX_BITBYTES :no-index: