Add documentation on how to compile tutorials.

[psigen]

While there's a lot of documentation explaining the source code of the included DART tutorials, there actually isn't any documentation on how to build the tutorials in the first place. This can lead to confusion for new users (e.g. #751).

We should add a section to the tutorials documentation that explains how to build just the DART tutorials if someone has already installed a version of DART. We may also want to consider if it would be useful to document/create a version of the tutorials CMakeLists.txt that can build independently from the DART source tree, for users that have a system-installed version of DART (from deb or brew) but want to compile just these tutorials.

[mkoval]

I strongly agree with moving the tutorials out of the DART source tree. Most users install DART as a binary package and build code outside of the source tree that depends on it, e.g. using find_package(DART) in CMake. As far as I can tell, the only way to currently build the tutorials is as part of DART (see below).

I suggest either: (1) moving the tutorials to a separate repository or (2) installing the tutorials to /usr/share/dart and providing instructions for how to copy them to the user's working directory. In both cases, it's important that the tutorials find DART as an external dependency.

If we run these tutorials on Travis, this could also partially address #738.

---

I am not a C++ novice by any means and am confused myself about how the tutorials are supposed to work. I just attempted to build them out-of-source and failed on several fronts:

1. Determine which version of DART I have installed (note: figuring out how to do this took quite a bit of Googling):

   $ dpkg-query --show libdart6
   libdart6    6.0.1.ppa4~trusty
   

2. Checkout the corresponding version of DART from source (note: there is no tag for v6.0.1, so I installed 6.0.0 and hoped for the best):

   $ git clone https://github.com/dartsim/dart.git dart_checkout
   $ cd dart_checkout
   $ git checkout v6.0.1
   error: pathspec '6.0.1' did not match any file(s) known to git.
   $ git checkout v6.0.0
   

3. Copy the tutorial files out into a separate directory:

   $ cp -r tutorials ../dart_tutorials
   $ cd ../dart_tutorials
   

4. Guess which COMPONENTS are being used:

   $ grep -hR 'using namespace dart::' . | sort | uniq
   using namespace dart::common;
   using namespace dart::dynamics;
   using namespace dart::gui;
   using namespace dart::math;
   using namespace dart::simulation;
   using namespace dart::utils;
   

5. Write a new CMakeLists.txt file that uses find_package to find DART with those COMPONENTS (note: I had to use trial and error to determine which namespaces were components and which were not).

   cmake_minimum_required(VERSION 2.8.12)
   project(dart_tutorials)
   
   find_package(DART REQUIRED COMPONENTS gui utils utils-urdf)
   
   include_directories(SYSTEM ${DART_INCLUDE_DIRS})
   add_definitions(${DART_DEFINITIONS})
   
   set(tutorials
     tutorialBiped
     tutorialCollisions
     tutorialDominoes
     tutorialMultiPendulum
   )
   
   foreach(tutorial ${tutorials})
     add_executable("${tutorial}" "${tutorial}-Finished.cpp")
     target_link_libraries("${tutorial}" ${DART_LIBRARIES})
   endforeach()
   

6. Build the project using CMake:

   $ mkdir build
   $ cmake -DCMAKE_BUILD_TYPE=RelWIthDebInfo ..
   $ make
   

7. Attempt to run the examples:

   $ ./tutorialBiped
   

8. At this point I gave up because I need to copy over some resources from the DART repository:

   $ ./tutorialBiped 
   Warning [LocalResource.cpp:47] [LocalResource::constructor] Failed opening file '/build/dart6-Dp4dlE/dart6-6.0.1.ppa4~trusty/data/skel/biped.skel' for reading: No such file or directory
   Warning [XmlHelpers.cpp:658] [openXMLFile] Failed opening URI 'file:///build/dart6-Dp4dlE/dart6-6.0.1.ppa4~trusty/data/skel/biped.skel'.
   Error [SkelParser.cpp:433] [readWorld] LoadFile [file:///build/dart6-Dp4dlE/dart6-6.0.1.ppa4~trusty/data/skel/biped.skel] Failed: Failed opening URI.
   tutorialBiped: /home/mkoval/dart_tutorials/tutorialBiped-Finished.cpp:300: dart::dynamics::SkeletonPtr loadBiped(): Assertion `world != nullptr' failed.
   Aborted (core dumped)
   

[mxgrey]

At this point I gave up because I need to copy over some resources from the DART repository:

Right, currently one of the tutorials uses a model which is distributed via the DART repo's data directory. In the long term, we've discussed having a web-based resource retriever for the models. That would be the ideal solution for this situation. In the meantime, the only thing I can think of would be to make a copy of the biped model if we want to split off the tutorial directory.

I strongly agree with moving the tutorials out of the DART source tree.

My only argument against moving it out of the source tree is that right now it's trivial to keep the tutorial version synced to the library version. If the library becomes incompatible with a tutorial at any time, it'll show up during compilation. My personal preference would be to make the build system of the tutorials directory independent from the rest of DART's build system (such that a user could copy/paste the tutorials contents to a different directory with no side effects), but [1] keep the directory in the repo as it currently is and [2] allow the build system of the tutorials directory to be called from the root build system of the repo. However, I don't feel overwhelmingly strongly about this preference, so if others would strongly prefer just taking it outside, I'd be okay with that.

[mkoval]

In the meantime, the only thing I can think of would be to make a copy of the biped model if we want to split off the tutorial directory.

That sounds good. In fact, I think the models are only used by the tutorials. Perhaps we should move it to the tutorials directory?

My personal preference would be to make the build system of the tutorials directory independent from the rest of DART's build system (such that a user could copy/paste the tutorials contents to a different directory with no side effects), but:

1. keep the directory in the repo as it currently is and
2. allow the build system of the tutorials directory to be called from the root build system

I agree - keeping the tutorials in the repository does simplify versioning. I am fine with doing this as long as we install the tutorials directory to ${CMAKE_INSTALL_PREFIX}/share/dart/tutorials. We can modify the ReadTheDocs instructions to start by having the user cp -r this directory into their working directory.

I am not sure how to achieve (2), but it should be a solvable problem.

[mxgrey]

I think the models are only used by the tutorials.

They're also used by the "examples", including the OSG examples. There has been discussion of moving the OSG examples into the same folder as the rest of the examples. We could potentially group all of them together: tutorials, generic examples, and OSG examples. We could have a layout something like this:

• examples/models for the models
• examples/tutorials for the tutorials
• examples/osg for the OSG examples
• examples/* for each existing example

We could make all the examples independent of the root DART build system.