vcpkg/docs/maintainers/vcpkg_download_distfile.md

# vcpkg_download_distfile

The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_download_distfile.md).

Download and cache a file needed for this port.

This helper should always be used instead of CMake's built-in `file(DOWNLOAD)` command.

## Usage
```cmake
vcpkg_download_distfile(
    <OUT_VARIABLE>
    URLS <http://mainUrl> <http://mirror1>...
    FILENAME <output.zip>
    SHA512 <5981de...>
)
```
## Parameters
### OUT_VARIABLE
This variable will be set to the full path to the downloaded file. This can then immediately be passed in to [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md) for sources.

### URLS
A list of URLs to be consulted. They will be tried in order until one of the downloaded files successfully matches the SHA512 given.

### FILENAME
The local name for the file. Files are shared between ports, so the file may need to be renamed to make it clearly attributed to this port and avoid conflicts.

### SHA512
The expected hash for the file.

If this doesn't match the downloaded version, the build will be terminated with a message describing the mismatch.

### QUIET
Suppress output on cache hit

### SKIP_SHA512
Skip SHA512 hash check for file.

This switch is only valid when building with the `--head` command line flag.

### HEADERS
A list of headers to append to the download request. This can be used for authentication during a download.

Headers should be specified as "<header-name>: <header-value>".

## Notes
The helper [`vcpkg_from_github`](vcpkg_from_github.md) should be used for downloading from GitHub projects.

## Examples

* [apr](https://github.com/Microsoft/vcpkg/blob/master/ports/apr/portfile.cmake)
* [fontconfig](https://github.com/Microsoft/vcpkg/blob/master/ports/fontconfig/portfile.cmake)
* [freetype](https://github.com/Microsoft/vcpkg/blob/master/ports/freetype/portfile.cmake)

## Source
[scripts/cmake/vcpkg\_download\_distfile.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_download_distfile.cmake)
[vcpkg-docs] Rework documentation for compatibility with readthedocs.io and MkDocs. 2017-05-25 14:33:16 +08:00			`# vcpkg_download_distfile`

[docs] Fix the automatically generated document URL (#16611) * [document] Fix the automatically generated document URL * [docs] Format all documents 2021-03-11 01:56:07 +08:00			`The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_download_distfile.md).`
[scripts-audit] Rollup PR 2021-02-26 (#16440) * [scripts-audit rollup] PR #16419 * pull the cmake doc comment parsing out into its own function * support cmake helper ports * add real support for deprecation, as opposed to ad-hoc * [scripts-audit rollup] PR #16192 * add a z_ in front of internal functions * move internal functions out set feature_vars again in parent scope * [scripts-audit rollup] PR #16309 Audit vcpkg_copy_pdbs * [scripts-audit rollup] PR #16304 * Fix usage, documentation * [scripts-audit rollup] PR #16393 * [scripts-audit rollup] PR #16377 Deprecate `vcpkg__cmake` in favor of `vcpkg_cmake_` from the `vcpkg-cmake` port, as well as `vcpkg_fixup_cmake_targets` in favor of `vcpkg_cmake_config_fixup` from the `vcpkg-cmake-config` port. 2021-03-01 05:17:19 +08:00
[vcpkg-docs] Rework documentation for compatibility with readthedocs.io and MkDocs. 2017-05-25 14:33:16 +08:00			`Download and cache a file needed for this port.`

[vcpkg-download-distfile] Regenerate docs and enable SKIP_SHA512 only in unstable (head) mode 2018-01-06 08:16:08 +08:00			This helper should always be used instead of CMake's built-in `file(DOWNLOAD)` command.

[vcpkg-docs] Rework documentation for compatibility with readthedocs.io and MkDocs. 2017-05-25 14:33:16 +08:00			`## Usage`
			```cmake
			`vcpkg_download_distfile(`
			`<OUT_VARIABLE>`
			`URLS <http://mainUrl> <http://mirror1>...`
			`FILENAME <output.zip>`
			`SHA512 <5981de...>`
			`)`
			```
			`## Parameters`
			`### OUT_VARIABLE`
			This variable will be set to the full path to the downloaded file. This can then immediately be passed in to [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md) for sources.

			`### URLS`
			`A list of URLs to be consulted. They will be tried in order until one of the downloaded files successfully matches the SHA512 given.`

			`### FILENAME`
			`The local name for the file. Files are shared between ports, so the file may need to be renamed to make it clearly attributed to this port and avoid conflicts.`

			`### SHA512`
			`The expected hash for the file.`

			`If this doesn't match the downloaded version, the build will be terminated with a message describing the mismatch.`

[gdal] Update to 3.1.3 (#13449) * [vcpkg__nmake] Add option INSTALL_COMMAND [gdal] Update to 3.1.3 and switch to vcpkg__nmake on Windows [vcpkg_build_make] Add option MAKEFILE * fix install on windows, fix linux build * fix options position * [gdal] Fix linux build * [gdal] Fix expat library name * [gdal] Fix geos library name * [gdal] Fix cmake wrapper * [pdal] Fix dependency geos * [pdal] Fix PDALConfig.cmake * [gdal] Fix dependency cfitsio on inx disable cfitsio temporary * [gdal] Correct cmake wrapper and usage * [gdal] Fix tools on windows-static * Revert a9ac823007975485aacc7e1f3eb4053e295376e1 * Apply suggestions * [vcpkg_build_nmake] Fix install command * [vcpkg_build_nmake] Fix install command * regenerate docs * [gdal] Update dependency iconv and charset library names * [gdal] add json-c as a dependency on non-windows Co-authored-by: Billy Robert O'Neal III <bion@microsoft.com> Co-authored-by: Nicole Mazzuca <mazzucan@outlook.com> 2020-11-21 02:29:25 +08:00			`### QUIET`
			`Suppress output on cache hit`

[vcpkg-download-distfile] Regenerate docs and enable SKIP_SHA512 only in unstable (head) mode 2018-01-06 08:16:08 +08:00			`### SKIP_SHA512`
			`Skip SHA512 hash check for file.`

			This switch is only valid when building with the `--head` command line flag.

Add headers to vcpkg_download_distfile (#5640) * Add headers to vcpkg_download_distfile Allows headers to be appended when downloading a distribution. This allows for setting authentication headers to download from a private repository. * [scripts,docs] Regenerate docs for portfile functions * [docs,scripts] Fix typo regressions * [docs,scripts] Fix broken link 2019-03-15 04:43:49 +08:00			`### HEADERS`
			`A list of headers to append to the download request. This can be used for authentication during a download.`

			`Headers should be specified as "<header-name>: <header-value>".`

[vcpkg-docs] Rework documentation for compatibility with readthedocs.io and MkDocs. 2017-05-25 14:33:16 +08:00			`## Notes`
[vcpkg-download-distfile] Regenerate docs and enable SKIP_SHA512 only in unstable (head) mode 2018-01-06 08:16:08 +08:00			The helper [`vcpkg_from_github`](vcpkg_from_github.md) should be used for downloading from GitHub projects.
[vcpkg-docs] Rework documentation for compatibility with readthedocs.io and MkDocs. 2017-05-25 14:33:16 +08:00
			`## Examples`

[vcpkg-download-distfile] Regenerate docs and enable SKIP_SHA512 only in unstable (head) mode 2018-01-06 08:16:08 +08:00			`* [apr](https://github.com/Microsoft/vcpkg/blob/master/ports/apr/portfile.cmake)`
[vcpkg-docs] Rework documentation for compatibility with readthedocs.io and MkDocs. 2017-05-25 14:33:16 +08:00			`* [fontconfig](https://github.com/Microsoft/vcpkg/blob/master/ports/fontconfig/portfile.cmake)`
[vcpkg_install_qmake] Add vcpkg_install_qmake (#9412) * [vcpkg_install_qmake] Add vcpkg_install_qmake and convert existing ports to use it. [vcpkg_configure_qmake] Add 'staticlib' to CONFIG in static builds * [vcpkg_configure_qmake] Don't specify DESTDIR * [libqglviewer][vcpkg_configure_qmake] Add staticlib CONFIG only for libqglviewer * [qt5-base] Increment version to track changes in vcpkg_configure_qmake() 2019-12-23 22:10:12 +08:00			`* [freetype](https://github.com/Microsoft/vcpkg/blob/master/ports/freetype/portfile.cmake)`
[vcpkg-docs] Rework documentation for compatibility with readthedocs.io and MkDocs. 2017-05-25 14:33:16 +08:00
			`## Source`
[scripts-audit] Rollup PR 2021-02-26 (#16440) * [scripts-audit rollup] PR #16419 * pull the cmake doc comment parsing out into its own function * support cmake helper ports * add real support for deprecation, as opposed to ad-hoc * [scripts-audit rollup] PR #16192 * add a z_ in front of internal functions * move internal functions out set feature_vars again in parent scope * [scripts-audit rollup] PR #16309 Audit vcpkg_copy_pdbs * [scripts-audit rollup] PR #16304 * Fix usage, documentation * [scripts-audit rollup] PR #16393 * [scripts-audit rollup] PR #16377 Deprecate `vcpkg__cmake` in favor of `vcpkg_cmake_` from the `vcpkg-cmake` port, as well as `vcpkg_fixup_cmake_targets` in favor of `vcpkg_cmake_config_fixup` from the `vcpkg-cmake-config` port. 2021-03-01 05:17:19 +08:00			`[scripts/cmake/vcpkg\_download\_distfile.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_download_distfile.cmake)`