gnucash/README

-*-text-*-

************ 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 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 quickfill 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 mutiple currency support are not 
    fully implemented.)
  - Quicken File Import: Import Quicken QIF style files.
    QIF files are automtically 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 compund 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 perl, scheme and tcl support for easy
    configuration and extensibility.
  - 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).

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

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

Precomipled binaries:
ftp://ftp.ultra.net/pub/eugene/RPMS/i386/

Development versions:
http://linas.org/linux/xacc/

Running:
--------
Only the Motif version of GnuCash is currently functional.  The Gnome version
will give you a taste for Gnome, but most functions will not work.   The qt
version doesn't compile, most functions are missing.  See below for OS's other
than Linux/*BSD support.

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.
RPM's for most of these can be found at http://rufus.w3.org/linux/  

slib    -- scheme libraries for guile.  Need version slib2c0 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/xacc (last resort)
           or sources at
           http://www.cpan.org/CPAN.html

The binary-only distribution of GnuCash comes with several executables: 
one has Motif statically linked in, and another has Motif linked in dynamically.
The motif dynamic-link version requires that either motif or lesstif be
installed.  Motif is a commercial product available form several vendors for
approx $50.  Lesstif is an open source clone available for free. Note that 
not all version of lesstif work with Gnucash: thhe the note below.

The binary-only distribution includes two binary files: 'gnucash.bin'
and 'gnucash-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 
'gnucash-static.bin' to 'gnucash.bin'.

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)

  which is the same thing that happens if you don't use the --shell
  option.  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.

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

Important Note:
---------------
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.86.0: works
Lesstif 0.86.5: broken
Lesstif 0.86.9  works ... but some menus come out 2 pixels high.
Lesstif 0.87.0: works ... "" ?
Lesstif 0.88.1: works ... "" ?

Note: some versions of XmHTML have been compiled with Motif, and these
need XmeDrawShadows to link and run.  However, this is an undefined symbol
in most versions of lesstif. Solution: download XmHTML source and 
compile/install it.

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

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:

nana    -- Used to provide a debugging infrastructure.
           Any version should work.
           http://www.fsf.org/software/nana/nana.html
	   http://www.cs.ntu.edu.au/homepages/pjm/nana-home/
SWIG    -- Used to autogenerate perl, tcl, guile wrappers.
           available at www.swig.org need 1.1p5 or later ...
guile   -- Provides main extension language infrastructure.
           This is used extensively in gnucash for initialization & startup.
           need version 1.3 or later ( or build 1998.08.18 or 1998.09.10 or later) ...
           ftp://ftp.gnucash.org/pub/gnucash/extra_libs/TAR/guile-core-19980818.tar.gz 
           guile-core-19980818-1.i386.rpm works
           guile-1.3.1-1 from redhat.com/pub/rawhide works ...
eperl   -- embeddedPerl needed for Reports.  The menu item "Reports" will not
           work witout this.
           version eperl-2.2.14 works well with perl 5.00404
           http://www.engelschall.com/sw/eperl/
           ftp://ftp.ultra.net/pub/eugene/RPMS/i386/eperl-2.2.14-1.i386.rpm

Motif or Lesstif  --
           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.)
           Commercial Motif seems to work, but beware old libXm's 
           combined with new glibc's, 

XmHTML  -- Provides HTML display capabilities. Used for Help Dialogues, Reports.
           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

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

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 
           http://rufus.w3.org/linux/RPM/PByName.html
           http://linas.org/linux/xacc (last resort)
           or sources at 
           http://www.cpan.org/CPAN.html

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

  # ./configure
  # make 
  # make install

You can build Motif, Gnome, and Qt versions. Currently, the Motif version
is the most stable, bug-free, correct, and feature rich.  The gtk/gnome
version compiles and is being actively developed, but will take a while to
reach the stibility level of the motif version. The Qt version may not 
compile.

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



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.

Anyone who's having the same problem with the added termcap libs that
I am can look in configure.in and comment out the TERMCAP_TMP line and
re-run autoconf and configure.  We'll have a better fix later.


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 overriden 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.1.x is known to work in the following configs:

Linux 2.x.x           -- Intel  w/ RedHat Motif
FreeBSD               -- Intel
OpenBSD               -- Intel

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

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
Solaris               -- Sparc  

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


Additional 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

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 -rHEAD 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 <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.

Dirk Schoenberger <schoenberger@signsoft.com> is working on the Qt/KDE port

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
Christopher B. Browne <cbbrowne@hex.net> for perl stock scripts
Graham Chapman <grahamc@zeta.org.au> for the xacc-rpts addon package
George Chen <georgec@sco.com> for MS-Money QIF's & fixes
Jeremey Collins <jcollins@gnucash.org> for GnoMoney & GTK port
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
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
Otto Hammersmith <otto@bug.redhat.com> for RedHat RPM version
Alexandru Harsanyi <haral@codec.ro> for misc core dumps & lockups.
Jon K}re Hellan <jk@isdn-a33.itea.ntnu.no> misc core dump fixes
Prakash Kailasa <PrakashK@bigfoot.com> for gnome build fixes
Tom Kludy <tkludy@csd.sgi.com> for SGI Irix port
Sven Kuenzler <sk@xgm.de> for SuSE README file
Ted Lemon <mellon@andare.fugue.com> for NetBSD port
Yannick Le Ny <y-le-ny@ifrance.com> pour la traduction en francais 
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
Myroslav Opyr <mopyr@IPM.Lviv.UA> for misc patches
Alain Peyrat <Alain.Peyrat@nmu.alcatel.fr> for configure.in patches
Gavin Porter <maufk@csv.warwick.ac.uk> for euro style dates
Ron Record <rr@sco.com> for SCO Unixware & OpenServer binaries
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
Ken Yamaguchi <gooch@ic.EECS.Berkeley.EDU> QIF import fixes; MYM import

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