Difference between revisions of "Development"

From GnuCash
Jump to: navigation, search
(Move content from Contributing to GnuCash#Code to make it easier to expand)
 
(See also: add docs/Maint)
(25 intermediate revisions by 7 users not shown)
Line 1: Line 1:
= Developing GnuCash Code =
+
= Overview =
 +
GnuCash is written principally in [http://en.wikipedia.org/wiki/C_(programming_language) C]. A [http://www.gnu.org/software/guile/ Guile] interpreter is built in and parts of Gnucash--principally reports, but also parts of the user configuration, file import, and other small parts--are in Scheme.
 +
The C API is wrapped for Guile access with [http://www.swig.org/ SWIG]; Python wrappers can be created with a configure option.
  
* See [[Building]] for more details on how to build the program from source code.
+
The GUI is built with [http://www.gtk.org GTK+] version 2.24.
* See [[Development_Process]] for
 
* We are in the last stage of converting source code version control from  [http://subversion.tigris.org/ Subversion] to [http://git-scm.com/ Git], which we intend to complete shortly after releasing GnuCash version 2.6 at the end of 2013. New contributors should follow the git [[Git instructions]] for cloning the repository and preparing patches. Any current developers still using subversion should switch to git for most of their work as soon as possible in order to be ready for the final conversion.
 
  
* Please subscribe to the [[Mailing Lists]] and introduce yourself to the development team. You can also hang out on [[IRC]], but that isn't required.
+
We're supporting two build systems [http://en.wikipedia.org/wiki/GNU_build_system GNU autotools] and [https://cmake.org CMake]. Understanding this complex system isn't generally necessary for fixing simple bugs, but more complex work will. Here's an [http://www.sourceware.org/autobook/autobook/autobook_toc.html excellent autotools tutorial] and a [https://cmake.org/cmake-tutorial/ short CMake one].
* Read the two files [http://svn.gnucash.org/trac/browser/gnucash/trunk/HACKING HACKING] and [http://svn.gnucash.org/trac/browser/gnucash/trunk/README.svn README.svn].
 
* Now try your hand at one of the outstanding bugs in [[Bugzilla]], something from the [[WishList]] or your own pet peeve. Please consider adding unit tests (see [[Testing]]) for features where applicable.
 
** The '''coding style''' was last discussed on the [http://lists.gnucash.org/pipermail/gnucash-devel/2009-August/026121.html gnucash-devel ML].
 
** If your code will contain '''textual output for the user''', have a look at [[Translation#Tips_for_Developers | Translation: Tips for Developers]].
 
** If your code adds or changes some functionality, do not forget the '''documentation''':
 
*** We use [http://www.stack.nl/~dimitri/doxygen DOxygen] to document the sources, including the C API. Details about our use are on the [[Doxygen]] wiki page.
 
*** Try to keep the ''README files'' and that in ''src/doc'' up to date.
 
*** Update the relevant sections in '''help''' and '''guide'''.
 
* Once you have your changes written and well tested - <tt>make check</tt> will run a bunch of tests -, you'll want to submit it so that someone with commit privilege can add it to the official sources. First, make a patch:
 
** [[Git]] is best. See the [[Git#Patches|patch instructions]].
 
**If you're using Subversion, you can create a patch with
 
  svn diff
 
** If there's already a bug about it in [[Bugzilla]], just attach the patch to the bug. Be sure to check the "patch" checkbox on the attachment form.
 
** If there isn't a bug already (be sure to search!), it really works best if you create a new one to attach your patch to.
 
*** Describe the problem or improvement that your patch addresses in the initial comment.
 
*** If you use Git, open the bug ''before'' you make your patch so that you can include the bug number in the commit message.
 
** If there isn't a bug already and the patch is trivial, you can send it to the '''gnucash-devel''' mailing list (though we really do prefer patches to go to [[Bugzilla]]).
 
*** Please attach the patch to the email, don't inline it in the message, even if you used git format-patch and it made a pretty email for you.
 
  
== Tools ==
+
We use [http://www.stack.nl/~dimitri/doxygen Doxygen] to document the sources, including the C API. Details about our use are on the [[Doxygen]] wiki page. The ''Help Manual'' and ''Concepts Guide'' are formatted using [http://www.docbook.org/ DocBook], an SGML markup language which enables us to publish them in several formats. Note that these documents have a separate [https://github.com/Gnucash/gnucash-docs repository].
 +
 
 +
== Object Orientation ==
 +
Most of the code is written in an object-oriented style. Some of it uses [http://en.wikipedia.org/wiki/GObject GObject], some uses a home-grown GObject-like system called QofObject, and some just does what GObject does in straight C. Understanding how to use that is an important skill to developing for GnuCash.
 +
The next development cycle will include migrating those parts of Gnucash other than the GUI to [http://isocpp.org/ C++]; see our [[C++]] page for details and resources. We are deferring updating the GUI either to Gtk+-3 or some other framework for at least another development cycle.
 +
 
 +
= What We Need Help On =
 +
* Patches to fix [[Bugzilla|bugs]] are always a appreciated. It's an excellent way to get familiar with the code base and to introduce yourself to the team.
 +
* If you prefer to dive in at the deep end, have a look at the development team's [[Roadmap|long-term plans]].
 +
= Preliminaries =
 +
Please subscribe to the [[Mailing Lists]] and introduce yourself to the development team. Some of the team also hang out on [[IRC]] so you can interact more directly.
 +
 
 +
Read the two files [http://svn.gnucash.org/trac/browser/gnucash/trunk/HACKING HACKING] and [http://svn.gnucash.org/trac/browser/gnucash/trunk/README.svn README.svn]
 +
 
 +
Look through the [http://svn.gnucash.org/docs/HEAD/ API documentation].
 +
 
 +
= Getting Sources and Building =
 +
You can follow the git [[Git|instructions]] for cloning the repository and preparing patches.
 +
 
 +
Build instructions for various platforms are described or linked at [[Building]].
 +
 
 +
= Coding Guidelines =
 +
* Please try to develop according to [http://en.wikipedia.org/wiki/Test-driven_development Test Driven Development] principles, following our [[Testing]] guidelines.
 +
* Please follow our [[CodingStandard| coding style]].
 +
* If your code will contain '''textual output for the user''', have a look at [[Translation#Tips_for_Developers | Translation: Tips for Developers]] and configuration [[Settings Wording]].
 +
* Be sure that <tt>make check</tt> passes before preparing your patch or pushing your commit.
 +
 
 +
= Documentation =
 +
If your code adds or changes some functionality, do not forget the '''documentation'''.
 +
 
 +
* Make sure that global (i.e. not static) functions are documented with [[Doxygen]]-formatted comments.
 +
* Try to keep the ''README files'' and that in ''src/doc'' up to date.
 +
* [[Documentation Update Instructions|Update]] the relevant sections in ''Help Manual'' and the [[Concept Guide]].
 +
 
 +
= Submitting Patches =
 +
 
 +
Once you have your changes written and well tested&mdash;<tt>make check</tt> will run a bunch of tests&mdash;you'll want to submit it so that someone with commit privilege can add it to the official sources. There are two ways we accept code:
 +
 +
# [[Git#Pull_Requests|Github pull requests]]: This is the preferred method if the change is non-trivial.
 +
#* If there is already a [[Bugzilla|bug report]] on the matter be sure to include a link to the bug in the pull request and comment on the bug with a link to the pull request.
 +
# Attach a patch to a [[Bugzilla|bug report]]:
 +
:* [[Git#Patches|Make a patch]].
 +
:* If there's already a bug about it in [[Bugzilla]], just attach the patch to the bug. Be sure to check the "patch" checkbox on the attachment form.
 +
:* If there isn't a bug already (be sure to search!), you'll need to create a new one to attach your patch to:
 +
:** Describe the problem or improvement that your patch addresses in the initial comment.
 +
:** Open the bug ''before'' you commit your changes so that you can include the bug number in the commit message.
 +
 
 +
= Tools =
  
 
Text editors / IDE:
 
Text editors / IDE:
 
* Most developers seem to have used [[Emacs]] as IDE.
 
* Most developers seem to have used [[Emacs]] as IDE.
 
* Additionally there are some experiences with [[Eclipse]].
 
* Additionally there are some experiences with [[Eclipse]].
* Some are using qtcreator.
+
* Some are using [http://qt-project.org/wiki/Category:Tools::QtCreator QtCreator].
 +
 
 +
For the GTK GUI:
 +
* [https://glade.gnome.org/ glade]
 +
 
 +
Some may be interested in our experiments with [[CMake]] and [http://qt-project.org/ Qt]: [[Cutecash]].
 +
 
 +
= See also =
 +
 
 +
An [https://lists.gnucash.org/pipermail/gnucash-devel/2004-June/011547.html informative mail] from the archives.
 +
 
 +
;GnuCash design and developer's reference: [http://svn.gnucash.org/docs/MAINT/ current bugfix] and [http://svn.gnucash.org/docs/MASTER/ future features] branch.
 +
 
 +
[http://www.gnu.org/software/guile/manual/html_node/Programming-in-Scheme.html Scheme programming manual]
 +
 
 +
[[C API]]
 +
 
  
Build system:
+
[[Category:Development]]
* Gnucash uses the [http://en.wikipedia.org/wiki/Autotools Autotools] as build system
 
* Additionally there are some experiments with [[CMake]], see [[Cutecash]]
 

Revision as of 02:41, 16 March 2017

Overview

GnuCash is written principally in C. A Guile interpreter is built in and parts of Gnucash--principally reports, but also parts of the user configuration, file import, and other small parts--are in Scheme. The C API is wrapped for Guile access with SWIG; Python wrappers can be created with a configure option.

The GUI is built with GTK+ version 2.24.

We're supporting two build systems GNU autotools and CMake. Understanding this complex system isn't generally necessary for fixing simple bugs, but more complex work will. Here's an excellent autotools tutorial and a short CMake one.

We use Doxygen to document the sources, including the C API. Details about our use are on the Doxygen wiki page. The Help Manual and Concepts Guide are formatted using DocBook, an SGML markup language which enables us to publish them in several formats. Note that these documents have a separate repository.

Object Orientation

Most of the code is written in an object-oriented style. Some of it uses GObject, some uses a home-grown GObject-like system called QofObject, and some just does what GObject does in straight C. Understanding how to use that is an important skill to developing for GnuCash. The next development cycle will include migrating those parts of Gnucash other than the GUI to C++; see our C++ page for details and resources. We are deferring updating the GUI either to Gtk+-3 or some other framework for at least another development cycle.

What We Need Help On

  • Patches to fix bugs are always a appreciated. It's an excellent way to get familiar with the code base and to introduce yourself to the team.
  • If you prefer to dive in at the deep end, have a look at the development team's long-term plans.

Preliminaries

Please subscribe to the Mailing Lists and introduce yourself to the development team. Some of the team also hang out on IRC so you can interact more directly.

Read the two files HACKING and README.svn

Look through the API documentation.

Getting Sources and Building

You can follow the git instructions for cloning the repository and preparing patches.

Build instructions for various platforms are described or linked at Building.

Coding Guidelines

Documentation

If your code adds or changes some functionality, do not forget the documentation.

  • Make sure that global (i.e. not static) functions are documented with Doxygen-formatted comments.
  • Try to keep the README files and that in src/doc up to date.
  • Update the relevant sections in Help Manual and the Concept Guide.

Submitting Patches

Once you have your changes written and well tested—make check will run a bunch of tests—you'll want to submit it so that someone with commit privilege can add it to the official sources. There are two ways we accept code:

  1. Github pull requests: This is the preferred method if the change is non-trivial.
    • If there is already a bug report on the matter be sure to include a link to the bug in the pull request and comment on the bug with a link to the pull request.
  2. Attach a patch to a bug report:
  • Make a patch.
  • If there's already a bug about it in Bugzilla, just attach the patch to the bug. Be sure to check the "patch" checkbox on the attachment form.
  • If there isn't a bug already (be sure to search!), you'll need to create a new one to attach your patch to:
    • Describe the problem or improvement that your patch addresses in the initial comment.
    • Open the bug before you commit your changes so that you can include the bug number in the commit message.

Tools

Text editors / IDE:

  • Most developers seem to have used Emacs as IDE.
  • Additionally there are some experiences with Eclipse.
  • Some are using QtCreator.

For the GTK GUI:

Some may be interested in our experiments with CMake and Qt: Cutecash.

See also

An informative mail from the archives.

GnuCash design and developer's reference
current bugfix and future features branch.

Scheme programming manual

C API