Add examples/README.md to explain and provide steps to create missing project/make files

[pizthewiz]

An issue that seems to trip up users new and old seems to be the missing example project files. I cannot count the number of times I've tried to help a user out on IRC or the forum that has run into this and I really feel as though we are making things more difficult for end-users. The main README.md does reference the issue:

If you are working with the Git repository, the stable branch of the OF repository corresponds to the most recent release, with a few important differences:
…
3. This GitHub repository has no project files for the different examples. They are generated automatically for each release using a tool in apps/devApps/projectGenerator/.
If you want to work with the openFrameworks GitHub repository, you should use the project generator to create project files for all the code in examples/.

but this isn't particularly helpful as it is hiding behind a "developers" badging (What if they are just a user and not a developer? Does it mean developers of openFrameworks proper or developers of applications using openFrameworks?), this probably isn't descriptive enough for new users and this doesn't help users that downloaded a repo archive via GitHub.

I suspect there are good reasons for not having the project/make files in the repo itself (though if it is file size, one could argue a couple of MB of project files pales in comparison to the trillion MBs of third party dependencies 😉) but I think it would be kind to pull out the issue to top billing in the main README and create a secondary README right in the examples folder as well. I am a bit behind on the current state of PG, command-line vs GUI, submodule vs inline, so I'm not in a great position to offer the README tweaks, but I do think it is an issue I'd hope could be considered for 0.9.0 if others felt important.

Note: the examples/README.md would probably need to be stripped for the nightly builds.

[pizthewiz]

Some issues to reference:
#2014, #2958, #1422

[bilderbuchi]

What if they are just a user and not a developer?

Then, imho, they should work with either a (stable) release or (bleeding edge) a nightly build, which both have the example project files afaik.

[pizthewiz]

That is definitely an option and usually what I recommend to asking users (and sometimes I tell people to check out scripts/dev) but bubbling that up to the README to set expectation could be really helpful.

[avilleret]

one more reason to work with git repo rather than with release, the shader tutorials are not packaged with the release

and I was confused to not see any makefile in the example folder until I read entirely the Readme
so maybe one good advice could be : read the manual first ;-)
btw, pushing the Developer section up to the head of the readme could help.

[bilderbuchi]

one good advice could be : read the manual first ;-)

that is always good advice! :-)

[robert-wallis]

As a newbie, I found some issues with building for iOS from the normal non-github download like #3178. Then trying to run the iOS opencvExample I got something similar to #3388. So I said, "enough already", and downloaded the source thinking I would have these patches. But the examples have no projects and the README.md just says:

If you want to work with the openFrameworks GitHub repository, you should use the project generator to create project files for all the code in examples/.
For per-platform readmes, and more informations, see the documentation.

Not super helpful, but fine I'll learn how to use project generator. However it's own 'per-platform' documentation doesn't tell you how to build the examples: https://github.com/openframeworks/openFrameworks/blob/master/docs/osx.md

So I just found the xcodeproj in projectGeneratorSimple, but after compiling and running it, I cannot select iOS for the platform. And I can't seem to just select and example I want to compile, it only wants to generate new projects.

Then I compiled the commandLine project from the xcodeproj and all I could get it to do after setting the ENV var was this:

$ ./projectGenerator -o ../../../../ -p"ios" -v ../../../../examples/ios/opencvExample
Abort trap: 6

I even tried debugging it in XCode, setting the environment params and command line options, and it just crashes in the POCO_APP_MAIN(commandLineProjectGenerator) macro at the bottom before int main(...) is even called.

Then I finally went to the command line and ran a make in the commandLine project, waited for it to build, and fail at the end with this error:

cp "ARGET_BUILD_DIR/RODUCT_NAME.app/Contents/MacOS/RODUCT_NAME" "ARGET_BUILD_DIR/commandLinePG"; rm -rf "ARGET_BUILD_DIR/RODUCT_NAME.app";  mv "ARGET_BUILD_DIR/commandLinePG" "ARGET_BUILD_DIR/projectGenerator"
cp: ARGET_BUILD_DIR/RODUCT_NAME.app/Contents/MacOS/RODUCT_NAME: No such file or directory
mv: rename ARGET_BUILD_DIR/commandLinePG to ARGET_BUILD_DIR/projectGenerator: No such file or directory
make[1]: *** [afterplatform] Error 1
make: *** [Release] Error 2

But that is actually a success because the RODUCT_NAME.app file exists as projectGenerator.app, Inside it there's a nice executable that I can run:

$ bin/projectGenerator.app/Contents/MacOS/projectGenerator ../../examples/ios/opencvExample
-----------------------------------------------
setting OF path to: /Users/robert/3rdParty/openFrameworks
from PG_OF_PATH environment variable

target platform is: osx

using additional template

updating project /Users/robert/3rdParty/openFrameworks/examples/ios/opencvExample
parsing addons.make
adding addon ofxOpenCv
saving addons.make
project updated!
-----------------------------------------------


1 project updated in 1.89062 seconds

But wait that didn't work, ... platform is: osx

$ bin/projectGenerator.app/Contents/MacOS/projectGenerator -p"ios" ../../examples/ios/opencvExample
Abort trap: 6

I hope this gives someone perspective on what might happen to users. And I think that I got pretty far before giving up for now.

[ofZach]

this is the project generator repo if you want to report any issues with the command line tool -- I haven't seen the problems you've mentioned and happy to try to help you debug them:

https://github.com/openframeworks/projectGenerator/

In the past, we've had two project generators, the simple one (which is user facing and just makes new projects) and the advanced one used for generating projects. We're moving over to the command line tool, so you're catching everything at a transition time....

[ofZach]

I'm seeing the abort trap: 6 error on my side to (this seems recent) and am looking into it on the projectGenerator repo

[robert-wallis]

Thanks I added a new ticket over there openframeworks/projectGenerator#51

[bakercp]

@pizthewiz Could you take a look at the current documentation on this issue and see if it has been resolved in a satisfying way? If not, could you propose some changes via a PR? Thanks!