path: root/README.rst

.. _`GNU Octave`: http://octave.org/
.. _`Octave-Forge`: http://octave.sf.net/
.. _`g-octave`: http://g-octave.rafaelmartins.eng.br/
.. _Python: http://python.org/
.. _Portage: http://www.gentoo.org/proj/en/portage/ 
.. _Paludis: http://paludis.pioto.org/
.. _pkgcore: http://www.pkgcore.org/
.. _`Gentoo Linux`: http://www.gentoo.org/
.. _`issue tracker`: http://g-octave.rafaelmartins.eng.br/report
.. _Git: http://git-scm.com/
.. _PySVN: http://pysvn.tigris.org/

g-octave
========

Introduction
------------

What is GNU Octave?
~~~~~~~~~~~~~~~~~~~

`GNU Octave`_ is a high-level language, primarily intended for numerical
computations. It provides a convenient command line interface for solving
linear and nonlinear problems numerically, and for performing other numerical
experiments using a language that is mostly compatible with Matlab.
It may also be used as a batch-oriented language.


What is Octave Forge?
~~~~~~~~~~~~~~~~~~~~~

`Octave-Forge`_ is a central location for the collaborative development of
packages for `GNU Octave`_.

The `Octave-Forge`_ packages contains the source for all the functions and
are designed to work with the `GNU Octave`_ package system. 


What is g-octave
~~~~~~~~~~~~~~~~

`g-octave`_ is a tool that generates and installs ebuilds for `Octave-Forge`_
packages "on-the-fly" to `Gentoo Linux`_, using Portage_, Paludis_ or pkgcore_.
It's capable to generate ebuilds and Manifest files (if needed)
for the packages, and to install them using an autogenerated overlay (named
g-octave). `g-octave`_ can also handle patches to the packages automatically.
The command line interface tries to be very similar to the interface of the
**emerge** tool.


Dependencies
------------

`g-octave`_ have some basic dependencies:

* Python_ 2.6
* Portage_
* PySVN_ (optional)
* Paludis_ (optional)
* pkgcore_ (optional)

`g-octave`_ also depends on some files, distributed by the maintainer,
like the package database (a tarball with the DESCRIPTION file of all
the packages), a file with the dependencies and the blacklist, a tarball
with the patches and a file that list the updated files.

These files are needed because upstream don't ship a package database
(they only distribute a tarball with the sources of all the packages, so
we have a script that create the database using this tarball) and because
we don't want to do a new release every time that the eclass is changed
or that a new patch is added. All these files are automatically fetched
by `g-octave`_

At this time, these files are here:
http://soc.dev.gentoo.org/~rafaelmartins/g-octave/db/


Settings
--------

All the settings are centralized on the file */etc/g-octave.cfg*. Please
read the comments and change what you need. The recommendation is to keep
everything as it is. :)

You can also use environment variables to configure `g-octave`.

http://soc.dev.gentoo.org/~rafaelmartins/g-octave/docs/latest/userguide/#configuring-g-octave


Configuring your package manager
--------------------------------

g-octave can use all the 3 package managers available on Gentoo Linux:
**Portage**, **Paludis** and **Pkgcore**.

You just need to setup the option `package_manager` with the lowercase
name of the package manager: `portage`, `paludis`, `pkgcore`.

If you're using Paludis or Pkgcore, you'll need to configure the overlay
in your package manager configuration files. Please check the documentation
of your package manager:

- Paludis: http://paludis.pioto.org/
- Pkgcore: http://www.pkgcore.org/

Portage works out of the box.


CLI options
-----------

*--version*
    show program's version number and exit

*-h, --help*
    show this help message and exit

*-l, --list*
    show a list of packages available to install and exit

*-i, --info*
    show a description of the required package and exit

*-p, --pretend*
    don't (un)merge packages, only create ebuilds and solve the dependencies

*-a, --ask*
    ask to confirmation before perform (un)merges

*-v, --verbose*
    Portage makes a lot of noise.

*-u, --update*
    try to update a package or all the installed packages

*-s, --search*
    search for packages with some term on the name (regular expressions allowed)

*-C, --unmerge*
    try to unmerge a package instead of merge

*-f, --force*
    forces the recreation of the ebuilds

*--force-all*
    forces the recreation of the overlay and of the ebuilds

*--no-colors*
    don't use colors on the CLI

*--sync*
    search for updates of the package database, patches and auxiliary files

*--config*
    return a value from the configuration file (/etc/g-octave.cfg)


Usage Examples
--------------

Install the latest version of *control*: ::
    
    # g-octave control

Install the version 0.3.1 of *control*: ::

    # g-octave control-0.3.1

Upgrade to latest version available of *control*: ::
    
    # g-octave -u control

Remove the package *control*: ::

    # g-octave -C control

Get informations about the package *control*: ::

    # g-octave -i control

To install the package *control* from the octave-forge SVN repository: ::
    
    # g-octave control-9999
    
The options *verbose*, *ask* and *pretend* are passed to **emerge**.


How can I help?
---------------

The users can help testing and reporting bugs in our `issue tracker`_.
If you can help programming in Python_ you're always welcome. :)

`g-octave`_ ebuilds are available on the Git repository, or the
Gentoo science overlay.


Warning
-------

If you experienced some random errors when installing packages, please
retry, using the option *--force-all*, and report the issue to us.
If you don't want to lose all your ebuilds, you can try to use the option
*--force*, that will re-create only the affected ebuild.


Download Page
-------------

You can get the sources here:
http://soc.dev.gentoo.org/~rafaelmartins/g-octave/releases/

or clone the Git_ repository using: ::
    
    $ git clone git://git.overlays.gentoo.org/proj/g-octave.git


Authors
-------

Rafael Goncalves Martins *<rafael at rafaelmartins dot eng dot br>*