Email UNIX Tools Help Fri May 5 07:12:20 EDT 2006 This file describes how to use the UNIX tools in your own personal account. You should be running UNIX on your computer to do this. Getting Started in a UNIX System ------- ------- -- - ---- ------ First make a `home directory' for the contest you wish to enter. You can enter many contests, and should have a separate home directory for each. In this home dir- ectory place a file named `HPCM_ADDRESS' that contains the email address of the contest (more specifically, of the autojudge for the contest). Thus if the contest email address is `fee', execute in the contest home directory: echo 'fee' >HPCM_ADDRESS From now on work in this contest home directory. Note that it is a bad idea to use your UNIX home direc- tory `~' as a contest home directory. Each contest you enter should have its own unique home directory. If you are not running Linux, check whether or not your /bin/sh shell is a version of the `bash' shell, and if not, read the `Special Instructions for non-Bash Shells' section at the end of this document, and import the bash shell if necessary. Next, send email to the contest email address with the subject `get help' and an empty message body. The reply will contain many files (including the file you are now reading). Copy this reply into the file named help.email in your contest home directory. Manually extract the file help/sh/hpcm_extract from this help.email file into your contest home directory as the hpcm_extract file. The files in help.email are separated by lines that match the regular expression `^---<>', that is, that begin with the characters `---<>'. Using this fact you can fairly easily extract the correct hpcm_extract file with an editor. Next execute the following UNIX commands in your contest home directory: chmod 700 hpcm_extract ./hpcm_extract < help.email chmod 700 help/sh/* This should extract all the files into the `help' subdi- rectory and make the files in `help/sh' executable. The hpcm_extract file, when it executes, will log its actions to the standard output. At this point you can remove the files help.email and hpcm_extract from the contest home directory. There will be another copy of hpcm_extract in the `help/sh' subdirectory. Next add the `help/sh' subdirectory to your PATH so you can execute the programs in this directory. Assuming your contest home directory is named `~/hpcm/practice', and assuming you use the `csh' shell, add set path=(~/hpcm/practice/help/sh $path) in your `~/.cshrc' file. If instead you use the Bourne shell, add PATH=$HOME/hpcm/practice/help/sh:$PATH in your `~/.profile' file. After editing the relevant file, log out and log back in again, and then check for errors by typing the UNIX command: hpcm_get -doc | more This should output the documentation for the hpcm_get program. You can output the documentation of the other programs in `help/sh' by executing them with just the `-doc' option, if you wish, but this should not be nec- essary. Lastly, to automatically extract files from email replies to requests generated by hpcm_get, add a copy of `~/hpcm/help/sh/procmailrc' to your `~/.procmailrc' file, and edit the copy according to the instructions in what you copied. This is all you need to do if your UNIX system uses the procmail program to deliver mail. If your system delivers mail using a different mailer, you may have to put the following line in your `~/.forward' file: "| exec /usr/bin/procmail" to cause your `~/.procmailrc' file to be used (include the "'s in the `~/.forward' file). Here `/usr/bin/ procmail' should be identical to the output of the UNIX command `which procmail'. If you cannot arrange for automatic extraction of files gotten by hpcm_get, you will have to manually input each reply containing files to the `hpcm_extract' UNIX command. E.g., copy a reply into a file `foo' and execute the command: hpcm_extract < foo within the contest home directory or one of its descen- dants. To add more contests later, you merely create a contest home directory for each contest, and a HPCM_ADDRESS file within that directory. You do NOT have to repeat any of the other actions described above. But you may find it helpful to symbolically link the `help' sub- directory of the new contest directory to the `help' subdirectory of old existing contest directory, so `hpcm_help' (see below) works. Programs like hpcm_extract, hpcm_get, hpcm_submit, and hpcm_help work by searching the current directory and its ancestors for a readable HPCM_ADDRESS file, and using the first directory they find as the contest home directory. Thus if hpcm_submit is executed in the `problems/ppp' subdirectory of the contest home direc- tory, it will identify `../..' as the contest home di- rectory. If you want more up to date versions of the files ob- tained by `get help' or `get demos', use the command hpcm_get -force help demos to repeat these messages. Then read the output from hpcm_extract's processing of the reply. This output will tell you which files have changed and therefore been updated. You then delete your local versions of these changed files and execute `hpcm_get -force help demos' one more time to get the updated versions of these files. If you get an updated version of any file in the `help/sh' subdirectory, re-execute: chmod 700 help/sh/* Commands that Do NOT Work -------- ---- -- --- ---- The following commands do NOT work for an email contest. print, print2, Use your favorite file print fprint, printer program instead. scoreboard See the scoreboard URL instead. help Instead you can use `hpcm_help'. Testing the Demo in a UNIX System ------- --- ---- -- - ---- ------ The UNIX command `hpcm_get', executed in the contest home directory, will get all the demonstration files into the `demos' subdirectory of the contest home di- rectory. If you go to the `/demos/count' subdirectory, you will find a demonstration problem complete with solutions in all the supported programming languages. The README file in this directory will tell you how to install any of these solutions and practice running it and submitting it. Working Problems in a UNIX System ------- -------- -- - ---- ------ Read the `solving' help file. Aside from direct use of print commands or the scoreboard command, and aside from having to use hpcm_help instead of `help', all the commands should work. Special Instructions for non-Bash Shells ------- ------------ --- -------- ------ Read this only if your UNIX /bin/sh is NOT the GNU bash shell. You will be running various HPCM programs written in the UNIX Bourne shell (sh) language. Some versions of sh do not support the `-r' option to the `read' command, the `-e' option to the `test' command, or the use of back- slash as a non-interpreted output character by the `echo' command. If `/bin/sh' has any of these problems, you need to make the GNU bash shell available in your PATH under the name `bash'. All versions of LINUX should have bash as a matter of course. If your system does not have bash, get it from: www.gnu.org/software/bash/bash.html File: email_unix_tools Author: Bob Walton Date: See top of file. The authors have placed this file in the public domain; they make no warranty and accept no liability for this file. RCS Info (may not be true date or author): $Author: hc3 $ $Date: 2006/05/05 11:21:31 $ $RCSfile: email_unix_tools,v $ $Revision: 1.19 $