CPAN

Comprehensive Perl Archive Network (CPAN) is the default tool to manage perl programs and modules on your computer. Because GnuCash uses the perl module Finance::Quote to get online quotes for commodities, it can be useful to have some knowledge of this tool beneath the Gnucash specific gnc-fq-* scripts.

Preface

Annotation

Currently this page shows the typical linux commands. The call or whole proceeding may vary for other OSes. Feel free to add them.

Abbreviations: gnc-fq-* scripts

In many cases there is no need to run cpan directly. GnuCash is shipped with a set of perl scripts, which will do the most usual things for you:

• Check and update your F::Q installation
  • gnc-fq-check: A list of quote sources supported by Finance::Quote, or the single term missing-lib if finance quote could not be executed.
  • gnc-fq-update: installs or updates Finance::Quote and its dependencies (using cpan)
• Check your commodities
  • gnc-fq-dump: obtains information from Finance::Quote about any specified stock, and then dumps it to the screen in annotated form.

  This will allow someone to see what is returned, and whether it provides all the information needed by Gnucash.

  • gnc-fq-helper: present a scheme interface to Finance::Quote

If they solve your problem, there is no need to read further.

Using CPAN

Caution: Root Access

Because you usually use this tool to update system libraries, it needs root/superuser/administrator access. So you should prefix the command by the command sudo which will ask you for the root password - at least on unixoid systems - or run it in a root shell which can be reached by entering su in a normal shell. (FIXME: and Windows?)

First Run: Configuration

On the first run, cpan needs some configuration

> sudo cpan
root's password:

CPAN.pm requires configuration, but most of it can be done automatically.
If you answer 'no' below, you will enter an interactive dialog for each
configuration option instead.

Would you like to configure as much as possible automatically? [yes] 

In the following section you can usually just press the <enter> key to get a good result.

Overview

cpan --help

shows you the usage. For more details run

 perldoc -F /usr/bin/cpan

Check your F::Q Installation

cpan -D Finance::Quote

will show you the details of your F::Q module:

Finance::Quote
-------------------------------------------------------------------------
        Fetch stock prices over the Internet
        E/EC/ECOCODE/Finance-Quote-1.17.tar.gz
        /usr/lib/perl5/vendor_perl/5.14.2/Finance/Quote.pm
        Installed: 1.17
        CPAN:      1.17  up to date
        David Hampton (HAMPTON)
        hampton@employees.org

Now you know the following:

• Your version is the latest published.

• If not, you should update it before trying to manually patch something.

• The path to the library, if you need to update single modules.

Other

For the Quartz version of OSX' the commands to update fq':

sudo perl -MCPAN -e shell
sudo /Applications/Gnucash.app/Contents/Resources/bin/gnc-fq-update

Or double-click on the "FinanceQuote Update" applet in the Gnucash dmg.

Note that CPAN requires 'make' and a compiler. Depending upon your OSX version, you may need to install some extra software:

• On OSX 10.9 (Mavericks), just launch CPAN. When it needs to build something, OSX will prompt you to install the command line tools. You'll need to re-run your cpan command (just push the up-arrow key in Terminal, then <return>) when it finishes.
• On OSX 10.6 (Snow Leopard), 10.7 (Lion), and 10.8 (Mountain Lion), install Xcode, a free download from the App Store. In XCode Preferences, select "Downloads" and the "command line tools" component. Once it's installed you can run CPAN.
• On OSX 10.5 (Leopard), you'll need to find your distribution DVD and install Xcode from that. Command line tools are installed automatically by default.
• Gnucash doesn't support earlier versions of OSX. Sorry.