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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a

### Added
- script: expose `all_headers` to templates — the fine-grained, transitive, deduplicated set of header files Slang resolved via `` `include `` for the kept trees. Populated whenever the Slang pass runs (`--top`/`--trim-incdirs`/`--broken`/`--encrypted`).
- manifest: allow packages to re-export the `export_include_dirs` of their direct dependencies with `- dep: <name>` and an optional `dir: <path>`, so that include directories can be passed on transitively (https://github.com/pulp-platform/bender/issues/340).

### Changed
- `bender clone`: primary flag for the checkout directory is now `--working-dir`, matching `bender snapshot`'s flag for the same concept; `-p`/`--path` are kept as hidden aliases for backwards compatibility.
Expand Down
10 changes: 10 additions & 0 deletions book/src/manifest.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,16 @@ export_include_dirs:
- include
```

Entries can also re-export the include directories of a direct dependency, so that packages depending on this one see them as well. With only `dep`, all `export_include_dirs` of that dependency are passed on; with `dir`, only the one that exactly matches an entry of the dependency's `export_include_dirs`. See [Exported Include Directories](sources.md#exported-include-directories).

```yaml
export_include_dirs:
- include
- dep: common_cells
dir: include
- dep: reqrsp_interface
```

Setting `frozen` to `true` prevents Bender from updating dependencies beyond what is recorded in the lockfile. This is useful for chip packages in tape-out mode where dependency changes would require disastrous amounts of re-verification.

```yaml
Expand Down
22 changes: 22 additions & 0 deletions book/src/sources.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,28 @@ export_include_dirs:

Any package that depends on `my_utils` will automatically have the `include` directory added to its include search path.

Only the packages that directly depend on `my_utils` receive its include directories. A package can pass the include directories of its dependencies on by listing the dependency with `dep`:

```yaml
package:
name: my_bus

dependencies:
common_cells: { git: "https://github.com/pulp-platform/common_cells.git", version: 1.39.0 }
reqrsp_interface: { git: "https://github.com/pulp-platform/reqrsp_interface.git", version: 0.4.0 }

export_include_dirs:
- include/normal/dir
- dep: common_cells
dir: include # must match an existing export_include_dir of common_cells
- dep: reqrsp_interface # without `dir`, all export_include_dirs of the dependency are passed on
```

- `dep` must name a direct dependency of the package.
- `dir` is given relative to the root of that dependency and must exactly match one of its `export_include_dirs` (a leading `./` and trailing `/` are ignored); otherwise Bender reports an error. Absolute paths and `..` never match.
- Re-exports are resolved transitively: if `common_cells` itself re-exports directories of one of its dependencies, these are passed on as well.
- An optional `target` restricts a re-export, just like for plain entries. Targets of the re-exported directories in the dependency are preserved.

> **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.
Expand Down
123 changes: 120 additions & 3 deletions src/config.rs
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,8 @@ pub struct Manifest {
pub sources: Option<Sources>,
/// The include directories exported to dependent packages.
pub export_include_dirs: Vec<(TargetSpec, PathBuf)>,
/// The include directories of dependencies re-exported to dependent packages.
pub reexport_include_dirs: Vec<ReexportIncludeDir>,
/// The plugin binaries.
pub plugins: IndexMap<String, PathBuf>,
/// Whether the dependencies of the manifest are frozen.
Expand Down Expand Up @@ -80,6 +82,21 @@ impl PrefixPaths for Manifest {
}
}

/// A re-exported include directory of a dependency.
///
/// Makes the exported include directories of a direct dependency available to
/// the packages depending on this one.
#[derive(Clone, Debug)]
pub struct ReexportIncludeDir {
/// The name of the dependency whose include directories are re-exported.
pub dep: String,
/// The directory of the dependency to re-export, as listed in its
/// `export_include_dirs`. If `None`, all of its directories are re-exported.
pub dir: Option<PathBuf>,
/// The target spec for which the re-export applies.
pub target: TargetSpec,
}

/// A package definition.
///
/// Contains the metadata for an individual package.
Expand Down Expand Up @@ -446,7 +463,7 @@ pub struct PartialManifest {
/// The source files.
pub sources: Option<SeqOrStruct<PartialSources, PartialSourceFile>>,
/// The include directories exported to dependent packages.
pub export_include_dirs: Option<Vec<StringOrStruct<PartialIncludeDir>>>,
pub export_include_dirs: Option<Vec<StringOrStruct<PartialExportIncludeDir>>>,
/// The plugin binaries.
pub plugins: Option<IndexMap<String, String>>,
/// Whether the dependencies of the manifest are frozen.
Expand Down Expand Up @@ -581,11 +598,29 @@ impl Validate for PartialManifest {
),
None => None,
};
let exp_inc_dirs = self
let mut exp_inc_dirs = Vec::new();
let mut reexp_inc_dirs = Vec::new();
for entry in self
.export_include_dirs
.unwrap_or_default()
.validate(vctx)
.wrap_err(format!("In export_include_dirs of package `{}`:", pkg.name))?;
.wrap_err(format!("In export_include_dirs of package `{}`:", pkg.name))?
{
match entry {
ExportIncludeDir::Local(trgt, path) => exp_inc_dirs.push((trgt, path)),
ExportIncludeDir::Dep(reexport) => {
if deps.contains_key(&reexport.dep) {
reexp_inc_dirs.push(reexport);
} else {
Errors::ExportDirUnknownDep {
pkg: pkg.name.clone(),
dep: reexport.dep,
}
.downgrade_if_suppressed()?;
}
}
}
}
let plugins = match self.plugins {
Some(s) => s
.iter()
Expand Down Expand Up @@ -639,6 +674,7 @@ impl Validate for PartialManifest {
Ok((trgt, path))
})
.collect::<Result<Vec<_>>>()?,
reexport_include_dirs: reexp_inc_dirs,
plugins,
frozen,
workspace,
Expand Down Expand Up @@ -895,6 +931,87 @@ impl Validate for PartialIncludeDir {
}
}

/// A partial entry of `export_include_dirs`.
///
/// Either a directory of this package (`dir`), or the include directories of a
/// dependency (`dep`, optionally restricted to a single `dir` of that dependency).
#[derive(Serialize, Deserialize, Debug)]
pub struct PartialExportIncludeDir {
/// The target spec for which the include dir applies
pub target: Option<TargetSpec>,
/// The include directory path
pub dir: Option<String>,
/// The dependency whose include directories are re-exported
pub dep: Option<String>,
/// Unknown extra fields
#[serde(flatten)]
extra: HashMap<String, Value>,
}

impl FromStr for PartialExportIncludeDir {
type Err = Void;
fn from_str(s: &str) -> std::result::Result<Self, Void> {
Ok(PartialExportIncludeDir {
target: None,
dir: Some(s.into()),
dep: None,
extra: HashMap::new(),
})
}
}

impl PrefixPaths for PartialExportIncludeDir {
fn prefix_paths(self, prefix: &Path) -> Result<Self> {
// The `dir` of a re-export refers to the dependency, not to this package.
if self.dep.is_some() {
return Ok(self);
}
Ok(PartialExportIncludeDir {
dir: self.dir.prefix_paths(prefix)?,
..self
})
}
}

/// An entry of `export_include_dirs`.
pub enum ExportIncludeDir {
/// An include directory of this package.
Local(TargetSpec, PathBuf),
/// Include directories of a dependency.
Dep(ReexportIncludeDir),
}

impl Validate for PartialExportIncludeDir {
type Output = ExportIncludeDir;
type Error = Error;
fn validate(self, vctx: &ValidationContext) -> Result<ExportIncludeDir> {
if !vctx.pre_output {
self.extra.iter().for_each(|(k, _)| {
Warnings::IgnoreUnknownField {
field: k.clone(),
pkg: vctx.package_name.to_string(),
}
.emit();
});
}
let target = self.target.unwrap_or(TargetSpec::Wildcard);
match (self.dep, self.dir) {
(None, Some(dir)) => Ok(ExportIncludeDir::Local(target, env_path_from_string(&dir)?)),
(Some(_), Some(dir)) if dir.trim().is_empty() => Err(err!(
"The `dir` of a re-exported dependency must not be empty."
)),
(Some(dep), dir) => Ok(ExportIncludeDir::Dep(ReexportIncludeDir {
dep: dep.to_lowercase(),
dir: dir.map(PathBuf::from),
target,
})),
(None, None) => Err(err!(
"An export_include_dirs entry needs a `dir` or a `dep`."
)),
}
}
}

/// A partial filtered preprocessor define
#[derive(Serialize, Deserialize, Debug, Default)]
pub struct PartialDefine {
Expand Down
34 changes: 34 additions & 0 deletions src/diagnostic.rs
Original file line number Diff line number Diff line change
Expand Up @@ -446,6 +446,18 @@ pub enum Warnings {
)
)]
SubmodulesDisabled(String, Vec<String>),

#[error("Package {} re-exports include directories of {}, which is not one of its dependencies.", fmt_pkg!(pkg), fmt_pkg!(dep))]
#[diagnostic(code(W37))]
ExportDirUnknownDep { pkg: String, dep: String },

#[error("Package {} re-exports include directory {} of {}, which does not match any of its `export_include_dirs`.", fmt_pkg!(pkg), fmt_path!(dir.display()), fmt_pkg!(dep))]
#[diagnostic(code(W38))]
ExportDirNotFound {
pkg: String,
dep: String,
dir: PathBuf,
},
}

#[derive(Error, Diagnostic, Debug, Clone)]
Expand All @@ -469,6 +481,24 @@ pub enum Errors {
#[error("Path {} for dependency {} does not exist.", fmt_path!(path.display()), fmt_pkg!(pkg))]
#[diagnostic(code(E32))]
DepPathMissing { pkg: String, path: PathBuf },

#[error("Package {} re-exports include directories of {}, which is not one of its dependencies.", fmt_pkg!(pkg), fmt_pkg!(dep))]
#[diagnostic(
code(E33),
help("Add {} to the `dependencies` of {}, or remove the entry from `export_include_dirs`.", fmt_pkg!(dep), fmt_pkg!(pkg))
)]
ExportDirUnknownDep { pkg: String, dep: String },

#[error("Package {} re-exports include directory {} of {}, which does not match any of its `export_include_dirs`.", fmt_pkg!(pkg), fmt_path!(dir.display()), fmt_pkg!(dep))]
#[diagnostic(
code(E34),
help("The `dir` must be listed in the `export_include_dirs` of {} (relative to its root).", fmt_pkg!(dep))
)]
ExportDirNotFound {
pkg: String,
dep: String,
dir: PathBuf,
},
}

impl Errors {
Expand All @@ -478,6 +508,10 @@ impl Errors {
Errors::IgnoredPath { cause } => Warnings::IgnoredPath { cause },
Errors::FileMissing { path } => Warnings::FileMissing { path },
Errors::DepPathMissing { pkg, path } => Warnings::DepPathMissing { pkg, path },
Errors::ExportDirUnknownDep { pkg, dep } => Warnings::ExportDirUnknownDep { pkg, dep },
Errors::ExportDirNotFound { pkg, dep, dir } => {
Warnings::ExportDirNotFound { pkg, dep, dir }
}
}
}

Expand Down
Loading