ohsh 0.1.0__py3-none-any.whl

ohsh/__init__.py

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: Apache-2.0
+"""ohsh (Ola's HDL Source Handler).
+
+Finds the ``manifest.json`` files under a project directory, resolves the
+dependencies of a top-level module, and writes each library's source files in
+compile order, plus the order to compile the libraries in.
+
+Example manifest file (``manifest.json``)::
+
+    {
+        "module": "module_name",
+        "sources": [
+            "source1.v",
+            "source2.v",
+            "source3.v"
+        ],
+        "dependencies": {
+            "work": ["module1", "module2"],
+            "lib_name": ["module3"]
+        }
+    }
+"""
+
+__version__ = "0.1.0"

ohsh/__main__.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: Apache-2.0
+from .cli import main
+
+main()

ohsh/cli.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: Apache-2.0
+
+import argparse
+import pathlib
+
+from . import __version__
+from .core import run
+from .utils import EXIT_CODE_DESCRIPTIONS, configure_logging
+
+
+def log_file_path(value):
+    path = pathlib.Path(value)
+    if not path.parent.is_dir():
+        raise argparse.ArgumentTypeError(f"directory does not exist: {path.parent}")
+    return path
+
+
+def format_exit_codes():
+    lines = [f"  {code:>3}  {description}" for code, description in EXIT_CODE_DESCRIPTIONS.items()]
+    return "exit codes:\n" + "\n".join(lines)
+
+
+def build_parser(cwd):
+    parser = argparse.ArgumentParser(
+        prog="ohsh",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=format_exit_codes(),
+        description="Resolve HDL module manifests into ordered, per-library source lists.",
+    )
+    parser.add_argument("module", help="name of the top-level module")
+    parser.add_argument(
+        "-t",
+        "--top-dir",
+        default=cwd,
+        help="directory to search for manifest files (default: current directory)",
+    )
+    parser.add_argument(
+        "-w",
+        "--work",
+        default="work",
+        help="library for the top module, which 'work' in its manifest refers to (default: work)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        default=cwd,
+        help="directory for the .src lists and libraries.src, created if missing (default: current directory)",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="count",
+        default=0,
+        help="show progress (-v) or debug details (-vv), otherwise only warnings and errors",
+    )
+    parser.add_argument(
+        "--log-file",
+        type=log_file_path,
+        default=None,
+        metavar="PATH",
+        help="also write debug logs to this file",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    return parser
+
+
+def main():
+    cwd = pathlib.Path.cwd()
+    parser = build_parser(cwd)
+    args = parser.parse_args()
+    # Only the command line configures logging, so programs that call run()
+    # directly keep control of where ohsh log messages go.
+    configure_logging(verbosity=args.verbose, log_file=args.log_file)
+    run(args, cwd)

ohsh/core.py

@@ -0,0 +1,201 @@
+# SPDX-License-Identifier: Apache-2.0
+import json
+import logging
+import pathlib
+import sys
+
+from .utils import (
+    EXIT_CANNOT_CREATE_OUTPUT,
+    EXIT_CIRCULAR_DEPENDENCY,
+    EXIT_DATA_ERROR,
+    EXIT_DUPLICATE_MODULE,
+    EXIT_MANIFEST_NOT_FOUND,
+    EXIT_MODULE_NOT_FOUND,
+    EXIT_NO_INPUT,
+    CircularDependencyError,
+    InvalidManifestError,
+    MissingManifestError,
+    discover_manifests,
+    extract_dependencies,
+    find_duplicate_modules,
+    find_manifest,
+    order_libraries,
+    to_absolute_path,
+    validate_manifest,
+    validate_top_dir,
+)
+
+VERILOG_EXTENSIONS = {".v", ".sv", ".svp", ".vh", ".svh"}
+VHDL_EXTENSIONS = {".vhd", ".vhdl", ".vo"}
+
+LIBRARY_ORDER_FILE_NAME = "libraries.src"
+
+logger = logging.getLogger(__name__)
+
+
+def _exit_with_error(message, code):
+    logger.error(message)
+    sys.exit(code)
+
+
+def run(args, cwd):
+    module = args.module
+    top_dir = args.top_dir
+    work = args.work
+
+    # If the top-level directory is a relative path, make it absolute.
+    top_dir = to_absolute_path(cwd, top_dir)
+
+    # Check if top-level is a directory and exists
+    if not validate_top_dir(top_dir):
+        _exit_with_error(
+            f"The specified top-level directory {top_dir} does not exist or is not a directory.",
+            EXIT_NO_INPUT,
+        )
+
+    # Find all files named "manifest.json" in the current working directory
+    all_manifest_files = discover_manifests(top_dir)
+
+    # parse all manifest files
+    manifest_data = []
+    for manifest_file in all_manifest_files:
+        try:
+            with open(manifest_file, encoding="utf-8") as file:
+                data = json.load(file)
+            validate_manifest(data)
+        except (json.JSONDecodeError, UnicodeDecodeError) as e:
+            _exit_with_error(f"Error parsing JSON from {manifest_file}: {e}", EXIT_DATA_ERROR)
+        except InvalidManifestError as e:
+            _exit_with_error(f"Invalid manifest {manifest_file}: {e}", EXIT_DATA_ERROR)
+        except OSError as e:
+            _exit_with_error(f"File error reading {manifest_file}: {e}", EXIT_NO_INPUT)
+        data["manifest_path"] = str(manifest_file.resolve())
+        manifest_data.append(data)
+        logger.debug(f"Parsed manifest file: {manifest_file}")
+
+    # Every lookup by module name below relies on the names being unique.
+    duplicates = find_duplicate_modules(manifest_data)
+    if duplicates:
+        listing = "\n".join(
+            f"  {name}: {', '.join(sorted(paths))}" for name, paths in sorted(duplicates.items())
+        )
+        _exit_with_error(
+            f"Each module must be declared in exactly one manifest, but these are not:\n{listing}",
+            EXIT_DUPLICATE_MODULE,
+        )
+
+    top_manifest = find_manifest(manifest_data, module)
+    if top_manifest is None:
+        _exit_with_error(
+            f"The specified module {module} was not found in any manifest.", EXIT_MODULE_NOT_FOUND
+        )
+    logger.debug(f"Found module {module} in manifest.")
+
+    # Extract dependencies recursively
+    try:
+        dependencies = extract_dependencies(manifest_data, top_manifest, work)
+    except CircularDependencyError as e:
+        _exit_with_error(f"Circular dependency detected: {e}", EXIT_CIRCULAR_DEPENDENCY)
+    except MissingManifestError as e:
+        _exit_with_error(f"Missing dependency: {e}", EXIT_MANIFEST_NOT_FOUND)
+
+    # Remove duplicate entries
+    dependencies = list(dict.fromkeys(dependencies))
+    logger.debug(f"Dependencies for module {module}: {dependencies}")
+
+    # Append the top manifest module with the work library to the dependencies list
+    dependencies.append((work, module))
+
+    logger.debug(f"Complete module list: {dependencies}")
+
+    library_order = order_libraries(manifest_data, dependencies)
+    logger.info(f"Library compile order: {', '.join(library_order)}")
+
+    # Extract source file list from all modules in the final dependencies list
+    source_files_by_lib = {}
+    for lib_name, module in dependencies:
+        # Separate Verilog and VHDL files
+        verilog_sources = []
+        vhdl_sources = []
+
+        manifest = find_manifest(manifest_data, module)
+        manifest_path = pathlib.Path(manifest["manifest_path"]).parent
+        sources = [str(manifest_path / source) for source in manifest.get("sources", [])]
+        for source in sources:
+            extension = pathlib.Path(source).suffix.lower()
+            if extension in VERILOG_EXTENSIONS:
+                verilog_sources.append(source)
+            elif extension in VHDL_EXTENSIONS:
+                vhdl_sources.append(source)
+            else:
+                logger.warning(f"Skipping {source} in module {module}: unknown file extension")
+
+        # If the library already exists in the source_files_by_lib dictionary, append the source files
+        if lib_name in source_files_by_lib:
+            source_files_by_lib[lib_name]["verilog"].extend(verilog_sources)
+            source_files_by_lib[lib_name]["vhdl"].extend(vhdl_sources)
+        else:  # Otherwise, create a new entry in the dictionary and add the source files
+            source_files_by_lib[lib_name] = {
+                "verilog": verilog_sources,
+                "vhdl": vhdl_sources,
+            }
+
+    # Remove duplicate source files while preserving order within each library
+    for lib_name, sources in source_files_by_lib.items():
+        sources["verilog"] = list(dict.fromkeys(sources["verilog"]))
+        sources["vhdl"] = list(dict.fromkeys(sources["vhdl"]))
+        logger.debug(
+            f"Source files for library {lib_name}: Verilog: {sources['verilog']}, VHDL: {sources['vhdl']}"
+        )
+
+    # Check that all source files exist
+    missing_files = []
+    for source_files in source_files_by_lib.values():
+        for source_file in source_files["verilog"] + source_files["vhdl"]:
+            if not pathlib.Path(source_file).exists():
+                missing_files.append(source_file)
+
+    if missing_files:
+        _exit_with_error(f"The following source files do not exist: {missing_files}", EXIT_NO_INPUT)
+
+    source_files_by_lib = {lib_name: source_files_by_lib[lib_name] for lib_name in library_order}
+
+    # Write the source files to output files, one file per library
+    output_dir = pathlib.Path(args.output)
+    try:
+        output_dir.mkdir(parents=True, exist_ok=True)
+    except OSError as e:
+        _exit_with_error(
+            f"Cannot create output directory {output_dir}: {e}", EXIT_CANNOT_CREATE_OUTPUT
+        )
+    for lib_name, source_files in source_files_by_lib.items():
+        verilog_output_file = output_dir / f"{lib_name}_verilog.src"
+        vhdl_output_file = output_dir / f"{lib_name}_vhdl.src"
+
+        if source_files["verilog"]:
+            with open(verilog_output_file, "w", encoding="utf-8") as f:
+                for source_file in source_files["verilog"]:
+                    f.write(f"{source_file}\n")
+            logger.info(
+                f"Wrote {len(source_files['verilog'])} Verilog files for library {lib_name} "
+                f"to {verilog_output_file}"
+            )
+        else:
+            logger.debug(f"No Verilog source files for library {lib_name}, skipping file creation.")
+
+        if source_files["vhdl"]:
+            with open(vhdl_output_file, "w", encoding="utf-8") as f:
+                for source_file in source_files["vhdl"]:
+                    f.write(f"{source_file}\n")
+            logger.info(
+                f"Wrote {len(source_files['vhdl'])} VHDL files for library {lib_name} "
+                f"to {vhdl_output_file}"
+            )
+        else:
+            logger.debug(f"No VHDL source files for library {lib_name}, skipping file creation.")
+
+    library_order_file = output_dir / LIBRARY_ORDER_FILE_NAME
+    with open(library_order_file, "w", encoding="utf-8") as f:
+        for lib_name in library_order:
+            f.write(f"{lib_name}\n")
+    logger.info(f"Wrote library compile order to {library_order_file}")

ohsh/utils.py

@@ -0,0 +1,242 @@
+# SPDX-License-Identifier: Apache-2.0
+
+import logging
+import pathlib
+
+logger = logging.getLogger(__name__)
+
+CONSOLE_HANDLER_NAME = "ohsh-console"
+CONSOLE_LEVEL_BY_VERBOSITY = {0: logging.WARNING, 1: logging.INFO}
+
+# Exit codes follow the Unix conventions where one exists: 1 for a general
+# error, 2 for usage errors (raised by argparse), and BSD sysexits.h (64-78) for
+# bad input and output. Errors specific to ohsh start at 100, clear of those
+# ranges and of the 126+ codes that shells reserve.
+EXIT_SUCCESS = 0
+EXIT_UNEXPECTED_ERROR = 1
+EXIT_USAGE = 2
+EXIT_DATA_ERROR = 65
+EXIT_NO_INPUT = 66
+EXIT_CANNOT_CREATE_OUTPUT = 73
+EXIT_MODULE_NOT_FOUND = 100
+EXIT_MANIFEST_NOT_FOUND = 101
+EXIT_CIRCULAR_DEPENDENCY = 102
+EXIT_DUPLICATE_MODULE = 103
+
+EXIT_CODE_DESCRIPTIONS = {
+    EXIT_SUCCESS: "success",
+    EXIT_UNEXPECTED_ERROR: "unexpected error",
+    EXIT_USAGE: "invalid command-line arguments",
+    EXIT_DATA_ERROR: "a manifest is not valid JSON or has the wrong structure",
+    EXIT_NO_INPUT: "top directory, manifest or source file missing or unreadable",
+    EXIT_CANNOT_CREATE_OUTPUT: "output directory cannot be created",
+    EXIT_MODULE_NOT_FOUND: "top module not found in any manifest",
+    EXIT_MANIFEST_NOT_FOUND: "a dependency has no manifest",
+    EXIT_CIRCULAR_DEPENDENCY: "modules depend on each other in a loop",
+    EXIT_DUPLICATE_MODULE: "a module name is declared in more than one manifest",
+}
+
+
+class CircularDependencyError(Exception):
+    def __init__(self, cycle):
+        self.cycle = cycle
+        super().__init__(" -> ".join(cycle))
+
+
+class MissingManifestError(Exception):
+    def __init__(self, module, required_by):
+        self.module = module
+        self.required_by = required_by
+        super().__init__(f"no manifest found for module {module} (required by {required_by})")
+
+
+class InvalidManifestError(Exception):
+    pass
+
+
+def _is_list_of_strings(value):
+    return isinstance(value, list) and all(isinstance(item, str) for item in value)
+
+
+def validate_manifest(manifest):
+    """Raise ``InvalidManifestError`` naming the first structural problem in ``manifest``.
+
+    ``sources`` and ``dependencies`` are optional. Unknown keys are ignored.
+    """
+    if not isinstance(manifest, dict):
+        raise InvalidManifestError("the top level must be a JSON object")
+    if not isinstance(manifest.get("module"), str) or not manifest["module"]:
+        raise InvalidManifestError('"module" must be a non-empty string')
+    if not _is_list_of_strings(manifest.get("sources", [])):
+        raise InvalidManifestError('"sources" must be a list of file names')
+    dependencies = manifest.get("dependencies", {})
+    if not isinstance(dependencies, dict) or not all(
+        _is_list_of_strings(modules) for modules in dependencies.values()
+    ):
+        raise InvalidManifestError('"dependencies" must map library names to lists of module names')
+
+
+def find_duplicate_modules(manifest_data):
+    """Return {module: [manifest paths]} for every module declared more than once."""
+    paths_by_module = {}
+    for manifest in manifest_data:
+        paths_by_module.setdefault(manifest["module"], []).append(manifest["manifest_path"])
+    return {module: paths for module, paths in paths_by_module.items() if len(paths) > 1}
+
+
+def find_manifest(manifest_data, module):
+    return next((m for m in manifest_data if m.get("module") == module), None)
+
+
+def resolve_library_name(declared_library, current_library):
+    # In a manifest, 'work' means the library the module itself is compiled into.
+    return current_library if declared_library == "work" else declared_library
+
+
+def extract_dependencies(manifest_data, top_manifest, work):
+    """Return every module ``top_manifest`` depends on, directly or indirectly.
+
+    The result is a list of (library, module) pairs in compile order: each module
+    comes after all the modules it depends on, and each pair appears once. The
+    top module itself is not included. A circular dependency has no valid compile
+    order, so it raises ``CircularDependencyError`` naming the modules in the cycle.
+    A dependency without a manifest raises ``MissingManifestError``.
+    """
+    collected_deps = []
+    dependency_chain = []
+    resolved = set()
+
+    def _collect_dependencies_of(manifest, library):
+        module_name = manifest.get("module")
+        # The same module reached through another library resolves its 'work'
+        # dependencies differently, so only skip exact (library, module) repeats.
+        if (library, module_name) in resolved:
+            return
+        logger.debug(f"Extracting dependencies for {module_name}")
+        dependency_chain.append(module_name)
+
+        for lib_name, modules in manifest.get("dependencies", {}).items():
+            lib_name = resolve_library_name(lib_name, library)
+            for module in modules:
+                logger.debug(f"Processing dependency {module} in library {lib_name}")
+                if module in dependency_chain:
+                    cycle_start = dependency_chain.index(module)
+                    raise CircularDependencyError(dependency_chain[cycle_start:] + [module])
+
+                # Recurse first so deeper dependencies are collected before this one.
+                dep_manifest = find_manifest(manifest_data, module)
+                if dep_manifest is None:
+                    raise MissingManifestError(module, required_by=module_name)
+                _collect_dependencies_of(dep_manifest, lib_name)
+
+                dep_tuple = (lib_name, module)
+                if dep_tuple not in collected_deps:
+                    collected_deps.append(dep_tuple)
+
+        dependency_chain.pop()
+        resolved.add((library, module_name))
+
+    _collect_dependencies_of(top_manifest, work)
+    return collected_deps
+
+
+def order_libraries(manifest_data, dependencies):
+    """Return the libraries used in ``dependencies`` in compile order.
+
+    Each library comes after the libraries its modules depend on. When libraries
+    depend on each other in a loop, no such order exists: a warning names the loop
+    and a best-effort order is returned, which tools that sort files themselves
+    can still use.
+    """
+    libraries = list(dict.fromkeys(library for library, _ in dependencies))
+    used_libraries = {library: set() for library in libraries}
+    for library, module in dependencies:
+        manifest = find_manifest(manifest_data, module)
+        for declared_library, modules in manifest.get("dependencies", {}).items():
+            used_library = resolve_library_name(declared_library, library)
+            if modules and used_library != library:
+                used_libraries[library].add(used_library)
+
+    ordered = []
+    while len(ordered) < len(libraries):
+        remaining = [library for library in libraries if library not in ordered]
+        ready = [library for library in remaining if used_libraries[library] <= set(ordered)]
+        if not ready:
+            loop = _find_library_loop(remaining[0], used_libraries, ordered)
+            logger.warning(
+                f"Libraries depend on each other in a loop ({' -> '.join(loop)}), so no "
+                "library order is valid. Writing a best-effort order: tools that compile "
+                "one library at a time may fail."
+            )
+            ready = remaining
+        ordered.append(ready[0])
+    return ordered
+
+
+def _find_library_loop(start, used_libraries, ordered):
+    # Every library still unordered uses at least one other unordered library,
+    # so following those edges from any of them must eventually revisit one.
+    path = [start]
+    while True:
+        next_library = min(used_libraries[path[-1]] - set(ordered))
+        if next_library in path:
+            return path[path.index(next_library) :] + [next_library]
+        path.append(next_library)
+
+
+def validate_top_dir(top_dir):
+    return pathlib.Path(top_dir).is_dir()
+
+
+def to_absolute_path(cwd, path):
+    """Return ``path`` as an absolute path, resolving a relative one against ``cwd``."""
+    path = pathlib.Path(path)
+    if not path.is_absolute():
+        return (pathlib.Path(cwd) / path).resolve()
+    return path
+
+
+def configure_logging(verbosity=0, log_file=None):
+    """Configure logging for the ``ohsh`` package.
+
+    Handlers are attached to the package logger (``ohsh``) so that messages from
+    every submodule are captured. Console output goes to stderr and shows
+    warnings and errors only, INFO messages with ``verbosity`` 1, and DEBUG
+    messages with 2 or more. A file handler, which always records DEBUG, is only
+    added when ``log_file`` is given.
+    """
+    pkg_logger = logging.getLogger("ohsh")
+    pkg_logger.setLevel(logging.DEBUG)
+    # Our handlers already emit everything, so a root handler set up by the
+    # host application (e.g. logging.basicConfig) would print each line twice.
+    pkg_logger.propagate = False
+
+    # Avoid attaching duplicate handlers if called more than once. Look for our
+    # own handler by name: other code (e.g. pytest capture) may attach its own.
+    if any(h.get_name() == CONSOLE_HANDLER_NAME for h in pkg_logger.handlers):
+        return pkg_logger
+
+    formatter = logging.Formatter("ohsh - %(levelname)s - %(message)s")
+
+    console_handler = logging.StreamHandler()
+    console_handler.set_name(CONSOLE_HANDLER_NAME)
+    console_handler.setLevel(CONSOLE_LEVEL_BY_VERBOSITY.get(verbosity, logging.DEBUG))
+    console_handler.setFormatter(formatter)
+    pkg_logger.addHandler(console_handler)
+
+    if log_file:
+        file_handler = logging.FileHandler(log_file)
+        file_handler.setLevel(logging.DEBUG)
+        file_handler.setFormatter(formatter)
+        pkg_logger.addHandler(file_handler)
+
+    return pkg_logger
+
+
+def discover_manifests(top_dir):
+    logger.debug(f"Discovering manifest files in {top_dir}")
+    manifest_files = list(pathlib.Path(top_dir).rglob("manifest*.json"))
+    for manifest in manifest_files:
+        logger.debug(f"Found manifest file: {manifest}")
+    logger.info(f"Found {len(manifest_files)} manifest files in {top_dir}")
+    return manifest_files

ohsh-0.1.0.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: ohsh
+Version: 0.1.0
+Summary: Resolve HDL module manifests into ordered, per-library source lists and a library compile order.
+Author: Ola Groettvik
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/logvik-org/ohsh
+Project-URL: Repository, https://github.com/logvik-org/ohsh
+Project-URL: Issues, https://github.com/logvik-org/ohsh/issues
+Project-URL: Changelog, https://github.com/logvik-org/ohsh/blob/main/CHANGELOG.md
+Keywords: hdl,verilog,vhdl,systemverilog,fpga,eda,dependency,manifest,hog
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0; extra == "dev"
+Provides-Extra: examples
+Requires-Dist: cocotb==2.1.0; extra == "examples"
+Requires-Dist: vunit-hdl==4.7.1; extra == "examples"
+Dynamic: license-file
+
+# ohsh - Ola's HDL Source Handler
+
+[![CI](https://github.com/logvik-org/ohsh/actions/workflows/ci.yml/badge.svg)](https://github.com/logvik-org/ohsh/actions/workflows/ci.yml)
+[![Integrations](https://github.com/logvik-org/ohsh/actions/workflows/integration.yml/badge.svg)](https://github.com/logvik-org/ohsh/actions/workflows/integration.yml)
+[![PyPI](https://img.shields.io/pypi/v/ohsh.svg)](https://pypi.org/project/ohsh/)
+[![Python](https://img.shields.io/pypi/pyversions/ohsh.svg)](https://pypi.org/project/ohsh/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/logvik-org/ohsh/blob/main/LICENSE)
+
+**ohsh** is a small, deliberately humble command-line tool that figures out, in
+the right order, which HDL (Verilog / SystemVerilog / VHDL) source files your
+design needs - by reading simple per-module `manifest.json` files and resolving
+their dependencies.
+
+It is a *companion* to the big build flows (like [hog](https://hog.readthedocs.io),
+Vivado, Quartus, Questa, cocotb, VUnit, …), not a replacement for them. ohsh
+just answers one question well - *"what files, in what order, for which
+libraries?"* - and hands you plain `.src` lists you can feed anywhere.
+
+> So simple it's an *oh sh… that was easy* moment. 🙂
+
+---
+
+## Features
+
+- 🔍 Auto-discovers HDL module manifests anywhere under a project tree.
+- 📂 Resolves module dependencies recursively, across libraries.
+- 🔁 Detects circular dependencies and exits with an error naming the cycle.
+- 📝 Emits ordered, per-library source lists for Verilog and VHDL.
+- 📚 Writes the order to compile the libraries in.
+- ✅ Validates that every referenced source file actually exists.
+- 🐍 Pure Python, zero runtime dependencies.
+
+## Installation
+
+```bash
+pip install ohsh
+```
+
+Or from a clone:
+
+```bash
+git clone https://github.com/logvik-org/ohsh.git
+cd ohsh
+pip install .
+```
+
+## Usage
+
+```bash
+ohsh [OPTIONS] MODULE
+```
+
+ohsh will:
+1. Search for all `manifest*.json` files starting from `--top-dir`.
+2. Resolve dependencies for `MODULE` (the top-level).
+3. Generate ordered Verilog and VHDL source lists per library.
+4. Write them as `<lib>_verilog.src` / `<lib>_vhdl.src` in the output directory.
+5. Write the library compile order to `libraries.src`.
+
+### Options
+
+| Option              | Description                                                            | Default      |
+|---------------------|------------------------------------------------------------------------|--------------|
+| `-t`, `--top-dir`   | Project top-level directory, the base for manifest discovery.          | cwd          |
+| `-w`, `--work`      | Library for the top module, which `work` in its manifest refers to.    | `work`       |
+| `-o`, `--output`    | Directory for the `.src` lists and `libraries.src`, created if missing. | cwd          |
+| `-v`, `--verbose`   | Show progress (`-v`) or debug details (`-vv`).                         | quiet        |
+| `--log-file PATH`   | Also write logs to a file (no log file is written by default).         | none         |
+| `--version`         | Print version and exit.                                                |              |
+| `-h`, `--help`      | Show help and exit.                                                    |              |
+
+### Example
+
+```bash
+ohsh -t /path/to/hdl_project -w mylib -o ./src_lists top_module
+```
+
+Produces:
+
+```
+src_lists/
+├── libraries.src
+├── mylib_verilog.src
+└── mylib_vhdl.src
+```
+
+Each `<lib>_verilog.src` / `<lib>_vhdl.src` file contains absolute paths to the
+source files, one per line, in compilation order.
+
+`libraries.src` lists the library names, one per line, in the order to compile
+them: each library comes after the libraries it uses. Compile the libraries in
+this order rather than hard-coding it. If libraries depend on each other in a
+loop (a module in `libA` uses `libB` and a module in `libB` uses `libA`), no
+such order exists. ohsh then logs a warning and writes a best-effort order,
+which works for tools that sort files themselves (such as Vivado or Quartus
+projects) but may fail with tools that compile one library at a time.
+
+## Documentation
+
+- [Manifest file format](https://github.com/logvik-org/ohsh/blob/main/docs/manifest-format.md)
+- [Exit codes](https://github.com/logvik-org/ohsh/blob/main/docs/exit-codes.md)
+- [Integrations with simulators and build tools](https://github.com/logvik-org/ohsh/blob/main/docs/integrations.md)
+- [Contributing and development](https://github.com/logvik-org/ohsh/blob/main/CONTRIBUTING.md)
+
+## License
+
+Licensed under the **Apache License 2.0**. See [LICENSE](https://github.com/logvik-org/ohsh/blob/main/LICENSE) and
+[NOTICE](https://github.com/logvik-org/ohsh/blob/main/NOTICE).
+
+## Author
+
+**Ola Groettvik** - [GitHub](https://github.com/olagrottvik)
+
+Contributions, issues, and suggestions are welcome!

ohsh-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+ohsh/__init__.py,sha256=SUwu4cC9AvJ5ygpbvCf_OdlXrcFqKsm8KcUW9PVELH8,626
+ohsh/__main__.py,sha256=joODZGnsQelRyR4fxFIThmMeoZDCwcNUjHraEK0Rrcc,68
+ohsh/cli.py,sha256=_Q11w30QSoDAwm5AgW0rmvG-UJmlVLbCkugsRPOR4Ak,2301
+ohsh/core.py,sha256=w3HhaF8OHQi6TLutLJP-QS1nIi4Q_d8FFKVTa-CEIYk,7932
+ohsh/utils.py,sha256=x4gCFF9-JvCBsA1WBTNzaxWOJh11L-ngn7Rm2eYtw9Y,10076
+ohsh-0.1.0.dist-info/licenses/LICENSE,sha256=zWm71hiYF505c5M38iGCPUfT3ZiyIHtJpdU_3BSTMV4,11348
+ohsh-0.1.0.dist-info/licenses/NOTICE,sha256=nWvVPkA-v_U_iOMLDgVhUuXVCAxJGzAt9fWUXSZuLuc,344
+ohsh-0.1.0.dist-info/METADATA,sha256=SjQr0sUbiVAkmVnYyNpSyfnCOklpx1V8pJzAhWAUdfE,6593
+ohsh-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ohsh-0.1.0.dist-info/entry_points.txt,sha256=PsMSxOQ_FVtCksSjd33iMpgFAXwprS6sAcTuhuXl-30,39
+ohsh-0.1.0.dist-info/top_level.txt,sha256=7j-bMBksgpWmaP9J1OH6R5a0rd23Cueg2fCVyFD9ZS0,5
+ohsh-0.1.0.dist-info/RECORD,,

ohsh-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ohsh-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ohsh = ohsh.cli:main

ohsh-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2024-2026 Ola Groettvik
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

ohsh-0.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,10 @@
+ohsh - Ola's HDL Source Handler
+Copyright 2024-2026 Ola Groettvik
+
+This product includes software developed by Ola Groettvik.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0

ohsh-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ohsh