Preparing the PackageMeta File

The PackageMeta file

The PackageMeta file is a YAML file named .pkgmeta that goes in the root of your project directory. This file is used to configure the packager for your addon.

In Windows it is a bit difficult to create a "dot file", but if you add a period at the end of the file name, it will keep the leading period and drop the ending one. For example, typing .pkgmeta. as the name after creating a new file will save the file as ".pkgmeta".

Please note, the YAML spec disallows tabs so make sure you use spaces for indentation or the packager will not parse your .pkgmeta file correctly.

Including external libraries

External libraries, or just "externals", are specified by providing the externals header and key-value pairs for the local path to the remote repository.

externals:
  Libs/LibStub:
    url: https://repos.wowace.com/wow/libstub/trunk
    tag: 1.0
  Libs/CallbackHandler-1.0:
    url: https://repos.wowace.com/wow/callbackhandler/trunk/CallbackHandler-1.0
    tag: latest
  Libs/LibMonkey-1.0: https://repos.curseforge.net/wow/libmonkey-1-0/trunk
  Libs/LibBanana-1.0:
    url: https://github.com/monkehdude/LibBanana-1.0.git
    curse-slug: libbanana-1-0
  Libs/LibSuit-2.0:
    url: https://repos.curseforge.net/wow/libsuit-2-0
    type: hg

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

In this example, LibMonkey, LibBanana and LibSuit will be packaged with the latest version available, CallbackHandler will be packaged with the latest tag available, and LibStub will be packaged with tag 1.0 always.

For Git and Mercurial repositories, you can use a tag, branch, or commit directive to specify what is checked out. Subversion repositories only support tag, but you can use any valid repo path as the url if you set the type to svn.

The packager will try to guess the repository type from the url, but you can define it using the type directive. Subversion (svn), Git (git), and Mercurial (hg) repositories are supported.

The packager will also try to automatically associate the external with it's CurseForge project from the url. If the external is on CurseForge, but uses a third-party repository, you can use curse-slug to associate the CurseForge project manually. You can also add the slug using the embedded-libraries header instead if you would rather use the "directory: url" short form.

If a .pkgmeta file exists for the external, the packager will parse it for ignored files to exclude from the package.

Moving folders around

You can move folders by using the move-folders header and key-value pairs for the source and destination directory. For example, you can use this to package multiple module addons that load on demand.

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

Note the package name is included as the root directory of the source folder. This example will move the folders Modules/Suit and Modules/Hat in your project directory to the root of the package as Monkey_Suit and Monkey_Hat. If the Modules directory is empty after moving a directory, it will be deleted and not included in the package.

Ignoring files or folders

To make the packager ignore files, you can use the ignore header with a list of file paths or globs.

ignore:
  - Scripts            # ignore the scripts folder
  - Modules/Debug.lua  # ignore a specific file
  - "*.txt"              # ignore multiple files with a pattern

The path should be the working copy path and is not affected by move-folders. You can also specify paths that an external will add to ignore unwanted files that the external includes.

Files beginning with a period, like .pkgmeta and .docmeta, are always ignored by the packager and do not need to be listed here.

Changing the package name

The packager will set the addon directory name and package name based on the file name of your TOC file. If you want to use another name, you can specify this with the package-as directive.

package-as: Monkey

This example will make is so the root directory of the package zip file is Monkey as well as use Monkey-version as the package file name.

Specifying dependencies

To specify dependencies that will show on the CurseForge website and the Twitch App, you can use the required-dependencies and optional-dependencies headers with a list of project short names (slugs). This will not add any files to the package.

required-dependencies:
  - monkey-town

optional-dependencies:
  - monkey-city

You can also specify libraries that are committed to the repo (hard embed) or externals using a third-party repo for a CurseForge project using the embedded-libraries header. This will make sure they receive points for it in the Author Rewards Program.

embedded-libraries:
  - libbongo-1-0

Say you are using LibBongo-1.0, which is available on CurseForge, but always want it available to the addon regardless of if you make a nolib package or not. With embedded-libraries you can commit the library to your repo and still list it as an embedded library.

Tools used

If you want to specify that you used a tool that is not a library, but would like people to know that it was used, and for it to receive points for the Author Rewards Program, you can do so with the tools-used header.

tools-used:
  - data-tools

Manual Changelog

If you want to make your own changelog manually rather than having one automatically generated for you, that is possible using the manual-changelog header.

manual-changelog: CHANGELOG.txt

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

If you want a changelog that is not plain text, you can use the following format:

manual-changelog:
  filename: CHANGELOG.md
  markup-type: markdown

Supported markup types are: plain, html, and markdown.

Creating a nolib package

If your project has libraries, you can also create a second package zip file that does not include any libraries added using the externals header, called a nolib package. This is disabled by default and nolib packages and will never be uploaded to CurseForge. If you publish GitHub releases, the nolib package will be attached to the release.

enable-nolib-creation: yes

Full Example

package-as: Monkey

externals:
  Libs/LibStub:
    url: https://repos.wowace.com/wow/libstub/trunk
    tag: 1.0
  Libs/CallbackHandler-1.0:
    url: https://repos.wowace.com/wow/callbackhandler/trunk/CallbackHandler-1.0
    tag: latest
  Libs/LibMonkey-1.0: https://repos.curseforge.net/wow/libmonkey-1-0/trunk
  Libs/LibBanana-1.0:
    url: https://github.com/monkehdude/LibBanana-1.0.git
    curse-slug: libbanana-1-0
  Libs/LibSuit-2.0:
    url: https://repos.curseforge.net/wow/libsuit-2-0
    type: hg

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

ignore:
  - Scripts
  - Modules/Debug.lua
  - "*.txt"

required-dependencies:
  - monkey-town

optional-dependencies:
  - monkey-city

embedded-libraries:
  - libbongo-1-0

tools-used:
  - data-tools

manual-changelog:
  filename: CHANGELOG.md
  markup-type: markdown