ug4
Developing with the Eclipse IDE

Table of Contents

The page is an install guide for the usage of Eclipse for ug.

Note
If you're working at the G-CSC, there is a preconfigured Eclipse download available. Ask for "software server".

Download Eclipse

  • Download the latest release of Eclipse from http://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/neonm4a : Eclipse IDE for C/C++ Developers
  • Unzip Eclipse and move it to your "Application" folder (MAC only)
  • Start Eclipse. On startup you are requested to choose a workspace. This is the location, where your projects will be placed. Specially, ug4 will be placed here. So, choose an folder where you want ug4 to be downloaded to. (e.g. home/projects/)
  • Make sure that the Eclipse-git Plugin 'EGit' is installed.

Generating Eclipse Project-Files

In order work with UG4 in Eclipse, please download and install UG4 as usual through UG4's package-manager (see https://github.com/UG4/ughub).

You'll find detailed instructions on how to generate and import UG4 project-files for Eclipse here: https://github.com/UG4/ughub#importing-ug4-into-your-ide

Build in Eclipse using external Makefiles

In order to build the ug4 libraries via Eclipse, you first must create the Makefiles. This is done using Cmake in the terminal (go to Setup and Installation if you did not already install CMake).

  1. Open a terminal/shell window
  2. move into your workspace directory you chose before
  3. cd ug4
  4. mkdir build_debug
  5. cd build_debug
  6. cmake -DDEBUG=ON .. --> Makefiles are generated

Note, that once the Makefiles have been created, you do not have to rebuild them at any time. This step has to be performed only once. Now, these Makefiles can be used in Eclipse:

  1. Click right on folder ug4 -> Choose Properties
  2. Under C/C++-Build:
  3. Disable Generate Makefiles automatically
  4. Disable Use default build command
  5. Choose Build directory: ... -> Click Filesystem -> Choose newly created folder build_debug
  6. In Behaviour: In Build (incremential build) remove all
  7. Disable automatically build: In Heading bar: Project -> remove Build automatically

You find the binary in ug4/bin/ with the name ugshell

Run ug-executable via Eclipse

If you want you can also start the executable from Eclipse. This is especially useful if you like to use the build-in Debugger.

  1. ug4 -> Properties
  2. Run/Debug Settings
  3. Click New ... -> C/C++ Application
  4. Fill in executable: Browse -> ug4/bin/ugshell
  5. Choose Arguments -> Program arguments: Fill in: -ex laplace.lua

Of course, if needed, use adapted arguments.

Path and Symbols

Eclipse has a powerful Autocompletion-Mechanism, Syntax-Highlighting for C++ and many other things. To make them available, you have to tell Eclipse, where to look for:

  1. Click right on folder ug4 -> Choose Properties
  2. Under C/C++-General -> Subfolder Path and Symbols
  3. Under Includes click Add ...
  4. Click on Workspace ... and choose the folder ugbase
  5. Check: Add to all languages and Add to all configurations

If you use build flags, you must tell Eclipse to recognize them. Specially, if you do not use UG_PARALLEL, all Parallel Code will not be highlighted but regarded as dead code. So, add it to the Environment:

  1. Click right on folder ug4 -> Choose Properties
  2. Under C/C++-General -> Subfolder Path and Symbols
  3. Under Symbols click Add ...
  4. Fill in UG_PARALLEL, value: ON
  5. Check: Add to all languages and Add to all configurations

Syntax Highlighting in Lua

Lua is the recommended scripting language in ug4. In order to have a more comfortable editing of Lua-Scripts you should install a Plugin. We created an own plugin which provides Syntax Highlighting and code completion for the ug4 registry functions/classes: Go here ugIDE for further details.

Available Plugins:

Note
You can only install one plugin at a time.

Syntax Highlighting for Doxygen

As Doxygen is used for generating the documentation for ug4, it is handy having the Doxygen commands as \brief, \param or alike highlighted correctly.

In Eclipse one have to activate that implicitly. Therefore two actions need to be taken in Eclipse:

  1. Window (Eclipse) or-> Preferences -> C / C++ -> File Types -> New ... -> *.doxygen and Type -> C++ Source. Confirm with OK.
  2. Window (Eclipse) or-> Preferences -> C / C++ -> Editor, under Documentation tool comments select Doxygen as workspace default. Confirm with OK.

Additional Tipps & Tricks

  • Speeding up the indexer: Eclipse -> Properties. Subfolder C/C++ -> Indexer : Disable Index unused headers, Enable Index source and header files opened in editor.
  • Line Numbers: Eclipse -> Properties. Subfolder General -> Editors -> Text Editors. Enable "Show line numbers".
  • Show Changes in File: Eclipse -> Properties. Subfolder General -> Editors -> Text Editors -> Quick Diff. Enable "Show differences in overview ruler" and set "SVN Working Copy Base" as reference source.
  • Switching Tabs: On Mac: Cmd+F6. On Windows: Ctrl+F6. Ctrl+PageUp / Ctrl+PageDown: Cycle through tabs without showing a list.
  • search a file in the tabs: Cmd+E (Mac)
  • search a symbol (e.g. function) in the current file: Cmd+O (Mac) or Ctrl+O (other)
  • quick open a resource (e.g. a file): Cmd+Shift+R (Mac) or Ctrl+Shift+R (other). Enter filename.
  • quick open a symbol: Cmd+Shift+T (Mac) or Ctrl+Shift+T (other). Enter type/class/function name (will only work when current file is .h or .cpp)
  • correct indention: Cmd+i (Mac) or Ctrl+i (other)
  • goto line: Cmd+L (Mac) or Ctrl+L (other)
  • You can change key mappings under Eclipse -> Properties, General -> Keys. (e.g. Next Editor to Ctrl+Tab, previous Editor to Ctrl+Shift+Tab)
  • Other recommended plugins are CMake plugin (install site http://cmakeed.sourceforge.net/eclipse/), TeXclipse (install site http://texlipse.sourceforge.net).

Create an UG4 project from exisiting source in Eclipse

Sometimes you already have checked out the source and just want to add ug4 as a project into Eclipse. This can be the case if you did svn manually or want to use Eclipse to remotely edit files that you access via FUSE/SSHFS or via other file networks.

  • In Eclipse's Menu, choose File -> New -> C++ Project
  • Uncheck "Use default location"
  • Use "Browse" to select the root directory of your ug4.
  • Enter a name for that project. This can be different from the name of your ug4 directory and has to be different from all other projects in eclipse, so you could also choose something like "ug4onHermit".

Note that this will create two new files in your ug4 directory: .cproject and .project. If you want to use this project in another eclipse (like another version or on another computer), you have to use File -> Import -> Existing Projects into Workspace .

Troubleshooting

  • Eclipse hangs up at "Loading workbench": Try to reset your workspace (see below)
  • C++-Autocompletion not working/hanging up: Try to reset your workspace (see below)
  • Reset your workspace: Quit Eclipse. Go to your workspace directory, and there to .metadata/.plugins. (That's where eclipse stores all the workspace data, like which projects you have in eclipse, and also C++-Indexer files). Delete all directories there except for org.eclipse.core.resources, org.eclipse.core.runtime and org.eclipse.cdt.core. Index files are stored in org.eclipse.cdt.core, you can delete that too if it is still not working. There's also a script for that in ug4/scripts/shell/ugrestoreworkspace (execute in your workspace dir).
  • SVN Information not showing for a project: Try to delete the project from the workspace, then add it again (import -> existing workspace).
  • A project is damaged in eclipse and you want to set it up from scratch: Delete it from the workspace. Quit Eclipse. Go to the projects directory and delete the files .project, .cproject and .settings.