Difference between revisions of "Eclipse"
(→Programmers: indent path) |
(→Programmers: review of include paths) |
||
Line 204: | Line 204: | ||
#:* (older versions:) Project ->Properties -> C/C++ Build -> Tab "Tool Settings" -> Directories: | #:* (older versions:) Project ->Properties -> C/C++ Build -> Tab "Tool Settings" -> Directories: | ||
#: add the relevant include paths: e.g. | #: add the relevant include paths: e.g. | ||
− | ::::"${workspace_loc:/gnucash/lib/libqof/backend}", | + | ::::\usr\include\ # should fetch most includes for a linux build |
− | ::::${workspace_loc:/gnucash/src/app-utils} etc. | + | ::::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. | ||
#:See also http://wiki.eclipse.org/CDT/User/FAQ#How_do_I_add_an_external_library_to_my_C.2B.2B_project.3F | #: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 ===== | ===== (Cross-) Compiling for Windows ===== |
Revision as of 19:21, 26 March 2015
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 www.eclipse.org/cdt/
Contents
Getting the Software
An Eclipse Package
From Eclipse.org
If Eclipse is unavailable by the package manager of your distribution or outdated, have a look at the Eclipses package comparision page and choose that, which covers most of your needs - obvisous it should include C/C+, because that contains the Autotools, which are used in the documentation, too. Then get it from the Eclipse download page.
A new main release is usually every year at the end of june available. As of july 2014 Version 4.4 "Luna" is recent. Usually the first letter of the code name will increase by one for each main release.
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
Add Plugin and Development Tool Software Sites in Eclipse
Note: In more recent version you can simply search Help->Eclipse Marketplace 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...
Name: Galileo Location: http://download.eclipse.org/releases/galileo
- 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, ...), which can be accessed by this package.
- choose Help --> Install New Software
- 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.)
- Scroll down to Programming Languages
- Choose Eclipse C/C++ Development Tools (Currently this installs version 6.0.0.200909110608)
- Click the Next button a few times, maybe answer a licensing question, and then the Finish button. It takes a few minutes to finish.
Suggested Plugins
Install eGit package if you wish to upate your repository from inside Eclipse
Eclipse's Git repository support is provided by the eGit package.
Optional Plugins
Reports etc.: Guile
- Install Schemeway
Prerequisite:
- JDT - Eclipse Java Developement Tools
- PDE - Plugin Developement Environment
If not already installed:
- Help -> Eclipse Marketplace or in old versions:
- Help --> Install New Software
- 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)
- Perl Developement Tools
- Perlipse
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.
- 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 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.
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, in contrast to svn egit wish to separate the local repository (default: $HOME/git/<name>) from the workspace (default: $HOME/workspace/<name>) of a repository.
- This section is still in developement.
- 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.
- Switch to the project explorer view. Eventually you has to open Window->Open perspective->Other...->C/C++
- Context menu-> or File->Import...->Projects from Git->Clone URI
- 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: trunk for svn based repositories, master else
- 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)
- URI: https://github.com/Gnucash/gnucash.git for code,
- Add autotools property, 2. or 3. alternative:
- Currently htdocs is no autotools but a makefile project.
- Select the Project Explorer
- File->New->Convert to a C/C++ Autotools Project
- Convert to C/C++ Autotools Project
- Candidates: gnucash*
- Language: C++ for cutecash, C else
- Select a Configuration
- (no changes)
- Additional Project Settings
- (no changes)
- Convert to C/C++ Autotools Project
- File->New->C/C++->Makefileproject with existing Code
- 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
- 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
- By default the Project Explorer hides a bunch of file, e.g. .* resulting in invisible .gitignore etc. Review inside it View Menu->Customize View->Filters 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: Window->Preferences->General->Editors->Task Tags or
- project specific: Project->Properties->...
- 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: 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.
- Tasks from Source Code
Programmers
- 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:
- (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.
- To browse the .h-includefiles you must enter each folder to the include path:
- \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.
(Cross-) Compiling for Windows
- Project -> Properties -> C/C++ Build -> Tool Chain Editor
- deselect "Show project types and toolsets only if they are supported by the platform"
- 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!
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.
SVN Commits only until 2014-02-01
- Download [git-update], a shell script to pull changes from github and fixup the branch references for git svn. Put it somewhere on your path, e.g. $HOME/bin.
- Edit it so that the path to the git's perl library directory (5th line) is correct for your installation or set $GITPERLLIB in your environment to point to the location of Git.pm or add that path to $PERL5LIB.
- Make it executable.
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.