Skip to content

flow: OPENROAD_EXE is a command; delete the GDB and VALGRIND switches - #4864

Open
oharboe wants to merge 3 commits into
The-OpenROAD-Project:masterfrom
oharboe:delete-gdb-valgrind-switches
Open

oharboe wants to merge 3 commits into
The-OpenROAD-Project:masterfrom
oharboe:delete-gdb-valgrind-switches

Conversation

@oharboe

@oharboe oharboe commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

To run OpenROAD under a debugger, valgrind or a profiler, put the tool in front of the binary in OPENROAD_EXE:

make DESIGN_CONFIG=... OPENROAD_EXE="gdb --args openroad" open_floorplan
make DESIGN_CONFIG=... OPENROAD_EXE="valgrind openroad" floorplan
make DESIGN_CONFIG=... OPENROAD_EXE="perf record -g -- openroad" floorplan

This now works everywhere: the flow's check, every stage, sub-makes, the generated open_*/gui_*/web_* rules, the metrics version query and generate_ram. A value with quotes works on the command line too, such as gdb in batch mode for a stage:

make DESIGN_CONFIG=... OPENROAD_EXE="gdb -batch -return-child-result -ex run -ex 'thread apply all bt' --args openroad" floorplan

The GDB=1 and VALGRIND=1 switches, which did the same for two tools, are deleted. Setting them now does nothing.

Why the switches were there, and why they can go

  • GDB came in d46cc3e (April 2021). At that point the Makefile spelled out OPENROAD_CMD = openroad -no_init -exit and the binary had no variable of its own, so the switch saved restating the flags. Two months later, make: ensure GDB option works with openroad when debugging #53 introduced OPENROAD_EXE ?= and moved GDB onto it. From then on, OPENROAD_EXE="gdb --args openroad" did the same job from the command line or the environment.
  • VALGRIND and VALGRIND_ARGS came in Provide easy way to run valgrind #205 (October 2021) as the same shortcut for valgrind, when OPENROAD_EXE could already be set.

Today the switches are broken (discussed in #4596):

  • utils.mk rewrites OPENROAD_EXE after the open_*/gui_*/web_* rules are generated, so those rules run without the debugger.
  • The rewritten value is exported, and a sub-make wraps it again: gdb --args gdb --args openroad, valgrind valgrind openroad.
  • With OPENROAD_EXE on the command line, the rewrite is ignored and the switch does nothing.

The general mechanism had gaps of its own. check-openroad and check-yosys ran test -x $(OPENROAD_EXE), so make all refused a wrapped command, and every make printed test: ... binary operator expected. GDB=1 avoided the check only because it rewrote the variable after the check had run. genMetrics.py and generate_ram ran the value as a single program name. #4044 had already made flow.sh run it as a command.

docs/contrib/MakefileContract.md asks that a variable never duplicate an existing one and never be a default-off toggle that no CI design sets. The switches were both.

Commits

  1. make: pass command-line variables to sub-makes intact. UNSET_VARS also clears MAKEFLAGS, so SUB_MAKE passes each command-line variable to the sub-make again, which keeps its origin "command line" (0ec2a3a). The value went through $(shell echo "...") and escape.sh, which only escapes spaces, parentheses and pipes. The result was then parsed by two shells, the recipe's and the bash -c '...' string, where a single quote ends the string. So OR_ARGS="-ex 'thread apply all bt'" failed in every sub-make with No rule to make target 'apply', "a b" lost its quotes, and the shell expanded a quoted '$$HOME'. Each variable is now one single-quoted shell word holding the value this make sees, with ' escaped for the shell and $ for the sub-make. SUB_MAKE moves out of the bash -c string into its arguments, so only the recipe's shell parses it. escape.sh had no other user and is deleted. The order of the sub-make's arguments and the origin of every variable are unchanged.
  2. flow: OPENROAD_EXE and YOSYS_EXE are commands. The checks look at the command's first word with command -v, which also accepts a name on PATH. genMetrics.py and regfile_ram.py split the value with shlex.split. do-auto-memories passes it to gen_memories.py as one argument. The Makefile contract states the rule. A single path, the common case, behaves as before.
  3. flow: delete the GDB and VALGRIND switches. This removes the two ifdef blocks and VALGRIND_ARGS, and adds an FAQ entry with the gdb, valgrind and perf examples. For a stage, the gdb example runs in batch mode, because a stage logs OpenROAD's output through a pipe:
    gdb -batch -return-child-result -ex run -ex 'thread apply all bt' --args openroad
    This prints a backtrace on a crash and otherwise exits with OpenROAD's own exit code.

Tests

flow/test/test_sub_make_args.py checks four OR_ARGS values, given on the command line, through a sub-make: single quotes (-ex 'thread apply all bt'), double quotes (-msg "a b"), a quoted $ ('$$HOME') and runs of spaces. OpenROAD must get the same argv as at the top level, and the single-quote value is also checked through a sub-make of a sub-make. The same values from the environment are checked too. On master, three of the four command-line cases fail: No rule to make target 'apply', ['-msg', 'a', 'b'], and $HOME expanded by the shell. The environment cases pass on master and still pass. The origin of OPENROAD_EXE taken from the environment is "environment" at make levels 0, 1 and 2, before and after the change.

flow/test/test_openroad_exe.py runs make on nangate45/gcd with a stub openroad and a stub wrapper that log their argv. It needs nothing installed and finishes in about 3 s. It checks that:

  • a wrapped OPENROAD_EXE, set on the command line or in the environment, passes check-openroad. A wrapped YOSYS_EXE passes check-yosys. A missing program still fails the check.
  • the wrapper runs exactly once, and the binary exactly once, at the top level (command), through a sub-make (test-unset-and-make-command), and in the generated open_/gui_/web_ rules.
  • GDB=1 and VALGRIND=1 leave the command and its output unchanged, at the top level and in a sub-make.

On master, the same test fails for the reasons above: the check rejects the wrapped command, "binary operator expected" appears, and GDB=1 gives gdb --args gdb --args in the sub-make. gen_memories_test.py gains a case where generate_ram runs under a wrapper.

By hand, with a real OpenROAD binary:

  • gdb -batch -return-child-result -ex run -ex 'thread apply all bt' --args openroad, given on the command line, on make run, through a sub-make and through a sub-make of a sub-make: exit 0 on success, the script's exit code on a Tcl error, and a backtrace on SIGSEGV.
  • do-2_1_floorplan under the same gdb: gdb ran OpenROAD once for the copyright banner, once for the log banner and once for the step, and the step's exit code came through.
  • valgrind and perf record through a sub-make both completed.
  • interactive gdb --args openroad on open_floorplan worked.

The other tests in flow/test give the same results as on master.

Draft until CI has run.

🤖 Generated with Claude Code

oharboe and others added 3 commits November 20, 2026 13:47
A variable given on the make command line lost its quoting on the way
into a sub-make:

    make OR_ARGS="-ex 'thread apply all bt'" ...  # make[1]: No rule to make target 'apply'
    make OR_ARGS='-msg "a  b"' ...                  # sub-make: -msg a b
    make OR_ARGS="'\$\$HOME'" ...                   # sub-make: the shell expands $HOME

UNSET_VARS clears MAKEFLAGS along with the other variables, so
SUB_MAKE passes each command-line variable again on the sub-make's
command line (0ec2a3a), which keeps its origin "command line". The
value went through `$(shell echo "...")` and escape.sh, which escapes
spaces, parentheses and pipes, and the result was parsed by two shells:
the recipe's and the `bash -c '...'` string, where a single quote ends
the string.

Each variable is now one single-quoted shell word holding the value
this make sees, with ' escaped for the shell and $ escaped for the
sub-make. SUB_MAKE moves out of the `bash -c` string into its
arguments, so only the recipe's shell parses it. escape.sh has no
other user and is deleted; the shell that ran it for every
command-line variable on every sub-make is gone too.

The order of the sub-make's arguments and the origin of every variable
are unchanged: command-line variables stay "command line", and an
environment variable such as OPENROAD_EXE stays "environment", at every
level.

flow/test/test_sub_make_args.py checks that values with single quotes,
double quotes, a `$` and runs of spaces give the tool the same argv in
a sub-make, and in a sub-make of a sub-make, as at the top level, both
from the command line and from the environment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>
A wrapper can go in front of the binary in the tool variables:

    make OPENROAD_EXE="gdb --args openroad" ...
    make OPENROAD_EXE="valgrind openroad" ...
    make OPENROAD_EXE="perf record -g -- openroad" ...

The recipes and flow.sh already run the value as a command. Three
places still took it to be a single path:

- check-openroad and check-yosys ran `test -x $(OPENROAD_EXE)`, which
  fails on a wrapped command and prints "binary operator expected"
  from every make that parses variables.mk. They now check the
  command's first word with `command -v`, which also accepts a name
  on PATH.
- genMetrics.py ran OPENROAD_EXE as one program name for the version
  query; it now splits it with shlex.split.
- do-auto-memories passed OPENROAD_EXE unquoted to gen_memories.py
  --openroad, so a wrapped command split into stray arguments, and
  regfile_ram.py ran it as one program name. It is passed as one
  argument and split with shlex.split.

A single path, the common case, works as before. The Makefile
contract states the rule, and flow/test/test_openroad_exe.py checks it
with a stub openroad and a stub wrapper on nangate45/gcd: the wrapped
command passes the check, runs once at the top level, once through a
sub-make, and in the generated open_/gui_/web_ rules.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>
`make GDB=1` and `make VALGRIND=1 VALGRIND_ARGS=...` rewrote
OPENROAD_EXE in utils.mk. They are broken today:

- utils.mk is included after the open_/gui_/web_ rules are generated,
  so those rules run OpenROAD without the debugger.
- The rewritten value is exported, and a sub-make wraps it again:
  `gdb --args gdb --args openroad`, `valgrind valgrind openroad`.
- With OPENROAD_EXE on the make command line, the rewrite is ignored
  and the switch does nothing.

GDB came from a time when the binary had no variable of its own.
d46cc3e (April 2021) added it when the Makefile spelled out
`OPENROAD_CMD = openroad -no_init -exit`, so running gdb otherwise
meant restating the flags. Two months later #53 introduced
OPENROAD_EXE with `?=` and moved GDB onto it; from then on
`OPENROAD_EXE="gdb --args openroad"` did the same from the command
line or the environment. VALGRIND followed in #205 (October 2021) as
the same shortcut for valgrind.

The general mechanism covers both, and any other tool: put it in front
of the binary in OPENROAD_EXE, which the previous commit made work
everywhere:

    make OPENROAD_EXE="gdb --args openroad" open_floorplan
    make OPENROAD_EXE="valgrind openroad" floorplan
    make OPENROAD_EXE="perf record -g -- openroad" floorplan

GDB and VALGRIND are now ordinary environment variables with no effect
on the flow. The FAQ shows the examples, with gdb in batch mode for a
stage, and test_openroad_exe.py checks that GDB=1 and VALGRIND=1 leave
the command unchanged, at the top level and in a sub-make.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request refactors the build system to treat OPENROAD_EXE and YOSYS_EXE as commands rather than simple file paths, allowing wrappers like gdb, valgrind, or perf to be prepended. It updates Python scripts to use shlex.split and modifies Makefile validation to check only the first word of the command. Additionally, it improves how command-line variables are passed to sub-makes, eliminating the need for escape.sh and explicit GDB/VALGRIND overrides, and adds corresponding tests and documentation. Feedback on the changes highlights a potential POSIX shell escaping issue in SUB_MAKE_ARG when handling single quotes.

Comment thread flow/Makefile Resolved
@oharboe
oharboe marked this pull request as ready for review November 20, 2026 13:03
@oharboe
oharboe requested a review from vvbandeira November 20, 2026 13:15
@openroad-ci

Copy link
Copy Markdown
Member

🔍 QoR check

Metrics reflect the PR merge build — i.e. what will land on the target branch.

Commit 6a95bf6 · Jenkins build #1 · Baseline: build · View build on dashboard

62 design(s) checked — 0 with regression(s), 0 without a comparable baseline.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants