WowAce.com Knowledge base

Projects / .pkgmeta file

r9

For your repositories, you can put a '.pkgmeta' file in to provide extra information. Yes, that is a dot followed by 'pkgmeta'.

.pkgmeta is a YAML file that goes in the root of your repository project folder. This means /trunk/.pkgmeta for SVN users and /.pkgmeta for Git and Hg users.

Remember to use spaces instead of tabs for indentation

Your .pkgmeta file, if it exists, will be validated when you commit.

Specifying externals

Externals are specified by providing the externals header and key-value pairs for the local path to the remote repository.

Example:

externals:
    libs/LibStub:
        url: svn://svn.wowace.com/wow/libstub/mainline/trunk
        tag: latest
    libs/CallbackHandler-1.0:
        url: svn://svn.wowace.com/wow/callbackhandler/mainline/trunk/CallbackHandler-1.0
        tag: latest
    libs/LibMonkey-1.0: svn://svn.curseforge.net/wow/libmonkey-1-0/mainline/trunk
    libs/LibBanana-1.0: 
        url: git://git.curseforge.net/wow/libbanana-1-0/mainline.git
        tag: 1.2
    libs/LibSuit-2.0:
        url: http://hg.curseforge.net/wow/libsuit-2-0/mainline

You do not need to have an empty libs folder for the above example to work, it will be created for you.

Unlike svn:externals, you can specify any repository type, be it svn, git, or hg.

Note: Your remote paths will be validated to check if they exist when you commit. This may cause you to wait a few moments.

Why not just use svn:externals?

The main reason to not use svn:externals is that since curseforge provides SVN, Git, and Hg support, .pkgmeta is an easy way to support all three equally. Also, svn:externals can only refer to other subversion repositories, whereas with .pkgmeta, there is nothing stopping you from referencing repositories of unlike types.

Moving folders around with the packager

There is a way to move folders by specifying in .pkgmeta. This is useful if you want to essentially have two addons in one game, particularly if one is a module of the other, e.g. Monkey and Monkey_Suit. Suit is inside the Monkey project, but can move out and be its own addon with .pkgmeta.

Example:

move-folders:
    Monkey/Modules/Suit: Monkey_Suit
    Monkey/Modules/Hat: Monkey_Hat

For clarity, it is Source: Destination.

As you can see, unlike other portions, you have to specify your addon's name, as this allows you to create modules.

Ignoring folders or files

To make the packager ignore files, you can easily do so by making an ignore header with filepaths underneath

Example:

ignore:
    - Scripts # ignore the scripts folder
    - Some/File.txt # ignore a specific file

It is to be assumed that this takes place before moving folders around with the move-folders header.

Changing the package name

Instead of using the "Package as" box on your repository, you can specify this in your .pkgmeta file as well.

Example:

package-as: Monkey

Specifying dependencies

To specify dependencies that will show on the site and also through the Curse Client, you can do so with the required-dependencies and optional-dependencies headers

Example:

required-dependencies:
    - monkey-town # same as monkey-town/mainline

optional-dependencies:
    - monkey-city

This will not add anything to any files in your zip.

The list consists of the short names of projects or project/repository combos.

Manual changelog

If you want to make your own changelog manually rather than having one automatically generated for you, that's possible with the following specification:

manual-changelog: CHANGELOG.txt

You can specify any filepath you want. If it cannot be found, the automatic changelog will still be created.

Why call it .pkgmeta?

It's a nice, neutral name. We didn't want something curseforge-specific, in case anyone else decides to implement it.

Also, since we don't want to limit it to just external definitions, we went for something more generic than .externals

Full Example

package-as: Monkey

externals:
    libs/LibStub:
        url: svn://svn.wowace.com/wow/libstub/mainline/trunk
        tag: latest
    libs/CallbackHandler-1.0:
        url: svn://svn.wowace.com/wow/callbackhandler/mainline/trunk/CallbackHandler-1.0
        tag: latest
    libs/LibMonkey-1.0: svn://svn.curseforge.net/wow/libmonkey-1-0/mainline/trunk
    libs/LibBanana-1.0: 
        url: git://git.curseforge.net/wow/libbanana-1-0/mainline.git
        tag: 1.2
    libs/LibSuit-2.0:
        url: http://hg.curseforge.net/wow/libsuit-2-0/mainline

move-folders:
    Monkey/Modules/Suit: Monkey_Suit
    Monkey/Modules/Hat: Monkey_Hat

ignore:
    - Scripts # ignore the scripts folder
    - Some/File.txt # ignore a specific file

required-dependencies:
    - monkey-town

optional-dependencies:
    - monkey-city

manual-changelog: CHANGELOG.txt