mirror of
https://github.com/microsoft/vcpkg.git
synced 2024-11-24 03:00:19 +08:00
[docs] Update docs for vcpkg_extract_source_archive (#25178)
* [docs] Update docs for vcpkg_extract_source_archive * [docs] Fix links * [docs] CR review * [docs] More CR * CR comments
This commit is contained in:
Robert Schumacher
GitHub
parent
432037ce4f
commit
d4709e69b8
@ -83,6 +83,8 @@ Print the install plan, but do not remove or install any packages.
|
||||
|
||||
The install plan lists all packages and features that will be installed, as well as any other packages that need to be removed and rebuilt.
|
||||
|
||||
<a id="editable"></a>
|
||||
|
||||
### `--editable`
|
||||
|
||||
**Classic Mode Only**
|
||||
|
||||
@ -42,14 +42,15 @@ https://github.blog/2019-02-14-introducing-draft-pull-requests/
|
||||
|
||||
At this time, the following helpers are deprecated:
|
||||
|
||||
1. `vcpkg_extract_source_archive()` should be replaced by [`vcpkg_extract_source_archive_ex()`](vcpkg_extract_source_archive_ex.md)
|
||||
2. `vcpkg_apply_patches()` should be replaced by the `PATCHES` arguments to the "extract" helpers (e.g. [`vcpkg_from_github()`](vcpkg_from_github.md))
|
||||
3. `vcpkg_build_msbuild()` should be replaced by [`vcpkg_install_msbuild()`](vcpkg_install_msbuild.md)
|
||||
4. `vcpkg_copy_tool_dependencies()` should be replaced by [`vcpkg_copy_tools()`](vcpkg_copy_tools.md)
|
||||
5. `vcpkg_configure_cmake` should be replaced by [`vcpkg_cmake_configure()`](ports/vcpkg-cmake/vcpkg_cmake_configure.md#vcpkg_cmake_configure) after removing `PREFER_NINJA` (from port [`vcpkg-cmake`](ports/vcpkg-cmake.md#vcpkg-cmake))
|
||||
6. `vcpkg_build_cmake` should be replaced by [`vcpkg_cmake_build()`](ports/vcpkg-cmake/vcpkg_cmake_build.md#vcpkg_cmake_build) (from port [`vcpkg-cmake`](ports/vcpkg-cmake.md#vcpkg-cmake))
|
||||
7. `vcpkg_install_cmake` should be replaced by [`vcpkg_cmake_install()`](ports/vcpkg-cmake/vcpkg_cmake_install.md#vcpkg_cmake_install) (from port [`vcpkg-cmake`](ports/vcpkg-cmake.md#vcpkg-cmake))
|
||||
8. `vcpkg_fixup_cmake_targets` should be replaced by [`vcpkg_cmake_config_fixup`](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md#vcpkg_cmake_config_fixup) (from port [`vcpkg-cmake-config`](ports/vcpkg-cmake-config.md#vcpkg-cmake-config))
|
||||
- [`vcpkg_extract_source_archive_ex()`](vcpkg_extract_source_archive_ex.md) should be replaced by the supported overload of [`vcpkg_extract_source_archive()`] (with `ARCHIVE`)
|
||||
- The deprecated overload of [`vcpkg_extract_source_archive()`] without `ARCHIVE` should be replaced by the supported overload with `ARCHIVE`.
|
||||
- `vcpkg_apply_patches()` should be replaced by the `PATCHES` arguments to the "extract" helpers (e.g. [`vcpkg_from_github()`](vcpkg_from_github.md))
|
||||
- `vcpkg_build_msbuild()` should be replaced by [`vcpkg_install_msbuild()`](vcpkg_install_msbuild.md)
|
||||
- `vcpkg_copy_tool_dependencies()` should be replaced by [`vcpkg_copy_tools()`](vcpkg_copy_tools.md)
|
||||
- `vcpkg_configure_cmake` should be replaced by [`vcpkg_cmake_configure()`](ports/vcpkg-cmake/vcpkg_cmake_configure.md#vcpkg_cmake_configure) after removing `PREFER_NINJA` (from port [`vcpkg-cmake`](ports/vcpkg-cmake.md#vcpkg-cmake))
|
||||
- `vcpkg_build_cmake` should be replaced by [`vcpkg_cmake_build()`](ports/vcpkg-cmake/vcpkg_cmake_build.md#vcpkg_cmake_build) (from port [`vcpkg-cmake`](ports/vcpkg-cmake.md#vcpkg-cmake))
|
||||
- `vcpkg_install_cmake` should be replaced by [`vcpkg_cmake_install()`](ports/vcpkg-cmake/vcpkg_cmake_install.md#vcpkg_cmake_install) (from port [`vcpkg-cmake`](ports/vcpkg-cmake.md#vcpkg-cmake))
|
||||
- `vcpkg_fixup_cmake_targets` should be replaced by [`vcpkg_cmake_config_fixup`](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md#vcpkg_cmake_config_fixup) (from port [`vcpkg-cmake-config`](ports/vcpkg-cmake-config.md#vcpkg-cmake-config))
|
||||
|
||||
Some of the replacement helper functions are in "tools ports" to allow consumers to pin their
|
||||
behavior at specific versions, to allow locking the behavior of the helpers at a particular
|
||||
@ -66,6 +67,8 @@ version. Tools ports need to be added to your port's `"dependencies"`, like so:
|
||||
}
|
||||
```
|
||||
|
||||
[`vcpkg_extract_source_archive()`]: vcpkg_extract_source_archive.md
|
||||
|
||||
### Avoid excessive comments in portfiles
|
||||
|
||||
Ideally, portfiles should be short, simple, and as declarative as possible.
|
||||
|
||||
@ -2,42 +2,39 @@
|
||||
|
||||
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 into the source directory.
|
||||
Extract an archive.
|
||||
|
||||
## Usage
|
||||
There are two "overloads" of this function. The first is deprecated:
|
||||
|
||||
```cmake
|
||||
vcpkg_extract_source_archive(<${ARCHIVE}> [<${TARGET_DIRECTORY}>])
|
||||
```
|
||||
|
||||
This overload should not be used.
|
||||
|
||||
The latter is suggested to use for all future `vcpkg_extract_source_archive`s.
|
||||
|
||||
```cmake
|
||||
vcpkg_extract_source_archive(<out-var>
|
||||
vcpkg_extract_source_archive(
|
||||
<out-var>
|
||||
ARCHIVE <path>
|
||||
[NO_REMOVE_ONE_LEVEL]
|
||||
[SKIP_PATCH_CHECK]
|
||||
[PATCHES <patch>...]
|
||||
[REF <ref>]
|
||||
[SOURCE_BASE <base>]
|
||||
[BASE_DIRECTORY <relative-path> | WORKING_DIRECTORY <absolute-path>]
|
||||
)
|
||||
```
|
||||
|
||||
`vcpkg_extract_source_archive` takes an archive and extracts it.
|
||||
It replaces existing uses of `vcpkg_extract_source_archive_ex`.
|
||||
The simplest use of it is:
|
||||
## Parameters
|
||||
|
||||
```cmake
|
||||
vcpkg_download_distfile(archive ...)
|
||||
vcpkg_extract_source_archive(source_path ARCHIVE "${archive}")
|
||||
```
|
||||
<a id="out-var"></a>
|
||||
|
||||
The general expectation is that an archives are laid out with a base directory,
|
||||
and all the actual files underneath that directory; in other words, if you
|
||||
extract the archive, you'll get something that looks like:
|
||||
### `<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/
|
||||
@ -52,35 +49,110 @@ zlib-1.2.11/
|
||||
...
|
||||
```
|
||||
|
||||
`vcpkg_extract_source_archive` automatically removes this directory,
|
||||
and gives you the items under it directly. However, this only works
|
||||
when there is exactly one item in the top level of an archive.
|
||||
Otherwise, you'll have to pass the `NO_REMOVE_ONE_LEVEL` argument to
|
||||
prevent `vcpkg_extract_source_archive` from performing this transformation.
|
||||
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.
|
||||
|
||||
If the source needs to be patched in some way, the `PATCHES` argument
|
||||
allows one to do this, just like other `vcpkg_from_*` functions.
|
||||
Additionally, the `SKIP_PATCH_CHECK` is provided for `--head` mode -
|
||||
this allows patches to fail to apply silently.
|
||||
This argument should _only_ be used when installing a `--head` library,
|
||||
since otherwise we want a patch failing to appply to be a hard error.
|
||||
With this flag, the top-level directory will be preserved and it is not an error to not have one.
|
||||
|
||||
`vcpkg_extract_source_archive` extracts the files to
|
||||
`${CURRENT_BUILDTREES_DIR}/<base-directory>/<source-base>-<hash>.clean`.
|
||||
When in editable mode, no `.clean` is appended,
|
||||
to allow for a user to modify the sources.
|
||||
`base-directory` defaults to `src`,
|
||||
and `source-base` defaults to the stem of `<archive>`.
|
||||
You can change these via the `BASE_DIRECTORY` and `SOURCE_BASE` arguments
|
||||
respectively.
|
||||
If you need to extract to a location that is not based in `CURRENT_BUILDTREES_DIR`,
|
||||
you can use the `WORKING_DIRECTORY` argument to do the same.
|
||||
### 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}
|
||||
)
|
||||
```
|
||||
|
||||
### REF
|
||||
|
||||
Pretty name for the extracted directory.
|
||||
|
||||
Forward slashes (`/`) will be replaced with `-`. Otherwise identical to [`SOURCE_BASE`](#source_base).
|
||||
|
||||
See [`WORKING_DIRECTORY`](#working_directory) for more details.
|
||||
|
||||
### 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 `REF`, `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.
|
||||
|
||||
## Examples
|
||||
|
||||
* [libraw](https://github.com/Microsoft/vcpkg/blob/master/ports/libraw/portfile.cmake)
|
||||
* [protobuf](https://github.com/Microsoft/vcpkg/blob/master/ports/protobuf/portfile.cmake)
|
||||
* [msgpack](https://github.com/Microsoft/vcpkg/blob/master/ports/msgpack/portfile.cmake)
|
||||
```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}"
|
||||
REF 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)
|
||||
|
||||
@ -1,24 +1,20 @@
|
||||
# vcpkg_extract_source_archive_ex
|
||||
|
||||
**This function has been deprecated in favor of [`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_ex.md).
|
||||
|
||||
Extract an archive into the source directory.
|
||||
Originally replaced [`vcpkg_extract_source_archive()`],
|
||||
but new ports should instead use the second overload of
|
||||
[`vcpkg_extract_source_archive()`].
|
||||
Extract an archive.
|
||||
|
||||
## Usage
|
||||
```cmake
|
||||
vcpkg_extract_source_archive_ex(
|
||||
[OUT_SOURCE_PATH <source_path>]
|
||||
...
|
||||
[OUT_SOURCE_PATH <out-var>]
|
||||
[<options>...]
|
||||
)
|
||||
```
|
||||
|
||||
See the documentation for [`vcpkg_extract_source_archive()`] for other parameters.
|
||||
Additionally, `vcpkg_extract_source_archive_ex()` adds the `REF` and `WORKING_DIRECTORY`
|
||||
parameters, which are wrappers around `SOURCE_BASE` and `BASE_DIRECTORY`
|
||||
respectively.
|
||||
This command forwards all options to [`vcpkg_extract_source_archive()`], with `<out-var>` as the first argument. Equivalent to `vcpkg_extract_source_archive(<out-var> <options>...)`. See the documentation for [`vcpkg_extract_source_archive()`] for parameter help.
|
||||
|
||||
[`vcpkg_extract_source_archive()`]: vcpkg_extract_source_archive.md
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user