mirror of https://github.com/microsoft/vcpkg.git
[docs] link to new functions in deprecated warnings (#17179)
* [docs] link to new functions in deprecated warnings * [docs] add deprecation messages to portfile-functions.md * [docs] also update documentation in .cmake files * [docs] introduce new directive DEPRECATED BY in the documentation generation script and use that directive * Trigger Build * Trigger Build * Trigger Build
This commit is contained in:
autoantwort
GitHub
parent
cf2ea00e82
commit
f44d4c169f
|
|
@ -5,7 +5,7 @@
|
|||
- [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md)
|
||||
- [vcpkg\_add\_to\_path](vcpkg_add_to_path.md)
|
||||
- [vcpkg\_apply\_patches](vcpkg_apply_patches.md) (deprecated)
|
||||
- [vcpkg\_build\_cmake](vcpkg_build_cmake.md)
|
||||
- [vcpkg\_build\_cmake](vcpkg_build_cmake.md) (deprecated, use [vcpkg\_cmake\_build](ports/vcpkg-cmake/vcpkg_cmake_build.md))
|
||||
- [vcpkg\_build\_gn](vcpkg_build_gn.md)
|
||||
- [vcpkg\_build\_make](vcpkg_build_make.md)
|
||||
- [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md)
|
||||
|
|
@ -18,7 +18,7 @@
|
|||
- [vcpkg\_clean\_executables\_in\_bin](vcpkg_clean_executables_in_bin.md)
|
||||
- [vcpkg\_clean\_msbuild](vcpkg_clean_msbuild.md)
|
||||
- [vcpkg\_common\_definitions](vcpkg_common_definitions.md)
|
||||
- [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md)
|
||||
- [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md) (deprecated, use [vcpkg\_cmake\_configure](ports/vcpkg-cmake/vcpkg_cmake_configure.md))
|
||||
- [vcpkg\_configure\_gn](vcpkg_configure_gn.md)
|
||||
- [vcpkg\_configure\_make](vcpkg_configure_make.md)
|
||||
- [vcpkg\_configure\_meson](vcpkg_configure_meson.md)
|
||||
|
|
@ -36,7 +36,7 @@
|
|||
- [vcpkg\_fail\_port\_install](vcpkg_fail_port_install.md)
|
||||
- [vcpkg\_find\_acquire\_program](vcpkg_find_acquire_program.md)
|
||||
- [vcpkg\_find\_fortran](vcpkg_find_fortran.md)
|
||||
- [vcpkg\_fixup\_cmake\_targets](vcpkg_fixup_cmake_targets.md)
|
||||
- [vcpkg\_fixup\_cmake\_targets](vcpkg_fixup_cmake_targets.md) (deprecated, use [vcpkg\_cmake\_config\_fixup](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md))
|
||||
- [vcpkg\_fixup\_pkgconfig](vcpkg_fixup_pkgconfig.md)
|
||||
- [vcpkg\_from\_bitbucket](vcpkg_from_bitbucket.md)
|
||||
- [vcpkg\_from\_git](vcpkg_from_git.md)
|
||||
|
|
@ -45,7 +45,7 @@
|
|||
- [vcpkg\_from\_sourceforge](vcpkg_from_sourceforge.md)
|
||||
- [vcpkg\_get\_program\_files\_platform\_bitness](vcpkg_get_program_files_platform_bitness.md)
|
||||
- [vcpkg\_get\_windows\_sdk](vcpkg_get_windows_sdk.md)
|
||||
- [vcpkg\_install\_cmake](vcpkg_install_cmake.md)
|
||||
- [vcpkg\_install\_cmake](vcpkg_install_cmake.md) (deprecated, use [vcpkg\_cmake\_install](ports/vcpkg-cmake/vcpkg_cmake_install.md))
|
||||
- [vcpkg\_install\_gn](vcpkg_install_gn.md)
|
||||
- [vcpkg\_install\_make](vcpkg_install_make.md)
|
||||
- [vcpkg\_install\_meson](vcpkg_install_meson.md)
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# vcpkg_apply_patches
|
||||
|
||||
**This function has been deprecated in favor of the `PATCHES` argument to `vcpkg_from_github()` et al.**
|
||||
**This function has been deprecated in favor of the `PATCHES` argument to [`vcpkg_from_github()`](vcpkg_from_github.md) et al.**
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_apply_patches.md).
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
# vcpkg_build_cmake
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_cmake.md).
|
||||
**This function has been deprecated in favor of [`vcpkg_cmake_build`](ports/vcpkg-cmake/vcpkg_cmake_build.md) from the vcpkg-cmake port.**
|
||||
|
||||
**This function has been deprecated in favor of `vcpkg_cmake_build` from the vcpkg-cmake port.**
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_cmake.md).
|
||||
|
||||
Build a cmake project.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
# vcpkg_configure_cmake
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_cmake.md).
|
||||
**This function has been deprecated in favor of [`vcpkg_cmake_configure`](ports/vcpkg-cmake/vcpkg_cmake_configure.md) from the vcpkg-cmake port.**
|
||||
|
||||
**This function has been deprecated in favor of `vcpkg_cmake_configure` from the vcpkg-cmake port.**
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_cmake.md).
|
||||
|
||||
Configure CMake for Debug and Release builds of a project.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
# vcpkg_fixup_cmake_targets
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_fixup_cmake_targets.md).
|
||||
**This function has been deprecated in favor of [`vcpkg_cmake_config_fixup`](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md) from the vcpkg-cmake-config port.**
|
||||
|
||||
**This function has been deprecated in favor of `vcpkg_cmake_config_fixup` from the vcpkg-cmake-config port.**
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_fixup_cmake_targets.md).
|
||||
|
||||
Merge release and debug CMake targets and configs to support multiconfig generators.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
# vcpkg_install_cmake
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_cmake.md).
|
||||
**This function has been deprecated in favor of [`vcpkg_cmake_install`](ports/vcpkg-cmake/vcpkg_cmake_install.md) from the vcpkg-cmake port.**
|
||||
|
||||
**This function has been deprecated in favor of `vcpkg_cmake_install` from the vcpkg-cmake port.**
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_cmake.md).
|
||||
|
||||
Build and install a cmake project.
|
||||
|
||||
|
|
|
|||
|
|
@ -20,6 +20,8 @@ class CMakeDocumentation {
|
|||
[String[]]$ActualDocumentation
|
||||
[Bool]$IsDeprecated
|
||||
[String]$DeprecationMessage
|
||||
[String]$DeprecatedByName
|
||||
[String]$DeprecatedByPath
|
||||
[Bool]$HasError
|
||||
}
|
||||
|
||||
|
|
@ -111,9 +113,19 @@ function FinalDocFile
|
|||
$documentation += $Docs.ActualDocumentation[0] # name line
|
||||
if ($Docs.IsDeprecated)
|
||||
{
|
||||
if ($null -eq $Docs.DeprecationMessage)
|
||||
if ($null -eq $Docs.DeprecationMessage -or $Docs.DeprecationMessage -match '^ *$')
|
||||
{
|
||||
$documentation += @("", "**This function has been deprecated**")
|
||||
if(![string]::IsNullOrEmpty($Docs.DeprecatedByName))
|
||||
{
|
||||
$message = " in favor of [``$($Docs.DeprecatedByName)``]($($Docs.DeprecatedByPath)$($Docs.DeprecatedByName).md)"
|
||||
$Docs.DeprecatedByPath -match '^ports/([a-z\-]+)/$' | Out-Null
|
||||
$port = $matches[1]
|
||||
if(![string]::IsNullOrEmpty($port))
|
||||
{
|
||||
$message += " from the $port port."
|
||||
}
|
||||
}
|
||||
$documentation += @("", "**This function has been deprecated$message**")
|
||||
}
|
||||
else
|
||||
{
|
||||
|
|
@ -153,10 +165,12 @@ function ParseCmakeDocComment
|
|||
{
|
||||
$Docs.IsDeprecated = $True
|
||||
}
|
||||
elseif($contents[0] -match '^# DEPRECATED: (.*)$')
|
||||
elseif($contents[0] -match '^# DEPRECATED( BY (([^/]+/)+)(.+))?((: *)(.*))?$')
|
||||
{
|
||||
$Docs.IsDeprecated = $True
|
||||
$Docs.DeprecationMessage = $matches[1]
|
||||
$Docs.DeprecatedByPath = $matches[2]
|
||||
$Docs.DeprecatedByName = $matches[4]
|
||||
$Docs.DeprecationMessage = $matches[7]
|
||||
}
|
||||
|
||||
[String]$startCommentRegex = '#\[(=*)\['
|
||||
|
|
@ -292,29 +306,32 @@ $portfileFunctionsContent = @(
|
|||
'',
|
||||
'# Portfile helper functions')
|
||||
|
||||
function GetDeprecationMessage
|
||||
{
|
||||
Param(
|
||||
[CMakeDocumentation]$Doc
|
||||
)
|
||||
if ($Doc.IsDeprecated)
|
||||
{
|
||||
$message = " (deprecated"
|
||||
if(![string]::IsNullOrEmpty($Doc.DeprecatedByName))
|
||||
{
|
||||
$message += ", use [$($($Doc.DeprecatedByName) -replace '_','\_')]($($Doc.DeprecatedByPath)$($Doc.DeprecatedByName).md)"
|
||||
}
|
||||
$message += ")"
|
||||
}
|
||||
$message
|
||||
}
|
||||
|
||||
$DocsName = @{ expression = { Split-Path -LeafBase $_.Filename } }
|
||||
$tableOfContents | Sort-Object -Property $DocsName -Culture '' | ForEach-Object {
|
||||
$name = Split-Path -LeafBase $_.Filename
|
||||
if ($_.IsDeprecated)
|
||||
{
|
||||
$portfileFunctionsContent += "- [$($name -replace '_','\_')]($name.md) (deprecated)"
|
||||
}
|
||||
else
|
||||
{
|
||||
$portfileFunctionsContent += "- [$($name -replace '_','\_')]($name.md)"
|
||||
}
|
||||
$portfileFunctionsContent += "- [$($name -replace '_','\_')]($name.md)" + $(GetDeprecationMessage $_)
|
||||
}
|
||||
$portfileFunctionsContent += @("", "## Internal Functions", "")
|
||||
$internalTableOfContents | Sort-Object -Property $DocsName -Culture '' | ForEach-Object {
|
||||
$name = Split-Path -LeafBase $_.Filename
|
||||
if ($_.IsDeprecated)
|
||||
{
|
||||
$portfileFunctionsContent += "- [$($name -replace '_','\_')](internal/$name.md) (deprecated)"
|
||||
}
|
||||
else
|
||||
{
|
||||
$portfileFunctionsContent += "- [$($name -replace '_','\_')](internal/$name.md)"
|
||||
}
|
||||
$portfileFunctionsContent += "- [$($name -replace '_','\_')](internal/$name.md)" + $(GetDeprecationMessage $_)
|
||||
}
|
||||
|
||||
$portfileFunctionsContent += @("", "## Scripts from Ports")
|
||||
|
|
@ -324,14 +341,7 @@ $portTableOfContents.GetEnumerator() | ForEach-Object {
|
|||
$portfileFunctionsContent += @("", "### [$portName](ports/$portName.md)", "")
|
||||
$cmakeDocs | ForEach-Object {
|
||||
$name = Split-Path -LeafBase $_.Filename
|
||||
if ($_.IsDeprecated)
|
||||
{
|
||||
$portfileFunctionsContent += "- [$($name -replace '_','\_')](ports/$portName/$name.md) (deprecated)"
|
||||
}
|
||||
else
|
||||
{
|
||||
$portfileFunctionsContent += "- [$($name -replace '_','\_')](ports/$portName/$name.md)"
|
||||
}
|
||||
$portfileFunctionsContent += "- [$($name -replace '_','\_')](ports/$portName/$name.md)" + $(GetDeprecationMessage $_)
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# DEPRECATED: in favor of the `PATCHES` argument to `vcpkg_from_github()` et al.
|
||||
# DEPRECATED: in favor of the `PATCHES` argument to [`vcpkg_from_github()`](vcpkg_from_github.md) et al.
|
||||
|
||||
#[===[.md
|
||||
# vcpkg_apply_patches
|
||||
|
|
|
|||
|
|
@ -1,8 +1,7 @@
|
|||
# DEPRECATED BY ports/vcpkg-cmake/vcpkg_cmake_build
|
||||
#[===[.md:
|
||||
# vcpkg_build_cmake
|
||||
|
||||
**This function has been deprecated in favor of `vcpkg_cmake_build` from the vcpkg-cmake port.**
|
||||
|
||||
Build a cmake project.
|
||||
|
||||
## Usage:
|
||||
|
|
|
|||
|
|
@ -1,8 +1,7 @@
|
|||
# DEPRECATED BY ports/vcpkg-cmake/vcpkg_cmake_configure
|
||||
#[===[.md:
|
||||
# vcpkg_configure_cmake
|
||||
|
||||
**This function has been deprecated in favor of `vcpkg_cmake_configure` from the vcpkg-cmake port.**
|
||||
|
||||
Configure CMake for Debug and Release builds of a project.
|
||||
|
||||
## Usage
|
||||
|
|
|
|||
|
|
@ -1,8 +1,7 @@
|
|||
# DEPRECATED BY ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup
|
||||
#[===[.md:
|
||||
# vcpkg_fixup_cmake_targets
|
||||
|
||||
**This function has been deprecated in favor of `vcpkg_cmake_config_fixup` from the vcpkg-cmake-config port.**
|
||||
|
||||
Merge release and debug CMake targets and configs to support multiconfig generators.
|
||||
|
||||
Additionally corrects common issues with targets, such as absolute paths and incorrectly placed binaries.
|
||||
|
|
|
|||
|
|
@ -1,8 +1,7 @@
|
|||
# DEPRECATED BY ports/vcpkg-cmake/vcpkg_cmake_install
|
||||
#[===[.md:
|
||||
# vcpkg_install_cmake
|
||||
|
||||
**This function has been deprecated in favor of `vcpkg_cmake_install` from the vcpkg-cmake port.**
|
||||
|
||||
Build and install a cmake project.
|
||||
|
||||
## Usage:
|
||||
|
|
|
|||
Loading…
Reference in New Issue