CMake and Eclipse¶
Eclipse paired with CMake creates a full-featured cross platform development and build environment...when the correct incantations and pixie dust are mixed in exactly the right way. One too many frogs legs or lotus beetles and the system is totally useless. Some mixtures work only on certain version combinations of CMake and Eclipse, but the process described below seems to be the most robust across multiple versions of CMake and Eclipse.
Basic setup¶
- Ensure CMake at up to at least version 2.6.x. This process was verified against versions 2.8.4 and 2.8.5.
- Eclipse version Helios or Indigo is recommended. Be sure to install Eclipse for C++ developers or install the CDT via Eclipse update.
- Reference OSG Building and Debugging Gotchas for other recommended Eclipse plugins for NS12 development.
Project setup¶
Eclipse has certain limitations regarding how project directories can be structured and some of these are contradictory to popular ways of using CMake. CMake supports 'out-of-source’ builds. That is, all build specific and CMake generated files are kept out of the source tree for cleanliness. A common approach is to create a directory called 'build’ in the root of the source tree and assign that as CMake’s build directory. However, this violates Eclipse restrictions and breaks indexing making it next to useless. Another option is to do an in-source-build (build dir = source dir) this is messy but worked fine up until Eclipse Indigo and CMake 2.8.5 where it will also cause Eclipse to nova. Therefore, the recommended approach is to make the build directory root at the same level as the source root.
/home/foo/source/nightshade-ng-engine /home/foo/source/nightshade-ng-engine-build
Compiler Note CentOS 6: To use the required more modern compiler version be sure to run scl enable devtoolset-7 bash in a terminal before continuing. Always run cmake, Eclipse, and build from this terminal.
With the directory structure in place, fire up cmake-gui, be sure to set project file generation for Eclipse CDT4 and run configure/generate.
Alternately use this command line (run from build directory):
OS6: cmake -G"Eclipse CDT4 - Unix Makefiles" -D CMAKE_BUILD_TYPE=RelWithDebInfo -D USE_VDEC=0 ../nightshade-ng-engine/ OS8: cmake -G"Eclipse CDT4 - Unix Makefiles" -D CMAKE_BUILD_TYPE=RelWithDebInfo -D TESTING=0 ../nightshade-ng-engine/
Note that Nvidia NSight is a version of Eclipse on Linux, but does not currently (2016-10) have any graphics debugging capabilities. So not much point using it. (See instead the Nvidia Linux Graphics Debugger which is a separate application.)
Now start up Eclipse and do the following to import the project.
- File→Import...
- General→Existing Projects into Workspace
- For the root directory enter the build root directory, not the source root
- Leave other options unchecked and click Finish
Let the indexer run and cross your fingers. Open a couple source files and verify all include files are resolved.
Compilation¶
Before you can run and debug your program you have to tell Eclipse what binary to run and what project to compile.
- Go to Run → Run Configurations...
- Double click on C/C++ Application to create a new configuration.
- Browse to the NG executable (build/src/NightshadeNG) for the Application field.
- Browse to select the NG project for the Project field.
Now you should be able to run the app.
Debugging¶
- Set up a debugging configuration in Eclipse. It appears that “Attach to Process” is the required type of debug configuration, otherwise NG will just segfault when Eclipse starts it.
- Be sure to manually add the actual source directory in the source tab as a local filesystem path.
- Add source paths to shared library code also so you can step through those.
If Nightshade exits at startup with no stack trace (you can confirm this by running NG from gdb directly) then you need to set up an eclipse debugging configuration by attaching to a running NG process.
You may have to manually launch NG if it doesn’t start via eclipse, then run the attached debugging configuration.
Common Issues¶
- If you get “no source available” did you set the source directory for the debug configuration?
- If you get a segfault but no stack trace you can confirm this by running gdb manually:
gdb Nightshade catch syscall exit exit_group r bt
Use attached debug mode instead.