diff options
authorRafael G. Martins <rafael@rafaelmartins.eng.br>2010-08-04 00:20:56 -0300
committerRafael G. Martins <rafael@rafaelmartins.eng.br>2010-08-04 00:20:56 -0300
commit596d154030123ca25dc160b17a8777e927466f3b (patch)
parentchanged the script contrib/manage_pkgdb.py to save the tree timestamp on (diff)
updated documentation
6 files changed, 207 insertions, 106 deletions
diff --git a/docs/conf.py b/docs/conf.py
index 9a7353c..0d4cd09 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -45,9 +45,9 @@ copyright = u'2010, Rafael Goncalves Martins'
# built documents.
# The short X.Y version.
-version = '0.3'
+version = '0.4'
# The full version, including alpha/beta/rc tags.
-release = '0.3'
+release = '0.4'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@@ -93,7 +93,7 @@ highlight_language = 'text'
# The theme to use for HTML and HTML Help pages. Major themes that come with
# Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'default'
+html_theme = 'nature'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
diff --git a/docs/development.rst b/docs/development.rst
index 8e3feb5..cd0610e 100644
--- a/docs/development.rst
+++ b/docs/development.rst
@@ -2,7 +2,13 @@ Development
:Source code: http://git.overlays.gentoo.org/gitweb/?p=proj/g-octave.git
-:Bugs to: rafael [at] rafaelmartins [dot] eng [dot] br
+:Bugs to: http://www.g-octave.org/trac/newticket
+.. warning::
+ This section of the documentation is supposed to be used by g-Octave
+ developers. End-users should not need to read this!
Running the test suites
@@ -11,44 +17,105 @@ You can run the tests suites using the script ``run_tests.py`` that can be
found in the directory ``scripts`` in the recent `source tarballs`_ or
in the `Git repository`_
-.. _`source tarballs`: http://soc.dev.gentoo.org/~rafaelmartins/g-octave/
+.. _`source tarballs`: http://www.g-octave.org/releases/
.. _`Git repository`: http://git.overlays.gentoo.org/gitweb/?p=proj/g-octave.git
$ scripts/run_tests.py
-If some test is broken, report me a bug by email. The bug tracker is
-temporary disabled.
+If some test is broken, please use the `bug tracker`_.
+.. _`bug tracker`: http://www.g-octave.org/trac/newticket
+Working on the package database
+Package databases are Git repositories with the DESCRIPTION files, patches
+and a ``info.json`` file with the non-octave dependencies and the licenses
+of the packages.
+We're using github to host the package database:
-Creating source tarballs from the octave-forge SVN repository
+If you want to fix something on the package database, please fork the
+repository, change it and fill a merge request.
+Updating the package database
+We have a script to update the package database: ``contrib/manage_pkgdb.py``.
+You just need to clone the git repository and create a directory to store
+the source tarballs, that are used to extract the DESCRIPTION files and
+build the package database.
+g-Octave will install the script on ``/usr/share/g-octave/contrib``
-We have a script to create source tarballs for all the packages,
-using the latest stable revision from the octave-forge SVN repo.
+ $ git clone git+ssh://git@github.com:your_username/g-octave-db.git
+ $ mkdir tarballs
+ $ /usr/share/g-octave/contrib/manage_pkgdb.py tarballs g-octave-db
-To use it, add a ``pkg_cache`` option to your configuration file with
-the directory where you want to save the generated tarballs and, after
-clone the Mercurial repository or download the source tarball, run from
-the root of the source tree::
+The first parameter of the script is the path to the directory that will
+store the tarballs. The second parameter is the path to the local clone
+of your forked git repository.
- $ scripts/package_sources.py
+Updating the list of external dependencies and licenses
-Creating a package database from the previously created source tarballs
+We have a script to update the JSON file that contains the external
+dependencies (non-octave packages from the portage tree) and the licenses
+(the license names used by the octave-forge developers doesn't matches
+with the names used on the Portage tree).
-You should want to also create a package database. For this, keep the
-``pkg_cache`` option in your configuration file pointing to the directory
-with your source tarballs and run from the root of the source tree::
+This script will be also installed on ``/usr/share/g-octave/contrib``
+ $ /usr/share/g-octave/contrib/manage_info.py g-octave-db/info.json
+The script is interactive and the argument is the path to the ``info.json``
+file, that lives on the root of the Git repository of the package database.
+The script will suggest some matches for each dependency. For the licenses
+you need to find the best match at the directory ``${PORTDIR}/licenses``,
+where ${PORTDIR} is the path to your Portage tree (``/usr/portage``
+Commiting the changes
+You can use the script ``manage_pkgdb.py`` to commit the changes::
+ $ /usr/share/g-octave/contrib/manage_pkgdb.py --commit tarballs g-octave-db
+The script will do a last check on your updates and commit the stuff to
+your fork repository.
+Using your fork as package database
+If you want to use your fork as package database, change the variable
+``db_mirror`` on the file ``/etc/g-octave.cfg`` to something like::
+ db_mirror = github://your_username/g-octave-db
- $ scripts/package_database.py /path/to/your/new/database.tar.gz
+Sending patches to the source code
-Sending patches
+The source code of g-Octave lives on a repository on the Gentoo Linux
+infrastructure. ::
-You can send git formated patches to me via email.
+ $ git clone git://git.overlays.gentoo.org/proj/g-octave.git
-More information will be available soon.
+You can change what you need, commit, generate a Git-formated patch and
+attach it to a new ticket on our `bug tracker`_.
diff --git a/docs/index.rst b/docs/index.rst
index 2a1df26..95ccc93 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -7,8 +7,10 @@ Welcome to g-Octave's documentation!
:Author: Rafael Goncalves Martins
-:Source code: http://git.overlays.gentoo.org/gitweb/?p=proj/g-octave.git
-:Bugs to: rafael [at] rafaelmartins [dot] eng [dot] br
+:Website: http://www.g-octave.org/
+:Source code: http://www.g-octave.org/trac/browser
+ http://git.overlays.gentoo.org/gitweb/?p=proj/g-octave.git
+:Bugs to: http://www.g-octave.org/trac/newticket
:Version: |release|
.. topic:: Overview
@@ -36,5 +38,6 @@ Contents
+ upgrading
diff --git a/docs/tinderbox.rst b/docs/tinderbox.rst
index 5141bf6..6f51502 100644
--- a/docs/tinderbox.rst
+++ b/docs/tinderbox.rst
@@ -2,13 +2,13 @@ Tinderbox
g-Octave provides a script to run build tests for all the octave-forge
-packages. This script is not intended to be used by end-users, only
+packages automatically and report issues to the `bug tracker`_.
-.. topic:: Warning!
+.. _`bug tracker`: http://www.g-octave.org/trac/report/9
- The automated bug reports are broken right now, because the Trac instance
- is currently offline and being moved to the Gentoo Linux infrastructure.
+.. warning::
+ This script is not intended to be used by end-users, only developers.
Creating the environment
@@ -37,7 +37,9 @@ You may also need some files from ``/etc/portage``
Mounting filesystems/directories
-You should mount your current ``/usr/portage`` inside the chroot dir::
+You should mount your current ``${PORTDIR}`` (e.g. ``/usr/portage``)
+inside the chroot dir (the script will force the use of Portage to build
+the packages)::
# mkdir /home/user/g-octave/usr/portage
# mount -o bind /usr/portage /home/user/g-octave/usr/portage
@@ -65,54 +67,24 @@ Updating the packages and installing the dependencies
# emerge -avuDN system
- # emerge -av mercurial pycurl
-Getting the source code
-Using the Git repository::
- # cd
- # git clone git://git.overlays.gentoo.org/proj/g-octave.git
- # cd g-octave
-Using the source tarball::
- # cd
- # wget http://files.rafaelmartins.eng.br/distfiles/g-octave/g-octave-<VERSION>.tar.gz
- # tar xvzf g-octave-<VERSION>.tar.gz
- # cd g-octave-<VERSION>
+ # USE="git" emerge -av layman
+ # layman -a science
+ # FEATURES="test" USE="sync" emerge -av g-octave
Configuring g-Octave
- # cp etc/g-octave.cfg /etc
-.. topic:: Warning!
- This is currently broken!
-You should edit the file ``/etc/g-octave.cfg`` and append the lines below
-(with your data)::
+You should `create an account`_ on the `g-Octave project page`_, edit the
+file ``/etc/g-octave.cfg`` and append the lines below (with your data)::
trac_user = username
trac_passwd = password
-For this you'll need to register_ at the `g-Octave project page`_, in order
-to be able to create new tickets and attachments.
+.. _`create an account`: http://www.g-octave.org/trac/register
+.. _`g-Octave project page`: http://www.g-octave.org/trac/
-.. _register: http://g-octave.rafaelmartins.eng.br/register
-.. _`g-Octave project page`: http://g-octave.rafaelmartins.eng.br/
-Now you need to add the g-octave overlay to the Portage configuration file
-``/etc/make.conf`` (use the same overlay path from ``/etc/g-octave.cfg``)::
- # echo 'PORTDIR_OVERLAY="/usr/local/portage/g-octave ${PORTDIR_OVERLAY}" >> /etc/make.conf
+Now you're done with the configuration.
Running the script
@@ -120,22 +92,23 @@ Running the script
Update the package database::
- # ./scripts/g-octave --sync
+ # g-octave --sync
-Run the test suites::
+Make sure that you have activated all the ``USE`` flags needed on octave::
- # ./scripts/run_tests.py
+ # emerge -vp octave
-Make sure that you have activated all the ``USE`` flags needed by octave::
+And build it first::
- # emerge -vp octave
+ # emerge octave
-Run the script::
+Now that you already have the main dependency of the packages installed
+and g-Octave configured, you can run the script::
- # ./scripts/tinderbox.py
+ # /usr/share/g-octave/contrib/manage_pkgdb.py
-At the end, the script should uninstall all the octave-forge packages
-directly installed. If you want to remove the dependencies, run::
+The packages are installed with the ``--oneshot`` option. To remove them
+with the dependencies, run::
# emerge -av --depclean
diff --git a/docs/upgrading.rst b/docs/upgrading.rst
new file mode 100644
index 0000000..a21b1e9
--- /dev/null
+++ b/docs/upgrading.rst
@@ -0,0 +1,24 @@
+Upgrading g-Octave
+Quick notes for users upgrading from older versions of g-Octave.
+From ``0.3`` to ``0.4``
+This version broke the compatibility with old package databases and some
+external files.
+You'll need to remove the directories of the package database and the
+overlay (``db`` and ``overlay`` options from the configuration file).
+To know what are the current values, type::
+ $ g-octave --config db
+ $ g-octave --config overlay
+And remove both directories!
+If you installed g-Octave with ``USE="-sync"``, please remove those
+directories before run ``emerge --config g-octave``.
diff --git a/docs/userguide.rst b/docs/userguide.rst
index 252818b..d4ee524 100644
--- a/docs/userguide.rst
+++ b/docs/userguide.rst
@@ -1,8 +1,7 @@
User Guide
-This is a small user guide for g-Octave, with some instructions to the
-end user.
+This is an user guide with some instructions to the end-user.
Installing g-Octave
@@ -14,15 +13,15 @@ To install it with ``layman`` and ``git`` installed, type::
# layman -a science
After you have the overlay installed, you can install the package, using: ::
# emerge -av app-portage/g-octave
-We have 2 ebuilds, one for the latest stable release (for ``~x86`` and ``~amd64``)
-and one live ebuild, that installs g-Octave from the mercurial repository
-(without keywords). If you want to use the live ebuild, you need to unmask
-this ebuild, adding the line below to ``/etc/portage/package.keywords``::
+We have 2 ebuilds, one for with latest stable release (for ``~x86`` and
+``~amd64``) and one live ebuild, that installs g-Octave from the Git
+repository (without keywords). If you want to use the live ebuild, you
+need to unmask them adding the line below to your
app-portage/g-octave **
@@ -46,7 +45,18 @@ installed, of course)::
The release tarballs can be found here:
+USE flags
+g-Octave have 2 USE flags:
+- ``doc``: Install this documentation. Depends on ``dev-python/sphinx``.
+- ``sync``: Enable the ``--sync`` command-line option. Available only
+ on the ebuilds of stable releases. The live ebuild will enable this
+ feature by default.
Configuring g-Octave
@@ -71,8 +81,8 @@ Using environment variables
All the options from the configuration file can be overrided with environment
variables. The environment variable name starts with ``GOCTAVE_`` and
-ends with the option name in uppercase. e.g. ``GOCTAVE_OVERLAY`` will
-override the option ``overlay`` from the config file.
+ends with the option name in uppercase. for example, ``GOCTAVE_OVERLAY``
+will override the option ``overlay`` from the config file.
Usage example::
@@ -97,8 +107,9 @@ Syncronizing the package database
Currently g-Octave depends on an external package database, in order to
-create the ebuilds for the packages. You'll need to fetch this database
-in the first time that you run g-Octave: ::
+create the ebuilds for the packages (only if you installed g-Octave with
+``USE="-sync"``). You'll need to fetch this database in the first time
+that you run g-Octave (and whenever you want to updates): ::
# g-octave --sync
@@ -112,21 +123,21 @@ g-octave can use all the 3 package managers available on Gentoo Linux:
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
+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.
+**Portage** works out of the box.
Installing packages
-From the stable source tarballs
+From the upstream source tarballs
You can list all the available packages using this command: ::
@@ -155,6 +166,9 @@ of packages:
Ask before install the package
``-p`` or ``--pretend``
Only pretend the installation of the package
+``-1`` or ``--oneshot``
+ Do not add the packages to the world file for later updating.
You can get some information about the package using this command: ::
@@ -168,20 +182,22 @@ or ::
From the octave-forge SVN repository
-If you want to test some new feature, or to use the new version of the
-packages ever, you'll like to install your packages directly from the
+If you want to test some new feature or to always use the newest version
+of the packages, you'll like to install the packages directly from the
SVN repository.
-To install a package from SVN, type::
+To install a package from SVN, you'll need to configure g-Octave, changing
+the value of the variable ``use_scm`` on the file ``/etc/g-octave.cfg``
+to ``true``. After that, type::
- # g-octave packagename-9999
+ # g-octave packagename
-All the common g-octave options for install packages are allowed, and
-the special version ``9999`` says to g-octave that you want to use the
-SVN version.
+If you only want to install a single package, you can use the command-line
+option ``--scm``.
-In order to be able to install packages from svn you need to install
-g-octave with the USE flag ``svn`` enabled.
+If you enabled the installation from SVN on the configuration file and
+wants to install a stable version, you can use the command-line option
Updating packages
@@ -231,3 +247,21 @@ or ::
# g-octave -C packagename-version
The options ``--ask`` and ``--verbose`` are also supported.
+Some times the generated ebuilds can be broken for some reason. To fix
+this you can use the command-line option ``--force``, that will rebuild
+the ebuild or the command-line option ``--force-all``, that rebuild the
+entire overlay.
+If you got some problem with corrupted sources, please remove the tarball
+from the ``${DISTDIR}`` and run::
+ # g-octave --force packagename
+If you still have problems, please fill a ticket on our `bug tracker`_
+.. _`bug tracker`: http://www.g-octave.org/trac/newticket