Feat: revamp build.py CLI to improve usability and maintainability #8437
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
* show defaults in help * remove redundant statements of default values * change default None to [] for lists * improve argparse usage: use nargs instead of manual parsing, restrict choices where possible * unify handling of all similar elements: components, backends, repoagents, caches, filesystems, endpoints, features
22 tasks
|
this does produce, in my opinion, a more helpful |
whoisj
requested changes
Oct 9, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What does the PR do?
This pull request updates the command-line interface for build.py with two main ideas in mind.
A. Use native features of
argparserather than (potentially brittle) manual parsing of multi-valued inputs:choicesto enforce limited sets of values:--target-platform {linux,rhel,windows,igpu}--build-type {Release,Debug,RelWithDebInfo,MinSizeRel}nargsinstead of separate postprocessing to split by separating characters:--image IMAGE Use specified Docker image in build as <image-name>,<full-image-name>. <image-name> can be "base", "gpu-base", or "pytorch".->
--image <image-name> <full-image-name> Use specified Docker image in build. <image-name> can be "base", "gpu-base", or "pytorch". (default: [])B. Unify the handling of different elements of the build to reduce code duplication and make it easier to add new features to control the build more precisely and flexibly.
The different elements are: components, backends, repoagents, caches, filesystems, endpoints, features.
Each type of element can be (internally) assigned different properties, which determine the available command-line arguments for that element type.
The properties include:
required: elements without this property get--enableand--disableflags.strict: elements with this property are limited to a predefined set of choices (e.g.local,redisfor caches).tag: elements with this property get--<element>-tag <element> <tag>flags to specify a tag from the central repository.org: elements with this property get--<element>-org <element> <org>flags to specify a different repository. (new feature)cmake: elements with this property get--extra-<element>-cmake-arg <element> <name> <value>and--override-<element>-cmake-arg <element> <name> <value>flags to modify their build.The resulting arguments become:
--enable-logging,--enable-stats,--enable-metrics,--enable-gpu-metrics,--enable-cpu-metrics,--enable-tracing,--enable-nvtx,--enable-gpu,--enable-mali-gpu->
--enable-feature [<feature> [<feature> ...] ...]--disable-feature [<feature> [<feature> ...] ...](in case starting from--enable-all)--endpoint ENDPOINT->
--enable-endpoint [<endpoint> [<endpoint> ...] ...]--disable-endpoint [<endpoint> [<endpoint> ...] ...]--filesystem FILESYSTEM->
--enable-filesystem [<filesystem> [<filesystem> ...] ...]--disable-filesystem [<filesystem> [<filesystem> ...] ...]--backend BACKEND Include specified backend in build as <backend-name>[:<repo-tag>]...--extra-backend-cmake-arg EXTRA_BACKEND_CMAKE_ARG Extra CMake argument for a backend build as <backend>:<name>=<value>.--override-backend-cmake-arg OVERRIDE_BACKEND_CMAKE_ARG Override specified backend CMake argument in the build as <backend>:<name>=<value>.->
--enable-backend [<backend> [<backend> ...] ...]--disable-backend [<backend> [<backend> ...] ...]--backend-tag <backend> <tag>--backend-org <backend> <org>--extra-backend-cmake-arg <backend> <name> <value>--override-backend-cmake-arg <backend> <name> <value>--repo-tag REPO_TAG The version of a component to use in the build as <component-name>:<repo-tag>.--extra-core-cmake-arg EXTRA_CORE_CMAKE_ARG Extra CMake argument as <name>=<value>.--override-core-cmake-arg OVERRIDE_CORE_CMAKE_ARG Override specified CMake argument in the build as <name>=<value>.->
--component-tag <component> <tag>--extra-core-cmake-arg <name> <value>--override-core-cmake-arg <name> <value>--repoagent REPOAGENT Include specified repo agent in build as <repoagent-name>[:<repo-tag>]->
--enable-repoagent [<repoagent> [<repoagent> ...] ...]--disable-repoagent [<repoagent> [<repoagent> ...] ...]--repoagent-tag <repoagent> <tag>--repoagent-org <repoagent> <org>--extra-repoagent-cmake-arg <repoagent> <name> <value>--override-repoagent-cmake-arg <repoagent> <name> <value>--cache CACHE Include specified cache in build as <cache-name>[:<repo-tag>].->
--enable-cache [<cache> [<cache> ...] ...]--disable-cache [<cache> [<cache> ...] ...]--cache-tag <cache> <tag>--cache-org <cache> <org>--extra-cache-cmake-arg <cache> <name> <value>--override-cache-cmake-arg <cache> <name> <value>Several minor features are also added:
--no-container-cache, which propagates todocker --no-cache.--default-repo-tag <tag>to override the calculated default value, which is not always appropriate. For example, when trying to build a dev version (currently 25.08), the upstream container version is set to the previous version (25.07), which takes precedence in the calculated default value, but using the corresponding dev versions of component and backend repositories may be intended. Rather than having to override it for each repo, it is useful to be able to override it globally.--use-buildbaseto use the temporary "buildbase" image as the "base" image for backends that need it (e.g. onnxruntime).--library-pathsis found not to be used anywhere in the script, and is therefore removed (after demonstrating how it could be incorporated in the new scheme).Checklist
Agreement
<commit_type>: <Title>pre-commit install, pre-commit run --all)Commit Type:
Check the conventional commit type
box here and add the label to the github PR.
Related PRs:
This PR includes the changes from #8362.
Where should the reviewer start?
Changes only affect build.py and associated documentation.
Here is the help message before any of these changes:
Here is the help message after all of the changes:
Test plan:
I have used the script to build containers in several configurations and found that everything works as desired.
There are changes to some of the CLI flags, listed above.
My understanding from the discussion in #8362 is that there are internal
build.pycommands that need to be checked. I am happy to convert and check these if they can be provided, but I currently have no insight into the exact internal commands that need to be maintained.Caveats:
More features could be added for the "component" elements: using forked repositories, modifying CMake arguments (beyond
core). However, these changes would require modifying theCMakeLists.txtfiles in the various component repositories, and therefore are left for future PRs (so that this PR only involves modifications tobuild.py).Background
In the process of adding minor features in #8362, I noticed some friction: duplication of code, multiple parsing steps, etc. The partial refactor, implemented here, allowed new options for different elements of the build process to be added much more easily (see 304b1a7 for an example, which resolves an existing todo item noted in the code).
Related Issues: (use one of the action keywords Closes / Fixes / Resolves / Relates to)
N/A