1. Michael Forbes
  2. sandbox

Overview

HTTPS SSH
.. -*- 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.

Usage
=====

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) ``configuration.sh``: A configuration file.
   b) ``Dependencies.blacklist``: A list of dependencies to exclude.
   c) ``Recipes``: Add any customized recipes you need.

4) Run the ``bin/goborootless.sh`` command which will build the
   installation.
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.

Example
=======
Here is a complete example, copying the required files from
``Installs/template``::

  hg clone https://bitbucket.org/mforbes/gobo_install gobo_install
  cd gobo_install
  hg sum
  mkdir Installs/new_env
  cp -r Installs/template/* Installs/new_env/
  cd Installs/new_env/
  ../../bin/goboinstall.sh    # Takes about 1 minute.
  bash --init-file "build/environment.bash"
  MakeRecipe http://www.python.org/ftp/python/2.7/Python-2.7.tar.bz2
  n

  Compile Python 2.7

See below for a detailed play-by-play.

Recipes
=======
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 http://www.python.org/ftp/python/2.7/Python-2.7.tar.bz2``
* ``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 <http://recipes.gobolinux.org/r/>`_
* `Writing Recipes <http://gobo.kundor.org/wiki/Writing_Recipes>`_

Dependencies
============
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/configuration.sh``.  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:

http://bitbucket.org/mforbes/gobo_install

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

http://www.gobolinux.org/

A list of available recipes can be found here:

http://recipes.gobolinux.org/r/.

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

  $ hg clone https://bitbucket.org/mforbes/gobo_install 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 ``goboinstall.sh`` 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/goboinstall.sh    # Takes about 1 minute.
     You are about to create a Rootless environment at
     .../gobo_install/Installs/new_env/build
     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 http://www.python.org/ftp/python/2.7/Python-2.7.tar.bz2
     MakeRecipe: There is already a recipe for Python, at
     MakeRecipe: http://gobolinux.org/recipe-store/Python--3.1.2-r1--recipe.tar.bz2
     MakeRecipe: Use 'NewVersion Python 2.7' instead of MakeRecipe? [Y/n]
  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 www.python.org|82.94.164.162|: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
(http://www.macports.org/install.php) to bootstrap the installation.

The first step is to copy the configuration.sh.template file to a file
named configuration.sh residing in the same folder as the
goborootless.sh 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:
http://recipes.gobolinux.org/r/.

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 goborootless.sh. 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
recipes.

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:
gobolinux-users@lists.gobolinux.org. Thanks.