Preparing the PackageMeta File
This file can have two names: "pkgmeta.yaml", or ".pkgmeta". If, for some reason, your repository contains both files, pkgmeta.yaml will take precedence. For the remainder of this article, we will refer to the file as PackageMeta.
Location of the File
The PackageMeta file is a YAML file that goes in the root of your repository project folder. This means /trunk/ for Subversion users and / for Git and Mercurial users. Remember to use spaces instead of tabs for indentation in the file. Your PackageMeta file, if it exists, will be validated when you commit.
Creating the File
On some OSes (Windows for example) there is a bit of difficulty creating this with the name .pkgmeta. To create the file correctly, you will need to use quotations around the file name. A simple mechanism to create this file is to follow these steps:
- Open Notepad or your preferred text editor (not a word processor).
- Make sure you have a blank document by going to the File menu and selecting New.
- Go to the File menu and select Save As.
- Navigate to the directory you want the file to be saved in.
- In the box for the filename to save as type .pkgmeta.
- Save the file.
Alternatively if you have issues with that method you can use the command line prompt to rename a text file.
- In Windows Explorer, create a new text document. You can name it to whatever you want, lets call it foo.txt.
- Go to the Start Menu, then to Run and type in cmd. This will open a command window.
- Navigate to where foo.txt is saved using the cd command (ie: cd c:\My Documents\)
- Type in the following to rename foo.txt to .pkgmeta: move foo.txt ".pkgmeta"
Externals are specified by providing the
externals header and key-value pairs for the local path to the remote repository.
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
In this example, LibMonkey and LibSuit will be packaged with the latest version available, LibStub and CallbackHandler will be packaged with the latest tag available, and LibBanana will be packaged with tag 1.2 always.
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 Subversion, Git, and Mercurial support, the PackageMeta file is an easy way to support all three equally. Also, svn:externals can only refer to other subversion repositories, whereas with the PackageMeta file, 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 your PackageMeta.
move-folders: Monkey/Modules/Suit: Monkey_Suit Monkey/Modules/Hat: Monkey_Hat
For clarity, it is
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
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.
Files beginning with a period, like .pkgmeta and .docmeta, are always ignored by the packager and should not be listed here.
Changing the package name
Instead of using the "Package as" box on your repository, you can specify this in your .pkgmeta file as well.
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
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.
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. Example:
tools-used: - data-tools # same as data-tools/mainline
If you want to make your own changelog manually rather than having one automatically generated for you, that's possible with the following specification:
You can specify any filepath you want. If it cannot be found, the automatic changelog will still be created.
If you want a changelog that is not plain text, use the following format:
manual-changelog: filename: CHANGELOG.txt markup-type: markdown
Supported markup types are: plain, html, and markdown.
If you want your project's license to be automatically included with your zip, you can specify it with license-output.
You can specify any filepath you want.
If your project has libraries, by default two zips will be made, one with libraries (main one) and one without, the -nolib version. You can disable this with the following:
If not specified, it will default to
Why call it PackageMeta?
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
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 license-output: LICENSE.txt tools-used: - data-tools # same as data-tools/mainline