WowAce.com Knowledge base

Projects / Packaging an Addon

r4

(Written by MinervahShadowmoon)

Welcome. In this guide, we will explain how to package an addon for the Curse Client. As you read through this guide, you might be surprised to find that there can be more to getting your addon onto Curse.com than you might think. Essentially, you have two options.

The first option is the old-fashioned and simple gathering all the files into a single MyAddon.zip file with your favorite compression client and uploading. This is a very likely solution for you if your addon is very simplistic. That is, if your addon does just one simple function or roughly takes only a hundred lines of code to do what it is designed to do, then you may not need to use all the features CurseForge and/or WoWAce have to offer. If your addon meets these general criteria, feel free to just login, create a project, and upload the file.

The second option is better suited to those addons that are larger and more robust. Their intended users are not specific to Mages, Healers, or Druids, etc. They generally have several hundred to even thousands of lines of code. The second option takes advantage of using detailed revision tracking and packaging.

While this guide is intended to explain how to accomplish the latter of the two options, it should be noted that any addon, big or small, can benefit from the version control systems in place at WoWAce and CurseForge. It is especially important to note that any addon being developed by more than one author will certainly benefit from these features. We will go into more detail as to why in a minute.

What This Guide Is Not

This guide is not for you if you are trying to learn how to write an addon; this is not a “How to write an addon” tutorial. There are other guides written directly written for that purpose at the WowWiki. Also, CurseForge and WoWAce are meant for addons only; any other projects would be better suited at CodePlex, SourceForge, or Google.

Finally, this guide isn’t intended to be “all-inclusive.” While we will try to cover as much as possible in one place, there are other subtopics related to this guide that are important enough that they be given their own article. For example, the “.pkgmeta” file we will be discussing later on is briefly touched on here, but it is a broad enough topic that it be given its own article. You will need to refer to that article once you’re done with this guide.

Why CurseForge or WoWAce?

CurseForge or WoWAce?

We first need to address something that might be a cause of confusion. If it isn’t confusing to you, then it probably is to someone else, and just in case, you should still read this section!

An often asked question on the forums is, “What is the difference between CurseForge and WowAce?” You might be wondering if one is better than the other. Well, the short answer is there isn’t much of a difference and neither is better than the other. Now, that said, here’s the long answer.

CurseForge is the development portal for its big-brother-site, Curse.com. Curse.com is the host of addons for several different games. So, it would stand to reason that CurseForge is the place where developers for all of those games come to do their thing.

So, what the heck is WowAce? Well, WowAce is a developer community for just World of Warcraft addons. In fact, it was initially started with the idea of just Ace2 and Ace3 Library based addons. If you are here to learn how to package an addon, then you probably already know what Ace is; we won’t be going into details. (If you really need an explanation, there are several resources available on the Ace3 project page.) It isn’t uncommon, however, to see discussions about non-Ace addons at WoWAce.

With their backgrounds in mind, we can now compare them. All addons uploaded to both sites will be available to users via the Curse Client. Projects, repositories, tickets, etc., are created, managed, and viewable at both sites. Also, forum posts will be viewable at both websites. (There is one exception, which we will get to in a moment.) This is because both sites use the same server(s) and the same databases. What is viewable on WowAce is very likely to be seen and synced with CurseForge.

There are only a few minor differences. One is obviously the visual design (skin) of the web sites. Another small difference is that the forums’ hierarchies are not exactly the same. Most posts to the forums will be viewable on both web sites, but not always. This really isn’t a factor though—the most knowledgeable developers and main contributors seem to make it a point to browse both forums.

Now that you have all the details of each web site, the question still remains: Which will you use? In all honesty, it is a personal choice. CurseForge is a little heavier on the graphics, so on a slow internet connection, the site might run a little slower for you. If you’re intending on developing for more than just World of Warcraft, then WoWAce might not be the most logical place for you. Just pick one and stick with it. A technical breakdown of the similarities and differences is available here. For the remainder of this guide, we will be referring to both web sites as a whole, since the procedures for releasing and addon are the same. In all references to “CurseForge” below, you should mentally remind yourself that we are speaking of WoWAce as well.

Syndication with Curse Client

As mentioned above, the main reason to use CurseForge is that any addon uploaded to it will be synced with the Curse Client. This makes it very easy for your addon users to get the most up to date version of your addon.

Repository

A repository, by dictionary definition is: “a receptacle or place where things are deposited, stored….” So, applied to your project, this would mean that it is a place where your addon will be stored. What is special about the repository is that it is accessed in a special way that enables special features. (You get the picture: It’s, well….it’s special.)

Any web pages you go to, including this one, are stored on hard drives somewhere in the world. When your browser requests to look at a page, it does so using a special kind of computer language called a protocol. When using CurseForge, your project is the equivalent of a web page, the repository is the equivalent of a hard drive, and the Version Control Software we are going to discuss in a minute is the browser. A repository has to be accessed using a special computer language (a protocol) that regular Internet browsers can’t understand. As a repository “browser”, the Version Control Software keeps track of changes in your project for you.

Version Control Software

Version Control Software (VCS) is a special kind of software that monitors changes to files and folders on your hard drive and then uploads those changes back to a repository. It also keeps a history of these changes. This makes it easier for several people to work on the same project, even the same file, at the same time. VCS came about because of this need. It also backs up your project just before each upload so any time you want to revert to a given version you can do so!

For example, Bob and Sally are working on a research paper together. Bob is tasked with the meat and potatoes of the paper, and Sally is in charge of the bibliography. Outside of a repository, Bob would need to finish writing the content of the paper, save it, and close his document editor before Sally could open the document and start with the bibliography. With VCS, both are able to work on the same file at the same time. That is, while Bob is writing the paper in his dormitory room on campus, Sally could simultaneously work on the bibliography in the Starbucks across town. This is accomplished by “checking out” a copy of the file from the repository, making their changes, and then merging those changes back to the repository. When Bob checked out the word document to start writing the paper, the VCS flagged the live copy in the repository. When Sally arrives at Starbucks and checks out a copy of the live document for herself, the VCS will tell her that Bob has already checked out the file. She can continue to make changes because as far as the repository and the VCS are concerned, both Bob and Sally have the exact same version of the word document—a blank version, or revision 1.

When Bob finishes his part of the paper, he will save those changes back to the repository. This is called committing. When Bob commits the document back to the repository, the VCS will mark the new version as revision 2. A half-hour later, Sally finishes with the bibliography and is ready to commit her version back to the repository. When she does, it will let her know that she no longer has the most recent version (revision) of the document. The VCS will ask her to compare the differences in each version (hers and the new one Bob committed) and give her the option to accept or decline individual changes, overwrite all of Bob’s changes, or abandon her own changes. Obviously, in this case, they would accept/decline individual changes, doing what is called a “merge.” A phone call between Bob and Sally could resolve any individual conflicts.

This is a very basic run-down on how VCS works. You should take some time to learn more about it after this guide. We suggest you read this Wikipedia entry. For those developers writing an addon solo, you will not need to use this feature of VCS, but you still can benefit from the backups that VCS makes. You can always revert to an earlier revision if you do not like the way your project went after a given point. Both solo and collaborative projects benefit from this feature.

Version Control Software and Curse

At CurseForge, you can choose between three repository types. They are Mercurial, Git, and Subversion. Each has their own set of rules and ideologies about how version control should be accomplished, though the main concept we just discussed will remain the same. We have given a bit of technical information about each of them below if you feel compelled to read it. However, it is not mandatory reading because for the purposes of this guide, we will be using Subversion.

Mercurial

Matt Mackall is the creator and lead developer of Mercurial. Mackall first announced Mercurial on April 19, 2005. The impetus for this was the announcement earlier that month by Bitmover that they were withdrawing the free version of BitKeeper. Mercurial was initially written to run on Linux. It has been ported to Windows, Mac OS X, and most other Unix-like systems. Mercurial is primarily a command line program but graphical user interface extensions are available. All of Mercurial's operations are invoked as keyword options to its driver program hg, a reference to the chemical symbol of the element mercury. TortoiseHg provides a user-friendly, right-click menu interface for Windows file manager.

Git

Git is a free distributed revision control, or software source code management project with an emphasis on being fast. Git was initially designed and developed by Linus Torvalds for Linux kernel development for the same reasons Mercurial was developed. Every Git working directory is a full-fledged repository with complete history and full revision tracking capabilities, not dependent on network access or a central server.

Subversion

Subversion (SVN) is a version control system initiated in 1999 by CollabNet Inc. Subversion was started as an effort to write an open source version control system which operated much like CVS but which fixed the bugs and supplied the features missing in CVS. By 2001, Subversion was sufficiently developed to be capable of hosting its own source code. In November 2009, Subversion was accepted into the Apache Incubator, which is the beginning of the process to become a standard top-level Apache project. CollabNet is still involved with Subversion but the project is run as an independent open source community. The home of Subversion is on Tigris.org, an open-source community dedicated to software engineering tools. Subversion is being used on projects such as the Apache Software Foundation, Free Pascal, FreeBSD, GCC, Django, Ruby, Mono, SourceForge.net, ExtJS, Tigris.org, and PHP.

The Subversion open-source community does not provide binaries but these can be downloaded from volunteers and from CollabNet, the initiator of the Subversion project. While the Subversion project does not include an official graphical user interface (GUI) for use with Subversion, a number of different GUIs have been developed, along with a wide variety of additional ancillary software.

Subversion will be our example platform throughout the guide. Once you are comfortable with version control, feel free to check out the other two platforms.

Getting Started

Installing Subversion

The first thing we need to do is install our choice of Subversion clients. There are two main ones we will discuss here—CollabNet and TortiseSVN. Choosing your Client

CollabNet Subversion

Very simply put, CollabNet’s Subversion client is a command-line-only interface and complicated, but for the advanced user, very flexible. That said, since you are here, it is assumed you are not an advanced user and thus, we will not be using this client. It is mentioned here to let you know that in case you cannot get something to work with the client we will be using, you might be able to accomplish it with this one. Just keep it in mind as you become more familiar.

If you would like to go ahead and download it, you may do so here. You will need to register and login to download it. After installation, you should read the 380-plus page manual that comes with it before attempting to use it. The first 100 or so pages give an excellent explanation of Version Control Software.

TortoiseSVN

Aimed at making the use of Subversion a matter of point-and-right-click, TortiseSVN is our choice client for learning to use VCS. Please download the 32-bit or 64-bit version as appropriate and install. Default installation options are fine, but feel free to customize as you see fit. We highly recommend that you read the help files before going any further, and re-reading them again after you complete this tutorial.

The next thing you need to do is modify the configuration file. In its default state, you will get ”EOL-style” errors when trying to commit your files back to the repository.

Step 1: Select Settings -> General.

Step 2: Find the "EDIT" button next to "Subversion configuration file".

Step 3: Near the bottom of the file, there is a line that says

# enable-auto-props = yes

Remove the # in front so that it says

enable-auto-props = yes

Step 4: Remove the # for each file type in the list in the [auto-props] as well. You will probably want to add

*.toc = svn:eol-style=native
*.lua = svn:eol-style=native
*.xml = svn:eol-style=native
*.pkgmeta = svn:eol-style=native

Once you have completed these steps, save the file and stop. Do not go exploring or get curious. Continue reading below.

Setting Up Your Repository

The next step is to set up your repository for your project on CurseForge. In order to do this, you need to have already created a project. If you have not done so, please do so now. If you are not sure how to do this, please read this article. You will need to wait until an administrator approves the project before trying to set up your repository. Generally, this is less than 24 hours.

Step 1: On your project page, you should go to Repository Actions -> Edit Repository.

Step 2: For "Repository Type", select the one you want. In our example, we are using Subversion.

Step 3: In "Package As", put the name of your project's main folder. For World of Warcraft, this will be the same as your addon's .toc file.

Step 4: Wait roughly a minute, and your repository should be created.

Step 5: You have the option of using a simple SVN password or a more secure SSH key. To use simple SVN password, go to the repository authorization section of your profile and setup your SVN password. SSH keys are far more secure, but harder to set up. To use SSH keys, follow the instructions of the article about SSH Public Keys and use the "Development URL" starting with svn+ssh://. For TortoiseSVN, see this article. For the purposes of this article, just use the SVN password for now. You can upgrade to the SSH key method later on when you are more experienced. Also, please note: Your Repository password and your CurseForge password are not the same (at least, initially). The repository is initially set up without a password. You MUST create a password for your repository, and while there is no rule against it, we recommend you do not use the same password.<br>

If you’re at all familiar with the Internet, you know that Websites are accessed using http://, and file transfer servers are accessed using ftp://. Repositories are accessed using a special URL, svn://. To browse a repository, you simply use: svn://svn.curseforge.net/wow/<projectname>/mainline/trunk. This will allow you to browse the repository with your Subversion client anonymously. For example, to browse Ackis’s Recipe List repository, you would type in svn://svn.wowace.com/wow/arl/mainline/trunk. (Notice that his project is hosted on WoWAce; replace “svn.wowace.com” with “svn.curseforge.net” if your project is hosted on CurseForge. Also, if you use Git, you would use git://, or Mercurial, hg://.)

If you were the developer, you could access your repository using the Developer URL, giving you full access to checkout and commit back to it. A Developer URL looks like this: svn://<username>@svn.curseforge.net/wow/<project>/mainline/trunk. There thing that prevents anyone from making changes to your project repository is that password you set up earlier. Whenever you access your repository using the Developer URL, you will be asked for the password.

Creating Your Working Copy Workspace

Now that you have everything set up on CurseForge, you need to setup a place on your hard drive where you will work on your project’s future revisions. You already have your addon on your hard drive, so you already have your working copy. However, Curse doesn’t yet have a copy of your addon. So, we need to create a “blank canvas” on your hard drive for SVN to start watching for changes where you will be writing your addon. When we make a change, it will recognize this and upload it to Curse.

To do this, we must move your addon outside of the Addons directory and then tell SVN to start watching for changes. We then move your addon back into the Addons directory. SVN will see this as a “change” and then allow you to commit those changes to your repository. Your addon will then be available on Curse.

Step 1: Move your project out of your World of Warcraft’s /Addon/ folder. Where you put it, does not matter, so long as you remember where it is. You need to Cut and paste the entire Folder, not just the files in the folder!

Step 2: Let’s say your World of Warcraft is installed at C:\Program Files\World of Warcraft\. Go to C:\Program Files\World of Warcraft\Interface\. Right click on the Addons folder and choose “SVN Checkout…” in the right click menu.

Step 3: You should now be presented with a dialog box. In the box, type the Developer URL for your project. (i.e. svn://<username>@svn.curseforge.net/wow/<project name>/mainline/trunk)

Step 4: For the checkout directory, you should put: C:\Program Files\World of Warcraft\Interface\Addons\<AddonName>. Use the default options and select “OK”.

Step 5: TortoiseSVN will now connect to the SVN repository. It will then prompt you for your password that you setup earlier.

Step 6: If your authentication is successful, TortoiseSVN will checkout the project from CurseForge. Since you don’t have anything uploaded on CurseForge, it won’t download anything. This is just a formality. This is the step that creates your “blank canvas” and tells Subversion to start watching for changes.

Step 7: Now we need to “make changes” so Subversion uploads the files back to Curse. This is done back copying and pasting your project files (not the folder) back to the folder created in your Addons folder by Subversion. (Subversion will create a new folder in the Addons directory with the name you specified earlier in Step 4.) This will register as a change for Subversion. You are now ready to upload.

Step 8: Right click on your addon folder in the /Addons/ directory and select “SVN Commit…”. This will bring up a dialog box where you can put in some comments about the revisions you made, see the files that were changed, etc. You can double click the files in the list to view the exact changes that were made to those files. These changes are called “SVN diffs.” Since the entire file changed in this step, it will be difficult to see how this is helpful, but as you edit your project in the future and you see the SVN diffs in action, it will make more sense. (These are very helpful when comparing two working copies on a collaborative project and you are trying to merge the changes together. It’s even more helpful when you are trying to remember what the heck you were thinking six months ago and helpful to users so they can see why you made changes. It’s mandatory to put something in this box, so you might as well make it descriptive.) When you are ready, click “OK”. TortoiseSVN will upload the files (“changes”) to CurseForge repository.

Step 9: When you go to http://www.curseforge.com/projects/<your_project>, you will notice that a new “Alpha” zip has been created. Don’t go posting to the forums just yet. We’re about to get more in depth about revisions, alphas vs. betas, etc. Pay close attention to the next section. It will mean the difference between being a good addon developer and a fly-by-night addon developer. For the moment, if you see a zip file on your project page, pat yourself on the back.

Committing Changes

Now that you have your first version up on Curse, you can continue to develop your addon with future versions/bug fixes. You should commit back the repository often. On small projects, once a day would be advised. On larger projects or collaborative projects, any time you make changes and walk away from the desk, or every few hours of continuous work. These commits will cause the packager to create a new zip of your project at its current revision.

Behind the Scenes

We’re not quite done yet. There are a few more topics we need to cover. In this section, we will discuss release statuses and tagging commits, the .pkgmeta file, and use of libraries in your addon. Before continuing to read this guide, if you haven’t successfully uploaded a file to your project page by this point, please reread the above sections to see if you missed something and then seek help in the forums if you are still having trouble.

What follows are advanced and technical topics that assume everything up to this point has been completed successfully. You will not benefit from reading the following sections until you have been able to commit your project to the repository.

Release Statuses

When an addon is initially uploaded, the packager tags it as an “Alpha” release. This release will not normally be viewable in the Curse client until tagged as a Beta or Release. Let’s shine a little light on all these Greek terms. It is important to understand these terms so that you can place your addon in the hands of the appropriate users depending on its current position in the development life-cycle. You would not want unstable and untested code being used by a new victim to the World of Warcraft addiction who hardly understands addons to begin with and just expects the game to “work.” Untested addons would be better suited to someone with more experience.

Alpha

The alpha build of an addon is the build released to people different from the author, usually internal to the organization or community that develops the addon. In other words, the author(s) of an addon have decided that what they have it a potentially workable addon, but it needs testing and debugging. The testing is usually done by other authors on CurseForge. Being addon developers, they have knowledge about addon development that a normal user probably doesn't have. In some cases, depending on individual settings inside the Curse client, normal users can have access to your Alpha releases, but they must specifically set up their Curse Client to look for Alpha releases.

In the first phase of testing, developers generally test the software using "white box" techniques. That is, the testers become familiar with how the software operates. They then target specific sections of code and try different input values, knowing what kind of output they should get, and see what happens. If they get the value(s) they were expecting each time different input values are used, the section of code passes the alpha test. If not, they report back to the developer.

Beta

Once alpha testing is complete, Beta testing begins. Beta releases are releases where the testers have no working knowledge of the addon, but are not novices to World of Warcraft. They are usually advanced users with lots of experience with addons, but are not necessarily developers.

A "beta version" is the first version released outside the CurseForge community, for the purpose of evaluation or real-world black-box testing. Black-box testing is when the tester isn't targeting specific sections of code, but the operability of the addon as a whole. Beta testers don't try different input values already knowing what the output should be, as in alpha/white-box testing. Instead, they treat the software as if it should run normally (with the exception of any posted known issues and bugs), and report back any anomalies. This allows for a more wide-spread, sort of random-like, approach to testing. This is often the time when the authors will announce a feature freeze on the addon, indicating that no more features will be added for this version of the addon. Only software issues, or bugs and unimplemented features will be addressed.

There are two types of betas - open and closed. A closed beta is when only a select group of people test the product. Open betas are available to the general public. The Curse client does not automatically install the latest Beta versions; it only does that if instructed to do so (whether by a global setting or individual addon setting override) because the default is only to install Release versions.

Release

A release version is the version of an addon where all testing has been completed, and all known bugs have either been fixed or are deemed unfixable in this version. No new features or major changes will take place, but continued revisions will be made available on current features as necessary to fix bugs. Any new features to be added would begin a new version of the software, and the new would be considered either Pre-Alpha (planning phase) or alpha. A release version is considered stable and can be used by all users, novice and experts.

Tagging Your Addon

When an addon is committed back to the repository and if you do nothing else, the packaging service on CurseForge creates a zip of the addon’s files and considers it (“tags” it) an Alpha version. As we said before, most users will never download that zip file if they’re using the Curse Client and thus, your addon will never be installed. In order to get it installed, you need to tag the zip as a beta or release. Please note: not every commit should be tagged as a beta or release! Referring back to the “Committing Changes” section, commits every day or on larger projects, every couple hours that are synced back with the Curse Client as betas or releases is a bad idea on so many levels. You should only tag your commits as betas during beta testing, and as a release only once per version increment.

We need to address revisions versus versioning. Basically, every time you commit your files to the repository, the revision number is incremented. This is how Subversion keeps track of your project, but isn’t necessarily how you should keep track of your project. Just because you’re at revision 59, doesn’t mean the addon’s version should be “v59.0”. As an example, World of Warcraft’s version at the time of writing is something like v3.22, but on such a big project, you can imagine that Blizzard is using version control software, and their current revision number is in the neighborhood of r25165. (This isn’t fact, it’s just supposition.)

Now that you understand the difference between revisions and versions, whenever you are ready to tag your addon as a new beta or release version, here is the commandment which you should follow:

Quote:

A version string is the name you give your tags when you do a right click -> tag/branch. If this name contains only dots and digits and optionally starts with the letter v (such as "v1.2.3" or "v1.23" or "3.2") or contains the word "release", then it is considered a release tag and a release zip will be created. If the above conditions don't match, it is considered a beta tag and a beta zip will be created. All other commits (that are not tagged) are alphas and alpha zips will be created.

So, simply put, tagging your commits is a simple right-click -> tag/branch on the project folder after committing it to the repository. If your version string contains a “v” or “release”, the packager will tag the zip as a release. Any other text inside the version string creates a beta zip. Untagged commits are packaged as alphas. Follow the above guidelines for the tag, and you you’re well on your way!

The All-Important .pkgmeta File

A couple of times throughout this guide we have referred to a packager on the CurseForge.com website. This packager can be compared to a little gnome that just sits and waits for developers to send him their addons, and he wraps them in some nice store-brand wrapping paper. (Merry Christmas…) Sometimes however, developers won’t want just the generic gift wrap he uses. Sometimes, they want things customized for their addon. This is where the .pkgmeta file comes in.

When a developer wants their addon’s package customized with a pretty red bow, some gold lace, or a nice jingle-bell, they supply the gnome with a .pkgmeta file. It’s the assembly instructions to the gnome for your addon. You use it to tell the packager what external addons your addon uses, where to find a custom change log if you are going to provide one, what files to ignore, etc.

It’s written in YAML format. All that basically means is that it’s extremely picky. You must keep consistent indentation, and use spaces for indenting instead of tabs. A detailed explanation of every keyword available is beyond the scope of this guide. You should refer to this page for a full breakdown. A .pkgmeta file isn’t required, but highly recommended; lack of providing one will tell the packager to just use default options.

Use of Libraries

Does your addon use Ace3, Rock, or any other library for that matter? Are you going to embed the library into your addon? If so, it is very important that you let the packager know this in your .pkgmeta file. You can do this by specifying externals in the .pkgmeta file. When your package is created, it takes the most recent version of the library (or the version you specify) and adds it to your zip file. If you aren’t embedding, make sure to specify the library as an optional dependency.

To Embed or Not To Embed

Not sure whether you should embed your libraries with your addon? Not sure what embedding is? It’s a rather involved discussion, and there are plenty of sources where you can read about the topic and decide for yourself what you will do. See the next section for the list.

External References, Sources Used, and Useful Information

Much of what is in this guide is the culmination of several different sources of information. In some cases, text was taken directly from their sources nearly verbatim. No disrespect is intended towards the authors of said content. In fact, the content was used in such a way because it could not have been said any better. That said, what follows is a list of sources from which this guide was derived. This list is also very helpful for you, the reader, because it contains useful information and, in some cases, information that just wouldn’t fit here but is nonetheless useful. In no certain order…