diff options
Diffstat (limited to 'docs/CPMUtil/AddPackage.md')
| -rw-r--r-- | docs/CPMUtil/AddPackage.md | 40 |
1 files changed, 21 insertions, 19 deletions
diff --git a/docs/CPMUtil/AddPackage.md b/docs/CPMUtil/AddPackage.md index 410c84a958..6e9ae1b775 100644 --- a/docs/CPMUtil/AddPackage.md +++ b/docs/CPMUtil/AddPackage.md @@ -17,7 +17,7 @@ - `URL`: The URL to fetch. - `REPO`: The repo to use (`owner/repo`). - `GIT_HOST`: The Git host to use - * Defaults to `github.com`. Do not include the protocol, as HTTPS is enforced. + - Defaults to `github.com`. Do not include the protocol, as HTTPS is enforced. - `TAG`: The tag to fetch, if applicable. - `ARTIFACT`: The name of the artifact, if applicable. - `SHA`: Commit sha to fetch, if applicable. @@ -26,23 +26,23 @@ The following configurations are supported, in descending order of precedence: - `URL`: Bare URL download, useful for custom artifacts - * If this is set, `GIT_URL` or `REPO` should be set to allow the dependency viewer to link to the project's Git repository. - * If this is NOT set, `REPO` must be defined. + - If this is set, `GIT_URL` or `REPO` should be set to allow the dependency viewer to link to the project's Git repository. + - If this is NOT set, `REPO` must be defined. - `REPO + TAG + ARTIFACT`: GitHub release artifact - * The final download URL will be `https://github.com/${REPO}/releases/download/${TAG}/${ARTIFACT}` - * Useful for prebuilt libraries and prefetched archives + - The final download URL will be `https://github.com/${REPO}/releases/download/${TAG}/${ARTIFACT}` + - Useful for prebuilt libraries and prefetched archives - `REPO + TAG`: GitHub tag archive - * The final download URL will be `https://github.com/${REPO}/archive/refs/tags/${TAG}.tar.gz` - * Useful for pinning to a specific tag, better for build identification + - The final download URL will be `https://github.com/${REPO}/archive/refs/tags/${TAG}.tar.gz` + - Useful for pinning to a specific tag, better for build identification - `REPO + SHA`: GitHub commit archive - * The final download URL will be `https://github.com/${REPO}/archive/${SHA}.zip` - * Useful for pinning to a specific commit + - The final download URL will be `https://github.com/${REPO}/archive/${SHA}.zip` + - Useful for pinning to a specific commit - `REPO + BRANCH`: GitHub branch archive - * The final download URL will be `https://github.com/${REPO}/archive/refs/heads/${BRANCH}.zip` - * Generally not recommended unless the branch is frozen + - The final download URL will be `https://github.com/${REPO}/archive/refs/heads/${BRANCH}.zip` + - Generally not recommended unless the branch is frozen - `REPO`: GitHub master archive - * The final download URL will be `https://github.com/${REPO}/archive/refs/heads/master.zip` - * Generally not recommended unless the project is dead + - The final download URL will be `https://github.com/${REPO}/archive/refs/heads/master.zip` + - Generally not recommended unless the project is dead ## Hashing @@ -54,20 +54,20 @@ Hashing strategies, descending order of precedence: - `HASH`: Bare hash verification, useful for static downloads e.g. commit archives - `HASH_SUFFIX`: Download the hash as `${DOWNLOAD_URL}.${HASH_SUFFIX}` - * The downloaded hash *must* match the hash algorithm and contain nothing but the hash; no filenames or extra content. + - The downloaded hash *must* match the hash algorithm and contain nothing but the hash; no filenames or extra content. - `HASH_URL`: Download the hash from a separate URL ## Other Options - `KEY`: Custom cache key to use (stored as `.cache/cpm/${packagename_lower}/${key}`) - * Default is based on, in descending order of precedence: + - Default is based on, in descending order of precedence: - First 4 characters of the sha - `GIT_VERSION` - Tag - `VERSION` - Otherwise, CPM defaults will be used. This is not recommended as it doesn't produce reproducible caches - `DOWNLOAD_ONLY`: Whether or not to configure the downloaded package via CMake - * Useful to turn `OFF` if the project doesn't use CMake + - Useful to turn `OFF` if the project doesn't use CMake - `SOURCE_SUBDIR`: Subdirectory of the project containing a CMakeLists.txt file - `FIND_PACKAGE_ARGUMENTS`: Arguments to pass to the `find_package` call - `BUNDLED_PACKAGE`: Set to `ON` to default to the bundled package @@ -80,12 +80,14 @@ Hashing strategies, descending order of precedence: For each added package, users may additionally force usage of the system/bundled package. +- `${package}_DIR`: Path to a separately-downloaded copy of the package. Note that versioning is not checked! - `${package}_FORCE_SYSTEM`: Require the package to be installed on the system - `${package}_FORCE_BUNDLED`: Force the package to be fetched and use the bundled version ## System/Bundled Packages Descending order of precedence: + - If `${package}_FORCE_SYSTEM` is true, requires the package to be on the system - If `${package}_FORCE_BUNDLED` is true, forcefully uses the bundled package - If `CPMUTIL_FORCE_SYSTEM` is true, requires the package to be on the system @@ -101,8 +103,8 @@ URLs: - `GIT_URL` - `REPO` as a Git repository - * You may optionally specify `GIT_HOST` to use a custom host, e.g. `GIT_HOST git.crueter.xyz`. Note that the git host MUST be GitHub-like in its artifact/archive downloads, e.g. Forgejo - * If `GIT_HOST` is unspecified, defaults to `github.com` + - You may optionally specify `GIT_HOST` to use a custom host, e.g. `GIT_HOST git.crueter.xyz`. Note that the git host MUST be GitHub-like in its artifact/archive downloads, e.g. Forgejo + - If `GIT_HOST` is unspecified, defaults to `github.com` - `URL` Versions (bundled): @@ -113,4 +115,4 @@ Versions (bundled): - `TAG` - "unknown" -If the package is a system package, AddPackage will attempt to determine the package version and append ` (system)` to the identifier. Otherwise, it will be marked as `unknown (system)` +If the package is a system package, AddPackage will attempt to determine the package version and append `(system)` to the identifier. Otherwise, it will be marked as `unknown (system)` |