oF structure

by Roy Macdonald

Let's get into openFrameworks (I'll refer to it as oF from now on). The philosophy chapter talks about oF in a very abstract and conceptual manner, which is really useful for understanding the design of the oF environment. Now, let's take a look at what the oF download looks like.

I have found it very useful to explain oF by making analogies to cooking. Coding and cooking have a lot of things in common, and most people are familiar with the act of cooking. In this chapter, I'll be drawing connections between processes and terminology in cooking and oF.

First things first

You need to download the oF version and the IDE (Integrated Development Environment) that suits your platform. The IDE is a piece of software that will let you write, compile, run and debug the code you write. It is "integrated" because it uses other pieces of software to do each of the mentioned tasks. You can run your code without using the IDE, but the IDE will make your programming life much easier.

Go to http://openframeworks.cc/download and download the version that you need. By the side of each available version, you will find a link to download the matching IDE and how to install it.

Welcome to your new kitchen

IDE

As said before, the Integrated Development Environment, IDE, is the application you will be using to build your oF projects. It will let you write code, compile (bake it), test it and debug it (find out what is giving you a problem, if there is any, and fix it). There are several different IDEs, at least one for each platform you might be utilizing.

The IDE is your new kitchen, where you'll find all the tools to cook incredible stuff. Yet there are a lot of different kitchen brands, just like IDEs. All do the same basic things but might be laid out and named in a slightly different way. If you know how to use one, you can use any other.

Roughly speaking an IDE is a collection of different tools that allow you to write, compile, test and debug your code. These tools are all integrated, as for what IDE stands for, so it makes your coding life a lot easier.

All IDEs have a similar interface:

Abstract IDE interface
Abstract IDE interface

For clarification, I will just provide a link to each IDEs setup guide along with a screenshot of it showing the diferent areas just explained.

Apple Xcode (Mac only)

Click here to read the Xcode setup guide.

If you want to develop for iOS devices also read this iOS setup Guide.

Xcode screenshot
Xcode screenshot

Microsoft Visual Studio (Windows only)

Click here to read the Visual Studio setup guide.

Visual Studio screenshot
Visual Studio screenshot

QtCreator (Mac/Win/Linux)

Click here to read the QtCreator setup guide.

QtCreator screenshot
QtCreator screenshot

Android Studio (Mac/Win/Linux)

Click here to read the Android Studio setup guide.

Linux

If you are using linux, you will need to do a few additional steps in order to get all setup and running. Read it here.

No IDE

Under certain circumstances, usually a more advanced usage or for some platforms like the Raspberry Pi, there is no IDE and you will have to use the tools independently through the Terminal. This is not as bad as it sounds, it is actually a very straight forwards way, it will just require you to get used to the command line interface (CLI). More over, there are a lot of coders that prefer to use CLI over any IDE, as it can actually be a lot more powerful and in simple terms the IDE is just a fancy graphical user interface for the commands that you get in the CLI.

Some of this cases are the following.

Emscripten (Mac/Win/Linux)

Click here to read the Emscripten setup guide.

Emscripten is a compiler that will turn your C++ code (the native language of openFrameworks) into JavaScript code, which is used by the internet browser. Which means that you can run your oF code in a browser!

If you are not familiar with the openFrameworks environment, C++ and JavaScript I strongly suggest to avoid Emscripten as your first approach.

MSYS2

Click here to read the MSYS2 setup guide..

MSYS2 is a software development platform for Microsoft Windows that provides a Unix-style interface.

Raspberry Pi

Click here to read the Raspberry PI setup guide.

OpenFrameworks runs on the raspberry too. Although you will need to use the CLI tools with it and probably connect to it remotely.

Pandaboard

Click here to read the Pandaboard setup guide.

ARMv7

Click here to read the generic ARMv7 setup guide.

Running examples

Find the oF version that you downloaded and decompress it. From now on we will refer to this folder as the oF root folder. You can place the oF root folder anywhere you like. One thing to stress is that oF is designed to be self-contained -- everything you need will stay in one folder, which can even be moved around on your drive if you need, but don't mess with the folder structure within this folder as nothing will work then. If you download another version of openFrameworks, it should stay in its own folder and don't try to merge them.

Open it. Inside of it, you will find several folders which we will describe below in more detail. For now, navigate to the examples folder and let's try to compile examples/graphics/graphicsExample. If you are on OS X, click on the graphicsExample.xcodeproj. If you are using Visual Studio, choose the "graphicsExample.sln" file. For QtCreator open the "graphicsExample.qbs"

Now your IDE should open and load this example. It should look like the IDE screenshots above. Locate the "Run" button or menu option and click on it. The example should compile (which might take a while, since the first time you compile you are also compiling the whole oF library). You'll see a lot of files being compiled the first time -- don't worry, this will just happen once or when the oF library needs to be rebuilt. Feel free to get a cup of coffee or stretch. Long compile times are great moments to take a screen break. It really depends on the machine in which you are compiling, for example, on a modern desktop or laptop computer it will take about a minute or two, but on small computers such as a Raspberry Pi it can take a lot, like half an hour.

If everything went well, a new window will pop up and display the example you just compiled. If this happened, congrats! You just have installed and compiled openFrameworks successfully and you are ready to go on. If this didn't happen, the first rule is, don't panic! Check the notes below for each IDE and be sure to read the release notes that come with oF.

If the graphics example works, spend some time going through the other oF examples and running them. Usually, it's good practice to close the current project / workspace completely before you open another one. Once the oF library is compiled, the projects should build quite quickly!

If you have trouble, please keep track of what errors you have, what platform you are on, and start using the oF forum to find help. There are years of experience there, and really helpful folks who can help answer questions. First, try searching for a specific error and if you don't see it, post a question on the forum. When you are beginning it can be quite frustrating, but the community is very good at helping each other out.

Once done continue reading.

.md files

You will find a lot of files that have an ".md" or ".markdown" extension. These are Markdown files, which are just regular text files that have a special syntax that allows for embedding URLs, images and styling text while making is still human readable if you are not using a the needed App for visualizing it, which at the same time makes it really easy to write. If you don't know markdown, then consider learning it. It is quite easy and it will prove to be very useful for things much broader than just openFrameworks or coding.

Some good markdown readers/editors are:

TODO: add list of markdown readers

Inside most examples there is a README.md file, which will contain some useful information about each specific example. If you just want to read these and don't want to install anything just go to the openFrameworks github repository and browse the examples folder and it will automatically render the readme file if there is any.

oF folder structure

Inside the oF root folder you will find several other folders, at least, the following:

Addons

The "addons" folder will contain the included "core" addons. Addons are extra pieces of code that extend oF's functionalities, allowing you to do almost anything with oF. Addons are usually written by third parties that have shared these. The "core" addons, the ones already included in your oF download, are addons that are used so frequently that it has been decided to include them as part of the official oF download. These are coded and maintained by oF's core developers. These are also checked and updated for each oF new release.

Within the examples folder you will find examples for each addon.

You can also go to ofxAddons where you'll find a huge collection of additional addons from the community.

Apps

This is the folder where you put your project files as you make new projects. Your current oF download contains the folder named "myApps" inside of "apps", and this is where the project generator will default to when you make a new project. One important thing to note is that the project is positioned relatively to the libs folder, i.e. if you were to look inside the project file you'd see relative folder paths, i.e. ../../../libs. This image is showing how ../../../libs might work visually:

app position to root
app position to root

A key thing to note is that your project files always have to live at this depth from the root. If you alter their depth, they won't find the other pieces they need to compile. This is a very common mistake for beginners, especially as you start to find example projects and bring them in oF to test, etc. Please make sure you understand that projects are always setup relative to the root level. This is what makes the whole oF folder able to be anywhere on your hard drive -- it's a self-contained package. This is probably the #1 issue beginners have, so it's worth emphasizing.

Examples

This is a folder with examples, sorted by topic. There are a big bunch of examples that cover almost all of aspects oF. Each example is made with the idea of keeping it simple and focused on the particular aspect it tries to address. Therefore it should be easily understandable and a good starting point when you want to do something similar in your project.

docs

Inside this folder you will find some useful notes for different platforms, libraries used and others.

libs

These are the libraries that openFrameworks uses to compile your project. They include things like FreeType for typography support, FreeImage for image loading, glfw for windowing, etc. Also, the code for openFrameworks is in libs, as well as the project files that help compile oF. If you need to look at the source code, here's where to look.

other

Here you'll find an Arduino sketch for using the serial example located at examples/communication/. This is handy to check that your serial communication with Arduino is set up correctly and working.

projectGenerator

oF now ships with a simple project generator which is really useful for making new projects. One of the larger challenges has always been making a new project. This tool takes a template (located in the scripts folder) and modifies it, changing the name to a new one that you choose and even allowing you to specify addons. It allows you to place the project anywhere you want, and while we've structured all the examples to be a certain distance away from the root, you can set the position using this tool (e.g. if you put the project deeper, it will change the ../../../libs to ../../../../libs). It's designed to make it easy / trivial to start sketching in code, without worrying too much about making a new project. In the past, we've always recommended that you copy an old project and rename it, but this is a more civilized approach to making projects. Check the readme file where the usage of this app is described.

The oF Pantry

Your default new kitchen will only have tools for coding, but the oF kitchen comes with a super nice pantry, filled up with really nice, cool and useful stuff.

Imagine that you want to cook something but your kitchen has no pantry or if there is one it is completely empty. Cooking anything would be quite difficult under such conditions, as you'd have to go out and buy the things you need and you probably won't find everything in one outing. This is not a nice scenario, especially if you want to get creative and make awesome things.

So, what happens when you have your pantry filled with oF's components? You will be able to cook whatever you want because some really good ingredients are already there. Additionally, there are some really nice tools in there. This will let you complete recipes in a short amount of time, leaving you more time to get creative and try out new and more delicious recipes.

What is inside the oF pantry

Here you will find a lot of different things, from ingredients to tools, all ordered according to use. This is a breakdown of how oF code is organized (as well as the examples) and should give you a sense of what oF contains:

Addons

As mentioned before, addons extend oF core functionalities. In each oF distribution there are several included addons, usually referred to as "core addons". There are also some core addons that are only ment to be used on certain platforms, like ofxiOS or ofxAndroid.

The following are some of the core addons that you will be able to use regardless of the platform for which you are developing:

That's what's in the pantry. What do you want to cook?

please note that this book / chapter is a work in progress. Feel free to suggest edits / corrections here