Difference between revisions of "Eclipse"

From GnuCash
Jump to: navigation, search
(Required Plugins: Restructuring)
(With CMake & Ninja: cmake 3.27.1 deprecation)
 
(124 intermediate revisions by 5 users not shown)
Line 1: Line 1:
[http://www.eclipse.org/cdt/ Eclipse C/C++ Development Tooling] (CDT) can be used as a multi-feature editor and debugger for gnucash. Eclipse is a Java IDE but has a C/C++ project which has become quite mature. See [http://www.eclipse.org/cdt/ www.eclipse.org/cdt/]
+
[http://www.eclipse.org/cdt/ Eclipse C/C++ Development Tooling] (CDT) can be used as a multi-platform, multi-feature editor and debugger for GnuCash. Originally [http://www.eclipse.org Eclipse] has been a Java IDE, but got also a C/C++ project which has become quite mature.
  
 
= Getting the Software =
 
= Getting the Software =
 +
A new main release is usually every year at the end of june available. As of ''June 2018'' '''Version 4.8 "Photon"''' is recent. Usually the first letter of the code name will increase by one for each main release.
  
 
== An Eclipse Package ==
 
== An Eclipse Package ==
 +
As  usual, you should use the [[#Distribution_specific_Notes|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 ===
 
=== From Eclipse.org ===
If Eclipse is unavailable by the package manager of your distribution have a look at the [http://www.eclipse.org/downloads/compare.php Eclipses package comparision page] and choose that, which covers most of your needs - obvisous it should include C/C+. Then get it from the [http://www.eclipse.org/downloads/ Eclipse download page].
+
At first you should have a look at the [https://www.eclipse.org/downloads/compare.php 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. So the ''C Development Tools'' (CDT) or, depending on your other tasks, ''Scientific Computing'', the former Parallel Tools Platform, are a good base.
  
A new main release is usually every year at the end of june available.
+
==== With Eclipse Installer ====
 +
You might consider to use the '''Eclipse Installer''' ''Oomph Setup'', which can download, configure and later update your eclipse installations:
 +
* The announcement [https://www.eclipse.org/community/eclipse_newsletter/2014/may/article3.php Eclipse has Oomph] shows its user perspective.
 +
* The [https://wiki.eclipse.org/Eclipse_Installer Eclipse Installer in the Eclipse Wiki] has several links, also to download the stable and nightly versions.
 +
* The [https://www.eclipse.org/downloads/packages/installer Eclipse Installer download page].
 +
Steps:
 +
:* Download the appropriate version for your OS and architecture.
 +
::;Note: If you wish not to clutter up your $HOME directory with program files, run the following steps ''as admin'':<Syntaxhighlight lang="sh">su</Syntaxhighlight> As a normal user you could use $HOME instead of <tt>/opt</tt> in the following steps.
 +
:* extract it to e.g. <tt>/opt/eclipse/installer</tt>,
 +
:* run <Syntaxhighlight lang="sh">/opt/eclipse/installer/eclipse-inst</Syntaxhighlight>
 +
:: inside:
 +
::* Settings->Advanced mode - many customization dialogs are hidden behind buttons.
 +
::* 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.
  
=== With Synaptic under Ubuntu / Debian ===
+
==== Without Eclipse Installer ====
 +
 
 +
If you dislike ''Oomph Setup'' you can download and install everything manually from the [https://www.eclipse.org/downloads/eclipse-packages/ 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.  
 
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.  
Line 17: Line 40:
 
This problem with GTK may explain the redraw issues I describe in the steps below...?
 
This problem with GTK may explain the redraw issues I describe in the steps below...?
  
==== Install Eclipse ====
+
===== 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.
 
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.
Line 23: Line 46:
 
== Required Plugins ==
 
== Required Plugins ==
  
=== Add Plugin and Development Tool Software Sites in Eclipse ===
+
=== 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 <code>Help->Install New Software</code> panel has NOTHING in it until you add the appropriate URLs.
  
'''Note:''' In more recent version you can simply search Help->Eclipse Marketplace for your desired plugins.
+
In more recent version you can use ''Oomph Setup'' or simply search <tt>Help->Eclipse Marketplace</tt> for your desired plugins.
 
 
'''Note:''' Replace "Galileo" with with the name of your Eclipse release.
 
 
 
For some reason 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.  
 
  
 
* Add the Galileo repository: click '''Add...'''
 
* Add the Galileo repository: click '''Add...'''
Name: Galileo
+
:Name: Galileo
Location: http://download.eclipse.org/releases/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...'''
 
* Add the Schemeway repository: click '''Add...'''
 
  Name: Schemeway
 
  Name: Schemeway
Line 41: Line 62:
 
=== Install C/C++ if not already part of your package ===
 
=== 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'' (<tt>configure</tt>, <tt>make</tt>, ...), which can be accessed by this 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'' (<tt>configure</tt>, <tt>make</tt>, ...) or at least ''Gnu make'', which can be accessed by this package.
  
# choose Help --> Install New Software
+
# choose <tt>Help --> Install New Software</tt>
# In the Work with menu, choose Galileo. (For some odd reason, 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.)
+
# In the <tt>Work with</tt> 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
+
# Scroll down to ''Programming Languages''
# Choose Eclipse C/C++ Development Tools (Currently this installs version 6.0.0.200909110608)
+
# Choose ''Eclipse C/C++ Development Tools''
# Click the Next button a few times, maybe answer a licensing question, and then the Finish button. It takes a few minutes to finish.
+
# Click the <tt>Next</tt> button a few times, maybe confirm the license, and then the <tt>Finish</tt> button. It takes a few minutes to finish.
  
 
== Suggested Plugins ==
 
== Suggested Plugins ==
  
=== Install eGit package if you wish to upate your repository from inside Eclipse ===
+
=== eGit to use Git Commands in Eclipse ===
  
Eclipse's [[Git]] repository support is provided by the [http://www.eclipse.org/egit/ eGit package].
+
Eclipse's [[Git]] repository support is provided by the [http://www.eclipse.org/egit/ eGit package], which is already included in the '''Eclipse for C/C++ Developers''' bundles at least since for Eclipse 4.7 "Oxygen".
 +
 
 +
=== cmake4eclipse ===
 +
;Only for program and docs suggested: [https://github.com/15knots/cmake4eclipse 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
 +
:*<code>Help->Eclipse MarketPlace</code> and search for cmake4eclipse or
 +
:*use its update site: https://raw.githubusercontent.com/15knots/cmake4eclipse/master/releng/comp-update/
 +
:then click <code>Install</code>. Then choose menu <code>Help:Help Contents</code> and read the <code>CMake for CDT User Guide:Getting Started</code>.
 +
:;If you want to edit 'cmake files': [https://github.com/15knots/cmakeed CMake Editor] adds color coding and syntax completion for CMake files.
 +
:: Same Installation procedure as for cmake4eclipse.
  
 
== Optional Plugins ==
 
== Optional Plugins ==
  
=== Guile (Reports etc.): Install Schemeway ===
+
=== Bash Scripts ===
 +
Most projects have somewhere bash scripts. For them are several extensions available: '''Bash Editor''' or '''EasyShell'''.
  
==== Prerequisite:  
+
=== Reports etc.: Guile===
* JDT - Eclipse Java Developement Tools
+
* Install & adjust '''Dandelion''' (while it was written for Common LISP it needs testing) or
* PDE - Plugin Developement Environment ====
+
* Install [https://github.com/schemeway/SchemeScript/blob/master/README.md Schemeway] :
If not already installed:
+
:;Prerequisite:
# <tt>Help -> Eclipse Marketplace</tt> or in old versions:
+
:* JDT - Eclipse Java Developement Tools
## <tt> Help --> Install New Software</tt>  
+
:* PDE - Plugin Developement Environment
## In the Work with menu, choose Galileo or wharever the codename of your release is.
+
::If not already installed:
# Search JDT and mark it,
+
:# <tt>Help -> Eclipse Marketplace</tt> or in old versions:
# Search PDE and mark it,
+
:## <tt> Help --> Install New Software</tt>  
# Click the Next button ...
+
:## 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 ...
 +
:;Installation:
 +
:# (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.
  
==== Continue ====
+
:Eclipse 2019-12: See http://schemeway.github.io/SchemeScript/update-site
# (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.
 
  
=== htdocs: Install PHP Developement Tools (PDT) ===
+
=== 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?
  
=== DocBook/XML for Documentation, Translation, Account Templates ===
+
=== Website htdocs: PHP ===
 +
Install PHP Developement Tools (PDT)
 +
=== Translators of program or website: GTEd ===
 +
GetText Editor (GTEd) integrates an Editor for po files and gettext tools.
 +
;Warning: Don't use Version 1.8.0! It destroys plural forms on saving.
  
There are several '''XML editors and tools''' if you wish to work on the ''documentation'' or ''account chart templates''.
+
=== Documentation, Translation, Account Templates: DocBook/XML ===
: E.g.
 
*'''''V'''isual '''E'''ditor for '''X'''ml'' and
 
*''Mylyn-Wikitext''
 
should produce ''Docbook'' output and are under EPL.
 
  
=== Debugging ===
+
Since Eclipse 4.8 "Photon" '''XML editors and tools''' is already part of the basic bundles like CDT. If you wish to work on the ''documentation'', its translation or ''account chart templates'' they might be handy.
'''Linux Tools''' has a bunch of useful tools - if you are on Linux.
+
: If you are using an older version of eclipse, there have been several packages, e.g.
 +
:* Docbook Editing and Processing for Eclipse (DEP4E) integrates Docbook XML and XSL, FOP, ...
 +
:*'''''V'''isual '''E'''ditor for '''X'''ml'' and
 +
:*''Mylyn-Wikitext''
 +
:should produce ''Docbook'' output and are under EPL.
  
 
=== Bug Triage ===
 
=== Bug Triage ===
In the category '''Team Synchronizing''' are inter alia a connector to ''bugzilla''.
+
The '''Mylyn Task List''', which is already included in ''CDT'', has inter alia a connector to ''bugzilla''. It is accessible in the category '''Team Synchronizing'''.
  
 
= Working with Eclipse on GnuCash =
 
= Working with Eclipse on GnuCash =
 +
== With CMake & Ninja ==
 +
The Autotools support was abandoned for the
 +
:Program in 3.0 and
 +
:Documentation in 4.8.
 +
CMake requires out of source builds. Eclipse has issues with out of source build as described in [https://gitlab.kitware.com/cmake/community/wikis/doc/editors/Eclipse-CDT4-Generator CMake Eclipse-CDT4-Generator]. Further information on using Eclipse with Unix/Linux can be obtained from [https://gitlab.kitware.com/cmake/community/wikis/doc/editors/Eclipse-UNIX-Tutorial 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.
 +
 +
;Options: The following options for the cmake command are useful:
 +
:;General:
 +
::;-G"Eclipse CDT4 - Ninja"<ref name="CDT4">Since cmake version 3.27.1 you will get warned: <syntaxhighlight lang="Console">
 +
CMake Deprecation Warning:
 +
  Support for "Extra Generators" like
 +
 +
    Eclipse CDT4
 +
 +
  is deprecated and will be removed from a future version of CMake. IDEs may
 +
  use the cmake-file-api(7) to view CMake-generated project build trees.
 +
</syntaxhighlight> Search https://cmake.org/cmake/help/latest/manual/cmake-file-api.7.html cmake-file-api(7) for a solution and add it here.
 +
</ref>: tells cmake to generate build project files for Eclipse using the faster [[Build_Tools#Ninja|Ninja]] instead of the traditional [[Build_Tools#Make|Make]] in build files;
 +
::;-D_ECLIPSE_VERSION=4.26: Tell CMake your Eclipse version as Eclipse has no <tt>--version</tt> parameter. Get it from Eclipses <tt>About</tt>. This will silent the warning <tt>-- Eclipse version is set to 3.6 (Helios). Adjust CMAKE_ECLIPSE_VERSION if this is wrong.</tt>
 +
:::;Notes:
 +
::::# Original reason: CMake was unable to find Eclipse. Perhaps add Eclipses drectory to your PATH variable.
 +
::::# The name in the message is wrong.
 +
::;-DCMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT=TRUE: creates a separate set of project files for source editing;
 +
::;-DCMAKE_INSTALL_PREFIX=<path>: sets the location where the built program will be installed
 +
:;Program:
 +
::;-DCMAKE_BUILD_TYPE=debug: enables debugging in Eclipse;
 +
::;-DWITH_PYTHON=TRUE: enables Python bindings;
 +
:;Docs:
 +
::;-DWITH_MOBI=TRUE: enables Mobipocket document format;
 +
 +
=== Simple Setup ===
 +
First a few directory definitions I'll use in the subsequent commands:
 +
:;src: the source directory—the worktree of your git clone of the gnucash[-docs] 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 <syntaxhighlight lang="sh">git clone [-b master] https://github.com/Gnucash/gnucash src</syntaxhighlight>
 +
# make the build directory and ws directory <syntaxhighlight lang="sh">mkdir build ws install</syntaxhighlight>
 +
# cd into the build directory (I assume it's next to srcdir in basedir) <syntaxhighlight lang="sh">cd build/</syntaxhighlight>
 +
# run cmake like so: <syntaxhighlight lang="sh">cmake -DCMAKE_BUILD_TYPE=debug -G"Eclipse CDT4 - Ninja" -DCMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT=TRUE -DCMAKE_INSTALL_PREFIX=../install ../src</syntaxhighlight>
 +
#:; 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:
 +
#*# Choose <tt>File->Import…</tt> from the menu;
 +
#*# Select <tt>General->Existing Projects into Workspace</tt> as import option and click <code>Next</code>;
 +
#*# As <tt>root directory</tt> choose build directory, make sure <tt>Copy to workspace</tt> is ''not checked'', click <code>Finish</code>, and wait for completion of the import;
 +
#* Import the source project:
 +
#*# Choose <tt>File->Import…</tt> from the menu;
 +
#*# Select <tt>General->Existing Projects into Workspace</tt> as import option and click <code>Next</code>;
 +
#*# As <tt>root directory</tt> choose build directory, make sure <tt>Copy to workspace</tt> is ''not checked'', click <code>Finish</code>, 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 <tt>.project</tt> file in the src directory. You should add this to your <tt>.gitignore</tt> 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.
 +
 +
:;Source: {{URL:Lists}}logs/2018/01/26.html#T14:00:38
 +
 +
=== Setup with separate worktrees===
 +
The author stores all git repos below <tt>~/git/</tt> and the build directories below eclipses default <tt>~/eclipse-workspace/</tt> as <tt>$TEAM/$PROJECT/</tt> with
 +
:$TEAM = aqbanking, gnucash, …
 +
:$PROJECT = program, docs, …
 +
This will allow easier updates of all repos.
 +
Because rebuilding after switching branches is time consuming, separate worktrees for common branches are created.
 +
 +
There is currently still one issue: <tt>git clone --mirror</tt> seems to create a <tt>bare</tt> (write protected) repo.
 +
<syntaxhighlight lang="sh">
 +
PROJECT=gnucash/program
 +
REMOTE=https://github.com/Gnucash/gnucash
 +
OPTIONS='-DWITH_PYTHON=TRUE -DCMAKE_BUILD_TYPE=debug'
 +
# or:
 +
# PROJECT=gnucash/docs
 +
# REMOTE=https://github.com/Gnucash/gnucash-docs
 +
# OPTIONS='-DWITH_MOBI=TRUE'
 +
# To avoid 'sudo …' you can append ' -DCMAKE_INSTALL_PREFIX=~/.local' in both cases.
 +
BRANCHES=stable # or 'stable future' if future exists in the remote repo
 +
git clone --mirror ${REMOTE} ~/git/${PROJECT}
 +
# Usually you want to add more remotes like to enable PR creation:
 +
# git remote add mygh git@github.com:ME/gnucash.git
 +
# or to enable merging of translations:
 +
# git remote add weblate https://hosted.weblate.org/git/gnucash/gnucash
 +
# Core developers also want access to the primary repo:
 +
# git remote add upstream git@code.gnucash.org:gnucash
 +
# and their main contributors.
 +
# Check the result with:
 +
# git remote -v
 +
# Do not forget to update them:
 +
# git fetch --all
 +
# But that can also be done later in eclipse's git view.
 +
cd ~/git/${PROJECT}
 +
for b in ${BRANCHES}; do git worktree add $b $b; done; # path and branch for existing branches
 +
mkdir -p ~/eclipse-workspace/${PROJECT}
 +
cd ~/eclipse-workspace/${PROJECT}
 +
for b in ${BRANCHES}; do cmake -G"Eclipse CDT4 - Ninja" -D_ECLIPSE_VERSION=4.26 -DCMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT=TRUE -S ~/git/${PROJECT}/$b/ ${OPTIONS} $b
 +
done;
 +
eclipse
 +
# Now import the generated project file(s) below ~/eclipse-workspace/${PROJECT} resulting in /gnucash-debug@stable
 +
</syntaxhighlight>
 +
 +
== 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:  
 
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
 
* use Eclipse only as IDE for editing and debugging and traditional command line tools for the rest
 
* install and learn how to  
 
* install and learn how to  
:* use plugins for git or svn
+
:* use plugins for git
::'''Tip:''' After you configured them, their commands are in the ''project explorers'' context menu in the submenu ''Team''.
+
::'''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 <tt>Window->Open Perspective</tt>.
:* configure the autotools chain in CDT to work the GnuCash way
+
:* configure the respective build toolchain in CDT to work the GnuCash way
 
:: If you wish to have a separate build directory disable in <tt>Window->Preferences->General->Workspace:Build automatically</tt>.
 
:: If you wish to have a separate build directory disable in <tt>Window->Preferences->General->Workspace:Build automatically</tt>.
 
::'''Tips:''' If you already checked out your project, you can
 
::'''Tips:''' If you already checked out your project, you can
::* ''add the '''autotools''' property'' by <tt>File->New->Convert to a C/C++ Autotools Project</tt>,
+
::* for the '''program''': FixMe: TBD
::* for ''htdocs'' after that <tt>Configure->Add PHP Support</tt>,
+
::* for '''docs''': add the ''autotools'' property by <tt>File->New->Convert to a C/C++ Autotools Project</tt>,
::* If you wish to ''use a separate '''build dir''''', enter it in <tt>Properties->C/C++ Build->Builder Settings</tt> of your project.
+
::* for '''htdocs''': add the ''makefile'' property by <tt>File->Import->C/C++->Existing code as Makefile Project</tt>
 +
::: after that <tt>Configure->Add PHP Support</tt>,
 +
::* If you wish to ''use a separate '''build dir''''', enter it in the <tt>Properties->C/C++ Build->Builder Settings</tt> tab of your project,
 +
::* If your Eclipse project workspace is your git source directory, to avoid getting your eclipse configuration files delete, when you run <tt>git clean -fdx</tt>, you might consider to run <Syntaxhighlight lang="sh">
 +
git config --global alias.xclean "clean -xdf -e /.project -e /.cproject -e /.autotools -e /.settings"</Syntaxhighlight>
 +
::: and later call <Syntaxhighlight lang="sh">
 +
git xclean</Syntaxhighlight>
 +
::: instead of <code>git clean -fdx</code>. The global switch is only required if you have more than one git repository.
 +
::* ''disable'' the '''Relative Dates''' in <code>Window->Preferences->Team->Git->History</code>.
  
== The quick way ==
+
=== The quick way ===
* Get a local working copy of gnucash from SVN, as described on the [[SVN]] page, as follows:
+
* Get a local working copy of gnucash from GitHub, as described on the [[Git]] page, as follows: <Syntaxhighlight lang="sh">
git clone https://github.com/Gnucash/gnucash.git gnucash
+
git clone https://github.com/Gnucash/gnucash.git gnucash
cd gnucash
+
cd gnucash
* Open a console and change into the directory of the newly created working copy. As described on [[Building]], call
+
</Syntaxhighlight>
./autogen.sh
+
* Open a console and change into the directory of the newly created working copy. As described on [[Building]], call <Syntaxhighlight lang="sh">
mkdir build        # Create the separate build directory
+
./autogen.sh
cd build
+
mkdir build        # Create the separate build directory
./configure
+
cd build
 +
./configure
 +
</Syntaxhighlight>
 
* If that completed without error, start your Eclipse.  
 
* If that completed without error, start your Eclipse.  
 
* Choose File -> New -> Other... -> C++ -> "Makefile Project with Existing Code".
 
* Choose File -> New -> Other... -> C++ -> "Makefile Project with Existing Code".
Line 123: Line 288:
 
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.
 
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.
  
= Getting eclipse 3.x to work with gnucash =
+
'''Tip:''' After running file changing commands outside of eclipse you should <tt>refresh</tt> the respective directories in eclipse - press <F5> after selecting the respective project or subdirectory in the ''project explorer''.
Precondition: Check out the sources. It might be best to make sure first that gnucash compiles and installs, before starting over with eclipse.
+
 
# Download Eclipse IDE for C/C++ Developers from [http://www.eclipse.org/downloads/] and extract to some folder
+
=== From Inside Eclipse ===
# Start eclipse
+
'''Notes:'''
# Create a new C-Project: File->New -> Empty C-Project:  
+
*It seems older versions of egit wants to separate the local repository (default: $HOME/git/<name>) from the workspace (default: $HOME/workspace/<name>) of a repository.
## Location: enter the path to the existing source folder (e.g. C:\soft\gnucash\repos)
+
*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 <tt>autogen.sh</tt>
 +
:* <tt>'''sudo''' make install</tt>
 +
==== Initial steps ====
 +
:To avoid annoying warnings, you should turn off ''automatic build'':
 +
::* Project -> Build automatically
 +
::* Preferences->Run/Debug->Launching->"build (if required) before launching".
 +
:;Note: There are several way to create/import a project:
 +
::You can also import existing projects from your file system and add missing properties.
 +
# Clone the '''git''' project:
 +
#:'''Warning!''' Be cautious to use Eclipse's Git as long as [https://bugs.eclipse.org/bugs/show_bug.cgi?id=429304 Bugs to fix for proper symlink support] is not fixed! We have at least a symlink in gnucash-docs/guide/ja/fdl-appendix.xml.
 +
#: There might be other issues, where egit is behind git.
 +
##Switch to the project explorer view. Eventually you has to open <tt>Window->Open perspective->Other...->C/C++</tt>
 +
##<tt>Context menu-></tt> or <tt>File->Import...->Projects from Git->Clone URI</tt>
 +
###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
 +
###Branch Selection: (unchanged)
 +
###Local Destination:
 +
###:Directory: <your local repository>
 +
###:Branch: master
 +
###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 wizard too, but that has no autotools option (in Eclipse 4.3)
 +
# '''Add''' missing '''properties''' like used toolchain: The complete GNU Toolchain (Gnu Make, Autotools, ...) is part of C/C++ . Depending on the project different ''toolchains'' are used and should be '''add'''ed as '''property''':
 +
##Select the Project Explorer
 +
#* Program: '''CMake''' by ''Cmake4eclipse'':
 +
## Add the <tt>C/C++</tt> nature with type <tt>Executable</tt> (not Autotools or Makefile),
 +
## In <tt>Project Properties</tt>
 +
### <tt>C/C++ Build</tt>: for ''every configuration''
 +
#### Tab <tt>Builder Settings->Generate Makefiles automatically</tt>: checked,
 +
#### Tab <tt>Behaviour->Enable parallel build</tt>: (suggested),
 +
#### Node <tt>Tool Chain Editor->Current Builder</tt>: '''CMake Builder (portable)''',
 +
#### Node <tt>CMake->Host OS Overrides->Buildscript generator (-G)</tt>: '''Ninja''' (suggested).
 +
#* Documentation: '''Autotools'''
 +
##<tt>File->New->Convert to a C/C++ Autotools Project</tt>
 +
###Convert to C/C++ Autotools Project
 +
###:Candidates: gnucash-docs
 +
###:Language: (Does not matter, XML is what we want)
 +
###Select a Configuration
 +
###: (no changes)
 +
###Additional Project Settings
 +
###: (no changes)
 +
#* Website: is a simple Gnu Make aka '''makefile''' project.
 +
##<tt>File->New->Convert to a C/C++ Project</tt>
 +
##:Candidates: gnucash-htdocs
 +
##:Convert to C or C++: (doesn't matter)
 +
##:Specify project type: enable
 +
##:Project Type: Makefile Project
 +
##:Toolchains: --Other Toolchain --
 +
## <tt>Context menu->Configure->Convert to PHP Project</tt>
 +
# For a '''separate build directory''':
 +
#:<tt>Project->Properties->C/C++ Build->Builder Settings->Build directory: ''${workspace_loc:/gnucash[-[ht]docs]}/build''</tt>
 +
#:'''Tip:''' You can define different build configurations e.g. for test and final build with <tt>Project->Properties->C/C++ Build->Builder Settings->Manage Configurations...</tt>
 +
# Autotools-Projects only:
 +
## Instead of running <code>./autogen.sh</code> now use <tt>Reconfigure Project</tt> from the context menu.
 +
## '''Configure''' Parameters:
 +
##:<tt>Project->Properties->Autotools->Configure Settings-></tt>...
 +
##:Most standard parameters can be set in the different sections, specific parameters belong to <tt>Advanced->Additional command-line o#ptions</tt>.
 +
# '''Further Customization''' of Eclipse
 +
## By default the Project Explorer hides a bunch of file, e.g. .* resulting in invisible .gitignore etc.
 +
##;Eclipse Mars (4.5) and newer: Use the ''Navigator'' <tt>Window->Show View->Navigator</tt> instead of the ''Project Explorer''.
 +
##;before: Review inside it <tt>View Menu->Customize View->Filters</tt> to change that behavior.
 +
# Optional: Using '''Tasks'''
 +
## Tasks from Source Code
 +
##: By default Eclipse creates a task list from special strings like "FIXME", "TODO" or "XXX". You can adjust the list
 +
### ''global'': <tt>Window->Preferences->General->Editors->Task Tags</tt> or
 +
### ''project specific'': Project->Properties->...
 +
## Local Tasks: In the <tt>Task list</tt> view create a category as container and
 +
##: inside add simple tasks for personal use.
 +
## Link Bugzilla: In the <tt>Task list</tt> view New Query->Add Task Repository->Bugzilla...
 +
##: Server: {{BugServer}}
 +
##: Label: GnuCash (or similar)
 +
<!-- I currently do no longer see this part: ##: Product: <select one from {{BugURL}}/describecomponents.cgi>
 +
##: Component: ... -->
 +
##;Note:You should either only query a small amount of entries or in <tt>Window->Preferences->Mylyn->Tasks</tt> disable <tt>Synchronize with Repositories</tt> 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
 +
#:<code>#include <glib/some_module></code> that is not associated with the
 +
#:<tt>/usr/include/glib-3.0/some_module</tt> directory because of "glib"<>"glib-3.0".
 +
#:To browse the .h include files you must enter each missing folder to the include path:
 +
#:* (global:) <tt>Window->Preferences->[FIXME]... </tt> or
 +
#:* (project specific:) <tt>Project ->Properties -> Path and Symbols -> Includes</tt> or
 +
#:* (older versions:) Project ->Properties -> C/C++ Build -> Tab "Tool Settings" -> Directories:
 +
#: add the relevant include paths: e.g.  
 +
#:::<tt>\usr\include\</tt>  # should fetch most includes for a linux build
 +
#:::<tt>C:\soft\gnome\include\gtk-3.0</tt>  # and so on for a Windows build
 +
#:::<tt>${workspace_loc:/gnucash/lib/libqof/backend}</tt>  # only on complains,
 +
#:::<tt>${workspace_loc:/gnucash/src/app-utils}</tt>  # etc.
 +
#:You might consider 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 ======
 +
# <tt>Project -> Properties -> C/C++ Build -> Tool Chain Editor</tt>
 
## deselect "Show project types and toolsets only if they are supported by the platform"
 
## deselect "Show project types and toolsets only if they are supported by the platform"
 
## Select Toolchain: "MinGW GCC"
 
## Select Toolchain: "MinGW GCC"
# Import include files: This is somehow ugly because you must set each directory you require.
 
#:To browse the .h-includefiles you must enter each folder to the include path:
 
#:* Project ->Properties -> C/C++ Build -> Tab "Tool Settings" -> Directories: add the relevant include paths: e.g. "${workspace_loc:/gnucash/lib/libqof/backend}", ${workspace_loc:/gnucash/src/app-utils} etc. and C:\soft\gnome\include\gtk-2.0 and so on
 
#:See also http://wiki.eclipse.org/CDT/User/FAQ#How_do_I_add_an_external_library_to_my_C.2B.2B_project.3F
 
  
There is much more support available: 
+
===== Documenters and Translators =====
* [http://www.eclipse.org/egit/ Plugin for Git].
+
* In <tt>Windows->Preferences->General->Editors->'''File Associations'''</tt> select <tt>*.xml</tt> and make your prefered editor the default, which opens on double clicking.
* '''Scheme editor''' plugin: [http://schemeway.sourceforge.net schemeway] (You will also have to install "Eclipse '''Java Development Tools'''" and "Eclipse '''Plug-in Development Environment'''"  via Help->Software Updates->Available Software-><eclipse version codename> e.g. Ganymede.)
+
* <tt>Windows->Preferences->XML->'''XML-Catalog'''</tt> allows you to specify the cataloges on your system, e.g. for Opensuse <tt>/etc/xml/catalog</tt>, additionally to the cataloges provided by your plugins. Now you can validate your work from the context menu point <tt>Validate</tt>.
 +
 
 +
===== 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 <code>Window->Preferences->General->Network Connection->SSH2</code>
 +
[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 <code>Window->Preferences->General->Security->Secure Storage</code>,
 +
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:
 +
<Syntaxhighlight lang="sh">
 +
git remote set-url --push origin git@code.gnucash.org:gnucash
 +
</Syntaxhighlight>
 +
====== 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 =====
 +
[http://wiki.eclipse.org/CDT/Autotools/User_Guide 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 <tt>Import...->General->Archive file</tt>, select the file in your temporary directory.
 +
:Don't forget, to add it to the git index, if it is OK.
  
= Edit =
+
=== Edit ===
 
Some useful hints for editing:
 
Some useful hints for editing:
 
* CTRL+Shift+T: Open Element (function, variable, Macro etc)
 
* CTRL+Shift+T: Open Element (function, variable, Macro etc)
Line 148: Line 440:
 
... and much more...
 
... and much more...
  
= Build (not to build) =
+
=== Make ===
Eclipse won’t be a good help for building. You are always faster if you make_install in a shell window for the directory tree you were editing. To avoid annoying warnings, you should turn off automatic build:
+
*<tt>Project->Build</tt>...
* Project -> Build automatically
+
*other targets: <tt>Project->Make Targets->Build <shift>+<F9></tt>: (select one)
* Preferences->Run/Debug->Launching->"build (if required) before launching".
 
  
= Debug =
+
=== Debug ===
 
You can use eclipse as a debugging interface. The idea is to attach eclipse to the running gnucash process.
 
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
 
# Run->Open Debug Dialog ->"C/C++ Attach to local app" -> New
Line 164: Line 455:
 
# Make sure you have put some breakpoints in and hit Continue
 
# 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.
 
# If a breakpoint is encountered you can step through with F6, F5 etc., inspect variables and so on.
 +
 +
;Debug Info: Make sure you installed the appropriate -dev (or -'''devel''') '''package'''s. If you run gnucash once under gdb instead of Eclipse, gdb will tell you which command to run to install all missing debug info. It may be more than you need though.
 +
 +
----
 +
[[Category: IDE]]

Latest revision as of 15:51, 18 August 2023

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 2018 Version 4.8 "Photon" 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. So the C Development Tools (CDT) or, depending on your other tasks, Scientific Computing, the former Parallel Tools Platform, are a good base.

With Eclipse Installer

You might consider to use the Eclipse Installer Oomph Setup, which can download, configure and later update your eclipse installations:

Steps:

  • Download the appropriate version for your OS and architecture.
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:
  • Settings->Advanced mode - many customization dialogs are hidden behind buttons.
  • 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.

Without Eclipse Installer

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 Gnu make, which can be accessed by this package.

  1. choose Help --> Install New Software
  2. 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.)
  3. Scroll down to Programming Languages
  4. Choose Eclipse C/C++ Development Tools
  5. 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 at least since for Eclipse 4.7 "Oxygen".

cmake4eclipse

Only for program and docs suggested
cmake4eclipse automates a number of tasks normally involved in setting up out of source builds with CMake in Eclipse:
  1. leave eclipse workbench;
  2. manually fire up a command-line shell;
  3. manually create a directory for the out-of-source-build;
  4. manually change the CWD to that directory
  5. manually invoke cmake, telling it to generate build scripts, which kind of build scripts you want and where source source files live;
  6. 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
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

Bash Scripts

Most projects have somewhere bash scripts. For them are several extensions available: Bash Editor or EasyShell.

Reports etc.: Guile

  • Install & adjust Dandelion (while it was written for Common LISP it needs testing) or
  • Install Schemeway :
Prerequisite
  • JDT - Eclipse Java Developement Tools
  • PDE - Plugin Developement Environment
If not already installed:
  1. 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.
  2. Search JDT and mark it,
  3. Search PDE and mark it,
  4. Click the Next button ...
Installation
  1. (You may already be here) Help --> Install New Software
  2. In the Work With menu, choose Schemeway.
  3. Put an * or Enter or something in the filter text field to make the list show up.
  4. Choose "SchemeWay Feature" (Currently this installs version 1.2.15)
  5. Click the Next button a few times, maybe answer a licensing question, and then the Finish button. It takes a few seconds to finish.
Eclipse 2019-12: See http://schemeway.github.io/SchemeScript/update-site

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)

Translators of program or website: GTEd

GetText Editor (GTEd) integrates an Editor for po files and gettext tools.

Warning
Don't use Version 1.8.0! It destroys plural forms on saving.

Documentation, Translation, Account Templates: DocBook/XML

Since Eclipse 4.8 "Photon" XML editors and tools is already part of the basic bundles like CDT. If you wish to work on the documentation, its translation or account chart templates they might be handy.

If you are using an older version of eclipse, there have been several packages, 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.

Bug Triage

The Mylyn Task List, which is already included in CDT, has inter alia a connector to bugzilla. It is accessible in the category Team Synchronizing.

Working with Eclipse on GnuCash

With CMake & Ninja

The Autotools support was abandoned for the

Program in 3.0 and
Documentation in 4.8.

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.

Options
The following options for the cmake command are useful:
General
-G"Eclipse CDT4 - Ninja"[1]
tells cmake to generate build project files for Eclipse using the faster Ninja instead of the traditional Make in build files;
-D_ECLIPSE_VERSION=4.26
Tell CMake your Eclipse version as Eclipse has no --version parameter. Get it from Eclipses About. This will silent the warning -- Eclipse version is set to 3.6 (Helios). Adjust CMAKE_ECLIPSE_VERSION if this is wrong.
Notes
  1. Original reason: CMake was unable to find Eclipse. Perhaps add Eclipses drectory to your PATH variable.
  2. The name in the message is wrong.
-DCMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT=TRUE
creates a separate set of project files for source editing;
-DCMAKE_INSTALL_PREFIX=<path>
sets the location where the built program will be installed
Program
-DCMAKE_BUILD_TYPE=debug
enables debugging in Eclipse;
-DWITH_PYTHON=TRUE
enables Python bindings;
Docs
-DWITH_MOBI=TRUE
enables Mobipocket document format;

Simple Setup

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

src
the source directory—the worktree of your git clone of the gnucash[-docs] 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:

  1. clone gnucash into src
    git clone [-b master] https://github.com/Gnucash/gnucash src
    
  2. make the build directory and ws directory
    mkdir build ws install
    
  3. cd into the build directory (I assume it's next to srcdir in basedir)
    cd build/
    
  4. 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.
  5. Start eclipse and open/create ws workspace. Again, be sure build, src and install are not subdirectories of ws.
  6. 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, 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 build directory, make sure Copy to workspace is not checked, 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.

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

Setup with separate worktrees

The author stores all git repos below ~/git/ and the build directories below eclipses default ~/eclipse-workspace/ as $TEAM/$PROJECT/ with

$TEAM = aqbanking, gnucash, …
$PROJECT = program, docs, …

This will allow easier updates of all repos. Because rebuilding after switching branches is time consuming, separate worktrees for common branches are created.

There is currently still one issue: git clone --mirror seems to create a bare (write protected) repo.

PROJECT=gnucash/program
REMOTE=https://github.com/Gnucash/gnucash
OPTIONS='-DWITH_PYTHON=TRUE -DCMAKE_BUILD_TYPE=debug'
# or:
# PROJECT=gnucash/docs
# REMOTE=https://github.com/Gnucash/gnucash-docs
# OPTIONS='-DWITH_MOBI=TRUE'
# To avoid 'sudo …' you can append ' -DCMAKE_INSTALL_PREFIX=~/.local' in both cases.
BRANCHES=stable # or 'stable future' if future exists in the remote repo
git clone --mirror ${REMOTE} ~/git/${PROJECT}
# Usually you want to add more remotes like to enable PR creation:
# git remote add mygh git@github.com:ME/gnucash.git
# or to enable merging of translations:
# git remote add weblate https://hosted.weblate.org/git/gnucash/gnucash
# Core developers also want access to the primary repo:
# git remote add upstream git@code.gnucash.org:gnucash
# and their main contributors.
# Check the result with:
# git remote -v
# Do not forget to update them:
# git fetch --all
# But that can also be done later in eclipse's git view. 
cd ~/git/${PROJECT}
for b in ${BRANCHES}; do git worktree add $b $b; done; # path and branch for existing branches
mkdir -p ~/eclipse-workspace/${PROJECT}
cd ~/eclipse-workspace/${PROJECT}
for b in ${BRANCHES}; do cmake -G"Eclipse CDT4 - Ninja" -D_ECLIPSE_VERSION=4.26 -DCMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT=TRUE -S ~/git/${PROJECT}/$b/ ${OPTIONS} $b
done;
eclipse
# Now import the generated project file(s) below ~/eclipse-workspace/${PROJECT} resulting in /gnucash-debug@stable

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 respective build toolchain 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
  • for the program: FixMe: TBD
  • for docs: add the autotools property by File->New->Convert to a C/C++ Autotools Project,
  • for htdocs: add the makefile property by File->Import->C/C++->Existing code as Makefile Project
after that Configure->Add PHP Support,
  • If you wish to use a separate build dir, enter it in the Properties->C/C++ Build->Builder Settings tab of your project,
  • If your Eclipse project workspace is your git source directory, 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 older versions of 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".
Note
There are several way to create/import a project:
You can also import existing projects from your file system and add missing properties.
  1. Clone the git project:
    Warning! Be cautious to 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.
    There might be other issues, where egit is behind git.
    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 wizard too, but that has no autotools option (in Eclipse 4.3)
  2. Add missing properties like used toolchain: The complete GNU Toolchain (Gnu Make, Autotools, ...) is part of C/C++ . Depending on the project different toolchains are used and should be added as property:
    1. Select the Project Explorer
    • Program: CMake by Cmake4eclipse:
    1. Add the C/C++ nature with type Executable (not Autotools or Makefile),
    2. In Project Properties
      1. C/C++ Build: for every configuration
        1. Tab Builder Settings->Generate Makefiles automatically: checked,
        2. Tab Behaviour->Enable parallel build: (suggested),
        3. Node Tool Chain Editor->Current Builder: CMake Builder (portable),
        4. Node CMake->Host OS Overrides->Buildscript generator (-G): Ninja (suggested).
    • Documentation: Autotools
    1. File->New->Convert to a C/C++ Autotools Project
      1. Convert to C/C++ Autotools Project
        Candidates: gnucash-docs
        Language: (Does not matter, XML is what we want)
      2. Select a Configuration
        (no changes)
      3. Additional Project Settings
        (no changes)
    • Website: is a simple Gnu Make aka makefile project.
    1. File->New->Convert to a C/C++ Project
      Candidates: gnucash-htdocs
      Convert to C or C++: (doesn't matter)
      Specify project type: enable
      Project Type: Makefile Project
      Toolchains: --Other Toolchain --
    2. Context menu->Configure->Convert to PHP Project
  3. 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...
  4. Autotools-Projects only:
    1. Instead of running ./autogen.sh now use Reconfigure Project from the context menu.
    2. 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 o#ptions.
  5. Further Customization of Eclipse
    1. By default the Project Explorer hides a bunch of file, e.g. .* resulting in invisible .gitignore etc.
      Eclipse Mars (4.5) 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.
  6. 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 view create a category as container and
      inside add simple tasks for personal use.
    3. Link Bugzilla: In the Task list view New Query->Add Task Repository->Bugzilla...
      Server: bugs.gnucash.org
      Label: GnuCash (or similar)
      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
  1. 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-3.0/some_module directory because of "glib"<>"glib-3.0".
    To browse the .h include files 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-3.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 consider 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
  1. 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.

  1. Run->Open Debug Dialog ->"C/C++ Attach to local app" -> New
  2. Select C:\soft\gnucash\inst\bin\gnucash-bin.exe
  3. You must specify the path to your source folder: Path mapping "../../../repos" to "C:\soft\gnucash\repos"
  4. Now start gnucash as usual from inst/bin (ignore warnings about errors in workspace)
  5. Launch your debugging configuration in eclipse
  6. Select the process to attach to (gnucash-bin.exe)
  7. 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).
  8. Make sure you have put some breakpoints in and hit Continue
  9. If a breakpoint is encountered you can step through with F6, F5 etc., inspect variables and so on.
Debug Info
Make sure you installed the appropriate -dev (or -devel) packages. If you run gnucash once under gdb instead of Eclipse, gdb will tell you which command to run to install all missing debug info. It may be more than you need though.

  1. Since cmake version 3.27.1 you will get warned:
    CMake Deprecation Warning:
      Support for "Extra Generators" like
    
        Eclipse CDT4
    
      is deprecated and will be removed from a future version of CMake. IDEs may
      use the cmake-file-api(7) to view CMake-generated project build trees.
    
    Search https://cmake.org/cmake/help/latest/manual/cmake-file-api.7.html cmake-file-api(7) for a solution and add it here.