.. -*- 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|18.104.22.168|: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: firstname.lastname@example.org. Thanks.