README file for easibox
=======================

By Philip Hunt, last altered 12-Jan-2004.
For Easibox version 0.3.0

Easibox's home page is 
<http://www.cabalamat.org/oss/easibox/intro.html>.

You can read about developments of Easibox on my weblog at 
<http://www.cabalamat.org/weblog/current_easibox.html>.

My email address is available from <http://www.cabalamat.org/>.


What is easibox?
----------------

Easibox is a utility for building distribution archives (that is,
tar files, zip files and other archive files).

Easibox is licensed under the GNU General Public License; see
file COPYING for details.

Easibox was written to solve a problem I had when releasing open
source software packages, such as my Leafwa program. The technique
I was using was manually creating a directory with the required
filename (such as "leafwa-0.6.1"), copying those files to be
archived into the directory, and then cd'ing to that directory's
parent and running tar to create the tarball. I found this
process time-consuming and error-prone. So I decided there must
be a better way...

My solution was this program ``easibox'' which decides what files
it will put in the archive, what sort of archive files will be
created, and other parameters, based on the contents of a
configuration file in the project directory. The configuration file
is read in by the Python interpreter; this means that it uses
Python syntax (so you don't have to learn another file type) and
that you can put Python program statements in it. 


How to install easibox
----------------------

Firstly, note that easibox is written in Python, and you must
have Python version 2.0 or greater installed on your machine.

Then you must get the easibox tarball and untar it. Since you are
reading this file, you've probably already done that.

Now you must put the directory containing the easibox executable
in your path. If you are using bash, the way to do this is to add
a line in your ~/.bashrc file of the form:

   export PATH=$PATH:/your/easibox/directory/here
   
Now easibox is installed and ready to run. 

(With one minor exception: any shell which was created before you
altered your .bashrc won't know about the changes. To get round
this, from such a shell you can enter:

   $ . ~/.bashrc
   $ rehash 
   
but it's probably easier to just create a new shell)


How to use easibox
------------------

In this example I will assume you are developing a project 'superfoo', 
which is held in the directory ~/superfoo/ and some subdirectories.

I also assume that you develop other projects as well. All your
projects will have their current and past archive files put in
directory ~/archive/ . Furthermore, some of your users like .tar.gz
files and others prefer .zip files; you want to please both sets of
users.

To tell easibox this, you must put this in a configuration
file:
--------------------------------------------------
boxFormats = ['tar.gz', 'zip']
archiveDestination = "~/archive/"
--------------------------------------------------

The configuration file can be put in /etc/easiboxrc (in which
case it applies to all users on the machine) or, alternately,
in ~/.easiboxrc (in which case it just applies to you). If both
files exist, any setting in ~/.easiboxrc take precedence.

~/superfoo/ = contains the README file and a few other introductory
   files
   
~/superfoo/src/ = contains various *.c and *.h source files. Also
   contains a Makefile. After compilation contains some *.o
   files and a 'superfoo' executable
   
~/superfoo/doc/ = contains various documentation files

~/superfoo/temp/ = various temporary files, not for distribution

You want the distribution to contain:

* Everything in the ~/superfoo/ directory.
  
* Everything in the ~/superfoo/doc/ directory, except the file
  "MY_NOTES".
  
* From the ~/superfoo/src/ directory, you just want the archive to
  contain the *.c and *.h files and the Makefile. 

* The distribution shouldn't include the ~/superfoo/temp/ directory
  at all. 

* Finally, your text editor makes lots of temporary files starting
  with a "~"; these shouldn't be archived.
      
To tell easibox to do this, create a file ~/superfoo/.easiboxrc
with these instructions:

--------------------------------------------------
include("*") # include everything from the top dir
include("doc/*")
exclude("doc/MY_NOTES")
include("src/*.c")
include("src/*.h")
include("src/Makefile")

# remove all ~* files:
exclude("~*")
exclude("doc/~*")
exclude("src/~*")
--------------------------------------------------

To run easibox, invoke it from the shell, and  tell it the version 
number for the new archive (you have to be in the right directory
to do this):

   $ cd ~/superfoo
   $ easibox -v 1.5.2
   
This results in the creation of files superfoo-1.5.2.tar.gz  
and superfoo-1.5.2.zip, in the directory ~/archive/


Using the "easibox" executable
------------------------------

Usage:

   easibox --pack <package> --ver <ver>
   easibox --ver <ver>
      These cause Easibox to create box files for the target package. 
      (Short forms are -p, -v).

   easibox [--pack <package>] --list
      Lists all boxed versions of the target package. (short form for
      --list is -l).

   easibox --usage
      Prints information on how to use Easibox

   easibox --version
      Prints the version of Easibox being used
      
   easibox --info
      Prints information about how Easibox is currently set 
      up


Each of these instructions can take a flag for verbosity:
      
   --verbose
      Flag that causes easibox to say what it's doing (short form is -V)   

;end
