fabulous

FABulous command-line interface entry point.

This module provides the main entry point for the FABulous FPGA framework command-line interface. It handles argument parsing, project setup, and CLI initialization.

Attributes

APP_NAME
ForceType
GLOBAL_FLAGS
ProjectDirType
WriterType
app

Classes

NixShell

Shell types supported by the nix development environment.

Functions

check_version_compatibility(_)	Check version compatibility between package and project.
common_options(ctx[, project_dir, _version, verbose, ...])	Provide common options for all FABulous commands.
convert_legacy_args_with_deprecation_warning()	Convert legacy argparse arguments to new Typer commands.
create_project_cmd(project_dir[, writer, overwrite])	Create a new FABulous project.
install_fabulator_cmd([directory])	Install FABulator in the specified directory.
install_nix_cmd()	Install Nix.
install_oss_cad_suite_cmd([directory])	Install the oss-cad-suite in the specified directory.
main()	Entry point for the application.
nix_env_cmd([flake_dir, shell, no_check])	Drop into the Nix development environment with EDA tool verification.
reorder_options(argv)	Reorder global flags to be before subcommands.
run_cmd([commands, force])	Run commands directly in a FABulous project.
script_cmd(script_file[, script_type, force])	Execute a script file with auto-detection of script type.
start_cmd([force])	Start FABulous in interactive mode. Alias: s.
update_project_version_cmd()	Update project version to match package version.
validate_project_directory(value)	Validate the project directory.
version_callback(value)	Print version information and exit.

Module Contents

APP_NAME = 'FABulous'

ForceType

GLOBAL_FLAGS

NixShell

class NixShell

Bases: StrEnum

Shell types supported by the nix development environment.

Initialize self. See help(type(self)) for accurate signature.

ProjectDirType

WriterType

app

check_version_compatibility(_) → None

Check version compatibility between package and project.

common_options(ctx, project_dir=None, _version=None, verbose=0, debug=None, log_file=None, global_dot_env=None, project_dot_env=None) → None

Provide common options for all FABulous commands.

convert_legacy_args_with_deprecation_warning() → None

Convert legacy argparse arguments to new Typer commands.

create_project_cmd(project_dir, writer=HDLType.VERILOG, overwrite=False) → None

Create a new FABulous project.

Alias: c

install_fabulator_cmd(directory=None) → None

Install FABulator in the specified directory.

This will create a new directory FABulator and install the suite there. If the directory already exists, it will be replaced. This also automatically adds the FABULATOR_ROOT env var in the global FABulous .env file.

install_nix_cmd() → None

Install Nix.

install_oss_cad_suite_cmd(directory=None) → None

Install the oss-cad-suite in the specified directory.

This will create a new directory called oss-cad-suite and install the suite there. If the directory already exists, it will be replaced. This also automatically adds the FAB_OSS_CAD_SUITE env var in the global FABulous .env file.

main() → None

Entry point for the application.

nix_env_cmd(flake_dir=None, shell=None, no_check=False) → None

Drop into the Nix development environment with EDA tool verification.

Enters a Nix dev shell and verifies that yosys, nextpnr, and openroad are installed and sourced from the Nix store. Use –no-check to skip the verification step.

reorder_options(argv) → list[str]

Reorder global flags to be before subcommands.

Rules:

• Only flags whose (base) token (before any ‘=’) is in GLOBAL_FLAGS are moved.

• Supports both –opt=value and –opt value forms (second handled heuristically: if the next token does not start with ‘-’ it is treated as that flag’s value).

• Flags already before the subcommand are left untouched.

• Order among moved flags is preserved relative to their appearance after the subcommand.

• If no registered subcommand is present, argv is returned unchanged.

run_cmd(commands=None, force=False) → None

Run commands directly in a FABulous project.

Alias: r

script_cmd(script_file, script_type='tcl', force=False) → None

Execute a script file with auto-detection of script type.

Automatically detects whether the script is a FABulous (.fab, .fs) or TCL (.tcl) script based on file extension and content. You can override the detection with –type.

If no project directory is specified, uses the current directory.

start_cmd(force=False) → None

Start FABulous in interactive mode. Alias: s.

This is the main command for running FABulous in interactive mode or with scripts. If no project directory is specified, uses the current directory.

update_project_version_cmd() → None

Update project version to match package version.

validate_project_directory(value) → Path | None

Validate the project directory.

version_callback(value) → None

Print version information and exit.