This repository contains the "classical" Humdrum Toolkit. To use along with the Humdrum Extras package, it is better to install the Humdrum Toolkit from:
https://github.com/humdrum-tools/humdrum-tools
The Humdrum Toolkit is a set of unix command-line programs which process data files, including musical scores, in the Humdrum file format. The Humdrum Toolkit can be used on unix-based computer systems such as linux and Apple OS X. To use in MS Windows, install a unix terminal emulator. A comprehensive package for linux tools in Windows can be downloaded from http://www.cygwin.com. The simplest method is to download all cygwin packages when installing, but that will require a long installation duration (such as overnight for some reason).
If you are lucky or a unix expert (and have git and gcc installed),
then you can run the following commands to download and install the
Humdrum Toolkit as a single-user installation as well as download
sample musical data and test all of the tools (some commands below
may need to be prefixed with sudo):
cd /usr/local
git clone https://github.com/humdrum-tools/humdrum
cd humdrum
make bin
make install
make data
make regressionOtherwise, follow the more detailed instructions below.
Further documentation about the Humdrum Toolkit as well as installing and using it can be found at http://www.humdrum.org,
To download the Humdrum Toolkit package, go to the following page on the GitHub website: https://github.com/humdrum-tools/humdrum and then click on the "Download ZIP" button on the right-hand side of the page. Or from a linux terminal, download with the command:
wget https://github.com/humdrum-tools/humdrum/archive/master.zipHowever, the preferable method of downloading the Humdrum Toolkit
is with the git command. This will allow you
to easily update the software and sample data occasionally by typing
make update && make bin in the installation directory. If
you have git installed on your computer (see below for git installation
notes), download the Humdrum Toolkit repository with the command:
cd /usr/local # recommended installation location
git config --global core.autocrlf false # cygwin users should do this
git clone https://github.com/humdrum-tools/humdrum
# or if there are permission writing errors, try:
sudo git clone https://github.com/humdrum-tools/humdrumTo use alongside the Humdrum Extras package, instead download the humdrum-tools repository by typing:
cd /usr/local
git config --global core.autocrlf false # cygwin users should do this
git clone --recursive https://github.com/humdrum-tools/humdrum-toolsIf you want to download sample Humdrum file musical scores but not the Humdrum Extras package, you can do this command in the main Humdrum Toolkit directory after downloading (if you are using git to install):
cd humdrum
make dataOr to use the humdrum-data repository outside of the humdrum directory,such as in your home directory if the Humdrum Toolkit is installed in /usr/local/humdrum, type the following command within the target installation directory:
cd
git clone --recursive https://github.com/humdrum-tools/humdrum-dataGit is a
version control program which is the main interface to online
repositories on GitHub. To check if the git program is
installed on your computer, type:
which gitIf the terminal replies with a line such as /usr/local/bin/git,
then git is installed and you can run the above installation commands.
If the which command replies with an error that git cannot
be found, you need to install git. How to do this will depend on
your operating system.
In linux, the installation command for git is usually one of these two possibilities:
sudo yum install git
sudo apt-get install gitFor cygwin on MS Windows computers, you
should have included git when installing packages when you
first installed cygwin. Re-run the installation program and include
git in the package installation list.
For Apple OS X, the easiest method is to download git from this link. More advanced Mac users can use Homebrew to install git:
brew install gitCygwin/Windows users should run the command
git config --global core.autocrlf falsebefore using git to download a repository. This command will prevent git from converting unix-style newlines to the windows style (which would mess up the AWK scripts).
To compile the C programs and create the bin directory for the
Humdrum Toolkit, type make bin inside of the humdrum directory:
cd humdrum
make binAlso, typing just make will give a list of things you can
do with the make command, listed in the order that they can be done.
Note that to use the make command or gcc for compiling
the C programs, these must already be installed. Check to see if
gcc is installed by typing this command (gcc installation includes
make command as well):
which gcc
which make
```
The terminal should reply with something like ```/usr/bin/gcc```
and ```/usr/bin/make```. If gcc is not installed, then you will
have to figure out how to install it on your computer first.
Linux/Unix computers usually have it pre-installed with the operating
system; if not, then typing ```sudo yum install gcc``` or ```sudo
apt-get install gcc``` will typically install it. Apple OS X does
not include it by default, so you will have to install it. If you
are using OS X Mavericks or later, then type ```xcode-select
--install``` to install the Xcode command line tools. The ```make```
command will be installed at the same time that ```gcc``` is
installed. Cygwin users would have to re-run the installation
program and include the compile tools if gcc was not initially
installed with cygwin.
Installing
==========
To use the Humdrum Toolkit commands within any directory, you must add the
humdrum/bin directory to the PATH environmental variable. This can be
done temporarily for the current session by typing:
```bash
cd humdrum # or cd /usr/local/humdrum or wherever it is installed
PATH=`pwd`/bin:$PATH
```
For a persistent installation of the Humdrum Toolkit whenever you
open a new terminal, you can type the following command to include
the humdrum/bin directory in the PATH command search path variable
within the file ~/.profile.
```bash
cd humdrum
make install
```
This installation method is suitable for single-user installations.
Super-users can instead install for all users on a computer system by
running this command instead:
```bash
sudo echo "export PATH=/usr/local/humdrum/bin:$PATH" >> /etc/profile"
```
if /usr/local/humdrum is the directory where the Humdrum Toolkit was
downloaded to.
Verifying
=========
Once the Humdrum Toolkit has been installed, check that the humdrum/bin
directory has been added correctly to the PATH environmental variable by typing:
```bash
echo $PATH | tr : '\n' | grep humdrum | head -n 1
```
which should display the humdrum/bin directory for the Humdrum Toolkit.
If the above command produces no result, see the previous section about adding
humdrum/bin to the PATH variable.
The Humdrum Toolkit makefile automates the above step and prints some
extra guidance on the next steps you can do:
```bash
cd humdrum
make checkpath
```
After the PATH variable has been modified to include the Humdurm Toolkit bin
directory, You can further check that the Humdrum Toolkit commands are
visible by running the ```which``` command:
```bash
which mint
```
This should reply with the location of the mint command,
such as ```/usr/local/humdrum/bin/mint```.
Further testing can be done to ensure that the Humdrum Toolkit
commands are performing as expected on your particular computer
system. Within the main Humdrum Toolkit directory (such as
/usr/local/humdrum), type ```make regression```. This will run
all of the Humdrum Toolkit programs with various inputs and compare
to expected outputs. The start of the test sequence should look
something like this:
```bash
(cd toolkit-source/regression-tests; make -s verbose)
TEST 01 for accent: OK
TEST 01 for assemble: OK
TEST 01 for barks: OK
TEST 01 for cbr: OK
TEST 01 for census: OK
TEST 01 for cents: OK
TEST 01 for cleave: OK
TEST 01 for cocho: OK
TEST 01 for context: OK
TEST 01 for correl: OK
TEST 01 for deg: OK
TEST 01 for degree: OK
TEST 01 for ditto: OK
```
Updating
========
To periodically update the humdrum package if you downloaded
using <em>git</em>, type these commands in the installation directory
for humdrum (<em>make</em> commands may need to be prefixed with `sudo`):
```bash
cd `which mint | sed 's/bin\/mint$//'` # or go to wherever installed
make update
make bin
```