Portage56k Readme
=================

Doc version: 0.1
Date:        20th February 2004
Author:      Andrew Roberts
Email:       dev@andy-roberts.net

Introduction
------------

This tool should only be of interest to anyone who is a Gentoo user, and
are currently restricted to 56k dial-up access to the Internet. It will
be assumed that the read has some familiarity with the Gentoo portage
system, and in particular, the 'emerge' tool. To be fair, I doubt you
could install Gentoo without being familiar with 'emerge'!

Only the most patient people would attempt to keep their Gentoo system
up-to date using a dial-up Internet connection. Wouldn't it be good if
it were possible to download any packages you wished to install/update
on another PC (which does have high-speed Internet access), burn to CD,
copy to original PC and then install?!

This is technically already possible. Using the emerge tool, type
'emerge -pf <package-name>'. Unfortunately, the output isn't that user
friendly, and for some reason, the output cannot be saved to file (not
even using shell redirection). Portage56k was therefore created to
rectify this issue. The goals are to provide a simple method for
obtaining the files required for package installation/upgrades; simple
downloading; and simple installing.

Installing
----------

Portage56k is only in its early stages. I have not yet managed to create
ebuilds for the tool. However, it's currently only a simple script, and
so is easy to install!

1) Download the tarball from http://portage56k.sourceforge.net/downloads/

2) Unpack the tarball:
   
   # tar xvfj portage56k-0.1.tar.bz2
   # cd portage56k-0.1

3) Ensure that the portage56k script has execute permissions. If not:

   # chmod 700 portage56k


Using portage56k
----------------

At the moment, portage56k is only very basic. It can currently retrive
the required files for any package you wish to upgrade/install. It
relies on emerge still being run with its output being redirected or
piped to portage56k. The output from portage56k is just a list of URLs.

1) # emerge -p <package-name> | portage56k > urls.txt

   (Of course, replace 'urls.txt' with any filename you wish)

2) Transport urls.txt to machine with fast Internet connection.

3) To download the files, you are free to use any tool that can connect
   to a FTP server and retreive files. I recommend using the 'wget' tool
   that can take a text file of URLs and download automatically.

   # wget -i urls.txt

   This is very useful if you need to download a lot of files. It would
   otherwise be very tedious to do it interactively with the standard
   'ftp' command!

4) Once all required files are downloaded, it is assumed that you have
   the means to copy them to some portable media. Burning to CD is the
   obvious choice. Instructions on how to use CD burning software will
   not be provided! The 'cdrecord' tool will do everything you need to
   do, and k3b is a decent frontend.

5) Bring files to original PC. Copy all downloaded files to
   /usr/portage/distfiles.

6) Finally, run the 'emerge' command (without the -p):

   # emerge <package-name>

   Emerge checks whether the files it needs are in the distfiles
   directory, if they are, then will proceed with compilation and
   merging. Otherwise, it will try to download.


Comments
--------

If you have any comments or spotted bugs, please contact
dev@andy-roberts.net.

Other Stuff
-----------

Portage56k is an open source project, licenced under the GPL.
Portage56k (C) 2004. Andrew Roberts