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 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/

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.87.0: broken (missing symbols for XmeDrawShadows, etc.)

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

Running:
--------
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'.

You can then 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.


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

The new --shell option should work properly now too.  There is no
gnucash-shell anymore.  There's just one binary.  You can invoke
gnucash with the --shell option now to get a guile shell with all the
gnucash functions loaded.  You can also get the normal startup
behavior from that shell like this:

  ./gnucash --shell
  guile> (load (string-append gnc:_startup-dir-default_ "/init.scm"))
  guile> (gnc:main)

which is the same thing that happens if you don't use the --shell
option.

The --shell option can be helpful when trying to write and test new
.scm files.  I set it up so that I (or someone else) could
(eventually) work on the graphing stuff...

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.




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

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