{"id":34227951,"url":"https://github.com/jpetrie/fetch-dependency","last_synced_at":"2026-01-25T18:16:22.119Z","repository":{"id":215849155,"uuid":"739917709","full_name":"jpetrie/fetch-dependency","owner":"jpetrie","description":"Configuration-time dependency management for CMake.","archived":false,"fork":false,"pushed_at":"2025-11-14T03:20:36.000Z","size":102,"stargazers_count":2,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-14T04:18:30.262Z","etag":null,"topics":["cmake"],"latest_commit_sha":null,"homepage":"","language":"CMake","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jpetrie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-01-06T23:49:30.000Z","updated_at":"2025-11-14T03:20:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"89d41358-3e1d-44b2-9172-c8ba31fb24c7","html_url":"https://github.com/jpetrie/fetch-dependency","commit_stats":null,"previous_names":["jpetrie/fetch-dependency"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/jpetrie/fetch-dependency","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpetrie%2Ffetch-dependency","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpetrie%2Ffetch-dependency/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpetrie%2Ffetch-dependency/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpetrie%2Ffetch-dependency/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jpetrie","download_url":"https://codeload.github.com/jpetrie/fetch-dependency/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpetrie%2Ffetch-dependency/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28756433,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T16:32:25.380Z","status":"ssl_error","status_checked_at":"2026-01-25T16:32:09.189Z","response_time":113,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cmake"],"created_at":"2025-12-16T01:00:25.951Z","updated_at":"2026-01-25T18:16:22.113Z","avatar_url":"https://github.com/jpetrie.png","language":"CMake","readme":"# FetchDependency\nFetchDependency is a CMake module that provides a mechanism to download, configure, build and install (local to the\ncalling project) a dependency package at configuration time.\n\nFetchDependency is designed to enable dependency handling in CMake according to a specific philosophy:\n - A project's dependencies should be made available automatically, to enable the quickest turnaround time from fetching\n   a project from source control to a successful build of that project.\n - A project's dependencies should be stored with it by default, rather than in a global location, in order to isolate\n   the project from changes made outside the project itself.\n - A project's dependencies should not pollute the targets of the project or any other dependencies, in order to\n   avoid target name collisions and keep the project's target list focused.\n\nThe cost of the aforementioned features is increased configuration time when using FetchDependency, especially during\nthe initial configuration, as all dependencies are downloaded and built from source. This is _noticeably un-CMake-like\nbehavior_, but it is necessary to achieve the above.\n\nTo alleviate the impact of configure-time builds, FetchDependency attempts to minimize build invocations by tracking\ninformation about the build such as its commit hash and the options used to configure it. Additionally, most of\nFetchDependency's expensive logic can be temporarily bypassed entirely by setting the environment variable\n`FETCH_DEPENDENCY_FAST` to 1. This enables rapid iteration on your build infrastructure following the initial configure\nand build of all dependencies.\n\n## Installation\nFetchDependency requires CMake 3.25 or later.\n\nThe recommended way to automatically include FetchDependency in your project is to use CMake's\n[FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html) module:\n\n```cmake\ninclude(FetchContent)\nFetchContent_Declare(FetchDependency\n  GIT_REPOSITORY https://github.com/jpetrie/fetch-dependency.git\n  GIT_TAG 1.2.2\n)\nFetchContent_MakeAvailable(FetchDependency)\ninclude(${fetchdependency_SOURCE_DIR}/FetchDependency.cmake)\n```\n\n## Usage\nCalling `fetch_dependency()` will fetch, build and install a dependency package:\n```cmake\n  fetch_dependency(Catch2 GIT_SOURCE https://github.com/catchorg/Catch2.git VERSION v2.13.8 CONFIGURATION Release)\n```\n\nThis will make the Release configuration of [Catch2](https://github.com/catchorg/Catch2) immediately available to the\ncalling project's future targets:\n```cmake\n  target_link_libraries(... Catch2::Catch2)\n```\n\nFetchDependency can resolve targets for dependencies that support\n[`find_package()`](https://cmake.org/cmake/help/latest/command/find_package.html) (in config mode) or\n[`PkgConfig`](https://cmake.org/cmake/help/latest/module/FindPkgConfig.html). FetchDependency does not generate or alias\nany targets on its own. The resolved target names will be those defined by the dependency itself, with the exception of\ntargets found by `PkgConfig` (which itself creates imported targets within a `PkgConfig::` namespace).\n\nIf you need to build multiple configurations of a dependency, you can use `declare_dependency()` to pre-declare a\ndependency configuration and its associated options before calling `fetch_dependency()`. See the full documentation\nbelow for details.\n\n## Documentation\n### `fetch_dependency()`\nDownload, build and locally install a dependency named `\u003cname\u003e` during configuration.\n```\n  fetch_dependency(\n    \u003cname\u003e\n    LOCAL_SOURCE \u003cpath\u003e\n    GIT_SOURCE \u003curl\u003e\n    [VERSION \u003cversion\u003e]\n    [NO_RESOLVE]\n    [NO_BUILD]\n    [GIT_DISABLE_SUBMODULES]\n    [GIT_DISABLE_SUBMODULE_RECURSION]\n    [GIT_SUBMODULES \u003cpaths...\u003e]\n    [SOURCE_ROOT \u003cpath\u003e]\n    [BINARY_ROOT \u003cpath\u003e]\n    [PACKAGE_NAME \u003cpackage\u003e]\n    [GENERATOR \u003cgenerator\u003e]\n    [CONFIGURATION \u003cconfiguration\u003e]\n    [CONFIGURE_OPTIONS \u003coptions...\u003e]\n    [BUILD_OPTIONS \u003coptions...\u003e]\n    [CMAKELIST_SUBDIRECTORY \u003cpath\u003e]\n    [LIST_SEPARATOR \u003cseparator\u003e]\n    [OUT_SOURCE_DIR \u003cout-var\u003e]\n  )\n```\n`\u003cname\u003e` is used to create the directory where the dependency's source and artifacts will be stored. Unless\n`PACKAGE_NAME` is provided (see below), it will also be used in the internal `find_package()` call to locate the\ndependency's targets.\n\nOne of `LOCAL_SOURCE` or `GIT_SOURCE` are required, and they are mutually exclusive.\n\nOptions:\n - `LOCAL_SOURCE \u003cpath\u003e` Path to the source of the dependency on the local file system.\n - `GIT_SOURCE \u003curl\u003e` URL of the Git repository. See the documentation for the `ROOT` parameter below for detail on\n   where the repository will be cloned.\n - `VERSION \u003cversion\u003e` Version string associated with the source. For local sources, this is unused and shouldn't be\n   provided. For Git sources, this is a Git branch name, tag or commit hash. A commit hash is the recommended means of\n   specifying a dependency version. Branches must be specified with their name to ensure they are correctly updated.\n   Specifying a commit hash is recommended because it can allow the `git fetch` operation to be avoided during configure\n   when the local copy is already on the specified tag. This option is required when `GIT_SOURCE` is specified.\n - `NO_RESOLVE` Do not attempt to resolve the dependency's targets by calling `find_package()`. This flag is useful if a\n   dependency does not generate the configuration files neccessary for `find_package()` to work (for example, if the\n   dependency ships with `pkg-config` metadata instead).\n - `NO_BUILD` Do not build or install the dependency. This is useful for dependencies where only the source is needed.\n   Note that this will still _configure_ the dependency (this is required to enable updates if `VERSION` is changed, due\n   to how `fetch_dependency()` is implemented). If you do not want the dependency configured (or it is not a CMake\n   project), consider using CMake's [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html) module\n   instead. Setting this option implies `NO_RESOLVE`.\n - `GIT_DISABLE_SUBMODULES` Prevent submodule updates when downloading the dependency (in other words, do not execute\n   `git submodule` commands).\n - `GIT_DISABLE_SUBMODULE_RECURSION` Prevent submodule updates from recursively updating additional submodules (in other\n   words, do not pass `--recursive` to `git submodule` commands).\n - `GIT_SUBMODULES \u003cpaths...\u003e` Process only the specified submodule paths during submodule updates. If this option is\n   not specified, all submodules will be updated. `GIT_DISABLE_SUBMODULES` will override this option.\n - `SOURCE_ROOT \u003cpath\u003e` The root storage directory for dependency source code (except when `LOCAL_SOURCE` is used). If\n   not specified, the value of the global `FETCH_DEPENDENCY_DEFAULT_SOURCE_ROOT` will be used. If that global is not\n   defined, the value \"External\" will be used. If the root is a relative path, it will be interpreted as relative to\n   `CMAKE_BINARY_DIR`. If the normalized value of this path is the same as that of `BINARY_ROOT`, then the subdirectory\n   \"Source\" will be added to the source root in order to avoid potential conflicts with binary root subdirectories.\n - `BINARY_ROOT \u003cpath\u003e` The root storage directory for dependency binary direcetory and associated artifacts. If not\n   specified, the value of the global `FETCH_DEPENDENCY_DEFAULT_BINARY_ROOT` will be used. If that global is not\n   defined, the value \"External\" will be used. If the root is a relative path, it will be interpreted as relative to\n   `CMAKE_BINARY_DIR`.\n - `PACKAGE_NAME \u003cpackage\u003e` Pass `\u003cpackage\u003e` to `find_package()` internally when locating the built dependency's\n   targets. If not specified, the value of `\u003cname\u003e` will be used.\n - `GENERATOR \u003cgenerator\u003e` Use the specified generator to configure the dependency, instead of inheriting the value of\n   `CMAKE_GENERATOR` from the outer project. This parameter is required when calling `fetch_dependency` in [script\n   mode](https://cmake.org/cmake/help/latest/manual/cmake.1.html#cmdoption-cmake-P), because `CMAKE_GENERATOR` will not\n   be set.\n - `CONFIGURATION \u003cname\u003e` Use the named configuration instead of the default for the dependency. Specifying a\n   configuration via this option will work correctly regardless of whether or not the generator in use is a single-\n   or multi-configuration generator. If not specified, \"Release\" is assumed.\n - `CONFIGURE_OPTIONS \u003coptions...\u003e` Pass the following options to CMake when generating the dependency.\n - `BUILD_OPTIONS \u003coptions...\u003e` Pass the following options to CMake's `--build` command when building the dependency.\n - `CMAKELIST_SUBDIRECTORY \u003cpath\u003e` The path to the directory containing the `CMakeLists.txt` for the dependency if it\n   is not located at the root of the dependency's source tree. Always interpreted as a path relative to the dependency's\n   source tree.\n - `LIST_SEPARATOR \u003cseparator\u003e` A string that FetchDependency will replace with `;` just prior to writing the values of\n   `CONFIGURE_OPTIONS` or `BUILD_OPTIONS` to the corresponding step script. This must be used when semicolons need to be\n   included in option values, for example when needing to pass `-DCMAKE_OSX_ARCHITECTURES=\"x86_64;arm64\"`. The `;`\n   character will cause CMake to split the value in two, so instead must set `LIST_SEPARATOR` to something like `\"\u003cs\u003e\"`\n   and write `-DCMAKE_OSX_ARCHITECTURES=\"x86_64\u003cs\u003earm64\"` in `CONFIGURE_OPTIONS`. The value of `LIST_SEPARATOR` applies\n   to any configurations pre-declared using `declare_dependency()` for this dependency as well.\n - `OUT_SOURCE_DIR \u003cout-var\u003e` The name of a variable that will be set to the absolute path to the dependency's source`\n   tree.\n\n### `declare_dependency()`\nPre-declare a dependency's configuration.\n```\n  declare_dependency(\n    \u003cname\u003e\n    CONFIGURATION \u003cpath\u003e\n    [CONFIGURE_OPTIONS \u003coptions...\u003e]\n    [BUILD_OPTIONS \u003coptions...\u003e]\n    [OUT_BINARY_DIR \u003cout-var\u003e]\n  )\n```\n\n`declare_dependency()` must be called before the corresponding `fetch_dependency()` call. When pre-declaring\nconfigurations, it isn't neccessary to pass configuration-related parameters to `fetch_dependency()`. All declared\nconfigurations will be built and installed.\n\n`\u003cname\u003e` must match the name used when `fetch_dependency()` is called.\n\nOptions:\n - `CONFIGURATION \u003cname\u003e` The configuration to declare.\n - `CONFIGURE_OPTIONS \u003coptions...\u003e` Pass the following options to CMake when generating this configuration of the\n   dependency.\n - `BUILD_OPTIONS \u003coptions...\u003e` Pass the following options to CMake's `--build` command when building this configuration\n   of the dependency.\n - `OUT_BINARY_DIR \u003cout-var\u003e` The name of a variable that will be set the absolute path to the dependency's binary tree.\n   Note that this variable will not be written to until the corresponding `fetch_dependency()` call completes.\n\n### `export_dependencies()`\nExport dependencies for use in other CMake list files.\n```\n  export_dependencies(\n    [NO_FINDPACKAGE]\n    PATH \u003cpath\u003e\n  )\n```\n\n`export_dependencies()` will write a file to `\u003cpath\u003e` that can be used to import fetched dependency information in\nanother CMake list file. It is intended to be used when calling `fetch_dependency()` in [script\nmode](https://cmake.org/cmake/help/latest/manual/cmake.1.html#cmdoption-cmake-P) to enable another CMake list file, in\nproject mode, to import fetched dependencies.\n\nA project-mode list file can consume the exported dependencies by calling\n[`include()`](https://cmake.org/cmake/help/latest/command/include.html) and passing `\u003cpath\u003e`. Including the export file\nwill:\n - set `FETCH_DEPENDENCY_PACKAGE_PATHS` and `FETCH_DEPENDENCY_PACKAGE_NAMES` (see below)\n - append the package paths to `CMAKE_PREFIX_PATH`\n - call [`find_package()`](https://cmake.org/cmake/help/latest/command/find_package.html) on each dependency\n\nOptions:\n - `PATH \u003cpath\u003e` The path to the export file to generate.\n - `NO_FINDPACKAGE` If set, prevents the generated script from setting `CMAKE_PREFIX_PATH` or calling `find_package()`.\n   This is useful if any additional logic is needed by a project prior to finding the dependency packages.\n\n### `FETCH_DEPENDENCY_DEFAULT_SOURCE_ROOT`\nDefines the default source root directory for fetched dependencies. It is initially undefined, which causes\n`fetch_dependency()` to fall back to storing dependency source underneath `${CMAKE_BINARY_DIR}/External/`. \n\n### `FETCH_DEPENDENCY_DEFAULT_BINARY_ROOT`\nDefines the default source root directory for dependency binary directories. It is initially undefined, which causes\n`fetch_dependency()` to fall back to storing dependency binaries underneath `${CMAKE_BINARY_DIR}/External/`. \n\n### `FETCH_DEPENDENCY_PACKAGE_PATHS`\nStores the set of package directories fetched by the project (and all of its dependencies, recursively) so far.\n\n### `FETCH_DEPENDENCY_PACKAGE_NAMES`\nStores the set of package names fetched by the project (and all of its dependencies, recursively) so far.\n\n### `FETCH_DEPENDENCY_PACKAGES`\n⚠️ _This variable is deprecated and will be removed in a future version of FetchDependency. Use\n`FETCH_DEPENDENCY_PACKAGE_PATHS` instead._ ⚠️\n\nStores the set of package directories fetched by the project (and all of its dependencies, recursively) so far.\n\n## Recipes\n### Fast Build Infrastructure Iteration\nIn cases where you need to work on your project's `CMakeLists.txt` or similar and will be repeatedly re-configuring your\nproject, it can be desirable to skip as much of FetchDependency's overhead as possible. This can be accomplished by\nsetting the environment variable `FETCH_DEPENDENCY_FAST` to 1.\n\nWhen this \"fast mode\" is enabled, `fetch_dependency()` only executes the logic needed to call `find_package()` on the\ndependency. It skips the up-to-date checks and build attempts that it might normally run, saving considerable time in\nthe configuration process (especially if you have many dependencies).\n\n\"Fast mode\" requires that a regular configure has been executed at least once, or the files necessary for the\n`find_package()` machinery to work correctly will not exist and the configuration will fail.\n\n### Local Dependency Edits\nSometimes it is necessary to make local changes to a dependency - if it's something you are developing it parallel to\nyour main project, or if there are bugs you're trying to address. FetchDependency generates CMake projects for each\ndependency, so it is possible to simply use those generated projects as you would normally. FetchDependency also allows\nyou to reproduce the configure and build steps it uses exactly by executing scripts in the `State` subdirectory of the\ndependency folder. These scripts will be named `configure.sh`/`build.sh` or `configure.bat`/`build.bat` depending on\nyour OS. \n\nWhen FetchDependency detects a local change to a dependency's source (either because `LOCAL_SOURCE` is in use, or\nbecause the Git working tree is dirty), it will never attempt to perform any updates to the source and it will always\nattempt to trigger the build step. Note that there is no link created between dependency source files and any targets\nin your main project, so simply building that may not detect local changes to a dependency - you will need to explicitly\nrun CMake against your main project, or use the per-dependency scripts within their state folder.\n\nKeep in mind that if you are using `GIT_SOURCE` for your dependency, the dependency's working tree is very likely in a\n\"detached HEAD\" state (confirm with `git status`). If that is true and you want to commit any local edits you make, you\nwill need to make sure to create a branch from the local changes, switch over to a real branch, and merge those changes\nback in.\n\n","funding_links":[],"categories":["Package Management / Build Systems"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpetrie%2Ffetch-dependency","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjpetrie%2Ffetch-dependency","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpetrie%2Ffetch-dependency/lists"}