7. Working with openFrameworks

openFrameworks, the easiest way

+ installing openFrameworks

- simply follow the instructions at http://www.openframeworks.cc/download/ (see notes for windows users below)

- based on the type of OS (OSX, Linux, Windows), you will need to download the proper distribution of openFrameworks. In addition you will need an Integrated Development Environment, xcode for Mac or Visual Studio Community for Windows. There are also distributions that will run on platforms such as arm boards (Raspberry Pi etc) and iOS and Android. The instructions to download and set up the correct versions of the IDE to work with OpenFrameworks are listed on  http://www.openframeworks.cc/download/. Advanced topics: running OF on Visual Studio 2019, or on Visual Studio Code.

+ additional install notes for windows users: 

- if you want to use Visual Studio (the MS stack)

- for novice users on Windows who don't have a strong preference for an open stack this is the preferred approach. Visual Studio may take a while to download and install but the installation process is relatively straightforward.

- follow the instructions through the links above until 'openFrameworks plugin for Visual Studio' so download and unzip the openFramworks file for Visual Studio, download and install Visual Studio and install the codecs.

- after running the first install of Visual Studio, the system will like have to install additiional C++ compilers and tools. To force this compile one of the OF examples:

    - unzip the downloaded openFrameworks zip and place the contents in some easy to find folder

    - pick an example project, for example \examples\3d\3DPrimitivesExample and double click the .vcxproj file. Visual Studio should open the project. in Visual Studio click the green play button on the toolbar with 'Local Windows Debugger' next to it. This likely causes Visual Studio to pop a message that it will download and install additional files (and will ask to close Visual Studio during the process). After it completes you can restart Visual Studio and go through this process again, the example should now compile and run.

- have fun compiling and running some of the other examples.

- the openFrameworks plugin  can be used to create new projects, but will only work after these steps have been completed, if not it may throw an ugly error. Your new apps should go into \apps\myApps in the openFrameworks folder.

+ testing your installation

- go to the directory \apps\examples  in the Open Frameworks folder you downloaded and unzipped and open a random example

- for Visual Studio, choose file - open - project/solution and open the .vcxproj file and then F5 (Start Debugging) or the play button on the tool bar

- for xcode,  open the .xcodeproj file in the example root folder and hit the top left play button, but do make sure that the drop down next to it states the name of your example, not openFrameworks

- try out a number of examples, you will notice that creating the program ('compiling') will get faster over time because the libraries that the various examples use do not need to be recompiled. If you want to have a look at the code behind the example. the starting point is typically  ofApp.cpp

+ creating your first program

- there are two ways to create a new program

- you should have a directory emptyExample in the folder <openFrameworksfolder>/apps/myApps. Just copy this folder and rename the folder to the name of your project. If it is not there, copy the emptyExample folder from the the exercises folder to apps/myApps.

- use the Project Generator. For xcode, see the Generating a New Project section in the xcode OF install instructions, for Visual Studio see the openFrameworks plug in for Visual Studio section in the VisualStudio OF instructions.

- then make a small change for example the below in ofApp.cpp, and build and run the program.

void testApp::setup(){

    cout << "Heya!" << endl; // just getting started

}

+ learn more

- get inspired by this gallery of projects

- browse over 1100 addons that are available for openFrameworks

- explore tutorials (and some more) and documentation (also on the syntax for C++). 

- a video series on Youtube (still growing and highly recommendable)

- OpenFrameworks examples on Vimeo

- The Programming Interactivity book by Joshua Noble - recommended for folks new to coding

- OpenFrameworks Facebook group

- https://github.com/benMcChesney/Open-Frameworks-Tutorials

- Instagram #openframeworks

- Twitter @openframeworks, #openframeworks

+ bang your head against the wall

- only do this very softly to make sure you don't injure yourself

+ get help

- Discuss, post questions and provide answers on the OF Forum

Advanced Topics - Using OF with GitHub & source control

+ getting openFrameworks straight from github = a stable distribution further developed and bugs fixed

- get openFrameworks straight from github: the place where openFrameworks is stored and developed online

Download and set up openFrameworks (and code::blocks or xcode as needed) as per the instructions on the OpenFrameworks website.

-- master: https://github.com/openframeworks/openFrameworks/zipball/master

-- develop: https://github.com/openframeworks/openFrameworks/zipball/develop

+ version control

alternatively you could get the openframeworks sources through version control, so you can keep updating the framework when new issues have been solved or new features have been added. you can always go back in time with version control.

first you have to install git: http://git-scm.com/

than you can use git from command line, but nicer to use a client program as mentioned below:

- SourceTree (MAC / WIN): http://www.sourcetreeapp.com/

- Fork (Mac / Win): https://git-fork.com

You would need to 'clone' a repository from github (url = https://github.com/openframeworks/openFrameworks.git) to a workspace folder on your local disk.

In the advance options you could state clone from branch 'master' or 'develop'.

+ collaborate on code: version control

if you want to work on code in collaboration dynamically, you would also need a versioning control system.

as mentioned before in 'version control' you will have to install

- using git: http://git-scm.com/

- mercurial: http://mercurial.selenic.com/

there are some platforms around that can host your code:

- google code: https://code.google.com/intl/nl/ (open source only)

- bitbucket: http://bitbucket.org/ (private collaboration)

- github: http://www.github.com/ (private, but public in collaboration)

is the client programs to these platforms:

- SourceTree (MAC / WIN): http://www.sourcetreeapp.com/

- TutoiseGit (WIN): https://code.google.com/p/tortoisegit/

- SmartGit(WIN/MAC): http://www.syntevo.com/index.html

- Fork (Mac/Win): https://git-fork.com

there are specific words used in these programs:

- repository: the 'online folder' where all the code comes together and is stored online

- pull: get new code from the platform to your local version

- push: put the code of your local version to the platform

- commit: add your local changes for the waiting line of changes to be pushed

- merge: mix web and local code together when changed happened on same lines of code: choose which to use

- update: go to the revision selected: you can update to an older version that worked right before

the general idea is that person A writes some code, commits a change on file Z, commits another change to file Y and then pushes these commits of Z and Y to the online repository. person B could then pull the new changes (commits of Z and Y) from the repository and merge this with the local version.

the client program shows a path of all the commit changes that happened in the repository, mentioning who was responsible for the changes.

+ some contributions to this info page by

- Studio Arne Boon, http://www.studioarneboon.nl/