|
|
|
Welcome to the Humdrum Toolkit -- software tools for music researchers. This guide describes how to install the Humdrum Toolkit on your Windows system. It also provides some general information about getting started with Humdrum. Included in this guide:
IMPORTANCE NOTICE: PLEASE READ THIS INSTALLATION GUIDE CAREFULLY BEFORE YOU BEGIN. Since this software is not a commercial product, no user support is available. Your comments and suggestions are welcome, although we cannot guarantee that your correspondence will be answered. This Installation Guide and the associated documentation are your principal sources of information.
(1) An IBM-PC or PC-compatible computer (2) At least 50 megabytes of free disk space (4) Windows 95, 98, 2000, XP, or NT 4 operating system
The following installation instructions are for use with UWIN, a UNIX implementation for Windows by AT&T. UWIN is a commercial product, but it is available for free for academic and research purposes.
You can sign the licensing agreement and download the UWIN packages from the
AT&T download page.
You'll want the following packages:
uwin_base
uwin_base_update3_0
uwin_groff
uwin_perl
The first two must be installed in that order. They are all .exe files.When
the installation is complete, you should have a new shortcut on your desktop
named ksh. Double-clicking on this shortcut will start UWIN in
an MS-DOS window. The ksh stands for Kornshell, which is the default
shell for UWIN.
N.B. Users unfamiliar with UNIX should be prepared for a period of learning
and adjustment. It is not recommended that you install the Humdrum Toolkit
until you have developed some facility with the following basic UNIX commands:
cd, chmod, cp, ls, mkdir, less, man, mv, pwd, and
rm.
The next step is to download the Humdrum package for UWIN from the
download page.You should download it into your c:\Program Files\UWIN
directory, or whatever directory you installed UWIN into.
Once you have downloaded the package into your UWIN directory, start up UWIN and type the following commands:
cd /
gzip -d Humdrum.UWIN.2.2beta.tar.gz
tar -xvf Humdrum.UWIN.2.2beta.tar
rm Humdrum.UWIN.2.2beta.tar
This will do the following things:
/usr/local/bin/humdrum/usr/share/man/man1gawk v.3.02 into /usr/bin/home/root directory/home/root/.profile, with useful environmental
variable settingsThe Humdrum distribution in the package includes pre-compiled versions of the Humdrum C-code programs for UWIN.
You'll have to quit UWIN ('exit') and restart it in order for any of these changes to take effect. After that you should find yourself in the /home/root directory. You can test whether Humdrum is working by typing:
context -n 2
1
2
The result should be "1 2".
Metapad is a free text editor that handles the UNIX text file format quite nicely. You can download it from:
Once you have it installed, you'll want to change a few options. Go to Options -> Settings -> Advanced 1. Select:
"Don't auto save extensions," and
"Default file format" -> "UNIX text"
You should then be able to open and edit any Humdrum file. Of course, if you
are already comfortable using vi then you should have no need for
Metapad.
Some users may be interested in gaining a basic understanding how the Humdrum tools work. The following description provides a general outline of the operation of the Humdrum tools.
The Humdrum tools were developed with several criteria in mind. The foremost criterion was that the tools needed to be easy to program. Most of the tools are written in the AWK programming language -- a "fast prototyping language" whose syntax is very similar to that of the C programming language. AWK was developed by Alfred Aho, Brian Kernighan, and Peter Weinberger (hence the name AWK). AWK is especially well suited to musical applications since AWK provides extensive, yet simple-to-use facilities for matching and manipulating strings patterns.
Since AWK is an interpreted language, AWK programs must invoke the AWK interpreter each time they are executed. The command-line syntax for invoking AWK programs is cumbersome. In order to simplify the command-line syntax, special-purpose "shell scripts" have been used to massage the command invocation, to parse the options, and to provide help screens where appropriate.
Most Humdrum commands cause a shell-script to be executed. Each script invokes the AWK interpreter and calls the appropriate AWK program. The shell-scripts were written in the well-known UNIX Kornshell. On Windows 95/98/2000/XP/NT, these scripts are held in files designated by the .ksh extension.
A typical Humdrum command, such as the kern
command, is associated with two files: kern.ksh (or just kern
on UNIX) and kern.awk. The .awk script acts as
both the "source" code and the "executable" code. Both .ksh
and .awk files are ordinary ASCII files, and so can
be examined and (potentially) modified by the user.
Some more complicated Humdrum commands have been partitioned into several subprograms. For example, the Humdrum extract command consists of four separate programs, extract1.awk, extract2.awk, and so on. The associated shell script (extract.ksh) determines which of the extract programs should be invoked, on the basis of the user-selected options.
In order to be able to execute Humdrum commands, several conditions need to
be satisfied. First, either the Kornshell or Bourne shell command
interpreter must be available. Second, the AWK language interpreter must
be available. Third, four pieces of information must be accessible to the shell:
(1) the shell must know where to find the Humdrum commands, (2) it must know
where to find the AWK interpreter, (3) it must know where it can store temporary
files, and (4) it must be told where to direct standard error outputs (on Windows
95/98/2000/XP/NT and DOS this is con. Each of these
four pieces of information need to be stored in shell "environment" variables.
The variables are named PATH, AWK_VER, TMP, and CON.
When you boot your system, these variables need to be assigned properly, otherwise the installed Humdrum tools will fail to work.
The table below lists some common errors associated with faulty or incomplete installation of the Humdrum Toolkit.
Further information is available to help with trouble-shooting.
Error Possible cause = Bad command or file nameKornshell has not been installed or PATH has not been properly set. glob: EXEC errorInstall invoked from Windows without opening a shell. not foundPATH not set correctly or command has not been copied into the Humdrum directory. : -f: not foundAWK_VER shell variable not set. : gawk: not found"nawk" not in current PATH (UNIX). awk: script file ">progname.awk>":HUMDRUM shell variable not set, or PATH no such file or directorynot set correctly. _main: memory allocation failureInput file(s) too big to handle; try breaking the input into smaller segments (using `yank'), and process each segment separately. Assemble back together by using `cat'.
| CREDITS | ||||
|---|---|---|---|---|
| Software Design | Distribution | |||
| David Huron | Center for Computer Assisted Research in the Humanities | |||
| Testing and Debugging | Programming | |||
| Tim Racinsky | Tim Racinsky, Kyle Dawkins, David Huron | |||
| Paul von Hippel | Keith Orpen, Craig Sapp | |||
| Documentation | Financial Assistance | |||
| David Huron | Social Science & Humanities Research Council of Canada | |||
UNIX is a registered trademark of Unix System Laboratories Incorporated. MS-DOS, Windows 95, Windows 98, Windows 2000, Windows XP, and Windows NT are registered trademarks of Microsoft Corporation. UWIN is a registered trademark of AT&T Corporation.