Vcpkg: Document format of CONTROL file

[traversaro]

While the CONTROL file format is quite intuitive, it would be nice to have some documentation on its fields, for example on the difference between Depends and Build-Depends.

[ras0219-msft]

To make a bit of progress here:

The CONTROL file format is a subset of the Debian control format [1]. Only a few of the fields are currently recognized, since we're focusing on the native libraries space. For example, we have no use for Priority, Essential, or Section. Some other fields might want to strongly consider in the future: Homepage, Maintainer, ...

Concretely for Depends versus Build-Depends: they're the same currently except that Depends is used in the (current) binary package format. In the future, I intend to record the exact versions built against in the Depends field to perform better error checking against installing conflicting versions.

[1] https://www.debian.org/doc/debian-policy/ch-controlfields.html

[KindDragon]

What [windows] mean in Build-Depends:? https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/CONTROL

[codicodi]

@KindDragon it means that dependency is needed only for windows (ie. non-uwp) builds.

[traversaro]

Fixed in https://github.com/Microsoft/vcpkg/pull/1111 , in particular by adding the file https://github.com/Microsoft/vcpkg/blob/49cd3995862c0bed0701f84535812e1d0690896f/docs/maintainers/control-files.md .