From 1a38dbc6ec5e0f494e93e868ecff3256b23b9087 Mon Sep 17 00:00:00 2001 From: Michael Rogenmoser Date: Thu, 5 Feb 2026 17:46:20 +0100 Subject: [PATCH 01/35] Copy README contents to initial book --- book/.gitignore | 1 + book/book.toml | 4 + book/src/SUMMARY.md | 12 + book/src/commands.md | 197 +++++++++++++++ book/src/configuration_format.md | 58 +++++ book/src/installation.md | 19 ++ book/src/manifest_format.md | 301 +++++++++++++++++++++++ book/src/manifest_format.md#dependencies | 1 + book/src/manifest_format.md#sources | 1 + book/src/manifest_format.md#targets | 1 + book/src/package_structure.md | 11 + book/src/principles.md | 20 ++ book/src/workflow.md | 7 + 13 files changed, 633 insertions(+) create mode 100644 book/.gitignore create mode 100644 book/book.toml create mode 100644 book/src/SUMMARY.md create mode 100644 book/src/commands.md create mode 100644 book/src/configuration_format.md create mode 100644 book/src/installation.md create mode 100644 book/src/manifest_format.md create mode 100644 book/src/manifest_format.md#dependencies create mode 100644 book/src/manifest_format.md#sources create mode 100644 book/src/manifest_format.md#targets create mode 100644 book/src/package_structure.md create mode 100644 book/src/principles.md create mode 100644 book/src/workflow.md diff --git a/book/.gitignore b/book/.gitignore new file mode 100644 index 00000000..e9c07289 --- /dev/null +++ b/book/.gitignore @@ -0,0 +1 @@ +book \ No newline at end of file diff --git a/book/book.toml b/book/book.toml new file mode 100644 index 00000000..b280d272 --- /dev/null +++ b/book/book.toml @@ -0,0 +1,4 @@ +[book] +title = "bender" +authors = ["Michael Rogenmoser", "Tim Fischer", "Fabian Schuiki", "Andreas Kurth"] +language = "en" diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md new file mode 100644 index 00000000..b4bf215e --- /dev/null +++ b/book/src/SUMMARY.md @@ -0,0 +1,12 @@ +# Summary + +- [Principles](./principles.md) +- [Installation](./installation.md) +- [Workflow](./workflow.md) +- [Package Structure](./package_structure.md) +- [Manifest Format (`Bender.yml`)](./manifest_format.md) + +- [Configuration Format (`bender.yml`, `Bender.local`)](./configuration_format.md) +- [Commands](./commands.md) diff --git a/book/src/commands.md b/book/src/commands.md new file mode 100644 index 00000000..24bec9da --- /dev/null +++ b/book/src/commands.md @@ -0,0 +1,197 @@ +# Commands + +`bender` is the entry point to the dependency management system. Bender always operates within a package; starting at the current working directory, search upwards the file hierarchy until a `Bender.yml` is found, which marks the package. + + +## `path` --- Get the path of a checked-out package + +The `bender path ` prints the path of the checked-out version of package `PKG`. + +Useful in scripts: + + #!/bin/bash + cat `bender path mydep`/src/hello.txt + + +## `packages` --- Display the dependency graph + +- `bender packages`: List the package dependencies. The list is sorted and grouped according to a topological sorting of the dependencies. That is, leaf dependencies are compiled first, then dependent ones. +- `bender packages -f`: Produces the same list, but flattened. +- `bender packages -g`: Produces a graph description of the dependencies of the form `TAB`. + + +## `sources` --- List source files +[Code](https://github.com/pulp-platform/bender/blob/master/src/cmd/sources.rs) + +Produces a *sources manifest*, a JSON description of all files needed to build the project. + +The manifest is recursive by default; meaning that dependencies and groups are nested. Use the `-f`/`--flatten` switch to produce a simple flat listing. + +To enable specific targets, use the `-t`/`--target` option. Adding a package and colon `:` before a target will apply the target only to that specific package. Prefixing a target with `-` will remove that specific target, even for predefined targets (e.g., `-t-` or `-t :-`). + +To get the sources for a subset of packages, exclude specific packages and their dependencies, or exclude all dependencies, the following flags exist: + +- `-p`/`--package`: Specify package to show sources for. +- `-e`/`--exclude`: Specify package to exclude from sources. +- `-n`/`--no-deps`: Exclude all dependencies, i.e. only top level or specified package(s). + +For multiple packages (or excludes), multiple `-p` (or `-e`) arguments can be added to the command. + + +## `config` --- Emit the current configuration + +The `bender config` command prints the currently active configuration as JSON to standard output. + + +## `script` --- Generate tool-specific scripts + +The `bender script ` command can generate scripts to feed the source code of a package and its dependencies into a vendor tool. These scripts are rendered using internally stored templates with the [tera](https://keats.github.io/tera/docs/) crate, but custom templates can also be used. + +Supported formats: + +- `flist`: A flat whitespace-separated file list. +- `flist-plus`: A flat file list amenable to be directly inlined into the invocation command of a tool, e.g. `verilate $(bender script flist)`. +- `vsim`: A Tcl compilation script for Mentor ModelSim/QuestaSim. +- `vcs`: A Tcl compilation script for VCS. +- `verilator`: Command line arguments for Verilator. +- `synopsys`: A Tcl compilation script for Synopsys DC and DE. +- `formality`: A Tcl compilation script for Formality (as reference design). +- `riviera`: A Tcl compilation script for Aldec Riviera-PRO. +- `genus`: A Tcl compilation script for Cadence Genus. +- `vivado`: A Tcl file addition script for Xilinx Vivado. +- `vivado-sim`: Same as `vivado`, but specifically for simulation targets. +- `precision`: A Tcl compilation script for Mentor Precision. +- `template`: A custom [tera](https://keats.github.io/tera/docs/) template, provided using the `--template` flag. +- `template_json`: The json struct used to render the [tera](https://keats.github.io/tera/docs/) template. + +Furthermore, similar flags to the `sources` command exist. + + +## `update` --- Re-resolve dependencies + +Whenever you update the list of dependencies, you likely have to run `bender update` to re-resolve the dependency versions, and recreate the `Bender.lock` file. + +Calling update with the `--fetch/-f` flag will force all git dependencies to be re-fetched from their corresponding urls. + +> Note: Actually this should be done automatically if you add a new dependency. But due to the lack of coding time, this has to be done manually as of now. + + +## `clone` --- Clone dependency to make modifications + +The `bender clone ` command checks out the package `PKG` into a directory (default `working_dir`, can be overridden with `-p / --path `). +To ensure the package is correctly linked in bender, the `Bender.local` file is modified to include a `path` dependency override, linking to the corresponding package. + +This can be used for development of dependent packages within the parent repository, allowing to test uncommitted and committed changes, without the worry that bender would update the dependency. + +To clean up once the changes are added, ensure the correct version is referenced by the calling packages and remove the path dependency in `Bender.local`, or have a look at `bender snapshot`. + +> Note: The location of the override may be updated in the future to prevent modifying the human-editable `Bender.local` file by adding a persistent section to `Bender.lock`. + +> Note: The newly created directory will be a git repo with a remote origin pointing to the `git` tag of the resolved dependency (usually evaluated from the manifest (`Bender.yml`)). You may need to adjust the git remote URL to properly work with your remote repository. + +## `snapshot` --- Relinks current checkout of cloned dependencies + +After working on a dependency cloned with `bender clone `, modifications are generally committed to the parent git repository. Once committed, this new hash can be quickly used by bender by calling `bender snapshot`. + +With `bender snapshot`, all dependencies previously cloned to a working directory are linked to the git repositories and commit hashes currently checked out. The `Bender.local` is modified correspondingly to ensure reproducibility. Once satisfied with the changes, it is encouraged to properly tag the dependency with a version, remove the override in the `Bender.local`, and update the required version in the `Bender.yml`. + +## `parents` --- Lists packages calling the specified package + +The `bender parents ` command lists all packages calling the `PKG` package. + +## `checkout` --- Checkout all dependencies referenced in the Lock file + +This command will ensure all dependencies are downloaded from remote repositories. This is usually automatically executed by other commands, such as `sources` and `script`. + +## `fusesoc` --- Create FuseSoC `.core` files + +This command will generate FuseSoC `.core` files from the bender representation for open-source compatibility to the FuseSoC tool. It is intended to provide a basic manifest file in a compatible format, such that any project wanting to include a bender package can do so without much overhead. + +If the `--single` argument is provided, only to top-level `Bender.yml` file will be parsed and a `.core` file generated. + +If the `--single` argument is *not* provided, bender will walk through all the dependencies and generate a FuseSoC `.core` file where none is present. If a `.core` file is already present in the same directory as the `Bender.yml` for the corresponding dependency, this will be used to link dependencies (if multiple are available, the user will be prompted to select one). Previously generated `.core` files will be overwritten, based on the included `Created by bender from the available manifest file.` comment in the `.core` file. + +The `--license` argument will allow you to add multiple comment lines at the top of the generated `.core` files, e.g. a License header string. + +The `--fuse-vendor` argument will assign a vendor string to all generated `.core` dependencies for the VLNV name. + +The `--fuse-version` argument will assign a version to the top package being handled for the VLNV name. + +## `vendor` --- Copy files from dependencies that do not support bender + +Collection of commands to manage monorepos. Requires a subcommand. + +Please make sure you manage the includes and sources required for these files separately, as this command only fetches the files and patches them. +This is in part based on [lowRISC's `vendor.py` script](https://github.com/lowRISC/opentitan/blob/master/util/vendor.py). + +### `vendor init` --- (Re-)initialize the vendorized dependencies + +This command will (re-)initialize the dependencies listed in the `vendor_package` section of the `Bender.yml` file, fetching the files from the remote repositories, applying the necessary patch files, and writing them to the respective `target_dir`. + +If the `-n/--no-patch` argument is passed, the dependency is initialized without applying any patches. + +### `vendor diff` --- Print a diff of local, unpatched changes + +This command will print a diff to the remote repository with the patches in `patch_dir` applied. + +### `vendor patch` --- Generate a patch file from local changes + +If there are local, *staged* changes in a vendored dependency, this command prompts for a commit message and generates a patch for that dependency. The patch is written into `patch_dir`. + +If the `--plain` argument is passed, this command will *not* prompt for a commit message and generate a patch of *all* (staged and unstaged) local changes of the vendored dependency. + +### Example workflow + +Let's assume we would like to vendor a dependency `my_ip` into a project `monorepo`. +A simple configuration in a `Bender.yml` could look as follows (see the `Bender.yml` description above for more information on this): + +```yaml +vendor_package: + - name: my_ip + target_dir: deps/my_ip + upstream: { git: "", rev: "" } + patch_dir: "deps/patches/my_ip" +``` + +Executing `bender vendor init` will now clone this dependency from `upstream` and place it in `target_dir`. + +Next, let's assume that we edit two files within the dependency, `deps/my_ip/a` and `deps/my_ip/b`. +We can print these changes with the command `bender vendor diff`. + +Now, we would like to generate a patch with the changes in `deps/my_ip/a` (but not those in `deps/my_ip/b`). +We stage the desired changes using `git add deps/my_ip/a` (of course, you can also just stage parts of a file using `git add --patch`). +The command `bender vendor patch` will now ask for a commit message that will be associated with this patch. +Then, it will place a patch that contains our changes in `deps/my_ip/a` into `deps/patches/my_ip/0001-commit-message.patch` (the number will increment if a numbered patch is already present). + +We can easily create a corresponding commit in the monorepo. +`deps/my_ip/a` is still staged from the previous step. +We only have to `git add deps/patches/my_ip/0001-commit-message.patch` and `git commit` for an atomic commit in the monorepo that contains both our changes to `deps/my_ip/a` and the corresponding patch. + +Upstreaming patches to the dependency is easy as well. +We clone the dependencies' repository, check out `` and create a new branch. +Now, `git am /path/to/monorepo/deps/patches/my_ip/0001-commit-message.patch` will create a commit out of this patch -- including all metadata such as commit message, author(s), and timestamp. +This branch can then be rebased and a pull request can be opened from it as usual. + +Note: when using mappings in your `vendor_package`, the patches will be relative to the mapped directory. +Hence, for upstreaming, you might need to use `git am --directory=` instead of plain `git am`. + +## `completion` --- Generate shell completion script + +The `bender completion ` command prints a completion script for the given shell. + +Installation and usage of these scripts is shell-dependent. Please refer to your shell's documentation +for information on how to install and use the generated script +([bash](https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html), +[zsh](https://zsh.sourceforge.io/Doc/Release/Completion-System.html), +[fish](https://fishshell.com/docs/current/completions.html)). + +Supported shells: +- `bash` +- `elvish` +- `fish` +- `powershell` +- `zsh` + +[aur-bender]: https://aur.archlinux.org/packages/bender +[releases]: https://github.com/pulp-platform/bender/releases +[rust-installation]: https://doc.rust-lang.org/book/ch01-01-installation.html diff --git a/book/src/configuration_format.md b/book/src/configuration_format.md new file mode 100644 index 00000000..8f46d8da --- /dev/null +++ b/book/src/configuration_format.md @@ -0,0 +1,58 @@ +# Configuration Format (`bender.yml`, `Bender.local`) + +Bender looks for a configuration file in the following places: + +- `/etc/bender.yml` +- `$HOME/.config/bender.yml` + +It will also look recursively upwards from the current working directory for the following: + +- `.bender.yml` +- `Bender.local` + +The contents of these files are merged as they are encountered, such that a configuration in `foo/.bender.yml` will overwrite a configuration in `foo/bar/.bender.yml`. + +The configuration file generally looks as follows: + +```yaml +# Location of the cloned and checked-out dependencies. Optional. +# Default: ".bender" in the current package's root directory. +database: some/directory + +# The command to use to invoke `git`. Optional. +# Default: "git" +git: git-wrapper.sh + + +# Overrides for dependencies. Optional. +# Forces a dependencies to use specific versions or local paths. Useful for +# locally resolving dependency conflicts in a package's own Bender.local file. +# Format is the same as `dependencies` in a package manifest. +overrides: + common_cells: { path: "/var/magic/common_cells" } + apb_uart: { git: "git@github.com:pulp-platform/apb_uart.git"} + +# Auxiliary plugin dependencies. Optional. +# Additional dependencies that will be loaded for every package in order to +# provide the `plugins` listed in their manifests. +# Format is the same as `dependencies` in a package manifest. +# DEPRECATED: This will be removed at some point. +plugins: + additional-tools: { path: "/usr/local/additional-tools" } + +# Number of parallel git tasks. Optional. +# Default: 4 +# The number of parallel git operations executed by bender can be adjusted to +# manage performance and load on git servers. Can be overriden as a command +# line argument. +git_throttle: 2 + +# Enable git lfs. Optional. +# Default: true +# Some git dependencies may use git-lfs for additional source files. As +# fetching these files may not always be desired or requried, it can be +# disabled. For multiple conflicting settings will use true. +git_lfs: false +``` + +[Relevant code](https://github.com/pulp-platform/bender/blob/master/src/config.rs) diff --git a/book/src/installation.md b/book/src/installation.md new file mode 100644 index 00000000..ade3f1f1 --- /dev/null +++ b/book/src/installation.md @@ -0,0 +1,19 @@ +# Installation + +To use Bender for a single project, the simplest is to download and use a precompiled binary. We provide binaries for all current versions of Ubuntu and CentOS, as well as generic Linux, on each release. Open a terminal and enter the following command: +```sh +curl --proto '=https' --tlsv1.2 https://pulp-platform.github.io/bender/init -sSf | sh +``` +The command downloads and executes a script that detects your distribution and downloads the appropriate `bender` binary of the latest release to your current directory. If you need a specific version of Bender (e.g., `0.21.0`), append ` -s -- 0.21.0` to that command. Alternatively, you can manually download a precompiled binary from [our Releases on GitHub][releases]. + +If you prefer building your own binary, you need to [install Rust][rust-installation]. You can then build and install Bender for the current user with the following command: +```sh +cargo install bender +``` +If you need a specific version of Bender (e.g., `0.21.0`), append ` --version 0.21.0` to that command. + +To install Bender system-wide, you can simply copy the binary you have obtained from one of the above methods to one of the system directories on your `PATH`. Even better, some Linux distributions have Bender in their repositories. We are currently aware of: + +### [ArchLinux ![aur-shield](https://img.shields.io/aur/version/bender)][aur-bender] + +Please extend this list through a PR if you know additional distributions. diff --git a/book/src/manifest_format.md b/book/src/manifest_format.md new file mode 100644 index 00000000..af57ef05 --- /dev/null +++ b/book/src/manifest_format.md @@ -0,0 +1,301 @@ +# Manifest Format (`Bender.yml`) + +The package manifest describes the package, its metadata, its dependencies, and its source files. All paths in the manifest may be relative, in which case they are understood to be relative to the directory that contains the manifest. + +```yaml +# Package metadata. Required. +package: + # The name of the package. Required. + name: magic-chip + + # The list of package authors and contributors. Optional. + # By convention, authors should be listed in the form shown below. + authors: ["John Doe "] + + # A short description of the package. Optional. + description: "This is a magical chip" + +# Specify git remotes for dependencies. Optional. +remotes: + pulp: + url: "https://github.com/pulp-platform" + default: true # Only required if multiple remotes are specified. + + # Additional non-default remotes (HTTP or SSH). + openhw: "https://github.com/openhwgroup" + # Template remote URL where `{}` is a placeholder for dependency name. + # If no placeholder is found, "/{}.git" is used. + internal: "git@gitlab.company.com:internal-repo/{}/release" + +# Other packages this package depends on. Optional. +dependencies: + # Path dependency. + axi: { path: "../axi" } + + # Git version dependency from default remote. + apb: "0.2" + + # Git version dependency from non-default remote. + fll: { version: "0.8", remote: "internal" } + + # Git version dependency with explicit git url. + ara: { git: "https://github.com/john_doe/ara.git", version: "2" } + + # Git revision dependency (always requires explicit git url). + spatz: {git: "https://github.com/pulp-platform/spatz.git", rev: "fixes" } + + # Git version dependency, only included if target "test" or "regression_test" is set. + common_verification: { version: "0.2", target: "any(test, regression_test)" } + + # Git revision dependency, passing a custom target. + # (equivalent to `-t common_cells:cc_custom_target`). + common_cells: { version: "1.39", pass_targets: ["cc_custom_target"] } + + # Git version dependency, passing conditional targets to a dependency + # (equivalent to `-t cva6:cv64a6_imafdcv_sv39` if target 64bit is set, + # `-t cva6:cv32a6_imac_sv32` if target 32bit is set) + ariane: + remote: openhw + version: 5.3.0 + pass_targets: + - {target: 64bit, pass: "cv64a6_imafdcv_sv39"} + - {target: 32bit, pass: "cv32a6_imac_sv32"} + +# Freeze any dependency updates. Optional. False if omitted. +# Useful for chip packages. Once the chip is in final tapeout mode, and +# dependency updates would require disastrous amounts of re-verification. +frozen: true + +# List of source files in this package. Optional. +sources: + # Individual source files are simple string entries: + - src/package.sv + - src/file1.vhd + - src/file2.vhd + + # Source files can be grouped: + - files: + - src/stuff/pkg.sv + - src/stuff/top.sv + + # Grouped source files may have additional include dirs, defines, and target: + - include_dirs: + - src/include + - src/stuff/include + defines: + # Define without a value. + EXCLUDE_MAGIC: ~ + # Define with a value. + PREFIX_NAME: stuff + target: all(asic, synthesis, freepdk45) + files: + - src/core/pkg.sv + - src/core/alu.sv + - src/core/top.sv + + # Source files can use glob patterns to include all matching files: + - src/more_stuff/**/*.sv + + # Source files can have custom fileendings + - sv: vendor/encrypted_sv_src.svp + - v: vendor/encrypted_v_src.vp + - vhd: vendor/encrypted_vhd_src.e + + # File list in another external file, supporting simple file names, `+define+` and `+incdir+` + - external_flists: + - other_file_list.f + files: [] + +# A list of include directories which should implicitly be added to source +# file groups of packages that have the current package as a dependency. +# Optional. +export_include_dirs: + - include + - uvm/magic/include + +# Additional workspace configuration. Optional. +workspace: + # Create symlinks to dependencies. + # A list of paths at which bender will create a symlink to the checked-out + # version of the corresponding package. + package_links: + links/axi: axi + common: common_cells + + # A directory where the dependencies will be checked out. Optional. + # If specified, bender will check out the dependencies once and leave them + # for the user to modify and keep up to date. + # CAUTION: Bender will not touch these after the initial checkout. + # Useful for chip packages, if the intent is to commit all dependencies into + # the chip's version control. + checkout_dir: deps + +# Map of package-provided commands that can be called as `bender `. +# Optional. Only available in dependent packages. +plugins: + hello: scripts/hello.sh + +# List of vendorized files from external repositories not supporting bender. Optional. +vendor_package: + # package name + - name: lowrisc_opentitan + # target directory + target_dir: vendor/lowrisc_opentitan + # upstream dependency (i.e. git repository similar to dependencies, only supports commit hash) + upstream: { git: "https://github.com/lowRISC/opentitan.git", rev: "47a0f4798febd9e53dd131ef8c8c2b0255d8c139" } + # paths to include from upstream dependency. Per default, all paths are included. Optional. + include_from_upstream: + - "src/*" + # paths to exclude from upstream dependency. Paths that also match a pattern in include_from_upstream are excluded. Optional. + exclude_from_upstream: + - "ci/*" + # directory containing patch files. Optional. + patch_dir: "vendor/patches" + # custom file mapping from remote repository to local repository, with optional patch_dir containing patches. Optional. Note: mappings make upstreaming patches slightly more complicated. Avoid if not necessary. + mapping: + - {from: 'hw/ip/prim/rtl/prim_subreg.sv', to: 'src/prim_subreg.sv' } + - {from: 'hw/ip/prim/rtl/prim_subreg_arb.sv', to: 'src/prim_subreg_arb.sv' } + - {from: 'hw/ip/prim/rtl/prim_subreg_ext.sv', to: 'src/prim_subreg_ext.sv', patch_dir: 'lowrisc_opentitan' } + - {from: 'hw/ip/prim/rtl/prim_subreg_shadow.sv', to: 'src/prim_subreg_shadow.sv' } +``` + +[Relevant code](https://github.com/pulp-platform/bender/blob/master/src/config.rs) + + +## Dependencies + +Dependencies are specified in the `dependencies` section of the package manifest, or the `overrides` section in the configuration file. There are different kinds of dependencies, as described in the following. + +### Path + + mydep: { path: "../path/to/mydep" } + +Path dependencies are not considered versioned. Either all versions of dependency `mydep` point to the same path, or otherwise the resolution will fail. + +### Git + + mydep: { git: "git@github.com:pulp-platform/common_verification.git", rev: "" } + mydep: { git: "git@github.com:pulp-platform/common_verification.git", version: "1.1" } + +Git dependencies are automatically checked out and cloned, and are considered for version resolution. The `rev` field can be a git "commit-ish", which essentially is a commit hash, a tag name, or a branch name, where the newest name that starts with the indicated revision is selected. The `version` field can be any of the [semver predicates](https://docs.rs/semver/#requirements), such as a simple version `X.Y.Z` (or `X.Y`), prefixing `=` to only allow that specific version, `~` to limit updates to patches, or defining custom ranges with `>=U.V.W, Note: Git tags without the `v` prefix will not be detected by bender. eg: use `v1.2.3`, and **NOT** `1.2.3` + +[Relevant dependency resolution code](https://github.com/pulp-platform/bender/blob/master/src/resolver.rs) + +### Git LFS Support + +Bender detects if a repository requires Git LFS and if the `git-lfs` tool is installed on your system. + +- If the repository uses LFS (detected via `.gitattributes`) and `git-lfs` is installed, Bender will automatically configure LFS and pull the required files. +- If the repository appears to use LFS but `git-lfs` is **not** installed, Bender will print a warning (`W33`) but proceed with the checkout. In this case, you may end up with pointer files instead of the actual large files, which can cause build failures. +- If the repository does not use LFS, Bender skips LFS operations entirely to save time. + +### Target handling + +Specified dependencies can be filtered, similar to the sources below. For consistency, this filtering does **NOT** apply during an update, i.e., all dependencies will be accounted for in the Bender.lock file. The target filtering only applies for sources and script outputs. This can be used e.g., to include specific IP only for testing. + +### Passing targets + +For sources and script generation, targets can be passed from a package to its dependency directly in the `Bender.yml` file. This allows for enabling and disabling of specific features. Furthermore, these passed targets can be again filtered with a target specification applied to the specific target. This can be used e.g., to enable specific features of dependencies. + + +## Sources + +The source files listed in the `sources` section of the package manifest are a recursive structure. Each entry in the list can either be a single source file, or a group of source files: + +```yaml +# Format of the `sources` section in the manifest: +sources: + - + - + - ... + + # A source file is formatted as follows: + - src/top.sv + + # A source group is formatted as follows. + # Be careful about the `-`, which may appear on the same line as the first + # field of the source group. + - + # List of include directories. Optional. + include_dirs: + - + - + - ... + # List of defines. Optional. + defines: + # Defines without value: + : ~ + : ~ + # Defines with value: + : + : + ... + # Target specifier. Optional. + target: + # Recursive list of source files and groups: + files: + - + - + - ... +``` + +The `target` specification configures a source group to be included or excluded under certain circumstances. See below for details. The `include_dirs` field specifies the `+incdir+...` statements to be added to any compilation command for the group. The `defines` field specifies the `+define+...` statements to be added add to any compilation command for this group. + + +## Targets + +Targets are flags that can be used to filter source files and dependencies. They are used to differentiate the steps in the ASIC/FPGA design flow, the EDA tools, technology targets, and more. They can also be used to have different versions of an IP optimized for different chips or technologies. + +Targets specify a simple expression language, as follows: + +- `*` matches any target +- `name` matches the target "name" +- `all(T1, ..., TN)` matches if all of the targets T1 to TN match (boolean *AND*) +- `any(T1, ..., TN)` matches if any of the targets T1 to TN match (boolean *OR*) +- `not(T)` matches if target T does *not* match (boolean *NOT*) + +The following targets are automatically set by various bender subcommands: + +- `synthesis` for synthesis tool script generation +- `simulation` for simulation tool script generation + +Individual commands may also set tool-specific targets: + +- `vsim` +- `vcs` +- `verilator` +- `synopsys` +- `riviera` +- `genus` +- `vivado` + +Individual commands may also set vendor-specific targets: + +- `xilinx` +- `synopsys` + +Individual commands may also set technology-specific targets: + +- `asic` +- `fpga` + +Additionally, we suggest to use the following targets to identify source code and netlists at different stages in the design process: + +- `test` for testbench code +- `rtl` for synthesizable RTL code +- `gate` for gate-level netlists + +Do not use `:` in your custom targets, as this is used to separate targets to apply to individual packages. + +Do not start the target name with `-`, as this is used to remove target application. + +[Relevant code](https://github.com/pulp-platform/bender/blob/master/src/target.rs) + +## Vendor + +Section to list files and directories copied and patched within this repository from external repositories not supporting bender. +To update, see below `vendor` command. diff --git a/book/src/manifest_format.md#dependencies b/book/src/manifest_format.md#dependencies new file mode 100644 index 00000000..3c3f15c7 --- /dev/null +++ b/book/src/manifest_format.md#dependencies @@ -0,0 +1 @@ +# Dependencies diff --git a/book/src/manifest_format.md#sources b/book/src/manifest_format.md#sources new file mode 100644 index 00000000..e70306d4 --- /dev/null +++ b/book/src/manifest_format.md#sources @@ -0,0 +1 @@ +# Sources diff --git a/book/src/manifest_format.md#targets b/book/src/manifest_format.md#targets new file mode 100644 index 00000000..01d0a4c8 --- /dev/null +++ b/book/src/manifest_format.md#targets @@ -0,0 +1 @@ +# Targets diff --git a/book/src/package_structure.md b/book/src/package_structure.md new file mode 100644 index 00000000..163e120c --- /dev/null +++ b/book/src/package_structure.md @@ -0,0 +1,11 @@ +# Package Structure + +Bender looks for the following three files in a package: + +- `Bender.yml`: This is the main **package manifest**, and the only required file for a directory to be recognized as a Bender package. It contains metadata, dependencies, and source file lists. + +- `Bender.lock`: The **lock file** is generated once all dependencies have been successfully resolved. It contains the exact revision of each dependency. This file *may* be put under version control to allow for reproducible builds. This is handy for example upon taping out a design. If the lock file is missing or a new dependency has been added, it is regenerated. + +- `Bender.local`: This optional file contains **local configuration overrides**. It should be ignored in version control, i.e. added to `.gitignore`. This file can be used to override dependencies with local variants. It is also used when the user asks for a local working copy of a dependency. + +[Relevant code](https://github.com/pulp-platform/bender/blob/master/src/cli.rs) diff --git a/book/src/principles.md b/book/src/principles.md new file mode 100644 index 00000000..f3e514eb --- /dev/null +++ b/book/src/principles.md @@ -0,0 +1,20 @@ +# Principles + +Bender is built around the following core principles: + +- **Be as opt-in as possible.** We do not assume any specific EDA tool, workflow, or directory layout (besides a few key files). All features are designed to be as modular as possible, such that the user can integrate them into their respective flow. + +- **Allow for reproducible builds.** Bender maintains a precise *lock file* which tracks the exact git hash a dependency has been resolved to. This allows the source code of a package to be reliable reconstructed after the fact. + +- **Collect source files.** The first feature tier of Bender is to collect the source files in a hardware IP. In doing this, it shall do the following: + - Maintain the required order across source files, e.g. for package declarations before their use. + - Be as language-agnostic as possible, supporting both SystemVerilog and VHDL. + - Allow source files to be organized into recursive groups. + - Track defines and include directories individually for each group. + +- **Manage dependencies.** The second feature tier of Bender is to maintain other packages an IP may depend on, and to provide a local checkout of the necessary source files. Specifically, it shall: + - Support transitive dependencies + - Not rely on a central package registry, unlike e.g. npm, cargo, or brew (necessary because parts of a project are usually under NDA) + - Enforce strict use of [semantic versioning](https://semver.org/) + +- **Generate tool scripts.** The third feature tier of Bender is the ability to generate source file listings and compilation scripts for various tools. diff --git a/book/src/workflow.md b/book/src/workflow.md new file mode 100644 index 00000000..c238a84d --- /dev/null +++ b/book/src/workflow.md @@ -0,0 +1,7 @@ +# Workflow + +The workflow of bender is based on a configuration and a lock file. The configuration file lists the sources, dependencies, and tests of the package at hand. The lock file is used by the tool to track which exact version of a package is being used. Adding this file to version control, e.g. for chips that will be taped out, makes it easy to reconstruct the exact IPs that were used during a simulation, synthesis, or tapeout. + +Upon executing any command, bender checks to see if dependencies have been added to the configuration file that are not in the lock file. It then tries to find a revision for each added dependency that is compatible with the other dependencies and add that to the lock file. In a second step, bender tries to ensure that the checked out revisions match the ones in the lock file. If not possible, appropriate errors are generated. + +The update command reevaluates all dependencies in the configuration file and tries to find for each a revision that satisfies all recursive constraints. If semantic versioning is used, this will update the dependencies to newer versions within the bounds of the version requirement provided in the configuration file. From 89b18584731a80c30ecfdbeef2bfaccc6e168d50 Mon Sep 17 00:00:00 2001 From: Michael Rogenmoser Date: Thu, 12 Feb 2026 13:14:01 +0100 Subject: [PATCH 02/35] Update book --- README.md | 2 +- book/src/commands.md | 4 ---- book/src/installation.md | 4 ++++ book/src/manifest_format.md | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 3947c274..eaaa997b 100644 --- a/README.md +++ b/README.md @@ -283,7 +283,7 @@ All git tags of the form `vX.Y.Z` are considered a version of the package. [Relevant dependency resolution code](https://github.com/pulp-platform/bender/blob/master/src/resolver.rs) -#### Git LFS Support +##### Git LFS Support Bender detects if a repository requires Git LFS and if the `git-lfs` tool is installed on your system. diff --git a/book/src/commands.md b/book/src/commands.md index 24bec9da..b4503c13 100644 --- a/book/src/commands.md +++ b/book/src/commands.md @@ -191,7 +191,3 @@ Supported shells: - `fish` - `powershell` - `zsh` - -[aur-bender]: https://aur.archlinux.org/packages/bender -[releases]: https://github.com/pulp-platform/bender/releases -[rust-installation]: https://doc.rust-lang.org/book/ch01-01-installation.html diff --git a/book/src/installation.md b/book/src/installation.md index ade3f1f1..2202eaf6 100644 --- a/book/src/installation.md +++ b/book/src/installation.md @@ -17,3 +17,7 @@ To install Bender system-wide, you can simply copy the binary you have obtained ### [ArchLinux ![aur-shield](https://img.shields.io/aur/version/bender)][aur-bender] Please extend this list through a PR if you know additional distributions. + +[aur-bender]: https://aur.archlinux.org/packages/bender +[releases]: https://github.com/pulp-platform/bender/releases +[rust-installation]: https://doc.rust-lang.org/book/ch01-01-installation.html diff --git a/book/src/manifest_format.md b/book/src/manifest_format.md index af57ef05..5e79045a 100644 --- a/book/src/manifest_format.md +++ b/book/src/manifest_format.md @@ -185,7 +185,7 @@ All git tags of the form `vX.Y.Z` are considered a version of the package. [Relevant dependency resolution code](https://github.com/pulp-platform/bender/blob/master/src/resolver.rs) -### Git LFS Support +#### Git LFS Support Bender detects if a repository requires Git LFS and if the `git-lfs` tool is installed on your system. From ea4e614e775bf1a1e1964d3749fd1d6af1aab9c8 Mon Sep 17 00:00:00 2001 From: Michael Rogenmoser Date: Wed, 11 Mar 2026 13:27:11 +0100 Subject: [PATCH 03/35] Update book --- book/src/SUMMARY.md | 28 +++++++++++++++++++++++----- book/src/concepts.md | 1 + book/src/dependencies.md | 1 + book/src/getting_started.md | 1 + book/src/index.md | 1 + book/src/installation.md | 9 +++++++++ book/src/local.md | 1 + book/src/lockfile.md | 1 + book/src/manifest.md | 1 + book/src/sources.md | 1 + book/src/targets.md | 1 + book/src/workflow/dependencies.md | 1 + book/src/workflow/init.md | 1 + book/src/workflow/package_dev.md | 1 + book/src/workflow/scripts.md | 1 + book/src/workflow/sources.md | 1 + book/src/workflow/vendor.md | 1 + book/src/workflows.md | 1 + 18 files changed, 48 insertions(+), 5 deletions(-) create mode 100644 book/src/concepts.md create mode 100644 book/src/dependencies.md create mode 100644 book/src/getting_started.md create mode 100644 book/src/index.md create mode 100644 book/src/local.md create mode 100644 book/src/lockfile.md create mode 100644 book/src/manifest.md create mode 100644 book/src/sources.md create mode 100644 book/src/targets.md create mode 100644 book/src/workflow/dependencies.md create mode 100644 book/src/workflow/init.md create mode 100644 book/src/workflow/package_dev.md create mode 100644 book/src/workflow/scripts.md create mode 100644 book/src/workflow/sources.md create mode 100644 book/src/workflow/vendor.md create mode 100644 book/src/workflows.md diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index b4bf215e..ab79d08f 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -1,12 +1,30 @@ # Summary -- [Principles](./principles.md) +- [Overview](./index.md) - [Installation](./installation.md) +- [Getting Started](./getting_started.md) +- [Concepts](./concepts.md) + - [Principles](./principles.md) + - [Manifest](./manifest.md) + - [Lockfile](./lockfile.md) + - [Local](./local.md) + - [Targets](./targets.md) + - [Dependencies](./dependencies.md) + - [Sources](./sources.md) +- [Workflows](./workflows.md) + - [Initialization](./workflow/init.md) + - [Dependencies](./workflow/dependencies.md) + - [Sources](./workflow/sources.md) + - [Scripts](./workflow/scripts.md) + - [Package Development](./workflow/package_dev.md) + - [Vendor](./workflow/vendor.md) +- [Commands](./commands.md) + + -- [Configuration Format (`bender.yml`, `Bender.local`)](./configuration_format.md) -- [Commands](./commands.md) + - [Targets](./manifest_format.md) +- [Configuration Format (`bender.yml`, `Bender.local`)](./configuration_format.md)--> diff --git a/book/src/concepts.md b/book/src/concepts.md new file mode 100644 index 00000000..74d42e13 --- /dev/null +++ b/book/src/concepts.md @@ -0,0 +1 @@ +# Concepts diff --git a/book/src/dependencies.md b/book/src/dependencies.md new file mode 100644 index 00000000..3c3f15c7 --- /dev/null +++ b/book/src/dependencies.md @@ -0,0 +1 @@ +# Dependencies diff --git a/book/src/getting_started.md b/book/src/getting_started.md new file mode 100644 index 00000000..bad55622 --- /dev/null +++ b/book/src/getting_started.md @@ -0,0 +1 @@ +# Getting Started diff --git a/book/src/index.md b/book/src/index.md new file mode 100644 index 00000000..07dd0c5c --- /dev/null +++ b/book/src/index.md @@ -0,0 +1 @@ +# Overview diff --git a/book/src/installation.md b/book/src/installation.md index 2202eaf6..5547367c 100644 --- a/book/src/installation.md +++ b/book/src/installation.md @@ -12,6 +12,15 @@ cargo install bender ``` If you need a specific version of Bender (e.g., `0.21.0`), append ` --version 0.21.0` to that command. +To compile bender from source, clone the git project and run the following command inside the bender project: +```sh +cargo build +``` +To install the local sources, you can run the following: +```sh +cargo install --path . +``` + To install Bender system-wide, you can simply copy the binary you have obtained from one of the above methods to one of the system directories on your `PATH`. Even better, some Linux distributions have Bender in their repositories. We are currently aware of: ### [ArchLinux ![aur-shield](https://img.shields.io/aur/version/bender)][aur-bender] diff --git a/book/src/local.md b/book/src/local.md new file mode 100644 index 00000000..fb3c6063 --- /dev/null +++ b/book/src/local.md @@ -0,0 +1 @@ +# Local diff --git a/book/src/lockfile.md b/book/src/lockfile.md new file mode 100644 index 00000000..f6823be4 --- /dev/null +++ b/book/src/lockfile.md @@ -0,0 +1 @@ +# Lockfile diff --git a/book/src/manifest.md b/book/src/manifest.md new file mode 100644 index 00000000..243e07a6 --- /dev/null +++ b/book/src/manifest.md @@ -0,0 +1 @@ +# Manifest diff --git a/book/src/sources.md b/book/src/sources.md new file mode 100644 index 00000000..e70306d4 --- /dev/null +++ b/book/src/sources.md @@ -0,0 +1 @@ +# Sources diff --git a/book/src/targets.md b/book/src/targets.md new file mode 100644 index 00000000..01d0a4c8 --- /dev/null +++ b/book/src/targets.md @@ -0,0 +1 @@ +# Targets diff --git a/book/src/workflow/dependencies.md b/book/src/workflow/dependencies.md new file mode 100644 index 00000000..3c3f15c7 --- /dev/null +++ b/book/src/workflow/dependencies.md @@ -0,0 +1 @@ +# Dependencies diff --git a/book/src/workflow/init.md b/book/src/workflow/init.md new file mode 100644 index 00000000..7597c975 --- /dev/null +++ b/book/src/workflow/init.md @@ -0,0 +1 @@ +# Initialization diff --git a/book/src/workflow/package_dev.md b/book/src/workflow/package_dev.md new file mode 100644 index 00000000..e20e4b55 --- /dev/null +++ b/book/src/workflow/package_dev.md @@ -0,0 +1 @@ +# Package Development diff --git a/book/src/workflow/scripts.md b/book/src/workflow/scripts.md new file mode 100644 index 00000000..59d9cb4b --- /dev/null +++ b/book/src/workflow/scripts.md @@ -0,0 +1 @@ +# Scripts diff --git a/book/src/workflow/sources.md b/book/src/workflow/sources.md new file mode 100644 index 00000000..e70306d4 --- /dev/null +++ b/book/src/workflow/sources.md @@ -0,0 +1 @@ +# Sources diff --git a/book/src/workflow/vendor.md b/book/src/workflow/vendor.md new file mode 100644 index 00000000..38225bd0 --- /dev/null +++ b/book/src/workflow/vendor.md @@ -0,0 +1 @@ +# Vendor diff --git a/book/src/workflows.md b/book/src/workflows.md new file mode 100644 index 00000000..307ef403 --- /dev/null +++ b/book/src/workflows.md @@ -0,0 +1 @@ +# Workflows From 0e239e47612f1678092f9512076ea887960bfd09 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Wed, 11 Mar 2026 13:57:39 +0100 Subject: [PATCH 04/35] book: Target documentation --- book/src/targets.md | 144 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) diff --git a/book/src/targets.md b/book/src/targets.md index 01d0a4c8..2198dac4 100644 --- a/book/src/targets.md +++ b/book/src/targets.md @@ -1 +1,145 @@ # Targets + +Targets are the primary mechanism in Bender for managing project configurations. They allow you to conditionally include source files, include directories, and dependencies based on the current context (e.g., simulation vs. synthesis, or FPGA vs. ASIC). + +## Target Expressions + +Bender uses a simple boolean expression language for targets: + +- `*`: Matches any target (wildcard). +- `name`: Matches if the target `name` is active. +- `all(T1, T2, ...)`: Matches if **all** listed targets are active (AND). +- `any(T1, T2, ...)`: Matches if **any** of the listed targets are active (OR). +- `not(T)`: Matches if target `T` is **not** active (NOT). +- `(T)`: Parentheses for grouping. + +Target names are case-insensitive and cannot contain colons (`:`) or start with a hyphen (`-`). + +## Usage in Bender.yml + +### Source Groups +You can wrap a group of files in a `target` specification. This allows you to manage different implementations or verification components within the same package. + +#### Testbench Inclusion +Ensures that verification-only code is never included in the synthesis or production flow: + +```yaml +sources: + # RTL sources + - files: + - src/core.sv + - src/alu.sv + + # Testbench only + - target: test + files: + - tb/driver.sv + - tb/tb_top.sv +``` + +#### Simulation vs. Synthesis +Commonly used to swap between an actual hardware macro and a fast behavioral model for simulation: + +```yaml +sources: + # Behavioral model for faster simulation + - target: all(simulation, not(synthesis)) + files: + - src/behavioral/ip_model.sv +``` + +#### Technology Selection +Useful when choosing between different physical implementations, such as ASIC standard cells versus FPGA primitives: + +```yaml +sources: + - target: asic + files: + - target/asic/clock_gate.sv + - target: fpga + files: + - target/fpga/clock_gate.sv +``` + +#### Core Configuration +Targets can be used to select between different hardware architectures or feature sets: + +```yaml +sources: + # 32-bit architecture + - target: rv32 + files: + - src/core/alu_32.sv + - src/core/regfile_32.sv + # 64-bit architecture + - target: rv64 + files: + - src/core/alu_64.sv + - src/core/regfile_64.sv +``` + +### Dependencies +Dependencies can also be conditional. This is useful for verification IP that is only needed during testing: + +```yaml +dependencies: + common_verification: { version: "0.2", target: any(test, simulation) } +``` + +## Built-in Targets + +Bender automatically activates certain targets based on the subcommand and output format. These "default targets" ensure that tool-specific workarounds or flow-specific files are included correctly. You can disable this behavior with the `--no-default-target` flag. + +### Script Format Targets + +The `bender script` command activates the following targets based on the chosen format: + +| Format | Default Targets | +| :--- | :--- | +| `flist`, `flist-plus` | `flist` | +| `vsim` | `vsim`, `simulation` | +| `vcs` | `vcs`, `simulation` | +| `verilator` | `verilator`, `synthesis` | +| `synopsys` | `synopsys`, `synthesis` | +| `formality` | `synopsys`, `synthesis`, `formality` | +| `riviera` | `riviera`, `simulation` | +| `genus` | `genus`, `synthesis` | +| `vivado` | `vivado`, `fpga`, `xilinx`, `synthesis` | +| `vivadosim` | `vivado`, `fpga`, `xilinx`, `simulation` | +| `precision` | `precision`, `fpga`, `synthesis` | + +### Special Targets + +- **RTL:** If you use the `--assume-rtl` flag, Bender will automatically assign the `rtl` target to any source group that does not have an explicit target specification. +- **ASIC:** While `asic` is a common convention, it is **not** set automatically by Bender. It should be manually activated via `-t asic` when needed. + +## Activating Targets via CLI + +Use the `-t` or `--target` flag with Bender commands: + +```bash +# Enable the 'test' target +bender script vsim -t test + +# Enable multiple targets +bender script vivado -t synthesis -t fpga +``` + +### Advanced CLI Syntax +- **Package-specific:** `-t my_pkg:my_target` activates `my_target` only for `my_pkg`. +- **Negative targets:** `-t -old_target` explicitly disables `old_target`. + +## Passing Targets Hierarchically + +A parent package can pass targets to its dependencies using `pass_targets`. This is useful for propagating configuration flags or selecting specific implementations in sub-modules: + +```yaml +dependencies: + ariane: + version: 5.3.0 + pass_targets: + - {target: rv64, pass: "cv64a6_imafdcv_sv39"} + - {target: rv32, pass: "cv32a6_imac_sv32"} +``` + +In this example, if the `rv64` target is active globally, Bender will ensure the `cv64a6_imafdcv_sv39` target is active specifically for the `ariane` dependency. From 7b58e037ed715fbfe02e3b7a5852817599d5dcb6 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Wed, 11 Mar 2026 13:58:15 +0100 Subject: [PATCH 05/35] book: Targets after dependencies and sources --- book/src/SUMMARY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index ab79d08f..075aafde 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -8,9 +8,9 @@ - [Manifest](./manifest.md) - [Lockfile](./lockfile.md) - [Local](./local.md) - - [Targets](./targets.md) - [Dependencies](./dependencies.md) - [Sources](./sources.md) + - [Targets](./targets.md) - [Workflows](./workflows.md) - [Initialization](./workflow/init.md) - [Dependencies](./workflow/dependencies.md) From 48701bc2ae1a8f286965a536f3db52100ab94eda Mon Sep 17 00:00:00 2001 From: Michael Rogenmoser Date: Wed, 11 Mar 2026 14:08:50 +0100 Subject: [PATCH 06/35] book: Manifest documentation --- book/src/manifest.md | 102 +++++++++++++++++++++++++++++++- tests/cli_regression/Bender.yml | 4 ++ 2 files changed, 105 insertions(+), 1 deletion(-) diff --git a/book/src/manifest.md b/book/src/manifest.md index 243e07a6..bdacf5e7 100644 --- a/book/src/manifest.md +++ b/book/src/manifest.md @@ -1 +1,101 @@ -# Manifest +# Manifest (`Bender.yml`) + +The package manifest describes the package, its metadata, its dependencies, and its source files. All paths in the manifest may be relative, in which case they are understood to be relative to the directory that contains the manifest. + +It is strongly recommended to start the Manifest file with a license header (open-source or proprietary) as a comment. This provides clarity on the project's usage. + +```yaml +# Copyright (c) 2026 ETH Zurich and University of Bologna. +# Licensed under the Apache License, Version 2.0, see LICENSE for details. +# SPDX-License-Identifier: Apache-2.0 +``` + +The first section of the manifest should be the package description, outlining the package itself. The package name is required and must match with the name used to call this bender package as a dependency. The name is interpreted in a case-insensitive manner within bender, so additional care should be taken to avoid name conflicts. + +Additionally, authors and a description can be specified. Bender currently does not use these fields but supports their existence. + +```yaml +# Package metadata. Required. +package: + # The name of the package. Required. + name: magic-chip + + # The list of package authors and contributors. Optional. + # By convention, authors should be listed in the form shown below. + authors: ["John Doe "] + + # A short description of the package. Optional. + description: "This is a magical chip" +``` + +The next section in the manifest is the dependencies. Basic projects not requiring any modules from dependencies can omit this section. All packages this bender project depends on should be listed here for proper functionality, including the version requirements. More details on the specific format can be found [here](./dependencies.md). + +```yaml +# Other packages this package depends on. Optional. +dependencies: + common_cells: { git: "https://github.com/pulp-platform/common_cells.git", version: "1.39" } +``` + +The sources section lists the HDL source files belonging to this package. It is optional for packages that only provide headers or are otherwise used without their own source files. More details on the format can be found [here](./sources.md). + +```yaml +# List of source files in this package. Optional. +sources: + # Individual source files. + - src/pkg.sv + - src/top.sv +``` + +Include directories that should be passed to all packages depending on this one are listed under `export_include_dirs`. This is the standard mechanism for sharing header files. The include directories listed here also apply to all files in the current package. + +```yaml +# Include directories exported to dependent packages. Optional. +export_include_dirs: + - include +``` + +Setting `frozen` to `true` prevents Bender from updating dependencies beyond what is recorded in the lockfile. This is useful for chip packages in tapeout mode where dependency changes would require disastrous amounts of re-verification. + +```yaml +# Freeze dependency updates. Optional. Defaults to false. +frozen: true +``` + +The workspace section provides additional options for the local working environment. It is not relevant for library packages and is typically only used in the top-level chip package. Package links creates symlinks for the specified dependencies to known locations, while checkout_dir enforces the checkout of all dependencies to a specific location. + +```yaml +# Additional workspace configuration. Optional. +workspace: + # Create symlinks to checked-out dependencies. + package_links: + links/axi: axi + common: common_cells + + # Directory where dependencies will be checked out. Optional. + # Once set, Bender performs the initial checkout and then leaves the directory + # untouched. Useful for chip packages that commit all dependencies into their + # own version control. + checkout_dir: deps +``` + +Packages can expose shell scripts as bender subcommands using the `plugins` section. These commands are available to packages that depend on this one and can be invoked as `bender `. + +```yaml +# Package-provided commands callable as `bender `. Optional. +plugins: + hello: scripts/hello.sh +``` + +The `vendor_package` section lists files copied from external repositories that do not support Bender. Vendored files are managed with the `bender vendor` command. More details on the workflow can be found [here](./workflow/vendor.md). + +```yaml +# Vendorized files from external repositories not supporting Bender. Optional. +vendor_package: + - name: lowrisc_opentitan + target_dir: vendor/lowrisc_opentitan + # Only commit hashes are supported for the upstream revision. + upstream: { git: "https://github.com/lowRISC/opentitan.git", rev: "47a0f4798febd9e53dd131ef8c8c2b0255d8c139" } + # Custom file mappings from upstream paths to local paths. Optional. + mapping: + - { from: "hw/ip/prim/rtl/prim_subreg.sv", to: "src/prim_subreg.sv" } +``` diff --git a/tests/cli_regression/Bender.yml b/tests/cli_regression/Bender.yml index a4200b04..5dd69d9b 100644 --- a/tests/cli_regression/Bender.yml +++ b/tests/cli_regression/Bender.yml @@ -1,3 +1,7 @@ +# Copyright (c) 2026 ETH Zurich and University of Bologna. +# Licensed under the Apache License, Version 2.0, see LICENSE for details. +# SPDX-License-Identifier: Apache-2.0 + package: name: regression_repo From 35869a0084fbeb6fac56a2a3392dd650c8fe5045 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Wed, 11 Mar 2026 14:22:17 +0100 Subject: [PATCH 07/35] book: Update targets --- book/src/targets.md | 43 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 35 insertions(+), 8 deletions(-) diff --git a/book/src/targets.md b/book/src/targets.md index 2198dac4..b85d93ee 100644 --- a/book/src/targets.md +++ b/book/src/targets.md @@ -6,14 +6,25 @@ Targets are the primary mechanism in Bender for managing project configurations. Bender uses a simple boolean expression language for targets: -- `*`: Matches any target (wildcard). -- `name`: Matches if the target `name` is active. -- `all(T1, T2, ...)`: Matches if **all** listed targets are active (AND). -- `any(T1, T2, ...)`: Matches if **any** of the listed targets are active (OR). -- `not(T)`: Matches if target `T` is **not** active (NOT). +- `*`: Wildcard, matches all target sets. +- `name`: Matches if the target `name` is active (case-insensitive). +- `all(T1, T2, ...)`: Matches if **all** arguments match (boolean AND). +- `any(T1, T2, ...)`: Matches if **at least one** argument matches (boolean OR). +- `not(T)`: Matches if `T` does **not** match (boolean NOT). - `(T)`: Parentheses for grouping. -Target names are case-insensitive and cannot contain colons (`:`) or start with a hyphen (`-`). +### Syntax Rules +Target names can contain alphanumeric characters, dots (`.`), underscores (`_`), and hyphens (`-`). + +**Restrictions:** +- They **cannot** contain colons (`:`), as colons are used for package-specific targets in the CLI. +- They **cannot** start with a hyphen (`-`), as leading hyphens are used to disable targets in the CLI. + +### Logical Examples +- `all(asic, synthesis)`: Matches when both 'asic' and 'synthesis' are set. +- `any(vsim, vcs, riviera)`: Matches if any of the listed simulation tools are active. +- `not(simulation)`: Matches only when 'simulation' is **not** set. +- `any(test, all(rtl, simulation))`: Matches for testbenches, or for RTL code during simulation. ## Usage in Bender.yml @@ -79,10 +90,13 @@ sources: ``` ### Dependencies -Dependencies can also be conditional. This is useful for verification IP that is only needed during testing: +You can make a dependency conditional using target expressions. This is commonly used to include verification IP or platform-specific components only when needed: ```yaml dependencies: + # Included only during simulation + uvm: { version: "1.2.0", target: simulation } + # Included for either test or simulation common_verification: { version: "0.2", target: any(test, simulation) } ``` @@ -131,7 +145,20 @@ bender script vivado -t synthesis -t fpga ## Passing Targets Hierarchically -A parent package can pass targets to its dependencies using `pass_targets`. This is useful for propagating configuration flags or selecting specific implementations in sub-modules: +Bender allows you to "configure" your dependencies by passing specific targets down to them using the `pass_targets` field. This is a powerful way to propagate global settings or select implementations in sub-modules. + +### Simple Passing +You can pass a target name as a string, which will then always be active for that specific dependency: + +```yaml +dependencies: + my_submodule: + version: "1.0.0" + pass_targets: ["enable_debug"] # 'enable_debug' is always active for my_submodule +``` + +### Conditional Passing +You can also pass targets conditionally, based on the targets active in the parent package: ```yaml dependencies: From 1e9b6100873c2dac03567747ae73bbfc0dfd1cda Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Wed, 11 Mar 2026 14:22:22 +0100 Subject: [PATCH 08/35] book: Write dependencies --- book/src/dependencies.md | 81 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) diff --git a/book/src/dependencies.md b/book/src/dependencies.md index 3c3f15c7..28cb3f3a 100644 --- a/book/src/dependencies.md +++ b/book/src/dependencies.md @@ -1 +1,82 @@ # Dependencies + +Bender is designed to manage complex, hierarchical dependency trees for hardware projects. A dependency is any external package that provides its own `Bender.yml` manifest. + +## Dependency Types + +Dependencies are defined in the `dependencies` section of your `Bender.yml`. + +### Git Dependencies +Git is the primary way to distribute Bender packages. You can specify them in two ways: + +> **Important:** The shorthand notation (e.g., `common_cells: "1.21.0"`) is only available if you have defined at least one [remote](#remotes) in your manifest. If no remote is specified, you must use the full `git` URL (see [revision](#revision-based)) + +#### Version-based (Recommended) +Bender uses [Semantic Versioning (SemVer)](https://semver.org/) to find the best compatible version. You can use standard [SemVer operators](https://docs.rs/semver/latest/semver/enum.Op.html) to specify version ranges: + +```yaml +dependencies: + common_cells: "1.21.0" + axi: { version: ">=0.23.0, <0.26.0" } +``` +> **Note:** Bender only recognizes Git tags that follow the `vX.Y.Z` format (e.g., `v1.2.1`). + +#### Revision-based +Use this for specific commits, branches, or tags that don't follow SemVer. +```yaml +dependencies: + pulp_soc: { git: "https://github.com/pulp-platform/pulp_soc.git", rev: "develop" } +``` + +### Path Dependencies +Path dependencies point to a local directory. They are never versioned; Bender simply uses the code found at that location. +```yaml +dependencies: + my_local_ip: { path: "../local_ips/my_ip" } +``` + +## Remotes + +To avoid repeating full Git URLs, you can define `remotes` in your manifest. + +### Single Remote +If you only define a single remote, it is automatically treated as the default: + +```yaml +remotes: + pulp: "https://github.com/pulp-platform" + +dependencies: + common_cells: "1.21.0" # Automatically searched in the 'pulp' remote +``` + +### Multiple Remotes +When using multiple remotes, you must explicitly mark one as the `default` if you want to use shortened dependency syntax: + +```yaml +remotes: + pulp: + url: "https://github.com/pulp-platform" + default: true + openhw: "https://github.com/openhwgroup" + +dependencies: + common_cells: "1.21.0" # Uses the default 'pulp' remote + cva6: { version: "4.0.0", remote: openhw } # Explicitly uses 'openhw' +``` + +## Targets + +Dependencies can be conditionally included or configured using targets. For details on how to use target expressions or pass targets to dependencies, see the [Targets](./targets.md) documentation. + +## Git LFS Support + +Bender automatically detects if a dependency uses **Git Large File Storage (LFS)**. If `git-lfs` is installed on your system, Bender will automatically pull the required large files during the checkout process. + +## Version Resolution and the Lockfile + +When you run `bender update`, Bender performs the following: +1. **Resolution:** It scans the entire dependency tree and finds a set of versions that satisfy all constraints. +2. **Locking:** The exact versions and Git commit hashes are written to `Bender.lock`. + +**Reproducibility:** Once a `Bender.lock` exists, running `bender checkout` will always download the exact same code, even if newer compatible versions have been released. Always commit your `Bender.lock` to version control. From 1cff3e9bacbd483953b05c18b3ab1b1d0904d702 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Wed, 11 Mar 2026 14:41:13 +0100 Subject: [PATCH 09/35] book: Write sources --- book/src/sources.md | 102 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) diff --git a/book/src/sources.md b/book/src/sources.md index e70306d4..973705ed 100644 --- a/book/src/sources.md +++ b/book/src/sources.md @@ -1 +1,103 @@ # Sources + +The `sources` section in `Bender.yml` defines the source files, include directories, and preprocessor definitions that make up your package. + +## Basic File Listing + +The simplest way to include files is to list them as strings. All paths are relative to the location of the `Bender.yml` file. + +```yaml +sources: + - src/my_pkg.sv + - src/my_ip.sv + - src/my_vhdl.vhd +``` + +## Source Groups + +You can group files together to apply common settings like include directories, preprocessor defines, or [targets](./targets.md). + +```yaml +sources: + - include_dirs: + - include + - src/common/include + defines: + USE_FAST_ALU: ~ # Define without a value + BIT_WIDTH: 64 # Define with a value + target: synthesis + files: + - src/rtl/alu.sv + - src/rtl/top.sv +``` + +- **include_dirs**: Paths added to the `+incdir+` flag during compilation. +- **defines**: Preprocessor macros added via `+define+`. +- **target**: A [target expression](./targets.md) that determines if this entire group is included in the current flow. + +## Glob Patterns + +Bender supports glob patterns for automatically including multiple files without listing them individually: + +```yaml +sources: + - src/*.sv # All .sv files in the src directory + - src/submodules/**/*.sv # All .sv files in all subdirectories (recursive) +``` + +## Custom File Types + +While Bender automatically detects file types by standard extensions (`.sv`, `.v`, `.vhd`), you can explicitly specify the type for encrypted or non-standard files: + +```yaml +sources: + - sv: vendor/encrypted_src.svp + - v: vendor/legacy_code.vp + - vhd: vendor/encrypted_vhdl.e +``` + +## External File Lists (`external_flists`) + +If you have existing EDA tool file lists (often `.f` or `.flist`), you can include them directly. Bender will attempt to parse them for source files, include directories, and defines: + +```yaml +sources: + - external_flists: + - scripts/files.f + files: [] +``` + +## File Overrides + +The `override_files: true` flag allows a source group to replace files with the same basename from other parts of the dependency tree. This is a powerful mechanism for "patching" dependencies or swapping implementations at the top level. + +```yaml +sources: + - override_files: true + files: + - patches/axi_fifo.sv # Will replace any 'axi_fifo.sv' found in the dependency tree +``` + +## Exported Include Directories + +If your package provides headers that its *dependents* need (e.g., UVM macros or shared packages), use the `export_include_dirs` section at the top level of the manifest: + +```yaml +package: + name: my_utils + +export_include_dirs: + - include +``` + +Any package that depends on `my_utils` will automatically have the `include` directory added to its include search path. + +> **Best Practice:** To avoid naming collisions, place your headers in a sub-folder named after your package. +> +> **The Problem:** If two packages (`axi` and `apb`) both export a header named `typedefs.svh`, a file including `` `include "typedefs.svh" `` will be ambiguous, and the compiler will pick whichever directory it finds first in the include path. +> +> **The Solution:** Structure your files as `include/axi/typedefs.svh` and `include/apb/typedefs.svh`, then include them with the package prefix: +> ```systemverilog +> `include "axi/typedefs.svh" +> `include "apb/typedefs.svh" +> ``` From f04261d0600a1ec37a371672f0644d4f60ca6de8 Mon Sep 17 00:00:00 2001 From: Michael Rogenmoser Date: Wed, 11 Mar 2026 14:38:43 +0100 Subject: [PATCH 10/35] book: Some workflow items --- book/src/dependencies.md | 8 +++++++- book/src/manifest.md | 2 +- book/src/workflow/dependencies.md | 16 +++++++++++++++- book/src/workflow/init.md | 8 ++++++++ 4 files changed, 31 insertions(+), 3 deletions(-) diff --git a/book/src/dependencies.md b/book/src/dependencies.md index 28cb3f3a..91c91cb5 100644 --- a/book/src/dependencies.md +++ b/book/src/dependencies.md @@ -73,10 +73,16 @@ Dependencies can be conditionally included or configured using targets. For deta Bender automatically detects if a dependency uses **Git Large File Storage (LFS)**. If `git-lfs` is installed on your system, Bender will automatically pull the required large files during the checkout process. +## Submodules + +TODO + ## Version Resolution and the Lockfile When you run `bender update`, Bender performs the following: 1. **Resolution:** It scans the entire dependency tree and finds a set of versions that satisfy all constraints. -2. **Locking:** The exact versions and Git commit hashes are written to `Bender.lock`. +2. **Locking:** The exact versions and Git commit hashes are written to [`Bender.lock`](./lockfile.md). + +For details on updating dependencies, see [Adding and Updating Dependencies](./workflow/dependencies.md) **Reproducibility:** Once a `Bender.lock` exists, running `bender checkout` will always download the exact same code, even if newer compatible versions have been released. Always commit your `Bender.lock` to version control. diff --git a/book/src/manifest.md b/book/src/manifest.md index bdacf5e7..7800f8fd 100644 --- a/book/src/manifest.md +++ b/book/src/manifest.md @@ -1,6 +1,6 @@ # Manifest (`Bender.yml`) -The package manifest describes the package, its metadata, its dependencies, and its source files. All paths in the manifest may be relative, in which case they are understood to be relative to the directory that contains the manifest. +The package manifest describes the package, its metadata, its dependencies, and its source files. All paths in the manifest may be relative, in which case they are understood to be relative to the directory that contains the manifest. A manifest is required for each bender package. It is strongly recommended to start the Manifest file with a license header (open-source or proprietary) as a comment. This provides clarity on the project's usage. diff --git a/book/src/workflow/dependencies.md b/book/src/workflow/dependencies.md index 3c3f15c7..97aed915 100644 --- a/book/src/workflow/dependencies.md +++ b/book/src/workflow/dependencies.md @@ -1 +1,15 @@ -# Dependencies +# Adding and Updating Dependencies + +As working with dependencies is one of bender's main features, there are a few commands to ensure functionality and assist with understanding the dependency structure. + +## New dependencies +Once new dependencies are added to the manifest, bender needs to first be made aware of their existence. Otherwise, some commands will not work correctly and return an error. To update dependencies, run the following command: + +```sh +bender update +``` + +In case other dependencies already exist and you do not want to re-resolve these, you can add the `--new-only` flag to the update command. + +## Updating dependencies +Similar to when adding new dependencies, updating existing dependencies to more recent versions is also done with the `update` command. diff --git a/book/src/workflow/init.md b/book/src/workflow/init.md index 7597c975..90d2d340 100644 --- a/book/src/workflow/init.md +++ b/book/src/workflow/init.md @@ -1 +1,9 @@ # Initialization + +To initialize a project, bender provides a convenience command to set up an initial empty manifest. + +```sh +bender init +``` + +This creates an initial `Bender.yml` manifest file containing the required package information and a harness for adding dependencies and sources. From 1afdf4e812b763b5b1d158efe68f1163ac44aa5c Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Wed, 11 Mar 2026 15:14:16 +0100 Subject: [PATCH 11/35] book: Update Lockfile --- book/src/lockfile.md | 58 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 57 insertions(+), 1 deletion(-) diff --git a/book/src/lockfile.md b/book/src/lockfile.md index f6823be4..5828308c 100644 --- a/book/src/lockfile.md +++ b/book/src/lockfile.md @@ -1 +1,57 @@ -# Lockfile +# Lockfile (`Bender.lock`) + +The lockfile, named `Bender.lock`, is a machine-generated file that records the exact version and Git revision (commit hash) of every dependency in your project's tree. + +## Why a Lockfile? + +While `Bender.yml` specifies your *intent* (e.g., "I need `common_cells` version 1.21.x"), the lockfile specifies the *reality* (e.g., "`common_cells` is version 1.21.5 at commit `a1b2c3d`"). + +The lockfile ensures: +- **Reproducible Builds:** Everyone on your team is working with the exact same code. +- **CI Stability:** Your CI pipeline won't suddenly fail because a dependency released a new (but incompatible) version. +- **Speed:** Bender doesn't need to re-resolve the entire dependency tree if the lockfile is already present. + +## How it Works + +The lockfile is managed by two primary commands: + +- **[`bender update`](./workflow/dependencies.md#updating-dependencies):** Scans manifests, resolves constraints, and **updates** the `Bender.lock`. +- **[`bender checkout`](./workflow/dependencies.md#checking-out-dependencies):** Reads the `Bender.lock` and ensures the local state matches the exact recorded revisions. + +## Structure of the Lockfile + +The lockfile is written in YAML. For each package, it stores: + +```yaml +packages: + common_cells: + revision: 290c010c26569ec18683510e1688536f98768000 + version: 1.21.0 + source: + git: "https://github.com/pulp-platform/common_cells.git" + dependencies: + - tech_cells_generic +``` + +- **revision:** The full 40-character Git commit hash. +- **version:** The SemVer version that was resolved. +- **source:** Where to download the package from. +- **dependencies:** A list of other packages that this specific package depends on, ensuring the entire tree is captured. + +## Best Practices + +- **Commit it:** Always check `Bender.lock` into your version control (Git). +- **Update with intention:** Only run `bender update` when you actually want to pull in newer versions of your dependencies. +- **Review changes:** When `Bender.lock` changes, review the diff to see exactly which packages were upgraded. + +## Frozen Manifests + +If you want to prevent accidental updates to your project's dependency tree, you can set `frozen: true` in your `Bender.yml`. + +```yaml +package: + name: my_chip + frozen: true # Prevents 'bender update' from running +``` + +When `frozen: true` is set, `bender update` will fail, ensuring that your `Bender.lock` remains unchanged until you explicitly unfreeze the manifest. This is mostly recommended for late-stage tapeouts. From 8e997062383fe3ce8b3bc88d7db60687d84ee865 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Wed, 11 Mar 2026 15:24:26 +0100 Subject: [PATCH 12/35] book: Write local --- book/src/local.md | 45 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/book/src/local.md b/book/src/local.md index fb3c6063..168c2457 100644 --- a/book/src/local.md +++ b/book/src/local.md @@ -1 +1,44 @@ -# Local +# Local Configuration (`Bender.local`) + +`Bender.local` is an optional, user-specific configuration file used to override the project's default settings. Its primary purpose is to allow local development of dependencies without modifying the shared `Bender.yml` or `Bender.lock`. + +## Overriding Dependencies + +The most common use for `Bender.local` is the `overrides` section. This forces Bender to use a specific version or a local path for a dependency, regardless of what the manifest requires. + +```yaml +overrides: + # Force a local path for 'common_cells' + common_cells: { path: "../local_development/common_cells" } + + # Force a specific git URL/revision + axi: { git: "https://github.com/my_fork/axi.git", rev: "experimental_branch" } +``` + +When an override is present, Bender will prioritize it over any other version resolution. + +## Management + +`Bender.local` can be managed both manually and automatically. Several Bender commands manage it for you during the development process: + +- **[`bender clone`](./workflow/package_dev.md#cloning-dependencies):** Automates moving a dependency to a local working directory and adds a `path` override. +- **[`bender snapshot`](./workflow/package_dev.md#snapshotting):** Updates `Bender.local` with the current Git hashes of your local checkouts. + +For a detailed guide on using these commands for multi-package development, see the [Package Development Workflow](./workflow/package_dev.md). + +## Other Configurations + +`Bender.local` can also be used to configure tool-specific settings: + +```yaml +# Change the directory where dependencies are stored (default is .bender) +database: my_deps_cache + +# Use a custom git binary or wrapper +git: /usr/local/bin/git-wrapper.sh +``` + +## Best Practices + +- **Don't Commit It:** `Bender.local` should **rarely** be checked into version control. It contains paths and settings specific to your local machine. Always add it to your `.gitignore`. +- **Use for Development:** Think of it as your "scratchpad" for multi-package development. Once your changes to a dependency are stable and released (tagged), remember to remove the override from `Bender.local` and update your `Bender.yml` with the new version. From 79dd1f7f79c40e34378f8bad946dd5017d96ab9c Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Wed, 11 Mar 2026 17:40:03 +0100 Subject: [PATCH 13/35] book: Add comparison between three files --- book/src/SUMMARY.md | 1 + book/src/bender_files.md | 31 +++++++++++++++++++++++++++++++ 2 files changed, 32 insertions(+) create mode 100644 book/src/bender_files.md diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 075aafde..e90bd3ee 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -8,6 +8,7 @@ - [Manifest](./manifest.md) - [Lockfile](./lockfile.md) - [Local](./local.md) + - [Manifest vs. Lock vs. Local](./bender_files.md) - [Dependencies](./dependencies.md) - [Sources](./sources.md) - [Targets](./targets.md) diff --git a/book/src/bender_files.md b/book/src/bender_files.md new file mode 100644 index 00000000..047a347a --- /dev/null +++ b/book/src/bender_files.md @@ -0,0 +1,31 @@ +# Bender Files + +Bender relies on three core files to manage your hardware project. While they all use the YAML format, they serve very different roles in the development lifecycle. + +## Comparison Overview + +| Feature | `Bender.yml` | `Bender.lock` | `Bender.local` | +| :--- | :--- | :--- | :--- | +| **Role** | Manifest (Intent) | Lockfile (Reality) | Local Overrides | +| **Main Content** | Dependencies & Version Ranges | Exact Git Revisions | Local Paths & Tool Config | +| **Managed By** | User (Manual) | `bender update` (Auto) | User or `bender clone` | +| **Version Control** | **Commit** | **Commit** | **Ignore** (`.gitignore`) | +| **Shared?** | Yes, with everyone | Yes, for reproducibility | No, unique to your machine | + +## Summary of Roles + +### `Bender.yml` (The Manifest) +This is your **Intent**. It defines the requirements of your package. You use it to specify which other packages you need (e.g., "I need `axi` version `0.21.x`"). It is the only file required to define a Bender package. + +### `Bender.lock` (The Lockfile) +This is the **Reality**. It is a machine-generated file that captures the exact state of your dependency tree. It records the specific Git commit hash for every dependency. By committing this file, you ensure that every developer and CI machine works with the exact same source code. + +### `Bender.local` (Local Overrides) +This is your **Workspace**. It allows you to override the shared configuration for your local environment. Its most common use is to point a dependency to a local directory (via `bender clone`) so you can modify its code and see the effects immediately in your top-level project. + +## Interaction Flow + +1. **Define** your requirements in `Bender.yml`. +2. Run `bender update` to resolve those requirements into a fixed `Bender.lock`. +3. Run `bender checkout` to download the exact source code specified in the lockfile. +4. (Optional) Use `Bender.local` to temporarily swap a dependency for a local version during development. From a3c5e5845d5d2dc36d0637cdbb8b8cc14eaf43f4 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Wed, 11 Mar 2026 19:08:56 +0100 Subject: [PATCH 14/35] book: Add CI workflow --- book/src/SUMMARY.md | 2 + book/src/workflow/ci.md | 83 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 book/src/workflow/ci.md diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index e90bd3ee..38d62a66 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -19,6 +19,8 @@ - [Scripts](./workflow/scripts.md) - [Package Development](./workflow/package_dev.md) - [Vendor](./workflow/vendor.md) + - [Continuous Integration](./workflow/ci.md) + - [Commands](./commands.md) From 59f124e6f4d1242e5882088490308b5f55bea069 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Wed, 1 Apr 2026 15:38:03 +0200 Subject: [PATCH 34/35] docs: only deploy on releases --- .github/workflows/docs.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index d5e78113..98953e3c 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -3,6 +3,8 @@ name: Deploy Documentation on: push: branches: [master] + tags: + - 'v*.*.*' workflow_dispatch: permissions: @@ -45,6 +47,7 @@ jobs: url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest needs: build + if: startsWith(github.ref, 'refs/tags/v') steps: - name: Deploy to GitHub Pages id: deployment From 6d4f569d3b8492c8c09e67a7c0d217a34fe66f68 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Wed, 1 Apr 2026 15:50:56 +0200 Subject: [PATCH 35/35] docs: Add PULP logo to README --- README.md | 4 + website/pulp_logo_icon.svg | 194 +++++++++++++++++++++++++++++++++++++ 2 files changed, 198 insertions(+) create mode 100644 website/pulp_logo_icon.svg diff --git a/README.md b/README.md index 6b664ced..1f6c034a 100644 --- a/README.md +++ b/README.md @@ -77,4 +77,8 @@ at your option. --- + +PULP Platform + + Bender is maintained by the [PULP Platform](https://pulp-platform.org/) at ETH Zurich and the University of Bologna. diff --git a/website/pulp_logo_icon.svg b/website/pulp_logo_icon.svg new file mode 100644 index 00000000..1437e65d --- /dev/null +++ b/website/pulp_logo_icon.svg @@ -0,0 +1,194 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +