#title Strasheela Installation ; #author Torsten Anders This page provides installation instructions for Strasheela, a constraint-based computer aided composition environment. To install Strasheela on either Linux, Windows, or MacOS X conduct the following installation steps. **However, please note that Strasheela's feature set on Windows is severely limited.** (Selection constraints cannot be installed, see below. As a result, music theory models like Strasheela's harmony model are not available.) * Install Emacs ** Linux On Linux Emacs is probably already there. ** MacOS The Emacs pre-installed by MacOS X is less suitable, due to its missing graphical interface. A highly recommended alternative is [[http://aquamacs.org/][Aquamacs]]. Alternatively, there are also the [[http://www.apple.com/downloads/macosx/unix_open_source/carbonemacspackage.html][Carbon Emacs Package]] and [[http://www.apple.com/downloads/macosx/unix_open_source/emacsonaqua.html][Emacs on Aqua]]. Note: Emacs on Aqua is only suitable for pre-10.4 Macs (based on Emacs version 20.7 instead of 21.* or 22.*). ** Windows For Windows, follow the instructions in the Mozart Installation Manual on [[http://www.mozart-oz.org/documentation/install/node1.html#label2][Obtaining and Installing GNU Emacs]]. The Emacs installer provided at the Mozart site is already dated, check out the [[http://www.gnu.org/software/emacs/windows/ntemacs.html][GNU Emacs FAQ For Windows]] for a more recent version: [[http://www.gnu.org/software/emacs/windows/faq2.html#getting-emacs][Where can I get precompiled versions?]]. * Install Mozart Simply get a package ready to install from the [[http://www.mozart-oz.org/download][Download Mozart]] page. In case of troubles or for compiling from source consult the Mozart [[http://www.mozart-oz.org/documentation/install/index.html][Installation Manual]]. Note that in November 2011 the binary Mozart 1.4.0 releases was updated (e.g., earlier the compilation of certain Strasheela packages did not work on recent Apple machines with 64 architecture, but that works fine now). Make sure you get a recent installation in case you installed Mozart before. ** Addressing Windows Problems On Windows, it might be a good idea to install the former Mozart version 1.3.1. Selection constraints (see below) cannot be installed on more recent versions on Windows, and Strasheela's harmony model depends on this extension. ; Selection constraints currently cannot be linked (missing symbols) on Windows and 1.3.0. A usual Windows problem is that Mozart does not find Emacs if it has to be invoked with a different name (e.g., =runemacs.exe= as the Win-Emacs-Version recommended above). In that case, set the environment variable =OZEMACS= to the path of your Emacs application (e.g., =C:\Program Files\emacs-22.1\bin\runemacs.exe=) as described [[http://support.microsoft.com/default.aspx?scid=kb;en-us;310519][here]]. ** Test Installation After successfully installing Mozart, you may want to test the installation. At a commandline (a terminal or a DOS box) type =oz=. This starts the Oz Programming Interface (OPI), which runs inside Emacs. The initial window is split in two text buffers (=Oz= and =*Oz Compiler*=). In the upper buffer type the following. ={Browse 'hello'}= Select this text line with the mouse, then go to the Oz menu and select 'Feed Region'. This feeds the selected code to the system (i.e. executes it): it opens a window called Oz Browser which shows 'hello'. Note that the newly created window may be behind the exiting window. * Install Oz Extensions Some Strasheela functionality makes use of Oz extensions which is not part of plain Oz itself. Installing these extensions is recommended, because several Strasheela contributions depend on them. The installation is very easy on Linux and MacOS, but can be problematic on Windows (see below). ** Selection Constraints Selection constraints provide powerful constraints for selecting list elements. Several Strasheela extensions use selection constraints in the background, for example the harmony model (HS) and some Pattern constraints. ; For instance, the following examples in the examples folder rely on [[http://www.mozart-oz.org/mogul/info/duchier/select.html][selection constraints]] (e.g. via Strasheela's harmony model): =04-AutomaticMelodyHarmonsation.oz=, =05-MicrotonalChordProgression.oz=, =07-Harmonised-L-system.oz=. ; - Install [[http://www.mozart-oz.org/mogul/info/duchier/select.html][selection constraints]]. Please note that you need a C++ compiler in order to install these constraints. The GNU C++ compiler is usually already installed on Linux. On MacOS X, install Apple's developer tool Xcode (available either from your MacOS installation CDs, or from [[http://developer.apple.com/tools/xcode/][here]] if this online version is newer). On Windows, you may consider installing this compiler under [[http://www.cygwin.com/][Cygwin]]. You can install the selection constraints by typing (of course, you do not type the leading promt yourself, here =$=). $ ozmake --install --package=http://www.mozart-oz.org/mogul/populate/duchier/select/duchier-select__1.3.0__source__1.8.pkg NB: Unfortunately, it has been found that =ozmake= on Mozart since version 1.3.2 hangs when invoking the GNU compiler on Windows.[4] ** IOzSeF [[http://www.mozart-oz.org/mogul/doc/tack/iozsef/iozsef.html][IOzSeF]] provides search engines which can solve complex constraint problems more efficiently. For example, all IOzSeF solvers support adaptive recomputation -- a technique saving memory (see [[http://books.google.com/books?id=BYXNltNPDGAC&pg=PR1&ots=XEZwT73n-z&dq=Programming+Constraint+Services&sig=vfakyMOLFnvtSWHV3_aUGo94iX8][Programming Constraint Services]]). Strasheela integrates IOzSeF for convenient score search (see [[../doc/api/node8.html][SDistro]]). You can install IOzSeF by typing $ ozmake --install --package=mogul:/tack/TkTreeWidget $ ozmake --install --package=mogul:/tack/iozsef * Install Strasheela ** How to obtain Strasheela? You can either obtain a Strasheela [[http://sourceforge.net/project/showfiles.php?group_id=167225][release]] or a [[http://strasheela.svn.sourceforge.net/viewvc/strasheela/trunk/strasheela.tar.gz?view=tar][development snapshot]] (releases are done at irregular intervals whenenver some development stage was finished). Both are =tar.gz= archive files, which must be unpacked.[5] Alternatively, you can check out the Subversion repository with the following command (this option allows for easy updates later, but requires installing [[http://en.wikipedia.org/wiki/Subversion_(software)][Subversion]]). $ svn co https://strasheela.svn.sourceforge.net/svnroot/strasheela/trunk/strasheela/ strasheela You can then later update your Subversion repository by moving into the =strasheela= top-level directory and typing this. $ svn update ** Installation The steps in this section result only in a bare-bones Strasheela installation which is of limited practical use. Only the installation steps in the sections below this section bring Strasheela to life (e.g. they are essential for hearing Strasheela output). The examples provided with Strasheela assume that all the following installation steps have been conducted. *** UNIX On a UNIX-like system (i.e. Linux or MacOS), you need a C++ compiler besides an Oz installation for compiling Strasheela with all its contributions. On Linux it is likely already installed, on MacOS you should first install Apple's developer tool Xcode, available on the MacOS installation CDs. Then, open a shell, and run the commands given below (naturally, you have to replace the path with the path on your system, and you do not enter the leading promt, here =$=). $ cd /path/to/Strasheela/scripts $ ./install-all.sh BTW: on MacOS, you can enter the path of the directory using drag and drop: grap the Strasheela scripts directory with the mouse and let it go over the terminal window. This script outputs some warnings which you can savely ignore. In case you later somehow changed Strasheela[2] and want to update the installation then run (again in the folder =Strasheela/scripts=[1]) $ ./update-all.sh *** Windows On Windows, you compile and install Strasheela and most of its contributions by opening a DOS command prompt window and typing the following (naturally, you have to replace the path with the path on your system, and you do not enter the leading promt, here =>=). > cd C:\path\to\Strasheela\scripts > install.bat You can enter the path of the directory using drag and drop: grap the Strasheela scripts directory with the mouse and let it go over the terminal window. The batch file =install.bat= installs only those parts of Strasheela which do not require a C++ compiler installed (e.g., Midi file input is not supported in this case). If you have a C++ compiler installed (and Mozart version 1.3.1), you may install all Strasheela contributions by using the batch file =install-all.bat= instead of =install.bat=. In case you later somehow changed Strasheela[2] and want to update the installation then run (again in the folder =Strasheela/scripts=) either > ./update.bat or (with a C++ compiler ) > ./update-all.bat *** Installing individual components An alternative method installs the core of Strasheela (in =Strasheela=) and each of its extensions (in =Strasheela/contributions/*/*=) separately. It uses [[http://www.mozart-oz.org/documentation/mozart-ozmake/index.html][ozmake]], a tool for installing Mozart packages (the above mentioned scripts internally call ozmake as well). Open a shell (or a DOS promt) and move into the directory =Strasheela/contributions/tmp/Path/=. Then type $ ozmake --install On Windows, you may need to enter =ozmake.exe=. Then, move into the *top-level* Strasheela directory and call =ozmake= again. Continue likewise with all Strasheela constributions in =Strasheela/contributions/= (e.g., =Strasheela/contributions/anders/Pattern=). ** IMPORTANT: Edit Oz Initialisation File to Load Strasheela You will usually want to load Strasheela automatically whenever you start Oz. For this purpose, please edit the Oz initialisation file. Strasheela provides the initialisation file template =Strasheela/_ozrc=.[3] A special template =Strasheela/_WindowsOZRC= is provided for Windows which demonstrates how Windows pathes are entered (this template still requires editing according to your system). Also, a special template =Strasheela/_MacOSOZRC= is available with typical MacOS settings. In any case, **you must edit these template files according to your system**. More specifically, you must set the directory (or directories) into which Strasheela should saves files (e.g., MIDI files, Csound files, Lilypond scores). Also, you must the the paths to the applications which Strasheela should call (e.g., Csound, Lilypond, see below). If these paths are not set correctly, then you cannot output any results created with Strasheela. Nevertheless, please leave all paths starting with =x-ozlib://= untouched. These are platform-independent paths, which don't require any changes. Also, you better don't change any code, unless you know what you are doing :) On Linux and MacOS X, you can save your initialisation file as =~/.ozrc= or =~/.oz/ozrc= (for Mac users unfamiliar with UNIX conventions: =~= indicates your home directory, e.g., /Users/yourself). On Windows, it is easiest to set the environment variable =OZRC= to the path of your initialisation file. A description how to manage environment variables on MS Windows XP can be found [[http://support.microsoft.com/default.aspx?scid=kb;en-us;310519][here]]. Note that aftern changing environment variable, you should open a new DOS box / restart Emacs in order to see its effect. #settingPATH Also, you may want to add the Oz applications (e.g., the Strasheela tutorial) to your =PATH= environment variable, so that you can call them directly at the commandline. For example, on MacOS or Linux add the following line to your =~/.profile= file. You may need to replace =1.3.2= with the mozart version you are using (just check how your subdirectory of =~/.oz= is called). export PATH=~/.oz/1.3.2/bin/:$PATH You can test your =PATH= setting by executing the following at the commmand line (first logout/login again or at least open a new terminal). $ StrasheelaTutorial ** Update This section discusses how to update from an old to a new Strasheela version. In case your old Strasheela source folder contains no personal files, you can simply replace your old folder with the new one. If your old folder contains personal files (e.g., personal contributions), then you better first copy them to the new Strasheela version :) You then upgrade simply by running the script =Strasheela/scripts/upgrade-all.sh= (on MacOS or Linux), =Strasheela/scripts/upgrade.bat= (on Windows), or =Strasheela/scripts/upgrade-all.sh= (on Windows with a C++ compiler installed). * IMPORTANT: Install the Software for which Strasheela Supports an Output Format Strasheela exports its scores into various formats, for instance, to produce sheet music or sound output. A number of output formats are already predefined. Most formats are supported by all Strasheela platforms (e.g. Linux, MacOS X, and Windows). Because, output formats are relatively easy to define, further output formats will be added later (or can be defined by the user). - MIDI output makes use of [[http://www.fourmilab.ch/webtools/midicsv/][csvmidi]]. - You need some platform specific MIDI file player for playback. - For sheet music output, Strasheela employs [[http://www.lilypond.org][Lilypond]]. - Lilypond scores are displayed by a PDF or postscript viewer, which is probably already on your system. Otherwise install, for instance, [[http://www.cs.wisc.edu/~ghost/][ghostview]] or [[http://www.adobe.com/products/acrobat/readstep2.html][Acrobat Reader]]. - Further sheet music output formats (including Finale and Sibelius) are supported via the [[http://common-lisp.net/project/fomus/][Fomus]] output (Fomus presently only runs on UNIX). - For sound output, Strasheela outputs the score format of some sound synthesis languages. Currently best supported is the [[http://www.csounds.com][Csound]] score format. - The created sound is played by some sound player. This can be a command line application (e.g. =sndplay= on Linux) or some sound editor (e.g. [[http://audacity.sourceforge.net/][Audacity]]). - Furthermore, Strasheela supports outputting the music representation formats of some other algorithmic composition systems. Presently, [[http://commonmusic.sourceforge.net/doc/cm.html][Common Music]] and [[http://www2.siba.fi/PWGL/][PWGL]] (PWGL presently only runs on MacOS X and Windows) are supported. - Output to [[http://ccrma.stanford.edu/software/clm][CLM]] and [[http://www.audiosynth.com][SuperCollider]] is in development (currently, specific CLM instruments and a special SuperCollider score representation are supported). * Using Strasheela in Realtime with OSC Strasheela provides an extension for music constraint programming in realtime, see the documentation of the [[../contributions/anders/Realtime/doc/node1.html][RT (realtime)]] and the [[../contributions/anders/OSC/doc/node1.html][OSC (Open Sound Control)]] functor for details. OSC is presently only supported on UNIX systems, and has so far been tested only on MacOS version 10.4. The OSC interface calls an X11 application (namely =xterm=). MacOS versions before 10.5 must be configured first to make that possible. Add the following to your =~/.profile= file. export DISPLAY=:0.0 Additionally, make sure that =xterm= is in your path. On MacOS, this is not necessarily the case, and you may want to add something like the following line to your =~/.profile= file. export PATH=/usr/X11R6/bin/:$PATH #forPackageCreators * Notes for Package Creators We highly welcome contributors of packages which simplify the Strasheela installation. For example, RPM files for SUSE Linux can be found [[http://packman.links2linux.de/package/strasheela/][here]] (thank you Toni!). Strasheela tries to simplify the package creation process. The above-mentioned script =install-all= supports all options of [[http://www.mozart-oz.org/documentation/mozart-ozmake/index.html][ozmake]]. For exammple, you can specify an installation directory with the option =--prefix= (default =~/.oz=). The Strasheela functors are installed in =/cache/x-ozlib= (most stuff goes into =/cache/x-ozlib/anders/strasheela/=, but there are additional folders created for user contributions). Mozart must find these installed files. For a 'global' installation, you may give the Mozart installation directory =$OZHOME= as prefix (recommended). Any other directory is possible as well, but then you must tell Mozart to search in this directory by setting the environment variable =$OZLOAD= (or =OZ_SEARCH_LOAD=) to a suitable value. For example, if Mozart should first look into the user's home directory, then into some folder given as prefix to ozmake during the Strasheela installation, and finally into the Mozart installation folder you specify the following. OZLOAD=cache=${HOME}/.oz/cache:cache=$(MYNEWCACHE):cache=$(OZHOME)/cache Per default, Mozart first searches in the home directory, and then in the Mozart installation folder -- which means that the user can shadow files installed in the Mozart installation folder. Strasheela applications (e.g., the interactive =StrasheelaTutorial= and the =OzServer=) are per default installed in =/bin=. This can be changed with the =install-all.sh= option =--bindir=. You may want to add this directory to the PATH environment variable. However, these applications should always be started from the commandline (as feedback is given at =stdout= / =stderr=): if you want to add a menu entry for the =StrasheelaTutorial=, please run them in a terminal nevertheless. BTW: =OzServer= on the other hand usually requires commandline parameters (e.g., a port number) and is therefore less suited for a menu entry. ; this is temporary (until Path fixes are in new Mozart version) In case you are building your package in a [[http://en.wikipedia.org/wiki/Chroot][chroot]] (e.g., to model some specific target system which differs from your running system), then some additional configuration is necessary. The =ozmake= calls by the script =install-all.sh= must find the compiled =*.ozf= files during the installation process. So, for the build process please specify your build root for Mozart via the environment variable =$OZLOAD= (see above), for example, as following (thanks to Toni Graffy for pointing this out). export INSTALLDIR=/usr/local # your installation prefix export BUILDROOT=/var/tmp/strasheela # your build root export PATH=$INSTALLDIR/mozart/bin:$PATH # adding the mozart executables export OZHOME=$INSTALLDIR/mozart # NB: include BUILDROOT in OZLOAD export OZLOAD=cache=${BUILDROOT}$OZHOME/cache:cache=$OZHOME/cache scripts/install-all.sh \ --prefix=${BUILDROOT}${INSTALLDIR}/mozart \ --bindir=${BUILDROOT}${INSTALLDIR}/mozart/bin ; BUILDROOT=/var/tmp/strasheela The Strasheela documentation (scattered across the Strasheela source files..) is not installed automatically. However, it can be extracted from the source with the script =extract-doc.sh= in Strasheela's =scripts= directory. Strasheela provides output to various formats, and therefore relies on other applications. Please add dependencies to Csound, midicsv, Lilypond, a sound file player, a midi file player, and a pdf file viewer. Also, make sure that you edit the provided OZRC template file appropriatedly according to your target system, before you save it as Oz initialisation file. In particular, in this initialisation file set the Strasheela environment variables (using =Init.putStrasheelaEnv=, see the template) to the right values where output files will be stored, where you installed applications like Csound, midicsv, Lilypond, and the player/viewer for sound/midi/pdf files, and possibly their right flags. Make sure that you set the operating system environment variable =$OZRC= to point to the (edited) global initialisation file. If a user later wants to add private settings, she can change the value of =$OZRC= for her account. In case of any questions concerning packaging Strasheela, please to not hestitate to ask via email (e.g., on the Strasheela mailing list). If you report your Strasheela package, then I am most happy to announce it at the Strasheela website (together with acknowledgments of course). Have fun with Strasheela! [[http://www.torsten-anders.de][Torsten Anders]] --------------------- [1] The folder =Strasheela/= denotes the relative path of the Strasheela source on your system. [2] For example, you added your own extensions in the folder =Strasheela/contributions/yourName/yourContribution= together with a corresponding =makefile.oz= in that folder (cf. [[http://www.mozart-oz.org/documentation/mozart-ozmake/index.html][ozmake]], or simply copy and edit the =makefile.oz= of one of the already existing contributions). [3] You can load Strasheela manually as well by manually feeding the (edited) content of =_ozrc= to Oz. [4] See http://www.ps.uni-sb.de/pipermail/mozart-users/2006/015298.html. Nevertheless, the selection constraints have been installed successfully on Windows with earlier Mozart versions (cf. the installation of the [[http://sourcesup.cru.fr/xmg/][XMG - eXtensible MetaGrammar]]). ; http://www.mozart-oz.org/home/doc/changes/node14.html#section.m131.internal [5] In order to reduce the file size of the release archive, the release does not contain the sound files which are part of the documentation of the examples (the sound files blow up the size to an archive 10 times as big!). For running Strasheela these missing sounds don't make any difference, and these files are always available as part of the online documentation of Strasheela. Nevertheless, if you do not have a permanent network connection, you may consider using a [[http://strasheela.svn.sourceforge.net/viewvc/strasheela/trunk/strasheela.tar.gz?view=tar][development snapshot]] or the Subversion repository, because these contain also the sound files of the documentation examples.