Vcpkg: Document vcpkg installation and possible variants

[mloskot]

The installation process is only briefely explained in the docs as git clone, bootstrap-vcpkg.bat and, optionally, vcpkg integrate install.

This is fine for default setup, but there is more details that really need to be covered in the documentation.

Some of obvious questions"

1. Shall I copy vcpkg.exe anywhere?
2. Can I copy vcpkg.exe anywhere (eg. c:\bin\vcpkg.exe which I have in PATH) or it has to stick to location where it was bootstrapped?
3. Can I control location where vcpkg.exe downloads/installs packages in?
4. What is the {vcpkg}\buildtrees directory for?
5. What is the {vcpkg}\installed directory for?
6. What is the {vcpkg}\downloads directory for?
7. What is the {vcpkg}\packages directory for?
8. What is the relation between the working copy where vcpkg.exe was bootstrapped and location where packages are installed?
9. Having C:\vcpkg-1\vcpkg.exe and C:\vcpkg-2\vcpkg.exe, do I maintain two sets of packages (two installation prefixes, in Unix speak)
10. Do such multiple working copies affect the user-wide integration?
11. Does use of such multiple working copies require use of the CMake toolchain file only?
12. Having the multiple working copies, can I mix integration modes? For example
    
    
    
    • C:\vcpkg-1\vcpkg.exe is user-wide integrated
    
    
    • C:\vcpkg-2\vcpkg.exe is used via the CMake toolchain file only
    
    

So far, user has to fish for (correct?) answers in the issues archive and compile the information from scraps, hoping the bigger picture generated is correct.

For example, https://github.com/Microsoft/vcpkg/issues/1681#issuecomment-324160402 suggests to clone a second copy...

References

3044

3052

[ras0219-msft]

Thanks for the questions!

First, to directly answer them:

1. Shall I copy vcpkg.exe anywhere?
   _No_
2. Can I copy vcpkg.exe anywhere (eg. c:\bin\vcpkg.exe which I have in PATH) or it has to stick to location where it was bootstrapped?
   _It needs to stay where it was bootstrapped, however you can add the root of the vcpkg folder to your path._
3. Can I control location where vcpkg.exe downloads/installs packages in?
   _You can use symlinks to redirect the downloads/installed folder, however the overall structure is fixed_
4. What is the {vcpkg}\buildtrees directory for?
   _Extracted sources and intermediate files_
5. What is the {vcpkg}\installed directory for?
   _Installed files; these are documented in https://github.com/Microsoft/vcpkg/blob/be0e6434371d200f0ebec3543f73436817cf1e3f/docs/users/integration.md#manual-compiler-settings_
6. What is the {vcpkg}\downloads directory for?
   _Caching downloads :)_
7. What is the {vcpkg}\packages directory for?
   _This is an internal staging folder. We have explicitly not documented this folder because it is likely to change in the future._
8. What is the relation between the working copy where vcpkg.exe was bootstrapped and location where packages are installed?
   _The tool follows a series of steps to determine the correct root to install into[1]: Command line argument, then environment variable (both documented in vcpkg help), then current working directory, then current executable directory. In both of the directory cases, we search up for the .vcpkg-root stamp file (like git) to determine the true root._
9. Having C:\vcpkg-1\vcpkg.exe and C:\vcpkg-2\vcpkg.exe, do I maintain two sets of packages (two installation prefixes, in Unix speak)
   _Yes, vcpkg is entirely self contained, save the obviously-not-contained "User-wide integration" :)_
10. Do such multiple working copies affect the user-wide integration?
    _No_
11. Does use of such multiple working copies require use of the CMake toolchain file only?
    _All options in https://github.com/Microsoft/vcpkg/blob/be0e6434371d200f0ebec3543f73436817cf1e3f/docs/users/integration.md work besides the "User-Wide for MSBuild" -- this include CMake toolchain, linking NuGet package, and manual integration. There's also the export command which can be used to produce standalone archives of binaries that can be individually integrated._
12. Having the multiple working copies, can I mix integration modes? For example
    
    
    
    • C:\vcpkg-1\vcpkg.exe is user-wide integrated
    
    
    • C:\vcpkg-2\vcpkg.exe is used via the CMake toolchain file only
      
      _Yes_
    
    

[1] https://github.com/Microsoft/vcpkg/blob/be0e6434371d200f0ebec3543f73436817cf1e3f/toolsrc/src/vcpkg.cpp#L70-L95

[mloskot]

@ras0219-msft This is excellent, thank you!

I think this could be copied verbatim into new "Installation" section in the FAQ :)