Re: Clarify META docs
2 views
Skip to first unread message
David E. Wheeler
Jan 4, 2016, 1:34:31 PM1/4/16
to Jim Nasby, pgxn-...@googlegroups.com
CC’ing pgxn-users, since it might be of more general interest.
On Dec 26, 2015, at 5:25 PM, Jim Nasby <Jim....@BlueTreble.com> wrote:
> http://pgxn.org/spec/#Terminology
> Is it required for a distribution to build all its extensions? Can it skip building if certain dependencies aren't met?
Unspecified. So no. PGXN only requires that you describe the contents of a release, not how it’s built or what you end up with. That’s on whatever build process the distribution sues (PGXS usually).
> http://pgxn.org/spec/#provides
> file: Extensions can contain multiple files, so it'd be helpful to know exactly how this field is used. I'm guessing this is the file clients are supposed to look for to see if the extension is installed in a cluster?
Unspecified. PGXN itself doesn’t do anything with this key. It probably ought to have been omitted from the spec; it’s there because I copied the CPAN Meta spec, where a single module usually corresponds to a single file. The same is often not the case for PGXN extensions.
> doc: Similar to file... how exactly is this field supposed to be used? What if there are multiple doc files for an extension?
The docfile key *is* used by the API indexer. It should specify the main documentation file for the extension. If you have multiple documentation files for a single extension, point to whichever is the main one (e.g., the first one, a TOC, etc.). The API indexer uses this key to point to the main doc file for an extension. If the key is missing, it tires to find a doc file with the same name (excluding file suffix) as the extension.
Best,
David
On Dec 26, 2015, at 5:25 PM, Jim Nasby <Jim....@BlueTreble.com> wrote:
> http://pgxn.org/spec/#Terminology
> Is it required for a distribution to build all its extensions? Can it skip building if certain dependencies aren't met?
Unspecified. So no. PGXN only requires that you describe the contents of a release, not how it’s built or what you end up with. That’s on whatever build process the distribution sues (PGXS usually).
> http://pgxn.org/spec/#provides
> file: Extensions can contain multiple files, so it'd be helpful to know exactly how this field is used. I'm guessing this is the file clients are supposed to look for to see if the extension is installed in a cluster?
Unspecified. PGXN itself doesn’t do anything with this key. It probably ought to have been omitted from the spec; it’s there because I copied the CPAN Meta spec, where a single module usually corresponds to a single file. The same is often not the case for PGXN extensions.
> doc: Similar to file... how exactly is this field supposed to be used? What if there are multiple doc files for an extension?
The docfile key *is* used by the API indexer. It should specify the main documentation file for the extension. If you have multiple documentation files for a single extension, point to whichever is the main one (e.g., the first one, a TOC, etc.). The API indexer uses this key to point to the main doc file for an extension. If the key is missing, it tires to find a doc file with the same name (excluding file suffix) as the extension.
Best,
David
Reply all
Reply to author
Forward
0 new messages