From 292067a61dccd6a7aa322dfc5a88b52997faaaf2 Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Fri, 20 May 2022 14:42:35 -0700 Subject: [PATCH] [docs] Fix broken links and generate documentation for `vcpkg-gn` (#24764) * [docs] Fix broken links. Add docs validation pipeline. * [docs][regenerate.ps1] Do not require a README.md in helper ports * [docs] Update validateDocs.yml to point to current main --- .github/workflows/validateDocs.yml | 54 +++++++++++++++++++ docs/README.md | 5 -- docs/about/faq.md | 4 +- docs/maintainers/portfile-functions.md | 5 ++ docs/maintainers/ports/vcpkg-gn.md | 12 +++++ .../ports/vcpkg-gn/vcpkg_gn_configure.md | 32 +++++++++++ .../ports/vcpkg-gn/vcpkg_gn_install.md | 29 ++++++++++ docs/maintainers/pr-review-checklist.md | 4 +- docs/regenerate.ps1 | 5 +- docs/users/buildsystems/integration.md | 4 +- .../users/buildsystems/msbuild-integration.md | 3 +- docs/users/config-environment.md | 8 +-- docs/users/manifests.md | 1 + docs/users/mingw.md | 10 ++-- docs/users/triplets.md | 3 +- docs/users/versioning.md | 1 - 16 files changed, 156 insertions(+), 24 deletions(-) create mode 100644 .github/workflows/validateDocs.yml create mode 100644 docs/maintainers/ports/vcpkg-gn.md create mode 100644 docs/maintainers/ports/vcpkg-gn/vcpkg_gn_configure.md create mode 100644 docs/maintainers/ports/vcpkg-gn/vcpkg_gn_install.md diff --git a/.github/workflows/validateDocs.yml b/.github/workflows/validateDocs.yml new file mode 100644 index 00000000000000..aabdb97b08ae48 --- /dev/null +++ b/.github/workflows/validateDocs.yml @@ -0,0 +1,54 @@ +name: Doc Validation + +on: + pull_request: + paths: + - 'docs/**' + +jobs: + validate: + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + path: vcpkg + + - name: Checkout Website + uses: actions/checkout@v3 + with: + repository: vcpkg/vcpkg.github.io + ref: '8ee5cacc91b6e017b5e4236940d9f385c1563598' + path: vcpkg.github.io + + - uses: actions/cache@v3 + with: + path: ~/.npm + key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} + restore-keys: | + ${{ runner.os }}-node- + + - run: npm ci + working-directory: vcpkg.github.io + + - name: Purge existing html files + run: rm -rf en + working-directory: vcpkg.github.io + + # The current navbar embeds a link to integration.md which no longer exists + - name: Ignore navbar + run: echo "" > templates/navbar.html + working-directory: vcpkg.github.io + + - name: Generate Core Pages + run: node scripts/generatePages.js + working-directory: vcpkg.github.io + + - name: Generate Docs Pages + run: node scripts/generateDocs.js ../vcpkg/docs + working-directory: vcpkg.github.io + + - name: Check Links + run: VCPKG_VALIDATE_LINKS_ONLY_DOCS=1 node scripts/validateLinks.js + working-directory: vcpkg.github.io diff --git a/docs/README.md b/docs/README.md index eb3b90cd9a27f7..f0114efa4ec19f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -50,11 +50,6 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too - [vcpkgx](https://vcpkgx.com/) - Package index + search - [vcpkg index](https://vcpkg.dev/) - Package index + search -### Specifications - -- [Export](specifications/export-command.md) -- [Feature Packages](specifications/feature-packages.md) - ### Blog posts - [Vcpkg Host Dependencies for Cross-Compilation](https://devblogs.microsoft.com/cppblog/vcpkg-host-dependencies/) diff --git a/docs/about/faq.md b/docs/about/faq.md index bc9d0cf29f49af..d2ff600b22805c 100644 --- a/docs/about/faq.md +++ b/docs/about/faq.md @@ -6,7 +6,7 @@ If you want to contribute but don't have a particular library in mind then take of [new port requests](https://github.com/Microsoft/vcpkg/issues?q=is%3Aissue+is%3Aopen+label%3Acategory%3Anew-port). ## Can Vcpkg create pre-built binary packages? What is the binary format used by Vcpkg? -Yes! See [the `export` command](../users/buildsystems/integration.md#export-command). +Yes! See the [`export` command](../users/buildsystems/export-command.md). ## How do I update libraries? The `vcpkg update` command lists all packages which are out-of-sync with your current portfiles. To update a package, follow the instructions in the command. @@ -88,7 +88,7 @@ Vcpkg uses CMake internally as a build scripting language. This is because CMake ## Will Vcpkg support downloading compiled binaries from a public or private server? We would like to eventually support downloading precompiled binaries, similar to other system package managers. -In a corporate scenario, we currently recommend building the libraries once and distributing the entire vcpkg root directory to everyone else on the project through some raw file transport such as a network share or HTTP host. See the [`export`](../users/buildsystems/integration.md#export) command. +In a corporate scenario, we currently recommend building the libraries once and distributing the entire vcpkg root directory to everyone else on the project through some raw file transport such as a network share or HTTP host. See the [`export` command](../users/buildsystems/export-command.md). ## What Visual C++ toolsets are supported? We support Visual Studio 2015 Update 3 and above. diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md index b2b8a49ba6bb21..515c8b511af853 100644 --- a/docs/maintainers/portfile-functions.md +++ b/docs/maintainers/portfile-functions.md @@ -74,6 +74,11 @@ - [vcpkg\_cmake\_configure](ports/vcpkg-cmake/vcpkg_cmake_configure.md) - [vcpkg\_cmake\_install](ports/vcpkg-cmake/vcpkg_cmake_install.md) +### [vcpkg-gn](ports/vcpkg-gn.md) + +- [vcpkg\_gn\_configure](ports/vcpkg-gn/vcpkg_gn_configure.md) +- [vcpkg\_gn\_install](ports/vcpkg-gn/vcpkg_gn_install.md) + ### [vcpkg-cmake-config](ports/vcpkg-cmake-config.md) - [vcpkg\_cmake\_config\_fixup](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md) diff --git a/docs/maintainers/ports/vcpkg-gn.md b/docs/maintainers/ports/vcpkg-gn.md new file mode 100644 index 00000000000000..c7ac13a05fe8f1 --- /dev/null +++ b/docs/maintainers/ports/vcpkg-gn.md @@ -0,0 +1,12 @@ +# vcpkg-cmake + +This port contains cmake functions for dealing with a GN buildsystem. + +## Example + +```cmake +vcpkg_gn_configure( + SOURCE_PATH "${SOURCE_PATH}" +) +vcpkg_gn_install() +``` diff --git a/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_configure.md b/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_configure.md new file mode 100644 index 00000000000000..da9326a810375e --- /dev/null +++ b/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_configure.md @@ -0,0 +1,32 @@ +# vcpkg_gn_configure + +The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_configure.md). + +Generate Ninja (GN) targets + +## Usage: +```cmake +vcpkg_gn_configure( + SOURCE_PATH + [OPTIONS ] + [OPTIONS_DEBUG ] + [OPTIONS_RELEASE ] +) +``` + +## Parameters: +### SOURCE_PATH (required) +The path to the GN project. + +### OPTIONS +Options to be passed to both the debug and release targets. +Note: Must be provided as a space-separated string. + +### OPTIONS_DEBUG (space-separated string) +Options to be passed to the debug target. + +### OPTIONS_RELEASE (space-separated string) +Options to be passed to the release target. + +## Source +[ports/vcpkg-gn/vcpkg\_gn\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-gn/vcpkg_gn_configure.cmake) diff --git a/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_install.md b/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_install.md new file mode 100644 index 00000000000000..e520fcc96aba56 --- /dev/null +++ b/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_install.md @@ -0,0 +1,29 @@ +# vcpkg_gn_install + +The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_install.md). + +Installs a GN project. + +In order to build a GN project without installing, use [`vcpkg_build_ninja()`]. + +## Usage: +```cmake +vcpkg_gn_install( + SOURCE_PATH + [TARGETS ...] +) +``` + +## Parameters: +### SOURCE_PATH +The path to the source directory + +### TARGETS +Only install the specified targets. + +Note: includes must be handled separately + +[`vcpkg_build_ninja()`]: vcpkg_build_ninja.md + +## Source +[ports/vcpkg-gn/vcpkg\_gn\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-gn/vcpkg_gn_install.cmake) diff --git a/docs/maintainers/pr-review-checklist.md b/docs/maintainers/pr-review-checklist.md index ce8d1c3a9998c0..05baaa58edd682 100644 --- a/docs/maintainers/pr-review-checklist.md +++ b/docs/maintainers/pr-review-checklist.md @@ -13,7 +13,7 @@ You can link any of these checklist items in a GitHub comment by copying the lin
c000001: No deprecated helper functions are used -See our [Maintainer Guidelines and Policies](maintainer-guide.md#Avoid-deprecated-helper-functions) for more information. +See our [Maintainer Guidelines and Policies](maintainer-guide.md#avoid-deprecated-helper-functions) for more information.
@@ -36,7 +36,7 @@ See our [manifest file documentation](manifest-files.md#description) for more in
c000004: No unnecessary comments are present in the changeset -See our [Maintainer Guidelines and Policies](maintainer-guide.md#Avoid-excessive-comments-in-portfiles) for more information. +See our [Maintainer Guidelines and Policies](maintainer-guide.md#avoid-excessive-comments-in-portfiles) for more information.
diff --git a/docs/regenerate.ps1 b/docs/regenerate.ps1 index d3c9e241245934..a319e19b147a22 100755 --- a/docs/regenerate.ps1 +++ b/docs/regenerate.ps1 @@ -27,6 +27,7 @@ class CMakeDocumentation { [String[]]$cmakeScriptsPorts = @( 'vcpkg-cmake' + 'vcpkg-gn' 'vcpkg-cmake-config' 'vcpkg-cmake-get-vars' 'vcpkg-pkgconfig-get-modules' @@ -265,7 +266,9 @@ Get-ChildItem "$VcpkgRoot/scripts/cmake" -Filter '*.cmake' | ForEach-Object { $cmakeScriptsPorts | ForEach-Object { $portName = $_ - Copy-Item "$VcpkgRoot/ports/$portName/README.md" "$PSScriptRoot/maintainers/ports/$portName.md" + if (Test-Path "$VcpkgRoot/ports/$portName/README.md") { + Copy-Item "$VcpkgRoot/ports/$portName/README.md" "$PSScriptRoot/maintainers/ports/$portName.md" + } New-Item -Path "$PSScriptRoot/maintainers/ports/$portName" -Force -ItemType 'Directory' | Out-Null $portTableOfContents[$portName] = @() diff --git a/docs/users/buildsystems/integration.md b/docs/users/buildsystems/integration.md index 4c2ace80b4a5af..67706600f1e65a 100644 --- a/docs/users/buildsystems/integration.md +++ b/docs/users/buildsystems/integration.md @@ -6,5 +6,5 @@ vcpkg supports use from any buildsystem and has specific native integration into - [MSBuild Integration (Visual Studio)](msbuild-integration.md) - [CMake Integration](cmake-integration.md) -- [Manual Integration](#manual-integration) -- [`export` Command](#export-command) +- [Manual Integration](manual-integration.md) +- [`export` Command](export-command.md) diff --git a/docs/users/buildsystems/msbuild-integration.md b/docs/users/buildsystems/msbuild-integration.md index e9dbf12275c84e..3cd698c7667d15 100644 --- a/docs/users/buildsystems/msbuild-integration.md +++ b/docs/users/buildsystems/msbuild-integration.md @@ -10,7 +10,6 @@ - [Linked NuGet Package](#linked-nuget-package) - [Common Configuration](#common-configuration) - [Manifest Mode Configuration](#manifest-mode-configuration) -- [Classic Mode Configuration](#classic-mode-configuration) ## Integration Methods @@ -60,7 +59,7 @@ More information about `Directory.Build.targets` and `Directory.Build.props` can ### Linked NuGet Package -**Note: This approach is not recommended for new projects, since it makes them difficult to share with others. For a portable, self-contained NuGet package, see the [`export command`](#export-command)** +**Note: This approach is not recommended for new projects, since it makes them difficult to share with others. For a portable, self-contained NuGet package, see the [`export command`](export-command.md)** VS projects can also be integrated through a NuGet package. This will modify the project file, so we do not recommend this approach for open source projects. diff --git a/docs/users/config-environment.md b/docs/users/config-environment.md index 1f872c94663a2e..3fca13efe1c801 100644 --- a/docs/users/config-environment.md +++ b/docs/users/config-environment.md @@ -75,19 +75,19 @@ This environment variables limits the amount of concurrency requested by underly #### VCPKG_DEFAULT_BINARY_CACHE -This environment variable redirects the default location to store binary packages. See [Binary Caching](binarycaching.md#Configuration) for more details. +This environment variable redirects the default location to store binary packages. See [Binary Caching](binarycaching.md#configuration) for more details. #### VCPKG_BINARY_SOURCES -This environment variable adds or removes binary sources. See [Binary Caching](binarycaching.md#Configuration) for more details. +This environment variable adds or removes binary sources. See [Binary Caching](binarycaching.md#configuration) for more details. #### VCPKG_NUGET_REPOSITORY -This environment variable changes the metadata of produced NuGet packages. See [Binary Caching](binarycaching.md#Configuration) for more details. +This environment variable changes the metadata of produced NuGet packages. See [Binary Caching](binarycaching.md#configuration) for more details. #### VCPKG_USE_NUGET_CACHE -This environment variable allows using NuGet's cache for every nuget-based binary source. See [Binary Caching](binarycaching.md#NuGets-cache) for more details. +This environment variable allows using NuGet's cache for every nuget-based binary source. See [Binary Caching](binarycaching.md#nuget-provider-configuration) for more details. #### X_VCPKG_ASSET_SOURCES diff --git a/docs/users/manifests.md b/docs/users/manifests.md index bb0e28025368d7..001c73cc658898 100644 --- a/docs/users/manifests.md +++ b/docs/users/manifests.md @@ -159,6 +159,7 @@ Then, you might just ask for: } ``` + #### `"platform"` Field The `"platform"` field defines the platforms where the dependency should be installed - for example, diff --git a/docs/users/mingw.md b/docs/users/mingw.md index d07328b15a76d7..2a0408f76b8716 100644 --- a/docs/users/mingw.md +++ b/docs/users/mingw.md @@ -6,10 +6,10 @@ ## Table of Contents - - [Mingw-w64 community triplets](#Mingw-w64-community-triplets) - - [Using Mingw-w64 natively on Windows](#Using-Mingw-w64-natively-on-Windows) - - [How to avoid mixing different installations](#How-to-avoid-mixing-different-installations) - - [Using Mingw-w64 to build Windows programs on other systems](#Using-Mingw-w64-to-build-Windows-programs-on-other-systems) + - [Mingw-w64 community triplets](#mingw-w64-community-triplets) + - [Using Mingw-w64 natively on Windows](#mingw-native) + - [How to avoid mixing different installations](#how-to-avoid-mixing-different-installations) + - [Using Mingw-w64 to build Windows programs on other systems](#mingw-cross) ## Mingw-w64 community triplets @@ -36,6 +36,7 @@ Because of this, community involvement is paramount! - [Open issues](https://github.com/microsoft/vcpkg/issues?q=is%3Aissue+is%3Aopen+mingw) - [Open pull requests](https://github.com/microsoft/vcpkg/pulls?q=is%3Apr+is%3Aopen+mingw) + ## Using Mingw-w64 natively on Windows With [MSYS2](https://www.msys2.org/), it is possible to easily create @@ -123,6 +124,7 @@ which create a mix of MSYS2 programs from different installations. You may want to set the desired `PATH` manually, or remove directories which contain `sh.exe`, `bash.exe`, `msys-2.0.dll` or `cygwin1.dll`. + ## Using Mingw-w64 to build Windows programs on other systems You can use the vcpkg mingw community triplets with toolchains on diff --git a/docs/users/triplets.md b/docs/users/triplets.md index 909fcce76c8814..9f9cca4d1ef90a 100644 --- a/docs/users/triplets.md +++ b/docs/users/triplets.md @@ -8,7 +8,7 @@ In Vcpkg, we use triplets to describe an imaginary "target configuration set" fo We currently provide many triplets by default (run `vcpkg help triplet`). However, you can easily customize or add your own by copying a built-in triplet from the `triplets\` directory into a project local location. Then, use `--overlay-triplets=` (or equivalent such as [`$VCPKG_OVERLAY_TRIPLETS`](config-environment.md#vcpkg_overlay_triplets), [CMake `VCPKG_OVERLAY_TRIPLETS`](buildsystems/cmake-integration.md#vcpkg_overlay_triplets), or [MSBuild Additional Options](buildsystems/msbuild-integration.md#vcpkg-additional-install-options)) to add that directory to vcpkg. See our [overlay triplets example](../examples/overlay-triplets-linux-dynamic.md) for a more detailed walkthrough. -To change the triplet used by your project away from the default, see our [Integration Document](buildsystems/integration.md#triplet-selection). +To change the triplet used by your project, you can pass `--triplet=` on the command line or see our [Buildsystem-Specific Documentation](buildsystems/integration.md). ## Community triplets @@ -65,6 +65,7 @@ This field is optional and, if present, will be passed into the build as `CMAKE_ See also the CMake documentation for `CMAKE_SYSTEM_VERSION`: https://cmake.org/cmake/help/latest/variable/CMAKE_SYSTEM_VERSION.html. + ### VCPKG_CHAINLOAD_TOOLCHAIN_FILE Specifies an alternate CMake Toolchain file to use. diff --git a/docs/users/versioning.md b/docs/users/versioning.md index 7b091a8a8f62b1..e4befb2eb05861 100644 --- a/docs/users/versioning.md +++ b/docs/users/versioning.md @@ -15,7 +15,6 @@ See our guide to [getting started with versioning](../examples/versioning.gettin * [`version-date`](#version-date) * [`version-string`](#version-string) * [Version constraints](#version-constraints) -* [Version files](#version-files) ## Version schemes Ports in vcpkg should attempt to follow the versioning conventions used by the package's authors. For that reason, when declaring a package's version the appropriate scheme should be used.