gnucash/README

************ BETA  RELEASE ******************
The version 1.1.x series of gnucash are considered BETA development code.
Things mopstly work these days; some things may still be broken. Feel 
free to try it.  Please report bugs to http://www.gnucash.org/

The last stable, production version was xacc-1.0.18
The next stable, production version will be gnucash-1.2.x

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

GnuCash
-------
GnuCash is an application to keep track of your finances.  It is similar in
concept to Quicken(TM).  Although GnuCash still lacks the advanced
features of Quicken, it does have the basic functionality.  Some
of the features of GnuCash are:

  - Multiple Accounts
  - Each account keeps a running balance and
    a reconciled balance, so you can keep track
    of the checks that have clear your account.
  - A simple interface.  If you can use the
    register in the back of your checkbook,
    you can use GnuCash.
  - QuickFill... if you begin typing a description
    in the description fields, and it matches an
    previous transaction, hitting <TAB> will copy
    the previous transaction.  Handy if you have
    similar transactions on a regular basis.
    (such as depositing your paycheck every week :)
  - 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. Multiple currencies are 
    supported, as well as currency trading accounts.
    Note this is still broken in many ways...
  - Quicken File Import. Import Quicken QIF files.
  - Reports. Display Balance, Profit&Loss reports,
    or print them in HTML form.

Advanced Features
-----------------
GnuCash offers some features not usually found
in simpler accounting programs.
  - Sub-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).
  - Double Entry: 
    Every transaction can appear in two
    accounts; one account is debited and the other is 
    credited with exactly the same amount.  With 
    double-entry, a transaction edited in one window 
    will be automatically updated in all other windows 
    showing that transaction, and in both of the 
    accounts.
  - Income/Expense Account Types (Categories).   
    When used properly 
    with the double-entry feature, these can be used 
    to create both Balance Sheet and Profits &amp; Losses
    reports.  For example, savings account interest,
    stock dividends, or paychecks can be marked as 
    both a deposit in a bank account, and as income in 
    an Income account type, using the double-entry 
    (transfer) feature.  Similarly, credit card charges
    can be noted in the credit card account, as well 
    as in a corresponding expense account.
  - 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.

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

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

Important Note:
---------------
Numerous core dumps have been reported when using various
versions of lesstif.  Some versions work, others don't.
Lesstif 0.81: works
Lesstif 0.82: broken
Lesstif 0.81: works
Lesstif 0.86.0: works
Lesstif 0.86.5: broken

These core dumps do not occur with RedHat Motif (or other commercial
versions of Motif).

Running:
--------
The binary-only distribution includes two binary files: 'xacc.bin'
and 'xacc-static.bin'. The former requires a Motif shared library;
the latter has Motif statically linked in.  If you have Motif,
then just run xacc.  If you do not have Motif, then copy 
'xacc-static.bin' to 'xacc.bin'.

Access to the on-line help documentation requires the that
the environment variable XACC_HELP be set to the 'Docs'
directory.  The 'xacc' shell script sets this variable to
the configured directory before running the main program,
so you don't have to set this by hand.

If you want to override the path to the Docs directory:

For csh/tcsh

% setenv XACC_HELP /usr/local/share/xacc/Docs

or, for bash/bsh/ksh/sh

% set XACC_HELP=/usr/local/share/xacc/Docs
% export XACC_HELP

You can then start GnuCash at the command-line, with
"xacc" or "xacc <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.


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:

SWIG    -- available at www.swig.org need 1.1p5 or later ...
guile   -- need version 1.3 or later ( or build 1998.09.10 or later) ...
           ftp://ftp.gnucash.org/pub/gnucash/extra_libs/TAR/guile-core-19980818.tar.gz 

Motif or Lesstif  --
           Lesstif 0.81    works   
           Lesstif 0.82    broken    
           Lesstif 0.83    works    
           Lesstif 0.86.0  is reported to work     
           Lesstif 0.86.5  crashes.   
           Commercial Motif seems to work, but beware old libXm's 
           combined with new glibc's, 

XmHTML  -- 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
libpng  -- portable network graphics library
libjpeg -- JPEG image handling library
libz    -- comopression library
xpm     -- X Pixmap extension
eperl   -- embeddedPerl needed for reports
           version eperl-2.2.14 works well with perl 5.00404
           http://www.engelschall.com/sw/eperl/

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

  # ./configure
  # make
  # make install

You can build Motif, Gnome, and Qt versions.
Depending on your make target, you'll produce:

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

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 a /usr/local/opt/gnucash style install
where everything just installs into local bin, doc, share, etc dirs.
I couldn't think of a better way to handle this, or I would have used
it.

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=/usr/local/opt/gnucash
    make motif
    make install-opt

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


Status:
-------
As of version 1.0.18:

GnuCash is known to work in the following configs:
Linux 2.x.x           -- Intel  w/ RedHat Motif
Slackware 3.4         -- Intel  w/ Mootif (OSF Motif 2.0.1)
Linux 2.x.x           -- Intel  w/ Lesstif v0.81
SGI IRIX              -- MIPS 
IBM AIX 4.1.5         -- RS/6000   http://www-frec.bull.com/
Unixware 7            -- Intel
SCO OpenServer 5.0.4  -- Intel

See http://linas.org/linux/xacc for precompiled binaries for these platforms

GnuCash seems to be having problems with:
Solaris -- Sparc  -- won't compile due to va-args in XmHTML
Linux 2.x.x -- Intel w/ Lesstif v0.82

Download Sites:
---------------
All of the precompiled binaries & the latest source versions can be found
at http://linas.org/linux/xacc  However, it is recommended that the master
sites for each particular binary be used instead, for two reasons:
1) bandwidth
2) OS-specific info & support

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

Linux Debian
      -- use debian tools to install
      http://linas.org/linux/xacc/xacc_1.0.15-1_i386.deb

That's all folks!

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, do a 

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


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 heirarchy,
   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 <linux@cyberramp.net> 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.

Fixes & Patches:
----------------
Fred Baube <fred@moremagic.com> for attempted Java port/MoneyDance
Christopher B. Browne <cbbrowne@hex.net> for perl stock scripts
George Chen <georgec@sco.com> for MS-Money QIF's & fixes
Jeremey Collins <linux@cyberramp.net> for GnoMoney & GTK port
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
Dave Freese <DFreese@osc.uscg.mil> for leap-year fix
Otto Hammersmith <otto@bug.redhat.com> for RedHat RPM version
Jon K}re Hellan <jk@isdn-a33.itea.ntnu.no> misc core dump fixes
Tom Kludy <tkludy@csd.sgi.com> for SGI Irix port
Ted Lemon <mellon@andare.fugue.com> for NetBSD port
G. Allen Morris III  <gam3@ann.softgams.com> for QIF core dump 
Peter Norton <spacey@inch.com> for a valiant attempt at a GTK port
OmNiBuS <webmaster@obsidian.uia.net> web site graphics & content
Gavin Porter <maufk@csv.warwick.ac.uk> for euro style dates
Ron Record <rr@sco.com> for SCO Unixware & OpenServer binaries
Dirk Schoenberger <schoenberger@signsoft.com> for Qt/KDE port
Christopher Seawood <cls@seawood.org> for XbaeMatrix core dump
Richard Skelton <rich@brake.demon.co.uk> for Solaris cleanup
Henning Spruth <spruth@bigfoot.com> for German text & euro date rework
Ken Yamaguchi <gooch@ic.EECS.Berkeley.EDU> QIF import fixes; MYM import

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