Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 26 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,32 @@

All notable changes to this project are documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [PEP 440](https://peps.python.org/pep-0440/) for
version identifiers (`.devN` marks a development pre-release).

## [0.3.0.dev1] - 2026-07-18

### Added
- `AnalysisResult.format_compile_order()` returns the human-readable,
tree-indented compile-order listing as a string, and
`AnalysisResult.print_compile_order()` prints it -- the same output the CLI
emits. `AnalysisResult` now retains the underlying `SourceFile` order (a
non-serialized `source_files` field; `to_dict()` is unchanged). The shared
rendering logic lives in `output.format_compile_order`.

## [0.3.0.dev0] - 2026-07-18

Opens the 0.3.0 development cycle.

### Fixed
- `analyse(top_file=...)` now parses and adds a top file that is not already
part of the project (file type inferred from its extension) instead of
raising "not in the project", so a testbench top level need not be listed in
the config just to produce a compile order. New
`config.add_top_file_by_path` / `config.TOP_FILE_EXT_TYPES`; added
`Resolver.verilog_include_dirs` so an auto-added Verilog top can resolve its
`` `include `` directives.

## [0.2.0] - 2026-07-11

Expand Down
124 changes: 124 additions & 0 deletions examples/python_api/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
# Python API example (`hdldepends.analyse`)

Most examples drive `hdldepends` from the command line. This one uses it as a
**Python library**: [`analyse_example.py`](analyse_example.py) imports
`hdldepends` and calls `hdldepends.analyse(...)`, which returns the compile
order in-process (no output files written) as an `AnalysisResult`.

It shows the three things the API gives you:

1. **A human-readable compile order** — `AnalysisResult.print_compile_order()`
prints the same tree-indented listing the CLI does, and
`format_compile_order()` returns it as a string (to log, write, or diff).
2. **A machine-readable compile order** — `result.compile_order` is a list of
plain, JSON-safe dicts, and `result.to_dict()` wraps it as `{"files": [...]}`.
3. **Auto-added testbench tops** — pointing `analyse` at a `top_file` that is
*not* in the config adds it on the fly, so simulation-only files need not be
listed just to get a compile order.

## Layout

```
hdldeps.yaml config: RTL only (the testbench is intentionally omitted)
analyse_example.py the Python API walkthrough
rtl/
counter_pkg.vhd package (work)
counter.vhd entity, uses work.counter_pkg (work)
sim/
counter_tb.vhd testbench, instantiates work.counter (NOT in the config)
```

## Run it

From the repository root (with `hdldepends` importable — e.g. after
`pip install -e .`):

```sh
python examples/python_api/analyse_example.py
```

The script anchors every path to its own directory, so the working directory
you launch it from does not matter.

## What it demonstrates

### 1. Compile order for the config's top (`top_entity: counter`)

```python
result = hdldepends.analyse("hdldeps.yaml", work_dir=HERE)
result.print_compile_order()
```

```
compile order:
VHDL: |---work: .../rtl/counter_pkg.vhd
VHDL: work: .../rtl/counter.vhd
```

`counter` uses `work.counter_pkg`, so the package is emitted first and indented
one level below the top.

### 2. The same result, machine-readable

```python
result.compile_order # -> list[dict], JSON-safe
result.to_dict() # -> {"files": [...]}
[e["path"] for e in result.compile_order] # just the ordered paths
```

```json
{
"files": [
{ "type": "VHDL", "library": "work", "path": ".../rtl/counter_pkg.vhd" },
{ "type": "VHDL", "library": "work", "path": ".../rtl/counter.vhd", "is_top": true }
]
}
```

`is_top` marks the last (top) entry. When a config uses `ext_files`, those
appear first as `{"type": "EXTERNAL", ...}` entries.

### 3. Testbench top via `top_file` (auto-added)

```python
tb = hdldepends.analyse("hdldeps.yaml", work_dir=HERE, top_file="sim/counter_tb.vhd")
print(tb.format_compile_order())
```

`sim/counter_tb.vhd` is not in `hdldeps.yaml`; `analyse` parses and adds it (its
type inferred from the `.vhd` extension), uses it as the top, and resolves its
dependencies against the project:

```
compile order:
VHDL: |---|---work: .../rtl/counter_pkg.vhd
VHDL: |---work: .../rtl/counter.vhd
VHDL: work: .../sim/counter_tb.vhd
```

## API reference

```python
hdldepends.analyse(
config_files, # a path, or a sequence of them (TOML / JSON / YAML)
*,
top_entity=None, # top-level entity/module name
top_file=None, # top-level file; auto-added if not already in project
top_lib=None, # default VHDL library (defaults to "work")
x_tool_version=None, # Xilinx tool version (.bd/.xci variant selection)
x_device=None, # Xilinx device (.bd/.xci variant selection)
work_dir=None, # anchor for relative config paths / top_file
) -> AnalysisResult
```

Top-selection precedence matches the CLI: `top_file` > `top_entity` > the
config's `top_*_file` > the config's `top_entity`.

`AnalysisResult`:

| Member | Description |
| ------------------------- | ------------------------------------------------------ |
| `compile_order` | `list[dict]` — JSON-safe, EXTERNAL entries first |
| `to_dict()` | `{"files": compile_order}` |
| `format_compile_order()` | `str` — the tree-indented listing the CLI prints |
| `print_compile_order()` | prints `format_compile_order()` to stdout |
71 changes: 71 additions & 0 deletions examples/python_api/analyse_example.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
#!/usr/bin/env python3
"""Use hdldepends as a Python library instead of the CLI.

Run it from anywhere:

python examples/python_api/analyse_example.py

It resolves the small VHDL project in this directory with
``hdldepends.analyse`` and shows what the API gives you:

1. a human-readable compile order -- the same tree-indented text the CLI
prints -- via ``AnalysisResult.print_compile_order()``;
2. the machine-readable, JSON-safe compile order (``compile_order`` / a list of
plain dicts, and ``to_dict()``);
3. pointing the analysis at a testbench that is NOT in the config: the API adds
it on the fly (``top_file``), so simulation-only files need not be listed.
"""

import json
from pathlib import Path

import hdldepends

# This example is self-contained: resolve paths relative to THIS file so it runs
# the same regardless of the current working directory. `work_dir` is what
# relative config paths (and a relative `top_file`) are anchored to.
HERE = Path(__file__).resolve().parent
CONFIG = "hdldeps.yaml" # relative to work_dir (HERE) below
TESTBENCH = "sim/counter_tb.vhd" # deliberately NOT listed in hdldeps.yaml


def banner(text: str) -> None:
print("\n" + "=" * 64)
print(text)
print("=" * 64)


def main() -> None:
# 1. Resolve using the config's own top (top_entity: counter).
result = hdldepends.analyse(CONFIG, work_dir=HERE)

banner("1. Compile order for the config's top (entity `counter`)")
# print_compile_order() writes the same tree-indented listing as the CLI.
result.print_compile_order()

# 2. The same result, machine-readable. `compile_order` is a list of plain
# dicts (JSON-safe); `to_dict()` wraps it as {"files": [...]}.
banner("2. Machine-readable compile order (JSON)")
print(json.dumps(result.to_dict(), indent=2))

# ...or just pull out the ordered file paths:
print("\nOrdered paths:")
for entry in result.compile_order:
print(f" {entry['path']}")

# 3. Point the analysis at a simulation testbench that is NOT in the config.
# `top_file` adds it to the project on the fly (its file type inferred
# from the extension) and uses it as the top -- so the compile order now
# ends at the testbench and pulls its dependencies (counter, counter_pkg)
# in ahead of it.
banner("3. Testbench top via `top_file` (auto-added, not in the config)")
tb_result = hdldepends.analyse(CONFIG, work_dir=HERE, top_file=TESTBENCH)

# format_compile_order() returns the listing as a string, so you can log it,
# write it to a file, diff it, etc. Here we simply print it.
listing = tb_result.format_compile_order()
print(listing)


if __name__ == "__main__":
main()
19 changes: 19 additions & 0 deletions examples/python_api/hdldeps.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Config for the Python API example (see analyse_example.py).
#
# Only the synthesisable RTL lives here. The testbench under sim/ is
# deliberately left out -- the API example adds it on the fly with `top_file`.

# Standard libraries provided by the simulator/synthesiser; not part of the
# project's own compile order.
ignore_libs:
- ieee
- std

# The config's default top, used when analyse() is called with no explicit top.
top_entity: counter

# Synthesisable sources, compiled into the default `work` library.
vhdl_files:
work:
- ./rtl/counter_pkg.vhd
- ./rtl/counter.vhd
30 changes: 30 additions & 0 deletions examples/python_api/rtl/counter.vhd
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

use work.counter_pkg.all;

entity counter is
port (
clk : in std_logic;
rst : in std_logic;
q : out std_logic_vector(WIDTH - 1 downto 0)
);
end entity counter;

architecture rtl of counter is
signal cnt : unsigned(WIDTH - 1 downto 0);
begin
process (clk)
begin
if rising_edge(clk) then
if rst = '1' then
cnt <= (others => '0');
else
cnt <= cnt + 1;
end if;
end if;
end process;

q <= std_logic_vector(cnt);
end architecture rtl;
8 changes: 8 additions & 0 deletions examples/python_api/rtl/counter_pkg.vhd
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
library ieee;
use ieee.std_logic_1164.all;

-- A tiny package the counter depends on, so the example has a real
-- intra-project dependency edge (counter uses work.counter_pkg).
package counter_pkg is
constant WIDTH : natural := 8;
end package counter_pkg;
24 changes: 24 additions & 0 deletions examples/python_api/sim/counter_tb.vhd
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
library ieee;
use ieee.std_logic_1164.all;

-- Simulation-only testbench. It is deliberately NOT listed in hdldeps.yaml;
-- analyse_example.py adds it on the fly via `top_file`, showing that a
-- testbench top level need not be in the config to get a compile order.
entity counter_tb is
end entity counter_tb;

architecture sim of counter_tb is
signal clk : std_logic := '0';
signal rst : std_logic := '1';
signal q : std_logic_vector(7 downto 0);
begin
dut : entity work.counter
port map (
clk => clk,
rst => rst,
q => q
);

clk <= not clk after 5 ns;
rst <= '0' after 20 ns;
end architecture sim;
Loading
Loading