Skip to content

[vcpkg manifest] Add documentation!#13488

Merged
strega-nil merged 12 commits intomicrosoft:masterfrom
strega-nil:manifest-docs
Sep 14, 2020
Merged

[vcpkg manifest] Add documentation!#13488
strega-nil merged 12 commits intomicrosoft:masterfrom
strega-nil:manifest-docs

Conversation

@strega-nil
Copy link
Contributor

@strega-nil strega-nil commented Sep 11, 2020

This adds documentation for manifest files and for manifest mode. It also converts the existing specification of the supports field to an EBNF, since I think that's easier to read and more exact.

There are two changes made to vcpkg manifests themselves as part of this documentation update:

  • $.features is now additionally allowed to be an object, and x-format-manifest will rewrite to this new object syntax.
  • x-format-manifest is now a non-experimental command

Example:

{
  "features": [
    {
      "name": "foo",
      "description": "bar"
    }
  ]
}

gets rewritten to

{
  "features": {
    "foo": {
      "description": "bar"
    }
  }
}

These are just for the maintainer docs,
not user docs.
this modifies nothing about what strings are accepted or rejected,
it just moves stuff around.

also adds tests.
Copy link
Member

@BillyONeal BillyONeal left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not done reviewing yet; the thing I'm "request changes" over is the documentation of x- commands. In the case of x-set-installed IMO the previous explicit install/remove instructions were better for demonstrating how the tool works. In the case of x-format-manifest or similar, if we want users to use them, we should remove the x-.

@PhoebeHui PhoebeHui added the category:documentation To resolve the issue, documentation will need to be updated label Sep 14, 2020
Copy link
Member

@BillyONeal BillyONeal left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

@strega-nil strega-nil merged commit 0fec134 into microsoft:master Sep 14, 2020
@strega-nil strega-nil deleted the manifest-docs branch September 30, 2020 18:32
strega-nil added a commit to strega-nil/vcpkg that referenced this pull request May 5, 2021
* [vcpkg docs] add docs for manifest files

These are just for the maintainer docs,
not user docs.

* [vcpkg] EBNF-ify platform expression parsing

this modifies nothing about what strings are accepted or rejected,
it just moves stuff around.

also adds tests.

* [vcpkg docs] add manifest mode example

* [wip] docs for augustin

also fix tabs

* [vcpkg manifest] switch to using maps for features

* Apply suggestions from code review

* un-experimentize format-manifest

* flesh out the user manifest mode docs

* CRs

* billy CRs

* final personal pass-thru
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

category:documentation To resolve the issue, documentation will need to be updated

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants