Lumiera
The new emerging NLE for GNU/Linux

this page is a loose collection of hints how to set up the work environment for Lumiera development
Please feel free to add instructions for further environments as applicable.

There is no mandatory or even recommended IDE or editor — use what you’re familiar with and what fits the purpose. Even a plain text editor will do, but won’t get you far; in a project of the size of Lumiera, the cross-linking and searching features of a capable Editor or real IDE are almost indispensable to make sense of the code base.

Eclipse CDT

Notes by ichthyo

There is nothing really fancy with the configuration, things work as you’d expect. Use your common sense.

  • create a Makefile project (not a managed project where the IDE issues the build commands). There is a setup wizard “Makefile Project with Existing Code”, but the manual setup works well too and is easy.

  • visit the Project Properties. In the “C++ Build”, replace the default make command:

    • use scons as the basic make command and ensure you’re in the top folder of the project

    • you may set up a parallel build, with the “optimal jobs” setting (N# of jobs equal number of cores)

    • as targets for the incremental build use build testcode research

    • as argument for full project clean use -c all

  • set up the Indexer / Scanner for editing support and cross linking in the “C++ General” section of the Project properties

    • define as source location the directories src, tests, and maybe research

    • define as target location the directory target

    • in Preprocessor Paths, Macros we need to ensure that the “builtin compiler” configuration provider is actually enabled. This provider is used by the IDE to retrieve definitions from the compiler for syntax checks while you type and for building the search index. Typically, this provider is called “GCC Builtin Compiler Settings”; please ensure in the global (or the project specific) configuration that the invocation command line includes the argument -std=gnu++17 — otherwise you’ll get a lot of red squiggles on the new language features ;-)

Indexer troubleshooting

When the searching and cross references just don’t seem to work, make sure the indexer has run and actually was able to see the right files with the right locations

  • visit the Indexer tab and ensure the full indexer is enabled. Maybe change a setting and hit “apply” to force re-building of the index. Depending on your computer, this indexing might take quite some time initially

  • if the indexing process was onece interrupted by a crash or force shutdown of the IDE, the index database might be corrupted. Try to remove it, either through the GUI, or try to locate the raw data and kill it while Eclipse is not running.
    It is located in <workspace-dir>/.metadata/.plugins/org.eclipse.cdt.core/…

  • at some point in the past, I had problems with a lacking definiton of our own library facilities. I could resolve them by adding the directory target/modules to the Library Paths tab. AFAIK, this is no longer necessary with Eclipse versions since Kepler.

  • it might help to add the include paths of some of the most relevant libraries (in case the automatic discovery fails to pick them up properly). Eg. the GTK includes and the glibmm includes. But please do this systematically, starting from those symbols marked with red squiggles in the code. The Indexer assumes your settings are for real; randomly adding some library source without any clue what you’re doing will make things worse, not better.

  • Hint: the automatic discovery works by observing the output of the build process. It might work better if you do a full build once with scons VERBOSE=true, so the IDE can see the full command lines.

  • After upgrading to a new version of such library dependencies, it might be necessary to remove the old search paths manually — more so if they are still accessible on the system. Dont blame the Indexer, which basically has no way to find out he is looking at the obsolete source files…

Sourcecode for relevant external libraries

Especially when working on the GUI, it can be handy to have some of the most relevant libraries around: gdl, gdlmm3, glib2.0, glibmm2.4, gtk+3.0, gtkmm3.0. Just extract the source code into a directory and add it via the “Makefile Project with Existing Code” wizard. Of course it helps to some degree if you’re also able to build that code (even partially) from within the IDE, since the indexer is than able to pick up more cross linking information. However, this is not a strict requirement — even while F3 often fails, the “Open Type” dialog is able to spot the definition in many cases non the less, and when this fails, you can still use “brute-force” file search. What turns out to be much more an impediment in practice is the fact that you’ll have to jump through that C++ binding layer, and you need to pick up some basic knowledge how this layer works to wrap the underlying plain-C GTK entities; don’t confuse the C++ wrapper objects with the gobject (a concept from GLib) used by GTK.

Debugger Breakpoints not working

This seems to be a FAQ since Eclipse Kepler: If some or all breakpoints just refuse to work and you see messages on the debug console like No source file named XYZ, then you should

  1. ensure you really build with debug symbols on (but this is the default in our build system)

  2. switch the “debugging process launcher”

    • open the launch configuration you use to start the debugging session. (the “bug” icon in the toolbar or the Run menu and from there “Debug configurations…”

    • at the bottom below the content pane and left to the Apply and Revert buttons, there is a indication “using XYZ Process Launcher” and a Hyperlink “Select other”. Select the Standard Create Process Launcher. You can make this even the workspace default, this is the more conservative setting which works most reliably.

    • verify the settings on the “Debugger” tab: Debugger combobox should be “gdb/mi”, GDB command set should be “Standard (Linux)” and your GDB command file ~/.gdbinit (if you use one) should be sane, since it is executed at the start of every GDB session.