gnucash/doc

-*-text-*-

************ DEVELOPMENT  RELEASE ******************
The version 1.3.x series of GnuCash are experimental development
releases.  They may or may not work. Use at your own risk.

The last stable, production version was gnucash-1.2.5
The next stable, production version will be gnucash-1.4.x 

##############################################

GnuCash
-------
GnuCash is a personal finance manager.  A check-book like 
register GUI allows you to enter and track bank accounts,
stocks, income and even currency trades.  The interface is 
designed to be simple and easy to use, but is backed with 
double-entry accounting principles to ensure balanced books.

Features include:

  - An easy-to-use interface.  If you can use the
    register in the back of your checkbook, you 
    can use GnuCash.  Type directly into the register,
    tab between fields, and use quick-fill to
    automatically complete the transaction.
  - Reconcile window  with running reconciled 
    and cleared balances makes reconciliation easy.
  - Stock/Mutual Fund Portfolios:  Track stocks
    individually (one per account) or in portfolio
    of accounts (a group of accounts that can be 
    displayed together).  
  - Multiple Currencies & Currency Trading: Multiple 
    currencies are supported and can be bought and
    sold (traded).  Currency movements between accounts
    are fully balanced when double-entry is enabled.
    (Some aspects of multiple currency support are not 
    fully implemented.)
  - Quicken File Import: Import Quicken QIF style files.
    QIF files are automatically merged to eliminate 
    duplicate transactions.
  - Reports: Display Balance Sheet, Profit&Loss, Portfolio 
    Valuation, or print them as HTML.
  - Chart of Accounts: A master account can have a hierarchy
    of detail accounts underneath it.  This allows similar
    account types (e.g. Cash, Bank, Stock) to be grouped 
    into one master account (e.g. Assets).
  - Split Transactions: A single transaction can be split
    into several pieces to record taxes, fees, and
    other compound entries.
  - Double Entry: When enabled, every transaction must 
    debit one account and credit another by an equal amount.
    This ensures that the "books balance": that the 
    difference between income and outflow exactly equals
    the sum of all assets, be they bank, cash, stock or other.
  - Income/Expense Account Types (Categories):  
    These serve not only to categorize your cash flow, 
    but when used properly with the double-entry feature,
    these can provide an accurate Profit&Loss statement.
  - General Ledger: Multiple accounts can be displayed 
    in one register window at the same time.  This can
    ease the trouble of tracking down typing/entry errors.
    It also provides a convenient way of viewing a
    portfolio of many stocks, by showing all transactions
    in that portfolio.
  - Written in C with embedded scheme support via Guile.
  - Perl support is optionally available for stand-alone scripting via SWIG.
  - File access is locked in a network-safe fashion, preventing
    accidental damage if several users attempt to access the 
    same file, even if the file is NFS-mounted.
  - Provides a byte-stream format, which allows accounts and
    account groups to be transmitted to other processes
    via pipes or sockets.
  - Get Stock & Mutual Fund quotes from various web sites, 
    update portfolio automatically (more funds being added 
    regularly).
  - European date handling, French, German, Swedish, and Great
    Britain translations.


Home Page:
----------
http://gnucash.org/

Original X-Accountant home page:
http://www.cs.hmc.edu/~rclark/xacc

Precompiled binaries:
http://www.gnucash.org/pub/gnucash/redhat-6.x/1.2.5/

Development versions:
http://www.gnucash.org/source_code.php3


Running:
--------
Only the 1.2.5 Motif version of GnuCash is currently stable. The Gnome
version is a development version, but will soon be stable enough for
regular use. Development of the Motif version has ceased and the Motif
version does not compile in current CVS. The Qt version doesn't
compile and most functions are missing. See below for OS's other
than GNU/Linux/*BSD support.

The following packages are required to be installed to run the gnucash 
Motif binary:

guile   -- Provides main extension language infrastructure.
           This is used extensively in gnucash for initialization & startup.
           Require version 1.3 or later. The guile-1.3-7 rpm works.

Motif or Lesstif  --
           Either a commercial Motif, or the free software clone Lesstif is
           needed.  If you use a commercial version of Motif (widely available
           for roughly 50 USD), be sure to get a version compatible with your
           glibc and libXt version.  Lesstif mostly works, but there have been
           problems.  Here's our experience:

           Lesstif 0.81    works   
           Lesstif 0.82    broken    
           Lesstif 0.83    works ... but get fast blinking cursor ...
           Lesstif 0.86.0  is reported to work     
           Lesstif 0.86.5  crashes.   
           Lesstif 0.86.9  works ... but some menus come out 2 pixels high.(?)
           Lesstif 0.87.0: broken (missing symbols for XmeDrawShadows, etc.)
           Lesstif 0.88.1  works
           Lesstif 0.89.0  works

XmHTML  -- Provides HTML display capabilities.
           Used for Help Dialogues and Reports.

           Require version 1.1.4 or later
           http://www.llp.fu-berlin.de/lsoft/F/5/XMHTML.html
           http://www.xs4all.nl/~ripley/XmHTML/XmHTML.html
           ftp://ftp.ultra.net/pub/eugene/RPMS/i386/XmHTML-1.1.5-1.i386.rpm
           ftp://ftp.ultra.net/pub/eugene/SRPMS/XmHTML-1.1.5-1.src.rpm

           Note: some precompiled versions of XmHTML have been compiled with 
           Motif.  When used with most precompiled versions of Lesstif, you 
           will get a "undefined symbol XmeDrawShadows" error. There are
           several solutions; the simplest is probably to download the
           XmHTML source package and compile it yourself.

slib    -- scheme libraries for guile. Need version slib2c4 or later.

libpng  -- portable network graphics library. Any version.
libjpeg -- JPEG image handling library. Any version.
libz    -- compression library. Any version.
xpm     -- X Pixmap extension. Any version.


To be able to use certain features of GnuCash, such as reports and
network stock price downloads, you must have the following packages
below installed (in addition to those listed above).
RPM's for most of these can be found at http://rufus.w3.org/linux/

slib    -- scheme libraries for guile.  Need version slib2c4 or later.
perl    -- Almost any version of perl5 should work.  I run perl-5.004 
eperl   -- Almost any version of eperl should work.  I run eperl-2.2.14

In addition, some perl modules need to be installed:

perl-LWP/libwww-perl-5.36
perl-HTML/HTML-0.6
perl-HTML/HTML-Parser-2.20
        -- these perl modules are used to fetch stock & mutual fund quotes
           off the net.  You can pick up RPMS at
           ftp://ftp.gnucash.org/pub/gnucash/binaries/RPMS
           http://rufus.w3.org/linux/RPM/PByName.html
           http://linas.org/linux/gnucash (last resort)
           or sources at
           http://www.cpan.org/CPAN.html


The following packages are required to be installed to run the GnuCash
Gnome binary:

gnome-libs -- version 1.0.40 or higher should work. These libraries
              require numerous other supporting libraries, such as
              gtk and glib.

guile  -- same as Motif
slib   -- same as Motif


Invocation:
-----------
You can start GnuCash at the command-line, with "gnucash" or "gnucash
<filename>", where <filename> is a GnuCash account file.  Sample
accounts can be found in "data" subdirectory.  *.dat files are GnuCash
accounts that can opened with the "Open File" menu entry.  *.qif files
are Quicken Import Format files that can be opened with the "Import
QIF" menu entry.

GnuCash responds to the following environment variables:

  GNC_RUN_AS_SHELL - if set, makes GnuCash pop up in a guile shell
  with all the gnucash functions loaded.  From there, you can get the
  normal startup behavior like this:

    GNC_RUN_AS_SHELL=t ./gnucash
    guile> (primitive-load (getenv "GNC_BOOTSTRAP_SCM"))
    guile> (gnc:load "startup.scm")
    guile> (gnc:main)

  This is the same thing that happens if you don't use this
  environment variable.  This can be helpful when trying to write and
  test new .scm files.

  GNC_BOOTSTRAP_SCM - the location of the initial bootstrapping scheme code.

  GNC_SCM_LOAD_PATH - an override for the GnuCash scheme load path.
  it should be a string representing a proper scheme list.  Each
  element can either be a string representing a directory, the symbol
  'default which will expand to the default path, or 'current which
  will expand to the current load-path at the instant it encounters
  the symbol.

  GNC_DEBUG - enable debugging output.  This allows you to turn on
  debugging earlier in the startup process than you can with --debug.


Internationalization:
---------------------
Message catalogues exist for French and German.  These are enabled with 
environment variables.  For example, 

Francais, en bash:
    export LANG=fr_FR

Francais, en tcsh:
    setenv LANG fr_FR

German version:
    export LANG=de_DE


Other locales that should mostly work, but are still in development:

en_US
en_GB
fr_CH
de_CH


Other Tools
-----------
A tool to generate (ascii) reports from gnucash/xacc files can be found 
at http://www.zeta.org.au/~grahamc/xacc_rpts.html.

A tool to cleanup & import Quicken files can be found at (insert the url
here).


Building & Installing:
----------------------
These steps does not apply to binary distributions; only to source
distributions.

Prior to building GnuCash, you will have to obtain and install the following
packages:

libtool -- Used to build our internal version of g-wrap which handles
           our guile C wrappers.  Available at ftp://ftp.gnu.org/gnu.
           RPM's and debs are widely available with most distributions.
SWIG    -- Used to autogenerate perl wrappers.
           available at www.swig.org need 1.1p5 or later ...

Normally, to build and install GnuCash, all you have to do is:

  # ./configure
  # make 
  # make install

If you only want a particular language installed, you can set the
LINGUAS environment variable before you run configure. For example,
to only install the French translations, run

  # export LINGUAS=fr
  # ./configure

If you want to make sure that all languages get installed, run

  # unset LINGUAS
  # ./configure

You can build Gnome, Motif, and Qt versions. The Gnome version
compiles and is being actively developed, is not yet at the stability
level of the 1.2.5 Motif version, but has more features. Currently,
the older 1.2.5 Motif version is the most stable and bug-free. The Qt
version may not compile.

Depending on your make target, you'll produce:

  gnucash.gnome
  gnucash.gnome.static
  gnucash.motif
  gnucash.motif.static
  gnucash.qt
  gnucash.qt.static

The 'static' version statically link in the libraries that GnuCash
uses.  For example, gnucash.motif.static is handy when compiling
against a commercial version of Motif, and distributing this version
to the general public.

Whichever one you produce last ends up the target of a local
gnucash.bin symlink, so that you can always run the local ./gnucash
script to see the last flavor that you built.  The ./gnucash script
also handles making sure that you're using files from the source dir
rather than an install tree just like the old ./xacc script did.

You'll use "make install" when you want to do a normal FSSTND /usr/
or /usr/local style install where everything scatters across the
filesystem in foo/gnucash/* directories.  You'll use "make
install-opt" when you want an /opt/gnucash style install where
everything installs into the /opt/gnucash directory.

So the two most likely sets of build instructions would be as follows:

  For a full system install (gnucash is installed as part of the
  system):

    ./configure --prefix=/usr --sysconfdir=/etc
    make motif
    make install

  For an /opt style install

    ./configure --prefix=/opt/gnucash
    make motif
    make install

Examples of other funny configure options:
    ./configure --with-motif=/usr/local/opt/mootif \
                --prefix=/usr/local/opt/gnucash \
                --with-xmhtml-includes=/home/rlb/XmHTML-1.1.5/include\
                --with-xmhtml-libraries=/home/rlb/XmHTML-1.1.5/src


Flag --with-gtk-config.  The way gtk phiolosphy goes,
you should *only* specify the config program location and
rely on it to tell you the right CFLAGS and XLIBS values.

Runtime and install destinations are separate.  The --prefix
you specify to configure determines where the resulting binary
will look for things at runtime.  The prefix you give to make
install (i.e. make prefix=foo install) only determines where the
files are placed.  If this location is different from the
configure --prefix value, then gnucash won't work until it's moved
to that location.  This feature is mostly useful for package
builders, but it shouldn't hurt anyone else.

Only the location of startup.scm is hardcoded into the binary, and
even that can be overridden with --startup-file on the command line.
The other defaults are now in startup.scm.  path-defaults.h is now
gone. The startup file setting is in gnucash.h, generated from
gnucash.h.in.


Supported OS's:
---------------
GnuCash version 1.2.x is known to work in the following configs:

GNU/Linux             -- Intel 
FreeBSD               -- Intel
OpenBSD               -- Intel

Xacc-1.0.18, the predecessor to GnuCash, is known to work on these additional
platforms:

Slackware 3.4         -- Intel  w/ Mootif (OSF Motif 2.0.1)
SGI IRIX              -- MIPS 
IBM AIX 4.1.5         -- RS/6000   http://www-frec.bull.com/
Unixware 7            -- Intel
SCO OpenServer 5.0.4  -- Intel
Solaris               -- Sparc  

See ftp://ftp.gnucash.org/pub/xacc (high-bandwidth)
or  http://linas.org/linux/gnucash (slow-www ) 
for precompiled binaries for these platforms


Additional Download Sites:
--------------------------
Precompiled binaries & pre-requisite packages can be found at

IBM AIX 4.1.5 
      -- SMIT-installable images 
      http://www.bull.de/pub/
      see also http://www-frec.bull.com/

SCO OpenServer 5.0.4 
      http://www.sco.com/skunkware/osr5/x11/apps/xacc/VOLS.tar

Unixware 7
      -- use pkgadd to install
      http://www.sco.com/skunkware/uw7/x11/apps/xacc/xacc.pkg.gz

SGI Irix
      -- in SGI install format
      -- warning, this is a very down-level version
      http://linas.org/linux/xacc/xacc-1.0b7-sgi-irix.inst.tar


Getting Source with CVS
-----------------------
A read-only version of the cvs tree is available on the net.
To access it, first, login, as so:

  cvs -d :pserver:cvs@cvs.gnucash.org:/home/cvs/cvsroot login

The password is "guest"

To get a copy of the source in the experimental development tree do a

  cvs -z3 -Pd :pserver:cvs@cvs.gnucash.org:/home/cvs/cvsroot checkout -rHEAD gnucash

To get a copy of the source in the gnucash-1.2 stable production tree do a

  cvs -z3 -Pd :pserver:cvs@cvs.gnucash.org:/home/cvs/cvsroot checkout -rxacc-12-patch gnucash


Developing GnuCash
------------------
Before you start developing GnuCash, you should do the following:

1. Read the file src/coding-style.txt to learn about the coding-styles
   used in the GnuCash source code.

2. Several of the directories under src contain files called design.txt
   which explain many aspects of GnuCash's design. Read those.

3. Go to the gnucash website and skim the archives of the gnucash
   development mailing list.

4. Join the GnuCash development mailing list. See the gnucash website
   for details on how to do this.


Submitting a Patch
------------------
Once you have done some work that you would like to submit, you need
to send a patch. There is a perl script called make-gnucash-patch
provided with the distribution that you can use to create the
patch. Here is how to use that perl script.

First, set up your development directories as follows:

< GnuCash home development directory >
    |
    |---- < directory containing original GnuCash sources >
    |
    |---- < directory containing your modified GnuCash sources >

A concrete example of those directories might be:

/home/me/gnucash
    |
    |---- /home/me/gnucash/gnucash.pristine (original sources)
    |
    |---- /home/me/gnucash/gnucash.mywork (original sources + my edits)

Copy the make-gnucash-patch script to the home development directory
(/home/me/gnucash above). Now set three environment variables to
reflect the names of your directories. Given the names above, you
would use:

export GNC_MAKEPATCH_OLD_DIR=gnucash.pristine
export GNC_MAKEPATCH_NEW_DIR=gnucash.mywork
export GNC_MAKEPATCH_HOME_DIR=/home/me/gnucash

Right before you make your patch, make sure *both* your working and
your pristine directories are in sync with cvs. Run 'cvs -z3 update -dP'
in both directories to ensure that is the case. Updating from cvs in
your working directory may cause conficts in a file. You must resolve
those conficts before making a patch.

Now run the script. Note that this script requires the programs
'makepatch', 'gzip', 'diff', and 'uuencode' (and, of course, 'perl')
to run. 

When you run the script, three files will be generated:

  gnc.diff - This file is an ascii text file containing the differences
             between the original sources and your edits. At the bottom
             of this file is a list of the files which were added,
             changed, or deleted.

             Please examine this file (especially the list at the bottom)
             to make sure that all of your changes (and no other changes)
             are present in the file.

             Do not submit this file!

  gnucash.diff.gz - This is a gzipped version of the above file.

                    Do not submit this file!

  gnucash.diff.gz.uue - This is a uuencoded (ascii-encoded) version
                        of the above file.

                        This is the file you submit.

Send gnucash.diff.gz.uue to gnucash-patches@gnucash.org

Thanks in advance for your contribution!


Main Developers:
----------------
Robin Clark <rclark@hmc.edu> wrote the original X-Accountant in Motif 
   as a school project, taking it to version 0.9 by October 1997.

Linas Vepstas <linas@linas.org> liked what he saw: the GUI was slick,
   the code was documented and well structured, and it was all GPL'ed.  
   And so he re-wrote it: adding cell-widgets to XbaeMatrix, so that 
   the combobox and arrows would make an even slicker GUI, rewrote the 
   X-Accountant internals to add double-entry, an account hierarchy,
   split out a transaction mini-engine, add support for stocks, and spiff
   up the help menus.  This was version 1.0 as of January 1998.  Since
   then, for version 1.1, the engine was expanded & refined, and the 
   register window code completely redesigned and made mostly 
   Motif-(and GUI-)independent.  Did some prototype OFX work.

Jeremy Collins <jcollins@gnucash.org> publicized the GnoMoney project 
   widely and broadly, and then changed its name to GnuCash.  Jeremy
   created the gnucash.org web site, registered the domain, got the 
   initial GTK/gnome code working.

Rob Browning <rlb@cs.utexas.edu> abused everyone for not using perl,
   and then added guile/scheme support. Rob maintains the build 
   infrastructure, is handling the whole guile/perl extension language 
   thing, and is dealing with configuration & configurability.

Dave Peticolas <peticola@cs.ucdavis.edu> hacks obsessively on
   GnuCash. But he can stop anytime he wants to. Really.

Bill Gribble <grib@billgribble.com> works magic. If your checks print
   wrong, blame him. If you don't like the amount printed on your
   checks, blame him. If you don't like your your bank balances,
   your bank, or your life, blame him too.


Fixes & Patches:
----------------
Andrew Arensburger <arensb@cfar.umd.edu> for FreeBSD & other patches
Matt Armstrong <matt_armstrong@bigfoot.com> for misc fixes
Fred Baube <fred@moremagic.com> for attempted Java port/MoneyDance
Dennis Bj<42>rklund <dennisb@cs.chalmers.se> Swedish translation
Per Bojsen <bojsen@worldnet.att.net> several core dump fixes
Christopher B. Browne <cbbrowne@hex.net> for perl and lots of scheme
Graham Chapman <grahamc@zeta.org.au> for the xacc-rpts addon package
George Chen <georgec@sco.com> for MS-Money QIF's & fixes
Albert Chin-A-Young <china@thewrittenword.com> configure.in patch
Jeremey Collins <jcollins@gnucash.org> for GnoMoney & GTK port
Matthew Condell <mcondell@bbn.com> FreeBSD patch
Patrick Condron <pcondon@rackspace.com> for webserver and T1 connection.
Ciaran Deignan <Ciaran.Deignan@bull.net> for AIX binary version
Tyson Dowd <tyson@tyse.net> for config/make patches & debian maint
Koen D'Hondt <ripley@xs4all.nl> for Solaris patches to XmHTML
Bob Drzyzgula <bob@mostly.com> for budgeting design notes
Paul Fenwick <pjf@schools.net.au> ASX support
Hubert Figuiere <hfiguiere@teaser.fr> patch to gnc-prices
Jan-Uwe Finck <ju_finck@mail.netwave.de> for German message translation
Ron Forrester <rjf@aracnet.com> for gnome patches
Dave Freese <DFreese@osc.uscg.mil> for leap-year fix
Bill Gribble <grib@billgribble.com> qif importation code
Otto Hammersmith <otto@bug.redhat.com> for RedHat RPM version
Eric Hanchrow <offby1@blarg.net> updated currency documentation
Alexandru Harsanyi <haral@codec.ro> for core dumps, lockups, gtk work
John Hasler <john@dhh.gt.org> engine patch
Jon K}re Hellan <jk@isdn-a33.itea.ntnu.no> misc core dump fixes
Prakash Kailasa <PrakashK@bigfoot.com> for gnome build fixes
Ben Kelly <ben.kelly@ieee.org> for motif menu bug fix, core dump fixes
Tom Kludy <tkludy@csd.sgi.com> for SGI Irix port
Sven Kuenzler <sk@xgm.de> for SuSE README file
Bryan Larsen <blarsen@ada-works.com> guile budget report
Graham Leggett <minfrin@sharp.fm> for fixing a hang
Ted Lemon <mellon@andare.fugue.com> for NetBSD port
Yannick Le Ny <y-le-ny@ifrance.com> pour la traduction en francais 
Grant Likely <glikely@nortelnetworks.com> gnome and engine patches
Heath Martin <martinh@pegasus.cc.ucf.edu> gnome patches, major register work
Matt Martin <mgmartin@abacusnet.net> guile error handling code
Robert Graham Merkel <rgmerk@mira.net> reporting, gnome, and config patches
Tim Mooney <mooney@dogbert.cc.ndsu.NoDak.edu> port to alpha-dec-osf4.0f
G. Allen Morris III  <gam3@ann.softgams.com> for QIF core dump 
Brent Neal <brent@baton.phys.lsu.edu> TIAA-CREF support.
Peter Norton <spacey@inch.com> for a valiant attempt at a GTK port
OmNiBuS <webmaster@obsidian.uia.net> web site graphics & content
Myroslav Opyr <mopyr@IPM.Lviv.UA> for misc patches
Dave Peticolas <peticola@morpheus.cs.ucdavis.edu> extensive intelligent patches
Laurent P{'e}lecq <laurent.pelecq@wanadoo.fr> i18n patches with gettext
Alain Peyrat <Alain.Peyrat@nmu.alcatel.fr> for configure.in patches
Peter Pointner <peter@wuzel.m.isar.de> QIF import fixes, Qt patches
Gavin Porter <maufk@csv.warwick.ac.uk> for euro style dates
Tomas Pospisek <tpo@spin.ch> debian patches
Ron Record <rr@sco.com> for SCO Unixware & OpenServer binaries
Dirk Schoenberger <schoenberger@signsoft.com> Qt/KDE work
Jan Schrage <jan.schrage@urz.uni-heidelberg.de> documentation patches
Christopher Seawood <cls@seawood.org> for XbaeMatrix core dump
Mike Simons <msimons@fsimons01.erols.com> misc configure.in patches
Richard Skelton <rich@brake.demon.co.uk> for Solaris cleanup
Henning Spruth <spruth@bigfoot.com> for German text & euro date rework
Robby Stephenson <robby.stephenson@usa.net> register & file history patches
Herbert Thoma <tma@iis.fhg.de> gnome register & euro support patches
Diane Trout <detrout@earthlink.net> scheme qif import patch
Richard Wackerbarth <rkw@dataplex.net> patch to gnc-prices
Rob Walker <rob@valinux.com> guile and register patches
David Woodhouse <dwmw2@infradead.org> Great Britain translations
Ken Yamaguchi <gooch@ic.EECS.Berkeley.EDU> QIF import fixes; MYM import

... and I am sure that I have missed many others ...