MANUAL HUMDRUM INSTALLATION

This document describes how to manually install the Humdrum Toolkit. There is also a document on installing Humdrum from a package , and a document on installing Humdrum using UWIN. All of these can be accessed from the Humdrum Download page.

Introduction

Welcome to the Humdrum Toolkit -- software tools for music researchers. This guide describes how to install the Humdrum Toolkit on your UNIX, Windows NT, Windows 95/98, Apple MACH-10, DOS, or OS/2 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.

What You Should Have

There are two ways of getting a copy of the Humdrum Toolkit. You can either:

If you have ordered the distribution package you should find the following items:

The Humdrum Toolkit A comprehensive summary of all Humdrum
Reference Manual. commands, options, and representation formats,
as well as other technical information.
A videocassette entitled Contains a 50-minute video-taped demonstra-
Introduction to Humdrum. tion illustrating several features of Humdrum,
including various forms of representation and
some of the software tools.
An envelope containing This envelope contains three 3.5 inch
the Distribution Disks. DOS-format disks.
A physical copy of Provides information about how to install and
this Installation Guide. configure the Humdrum Toolkit on UNIX,
DOS, or OS/2 systems.

The Humdrum tools work under the UNIX operating system. The Humdrum tools will also work under Windows 95/98/NT, DOS or OS/2 environments provided the user has access to UNIX utilities for DOS or OS/2. In all systems, the Humdrum tools must be invoked using the Kornshell or Bourne shell command interpreters. Under LINUX the compatible Bash shell interpreter can be used provided the shell getopts function is available. The Humdrum Tools can also be run under the C-shell (csh) or TC-shell (tsch) with some modifications.

What You Need

UNIX Users:
If you are using UNIX, you need the following:
(1) At least 5 megabytes of free disk space
(2) AWK (1985 revision) -- also known as nawk, gawk
(3) Either the Kornshell or Bourne shell command interpreter
Windows 95/98/NT, Windows 3.X, DOS Users:
If you are using DOS, you need the following:
(1) An IBM-PC or PC-compatible computer
(2) At least 5 megabytes of free disk space
(3) At least 512 kilobytes of internal memory
(4) DOS operating system; version 2.1 or later
(5) UNIX utilities for DOS, including AWK and Kornshell&#167
(6) Roland MPU-401 or compatible MIDI card (optional)
&#167 These utilities are available from Mortice Kern Systems.
Macintosh Classic, Quadra, Power Macs, Powerbook, G3 Users:
If you are using Apple System 7, you need the following:
(1) An Apple computer or compatible clone
(2) At least 5 megabytes of free disk space
(3) At least 512 kilobytes of internal memory
(4) System 7 or later operating system
(5) UNIX utilities for Apple systems, including AWK and Kornshell&#167
&#167 These utilities are available from Tenon Intersystems.

Installation Preliminaries

The Humdrum tools are designed for use with UNIX, Windows 95/98/NT, DOS, or OS/2 environments. However, there are some differences of implementation between these systems that affect the configuration and performance. On UNIX systems, the Humdrum tools pertaining to MIDI input and output are currently unavailable. On Windows NT, Windows 95/98, Windows 3.X, DOS and OS/2 systems the Humdrum Toolkit is able to work only if the software has access to crucial UNIX utilities not provided with the toolkit. In particular, the Humdrum tools will not work under Windows, DOS or OS/2 without access to the AWK pattern-action language and the Kornshell or Bourne shell command interpreters. Several versions of both AWK and ksh are available for Windows 95/98/NT, DOS and OS/2. Both commercial software and freeware are available. Reliable versions of the necessary utilities are available in the

MKS Toolkit manufactured by Mortice Kern Systems, AT&T's UWIN utilities, Microsoft's Interix, and GNU's cygwin, These, or comparable UNIX utilities, must be installed on your Windows 95/98/NT, DOS or OS/2 system before the Humdrum Toolkit can be successfully installed. The Humdrum installation procedure itself makes use of various UNIX utilities.

Presuming that you have installed the "MKS Toolkit," "UWIN", "Interix", or "cygwin", on your Windows 95/98/NT, DOS or OS/2 system, you can continue with the Humdrum installation.

You may install the Humdrum Toolkit by using the automatic installation program -- install -- provided with Humdrum.

Installation on Windows NT, Windows 95/98, Windows 3.X, DOS or OS/2

Before you begin installation, you need to carry out a few preliminary tasks.

Having successfully completed these preliminaries, you are ready to begin installation.

In order to confirm that your Humdrum Toolkit has been successfully installed, type the

humver command. This command will simply echo the version of the toolkit currently installed. The Humdrum tools should be ready for use.

If you intend to make use of the Humdrum MIDI tools, refer to the MIDI Configuration section of this installation guide.

Installation on UNIX

Before you begin installation, you need to carry out a few preliminary tasks. Not all UNIX systems are equipped with a floppy disk drive. It may be necessary to copy the entire contents of the distribution disks in raw form into a temporary directory on your UNIX userid. This may be done via uucp, ftp, tar, procom, kermit, or some other file-transfer utility. (Refer to the UNIX reference manual for your facility.) Copy the contents of all of the distribution disks into a single directory. Note that most of the files are in compressed form.

Having successfully completed these preliminaries, you are ready to begin installation.

In order to confirm that your Humdrum Toolkit has been successfully installed, type the

humver command. This command will simply echo the version of the toolkit currently installed. The Humdrum tools should be ready for use.

Additional Information for UNIX Users

Some transfer programs -- such as ftp -- will preserve carriage returns as a carriage-return/line-feed combination, rather than transforming them into simple line-feeds expected by UNIX. You may encounter problems with control-M characters (^M) inserted at the end of each record for all of your Humdrum files. These characters must be eliminated in order for the Humdrum tools to be operational. If you are an experienced UNIX user, you can use the sed stream-editor to eliminate all control-M characters. Execute the sed script:

sed 's/^V^M//' inputfile > outputfile

for each file -- remembering to rename the output file as the input file. (The string "^V^M" represents control-V followed by control-M.) If you are not an experienced UNIX user, you may want to seek the assistance of a local UNIX expert or consultant.

While it is possible to distribute executable files (.exe) for Windows 95/98/NT, DOS and OS/2 systems, the variety of UNIX platforms precludes distributing executable files for various C programs. Consequently, UNIX users must compile a handful of programs so that they will work on your specific machine. Five programs are involved: assemble, humdrum_, midi, rid, and simil. These programs can be compiled by (1) changing directory to each of the source-code subdirectories for each of these tools (i.e. csource), and (2) executing the make command for each tool. Simply type the command:

make

-- once in each of the five subdirectories. Once you have made an executable file, move it to your main Humdrum directory ($HUMDRUM/bin) -- using the UNIX mv command. This will ensure that these programs reside in your PATH. Finally, use the UNIX

chmod a+x *

command to ensure that all files in the $HUMDRUM/bin directory are executable.

Note that since there is no standard MIDI interface for UNIX systems, the Humdrum MIDI input and output tools cannot be used on UNIX. These tools include encode, record, smf, and tacet. Version 2.0 of the "perform" command can be installed and configured on Linux systems.

Installation on Apple Systems Using MachTEN

Since Apple computer systems do not provide basic UNIX utilities, the Humdrum Toolkit cannot be run on native Apple systems.

However, the Humdrum Toolkit can be installed if users purchase a commercial set of UNIX utilities for Apple Systems.

Tenon Intersystems distributes a suitable product called MachTEN. A review of the MachTEN software (including a comparison with A/UX) was published in Advanced Systems Magazine (formerly Sun World Magazine).

Assuming that MachTEN or similar software has been installed, users should follow the instructions given for UNIX installation of the Humdrum Toolkit.

MIDI Configuration

The Humdrum MIDI tools can be used on Windows 95/98/NT, DOS and OS/2 systems provided the computer is fitted with a Roland MPU-401 or compatible MIDI card. The Humdrum MIDI tools are not currently available under UNIX. Note that the MIDI software tools support only the following interrupts: 2/9, 3, 5, and 7. Interrupts 10, 11, and 12 will not work. If necessary, refer to the manufacturer's hardware manual for details concerning how to change interrupt settings on your MIDI board.

When using Microsoft Windows, the Humdrum MIDI tools are able to access the MIDI card only if Windows is invoked in "standard mode" rather than "386 enhanced mode." From the DOS prompt type:

win /s

and select the MKS Kornshell icon. Once in the Kornshell, be sure that your profile.ksh has been executed. If not, type the command

. /etc/profile.ksh

Quick-Start Tutorial

Having installed the Humdrum Toolkit, you will be eager to see Humdrum in action. Begin by changing directories to the Humdrum demonstration directory. This is located in the subdirectory demo under the directory where you installed Humdrum. In most cases, you can change directories by typing the command:

cd /humdrum/demo

This directory holds a number of tutorial files, and also includes a subdirectory containing a selection of musical scores encoded in various Humdrum formats.

Begin by typing:

demo

This demonstration will first ask you whether you have an appropriate MIDI set-up (see MIDI Configuration). Answer `yes' only if your system runs Windows 95/98/NT, DOS or OS/2 and has a Roland MPU-401-compatible MIDI card with a MIDI synthesizer connected for sound output. (Answering `no' will restrict the demonstration to outputs that don't involve sound.)

The Humdrum demo will provide a menu of ten sample problems. Each problem will pose and answer some analytic question in real-time. (On older machines, some of the sample calculations may take several minutes to execute.) You can stop the demo at any time by typing one or more control-Cs.

If your system is configured for MIDI output, you might also try changing directories to the scores subdirectory and playing one of the scores. A MIDI version of the first movement of Haydn's string quartet Opus 76, No. 3, is encoded in the file haydn76.hmd.

Begin by typing the command:

perform misc/haydn76.hmd

If your MIDI system is properly configured, you should hear a deadpan performance of the work. Try typing various numbers followed by . This will move the performance immediately to the corresponding numbered measure. (If you enter a number greater than the total number of measures, playback will terminate.) Type plus (+) or minus (-) to move ahead or backward one measure at a time. Press the space-bar to interrupt play. Also try typing `<' and `>' to slow-down or speed-up the tempo. (Notice that you don't have to use the shift-key when typing `<', `>' or `+'.) You might also want to explore the search commands. Try typing a slash (/) followed by the word `Development', followed by . To search backward from the current score position, use the question mark (?) rather than the slash -- as in `?Exposition' . To end, type the escape key . If your MIDI instrument continues to sound after the

perform program has ended, type:

tacet

This will turn-off any sounding tones.

You may want to view the accompanying videocassette in order to further familiarize yourself with the capabilities of the Humdrum Toolkit. Ultimately, you will need to begin reading the Humdrum Users' Guide and start working through the tutorial exercises. As with the study of a musical instrument, practice is essential to developing a skill.

How HUMDRUM Works

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/NT, DOS and OS/2 these scripts are held in files designated by the .ksh extension. These scripts can also be executed from the Bourne shell, but they are not compatible with the UNIX C shell.

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.

More computationally intensive programs have been written in the C programming language. These include Humdrum commands such as perform and simil. On Windows 95/98/NT, DOS, the perform.exe, simil.exe, ... files are executable files, compiled from C programs. The Humdrum distribution disks include the complete source code (.c files) for all of these commands.

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 UNIX normally /dev/tty; on Windows 95/98/NT, 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.

Trouble-Shooting Tips

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. .cs I 18
Error Possible cause
=
Bad command or file name Kornshell has not been installed or PATH
has not been properly set.
glob: EXEC error Install invoked from Windows without
opening a shell.
not found PATH not set correctly or command has
not been copied into the Humdrum directory.
: -f: not found AWK_VER shell variable not set.
: awk: not found "awk" not in current PATH (DOS/OS2).
: nawk: not found "nawk" not in current PATH (UNIX).
awk: script file ">progname.awk>": HUMDRUM shell variable not set, or PATH
no such file or directory not set correctly.
_main: memory allocation failure Input 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'.
pc: compiler error ... Humdrum `pc' command conflicts with a
Pascal language compiler named `pc'.
Rename Humdrum `pc.ksh' and `pc.awk' files.
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. PC-DOS and OS/2 are registered trademarks of IBM Corporation. MS-DOS, Windows, Windows 95, Windows 98, and Windows NT are registered trademarks of Microsoft Corporation. Macintosh, Classic, Quadra, Power Mac, Powerbook, and G3 are registered trademarks of Apple Computers Incorporated. MKS and MKS Toolkit are registered trademarks of Mortice Kern Systems Incorporated.
Copyright © 1993, 1999 David Huron