Revision as of 01:08, 29 June 2018

Eclipse C/C++ Development Tooling (CDT) can be used as a multi-platform, multi-feature editor and debugger for GnuCash. Originally Eclipse has been a Java IDE, but got also a C/C++ project which has become quite mature.

Getting the Software

A new main release is usually every year at the end of june available. As of june 2017 Version 4.7 "Oxygen" is recent. Usually the first letter of the code name will increase by one for each main release.

An Eclipse Package

As usual, you should use the package manager of your distribution to install Eclipse. If no recent versions is available there, you will have to download and install it from eclipse org.

From Eclipse.org

At first you should have a look at the Eclipses package comparision page and determinate that bundle, which covers most of your needs - obvisous it should include C/C++, because that contains the support of different make utilities, which are used by most gnucash repositories.

Then we suggest to use the Eclipse Installer Oomph Setup for the download, which will allow some configuration and can later search for updates:

download it from eclipse-packages,
verify the sha,

Note

If you wish not to clutter up your $HOME directory with program files, run the following steps as admin:

su

. As a normal user you could use $HOME instead of /opt in the following steps.

extract it to e.g. /opt/eclipse/installer,
run
```
/opt/eclipse/installer/eclipse-inst
```

inside:

If you do not want to install all stuff to the current users home directory, you should configure it, to store the pool e.g. below /opt/eclipse.
Choose your desired

packages - Eclipse IDE for C/C++ Developers package has the desired CDT4 plugins including eGit - and
installation directory.

If you dislike Oomph Setup you can download and install everything manually from the Eclipse download page.

Distribution specific Notes

With Synaptic under Ubuntu / Debian

It's 2010/02/24 and the latest stable Ubuntu is 9.10 "Karmic." I believe the Debian procedure may be similar. HOWEVER, the Ubuntu packages may not be in sync with Debian.

There have been some bugs reported that affect the function of the Eclipse windows and buttons. See http://blog.export.be/2009/10/fixing-eclipse-for-ubuntu-karmic-koala-9-10/ and https://bugs.eclipse.org/bugs/show_bug.cgi?id=291257 for some details, and a corresponding Launchpad bug with workaround is here: https://bugs.launchpad.net/ubuntu/+source/eclipse/+bug/458703

This problem with GTK may explain the redraw issues I describe in the steps below...?

Install Eclipse

Open Synaptic Package Manager or Aptitude or whatever and install the Eclipse package. The current version as of these instructions is "Galileo," version 3.5.1.

Required Plugins

Obsolete Prerequisite: Add Software Sites in Eclipse

For whatever reasons the Galileo Eclipse package installs with NO default links to the standard software sites. So the Help->Install New Software panel has NOTHING in it until you add the appropriate URLs.

In more recent version you can use Oomph Setup or simply search Help->Eclipse Marketplace for your desired plugins.

Add the Galileo repository: click Add...

Name: Galileo

Location: http://download.eclipse.org/releases/galileo

Note: Replace "Galileo" with with the name of your Eclipse release.

Add the Schemeway repository: click Add...

Name: Schemeway
Location: http://schemeway.sourceforge.net/update-site

Once the software sites are included it's easy to install the C environment and Schemeway.

Install C/C++ if not already part of your package

This is recommend also if you work on the documentation (gnucash-doc) or the website (htdocs), because they all make use of the autotools (configure, make, ...) or at least <make>, which can be accessed by this package.

choose Help --> Install New Software
In the Work with menu, choose the name of your eclipse version. (For some odd reason, in Galileo nothing shows up in the software list on my system. I found I could put a * or Enter or something in the filter text field and the software list shows up.)
Scroll down to Programming Languages
Choose Eclipse C/C++ Development Tools
Click the Next button a few times, maybe confirm the license, and then the Finish button. It takes a few minutes to finish.

Suggested Plugins

eGit to use Git Commands in Eclipse

Eclipse's Git repository support is provided by the eGit package, which is already included in the Eclipse for C/C++ Developers bundles for Eclipse Oxygen.

cmake4eclipse

Only for the program suggested

cmake4eclipse automates a number of tasks normally involved in setting up out of source builds with CMake in Eclipse:

leave eclipse workbench;
manually fire up a command-line shell;
manually create a directory for the out-of-source-build;
manually change the CWD to that directory
manually invoke cmake, telling it to generate build scripts, which kind of build scripts you want and where source source files live;
re-enter eclipse workbench, configure the checked out project to use the generated buildscripts.

cmake4eclipse allows these tasks to be performed automatically within Eclipse.

To install it from within Eclipse select

Help->Eclipse MarketPlace and search for cmake4eclipse or
use its update site: https://raw.githubusercontent.com/15knots/cmake4eclipse/master/releng/comp-update/

then click Install. Then choose menu Help:Help Contents and read the CMake for CDT User Guide:Getting Started.

If you want to edit 'cmake files': CMake Editor adds color coding and syntax completion for CMake files.; Same Installation procedure as for cmake4eclipse.

Optional Plugins

Reports etc.: Guile

Install & adjust Dandelion (to be tested)
Install Schemeway (stalled, prerequisite below)

Prerequisite:

JDT - Eclipse Java Developement Tools
PDE - Plugin Developement Environment

If not already installed:

Help -> Eclipse Marketplace or in old versions:
1. Help --> Install New Software
2. In the Work with menu, choose Galileo or wharever the codename of your release is.
Search JDT and mark it,
Search PDE and mark it,
Click the Next button ...

Continue

(You may already be here) Help --> Install New Software
In the Work With menu, choose Schemeway.
Put an * or Enter or something in the filter text field to make the list show up.
Choose "SchemeWay Feature" (Currently this installs version 1.2.15)
Click the Next button a few times, maybe answer a licensing question, and then the Finish button. It takes a few seconds to finish.

gnc-fq-*, Finance::Quote: Perl

There are several tools available:

Eclipse Perl Integration (EPIC): EPIC 0.6.57 promoted to 'stable' (2015-01-11)
Perl Developement Tools
Perlipse, last: 1.2 in 2017?

Website htdocs: PHP

Install PHP Developement Tools (PDT)

Documentation, Translation, Account Templates: DocBook/XML

There are several XML editors and tools if you wish to work on the documentation or account chart templates.

E.g.

Docbook Editing and Processing for Eclipse (DEP4E) integrates Docbook XML and XSL, FOP, ...
Visual Editor for Xml and
Mylyn-Wikitext

should produce Docbook output and are under EPL.

Debugging

Linux Tools has a bunch of useful tools - if you are on Linux.

Bug Triage

In the category Team Synchronizing are inter alia a connector to bugzilla.

Working with Eclipse on GnuCash

With CMake & Ninja

From GnuCash 3.0 the program can no longer be built using autotools. CMake requires out of source builds. Eclipse has issues with out of source build as described in CMake Eclipse-CDT4-Generator. Further information on using Eclipse with Unix/Linux can be obtained from CMake Eclipse-UNIX Tutorial.

Use of version control and the ability to access the advanced C/C++ editing tools requires that separate projects need to be installed in Eclipse for editing source code and for the build-debug as described in the sources above.

The following options for the cmake command are useful:

-G"Eclipse CDT4 - Ninja" tells cmake to generate build project files for Eclipse including the ninja build files;
-DMAKE_BUILD_TYPE=debug enables debugging in Eclipse;
-DCMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT=TRUE creates a separate setof project files for source editing;
-DCMAKE_INSTALL_PREFIX=<path> sets the location where the built program will be installed

First a few directory definitions I'll use in the subsequent commands:

src: the source directory (your git clone of the gnucash repo),
build: the target directory in which to build gnucash and also where cmake will be run,
ws: the eclipse workspace,
install: where gnucash will be installed.

You should keep the 4 directories separate, none should be a subdirectory of any other. You can group the src, build and install directories in one base directory if it suits you. The Eclipse workspace directory normally lives under your home directory and can be separate from the other three directories but can be grouped with them as illustrated below:

clone gnucash into src

git clone https://github.com/Gnucash/gnucash src

make the build directory and ws directory
```
mkdir build ws install
```
cd into the build directory (I assume it's next to srcdir in basedir)
```
cd build/
```

run cmake like so:

cmake -DCMAKE_BUILD_TYPE=debug -G"Eclipse CDT4 - Ninja" -DCMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT=TRUE -DCMAKE_INSTALL_PREFIX=../install ../src

Note: Here it is assumed the build and src directories share the same parent directory. If not adjust the relative paths as needed.
Start eclipse and open/create ws workspace. Again, be sure build, src and install are not subdirectories of ws.
Once the workspace is open in Eclipse:
- Import the build project:
  1. Choose File->Import... from the menu;
  2. Select "General->Existing Projects into Workspace" as import option and click Next;
  3. As "root directory" choose build directory, make sure "Copy to workspace" is *not* checked and click Finish and wait for completion of the import;
- Import the source project:
  1. Choose File->Import... from the menu;
  2. Select "General->Existing Projects into Workspace" as import option and click Next;
  3. As "root directory" choose src directory, make sure "Copy to workspace" is *not* checked and click Finish and wait for completion of the import;

Eclipse is ready for gnucash development with cmake and ninja-build. The build will not write a single file in the source directory so you will be free to use all git commands there without risking to damage your eclipse project. It will create a .project file in the src directory. You should add this to your .gitignore file in src so that it is not transferred to the main gnucash repository.

I found some help on SO for the importing part: https://stackoverflow.com/questions/11645575/importing-a-cmake-project-into-eclipse-cdt#11665963. In between (2018-05-24) there is a follow up telling cmakes eclipse generator is unmaintained (worked last in Luna) and you should use https://marketplace.eclipse.org/content/cmake4eclipse instead.

from https://lists.gnucash.org/logs/2018/01/26.html#T14:00:38

With AutoTools

This section needs a review!

With Eclipse >= 3.6 ("Helios") and the CDT >= 7.x installed, using eclipse to develop gnucash is rather easy, but there are several ways possible:

use Eclipse only as IDE for editing and debugging and traditional command line tools for the rest
install and learn how to

use plugins for git

Tip: After you configured them, most git commands are in the project explorers context menu in the submenu Team. More commands like git clean are available after you switch from your default C/C++ perspective to the Git perspective. Just click the tabulators in the upper right corner after you once opened them via Window->Open Perspective.

configure the autotools chain in CDT to work the GnuCash way

If you wish to have a separate build directory disable in Window->Preferences->General->Workspace:Build automatically.

Tips: If you already checked out your project, you can

add the autotools property by File->New->Convert to a C/C++ Autotools Project,
for htdocs after that Configure->Add PHP Support,
If you wish to use a separate build dir, enter it in Properties->C/C++ Build->Builder Settings of your project,
to avoid getting your eclipse configuration files delete, when you run git clean -fdx, you might consider to run

git config --global alias.xclean "clean -xdf -e /.project -e /.cproject -e /.autotools -e /.settings"

and later call

git xclean

instead of git clean -fdx. The global switch is only required if you have more than one git repository.

disable the Relative Dates in Window->Preferences->Team->Git->History.

The quick way

Get a local working copy of gnucash from GitHub, as described on the Git page, as follows:

git clone https://github.com/Gnucash/gnucash.git gnucash
cd gnucash

Open a console and change into the directory of the newly created working copy. As described on Building, call

./autogen.sh
mkdir build        # Create the separate build directory
cd build
./configure

If that completed without error, start your Eclipse.
Choose File -> New -> Other... -> C++ -> "Makefile Project with Existing Code".
Choose some project name for yourself, and
choose the newly created working copy directory as "Existing Code Location".
Choose the "GNU Autotools Toolchain" as toolchain. Click Finish.

You can now edit the source code and also call "Build Project", and this will work as expected, i.e. it will result in the "gnucash" executable in src/bin.

Tip: After running file changing commands outside of eclipse you should refresh the respective directories in eclipse - press <F5> after selecting the respective project or subdirectory in the project explorer.

From Inside Eclipse

Notes:

It seems egit wants to separate the local repository (default: $HOME/git/<name>) from the workspace (default: $HOME/workspace/<name>) of a repository.
This section is still in development.
This is not only one way. If your way is shorter or better, feel free to improve this section. E.g. how to

(re-)run autogen.sh
sudo make install

Initial steps

To avoid annoying warnings, you should turn off automatic build:

Project -> Build automatically
Preferences->Run/Debug->Launching->"build (if required) before launching".

Clone the git project:
Warning! Don't use Eclipse's Git as long as Bugs to fix for proper symlink support is not fixed! We have at least a symlink in gnucash-docs/guide/ja/fdl-appendix.xml.
1. Switch to the project explorer view. Eventually you has to open Window->Open perspective->Other...->C/C++
2. Context menu-> or File->Import...->Projects from Git->Clone URI
  1. URI: https://github.com/Gnucash/gnucash.git for code,
    https://github.com/Gnucash/gnucash-docs documentation or
    
    https://github.com/Gnucash/gnucash-htdocs website.
    
    The remaining field will be autofilled or stay empty
  2. Branch Selection: (unchanged)
  3. Local Destination:
    Directory: <your local repository>
    
    Branch: master
  4. Select a wizard to use for importing projects:
    Import as general project (needs later Convert to C/C++ Autotools Project)
    
    In theory one could use the new project wizzard too, but that has no autotools option (in Eclipse 4.3)
Add autotools property, 2. or 3. alternative:
Currently htdocs is no autotools but a makefile project.
1. Select the Project Explorer
2. File->New->Convert to a C/C++ Autotools Project
  1. Convert to C/C++ Autotools Project
    Candidates: gnucash*
    
    Language: C++ for cutecash, C else
  2. Select a Configuration
    (no changes)
  3. Additional Project Settings
    (no changes)
3. File->New->C/C++->Makefileproject with existing Code
  1. Project Name: (as you like)
    
    Existing Code Location: (Local Destination from above)
    
    Languages: C for GnuCash, additional C++ for Cutecash (can be disabled for docs/htdocs)
    
    Toolchain for indexer Settings: GNU Autotools Toolchain
4. Instead of ./autogen.sh now Reconfigure Project from the context menu should work.
For a separate build directory:
Project->Properties->C/C++ Build->Builder Settings->Build directory: ${workspace_loc:/gnucash[-[ht]docs]}/build

Tip: You can define different build configurations e.g. for test and final build with Project->Properties->C/C++ Build->Builder Settings->Manage Configurations...
Configure Parameters:
Project->Properties->Autotools->Configure Settings->...

Most standard parameters can be set in the different sections, specific parameters belong to Advanced->Additional command-line options.

In case there is no Project->Properties->Autotools entry, execute File -> New -> Other... -> C/C++ -> Convert to a C/C++ Project and specify Project Type: GNU Autotools.
Further Customization of Eclipse
1. By default the Project Explorer hides a bunch of file, e.g. .* resulting in invisible .gitignore etc.
  Mars and newer
  
  Use the Navigator Window->Show View->Navigator instead of the Project Explorer.
  
  before
  
  Review inside it View Menu->Customize View->Filters to change that behavior.
Optional: Using Tasks
1. Tasks from Source Code
  By default Eclipse creates a task list from special strings like "FIXME", "TODO" or "XXX". You can adjust the list
  1. global: Window->Preferences->General->Editors->Task Tags or
  2. project specific: Project->Properties->...
2. Local Tasks: In the <Task list</tt> view create category as container and inside simple tasks
3. Link Bugzilla: In the <Task list</tt> view New Query->Add Task Repository->Bugzilla...
  URL: bugzilla.gnome.org
  
  Product: Gnucash
  
  Component: ...
  
  Note
  
  You should either only query a small amount of entries or in Window->Preferences->Mylyn->Tasks disable Synchronize with Repositories or increase the interval. Otherwise bugzilla thinks, you are running a DOS attack and will block you.

Programmers

Import include files: This is somehow ugly because you must set some of the directories you require. It seems, if you have
#include <glib/some_module> that is not associated with the

/usr/include/glib-2.0/some_module directory because of "glib"<>"glib-2.0".
To browse the .h-includefiles you must enter each missing folder to the include path:
- (global:) Window->Preferences->[FIXME]... or
- (project specific:) Project ->Properties -> Path and Symbols -> Includes or
- (older versions:) Project ->Properties -> C/C++ Build -> Tab "Tool Settings" -> Directories:
add the relevant include paths: e.g.
\usr\include\ # should fetch most includes for a linux build

C:\soft\gnome\include\gtk-2.0 # and so on for a Windows build

"${workspace_loc:/gnucash/lib/libqof/backend}" # only on complains,

${workspace_loc:/gnucash/src/app-utils} # etc.

You might wish to set the checkmarks for
Add to all configurations

Add to all languages

See also http://wiki.eclipse.org/CDT/User/FAQ#How_do_I_add_an_external_library_to_my_C.2B.2B_project.3F

(Cross-) Compiling for Windows

Project -> Properties -> C/C++ Build -> Tool Chain Editor
1. deselect "Show project types and toolsets only if they are supported by the platform"
2. Select Toolchain: "MinGW GCC"

Documenters and Translators

In Windows->Preferences->General->Editors->File Associations select *.xml and make your prefered editor the default, which opens on double clicking.
Windows->Preferences->XML->XML-Catalog allows you to specify the cataloges on your system, e.g. for Opensuse /etc/xml/catalog, additionally to the cataloges provided by your plugins. Now you can validate your work from the context menu point Validate.

GnuCash Developers

Committers have to do a few additional steps to get most benefits from Eclipse.

SSH Key Management

At first you need a SSH key to be able to commit. This can be done in

Window->Preferences->General->Network Connection->SSH2

[FIXME: Are there additional requirements for Windows?]

Send your pulic key to the Gnucash administrator to become well known.

There is also a password manager in

Window->Preferences->General->Security->Secure Storage

which can save your passphrase to unlock your SSH key. If you use this feature, you should set a master password on you password manager!

EGit

It seems EGit 3.7.0.20150226 can not configure a push url different from the fetch url, so you should do it in git:

git remote set-url --push origin git@code.gnucash.org:gnucash

Commiting

If you commit patches of other contributors, add their name and email address to the Author field in the commit dialog instead of yours.

References

eclipse CDT Autotools User Guide

Tips for your real work

Using the Bugzilla Connector =

The connector will keep you up to date in a configurable intervall. Because it is not always in the same state as the real bugzilla, it is less useful for submitting changes.

While you can apply patches by right click on the attachment, it is harder to get a compressed attachment like a zipped po file:

Open the Task in an editor window

right click on the attachement, save it in a temporary directory

While you right click in the project explorer in the right directory Import...->General->Archive file, select the file in your temporary directory.

Don't forget, to add it to the git index, if it is OK.

Edit

Some useful hints for editing:

CTRL+Shift+T: Open Element (function, variable, Macro etc)
CTRL+Shift+R: Open file
F3: open the definition of an element
CTRL+Alt+h: open call hierarchy

... and much more...

Make

Project->Build...
other targets: Project->Make Targets->Build <shift>+<F9>: (select one)

Debug

You can use eclipse as a debugging interface. The idea is to attach eclipse to the running gnucash process.

Run->Open Debug Dialog ->"C/C++ Attach to local app" -> New
Select C:\soft\gnucash\inst\bin\gnucash-bin.exe
You must specify the path to your source folder: Path mapping "../../../repos" to "C:\soft\gnucash\repos"
Now start gnucash as usual from inst/bin (ignore warnings about errors in workspace)
Launch your debugging configuration in eclipse
Select the process to attach to (gnucash-bin.exe)
The process will be interrupted. Try if you can browse to gnc_ui_start_event_loop. If not start over with the Source tab (see step 3).
Make sure you have put some breakpoints in and hit Continue
If a breakpoint is encountered you can step through with F6, F5 etc., inspect variables and so on.

@@ Line 275: / Line 275: @@
 ## Local Tasks: In the <Task list</tt> view create category as container and inside simple tasks
 ## Link Bugzilla: In the <Task list</tt> view New Query->Add Task Repository->Bugzilla...
-##: URL: {{BugURL}}
+##: URL: bugzilla.gnome.org
 ##: Product: Gnucash
 ##: Component: ...

Difference between revisions of "Eclipse"