Projects / .pkgmeta file

Location of the file

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 in the file

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

Creating the file

On some OSes (Windows for example) it is a bit more difficult to create this file. In order for you 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" with the quotation marks.
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 up 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"

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

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 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.

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.

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.

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. Example:

tools-used:
    - data-tools # same as data-tools/mainline

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.

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

manual-changelog:
    filename: CHANGELOG.txt
    markup-type: creole

Supported markup types are: creole, plain, bbcode, html, markdown, textile, and wiki (no longer supported, use creole now)

License output

If you want your project's license to be automatically included with your zip, you can specify it with license-output.

license-output: LICENSE.txt

You can specify any filepath you want.

-nolib creation

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:

enable-nolib-creation: no

If not specified, it will default to yes.

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

license-output: LICENSE.txt

tools-used:
    - data-tools # same as data-tools/mainline

You must login to post a comment. Don't have an account? Register to get one!

15 comments
1
2
Next →

- #15
dr4cul4 Thu, 19 Aug 2010 21:06:04
I need a special char at the beginning of package-as.

To be more specific I need #:

package-as: #something
- #14
quantorsht Sun, 06 Sep 2009 10:20:03
I've noticed that my files still say they are 3.0.9 compatible, instead of 3.2.0. I have manually been updating them, but how can I fix it so the default Game Version is 3.2.0?
- #13
Azethoth Tue, 31 Mar 2009 23:03:29
Fix the windows .pkgmeta description to instead have people copy an existing one and then modify it. So much faster and easier that in fact I never knew there was an issue till I read this.
- #12
Ackis Fri, 20 Mar 2009 19:48:39
http://paste.wowace.com/360/

This is a nice big .pkgmeta file for you to use an an example if you wish.
- #11
LokiCoyote Thu, 20 Nov 2008 22:12:15
I know this is an example, but for normal addons, should LibStub be listed as an external?
Could CallbackHandler instead be used to demonstrate linking to "tags"?
- #10
dekimsey Thu, 23 Oct 2008 17:12:56
The file listing shows a "Game Version", how does one specify this? I'm assuming it should have something to do with the .pkgmeta file as the "## Interface: 30200" line in the toc file doesn't seem to be picked up. Ideas?
- #9
kunda Sat, 18 Oct 2008 23:55:15
With my windows version I CAN NOT create a file (via win explorer) that starts with a dot '.'!!!

I DO: In DOS prompt in checked-out /trunk folder: (I use a command line svn version)
- type 'edit .pkgmeta' -> opens an editor (or the DOS one)
- edit it
- Alt will allow you to navigate through edit to save it (if DOS editor)

(A newly created project does not contain a '.pkgmeta'-file. QUOTE: '...you can put a '.pkgmeta' file in to...')
- #8
egingell Tue, 14 Oct 2008 11:28:30
package-as: !<some addon name> doesn't work. It also doesn't work from "Edit Repository"
- #7
Takika Tue, 07 Oct 2008 16:05:14
I Tried to parse two .pkgmeta file with perl YAML module. I got this error:
YAML Error: Stream does not end with newline character.
Is it valid?
EDIT: I tried three perl YAML bindings, and only YAML::Syck can read them.
EDIT2: I tried AckisRecipelist. The .pkgmeta file of this project has no newline at the end. If I add this newline, YAML::Tiny can read it, YAML::Syck can't.
Please, ADD THE NEW LINE TO THE END OF METAFILE.
- #6
Daviesh Thu, 02 Oct 2008 04:46:27
Brimmstone, the .pkgmeta file is only read and run by the packager for generating the zip files. If you want the libraries when you check out, you could do svn externals on your libraries directory grabbing the trunk version of the library. You should set your pkgmeta file to grab tagged versions of the libraries. Remember, the packager ignores svn externals and only reads the pkgmeta file.