mirror of
https://github.com/microsoft/vcpkg.git
synced 2024-12-24 19:07:50 +08:00
6118e6b134
* Remove documentation of disabled legacy parameter * Document unique source directories * Update example * Remove one more ref to REF
155 lines
4.9 KiB
Markdown
155 lines
4.9 KiB
Markdown
# vcpkg_extract_source_archive
|
|
|
|
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_extract_source_archive.md).
|
|
|
|
Extract an archive.
|
|
|
|
## Usage
|
|
```cmake
|
|
vcpkg_extract_source_archive(
|
|
<out-var>
|
|
ARCHIVE <path>
|
|
[NO_REMOVE_ONE_LEVEL]
|
|
[SKIP_PATCH_CHECK]
|
|
[PATCHES <patch>...]
|
|
[SOURCE_BASE <base>]
|
|
[BASE_DIRECTORY <relative-path> | WORKING_DIRECTORY <absolute-path>]
|
|
)
|
|
```
|
|
|
|
## Parameters
|
|
|
|
<a id="out-var"></a>
|
|
|
|
### `<out-var>`
|
|
|
|
Name of the variable to set with the directory containing the extracted contents.
|
|
|
|
### ARCHIVE
|
|
|
|
Full path to the archive to extract.
|
|
|
|
### NO_REMOVE_ONE_LEVEL
|
|
|
|
Skip removing the top level directory of the archive.
|
|
|
|
Most archives contain a single top-level directory, such as:
|
|
|
|
```
|
|
zlib-1.2.11/
|
|
doc/
|
|
...
|
|
examples/
|
|
...
|
|
ChangeLog
|
|
CMakeLists.txt
|
|
README
|
|
zlib.h
|
|
...
|
|
```
|
|
|
|
By default, `vcpkg_extract_source_archive` removes this directory and moves all contents into the directory returned in `<out-var>`. If there is no top-level directory, it is an error.
|
|
|
|
With this flag, the top-level directory will be preserved and it is not an error to not have one.
|
|
|
|
### SKIP_PATCH_CHECK
|
|
|
|
Silence and ignore errors when applying patches.
|
|
|
|
This option should only be passed when operating in an unstable mode like `--head`. If the sources are pinned, failing to apply a patch should be considered a fatal error.
|
|
|
|
### PATCHES
|
|
|
|
List of patches to apply to the extracted source.
|
|
|
|
Patches will be applied in order, after any top-level directories are removed (see [`NO_REMOVE_ONE_LEVEL`](#no_remove_one_level)). Relative paths are interpreted relative to the current port directory.
|
|
|
|
If a patch should be conditionally applied based on target information, you can construct a list and splat it.
|
|
|
|
```cmake
|
|
set(patches "")
|
|
if(VCPKG_TARGET_IS_WINDOWS)
|
|
list(APPEND patches only-windows.patch)
|
|
endif()
|
|
vcpkg_extract_source_archive(src
|
|
ARCHIVE "${archive}"
|
|
PATCHES
|
|
always-applied.patch
|
|
${patches}
|
|
)
|
|
```
|
|
|
|
### SOURCE_BASE
|
|
|
|
Pretty name for the extracted directory.
|
|
|
|
Must not contain path separators (`/` or `\\`).
|
|
|
|
See [`WORKING_DIRECTORY`](#working_directory) for more details.
|
|
|
|
### BASE_DIRECTORY
|
|
|
|
Root subfolder for the extracted directory.
|
|
|
|
Defaults to `src`. Must be a relative path.
|
|
|
|
See [`WORKING_DIRECTORY`](#working_directory) for more details.
|
|
|
|
### WORKING_DIRECTORY
|
|
|
|
Root folder for the extracted directory.
|
|
|
|
Defaults to `${CURRENT_BUILDTREES_DIR}/<BASE_DIRECTORY>`. Must be an absolute path.
|
|
|
|
`vcpkg_extract_source_archive` extracts the archive into `<WORKING_DIRECTORY>/<SOURCE_BASE>-<short-hash>.clean`. If the folder exists, it is deleted before extraction. Without specifying `SOURCE_BASE`, `BASE_DIRECTORY`, or `WORKING_DIRECTORY`, this will default to `${CURRENT_BUILDTREES_DIR}/src/<archive-stem>-<short-hash>.clean`.
|
|
|
|
In [`--editable`](../commands/install.md#editable) mode:
|
|
1. No `.clean` suffix is added to the extracted folder
|
|
2. The extracted folder is not deleted. If it exists, `vcpkg_extract_source_archive` does nothing.
|
|
|
|
`<short-hash>` unambiguously identifies a particular set of archive and patch file contents.
|
|
Any modifications to the contents of the working directory after calling this function should be applied unconditionally
|
|
in order to avoid unexpected behavior in editable mode.
|
|
|
|
## Examples
|
|
|
|
```cmake
|
|
vcpkg_download_distfile(
|
|
archive # "archive" is set to the path to the downloaded file
|
|
URLS "https://nmap.org/dist/nmap-7.70.tar.bz2"
|
|
FILENAME "nmap-7.70.tar.bz2"
|
|
SHA512 084c148b022ff6550e269d976d0077f7932a10e2ef218236fe13aa3a70b4eb6506df03329868fc68cb3ce78e4360b200f5a7a491d3145028fed679ef1c9ecae5
|
|
)
|
|
vcpkg_extract_source_archive(
|
|
src # "src" is set to the path to the extracted files
|
|
ARCHIVE "${archive}"
|
|
SOURCE_BASE nmap.org-nmap-7.70
|
|
PATCHES
|
|
0001-disable-werror.patch
|
|
)
|
|
vcpkg_cmake_configure(SOURCE_PATH "${src}")
|
|
```
|
|
|
|
* [GitHub Search](https://github.com/microsoft/vcpkg/search?q=vcpkg_extract_source_archive+path%3A%2Fports)
|
|
|
|
## Remarks
|
|
|
|
**Deprecated Syntax**
|
|
|
|
This command also supports a deprecated overload:
|
|
|
|
```cmake
|
|
vcpkg_extract_source_archive(<archive> [<working_directory>])
|
|
```
|
|
|
|
The deprecated overload extracts `<archive>` into `${working_directory}/<archive-filename>.extracted` if the target does not exist. This incorrect behavior allows patches and other modifications to leak between different builds, resulting in hard-to-debug errors.
|
|
|
|
All uses of the deprecated overload should be replaced with the syntax in [Usage](#usage) above by adding an explicit [`ARCHIVE`](#archive) parameter and replacing direct references to the extracted path with uses of the [`<out-var>`](#out-var).
|
|
|
|
**Replacement**
|
|
|
|
This command replaces [`vcpkg_extract_source_archive_ex()`](vcpkg_extract_source_archive_ex.md).
|
|
|
|
## Source
|
|
[scripts/cmake/vcpkg\_extract\_source\_archive.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive.cmake)
|