.. -*- rst -*- -*- restructuredtext -*-

.. This file should be written using the restructure text
.. conventions.  It will be displayed on the bitbucket source page and
.. serves as the documentation of the directory.

README for gobo_install

This package simplifies the process of getting a GoboRootless
installation up and running.  It uses configurations specified in the 
``Installs`` directory to define and build custom compile environments.


1) Download and unpack this package into a directory (``gobo_install``
   in the example below.)
2) Make a directory ``Installs/new_env`` (choose whatever name you
   want).  Below we copy the ``Installs/template`` directory as a
   starting example.
3) Modify the following files in ``Installs/new_env`` as needed:

   a) ````: A configuration file.
   b) ``Dependencies.blacklist``: A list of dependencies to exclude.
   c) ``Recipes``: Add any customized recipes you need.

4) Run the ``bin/`` command which will build the
5) Source the file ``Install/<env_name>/build/environment.bash`` to
   start using the new installation.

Now you can try installing stuff from previously existing Gobo
recipes, or you can edit or make your own recipes.

Here is a complete example, copying the required files from

  hg clone gobo_install
  cd gobo_install
  hg sum
  mkdir Installs/new_env
  cp -r Installs/template/* Installs/new_env/
  cd Installs/new_env/
  ../../bin/    # Takes about 1 minute.
  bash --init-file "build/environment.bash"

  Compile Python 2.7

See below for a detailed play-by-play.

To install new software, you can first try to install it from an
existing recipe using the ``Compile`` command::

  Compile Python 2.7

If a suitable recipe does not exist, then you can edit/update an
existing recipe or create a new one from a source distribution:

* ``EditRecipe Python 2.7``
* ``MakeRecipe``
* ``UpdateRecipe`` 

These will install the new recipe in ``Install/new_env/Recipe`` where
you can inspect and customize it as required.  For more details see:

* `List of recipes <>`_
* `Writing Recipes <>`_

The original intent of Gobo_ was to provide a complete linux
distribution.  As such, it generally tries to install all of the
required dependencies.  For a rootless installation this is
undesirable.  Instead, we try to make use of existing programs.  The
file ``Installs/new_env/Dependencies.blacklist`` should contain a list
of programs that need not be installed because the exist on the system
outside of the current installation.  Note that some of the programs
are required to support GNU specific conventions.  On the Mac OS X
platform this is especially a problem.

The install script attempts to locate these programs using the paths
specified in ``Installs/new_env/``.  Note that are
several paths here including some that specify tools only needed by
the install scripts, and other specifying programs that should be
included as part of the final environment.

One option for dealing with dependencies is to link the appropriate
programs to the ``Installs/new_env/build/sbin`` directory.  This
allows you to clean the path, thereby better controlling the
dependencies in the environment.

Further Information
Further information about this particular set of install scripts can
be found at the project homepage:

Details about the general Gobo Linux distribution can be found here:

A list of available recipes can be found here:

Example Details
Here is a play by play of the example given earlier.  First we
checkout the ``gobo_install`` package and check the version

  $ hg clone gobo_install
     requesting all changes
     updating to branch default
     99 files updated, 0 files merged, 0 files removed, 0 files unresolved
  $ cd gobo_install
  $ hg sum
     parent: 27:9ab928efc98e tip

Now we make a new directory in the ``Installs`` folder for our new
environment which we call ``new_env``.  We copy the ``template`` files
into this as a starting point::

  $ mkdir Installs/new_env
  $ cp -r Installs/template/* Installs/new_env/

Now we go into this directory and run the ```` script.
This takes about a minute and downloads a few essential components, as
well as sets up the environmental files, locates some locally
installed programs etc.::

  $ cd Installs/new_env/
  $ ../../bin/    # Takes about 1 minute.
     You are about to create a Rootless environment at
     Creating ...
     To start the new_env environment start a shell as follows:
       bash --init-file ".../gobo_install/Installs/new_en

Now we can start a new shell with the Gobo environment.  This is how
you should use the environment in the future as well.::

  $ bash --init-file "build/environment.bash"
  new_env: $

Notice the new prompt.  Now let's try to create a new recipe for
Python 2.7 based on the source distribution::

  new_env: $ MakeRecipe
     MakeRecipe: There is already a recipe for Python, at
     MakeRecipe: Use 'NewVersion Python 2.7' instead of MakeRecipe? [Y/n]
     MakeRecipe: Creating recipe template for Python version 2.7.
     MakeRecipe: Press Enter to continue or Ctrl-C to cancel.

     MakeRecipe: Please fill up 'compileRecipeAuthor'...
     Connecting to||:80... connected.
     Saving to: `Python-2.7.tar.bz2'
     MakeRecipe: Python 2.7 build system seems to be based on Autoconf.

Note that ``MakeRecipe`` found a recipe for Python 3.1 and though I
might want to use that instead.  I declined.  If you are going to edit
recipes and contribute them back to Gobo, then you should fill out the
`compileRecipeAuthor` field as requested so you get credit.  Gobo next
downloads the source package (the download directory is linked to
``/tmp/gobo_archive/`` so that you don't download multiple sources if
you have several different environments.  You can customize this.)  It
then inspects the package and informs that it has discovered a typical
``Autoconf`` build setup.

This creates a Python recipe for you::

  new_env: $ ls Recipes/Python/2.7
     Resources  Recipe

Now we can compile this::

  new_env: $ Compile Python 2.7
     Compile: Found recipe for Python 2.7
     GetRecipe: Trying to get .../gobo_install/Installs/new_env/build/Files/Compile/LocalRecipes/Python/2.7

This runs the standard ``configure; make; make install`` sequence plus
some additional sym-linking etc. so that the programs are found
properly by the Gobo environment.  Now we can run the program::

  new_env: $ python
     Python 2.7 (r27:82500, Jul  8 2010, 19:22:53) 
     [GCC 4.1.2 20080704 (Red Hat 4.1.2-48)] on linux2
     Type "help", "copyright", "credits" or "license" for more information.

Old README File:  Some things have been changed.

Currently Mac OS X 10.5 Leopard and Ubuntu 9.10 Karmic Koala
have been tested. Mac OS X requires MacPorts
( to bootstrap the installation.

The first step is to copy the file to a file
named residing in the same folder as the script. Alternatively, pass the -c <configuration
file> option to specify a configuration file residing in a different
location. You can customize the programs to be installed by editing
the configuration file. The list of available programs is here:

The next step is to cd to the folder where you want to install
GoboRootless (the installer will create a folder called "GoboRootless"
inside this folder) and execute Alternatively, pass
the -i <install folder> option to install GoboRootless inside a
specific folder.

You can override the default GoboLinux recipes by passing the -r
<recipes folder> option. The recipes folder should contain your custom

Passing the -h option will print a brief help message containing a
summary of the available options.

Please send any feedback to the GoboLinux Users mailing list: Thanks.