Linking addons to a new project

All the core addons and most of the non-core addons have examples of their usage. So if you are starting a new project and need to use just one particular addon, the simplest way to do it is to just copy the folder containing the example of the addon into a new folder, rename the folder, and start to change the project's code for your needs.

For example, if you plan to make a project that will use XML files to store the settings in the project, then copy the folder xmlSettingsExample from examples/addons to apps/myApps and rename the copied xmlSettingsExample to myProjectXml. Finally, open the project inside myProjectXml folder and continue developing it there. The ofxXmlSettings class is included in the project, so you can use it.

If you need to link several addons to the new project, it is a good idea to generate an empty project with linked addons using the Project Generator wizard application, included in openFrameworks.

Using Project Generator

To create a new project with Project Generator, perform the following steps:

1. Run the Project Generator application. Depending on your OS, it is located in the folder projectGenerator or in apps/projectGenerator. You will see its main screen with a number of buttons as shown in the following screenshot:

   

2. Click on the Name: mySketch button, the text input window appears. Enter the desired name for your project here, for example myProject1, and click on the OK button.

3. If you want, click on the Path: … button and select a folder for your project.

4. Now, click on the Addons: button. You will see a window with the list of addons currently installed in the addons folder:

   

5. On the left-hand side, you will see the list of core addons, and on the right-hand side, you will see the list of non-core addons. Note that if you have not installed any addons by yourself yet, the list to the right will be empty.

6. Select the addons you need for your project by checking the corresponding checkboxes. For example, if we want to use the OSC protocol and xml files, check the ofxOSC and ofxXmlSettings boxes:

   

7. Click on the << Back button and you will return to the generator's main screen.

8. Click on the GENERATE PROJECT button to generate a new project. Once generated, at the bottom of the generator's screen, you will see the text, generated: [path to our project].

9. By now, the project is generated and the addons are linked to the project but to use addons, we should add the #include directives of these header files. So the next step is to open the generated project and add the corresponding #include directives for the addons. Normally, the name of the included file for the addon is exactly the addon's name with the .h suffix. In our example, we should add the following lines after the line #include "ofMain.h" in the testApp.h file:

   #include "ofxOsc.h"
   #include "ofxXmlSettings.h"

10. Now, you can continue developing and using all the addons you linked to the project.

There is one tricky thing regarding the linking of non-core addons; there is a dependence between the addons. That is, some addons may require other addons for their work. So if you link such an addon and try to compile the project without the required addons, you will get compiler errors. Fortunately, you can discover which addons you are missing by reading the compiler error message. For example, an error text such as Cannot open include file: 'ofxSTL.h': No such file or directory means that you are missing the ofxSTL addon. To resolve the problem, you need to install all the missing addons, restart Project Generator, select all the needed addons, and generate the project again.