[docs] Split integration.md per Build System. #24737
Conversation
Centralize buildsystem configuration.
ras0219-msft
changed the title
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| When installing libraries, vcpkg creates a single common layout partitioned by triplet. | ||
|
|
||
| The root of the tree in classic mode is `[vcpkg root]/installed`. The root of the tree in manifest mode is `[vcpkg.json directory]/vcpkg_installed`. |
There was a problem hiding this comment.
| The root of the tree in classic mode is `[vcpkg root]/installed`. The root of the tree in manifest mode is `[vcpkg.json directory]/vcpkg_installed`. | |
| The root of the tree in classic mode is `[vcpkg root]/installed/<triplet>`. The root of the tree in manifest mode is `[vcpkg.json directory]/vcpkg_installed/<triplet>`. |
There was a problem hiding this comment.
I intentionally leave the <triplet> off here, because in the Manifest Mode + MSBuild case it actually does double up the triplet: /path/to/project/vcpkg_installed/arm64-windows/x64-windows/tools/<host tools here>. This is because we got feedback from the IDE team that it was critical for MSBuild users to be able to switch platforms (x64 -> Win32 -> ARM64) without needing to reinstall dependencies.
So in vcpkg terminology, header files for a given target are located at [install root]/[target triplet]/include. Do you have a suggestion for how I can reword the sentence above to make this clearer?
There was a problem hiding this comment.
This is because we got feedback from the IDE team that it was critical for MSBuild users to be able to switch platforms (x64 -> Win32 -> ARM64) without needing to reinstall dependencies.
wasn't this fixed by @autoantwort ? I mean VS Code has the same problem if you switch triplets and have defined the same VCPKG_INSTALLED_DIR. Manifest mode should never touch unrelated triplets.
Do you have a suggestion for how I can reword the sentence above to make this clearer?
After rereading the sentence above and below it seems ok. Maybe line 5 and line 7 could have been swapped and slightly rewritten to accommodate the swap.
What really is missing here is a link on how to manipulate the default root.
There was a problem hiding this comment.
Host dependencies & host triplets are what ruin it and require the extra partitioning :(. It's also conceivable that a user could have multiple MSBuild configurations that select different feature sets in the manifest, so different sets of dependencies get installed -- though I just realized that we aren't solving that problem... we may need to change this to $(Platform)/$(Configuration), same as the output directories.
LilyWangLL
added
category:documentation
|
cc @ninjaoflight @x0rld @jnooree and I sync the readme. |
| * Debug `.lib`, `.a`, and `.so` files: `debug/lib/` or `debug/lib/manual-link/` | ||
| * Debug `.dll` files: `debug/bin/` | ||
| * Debug `.pc` files: `debug/lib/pkgconfig/` | ||
| * Tools: `tools/[portname]/` |
There was a problem hiding this comment.
Is this the right place for the missing filesystem layout specification (#17607)? In particular, the diversity in tools (missing [portname]/, extra bin/) can't be fixed until there is an accepted specification.
There was a problem hiding this comment.
I think that a full layout policy document should probably exist separately, but until that separate document exists this is a fine place to put that information.
|
|
||
| The root of the tree in classic mode is `[vcpkg root]/installed`. The root of the tree in manifest mode is `[vcpkg.json directory]/vcpkg_installed`. | ||
|
|
||
| Underneath this root, in a subfolder named after the triplet: |
There was a problem hiding this comment.
Other important folders:
share/[portname]/ for CMake config and copyright.
share/cmake/ for additional CMake config.
There is also another pkgconfg dir for ABI-independent resources.
There was a problem hiding this comment.
There is also another pkgconfg dir for ABI-independent resources.
share/pkgconfig
There was a problem hiding this comment.
share/[portname]/ for CMake config and copyright.
I didn't document this because this particular document is aimed at non-CMake buildsystems (though I suppose meson users might care).
share/cmake/ for additional CMake config.
This is actually against vcpkg policy; it is our intent that all config files (xyz-config.cmake) will exists at share/xyz/xyz-config.cmake.
share/pkgconfig
Are there any current ports you're aware of that take advantage of this? If so, I think we have some bugs in our various helpers that touch pkgconfig.
There was a problem hiding this comment.
This is actually against vcpkg policy; it is our intent that all config files (
xyz-config.cmake) will exists atshare/xyz/xyz-config.cmake.
Where is this specified, explicitly?
For x64-windows, I see app. 370 hits for :/share/cmake/ in CI's file list. Mostly, but not exclusively, Qt5.
In addition, I would strongly prefer /share/cmake/<Package> whenever <Package> is different from <Port>. Which would include all "unofficial" stuff. Or just generally prefer /share/cmake/<Package>, to separate CMake stuff from required data files (GDAL, PROJ).
There was a problem hiding this comment.
share/pkgconfig
Are there any current ports you're aware of that take advantage of this? If so, I think we have some bugs in our various helpers that touch pkgconfig.
This has 8 hits for x64-windows. I didn't check if they are valid or if they should go to lib.
There was a problem hiding this comment.
Are there any current ports you're aware of that take advantage of this?
We had this discussion in microsoft/vcpkg-tool#171 (comment).
Ports which produces a lib go to lib/pkgconfig, otherwise they go to share/pkgconfig
We've gotten feedback that it's confusing to have half of the settings used for a buildsystem in
integration.mdand the other half inmanifests.md. Additionally, it isn't useful to mix multiple buildsystems into a single page, since a user knows up front which buildsystem they're using.This PR splits
users/integration.mdinto a directoryusers/buildsystems/with individual pages for CMake, MSBuild, Manual integration, and the export command. In a future PR that adds reference documentation for the vcpkg command line,exportshould be moved out of this directory and into that reference.