I built this simple sample addon to help me understand how to get off the ground using AceConfig and AceDB to let me setup configuration options and save them and get them into the standard interface/addon options screen.
I wanted to share in case others were struggling as well. I found the getting started guide difficult to grok at times with my limited knowledge of the interactions and patterns of the framework.
There's no point in listing your libraries in an "embeds.xml" file. That convention came into being to accommodate the original WowAce site backend and updater program, neither of which exist today, and which needed such a file to detect which libraries it should package/install (or not, for "nolib" users) with an addon. In the modern addon ecosystem, the Curse packager gets that information from your addon's ".pkgmeta" file, and the Curse addon updater doesn't use that information at all (the packager already made a separate nolib package, so it just downloads that for nolib users). All an "embeds.xml" file is doing for you today is adding another disk read to your addon's loading time. Just list your libraries directly in your TOC file.
If you were to use .pkgmeta in the future, you would want to surround the addon file listings in your TOC with @nolib-strip@ and @end-nolib-strip@ lines so the packager knows which lines to remove when it's making a package without embedded libraries. (You'd also want to remove the actual library files from your repository in that case, and let the packager automatically grab up-to-date copies each time it made a package.)
You should avoid using color codes in your TOC's Title field. They break the standard sorting methods (eg. in the addon list on the character selection screen, and in the in-game addon manager) and it greatly reduces readability when your addon list becomes a rainbow of clashing random colors.
Some other observations about your Git repository, not your addon:
- Your .gitattributes file doesn't include anything relevant to the files in your repo, so you should delete it.
- Your .gitignore file doesn't include anything relevant either, and non-project-specific ignores like OS metadata files are better specified in a global .gitignore file so they apply to all Git repos on your computer, and you don't have to copy and paste the same rules/file into every repo you ever create.
There's no point in listing your libraries in an "embeds.xml" file. That convention came into being to accommodate the original WowAce site backend and updater program, neither of which exist today, and which needed such a file to detect which libraries it should package/install (or not, for "nolib" users) with an addon.
That depends on whether you are hard-embedding libraries or not. Generally you want to reference the xml file, if available. As you see from LibStub, it has no xml file.
Nothing wrong with hard-embedding, but the method has been known to occasionally cause issues with older versions of a library overwriting a newer version. I haven't seen that happen in quite some time, but it is possible. Hard-embedding usually is for libraries themselves, as they hard-embed LibStub and, if needed, CallbackHandler-1.0. Full AddOns do not need hard-embeds (see stripping below).
Note that Ace3 components have a specific load order; see the Ace3.toc to see what the order is, as I can't remember all of them.
Also, you can "strip out" libraries, with the one exception being LibDataBroker-1.1. Here is the link for all the repository keyword substitutions.
Generally you want to reference the xml file, if available.
No. For the same reason you should skip using embeds.xml (it adds an unnecessary disk read) you should just reference the library's Lua file directly, unless its XML file does something other than referencing the Lua file. The whole "let's have an XML stub" paradigm started because someone thought it would be more convenient if addons could always just call "lib.xml" for any library and it would be okay if the library added more files later, but in reality (a) libraries don't add more files and (b) not everyone named their useless XML stub "lib.xml" anyway.
The only library I've ever seen where I'd recommend referencing the XML file is AceGUI, because listing all 20 Lua files for AceGUI in your TOC is annoying.
Nothing wrong with hard-embedding, but the method has been known to occasionally cause issues with older versions of a library overwriting a newer version.
This can't happen with LibStub libraries (ie. pretty much all of them) unless the library's author screwed up the library's internal version numbering.
Basically the hard-embedding debate comes down to this:
If you're using the Curse packager (or a third-party packager that supports .pkgmeta), don't hard-embed libraries.
Otherwise, you have to hard-embed libraries, but don't forget to update them when a new version of the library is released.
Also, you can "strip out" libraries, with the one exception being LibDataBroker-1.1. Here is the link for all the repository keyword substitutions.
However, you can (and should) @no-lib-strip@ LibDataBroker-1.1 if you also use LibDBIcon-1.0, because the standalone version of LibDBIcon-1.0 already includes LibDataBroker-1.1.
I wanted to share in case others were struggling as well. I found the getting started guide difficult to grok at times with my limited knowledge of the interactions and patterns of the framework.
Available @ https://github.com/ChrisNolan/TestAddonAceConfig
If you have a moment to let me know if I've gotten anything wrong feedback would be welcome.
If you were to use .pkgmeta in the future, you would want to surround the addon file listings in your TOC with @nolib-strip@ and @end-nolib-strip@ lines so the packager knows which lines to remove when it's making a package without embedded libraries. (You'd also want to remove the actual library files from your repository in that case, and let the packager automatically grab up-to-date copies each time it made a package.)
You should avoid using color codes in your TOC's Title field. They break the standard sorting methods (eg. in the addon list on the character selection screen, and in the in-game addon manager) and it greatly reduces readability when your addon list becomes a rainbow of clashing random colors.
Some other observations about your Git repository, not your addon:
- Your .gitattributes file doesn't include anything relevant to the files in your repo, so you should delete it.
- Your .gitignore file doesn't include anything relevant either, and non-project-specific ignores like OS metadata files are better specified in a global .gitignore file so they apply to all Git repos on your computer, and you don't have to copy and paste the same rules/file into every repo you ever create.
I know this hasnt been updated since 2010 but https://www.wowace.com/addons/ace3/pages/getting-started/ talks about using the embeds.xml still.
Does this mean we can just link to the .lua file in our .toc file so that the above becomes
Or do we still link to the xml file
Nothing wrong with hard-embedding, but the method has been known to occasionally cause issues with older versions of a library overwriting a newer version. I haven't seen that happen in quite some time, but it is possible. Hard-embedding usually is for libraries themselves, as they hard-embed LibStub and, if needed, CallbackHandler-1.0. Full AddOns do not need hard-embeds (see stripping below).
Note that Ace3 components have a specific load order; see the Ace3.toc to see what the order is, as I can't remember all of them.
Also, you can "strip out" libraries, with the one exception being LibDataBroker-1.1. Here is the link for all the repository keyword substitutions.
No. For the same reason you should skip using embeds.xml (it adds an unnecessary disk read) you should just reference the library's Lua file directly, unless its XML file does something other than referencing the Lua file. The whole "let's have an XML stub" paradigm started because someone thought it would be more convenient if addons could always just call "lib.xml" for any library and it would be okay if the library added more files later, but in reality (a) libraries don't add more files and (b) not everyone named their useless XML stub "lib.xml" anyway.
The only library I've ever seen where I'd recommend referencing the XML file is AceGUI, because listing all 20 Lua files for AceGUI in your TOC is annoying.
This can't happen with LibStub libraries (ie. pretty much all of them) unless the library's author screwed up the library's internal version numbering.
Basically the hard-embedding debate comes down to this:
However, you can (and should) @no-lib-strip@ LibDataBroker-1.1 if you also use LibDBIcon-1.0, because the standalone version of LibDBIcon-1.0 already includes LibDataBroker-1.1.