README

############################################################
GnuCash 2.4.x README file.
The last known stable series is the 2.4.0 series.
------------------------------------------------------------
##################
Table of Contents:
------------------
- Overview
- Dependencies
- Invocation/running
- Internationalization
- Building & Installing
- Supported Platforms
- Additional Download Sites
- Getting the Source via SVN
- 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://www.gnucash.org/
Precompiled binaries:
http://www.gnucash.org/pub/gnucash/
Development versions:
http://www.gnucash.org/en/hacking.phtml
############
Dependencies
------------
The following packages are required to be installed to run GnuCash:
[see README.dependencies]
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-2.0.0 and newer needs at least the version libofx-0.7.0
or newer. Sources can be found at
http://sourceforge.net/projects/libofx/
aqbanking: This library provide support for HBCI online actions.
#######
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 the "doc/examples" subdirectory. *.gnucash
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 catalogs exist for many different languages. These are
enabled with environment variables. For example,
Francais, in bash:
export LANG=fr_FR
Francais, in 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 SVN, read the README.svn 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
SWIG: 1.3.28 or later is needed. See http://www.swig.org or
http://sourceforge.net/project/showfiles.php?group_id=1645
(Note: g-wrap has been dropped completely in gnucash 2.2.0 and
is no longer needed.)
texinfo: If you are building from SVN, 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: see README.dependencies and
current:
libgnome-dev
libgtkhtml-dev
guile1.4
libguile9-dev
libguile9-slib
SuSE:
see README.dependencies
GnuCash understands a few non-standard ./configure options. You
should run ./configure --help for the most up to date summary of the
supported options.
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 2.0.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 Mandriva 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 Subversion
------------------------------
A read-only version of the svn tree is available on the net at:
http://svn.gnucash.org/repo/gnucash/
To get what used to be CVS HEAD (and now includes what used to be
gnucash-gnome2-dev), you will need to get the svn TRUNK:
svn checkout http://svn.gnucash.org/repo/gnucash/trunk gnucash
The argument "gnucash" above can be whatever you want your local
directory to be called, and is optional. If you leave it out,
you'll have a directory called "trunk" created containing all the
source code.
If you want the latest 2.0.x code, you'd need to pull from the
2.0 branch, as follows:
svn checkout http://svn.gnucash.org/repo/gnucash/branches/2.0 gnucash-2.0
##################
Developing GnuCash
------------------
Before you start developing GnuCash, you should do the following:
1. Read http://wiki.gnucash.org/wiki/Development
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 are two ways to submit a patch. First, if
you're using SVN and only made changes to existing SVN files you
can generate the patch using:
svn diff > /tmp/mypatch
and attach it to the appropriate bug or enhancement request in
Bugzilla (https://bugzilla.gnome.org). Create a new bug if you don't
find one that's applicable. Please don't submit patches to either of
the mailing lists, as they tend to be forgotten.
If your patch adds new files, use the `-N' flag to diff between a
clean directory and your development directory. E.g.
$ diff -urN {gnucash-pristine} {gnucash-mydevel} > /tmp/mypatch
Thank you.