Boost Clone

This action clones the Boost source directory, attempting to get it from the cache first. Only the specified modules are cloned and cached.

This is usually the next step in your workflow after setting up a C++ compiler with Setup C++ or installing other dependencies with Install Packages.

Cloning boost is useful when one wants the always use the latest version of boost in a library or is writing a boost proposal. For other use cases, individual boost modules can be fetched with vcpkg in Install Packages or directly included in a package manager manifest.

Besides the explicitly specified list of modules, the action can also scan directories for boost dependencies to implicitly determine what modules should be cloned.

The union of the implicitly and explicitly specified modules is cloned. Caching is based only on these dependencies.

For a project with about 5 boost dependencies, caching saves about 4 minutes in the workflow. When there’s no cache, the scanning scripting saves us about 3 minutes.

Cache key details

The action derives its cache key from three independent SHA-1 fragments:

boostHash – the Boost super-project revision (covers pessimistic caching paths).
modulesAndPatchesHash – hashes of explicitly requested modules plus optional patch repositories.
configHash – the normalized configuration (branch, scan include/exclude lists, directories, ignore set, and the optimistic flag).

Only the fragments relevant to the chosen caching mode are included: optimistic caching uses modulesAndPatchesHash plus configHash (and falls back to boostHash when no modules or patches are provided) because module hashes already capture upstream changes; pessimistic caching always includes boostHash and only appends modulesAndPatchesHash when patches are present to avoid redundant invalidations.

These fragments are concatenated with - separators (for example, boost-source-${modulesAndPatchesHash}-${configHash}), so any change in source revision, requested modules/patches, or configuration forces a new cache key while still avoiding needless cache churn.

Next steps

After cloning boost modules for your C++ project, the next step in your workflow should usually be CMake Workflow. If you are developing a Boost library, it is also usual for the next step to be the B2 Workflow.

Example

steps:
- name: Clone Boost.Variant2
  uses: alandefreitas/cpp-actions/boost-clone@v1.9.2
  id: boost-clone
  with:
    branch: master
    modules: variant2

Input Parameters

Parameter

Description

Default

boost-dir

The directory where Boost should be cloned.

If no value is provided (default), the action will clone boost in a temporary directory.

branch

Branch of the super-project.

Boost projects should usually set this to develop or master according to the project branch they are working on.

master

patches

A list of patches to apply to the boost super-project.

A patch is a module intended as a Boost library that is not yet part of the super-project.

Each path will be cloned in the libs directory of the super-project. ⚠️ This parameter is required.

modules

The boost submodules we need to clone.

This field is optional. If not set, the action will scan the modules found in scan-modules-dir.

scan-modules-dir

An independent directory we should scan for boost dependencies to clone. This option also accepts a multi-line string with multiple directories.

This is usually a directory in the current project that requires boost libraries. The Boost modules required in files from this directory will be added to the modules list.

Only the subdirectories of this directory specified by modules-scan-paths will be scanned.

.

modules-scan-paths

Additional module subdirectory to scan.

For instance, by setting it to test the action will scan the test directory for boost dependencies.

By default, the action scans the ['include', 'src', 'source', 'test', 'tests', 'example', 'examples'] directories.

modules-exclude-paths

Module subdirectory to exclude from scanning.

Directories that match any of the values in this list will be ignored.

By default, the action excludes the ['test', 'tests'] directories.

test tests

scan-modules-ignore

List of modules that should be ignored in scan-modules.

This if often useful to exclude the current project’s libraries from the scan.

cache

Cache the boost source directory for future builds. The cache key will include the boost hash, the modules hash and the patch hashes.

When using the cache, the action will not rescan dependencies. This means that if a transitive dependency is updated and optimistic-caching is being used, the cache will not be invalidated. The previous version of the transitive dependency will be used until the cache expires.

true

optimistic-caching

If this option is true, the action will reuse the cache whenever direct dependencies haven’t changed.

For instance, if your library depends on Boost.Url and Boost.Url depends on Boost.Optional, then the cache will be reused for as long as Boost.Url hasn’t changed, even if Boost.Optional has changed. If you know about a change in a transitive dependency that affects your library, the current cache should be invalidated for the changes to take effect.

In the develop branch, this makes the cache much more useful, as the super-project hash changes many times a day and the cache would be invalidated every time that happens. The downside is that if a transitive dependency is updated, the cache will not be invalidated until the current cache expires. However, this option assumes changes in transitive dependencies should not usually affect the library.

If this option is set to false, the cache will be invalidated whenever the hash of the Boost super-project repository changes, which implies it’s also updated whenever a transitive dependency is updated. Note that in this pessimistic case, the cache will be invalidated even if the change in the super-project is unrelated to the library, even when considering transitive dependencies. This makes the pessimistic option more pessimistic than it should be.

The reason we have to use the main super-project hash in the cache key is that calculating a new hash only for transitive dependencies would require us to clone these transitive dependencies, which makes the cache useless.

The default value is false, because we prioritize correctness over performance. However, most users should consider the possibility of setting this option to true, considering their requirements.

false

trace-commands

Trace commands executed by the workflow.

false

clone-strategy

Strategy for obtaining Boost source files.

- auto: Automatically select the best strategy based on branch type and module count. For release tags with many modules (>25), downloads the CMake release archive. For develop/master or few modules, uses git clone with batch initialization. - git: Always use git clone (current behavior, with batch-init optimization). - archive: Always download the CMake release archive (only works for release tags).

The archive strategy is faster when many modules are needed, as it avoids per-module git overhead. However, it only works for release tags (e.g., boost-1.87.0), not for develop/master branches.

auto

archive-threshold

Number of total modules (including transitive dependencies) above which the archive strategy is preferred over git clone.

Only applies when clone-strategy is 'auto' and branch is a release tag.

The default of 25 is an approximate crossover point based on typical network conditions. Archive download has a fixed overhead (~30s for the ~80MB CMake archive) but no per-module cost. Git clone has lower initial cost but adds ~0.5-1s per module for submodule initialization. For projects needing fewer modules, git is faster; for more modules, archive becomes more efficient. Adjust based on your network and typical module count.

25

Outputs

Output

Description

boost-dir

The absolute path to the boost source files.