Intro
Install
One minute crash course

Intro

For a more thorough introduction to epto, after installation do:

man epto

Epto for sh: Industrial strength shell programming with zero or near zero fuzz for the busy programmer/sysadmin.

Epto is a small open source library and framework for industrial strength shell script programming with sh. It features convienient error handling, tracing, option handling, and process level transaction safety (sort of), plus more. It requires Perl version 5 or above.

It is targeted at Linux, Solaris and Cygwin systems, but is probably easy to port to other variants of Unix.

Epto is released under the MIT license.

This is a Beta release.
Send errors, patches and suggestions, as well as "booooo" or "hear hear", to:

Jonas Mölsä, jbm@nada.kth.se

Epto chooses convenience over efficency. If you have big needs for efficency, don't use epto. Don't even use sh. Use (for example) Python or Perl instead.

Also, Epto chooses Bourne shell compability over rich Bash functionality. Bourne shell is guaranteed to be present on every unix/linux computer, and I need a tool that will be of use to me even in places where I can't use Bash. Some features of Bash has been implemented in epto, like arrays/vectors (same basic semantics but different syntax) and printf.

The code you write when you fill in the eptogen produced templates is yours. You can copyright it however you want. You can not claim copyright in such a way that other peoples right to use their eptogen produced templates are affected (by for example claiming copyright to the actual names of the fill-in templates/functions).

The easiest way to copyright your code differently from epto is to source your code in the different fill-in functions in the eptogen produced templates. If this is not acceptable, drop me a mail and I will try to think of a way to handle it. If you have any suggestions, let me know.

Install

To install:

        ./configure
        make
        make install

And (strongly recommended):

make test

The test takes c:a 70 seconds on a 2.4 GHz Pentium, but 11-12 minutes on a 133 MHz Pentim. If you have an old computer, be prepared to wait. If you are running under cygwin, be prepared to wait more.

If the test failed, be sure to wipe out any leftover directories in /tmp:
rm -rf /tmp/epto*
Do this as a non-root user, so that you only can remove your own files. (Don't want to crash someone elses use of epto!)

Default prefix (base directory) is /usr/local

If you want to change that, do: ./configure --prefix=/some/other/dir (If you chnge it, make sure PATH contains the bin-directory, and MANPATH the man-directory under /some/other/dir) One good choice, for a personal installation only, is: --prefix=$HOME/local

For other configure options, see the program comment in configure.

Epto has been tested on RedHat 8.0, cygwin 1.5.9-1 and 1.5.10-1, and Solaris 9. Users have also run the tests successfully on Mac OS 10.2.8 "Jaguar"

One minute crash course in bare minimum epto programming

1. Generate the script template

To generate an epto script

eptogen scriptname.sh

To generate a extremely minimal epto script for learning, experimentation etc:

eptogen -m scriptname.sh

Fill in the program comment (The man-like documentation in the beginning) unless you generated the script with -m, in which case you do not have any program comment.

2. Take care of options

2a. Prepare for parsing

If your script takes three options, -x -t and -f, where -f takes a file argument, replace (in function "init_variables"):

set_option_syntax ""
with:

set_option_syntax "[-xt] [-f file]"

This will take care of parsing the command line for these options, and set opt_x, opt_t and opt_f to non-null values if the occur on the command line. There will also be an opt_f_arg that contains the argument to -f.

2b. Handle parsed options

Handle the options in function "handle_options_and_command_arguments":

[ $opt_t ] && print_total=true # or whatever [ $opt_x ] && { blah; blah; blah; } # or whatever [ $opt_f ] && logfile=$opt_f_arg # or whatever

The standard epto options [-ADNUvV] [-F file] [-T timeout] are handled automatically.

3. Error, commit, exit and rollback

If you know, already after options handling, what you want to happen on exit, error, or commit, say so in the function "setup_initial_commit_rollback_and_exit_handling". Otherwise, say so at the appropriate place in main.

Three functions (for your use) handles deletion and rollback of files and dirs:

rollback_file_onerror file_or_dir ... # restore files/dirs on error exit

delete_file_atexit file_or_dir... # delete files/dirs at exit (eg tmpfiles)

delete_file_onerror file_or_dir ... # delete files/dirs on error exit

If you send the script process an unstoppable signal, none of the above functions will get a chance, but otherwise, they kick in when they should.

If the script fails, it will delete temporary files, restore changed files and delete partially constructed files.

Options will have been parsed and handled with a minmum of fuzz or work on your part.

What's next?

The next natural step is eptointro(1).

After that, read the example programs in the examples directory, and look at:

epto(1), eptogen(1), eptopgl(1), eptofunc(1), eptorun(1), eptotx(1)

Also, for lighter (with less functionality), standalone scripts, look at:

eptolitepgl(1)

Contents