Back to files

README file for Easibox

By Philip Hunt, last altered 29-Feb-2004. For Easibox version 0.6.0

Easibox's home page is

<http://www.zen19725.zen.co.uk/oss/easibox/intro.html>.

You can read about developments of Easibox on my weblog at

<http://www.zen19725.zen.co.uk/weblog/current_easibox.html>.

Easibox has a project page on Freshmeat at

<http://freshmeat.net/projects/easibox/>

My email address is available from <http://www.zen19725.zen.co.uk/>.

This Easibox distribution comes with an HTML User Manual, located in the file:

doc/easibox_manual.html

What is Easibox?

Easibox is a utility for building distribution archives (that is, tar files, zip files and other archive files) -- these are referred to as "box 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 the 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.3 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