What would it be helpful to document regarding Bazel in OpenROAD?

[oharboe]

These days ChatGPT and their ilk is pretty good at explaining things, so what should OpenROAD documentation contain in regards to Bazel?

There's no royal road to learning Bazel: it is a modern build system with powerful and necessarily complex features handling everything from fast incremental builds, artifacts, hermeticity and dependency management. Bazel does the job of the necessarily complex build scripts, CMake and DependencyInstaller.sh scripts across all platforms.

Clearly it is counterproductive to repeat generic Bazel documentation in OpenROAD: it will be of lower quality and quickly out of date compared to the official Bazel documentation+googling+chatgpt.

My thinking is that the OpenROAD Bazel.md file should contain some getting started advice and documentation that can be consumed by crawlers and constrain AI/google to give more actionable help. Constraints, such as policies, are probably good examples.

https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/docs/user/Bazel.md

Thoughts? Requests?

[maliberty]

I think things that users/developers would commonly want to do is worth including even if you could dig it out of the formal docs or play twenty-questions with an LLM. Convenience has value.

[oharboe]

How do you run a specific tests or set of tests (e.g. gpl tests)? How do you build a debug build? How do you run a test in gdb? How do you invoke openroad manually from a bazel build? How does this work with ORFS (not bazel-orfs)?

Should be addressed here:

#7605

How do you run a test with -gui?

Not available in Bazel yet, but I think, effectively, I've documented it above. Nothing special, just go to down with ORFS.

What do you need to do if you add a new public or private source code file or a new test?

I'm leaving this to you...

[oharboe]

How do you run a specific tests or set of tests (e.g. gpl tests)? How do you build a debug build? How do you run a test in gdb? How do you run a test with -gui? How do you invoke openroad manually from a bazel build? What do you need to do if you add a new public or private source code file or a new test? How does this work with ORFS (not bazel-orfs)?

What else?

[maliberty]

Not much else comes to mind right now. We will have more to document as we close more of the gaps (-gui, asan/tsan/ubsan, vtune, etc).

[oharboe]

Added a small blurb on asan #7608

[oharboe]

Profiling use-case #7609

[gadfort]

I think providing some additional commands might be helpful, like:

• how to just build openroad (no testing) bazel :openroad?
• what do the ... mean?
• directions for how to add tests in the bazel
• can I get a list of build configurations?
• can I get a list of tests? how do I select a group of tests (like all from pdn with the phrase "asap7")
• how can I force a rebuild?

Provide some quick links to the bazel FAQ and other useful resources on their end (we dont need to repeat their docs, but linking to them is helpful).

• terms like host and target would be great if they had a link to the bazel docs for their definitions.

[gadfort]

• how do I limit parallel builds? in cmake -jX works, how can we control that on bazel

[gadfort]

sorry for the drip information add-ons, but also add a Blub about why bazelisk vs bazel? if there is a difference if not, why not just use bazel as the command?

[oharboe]

More blurbs...

#7612

[oharboe]

First pass of bazel docs merged