IDE Setup
=========

_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

. ensure you _really_ build with debug symbols on (but this is the default in our build system)
. 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.

