User Guide ========== This is an user guide with some instructions to the end-user. Installing g-Octave ------------------- The ebuilds for g-Octave will be available on the Portage tree as soon as possible. For now, they can be found on the Gentoo ``science`` overlay. 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 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 ``/etc/portage/package.keywords``:: app-portage/g-octave ** The live ebuild is only recommended for who want to help testing new features, or for developers. Stable users (with ``x86`` or ``amd64``) that wants to test the latest release will need to unmask the ebuild too, adding this to /etc/portage/package.keywords (e.g. for ``x86``):: app-portage/g-octave ~x86 The source code of g-Octave can be found in this Git repository: http://git.overlays.gentoo.org/gitweb/?p=proj/g-octave.git;a=summary You can clone the Git repository using this command (with Git installed, of course):: $ git clone git://git.overlays.gentoo.org/proj/g-octave.git The release tarballs can be found here: http://www.g-octave.org/releases/ 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 -------------------- Using the file ``/etc/g-octave.cfg`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you installed g-Octave correctly, you should find a configuration file at ``/etc/g-octave.cfg``. The main options are ``package_manager``, ``db`` and ``overlay``, that defines the package manager used by g-octave and the directory paths for the package database and the generated overlay, respectively. Other options are available. Please read the comments in the configuration file. 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. for example, ``GOCTAVE_OVERLAY`` will override the option ``overlay`` from the config file. Usage example:: # GOCTAVE_OVERLAY=/tmp/overlay g-octave -av packagename Enabling the logging feature ---------------------------- If you want to write some relevant stuff to a log file you can enable the logging feature, configuring the option ``log_level`` on the configuration. The available options are: ``debug``, ``info``, ``warning``, ``error``, ``critical``. You can change the location of the log file, using the option ``log_file``. The default is: ``/var/log/g-octave.log`` Make sure that the user running g-octave have write permissions to ``log_file``. Syncronizing the package database --------------------------------- Currently g-Octave depends on an external package database, in order to 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 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. Installing packages ------------------- From the upstream source tarballs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can list all the available packages using this command: :: # g-octave --list or :: # g-octave -l To install a package, use: :: # g-octave packagename or :: # g-octave packagename-version For example: :: # g-octave control-1.0.11 ``g-octave`` command-line tool supports some options for the installation of packages: ``-a`` or ``--ask`` 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: :: # g-octave --info packagename or :: # g-octave -i packagename From the octave-forge SVN repository ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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, 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 If you only want to install a single package, you can use the command-line option ``--scm``. 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 ``--no-scm``. Updating packages ----------------- You can update a package using this command: :: # g-octave --update packagename or :: # g-octave -u packagename If you want to update all the installed packages, run this without arguments:: # g-octave --update or :: # g-octave -u The options ``--ask`` and ``--verbose`` are also supported. Searching packages ------------------ You can do searches on the package names if you use the option ``-s`` or ``--search``. Regular expressions are allowed. :: # g-octave --search anything or :: # g-octave -s ^con Uninstalling packages --------------------- You can uninstall packages using this command: :: # g-octave --unmerge packagename or :: # g-octave -C packagename-version The options ``--ask`` and ``--verbose`` are also supported. Troubleshooting --------------- 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