Skip to content

Dependencies Overview

Jump to bottom
Nikita Ivanov edited this page Oct 29, 2023 · 8 revisions

Dependencies in Re

Your code can and will depend on other code to function: whether it be some other library in your own project or an external repository, this is nearly always the case.

Re provides a unified interface to specify local and external dependencies in your target config.

‘deps’ config section

The dependencies of your Re target are specified in the deps section of its re.yml file. It is a list of depstrings — specially formatted identifiers defining each dependency.

Examples

# <the rest of your re.yml here...>

deps:
  # Depends on a local target named “libhello”.
  - libhello

  # Depends on a library from Vcpkg.
  - vcpkg:fmt

  # Depends on a library from Conan, specifying a minimum
  # version and that it must be statically linked.
  - conan:libfoobar ^1.2.3 [!shared]

  # Depends on a GitHub repository with a version
  # specifier and a filter.
  - github:osdeverr/rebs ^0.6.0 [buildkit]

  # Depends on a non-GitHub Git repository with a directory
  # filter and regular target filters.
  - git:https://gitlab.com/foo/bar-utils.git ^1.4.7 [/utils-re, libfileutil, libdirlist]

Depstring Format

Schema

[<dep-namespace>:]<dep-name> [<version-operator> <version>] [[filters...]]

Depstring Components

dep-namespace

Determines the source of this dependency, like a specific package manager or online service.

Currently valid values:

  • local — locally available target named <dep-name>.
    • Versions and filters are ignored.
  • vcpkg — Vcpkg package named <dep-name>. Will automatically download and install if not yet available.
    • Versions and filters are ignored due to the nature of Vcpkg.
  • conan — Conan package named <dep-name>. Will automatically download and install if not yet available.
    • Supports versioning.
    • Filters allow you to specify Conan dependency settings, like [shared, !with_mysql].
    • Requires Conan to be available as conan in the command line — you need to install it manually.
  • git — Git repository at URL <dep-name>. The repository will automatically be shallow-cloned to a directory inside .re-cache.
    • The repository must contain a valid Re project, which will be loaded as if it was locally available.
    • Supports versioning via Git tags.
    • Supports filtering by directory and by targets.
  • github — GitHub repository at path <dep-name> (example: osdeverr/rebs). Shorthand for entering a GitHub repo URL with the git namespace.
    • Supports everything git supports.

By default, the local namespace is used.

dep-name

A unique identifier for the dependency inside the namespace. This can be a target name, a package name, a URL or anything else the namespace defines it to be.

version-operator

If specified, the dependency is versioned — that is, Re will download a specific version of it instead of the arbitrary “latest” one.

Currently valid values:

  • @ — use the exact textual version specified in <version>, or throw an error if this version does not exist.
  • == | <= | >= | < | > — use the most recent version equal to, lower than or equal, higher than or equal, lower, or higher than the <version> respectively. Performs a SemVer comparison.
  • ^ — use the most recent version with the same major version number as the specified version. Performs a SemVer comparison.
  • ~ — use the most recent version with the same major and minor version numbers as the specified version. Performs a SemVer comparison.

version

If <version-operator> is present, specifies the version required. If the operator is not @, the version is parsed and treated as SemVer for comparison.

filters

A square-bracket-enclosed, comma-separated list of dependency filters. Allows you to only use a certain part of the dependency pulled or to specify additional settings.

In git and github namespaces, filters let you only use certain targets from the pulled repository.

Example: github:osdeverr/rebs ^0.0.1 [buildkit]

As well as that, if the first filter in the list starts with a slash (/), the resolver will start loading the Re project in the repository from the directory specified in the filter — this lets you depend on a specific directory in the repo which contains the Re target you desire.

In this mode, everything outside of the directory specified will be completely “cut off” and will not be visible to Re — this is only an emergency escape hatch for when the repository does not allow you to properly depend on it without these hacks.

In the conan namespace, filters specify package options to be passed to the package manager. For example, [!shared] will force Conan to build the required library in static mode.

In local and vcpkg, filters are not supported and will be silently ignored.

Resolution

Re tries to resolve all dependencies whenever the project is built or project metadata is generated.

Dependencies are always loaded and built before the targets which depend on them.

Internally, Re flattens the entire project tree into a single ordered list. Targets with less dependencies are placed first: the first target in the list depends on nothing, the last is the one with the most dependencies.

If a circular dependency is present, Re will fail to resolve the entire dependency tree and exit with an error.

Clone this wiki locally