how to make an addon, install.xml

Is there any written info on the protocol of making an addon? I’m particularly confused about the install.xml. I’ve looked at some of the addons that already have the file but it isn’t much clearer I’m afraid. Is this actually used somehow? How does the #ifdef in the <addons_h> go in addons.h? and all the entries for ,, do we have to enter these one by one? how are they used? Also for the do we put a machine-readable name or human-readable? sorry for the bombardment of questions… just couldn’t find any docs on the matter. cheers :stuck_out_tongue:

there is not sadly a finished document about this, but there is info here:…-addons+xml

which explains the rational. Most addons are just additional source code (which is easy) and you can model what you make on the dir list one, for example. When the addons includes other includes and libraries and dlls it gets more tricky. Part of the xml is to provide a list of what you need per platform / compiler, so for some addons, like Osc / opencv this can be a bit more involved. With the requires, our hope was that you can write in by hand what your addon requires (like ofxVectorMath, etc).

the other hope with the xml was to use it to generate instructions or html / docs, etc.

for now the xml is just read by humans, but some folks have already started scripting this (arturo has made some great progress on linux). And our hope is that more scripts are written so that adding opencv to a project is just as easy as point and click…

hope that helps!


ah ok, thanks Zach. Just out of curiosity, what was the reason for having an ofAddons.h & define-for-each-addon system, and not just include a header file from the addon directly? We could dictate that by convention, all addons must have a single header file with the same name as the folder which includes all other header files required for the addon (e.g. ofxOpenCV/src/ofxOpenCv.h, ofxVectorMath/src/ofxVectorMath.h - I think most addons already comply with this). So if a user wants to install a new addon they don’t need to worry about editing ofAddons.h and remembering what define to put in their source. They can just include the ‘.h’ directly in their source which has the same name as the addon folder…

the idea was that with addons.h, you could hypothetically do some error checking too, like

       #error "you need to include vector math to use memos cool proj"  
   #include "../../../addons/ofxMemo"  

since we are not doing it now it doesn’t make that much difference, but with more complicated dependencies, it’d be useful to do some error checking in one central place.

hope that helps explain the thinking…

take care!

I’ve just been explicitly including ofAddons and specifying what else I need just before (e.g., ofxVector). Are you thinking it’d be better the other way because you’d see in the testApp what exactly is being included, rather than having to hunt down which addon you’re missing?

sorry, is that question for me? what do you mean?

the idea behind using addons.h is that is keeps the code similar per platform and allows us to do any special checking on depencies as we include. otherwise, the include process is more haphazzard and it might not be obvious that what is included is really an addon, or which addon it is. (esp. if the main “.h” file is named poorly).

you can feel free to use it however you want, but for us (who have to spend alot of time debugging code and getting people setup) it’s alot cleaner to have all addons put in one place with a conditional include.

  • z

i’m siding with zach on this because it took me a couple days to see the beauty of this method. ultimately it allows you to reference to addons as whole modules using the #idndef and #define system. I use it for dependency checking in ofxPhysics where I check for ofTypes (it doesn’t get compiled in the right order sometimes) and ofxVectorMath so my engine doesn’t produce crashes that look to be code related. If you use addons just as files then you really can’t check if they have been included since that would mean additional code for checking, even possibly modifying whole libraries just for checking and dependencies. stick to #define and #ifndef and everything will “just work” which is one of the primary goals of oF: rapid, easy prototyping out of the box.

Yeah, sorry – I was kind of vague. I’m really just reiterating Memo’s question about why one approach is used instead of another.

Approach #1 (classic of addon approach): In your ofSimpleApp you include ofAddons.h and a #define for each addon you want to include. When an addon needs to itself use other addons, this is checked for in ofAddons.h

Approach #2 (streamlined approach/memo’s idea/what I’ve been doing): In your ofSimpleApp you directly include your addon (e.g.: #include “ofxKyle.h”). If your addon itself uses other addons, this is specified in your addon (e.g., in “ofxKyle.h”).

I prefer the streamlined approach – to install an addon you just have to copy the folder to /addons, and don’t need to modify ofAddons.h. Also, if you want to use an addon, you just have to #include the addon in your ofSimpleApp instead of #defining that it’s needed, and then finding out you also need to #define some other needed addons.

Hopefully that wasn’t unnecessarily detailed :slight_smile:

I am not trying to be rude here so sorry if it comes out that way. I believe the original question from memo is what is the protocol of making an addon. zach answered how the oF method works and why and then said that you are welcomed to do it in what ever way makes you happy. I dont think zach is going to change the way this works in oF so that is solid. But everyone else can do what they want. Just trying to reiterate the subject matter. :smiley:

Carry on.

the #define method is fine, its not a major hassle and I can see some benefits - especially when scripting gets involved. But I think we’d all agree that its the addon developers responsibility to include any required addons in his/her header files! e.g. If my addon uses ofxVectorMath, then obviously I’m going to declare the define and include addons.h in my addon’s header files… otherwise it would be a nightmare for users!

well in order to stem confusion i made a wiki article (zach would be proud) that describes most of the conundrums and structure of the install.xml. it can be found at The #define way is simple and it just works. There’s no need to fix what isn’t broken.

Nice! I never really understood how to make that xml file until now. Very well put together and explained.

no problem. it’s a second nature to me now. as soon as i solve some sort of problem i have this urge to write a wiki article about it… (thanks a lot zach :P… if they only made an Xcode for windows and linux…

hi kyle,

I understand what you are suggesting, but there are some reasons why it makes sense to add what you want into the main OF codebase (by addons.h) -

a) it makes it really easy to see what’s an addon vs any other code you might have in your project (like random libraries, or things not part of OF, etc)
b) it makes the list of what addons are in your project easier to grasp (and easier in the future to see all the addons in your OF directory)
c) it can lead to cleaner error checking with addons that require addons.
d) in the future, somehow the addon changes somehow (or the main include changes) you can alter that include in one place, as opposed to every single instance you have used that include.

I hope that makes sense -

anyway, this is still very new at the moment and it worth it to discuss other styles. you are free also to use it however you want !!!

thanks artem for the wiki pages !

take care,

I just wanted to add, that I just experienced the wickedness of these addon defines. while i was trying to get the ofxSimpleGUI addon to run on with my app, I was getting tons of compile errors, because it had code to handle and render lots of objects which were in addons which I didn’t have in my project (vector, opencv, optical flow etc.). So I used the addon defines to ifdef around the relevant sections in the ofxSimpleGUI - so if my project doesn’t have the openCV addon, the relevant controls don’t get included - awesome \(^_^)//