gnucash/README

############################################################
          GnuCash 1.9.x README file.

NOTE: THIS IS A DEVELOPMENT RELEASE!!! THIS VERSION HAS NOT
BEEN TESTED PROPERLY AND MAY DO ABSOLUTELY ANYTHING!  

USE AT YOUR OWN RISK (AND KEEP *LOTS* OF BACKUPS)

If you want something a bit more tested, please use the
1.8 stable series.
------------------------------------------------------------

##################
Table of Contents:
------------------

  - Overview
  - Upgrading from 1.6.x
  - Dependencies
  - Invocation/running
  - Internationalization
  - Building & Installing
  - Supported Platforms
  - Additional Download Sites
  - Getting the Source via CVS
  - Developing GnuCash

########
Overview
--------

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. A full set of reports allow you to see the state of
your finances. 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.
    The interface is customizable from within the 
    application itself (no editing config files :) )
  - Scheduled Transactions: GnuCash now has the ability to 
    automatically create and enter transactions, remind when
    a transaction is due, give a choice of entering a transaction
    or postponing it and remove an automated transaction after a
    certain period.
  - Mortgage & Loan Repayment Druid: Used to setup a variable
    payment loan scheduled transaction.
  - Small Business Accounting Features: GnuCash now can be used
    for Customer and Vendor tracking, Invoicing and Bill Payment,
    and using different Tax and Billing	Terms in a small business.
  - OFX Import: GnuCash is the first free software application 
    to support the Open Financial Exchange protocol that many 
    banks and financial services are moving to use. The 
    development of OFX and HBCI support has also resulted in
    an improved transaction matching system that more accurately
    picks duplicate transactions.
  - HBCI Support: GnuCash is the first free software application
    to support the German Home Banking Computer Interface protocol
    which includes statement download, initiate bank transfers 
    and direct debits.
  - Quicken File Import: Import Quicken QIF style files.
    QIF files are automatically merged to eliminate 
    duplicate transactions.
  - 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).  
  - Get Stock & Mutual Fund quotes from various web sites, 
    update portfolio automatically (more funds being added 
    regularly).
  - Reports: Display Balance Sheet, Profit&Loss, Portfolio 
    Valuation, Transaction Reports, or account balance tracking,
    or export them as HTML.  You can write your own custom
    report if you know a little Scheme.  Reports can now be performed
    over an accounting period!
  - 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.
  - New Multi-Currency Transaction Handling: GnuCash no longer
    requires separate currency exchange accounts to handle 
    multiple currency transfers.
  - 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.
  - 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.
  - International date handling, many different translations.
  - New User Manual and Help: A brand new user help has been 
    written which focuses on how to do tasks in conjunction 
    with a Tutorial and Concepts guide that gives the user 
    background information on using GnuCash.
  - Redesigned Menu's: The GnuCash menu's have been redesigned
    to conform more with the new GNOME Human Interface Guidelines.

Home Page:
http://gnucash.org/

Precompiled binaries:
http://www.gnucash.org/pub/gnucash/

Development versions:
http://www.gnucash.org/en/hacking.phtml

###############################
Upgrading from earlier versions
-------------------------------

There are many, many changes from the 1.6 series - have a look at the
NEWS file if you want more details. In particular:

- GnuCash now requires g-wrap 1.3.4 or better. See the "dependencies"
section of this file for more detail. 

- The data files are not able to be accessed by 1.6 once the new
features are used and saved, i.e. they are not backwards-compatible! 
So backup your data!

- The help documentation of gnucash has been moved to the separate
package gnucash-docs. If you see error messages like "URL not found"
when clicking on the "Help" menu item, you need to install the
separate package gnucash-docs.

We hope you enjoy all the new features!


############
Dependencies
------------

The following packages are required to be installed to run GnuCash:

  Gnome 1.4: see www.gnome.org for more information.

  guile: provides main extension language infrastructure, used
    extensively in GnuCash for initialization & startup. Requires
    version 1.3.4 or later.  Version 1.4 is noticeably speedier and is
    recommended if possible.  You can obtain source from
    ftp://ftp.gnu.org/pub/gnu/guile/guile-1.4.tar.gz

  slib: scheme libraries for guile. Need version slib2c4 or later.
    You can find source at
    http://swissnet.ai.mit.edu/ftpdir/scm/slib2d1.zip

  libpng: portable network graphics library. Any version.  You can
    find the source at
    ftp://swrinde.nde.swri.edu/pub/png/src/libpng-1.0.9.tar.gz.

  libjpeg: JPEG image handling library. Any version.  Sources can be
    found at ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz.

  libz: compression library. Any version.  You can find source at
    http://www.gzip.org/zlib.tar.gz.

  xpm: X Pixmap extension. Any version.  Normally distributed with an
   X installation.  By default this is part of XFree86 4.0 or better.
   You can also find this at
   ftp://ftp.x.org/contrib/libraries/xpm-3.4k.tar.gz.

  gnome-libs: version 1.2.0 or higher should work.  The latest
    version, 1.2.13, is of course recommended. These libraries
    require numerous other supporting libraries, such as gtk and glib.
    All of these can be found at ftp.gnome.org.

  gnome-print: any recent version should work, however problems have
    been reported with 0.28.  This is a part of GNOME as well. Sources
    at ftp://ftp.gnome.org/pub/GNOME/stable/sources/gnome-print

  gdk-pixbuf: any recent version should work.  This is typically
   distributed with GNOME.  Sources at
   ftp://ftp.gnome.org/pub/GNOME/stable/sources/gdk-pixbuf.

  gtkhtml: version 0.8 and later should work. You can obtain the latest
    version of gtkhtml from Helix Code.  Note that this has changed
    since 1.4, which used the older gtkxmhtml library.  Sources can be
    found at ftp://ftp.gnome.org/pub/GNOME/unstable/sources/gtkhtml/.

  guppi: version 0.35.3 should work.  Version 0.35.5 is required for
   some advanced functionality.  This can be found at
   ftp://ftp.gnome.org/pub/GNOME/stable/sources/Guppi.  You may need
   to configure it with `--prefix=/usr' in order for gnucash's
   `configure' to find the guppi library. Note: Version 0.40.3
   (released January 2002) has a problem with reversed legends in
   stacked barcharts. Since Guppi development has halted since that
   version, we can only provide a source code patch for Guppi 0.40.3
   that fixes this problem. You find that patch in
   lib/guppi-legend.patch.

  libgal: any recent version should work.  This is a GNOME related
   library used by several different programs.  You can find it at
   ftp://ftp.gnome.org/pub/GNOME/unstable/sources/gal/.

  libdb: Version 1.85 or a compatible version.

The above urls are from June 5, 2001.  Source locations can change,
but will likely be found near the same place (maybe moved from
unstable to stable).

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

  perl: Almost any version of perl5 should work.  I run perl-5.004 

In addition, some perl modules need to be installed. You can run
the script 'update-finance-quote' as root to obtain the latest
versions of required packages.

To use the new import features (OFX and HBCI) you need to obtain
the following;
  libofx: This library provide support for OFX file imports. 
    GnuCash-1.8.10 and newer needs at least the version libofx-0.7.0
    or newer. Sources can be found at
    http://sourceforge.net/projects/libofx/
  aqbanking/aqhbci: This library provide support for HBCI file imports. 
    GnuCash has mostly been tested against the 0.9.7 version, though
    any newer version should also work. Sources can be found at
    http://sourceforge.net/projects/aqbanking and
    http://sourceforge.net/projects/aqhbci/. More info in
    doc/README.HBCI.

#######
Running
-------

For GnuCash invocation details, see the manpage in doc/gnucash.1.
You can also run gnucash --help for the command line options.

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.  *.xac 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_BOOTSTRAP_SCM - the location of the initial bootstrapping scheme code.

  GUILE_LOAD_PATH - an override for the GnuCash load path, used when
  loading scheme files.  It should be a string in the same form as the
  PATH or LD_LIBRARY_PATH environment variable.

  GNC_MODULE_PATH - an override for the GnuCash load path, used when
  loading gnucash modules.  It should be a string representing a
  proper scheme list.  It should be a string in the same form as the
  PATH or LD_LIBRARY_PATH environment variable.

  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 many different languages. 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


#####################
Building & Installing
---------------------

(For additional build system details, see doc/README.build-system.)

GnuCash uses GNU Automake to handle the build process, so for most of
the details, see the generic instructions in INSTALL.  (If you are
building directory from CVS, read the README.cvs for more instructions.)
Below we detail the GnuCash specific bits.

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


  libtool: Available at ftp://ftp.gnu.org/gnu.
    RPM's and debs are widely available with most distributions.

  gnome development system: headers, libraries, etc.

  libxml: available from ftp.gnome.org

  g-wrap: RPM's, debs, and source available at 
          http://www.gnucash.org/pub/g-wrap.
          You should use g-wrap 1.3.4 or later.

  texinfo: If you are building from CVS, you need the GNU texinfo
           package, version 4.0 or later.

What you'll need to get and install in order to make sure you have all
of these pieces properly installed for your particular operating
system flavor will vary, but here's at least a partial list of what
you'll need for the systems we know about:

  Debian/GNU/Linux:
    current:
      libgnome-dev
      libgtkhtml-dev
      guile1.4
      libguile9-dev
      libguile9-slib


  SuSE:
    see doc/build-suse.txt

GnuCash understands a few non-standard ./configure options.  You
should run ./configure --help for the most up to date summary of the
supported options, but here are some more detailed descriptions of
some of them:

  --enable-opt-style-install

    GnuCash supports two types of install, the first is the normal
    /usr or /usr/local/ style, where the files are installed into
    /usr/bin /usr/lib, etc.  This is the default.

    The second style is the FSSTND, opt-style install.  In this style,
    all of the files are installed under a common subdirectory, often
    in /usr/local/opt, with the binaries going to
    /usr/local/opt/foo/bin, the libs going to /usr/local/opt/foo/lib,
    etc.  To request this style of install, just use the
    --enable-opt-style-install option to ./configure.

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

Note that while you need the Gnome libraries installed, you don't
need to have a Gnome desktop.  

Runtime and install destinations are separate.  The --prefix you
specify to configure determines where the resulting binary will look
for things at runtime.  Normally this determines where a "make
install" will put all the files.  However, automake also supports the
variable.  DESTDIR is used during the `make install' step to relocate
install objects into a staging area.  Each object and path is prefixed
with the value of `DESTDIR' before being copied into the install area.
Here is an example of typical DESTDIR usage:

     make DESTDIR=/tmp/staging install

   This places install objects in a directory tree built under
`/tmp/staging'.  If `/gnu/bin/foo' and `/gnu/share/aclocal/foo.m4' are
to be installed, the above command would install
`/tmp/staging/gnu/bin/foo' and `/tmp/staging/gnu/share/aclocal/foo.m4'.

DESTDIR can be helpful when trying to build install images and
packages.

NOTE: If you have installed different parts of Gnome in different
places (for instance, if you've installed gtkhtml in /usr/local) you
will need to set the environment variables GNOME_PATH and
GNOME_LIBCONFIG_PATH.  See the manpage for gnome-config for more
details.


###################
Supported Platforms
-------------------

GnuCash 1.8.x is known to work with the following operating systems:

GNU/Linux             -- x86, Sparc, PPC
Solaris		      -- Sparc
FreeBSD               -- x86
OpenBSD               -- x86
MacOS X		      -- PPC

Previous versions have been known to work on the following platforms, but
their current status is unknown:

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://www.gnucash.org/pub/gnucash (high-bandwidth)
or  http://linas.org/linux/gnucash (slow-www ) 
for precompiled (but *very old*) binaries for these platforms

GnuCash can probably be made to work with most POSIX-ish platforms, 
provided the libraries and toolchain are available.

#########################
Additional Download Sites
-------------------------

You can also download GnuCash from:

  - http://download.sourceforge.net/gnucash

You can download GnuCash Solaris packages from:

  - http://www.unixrealm.com/downloads/

You can get GnuCash Mandrake packages on Mandrake Cooker sites.


Precompiled binaries & pre-requisite packages can be found at the
following sites. The GnuCash versions here are all *extremely*
old, and were indeed from GnuCash's ancestor "x-accountant".

IBM AIX 4.1.5 
      -- SMIT-installable images 
      -- warning, this is from the 1.0 series of xacc
      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
      -- this is from the 1.0 series of xacc

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 -d :pserver:cvs@cvs.gnucash.org:/home/cvs/cvsroot checkout -r HEAD gnucash

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

  cvs -z3 -d :pserver:cvs@cvs.gnucash.org:/home/cvs/cvsroot checkout -r gnucash-1-8-branch gnucash


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

1. Read the file src/doc/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:

  This section has been removed to the file README.patches

  Please consult that file for details on using the script provided to make
  patches suitable for submitting to the GnuCash development team.


Thank you.