This directory contains all of the files for the Eastman Csound 
Library (hereafter "cslib") currently running at the Eastman
Computer Music Center. The cslib scripts make heavy use of the UNIX m4 macro
preprocessor.

	The principal advantage of using m4 is that the initial user syntax
can be quite simple, enabling new users to use the cslib instruments,
score11 templates, example scores and utilities immediately,
before they have learned the syntactical conventions of
Csound or of a programming language such as C. However, the m4 syntax
can become quite convoluted and ugly -- sometimes almost impenetrable -- when
more complex processing is needed (e.g. macros embedded within macros, or
even simple if/else options). And the modular nature of m4 tends to spawn
a multiplicity of small files spread over several directories. If I had
the time or inclination I'd rewrite the whole thing in C, perhaps with a
single Makefile, but this probably will never happen.

	The cslib subdirectories contain the following files :
  ins :  csound instrument definitions
  Include : files with macro definitions called by instrument and score files
  templates : templates used to make score11 input files
  ex : one or more example scores for each instrument
  funcs : all necessary functions for the library instruments
      and many additional sets of mutisample Csound function definitions
  man : manual pages
  src: source code for "olibscan.c"

	The principal files containing macro definitions are located in
subdirectory Include. These files include:

	m4defs.h -- universal Orchestra Library macros used in preprocessing of
                    both orchestra and score files
In this file, we also have modified the UNIX m4 syntax somewhat. For
example, the changequote " symbol has been changed to left and right
square brackets
	 [    and    ]
and an optional universal comment symbol
	COMMENT
has been included.  Any universal cslib macros (used in preprocessing of both
orchestra and score files) you wish to include should be appended to this file.

	im4defs.h -- converts an orchestra file with cslib  macros into
                     an orchestra file in Csound syntax
	sdefs.m4 -- converts a score11 input file with cslib macros into
                     a file ready for processing by Aleck Brinkman's score11
	idefs.m4 -- contains additional orchestra file macro definitions used
	            by im4defs.h
	inumbers.m4 -- assigns instrument numbers to the cslib instruments

#############################################################
Installation:
1. Move the complete cslib directory to its desired location.
/usr/local/turnkey/cslib is recommended. If you choose any other path, you will
have to change the environment variable definitions suggested in the following
step.

2. The following user environment variables must be defined for these scripts to
work:
   SFDIR : the disk or disk partition and directory where a user's
           soundfiles are written
   CSLIBDIR : the complete path name of this cslib directory

	At Eastman, these environment variables are defined within a file the
files /etc/profile.d/turnkey.sh (bash and sh shells) and
/etc/profile.d/turnkey.csh (tcsh and csh shells).
/etc/profile.d/turnkey.csh should be sourced in  /etc/csh.cshrc.
/etc/profile.d/turnkey.sh will be sourced automatically.

These files include environment variables for SFDIR, CSLIBDIR and
other environment variables and aliases.

-------------- REVISED TO HERE 
 NOTE: THIS LIST IS OUT OF DATE. SOME OF THE ALIASES BELOW HAVE BEEN
REPLACED.
alias lsolibins		ls $CSLIBDIR/ins
alias lsolibscore	ls $CSLIBDIR/templates
alias lsolibscores	lsolibscore
alias lsolibex		ls $CSLIBDIR/ex
alias lsolibfunc	ls $CSLIBDIR/funcs
alias lsolibfuncs	lsolibfunc
alias m4o		m4orch
alias getscore		getolibscore
alias getsc    		getolibscore
alias getex		getolibex
alias getfunc		getolibfunc
alias getdoc		getolibdoc
alias getex		getolibex
alias lsins		lsolibins
alias lssc		lsolibscore
alias lsex		lsolibex
alias lsfunc		lsolibfunc
alias lsdoc		lsolibdoc
alias sflinksfl		sflinksflib

3. Rename your score11 executable file "runscore"

5. Compile the "olibscan.c" program in the olib/src directory, name the
executable file "olibscan," and move it to the /usr/local/bin directory.

The basic installation of the ECMC Csound Library should now be complete.
#############################################################

Top level scripts:

	The following scripts, now in your local bin directory, expand the olib
macros as follows:

      m4orch --runs an orchestra input file through olibscan (checking for
unmatched braces or parentheses), then expands all macros and writes the
output into file "orch.orc" (the default Csound orchestra file name).
		Usage: m4orch orchestra_file_name
m4orch (which can be abbreviated "m4o") also makes a shorthand soft link file
called "orc" to file "orch.orc". To view this file, type
	cat orch.orc   or     cat orc
or use "less" or "more" in place of "cat"

      m4expand -- works just like "m4orch", but brings the expanded standard
output directly to the terminal  for viewing rather than writing it to a file
		Usage: m4expand orchestra_file_name

      score11 -- an input score file is first run through Include/sm4defs.h
within the olib directory for macro preprocessing, then sent to "runscore"
(the actual score11 program)
		Usage: score11 score_file_name
To view the output file "sout" ("score output"), use "cat," "less" or "more"

      m4expandsc -- expands the macros within a score file and send the
output directly to the terminal. As with "m4expand," no output file is written.
		Usage: m4expandsc score_file_name
--------
The complete process of preparing olib orchestra and score files for soundfile
compilation by Csound is as follows:

	1. Prepare an input olib orchestra file. Example:
		SETUP(44100,2205,1)
		MARIMBA
		DRUMS
If desired, run this file through "m4expand" to view the expanded Csound code.

	2. Run this orchestra file through "m4orch" to expand the macros and
write the output into file "orch.orc"

	3. Prepare an input score file for this orchestra to play. To obtain
score templates for each instrument to be used, type
		sctp  instrument_names  > scorefile_name
For the orchestra above, we would obtain score templates for instruments
MARIMBA and DRUMS by typing
		sctp marimba drums > scorefile_name

	4. Edit file "scorefile_name" to specify the desired rhythms, pitches
and other parameter values. The documentation in olib/man describes the usage
of the olib instruments, and the tutorial examples in olib/ex can serve as
initial models.
	If you wish to view your edited score file as score11 will see it, type
		m4expandsc  scorefile_name

	5. Send your score file to score11 for processing:
		score11 scorefile_name
To view the score11 output, type
		cat sout

	6. Compile your Csound soundfile :
		csound [- flags] orch.orc sout

-------------------
Adding or deleting instruments: 

	Whenever an instrument is added to or deleted from the Orch. Lib., the
following files in the Include subdirectory must be edited:
	idefs.m4 -- add a define statement for the instrument at the end of
                    this file
	sdefs.m4 -- add a corresponding define statement for the instrument at
                    then end of this file
	inumbers.m4 -- add a define statement with a Csound instrument number
                       for the instrument at the end of this file
The subdirectory Include  files
   im4defs.h, m4defs.h and sm4defs.h
do NOT have to be edited when instruments are added or deleted:

	If global variables are used (ga, gi, gk) they should be added to the
file "global_vars" in the Include subdirectory, and checked to avoid
duplication of numbers.

	Place a copy of the Csound instrument file code in directory "ins,"
a score template in directory "templates," and one or more sample scores
in directory "ex". To document usage of this instrument, write a manual description
in roff -man format and add it to the olib/man subdirectory.

-------------------------
History:
Many of the olib scripts were originally written by Robert Gross and A.S. in the
early 1980s for use on the first Eastman computer, a PDP11 system.
These scripts were modified by A.S.  for installation on SUN
systems in 10/88, then further modified for installation on the NeXT wrkstation
in March and April, 1993, modified again for use on SGI systems during
the 1990s and for Linux systems and bash shells during 2003 and 2004.

