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://bitbucket.org/rafaelmartins/g-octave/issues/
.. _Mercurial: http://mercurial.selenic.com/

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_. It's capable to
generate ebuilds and Manifest files 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.

At this moment `g-octave`_ depends on the Portage_ package manager to works,
but the support to Paludis_ and pkgcore_ is planned.


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

`g-octave`_ have some basic dependencies:

* Python_ 2.6
* Portage_

`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, the eclass *octave-forge*, 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://files.rafaelmartins.eng.br/octave-forge/


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


Features
--------

Below is a list of features implemented or planned to the next releases.

* Selection of the packages by name-version **(done)**
* Selection of the packages by name (using the latest version available)
  **(done)**
* Creation of the ebuilds **(done)**
* Creation of the Manifest files **(done)**
* Creation of the overlay automatically **(done)**
* Installation of the packages **(done)**
* Update of the packages already installed
* Remotion of the installed packages **(done)**
* Installation of the packages with patches automatically **(done)**
* List the packages available to install **(done)**
* Show detailed info about a package **(done)**
* Supports multiple versions of the same package on the tree **(done)**
* The user can force the recreation of an ebuild **(done)**
* The user can force the recreation of the overlay **(done)**
* Resolution of the dependencies of packages from the Portage tree, based
  on the dependency list, provided by the maintainer of `g-octave`_ **(done)**
* Installation of multiple packages at once (not only the dependencies)
* Handle updates of the eclass and the auxiliary files automatically **(done)**
* Alert the user if the `g-octave`_ overlay is not appended to the
  PORTDIR_OVERLAY environment variable **(done)**
* Portage_ is supported **(done)**
* Paludis_ is supported
* pkgcore_ is supported
* Configuration file to the main settings */etc/g-octave.cfg* **(done)**
* Use colors on the CLI **(done)**
* The user can disable the use of colors on the CLI **(done)**
* Log `g-octave`_ actions to a file


To-Do
-----

We have other goals besides implementing the remaining features:

* Remove the unneeded dependency: pycolors **(done)**
* Remove the unneeded dependency: simplejson **(done)**
* Port to Python_ >= 3.0
* Improve the code comments
* Improve the error handling
* Improve the overlay management
* Write a man page **(done)**
* Convince upstream to distribute the package database
* Improve the use of `g-octave`_ as a normal user, with "--pretend"
* Improve the script that generates the package database
* Improve the details available on the packages list
* Write a testsuite
* more...


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.

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


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

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

Install the version 1.0.11 of *control*: ::

    # g-octave control-1.0.11

Remove the package *control*: ::

    # g-octave -C control

Get informations about the package *control*: ::

    # g-octave -i control
    
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_, please take a look at our missing
features and at the To-Do list. :)

`g-octave`_ ebuilds are available on the mercurial repository, or here:
http://overlay.rafaelmartins.eng.br/ (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 recreate only the affected ebuild.


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

You can get the sources here:
http://g-octave.rafaelmartins.eng.br/wiki/DownloadSources

or checkout the Mercurial_ repository using: ::
    
    $ hg clone http://hg.rafaelmartins.eng.br/g-octave/


Authors
-------

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